.TH "simrisc" "1" "2020\-2021" "simrisc\&.14\&.02\&.00" "simrisc breast cancer simulation program"
.PP
.SH "NAME"
simrisc \- This program performs simulations in the context of
breast cancer
.PP
.SH "SYNOPSIS"
\fBsimrisc\fP [options] \fIanalyses\fP
.PP
The \fIanalyses\fP argument is the name of the file specifying the analyses to
perform\&. See section \fBANALYSES\fP for details\&.
.PP
.SH "DESCRIPTION"
.PP
\fBSimrisc\fP was originally designed around 2010 by Marcel Greuter at the
University Medical Center Groningen, and thereafter modified in 2015 by Chris
de Jonge\&.
.PP
.SH "OPTIONS"
.PP
Short options are provided between parentheses, immediately following
their long option equivalents\&. Several parameters specify the path\-names of
files produced by \fBsimrisc\fP\&. If a path\-name starts with a tilde character (~) then
the tilde is replaced by the user\(cq\&s home directory\&. An initial + is replaced
by the program\(cq\&s base directory (see option \fIbase\fP)\&. When an analysis uses
multiple iterations then `$\(cq\& characters in filename specifications are
replaced by the analysis\(cq\& interation index\&.
.PP
All single\-letter options referring to filesystem entries (directories,
filenames) are capitalized, all other single\-letter options are lowercase\&.
.PP
.IP o
\fB\-\-base\fP=\fIbasedir\fP (\fB\-B\fP)
.br
the base directory where the output files will be written\&. By default
\fI\&./\fP\&. If \fIbasedir\fP doesn\(cq\&t exist it is created by the program\&. If
the directory cannot be created and exception is thrown, terminating
the program\&. The \fIbasedir\fP specifications may specify relative or
absolute directory locations;
.IP
.IP o
\fB\-\-config\fP=\fIpath\fP (\fB\-C\fP)
.br
the location of the configuration file\&. By default
\fI~/\&.config/simrisc\(cq\&\fP is used\&.
.IP
.IP o
\fB\-\-data\fP=\fIpath\fP (\fB\-D\fP)
.br
path name of the file to contain the data of the cases generated by the
simulation (default: \(cq\&/data\-$\&.txt\(cq\&)\&. If a data file should not
be written specify \fI!\fP (mnemonic: the logical not operator, i\&.e\&.,
\fI\-\-data !\fP)\&. See section \fBOUTPUT\fP for a description of the
generated data;
.IP
.IP o
\fB\-\-death\-age\fP=\fIage\fP (\fB\-a\fP)
.br
run one simulation using a specific natural death\-age\&. This option
also requires the specification of \fItumor\-age\fP, and is mutually
exclusive with the \fIcase\fP option;
.IP
.IP o
\fB\-\-help\fP (\fB\-h\fP)
.br
shows help information and terminates;
.IP
.IP o
\fB\-\-last\-case\fP=\fInCases\fP (\fB\-l\fP)
.br
perform simulations until \fInCases\fP cases have been analyzed and only
write the data for the final case to the data file\&. The \fIrounds\fP and
\fIsensitivity\fP files contain the summarized results of all \fInCases\fP
analyzed cases;
.IP
.IP o
\fB\-\-one\-analysis\fP (\fB\-o\fP)
.br
the program\(cq\&s arguments specify the parameters of a single analysis,
rather than the name of an analyses\-specification file\&. The program\(cq\&s
arguments are optional and are used to alter the parameter
values as defined in the config file or to define \fIlabel\fP
specifications\&. See section \fBANALYSES\fP for details;
.IP
.IP o
\fB\-\-parameters\fP=\fIpath\fP (\fB\-P\fP)
.br
path name of the file showing the actually used parameter
specifications\&. By default no parameter file is written;
.IP
.IP o
\fB\-\-rounds\fP=\fIpath\fP (\fB\-R\fP)
.br
path name of the file to containing the summary info of the simulation
rounds (default: \(cq\&/rounds\-$\&.txt\(cq\&)\&. If a rounds file should not
be written specify \fI!\fP (i\&.e\&., \fI\-\-rounds !\fP)\&. See section
\fBOUTPUT\fP for a description of the generated summary info;
.IP
.IP o
\fB\-\-sensitivity\fP=\fIpath\fP (\fB\-S\fP)
.br
path name of the file to containing the summary info of the
simulation\(cq\&s sensitivity data (default: \(cq\&/sensitivity\&.txt\(cq\&)\&. If
a sensitivity file should not be written specify \fI!\fP (i\&.e\&.,
\fI\-\-sensitivity !\fP)\&. See section \fBOUTPUT\fP for a description of the
produced sensitivity summary;
.IP
.IP o
\fB\-\-tumor\-age\fP=\fIage\fP (\fB\-t\fP)
.br
run one simulation using a specific tumor self\-detect age\&. This option
also requires the specification of \fIdeath\-age\fP, and is mutually
exclusive with the \fIcase\fP option;
.IP
.IP o
\fB\-\-verbose\fP (\fB\-V\fP)
.br
provides additional information while running;
.IP
.IP o
\fB\-\-version\fP (\fB\-v\fP)
.br
shows \fBsimrisc\fP\(cq\&s version information and terminates;
.PP
.SH "ANALYSES"
.PP
Unless the \fIone\-analysis\fP option is used the program\(cq\&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\&.
.PP
Parameter specifications starting with uppercase letters (like \fIAnalysis:\fP
and \fIScenario:\fP) specify (sub)sections and contain no additional
specifications\&. Specifications starting with lowercase letters (like
\fIageGroup:\fP) are followed by actual parameter values\&. For a complete
overview refer to the \fBsimriscparams\fP(7) man\-page\&.
.PP
Analysis files may define multiple analyses\&. Each analysis specification
\fImust\fP begin with a line containing
.nf
Analysis:
.fi
At each \fIAnalysis:\fP specification the program\(cq\&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 \fIAnalysis:\fP sections and remain
active while \fBsimrisc\fP is running\&.
.PP
Following \fIAnalysis:\fP lines the characteristics of the analysis are
specified\&. These specifications may, in the following order:
.IP o
define \fIlabel:\fP lines (label: lines, when used, must immediately
follow \fIAnalysis:\fP lines)\&. The text following \fIlabel:\fP lines is
written at the top of the output files;
.IP o
alter default \fBsimrisc\fP options;
.IP o
redefine parameter specifications of configuration files;
.PP
All specifications in \fIAnalysis:\fP sections are optional\&. An \fIAnalysis:\fP
specification merely containing the line \fIAnalysis:\fP 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\&.
.PP
Empty lines, trailing white\-space, and all characters on lines starting at the
hash\-mark (\fI#\fP) are ignored and may be used anywhere in analysis files\&.
.PP
Lines not conforming to the above description result in error messages,
causing \fBsimrisc\fP to end\&.
.PP
When parameters of configuration file sections (cf\&. \fBsimriscparams\fP(7)) are
omitted from \fIAnalysis:\fP sections then the parameters as specified in the
configuration file are used\&.
.PP
When program options are specified their long option names must be used\&. E\&.g\&.:
.nf
base: /tmp/
last\-case: 20
.fi
.PP
Command\-line options always overrule options specified in analysis files\&.
.PP
Multiple analysis sections should not use identically named output files, as
the output files are (re)written for each separate analysis\&.
.PP
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
.nf
iterations: 3
.fi
the analysis performs 3 iterations\&.
.PP
Parameters are either read from the configuration file or they are redefined
in \fIAnalysis:\fP 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
\fIAnalysis:\fP specification could be, e\&.g\&.,
.nf
Screening:
round: 50 Mammo MRI
round: 55 Mammo MRI
round: 60 Mammo MRI
round: 65 Mammo MRI
.fi
.PP
When the \fI\-\-one\-analysis\fP 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
\fI/tmp/data\fP, simulating 1000 cases, and using 20 as seed for the random
number generator the command
.nf
simrisc \-D /tmp/data \-o Scenario:, cases: 1000, seed: 20
.fi
can be used\&. Note that when using the \fIone\-analysis\fP option parameter
section names must precede parameter specifications\&. E\&.g\&., since the
parameters \fIcases\fP and \fIseed\fP are defined in the `Scenario\(cq\& section
(cf\&. \fBsimriscparams\fP(7)) they must be preceded by the \fIScenario:\fP
specification\&.
.PP
Subsequent \fIAnalysis:\fP 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\(cq\&s parameter
specifications\&. So when an \fIAnalysis:\fP specification modifies parameters,
then subsequent \fIAnalysis:\fP sections start from the unmodified option and
parameter specifications\&.
.PP
When \fIAnalysis:\fP sections specify \fIbase:\fP directory locations then file
specifications using an initial `\fI+\fP\(cq\& character to represent the base
directory (like \fI\-\-data +/data\&.txt\fP) use the base directory specified at
the \fIAnalysis:\fP\(cq\&s \fIbase:\fP specification\&.
.PP
.SH "OUTPUT"
.PP
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:
.nf
Wed, 27 Jan 2021 09:42:49 +0100
.fi
If \fIlabel:\fP 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\(cq\&s specific data are shown\&.
.PP
The data in all files (except for the file listing the actually used
parameters (option \fI\-\-parameters\fP (\fIP\fP))) 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\&.
.PP
\fBData of simulated cases\fP
.PP
For each simulated case the values of the following variables are written to
file (one line of comma\-separated values per simulated case):
.IP o
\fIcase:\fP the (0\-based) case\-index;
.IP o
\fIcause of death:\fP either \fINatural\fP or \fITumor\fP;
.IP o
\fIdeath age:\fP the case\(cq\&s age of death;
.IP o
\fInatural death age:\fP the case\(cq\&s natural age of death (if no tumor
occurs);
.IP o
\fIdeath status:\fP a numeric index specifying how and at what stage the
case died:
.br
1: natural death in the pre\-screening phase,
.br
2: natural death in the screening phase,
.br
3: natural death in the post\-screening phase,
.br
4: tumor caused death in the pre\-screening phase,
.br
5: tumor caused death in the screening phase,
.br
6: tumor caused death in the post\-screening phase;
.IP o
\fItumor present:\fP \fIYes\fP if the simulation resulted in a tumor, \fINo\fP
if no tumor occurred;
.IP o
\fItumor detected:\fP \fIYes\fP if the tumor was detected, \fINo\fP if not;
.IP o
\fIinterval tumor:\fP \fIYes\fP if the tumor was an interval tumor, \fINo\fP if
not;
.IP o
\fItumor diameter:\fP the tumor\(cq\&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\&.
.IP o
\fItumor doubling days:\fP the time (in days) it takes for the tumor to
double its size;
.IP o
\fItumor preclinical period:\fP the age at which the tumor is potentially
detectible by Mammographic screening;
.IP o
\fItumor onset age:\fP the age at which the tumor first occurred;
.IP o
\fItumor self\-detect age:\fP the age at which the tumor was
self\-detected\&. This age is the result of the simulation, and may
exceed the case\(cq\&s actual death age (if so, the case\(cq\&s data report that
no tumor is present);
.IP o
\fItumor death age:\fP the age at which the tumor caused or would have
caused he case\(cq\&s death\&. The simulation process uses ages ranging from
0 through 100\&. If the age at which the tumor causes the case\(cq\&s death
exceeds 100, then 100\&.00 is reported;
.IP o
\fIcosts:\fP the case\(cq\&s screening and (if appliccable) treatment costs;
.IP o
\fIself\-detection indicator\fP: 1 if the tumor was self\-detected, 0 if not
(also if there\(cq\&s no tumor);
.IP o
\fIdetection round\fP: 0\-based round index at which the tumor was detected
(or 1) if the tumor was self\-detected, 0 if not (also if there\(cq\&s no
tumor)\&.
.PP
.SH "FILES"
.PP
.IP o
\fI~/\&.config/simrisc\fP: the default location of the program\(cq\&s
configuration file;
.IP o
the \fBsimrisc\fP distribution archive contains the default configuration file
as \fIsimrisc\-VERSION/stdconfig/simrisc\fP, where \fIVERSION\fP is
replaced by \fBsimrisc\fP\(cq\&s actual release version;
.IP o
when installing \fBsimrisc\fP using Linux distribution archives (e\&.g\&.,
\fI\&.deb\fP files) the default configuration file is commonly available
as \fI/usr/shared/doc/simrisc/simrisc\&.gz\fP
.PP
.SH "SEE ALSO"
.PP
\fBsimriscparams\fP(7)
.PP
.SH "COPYRIGHT"
This is free software, distributed under the terms of the
GNU General Public License (GPL)\&.
.PP
.SH "AUTHOR"
Frank B\&. Brokken (\fBf\&.b\&.brokken@rug\&.nl\fP),
.br
.PP