NOUSERMACRO(simrisc line)

includefile(../../release.yo)

htmlbodyopt(text)(#27408B)
htmlbodyopt(bgcolor)(#FFFAF0)
whenhtml(mailto(Frank B. Brokken: f.b.brokken@rug.nl))

DEFINEMACRO(lsoption)(3)(\
    bf(--ARG1)=tt(ARG3) (bf(-ARG2))\
)
DEFINEMACRO(laoption)(2)(\
    bf(--ARG1)=tt(ARG2)\
)
DEFINEMACRO(loption)(1)(\
    bf(--ARG1)\
)
DEFINEMACRO(soption)(1)(\
    bf(-ARG1)\
)


DEFINEMACRO(sr)(0)(bf(simrisc))
DEFINEMACRO(Sr)(0)(bf(Simrisc))
DEFINEMACRO(Cpp)(0)(bf(C++))
DEFINEMACRO(prot)(0)(tt((prot)))

IFDEF(man)(
DELETEMACRO(tt)
DEFINEMACRO(tt)(1)(em(ARG1))
)()

def(itt)(1)(it()tt(ARG1))

COMMENT( man-request, section, date, distribution file, general name)
manpage(simrisc)(1)(_CurYrs_)(simrisc._CurVers_)
        (simrisc breast cancer simulation program)

manpagename(simrisc)(This program performs simulations in the context of
breast cancer)

COMMENT( all other: add after () )
manpagesynopsis()
        sr() [options] tt(analyses)

The tt(analyses) argument is the name of the file specifying the analyses to
perform.  See section bf(ANALYSES) for details.

manpagedescription()

    Sr() was originally designed around 2010 by Marcel Greuter at the
University Medical Center Groningen, and thereafter modified in 2015 by Chris
de Jonge.

manpageoptions()
         
    Short options are provided between parentheses, immediately following
their long option equivalents. Several parameters specify the path-names of
files produced by sr(). If a path-name starts with a tilde character (~) then
the tilde is replaced by the user's home directory. An initial + is replaced
by the program's base directory (see option tt(base)). When an analysis uses 
multiple iterations then `$' characters in filename specifications are
replaced by the analysis' interation index.

All single-letter options referring to filesystem entries (directories,
filenames) are capitalized, all other single-letter options are lowercase.

    itemization(
    it() lsoption(base)(B)(basedir)nl()
       the base directory where the output files will be written. By default
        tt(./). If tt(basedir) doesn't exist it is created by the program. If
        the directory cannot be created and exception is thrown, terminating
        the program. The tt(basedir) specifications may specify relative or 
        absolute directory locations;

    it() lsoption(config)(C)(path)nl()
       the location of the configuration file. By default
        tt(~/.config/simrisc') is used.

    it() lsoption(data)(D)(path)nl()
       path name of the file to contain the data of the cases generated by the
        simulation (default: '<base>/data-$.txt'). If a data file should not
        be written specify tt(!) (mnemonic: the logical not operator, i.e.,
        tt(--data !)). See section bf(OUTPUT) for a description of the
        generated data;

    it() lsoption(death-age)(a)(age)nl() 
       run one simulation using a specific natural death-age.  This option
        also requires the specification of tt(tumor-age), and is mutually
        exclusive with the tt(case) option;

    it() loption(help) (soption(h))nl()
       shows help information and terminates;

    it() lsoption(last-case)(l)(nCases)nl()
       perform simulations until tt(nCases) cases have been analyzed and only
        write the data for the final case to the data file. The tt(rounds) and
        tt(sensitivity) files contain the summarized results of all tt(nCases)
        analyzed cases;

    it() loption(one-analysis) (soption(o))nl()
      the program's arguments specify the parameters of a single analysis,
        rather than the name of an analyses-specification file. The program's
        arguments are optional and are used to alter the parameter
        values as defined in the config file or to define tt(label)
        specifications. See section bf(ANALYSES) for details;

    it() lsoption(parameters)(P)(path)nl()
       path name of the file showing the actually used parameter
        specifications. By default no parameter file is written;

    it() lsoption(rounds)(R)(path)nl()
       path name of the file to containing the summary info of the simulation
        rounds (default: '<base>/rounds-$.txt'). If a rounds file should not
        be written specify tt(!) (i.e., tt(--rounds !)). See section
        bf(OUTPUT) for a description of the generated summary info;

    it() lsoption(sensitivity)(S)(path)nl()
       path name of the file to containing the summary info of the
        simulation's sensitivity data (default: '<base>/sensitivity.txt'). If
        a sensitivity file should not be written specify tt(!) (i.e.,
        tt(--sensitivity !)). See section bf(OUTPUT) for a description of the
        produced sensitivity summary; 


COMMENT(
    it() lsoption(totalrisk)(T)(path)nl()
       path name of the file to containing the cumulative total risk values
        (default: '<base>/totalrisk.txt'). By default the cumulative total
        risk values are not written to file;
END)

    it() lsoption(tumor-age)(t)(age)nl() 
       run one simulation using a specific tumor self-detect age.  This option
        also requires the specification of tt(death-age), and is mutually
        exclusive with the tt(case) option;

    it() loption(verbose) (soption(V))nl()
       provides additional information while running;

    it() loption(version) (soption(v))nl()
       shows sr()'s version information and terminates;
    )
           
manpagesection(ANALYSES)

Unless the tt(one-analysis) option is used the program's first and only
required argument is the name of a file providing the details of the analyses
to perform. Those files are called analysis files and must be standard ascii
text files. I.e., they only contain 7-bit ascii printable and white-space
characters. The identifiers used in analysis files and in configuration files
are interpreted case sensitively.

Parameter specifications starting with uppercase letters (like tt(Analysis:)
and tt(Scenario:)) specify (sub)sections and contain no additional
specifications. Specifications starting with lowercase letters (like
tt(ageGroup:)) are followed by actual parameter values. For a complete
overview refer to the bf(simriscparams)(7) man-page.

Analysis files may define multiple analyses. Each analysis specification
em(must) begin with a line containing 
        verb(
    Analysis:
        ) 
    At each tt(Analysis:) specification the program's initial configuration is
reset: the default option values are used unless redefined by explicitly
provided command-line options. Explicitly provided command-line options
cannot be altered by specifications in tt(Analysis:) sections and remain
active while sr() is running.

Following tt(Analysis:) lines the characteristics of the analysis are
specified.  These specifications may, in the following order:
    itemization(
    it() define em(label:) lines (label: lines, when used, must immediately
        follow tt(Analysis:) lines). The text following tt(label:) lines is
        written at the top of the output files;
    it() alter default sr() options;
    it() redefine parameter specifications of configuration files;
    )

All specifications in tt(Analysis:) sections are optional.  An tt(Analysis:)
specification merely containing the line tt(Analysis:) defines an analysis
using the explicitly specified command-line options or the default program
options and using the parameter specifications provided in the configuration
file.

Empty lines, trailing white-space, and all characters on lines starting at the
hash-mark (tt(#)) are ignored and may be used anywhere in analysis files.

Lines not conforming to the above description result in error messages,
causing sr() to end.

When parameters of configuration file sections (cf. bf(simriscparams)(7)) are
omitted from tt(Analysis:) sections then the parameters as specified in the
configuration file are used.

When program options are specified their long option names must be used. E.g.:
    verb(
    base:       /tmp/
    last-case:  20
    )

Command-line options always overrule options specified in analysis files.

Multiple analysis sections should not use identically named output files, as
the output files are (re)written for each separate analysis.

Analysis sections are commonly used to alter the default specifications of the
configuration file. E.g., the default number of iterations equals 1. By
specifying
    verb(
    iterations: 3
    )
    the analysis performs 3 iterations.

Parameters are either read from the configuration file or they are redefined
in tt(Analysis:) sections. E.g., in de provided configuration file screening
rounds use two-year intervals between the ages of 50 and 74. To use screening
rounds using 5-year intervals, between ages 50 and 65, then an
tt(Analysis:) specification could be, e.g.,
    verb(
Screening:
    round:     50  Mammo MRI
    round:     55  Mammo MRI
    round:     60  Mammo MRI
    round:     65  Mammo MRI
    )

When the tt(--one-analysis) option is used parameters may be altered by
providing comma-separated parameter specifications as program command-line
arguments. E.g., to perform one analysis, writing the data file to
tt(/tmp/data), simulating 1000 cases, and using 20 as seed for the random
number generator the command
    verb(
    simrisc -D /tmp/data -o Scenario:, cases: 1000, seed: 20
    )
    can be used. Note that when using the tt(one-analysis) option parameter
section names must precede parameter specifications. E.g., since the
parameters tt(cases) and tt(seed) are defined in the `Scenario' section
(cf. bf(simriscparams)(7)) they must be preceded by the tt(Scenario:)
specification.

Subsequent tt(Analysis:) specifications in analysis files use the program
options as specified on the command line (or, if not specified, the default
program options) and uses the configuration file's parameter
specifications. So when an tt(Analysis:) specification modifies parameters,
then subsequent tt(Analysis:) sections start from the unmodified option and
parameter specifications.

When tt(Analysis:) sections specify tt(base:) directory locations then file
specifications using an initial `tt(+)' character to represent the base
directory (like tt(--data +/data.txt)) use the base directory specified at
the tt(Analysis:)'s tt(base:) specification.


manpagesection(OUTPUT)

The first lines of the generated files contain time stamps showing the date
and time when the files were written. Here is an example of the time stamp,
following the RFC 2822 format:
    verb(
    Wed, 27 Jan 2021 09:42:49 +0100
    ) 
    If tt(label:) lines are used then the time stamp is followed by the label
specifications, which is then followed by an empty line. After this header the
file's specific data are shown.

The data in all files (except for the file listing the actually used
parameters (option tt(--parameters) (tt(P)))) are written using the standard
comma-separated format (cf. RFC 4180). The initial lines contain table
headings and column labels documenting the meanings of the various
columns. Likewise there is a final line ending the tables.

bf(Data of simulated cases)

For each simulated case the values of the following variables are written to
file (one line of comma-separated values per simulated case):
    itemization(
    itt(case:) the (0-based) case-index;
    itt(cause of death:) either tt(Natural) or tt(Tumor);
    itt(death age:) the case's age of death;
    itt(natural death age:) the case's natural age of death (if no tumor
        occurs); 
    itt(death status:) a numeric index specifying how and at what stage the
        case died:nl()
            1: natural death in the pre-screening phase,nl()
            2: natural death in the screening phase,nl()
            3: natural death in the post-screening phase,nl()
            4: tumor caused death in the pre-screening phase,nl()
            5: tumor caused death in the screening phase,nl()
            6: tumor caused death in the post-screening phase;
    itt(tumor present:) tt(Yes) if the simulation resulted in a tumor, tt(No)
        if no tumor occurred;
    itt(tumor detected:) tt(Yes) if the tumor was detected, tt(No) if not;
    itt(interval tumor:) tt(Yes) if the tumor was an interval tumor, tt(No) if
        not; 
    itt(tumor diameter:) the tumor's diameter in mm when it was detected. 0.00
        is shown if no tumor occurred. In the exceptional case where the
        simulation produced a tumor whose diameter exceeded 1000 mm the value
        1001 is shown.
    itt(tumor doubling days:) the time (in days) it takes for the tumor to
        double its size;
    itt(tumor preclinical period:) the age at which the tumor is potentially
        detectible by Mammographic screening;
    itt(tumor onset age:) the age at which the tumor first occurred;
    itt(tumor self-detect age:) the age at which the tumor was
        self-detected. This age is the result of the simulation, and may
        exceed the case's actual death age (if so, the case's data report that
        no tumor is present);
    itt(tumor death age:) the age at which the tumor caused or would have
        caused he case's death. The simulation process uses ages ranging from
        0 through 100. If the age at which the tumor causes the case's death
        exceeds 100, then 100.00 is reported;
    itt(costs:) the case's screening and (if appliccable) treatment costs;
    itt(self-detection indicator): 1 if the tumor was self-detected, 0 if not
        (also if there's no tumor);
    itt(detection round): 0-based round index at which the tumor was detected
        (or 1) if the tumor was self-detected, 0 if not (also if there's no
        tumor).
    )

includefile(include/configfiles.yo)

manpageseealso()

     bf(simriscparams)(7)

COMMENT(
        manpagediagnostics()
    
    manpagebugs()
        too early for that...
EDN)

includefile(include/trailer.yo)
