Provided by: simrisc_14.05.00-3_amd64 
NAME
simrisc - This program performs simulations in the context of breast cancer
SYNOPSIS
simrisc [options] analyses
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.
Changes introduced in version 14.04.00
o Parameters affected by spread: true
Parameters that may vary are specified using triplets: value, spread and distribution. In all
cases the spread values and distribution names are optional: they can both be omitted or both must
be specified. If these parameters are not specified then their value parameter won’t vary if
spread: true is specified;
o The Mammo, Tomo, and MRI modalities are provided with std.dev and distribution parameters for
their Dose, M, Beta, Specificity, and Sensitivity parameters;
o When spread: true is specified the actually used and original parameter values are listed in a
file, by default spread-$.txt, where $ is replaced by the loop iteration index. Use the option -s
to specify a non-default filename (cf. simrisc(1));
o Age ranges no longer have trailing colons;
o The Case-specific data matrix defines an extra (18th) column, showing the results of the screening
rounds for each simulated case;
o The order of the beir7 beta and eta parameters is reversed: eta is specified first, followed by
beta. The spread and distribution parameters following beta apply to beta, and not to eta, which
is a fixed value.
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.
o --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;
o --config=path (-C)
the location of the configuration file. By default ~/.config/simrisc’ is used.
o --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;
o --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;
o --err (-e)
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 -e must be specified.
However, option -e should not be used for real simulations;
o --help (-h)
shows help information and terminates;
o --last-case=nCases (-l)
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;
o --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;
o --parameters=path (-P)
path name of the file showing the actually used parameter specifications. By default no parameter
file is written;
o --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;
o --spread=path (-s)
path name of the file to contain the actually used and original parameter values when spread: true
is specified (default: ’<base>/spread-$.txt’). If this file should not be written specify !
(mnemonic: the logical not operator, i.e., --spread !). See section OUTPUT for a sample of its
content;
o --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;
o --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;
o --verbose (-V)
provides additional information while running;
o --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. 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 Analysis: and Scenario:) specify
(sub)sections and contain no additional specifications. Specifications starting with lowercase letters
(like ageGroup:) are followed by actual parameter values. For a complete overview refer to the
simriscparams(7) man-page.
Analysis files may define multiple analyses. Each analysis specification must begin with a line
containing
Analysis:
At each 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 Analysis: sections and remain active while simrisc is
running.
Following Analysis: lines the characteristics of the analysis are specified. These specifications may,
in the following order:
o define label: lines (label: lines, when used, must immediately follow Analysis: lines). The text
following label: lines is written at the top of the output files;
o alter default simrisc options;
o redefine parameter specifications of configuration files;
All specifications in Analysis: sections are optional. An Analysis: specification merely containing the
line 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 (#) are ignored
and may be used anywhere in analysis files.
Lines not conforming to the above description result in error messages, causing simrisc to end.
When parameters of configuration file sections (cf. simriscparams(7)) are omitted from 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.:
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
iterations: 3
the analysis performs 3 iterations.
Parameters are either read from the configuration file or they are redefined in 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 Analysis: specification
could be, e.g.,
Screening:
round: 50 Mammo MRI
round: 55 Mammo MRI
round: 60 Mammo MRI
round: 65 Mammo MRI
When the --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
/tmp/data, simulating 1000 cases, and using 20 as seed for the random number generator the command
simrisc -D /tmp/data -o Scenario:, cases: 1000, seed: 20
can be used. Note that when using the one-analysis option parameter section names must precede parameter
specifications. E.g., since the parameters cases and seed are defined in the `Scenario’ section (cf.
simriscparams(7)) they must be preceded by the Scenario: specification.
Subsequent 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 Analysis: specification modifies parameters, then subsequent Analysis:
sections start from the unmodified option and parameter specifications.
When Analysis: sections specify base: directory locations then file specifications using an initial `+’
character to represent the base directory (like --data +/data.txt) use the base directory specified at
the Analysis:’s base: specification.
OUTPUT
The first lines of the generated files contain time stamps showing the date and time when the files were
written and the used SimRisc version. Here is an example, following the RFC 2822 format for the
timestamp:
Thu, 08 Apr 2021 21:43:09 +0200 (SimRisc V. 14.04.00)
If 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 --parameters
(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.
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):
o case: the (0-based) case-index;
o cause of death: either Natural or Tumor;
o death age: the case’s age of death;
o natural death age: the case’s natural age of death (if no tumor occurs);
o death status: a numeric index specifying how and at what stage the case died:
1: natural death in the pre-screening phase,
2: natural death in the screening phase,
3: natural death in the post-screening phase,
4: tumor caused death in the pre-screening phase,
5: tumor caused death in the screening phase,
6: tumor caused death in the post-screening phase;
o tumor present: Yes if the simulation resulted in a tumor, No if no tumor occurred;
o tumor detected: Yes if the tumor was detected, No if not;
o interval tumor: Yes if the tumor was an interval tumor, No if not;
o 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.
o tumor doubling days: the time (in days) it takes for the tumor to double its size;
o tumor preclinical period: the age at which the tumor is potentially detectible by Mammographic
screening;
o tumor onset age: the age at which the tumor first occurred;
o 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);
o 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;
o costs: the case’s screening and (if appliccable) treatment costs;
o self-detection indicator: 1 if the tumor was self-detected, 0 if not (also if there’s no tumor);
o 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).
o screening rounds: this column contains 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:
o 0: the case did not attend this screening round;
o 1: the case did attend this screening round;
o 2: the case did attend this screening round, resulting in a false negative diagnosis;
o 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:
0011311110000
Using screening round indices (which are also used to refer to rounds in the rounds-$.txt files),
this case did not attent screening rounds 0, 1, 9, 10, 11 and 12, and at 4 a false positive
diagnosis was obtained.
Actually used spread-values
When spread: true is specified then by default the actually used and orgiginal parameter values are
written to the file spread-$.txt, where $ is replaced by the loop’s iteration index. Here is a sample
from the content of such a file, showing the values of modality Mammo’s Beta parameters:
Beta:
nr: 1 using -4.37906 (configured: -4.38)
nr: 2 using 0.490436 (configured: 0.49)
nr: 3 using -1.33749 (configured: -1.34)
nr: 4 using -7.22025 (configured: -7.18)
FILES
o ~/.config/simrisc: the default location of the program’s configuration file;
o the simrisc distribution archive contains the default configuration file as
simrisc-VERSION/stdconfig/simrisc, where VERSION is replaced by simrisc’s actual release version;
o when installing simrisc using Linux distribution archives (e.g., .deb files) the default
configuration file is commonly available as /usr/shared/doc/simrisc/simrisc.gz
SEE ALSO
simriscparams(7)
COPYRIGHT
This is free software, distributed under the terms of the GNU General Public License (GPL).
AUTHOR
Frank B. Brokken (f.b.brokken@rug.nl),
simrisc.14.05.00 2020-2021 simrisc(1)