Provided by: simrisc_14.05.00-3_amd64 
NAME
simriscparams - The description of the configuration files
DESCRIPTION
This page describes the organization of the simrisc configuration files. These files are formatted like
standard unix configuration files. Lines are interpreted after removing initial white-space (blanks and
tabs). If a line ends in \ (a backslash), then the next line (initial white-space removed) is appended
to the current line.
While processing the configuration files trailing blanks and information on lines starting at the first #
character are removed.
Note that all parameter identifiers are interpreted case sensitively. E.g., Costs: is a different
parameter than costs:. The numeric values used in this man-page are for illustration purpose only. Some
restrictions apply though: standard deviations cannot be negative; proportions and probabilities must lie
in the range 0..1; multiple probabilities (like the ones used for breast densities) must add up to 1;
etc. If restrictions apply then they are mentioned at the various parameter descriptions below.
DEFAULT CONFIGURATION FILE
A configuration file provided in the simrisc distribution is
/usr/share/doc/simrisc/simrisc.gz.
Usually this file is unzipped to the ~/.config directory:
gunzip < /usr/share/doc/simrisc/simrisc.gz > ~/.config/
whereafter ~/.config/simrisc can be edited to contain local modifications.
Various parameters specify probability distributions. Usually the Normal distribution is specified. The
program also recognizes the LogNormal and Uniform distributions.
Parameter specifications start with keywords, followed by a colon. The keywords are listed in the
following overview. The format of the specifications is also fixed, but empty lines and white space may
be used to improve the specifications’ readabilities. Also, all characters starting at # characters until
the end of the line are considered comment and are ignored.
Parameter specifications starting with uppercase letters (like Scenario:) specify (sub)sections and
contain no additional specifications. Specifications starting with lowercase letters (like ageGroup:) are
followed by actual parameter values.
The configuration file must define all parameters of all configuration sections, but configuration
parameters can be modified using a separate analysis file or using overriding command-line parameters.
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.
The Scenario section
This section starts with a line containing Scenario: and it defines some general parameters that are used
during the simulation process. The default configuration file contains the following specifications:
o spread: false
when specified as true then parameter spreading is used;
o iterations: 1
the (positive) number of iterations used in a simulation loop;
o generator: random
in addition to random modes fixed and increasing are available.
This parameter specificies the way simrisc’s random number generators are initialized. When mode
random is specified the random number generators are initialized using randomly selected seeds and
seed (below) is not used. When mode fixed is used the random number generators are initialized
with seed’s value. When mode increasing is used the seeds of the random number generators are
incremented using a fixed increment at each iteration;
o seed: 1
the (positive) value to seed the random number generator with. This parameter is ignored when
generator: random was specified;
o cases: 100000
the (positive) number of cases to simulate;
The Costs section
This section starts with a line containing Costs: and it defines several parameters used for
cost-calculations. Modality-specific cost parameters are specified at the Modalities section. The default
configuration file contains the following specifications:
o biop: 176
the (positive) cost of performing a biopsy;
o diameters: 0: 6438 20: 7128 50: 7701
pairs of diameter: cost values specifying the treatment cost starting at the specified tumor
diameter, up to the next pair’s diameter (if specified) or all diameters starting at the diameter
specified at the last pair. The first diameter must be 0. The second value of each pair specifies
the (non-negative) treatment costs for that age-group.
o Discount:
the costs discount proportion starting at some age. This line is followed by two additional lines
specifying the starting age and discount proportion:
age: 50
proportion: 0
The BreastDensities section
This section starts with a line containing BreastDensities: and it defines breast density values for
various age groups, covering ages 0 through the maximum age for simulated cases. The default
configuration file contains the following specifications:
# bi-rad: a b c d
ageGroup: 0 - 40 0.05 0.30 0.48 0.17
ageGroup: 40 - 50 0.06 0.34 0.47 0.13
ageGroup: 50 - 60 0.08 0.50 0.37 0.05
ageGroup: 60 - 70 0.15 0.53 0.29 0.03
ageGroup: 70 - * 0.18 0.54 0.26 0.02
Age groups are half-open ranges: they start at their first ages, and end at (not including) their second
ages. The first ages of subsequent age groups must be equal to the second ages of their previous age
groups. For the last age group the specification * can be used, indicating that all ages at or above the
last age group’s begin age are handled by that group.
For each age group the probabilities of the four bi-rad classifications must sum to 1.0.
the Modalities section
This section starts with a line containing Modalities: and it specifies cancer-scanning modalities.
Currently three modalities are supported: Mammo, Tomo and MRI.
Some modalities specify age groups, which are (like the age ranges used for breastDensities) half-open
ranges: they start at their first ages, and end at (not including) their second-ages, while subsequent
age ranges must connect. Also, the last age group may use the end-age specification *.
The default configuration file contains (below the line Modalities:) the following specifications (if
modalities aren’t used their specifications are optional):
o Mammo:
For the Mammo modality the costs, radiation doses and m: parameter specifications per bi-rad
category, specificity probabilities for age groups, the parameters of the beta-function, and the
systematic error probability must be specified.
The default configuration file contains (below the line Mammo:) the following specifications
costs: 64
# default:
systematicError: 0.1
Dose:
# mean spread dist
bi-rad: a 3 1 Normal
bi-rad: b 3 1 Normal
bi-rad: c 3 1 Normal
bi-rad: d 3 1 Normal
M:
# proportion spread dist
bi-rad: a .061 .021 Normal
bi-rad: b .163 .045 Normal
bi-rad: c .400 .106 Normal
bi-rad: d .826 .088 Normal
Beta:
# mean spread dist
nr: 1 -4.38 .002 Normal
nr: 2 .49 .0005 Normal
nr: 3 -1.34 .0074 Normal
nr: 4 -7.18 .0340 Normal
Specificity:
# range proportion spread dist
ageGroup: 0 - 40 .961 .005 Normal
ageGroup: 40 - * .965 .005 Normal
For this modality the sensitivity is computed using the beta-function published by Isheden and
Humphreys (2017, Statistical Methods in Medical Research, 28(3), 681-702). From a randomly
generated probability and a case’s age the case’s bi-rad category is determined and that category
is then used to select the m-parameter that is used in the beta-function;
o Tomo:
For the Tomo modality the costs, radiation doses per bi-rad category, sensitivity probabilities
per bi-rad category, and specificity probabilities for age groups must be specified.
The default configuration file contains (below the line Tomo:) the following specifications:
costs: 64
Dose:
# mean spread dist
bi-rad: a 3 1 Normal
bi-rad: b 3 1 Normal
bi-rad: c 3 1 Normal
bi-rad: d 3 1 Normal
Sensitivity:
# proportion spread dist
bi-rad: a .87 .05 Normal
bi-rad: b .84 .05 Normal
bi-rad: c .73 .05 Normal
bi-rad: d .65 .05 Normal
Specificity:
# range proportion spread dist
ageGroup: 0 - 40 .961 .0025 Normal
ageGroup: 40 - * .965 .0025 Normal
o MRI:
For the MRI modality the costs, and the sensitivity and specificity probabilities must be
specified.
The default configuration file contains (below the line MRI:) the following specifications:
costs: 280
# proportion spread dist
sensitivity: .94 .005 Normal
specificity: .95 .005 Normal
The Screening section
This section starts with a line containing Screening: and it defines the ages at which screenings are
performed as well as the screenings attendance rate. If no screening rounds should be used then specify a
single round-specification line
round: none
Otherwise, each screening round is defined by the keyword round: followed by an age which in turn is
followed by a list of at least one space delimited modality specification (currently Mammo, Tomo and
MRI). The default configuration file contains (below the line Screening:) the following specifications:
round: 50 Mammo
round: 52 Mammo
round: 54 Mammo
round: 56 Mammo
round: 58 Mammo
round: 60 Mammo
round: 62 Mammo
round: 64 Mammo
round: 66 Mammo
round: 68 Mammo
round: 70 Mammo
round: 72 Mammo
round: 74 Mammo
In addition to the round specification line(s) the Screening section specifies the attendance rate
proportion. The default configuration file specifies:
# proportion:
attendanceRate: .8
The Tumor section
This section starts with a line containing Tumor: and it defines the parameters specifying tumor
characteristics. Several of the parameters in this section can be provided with a spread and distribution
specification. When spread: true is specified then these spread and distribution specifications are used
to apply statistical variations to these parameters.
Supported distributions are Normal, Uniform, and LogNormal. If value is the specified value parameter
value, and spread the specified spread parameter then the values that are actually used during the
simulations are:
o when using the Normal distribution N(mean, stddev):
N(value, spread)
o when using the Uniform distribution U(begin, end):
U(value - spread / 2, value + spread / 2)
o when using the LogNormal distribution L(mean, stddev):
L(value, spread)
The spread parameters may not be negative. If spread is specified then the distribution must also be
specified. If spread is not specified, then the value parameter won’t vary if spread: true is specified
in the Scenario section.
The Tumor: section has four subsections: beir7:, Growth, Incidence:, and Survival:. They contain the
following parameter specifications:
beir7:
BEIR (tumor induction) parameters: only tumor induction type 7 (i.e., beir7) is used. The default
configuration file contains this specification:
# eta beta spread dist.
beir7: -2.0 0.51 0.32 Normal
If spread: true is specified then the actually used beta parameter is drawn from the specified
distribution having the specified std.dev. (spread).
Growth:
Tumor growth specifications consist of three elements: the start diameter, the self-detect parameters and
the doubling time specifications.
The start parameter defines the start diameter of emerging tumors. The default configuration file
contains the following specification:
start: 5
Four parameters are used to determine the diameter at which self-detection is possible. These parameters
are:
o the standard deviation (stdev, see below) used by the lognormal distribution to compute the
diameter at which self-detection occurs. This parameter is required and cannot be negative;
o the mean (see below) used by the lognormal distribution. This parameter is required and cannot be
negative. Its value will vary using the following two parameters if spread: true was specified;
o the spread (standard deviation) used by the distribution that is used to vary the mean if spread:
true was specified. It can be omitted in which case the mean won’t vary;
o the distribution used to vary the mean. If the previous parameter is omitted then this parameter
must also be omitted.
The actually used self-detect diameter is computed using:
diameter = L(mean, stdev)
The default configuration file contains these parameter specifications:
# stdev value spread dist.
selfDetect: .70 2.92 .084 Normal
Finally, the Growth: subsection also defines tumor doubling times for various age groups. Doubling times
are computed like the self-detect diameters, i.e., using lognormal distributions. Thus, age groups are
followed by four parameter specifications (of which the last two are optional): the standard deviation of
the lognormal distribution, the mean value of the lognormal distribution, and the spread and name of the
distribution that is used when spread: true was specified. The age groups must cover ages 0 through the
maximum age for simulated cases, and are specified as described at section BreastDensities:. The default
configuration file contains the following specifications:
DoublingTime:
# stdev mean spread dist.
ageGroup: 1 - 50 .61 4.38 .43 Normal
ageGroup: 50 - 70 .26 5.06 .17 Normal
ageGroup: 70 - * .45 5.24 .23 Normal
Incidence:
Three carrier types are supported: Normal, BRCA1 and BRCA2. Each having a probability of occurrence. The
probabilities of specified carriers must add to 1. Each carrier is identified by its name (e.g., Normal:)
followed by four parameter specifications:
o the probability that the carrier is observed;
o the standard deviation used when computing the risk of getting a tumor. As this standard deviation
is used in the denominator of expressions it must be larger than zero.
o the lifetime risk: three parameters specifying a probability, optionally followed by the standard
deviation and distribution that is used to vary the probability when spread: true is specified;
o the mean age: three parameters specifying the mean age, optionally followed by the standard
deviation and distribution that is used to vary the probability when spread: true is specified;
The default configuration file specifies the Normal carrier’s probability as 1, effectively suppressing
the other carriers. The default configuration file contains (below the Incidence: parameter line) the
following specifications:
Normal:
probability: 1
stdDev: 21.1
# value spread distr.
lifetimeRisk: .226 .0053 Normal
meanAge: 72.9 .552 Normal
BRCA1:
probability: 0
stdDev: 16.51
# value spread distr.
lifetimeRisk: .96
meanAge: 53.9
BRCA2:
probability: 0
stdDev: 16.51
# value spread distr.
lifetimeRisk: .96
meanAge: 53.9
Survival:
Four types of survival parameters must be specified. Each type specifies a distribution type, (a..d), a
mean, and an (optional) spread and distribution which is used when spread: true is specified. The default
configuration file specifies:
# value spread dist:
type: a .00004475 .000004392 Normal
type: b 1.85867 .0420 Normal
type: c -.271 .0101 Normal
type: d 2.0167 .0366 Normal
PARAMETER RESPECIFICATION
Parameters can be respecified by defining a separate parameter configuration file or by providing
alternate parameter specifications in analyses: sections of the program’s input file, or by providing
alternative parameter specifications as command-line arguments (cf. the simrisc(3) man-page)
FILES
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
simrisc(1)
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 simriscparams(7)