.TH "simrisc" "1" "2020\-2024" "simrisc\&.15\&.05\&.00" "simrisc cancer simulation program"
.PP
.SH "NAME"
simrisc \- This program performs simulations in the context of
breast and lung 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\-\-cancer\fP=\fItype\fP (\fB\-c\fP)
.br
The simulation type (\fItype\fP) can be specified as \fIbreast\fP to
perform breast cancer simulations\&. Breast cancer simulations are
performed by default when the \fI\-\-cancer\fP option is not
specified\&. Alternatively, to perform lung cancer simulations \fItype\fP
must be specified as either \fImale\fP or \fIfemale\fP to perform
simulations for, respectively, male or female cases\&.
.IP
Be advised that the default configuration file specifies \fIScreening
Mammo\fP rounds, which must either be changed to \fICT\fP in locally used
configuration files or in \fIAnalysis:\fP sections (see section
\fBANALYSES\fP below);
.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\-\-log\fP \fIbegin end fname [set]\fP
.br
log process actions of cases \fIbegin\fP thru \fIend\fP on the file
\fIfname\fP\&. This includes generated random values\&. Random values
generated in several contexts can be suppressed\&. Specify
.br
* \fBC\fP to suppress generated case\-specific uniformly distributed
random values
.br
* \fBL\fP to suppress generated log\-normal distributed
random values
.br
* \fBU\fP to suppress generated uniformly distributed
random values not associated with cases
.br
* \fBV\fP to suppress generated uniformly distributed
random values associated with VSD computations\&.
.IP
Note that \fIbegin end\fP 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 \fI\-\-log \(dq\&100 100 fname LUV\(dq\&\fP\&. Also note that only
a \fIsingle\fP argument ispassed to \fI\-\-log\fP\&. Therefore its argument
must be surrounded by quotes;
.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\&. If the
\fI\-\-base (\-B)\fP option was specified then \fIpath\fP is written in the
base directory if \fIpath\fP does not contain a slash (/) (use
\fI\&./path\fP to write the parameters file in the current directory if
\fI\-\-base\fP was specified);
.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\-\-spread\fP=\fIpath\fP (\fB\-s\fP)
.br
path name of the file containing the configured and actually used
parameter values when \fIspread: true\fP is specified (default:
\(cq\&/spread\-$\&.txt\(cq\&)\&. If this file should not be written specify
\fI!\fP (mnemonic: the logical not operator, i\&.e\&., \fI\-\-spread !\fP)\&. If
a parameter doesn\(cq\&t use spreading then the \(cq\&using\(cq\& part is
omitted\&. See section \fBOUTPUT\fP for a sample of its content;
.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\-\-tnm\fP (\fB\-T\fP)
.br
The data file contains a column labeled \fITNM\fP showing the (0\-based)
\fITNM\fP categories for cases having developed tumors\&. 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 \fI\-\-tnm\fP option cases not having
developed tumors receive TNM column entries \fI\-1,0\fP to avoid missing
data;
.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 \fI\-\-one\-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\&. These files are called \fIanalysis files\fP\&. 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\&.
.PP
Configuration specifications starting with uppercase letters (like
\fIScenario:\fP and \fICosts:\fP) specify (sub)sections and don\(cq\&t contain
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\&.
.PP
Options specified on the command\-line cannot be specified in
\fIAnalysis:\fP sections and remain active while \fBsimrisc\fP is running\&. The default
option values are reset at each separate \fIAnalysis:\fP unless an option has
been specified on the command\-line, in which case those option values are used
throughout the \fBsimrisc\fP run\&.
.PP
Following \fIAnalysis:\fP lines the characteristics of the analysis are
specified which can be specified for each \fIAnalysis:\fP specification, in the
following order:
.IP o
a \fIlabel:\fP line: \fIlabel:\fP lines, when used, must immediately
follow \fIAnalysis:\fP lines\&. The text following \fIlabel:\fP is
written at the top of the output files;
.IP o
option lines: specifying \fBsimrisc\fP 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\&.:
.nf
base: /tmp/
last\-case: 20
.fi
.IP
.IP o
parameter specifications: modify (some) parameter specifications
defined in configuration files\&. When parameters of configuration file
sections (cf\&. \fBsimriscparams\fP(7)) are not specified then the
parameters specified in the configuration file are used\&.
.PP
All specifications in \fIAnalysis:\fP sections are optional\&. An
\fIAnalysis:\fP section 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, initial and 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
Filename specified in \fIAnalysis:\fP sections may start with a tilde character
(~) which is replaced by the user\(cq\&s home directory, or they may start with an
initial + character, which is replaced by the program\(cq\&s base directory (see
option \fIbase\fP)\&. When an analysis performs multiple iterations then `$\(cq\&
characters in filename specifications are replaced by the analysis\(cq\& interation
index\&.
.PP
Multiple analysis sections should not specify 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
Scenario:
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 are modified 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
When an \fIAnalysis:\fP specification modifies parameters, then subsequent
\fIAnalysis:\fP sections start from the unmodified option and parameter
specifications\&.
.PP
Here is an example of an analysis file specifying two analyses:
.nf
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
.fi
.PP
.SH "OUTPUT"
.PP
The first lines of the generated files contain time stamps showing the date
and time when the files were written and the used \fISimRisc\fP version\&. Here is
an example, following the RFC 2822 format for the timestamp:
.nf
Mon, 14 Nov 2022 15:30:26 +0100 (SimRisc V\&. 15\&.00\&.00)
.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 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)\&.
.IP
.IP o
\fIscreening rounds\fP: 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:
.IP o
0: the case did not attend this screening round;
.IP o
1: the case did attend this screening round;
.IP o
2: the case did attend this screening round, resulting in a false
negative diagnosis;
.IP 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:
.nf
0011311110000
.fi
Using screening round indices (which are also used to refer to rounds
in the \fIrounds\-$\&.txt\fP files), this case did not attent screening
rounds 0, 1, 9, 10, 11 and 12, and at 4 a false positive diagnosis was
obtained\&. Note that the screening round indices start at 0: the first
screening round is indicated by index 0\&.
.PP
\fBActually used spread\-values\fP
.PP
When \fIspread: true\fP is specified then by default the actually used and
orgiginal parameter values are written to the file \fIspread\-$\&.txt\fP, where
\fI$\fP is replaced by the loop\(cq\&s iteration index\&. Here is a sample from the
content of such a file, showing the values of the \fITumor: DoublingTime:\fP
agegroups parameters:
.nf
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
.fi
.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 "BUGS"
.PP
Versions before version 15\&.03\&.00 should not be used for lung cancer
simulations\&. The bug invalidating lung cancer simulations was repaired in
version 15\&.03\&.00\&.
.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