simrisc(1)

simrisc breast cancer simulation program
(simrisc.13.02.01.tar.gz)

2020

NAME

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

Short options are provided between parentheses, immediately following their long option equivalents. Several parameters specify the path-names of files produced by simrisc. 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 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.

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

• --config=path (-C)
  path name of the configuration file (by default '~/.config/simrisc');

• --data=path (-D)
  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 ! (mnemonic: the logical not operator, i.e., --data !). See section OUTPUT for a description of the generated data;

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

• --config=path (-C)
  the location of the configuration file. By default ~/.config/simrisc' is used.

• --help (-h)
  shows help information and terminates;

• --id-base=nr (-i)
  when specifying 0 the standard RandomPool is used. Otherwise nr specifies the initial base-ID used for the initialization of the IDPool. This value is converted to a number that's unique for specific random number generators (associated with, respectively, sensitivity, false-positives, and attendance values). Note that using this option prevents specification of id-base in analyses: sections, as command-line options cannot be overruled by those sections. By default the value 1 is used.

• --nCases=nCases (-n)
  perform simulations until nCases cases have been analyzed and only write the data for the final case to the data file. The rounds and sensitivity files contain the summarized results of all nCases analyzed cases;

• --one-analysis (-o)
  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 label specifications. See section ANALYSES for details;

• --parameters=path (-P)
  path name of the file showing the actually used parameter specifications. By default no parameter file is written;

• --rounds=path (-R)
  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 ! (i.e., --rounds !). See section OUTPUT for a description of the generated summary info;

• --sensitivity=path (-S)
  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 ! (i.e., --sensitivity !). See section OUTPUT for a description of the produced sensitivity summary;

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

• --verbose (-V)
  provides additional information while running;

• --version (-v)
  shows simrisc's version information and terminates;

ANALYSES

Unless the 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.

Analyses files may define multiple analyses. Each analysis specification must begin with a line containing

    analysis:
        

• redefine the default specifications of the configuration file;
• alter the default program options (but note that explicitly provided program options cannot be altered by analyses-specifications);
• define label lines;
• be absent (so two consecutive analysis: lines specify two analyses);
• be empty lines;
• contain comment (starting at `#' characters)

Analysis: sections not altering configuration parameters use the parameters that are specified in the configuration file.

Lines not containing option-, label- or parameter-specifications are also ignored, but should (to avoid confusion) probably be avoided.

Options are specified using their long option names as keys. E.g.:

    base:   /tmp/
    nCases: 20
    

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 found in the configuration file. E.g., the default the default number of iterations equals 1. By specifying

    iterations: 3
    

Configuration parameters are either read from the configuration file or they are redefined in analysis: sections. E.g., by default screening rounds are defined for two-year intervals between the ages of 50 and 74. If screening rounds are requested for 5-year intervals between ages 50 and 65 then an analysis: specification could be, e.g.,

    screeningRound:     50  Mammo MRI
    screeningRound:     55  Mammo MRI
    screeningRound:     60  Mammo MRI
    screeningRound:     65  Mammo MRI
    

In addition to options and parameter specifications analysis: sections may contain (multiple) label: lines. The text following label: is written at the top of the output files of those sections.

When using the --one-analysis option parameters may be altered by providing comma-separated parameters specifications as program command-line arguments. E.g., to perform one analysis, writing the data file to /tmp/data, simulating 1000 cases, and 20 for seeding the random number generator the command

simrisc -o -D /tmp/data nWomen: 1000, seed: 20
    

Each analysis: specification starts with the configuration file's parameter specifications. When an analysis: specification modifies parameters, then subsequent analysis: sections again start with the configuration files parameter specifications.

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:

    Thu, 16 Jul 2020 15:30:45 +0200
    

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):

• woman: the (0-based) case-index;
• cause of death: either Natural or Tumor;
• death age: the case's death age;
• tumor present: Yes if the simulation resulted in a tumor, No if no tumor occurred;
• tumor detected: Yes if the tumor was detected, No if not;
• interval tumor: Yes if the tumor was an interval tumor, No if not;
• 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 listed.
• 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);
• tumor death age: the age at which the tumor caused the 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;
• tumor doubling time: the time (in days) it takes for the tumor to double its size;
• tumor onset age: the age at which the tumor first occurred;
• tumor preclinical period: the age at which the tumor is potentially detectible by Mammographic screening;

FILES

• ~/.config/simrisc: the default location of the program's configuration file;

SEE ALSO

simriscparams(7)

BUGS

too early for that...

COPYRIGHT

AUTHOR