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 cancer simulation program)

manpagename(simrisc)(This program performs simulations in the context of
breast and lung 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.

includefile(include/changes.yo)

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(cancer)(c)(type)nl()
       The simulation type (tt(type)) can be specified as tt(breast) to
        perform breast cancer simulations. Breast cancer simulations are
        performed by default when the tt(--cancer) option is not
        specified. Alternatively, to perform lung cancer simulations tt(type)
        must be specified as either tt(male) or tt(female) to perform
        simulations for, respectively, male or female cases.

       Be advised that the default configuration file specifies tt(Screening
        Mammo) rounds, which must either be changed to tt(CT) in locally used
        configuration files or in tt(Analysis:) sections (see section
        bf(ANALYSES) below);

    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;

COMMENT(
    it() loption(err) (soption(e))nl()
       before version 14.05.00 the Beir7 risk vector was computed using an
        incorrect algorithm. The error was fixed in simrisc 14.05.00.  When it
        is required to use the erroneous algorithm, e.g., to compare the
        results of simulations with previously obtained results, option tt(-e)
        must be specified. However, option tt(-e) should not be used for real
        simulations;
END)

    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(log) tt(begin end fname [set])nl()
       log process actions of cases tt(begin) thru tt(end) on the file
        tt(fname). This includes generated random values. Random values
        generated in several contexts can be suppressed. Specify+nl()
        * bf(C) to suppress generated case-specific uniformly distributed
        random values+nl()
        * bf(L) to suppress generated log-normal distributed
        random values+nl()
        * bf(U) to suppress generated uniformly distributed
        random values not associated with cases+nl()
        * bf(V) to suppress generated uniformly distributed
        random values associated with VSD computations.

       Note that tt(begin end) defines an inclusive range. To log the process
        for a single case (e.g. case 100) ignoring the L, U, and V generated
        values specify tt(--log "100 100 fname LUV"). Also note that only
        a em(single) argument ispassed to tt(--log). Therefore its argument
        must be surrounded by quotes;

    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. If the
        tt(--base (-B)) option was specified then tt(path) is written in the
        base directory if tt(path) does not contain a slash (/) (use
        tt(./path) to write the parameters file in the current directory if
        tt(--base) was specified);

    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(spread)(s)(path)nl()
       path name of the file containing the configured and actually used
        parameter values when tt(spread: true) is specified (default:
        '<base>/spread-$.txt'). If this file should not be written specify
        tt(!) (mnemonic: the logical not operator, i.e., tt(--spread !)). If
        a parameter doesn't use spreading then the 'using' part is
        omitted. See section bf(OUTPUT) for a sample of its content;

    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;

    it() loption(tnm) (soption(T))nl()
       The data file contains a column labeled tt(TNM) showing the (0-based)
        tt(TNM) categories for cases having developed tumors (see also the
        bf(simiscparams)(7) man-page). By default this column remains empty
        for cases not having developed tumors, which may be inconvenient when
        processing the data (e.g., to perform statistical analyses). When
        specifying the tt(--tnm) option cases not having developed tumors
        receive TNM column entries tt(-1,0) to avoid missing data;

    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. These files are called em(analysis files). These files must be a
standard ascii text files. I.e., they can only contain 7-bit ascii printable
and white-space characters. Identifiers used in analysis files and in
configuration files are interpreted case sensitively.

    Configuration specifications starting with uppercase letters (like
tt(Scenario:) and tt(Costs:)) specify (sub)sections and don't contain
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.

    Options specified on the command-line cannot be specified in
tt(Analysis:) sections and remain active while sr() is running. The default
option values are reset at each separate tt(Analysis:) unless an option has
been specified on the command-line, in which case those option values are used
throughout the sr() run.

    Following tt(Analysis:) lines the characteristics of the analysis are
specified which can be specified for each tt(Analysis:) specification, in the
following order:
    itemization(
    it() a em(label:) line: tt(label:) lines, when used, must immediately
        follow tt(Analysis:) lines. The text following tt(label:) is
        written at the top of the output files;
    it() option lines: specifying sr() options (not specified on the command
        line) which are then used for that analysis. When program options are
        specified their long option names must be used. E.g.:
    verb(
    base:       /tmp/
    last-case:  20
    )

    it() parameter specifications: modify (some) parameter specifications
        defined in configuration files. When parameters of configuration file
        sections (cf. bf(simriscparams)(7)) are not specified then the
        parameters specified in the configuration file are used.
    )

    All specifications in tt(Analysis:) sections are optional.  An
tt(Analysis:) section 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, initial and 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.

Filename specified in tt(Analysis:) sections may start with a tilde character
(~) which is replaced by the user's home directory, or they may start with an
initial + character, which is replaced by the program's base directory (see
option tt(base)). When an analysis performs multiple iterations then `$'
characters in filename specifications are replaced by the analysis' interation
index.

Multiple analysis sections should not specify 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(
    Scenario:
        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 are modified 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.

When an tt(Analysis:) specification modifies parameters, then subsequent
tt(Analysis:) sections start from the unmodified option and parameter
specifications.

Here is an example of an analysis file specifying two analyses:
        verb(
Analysis:
    base:   1
    cancer: male
    parameters: +params.txt

    Scenario:
        cases: 10

    Screening:
        round:     50  CT
        round:     55  CT

Analysis:
    base:   2
    config: ~/src/simrisc/stdconfig/lung
    parameters: +params.txt
    cancer: breast

    Scenario:
        cases: 20
        spread: true

    Screening:
        round:     50  Mammo MRI
        round:     55  Mammo MRI
        round:     60  Mammo MRI
        round:     65  Mammo MRI
        )

manpagesection(OUTPUT)

The first lines of the generated files contain time stamps showing the date
and time when the files were written and the used tt(SimRisc) version. Here is
an example, following the RFC 2822 format for the timestamp:
    verb(
    Mon, 14 Nov 2022 15:30:26 +0100 (SimRisc V. 15.00.00)
    )
    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 (data-X.txt files))

Below the date and label lines the legend of the death-status (see below at
item tt(death status)) is shown. Each iteration generates a separate
tt(data-X.txt) file, where tt(X) indicates the iteration index (starting at
value 0).


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 (1-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, no tumor, before the 1st screening round,nl()
    2: natural death, undetected tumor, before the 1st screening round,nl()
    3: self-detected tumor before the 1st screening round,nl()
    4: natural death, no tumor, between screening rounds,nl()
    5: natural death, undetected tumor, between screening rounds,nl()
    6: self-detected tumor between screening rounds,nl()
    7: screening-detected tumor,nl()
    8: natural death, no tumor, after the last screening round,nl()
    9: natural death, undetected tumor, after the last screening round,nl()
   10: self-detected tumor after the last screening round;
    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 screening. -1.00 is shown if there's no pre-clinial
        period; 
    itt(tumor onset age:) the age at which the tumor first occurred. -1.00 is
        shown if  no tumor developed;
    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). -1.00 is shown if there's no self-detect age;
    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. 0.00 is shown if no tumor
        developed; 
    itt(costs screening:) the case's screening and (if appliccable) treatment
        costs; 
    itt(costs biop:) the costs of a performed biopsy;
    itt(detected self): 1 if the tumor was self-detected, 0 if not
        (also if there's no tumor);
    itt(detected round): round number at which a tumor was detected, using
        the following values (assuming tt(N) screening rounds were
        specified):nl()
        verb(   0: no tumor was detected;
  -1: tumor was self-detected before the 1st screening round;
   1: tumor was detected during/after the 1st screening round
      (and before the 2nd round);
  *1: tumor was self-detected after the 1st screening round
      (which was not attended);
   ...
   3: tumor was detected during/after the 3rd screening round;
  *3: tumor was self-detected after the 3rd screening round
      (which was not attended);
   ...
   N: tumor was detected during/after the Nth screening round;
  *N: tumor was self-detected after the Nth screening round
      (which was not attended).
        )
    itt(screening rounds:) this column show which screening rounds
        were attended by the simulated cases, and if so whether false
        negative or false positive diagnoses were made. The following digits
        are used:
       itemization(
       itt(0:) the case did not attend this screening round;
       itt(1:) the case did attend this screening round.
       it() 2: the case did attend this screening round, resulting in a false
            negative diagnosis;
       it() 3: the case did attend this screening round, resulting in a false
        positive diagnosis.
       )

       There are as many digits as screening rounds. The leftmost digit refers
        to the first screening round, the rightmost digit to the last
        screening round. E.g., using 12 screening rounds the following
        indicators could be obtained:
       verb(
    001101111000
       )
       Using screening round indices (which are also used to refer to rounds
        in the tt(rounds-$.txt) files), this case did not attent screening
        rounds 1, 2, 5, 10, 11, and 12.
    itt(TNM): The TNM status/stage of the tumor (see also the
        bf(simiscparams)(7) man-page). It specifies the row/column index of
        table of probabilities of positive lymph nodes and metastatis, given
        the size of the tumor (table S3, cf. Goldstraw et al., Journal of
        thoracic oncology, 2016, 11(1): 39-51; Yuan et al., Scientific
        Reports, 2016, 6(1): 1-9).
    )

bf(Actually used spread-values)

When tt(spread: true) is specified then by default the actually used and
orgiginal parameter values are written to the file tt(spread-$.txt), where
tt($) is replaced by the loop's iteration index. Here is a sample from the
content of such a file, showing the values of the tt(Tumor: DoublingTime:)
agegroups parameters:
    verb(
    Tumor:
      DoublingTime
        ageGroup:    1 - 50    configured: 4.38, using: 3.41972
        ageGroup:   50 - 70    configured: 5.06, using: 4.83591
        ageGroup:   70 -  *    configured: 5.24, using: 5.30492
     )

bf(The rounds-X.txt files)

Each iteration generates a separate tt(rounds-X.txt) file, where tt(X)
indicates the iteration index (starting at value 0).

The rounds-files summarize the results of the simulations for each separate
screening round. It contains at least eight columns plus a column for each
used modality:
    quote(
    round: the round number (starting at 1);nl()
    false pos: the number of false positive screening results;nl()
    false neg: the number of false negative screening results;nl()
    number of tumors: the number of detected real tumors;nl()
    number of interval: the number of self-detected (interval) tumors;nl()
    number of trueInt: the number of self-detected (interval) real tumors;nl()
    screening costs: the total screening costs;nl()
    screening biop: the total costs of performed biopsies;nl()
    number of [modality]: the number of times each modality was used.
    )


includefile(include/configfiles.yo)

manpageseealso()

     bf(simriscparams)(7)

COMMENT(
        manpagediagnostics()

EDN)

manpagebugs()

Versions before version 15.03.00 should not be used for lung cancer
simulations. 

includefile(include/trailer.yo)


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)
