Scroll to navigation

simriscparams(7) simrisc configuration file organization simriscparams(7)

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 case sensitively interpreted. 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. Restrictions 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 between # 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.

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:

spread: false
when specified as true then parameter spreading is used;
iterations: 1
the (positive) number of iterations used in a simulation loop;
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;
seed: 1
the (positive) value to seed the random number generator with. This parameter is ignored when generator: random was specified;
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:

biop: 176
the (positive) cost of performing a biopsy;
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.
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):

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   


    #      bi-rad:  a       b       c       d             


    dose:           3       3       3       3  


    m:             .136    .136    .136    .136


    #             ageGroup


    specificity:  0 - 40:  .961     40 - *: .965


    #        1       2        3        4    


    beta:  -4.38     .49    -1.34    -7.18


    systematicError:  0.1
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;
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   


    #      bi-rad:  a       b       c       d             


    dose:           3       3       3       3  


    sensitivity:    .87     .84     .73     .65   


    #             ageGroup


    specificity:  0 - 40:  .961     40 - *: .965

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


    sensitivity:    .94


    specificity:    .95

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. 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 


    #                   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:

when using the Normal distribution N(mean, stddev): 


   N(value, spread)
when using the Uniform distribution U(begin, end): 


   U(value - spread / 2, value + spread / 2)
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:



   #       beta    eta     spread  dist. 


   beir7:  0.51    -2.0    0.32    Normal
If spread and dist are specified then the beta and eta parameters vary using these distribution parameters when spread: true is specified.

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:

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;
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;
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;
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:

the probability that the carrier is observed;
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.
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;
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

~/.config/simrisc: the default location of the program’s configuration file;
the simrisc distribution archive contains the default configuration file as simrisc-VERSION/stdconfig/simrisc, where VERSION is replaced by simrisc’s actual release version;
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),

2020-2021 simrisc.14.02.00