analyses
The analyses
argument is the name of the file specifying the analyses to
perform. See section ANALYSES for details.
Simrisc was originally designed around 2010 by Marcel Greuter at the University Medical Center Groningen, and thereafter modified in 2015 by Chris de Jonge.
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.
basedir
(-B)./
. 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;
path
(-C)
path
(-D)!
(mnemonic: the logical not operator, i.e.,
--data !
). See section OUTPUT for a description of the
generated data;
age
(-a)tumor-age
, and is mutually
exclusive with the case
option;
path
(-C)~/.config/simrisc'
is used.
cases
(-n)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;
label
specifications. See section ANALYSES for details;
path
(-P)
path
(-R)!
(i.e., --rounds !
). See section
OUTPUT for a description of the generated summary info;
path
(-S)!
(i.e.,
--sensitivity !
). See section OUTPUT for a description of the
produced sensitivity summary;
age
(-t)death-age
, and is mutually
exclusive with the case
option;
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:Following this line the characteristics of the analysis are specified. These specifications may
analysis:
lines specify two
analyses);
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/ cases: 20Actually provided command-line options always overrule options that are specified in analyses files. If a scenario specification merely consists of the line
scenario:
an analysis is performed using the parameter
specifications that are found in the program's configuration file.
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: 3the analysis performs perform 3 iterations.
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.,
round: 50 Mammo MRI round: 55 Mammo MRI round: 60 Mammo MRI round: 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 -D /tmp/data -o Scenario:, cases: 1000, seed: 20can be issued.
one-analysis
option is used that parameter sections
must precede parameter specifications. As the parameters cases
and
seed
are defined in the `Scenario' section (cf. simriscparams(7))
they must be preceded by the Scenario:
specification.
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.
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 +0200An empty line follows next, whereafter the file's specific data are written. 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 first line lists the
comma-separated variable labels, followed by the comma separated data
line(s).
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):
case:
the (0-based) case-index;
cause of death:
either Natural
or Tumor
;
death age:
the case's age of death;
natural death age:
the case's natural age of death (if no tumor
occurs);
death status:
a numeric index specifying how and at what stage the
case died: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 doubling days:
the time (in days) it takes for the tumor to
double its size;
tumor preclinical period:
the age at which the tumor is potentially
detectible by Mammographic screening;
tumor onset age:
the age at which the tumor first occurred;
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 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;
costs:
the case's screening and (if appliccable) treatment costs;
self-detection indicator
: 1 if the tumor was self-detected, 0 if not
(also if there's no tumor);
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).
~/.config/simrisc
: the default location of the program's
configuration file;
simriscparams(7)