.TH "simriscparams" "7" "2020\-2021" "simrisc\&.14\&.02\&.00" "simrisc configuration file organization" .PP .SH "NAME" simriscparams \- The description of the configuration files .PP .SH "DESCRIPTION" .PP This page describes the organization of the \fBsimrisc\fP 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 \e (a backslash), then the next line (initial white\-space removed) is appended to the current line\&. .PP While processing the configuration files trailing blanks and information on lines starting at the first # character are removed\&. .PP Note that all parameter identifiers are case sensitively interpreted\&. E\&.g\&., \fICosts:\fP is a different parameter than \fIcosts:\fP\&. 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\&. .PP .SH "DEFAULT CONFIGURATION FILE" .PP A configuration file provided in the \fBsimrisc\fP distribution is .br \fI/usr/share/doc/simrisc/simrisc\&.gz\fP\&. .PP Usually this file is unzipped to the \fI~/\&.config\fP directory: .nf gunzip < /usr/share/doc/simrisc/simrisc\&.gz > ~/\&.config/ .fi whereafter \fI~/\&.config/simrisc\fP can be edited to contain local modifications\&. .PP Various parameters specify probability distributions\&. Usually the \fINormal\fP distribution is specified\&. The program also recognizes the \fILogNormal\fP and \fIUniform\fP distributions\&. .PP 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\(cq\& readabilities\&. Also, all characters between \fI#\fP characters until the end of the line are considered comment and are ignored\&. .PP Parameter specifications starting with uppercase letters (like \fIScenario:\fP) specify (sub)sections and contain no additional specifications\&. Specifications starting with lowercase letters (like \fIageGroup:\fP) are followed by actual parameter values\&. .PP 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\&. .PP .SH "The Scenario section" .PP This section starts with a line containing \fIScenario:\fP and it defines some general parameters that are used during the simulation process\&. The default configuration file contains the following specifications: .PP .IP o \fIspread: false\fP .br when specified as \fItrue\fP then parameter spreading is used; .IP .IP o \fIiterations: 1\fP .br the (positive) number of iterations used in a simulation loop; .IP .IP o \fIgenerator: random\fP .br in addition to \fIrandom\fP modes \fIfixed\fP and \fIincreasing\fP are available\&. .br This parameter specificies the way \fIsimrisc\(cq\&s\fP random number generators are initialized\&. When mode \fIrandom\fP is specified the random number generators are initialized using randomly selected seeds and \fIseed\fP (below) is not used\&. When mode \fIfixed\fP is used the random number generators are initialized with \fIseed\(cq\&s\fP value\&. When mode \fIincreasing\fP is used the seeds of the random number generators are incremented using a fixed increment at each iteration; .IP .IP o \fIseed: 1\fP .br the (positive) value to seed the random number generator with\&. This parameter is ignored when \fIgenerator: random\fP was specified; .IP .IP o \fIcases: 100000\fP .br the (positive) number of cases to simulate; .PP .SH "The Costs section" .PP This section starts with a line containing \fICosts:\fP and it defines several parameters used for cost\-calculations\&. Modality\-specific cost parameters are specified at the \fIModalities\fP section\&. The default configuration file contains the following specifications: .PP .IP o \fIbiop: 176\fP .br the (positive) cost of performing a biopsy; .IP .IP o \fIdiameters: 0: 6438 20: 7128 50: 7701\fP .br pairs of \fIdiameter: cost\fP values specifying the treatment cost starting at the specified tumor diameter, up to the next pair\(cq\&s diameter (if specified) or all diameters starting at the diameter specified at the last pair\&. The first diameter \fImust\fP be 0\&. The second value of each pair specifies the (non\-negative) treatment costs for that age\-group\&. .IP .IP o \fIDiscount:\fP .br the costs discount proportion starting at some age\&. This line is followed by two additional lines specifying the starting age and discount proportion: .nf age: 50 proportion: 0 .fi .PP .SH "The BreastDensities section" .PP This section starts with a line containing \fIBreastDensities:\fP 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: .nf # 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 .fi 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 \fI*\fP can be used, indicating that all ages at or above the last age group\(cq\&s begin age are handled by that group\&. .br For each age group the probabilities of the four bi\-rad classifications must sum to 1\&.0\&. .PP .SH "the Modalities section" .PP This section starts with a line containing \fIModalities:\fP and it specifies cancer\-scanning modalities\&. Currently three modalities are supported: \fIMammo, Tomo\fP and \fIMRI\fP\&. .PP Some modalities specify age groups, which are (like the age ranges used for \fIbreastDensities\fP) 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 \fI*\fP\&. .PP The default configuration file contains (below the line \fIModalities:\fP) the following specifications (if modalities aren\(cq\&t used their specifications are optional): .PP .IP o \fIMammo:\fP .br For the \fIMammo\fP modality the costs, radiation doses and \fIm:\fP 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\&. .br The default configuration file contains (below the line \fIMammo:\fP) the following specifications: .nf 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 .fi 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\(cq\&s age the case\(cq\&s bi\-rad category is determined and that category is then used to select the m\-parameter that is used in the beta\-function; .IP .IP o \fITomo:\fP .br For the \fITomo\fP modality the costs, radiation doses per bi\-rad category, sensitivity probabilities per bi\-rad category, and specificity probabilities for age groups must be specified\&. .br The default configuration file contains (below the line \fITomo:\fP) the following specifications: .nf 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 .fi .IP .IP o \fIMRI:\fP .br For the \fIMRI\fP modality the costs, and the sensitivity and specificity probabilities must be specified\&. .br The default configuration file contains (below the line \fIMRI:\fP) the following specifications: .nf costs: 280 sensitivity: \&.94 specificity: \&.95 .fi .PP .SH "The Screening section" .PP This section starts with a line containing \fIScreening:\fP 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 \fIround:\fP followed by an age which in turn is followed by a list of at least one space delimited modality specification (currently \fIMammo, Tomo\fP and \fIMRI\fP)\&. The default configuration file contains (below the line \fIScreening:\fP) the following specifications: .nf 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 .fi .PP .SH "The Tumor section" .PP This section starts with a line containing \fITumor:\fP 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 \fIspread: true\fP is specified then these spread and distribution specifications are used to apply statistical variations to these parameters\&. .PP Supported distributions are \fINormal, Uniform,\fP and \fILogNormal\fP\&. If \fIvalue\fP is the specified \fIvalue\fP parameter value, and \fIspread\fP the specified \fIspread\fP parameter then the values that are actually used during the simulations are: .IP o when using the \fINormal\fP distribution \fIN(mean, stddev)\fP: .nf N(value, spread) .fi .IP o when using the \fIUniform\fP distribution \fIU(begin, end)\fP: .nf U(value \- spread / 2, value + spread / 2) .fi .IP o when using the \fILogNormal\fP distribution \fIL(mean, stddev)\fP: .nf L(value, spread) .fi .PP The \fIspread\fP parameters may not be negative\&. If \fIspread\fP is specified then the distribution must also be specified\&. If \fIspread\fP is not specified, then the \fIvalue\fP parameter won\(cq\&t vary if \fIspread: true\fP is specified in the \fIScenario\fP section\&. .PP The \fITumor:\fP section has four subsections: \fIbeir7:, Growth, Incidence:,\fP and \fISurvival:\fP\&. They contain the following parameter specifications: .PP \fBbeir7:\fP .PP BEIR (tumor induction) parameters: only tumor induction type 7 (i\&.e\&., beir7) is used\&. The default configuration file contains this specification: .nf # beta eta spread dist\&. beir7: 0\&.51 \-2\&.0 0\&.32 Normal .fi If \fIspread\fP and \fIdist\fP are specified then the \fIbeta\fP and \fIeta\fP parameters vary using these distribution parameters when \fIspread: true\fP is specified\&. .PP \fBGrowth:\fP .PP Tumor growth specifications consist of three elements: the start diameter, the self\-detect parameters and the doubling time specifications\&. .PP The \fIstart\fP parameter defines the start diameter of emerging tumors\&. The default configuration file contains the following specification: .nf start: 5 .fi .PP Four parameters are used to determine the diameter at which self\-detection is possible\&. These parameters are: .IP o the standard deviation (\fIstdev\fP, see below) used by the lognormal distribution to compute the diameter at which self\-detection occurs\&. This parameter is required and cannot be negative; .IP o the \fImean\fP (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 \fIspread: true\fP was specified; .IP o the spread (standard deviation) used by the distribution that is used to vary the mean if \fIspread: true\fP was specified\&. It can be omitted in which case the mean won\(cq\&t vary; .IP o the distribution used to vary the mean\&. If the previous parameter is omitted then this parameter must also be omitted\&. .PP The actually used self\-detect diameter is computed using: .nf diameter = L(mean, stdev) .fi .PP The default configuration file contains these parameter specifications: .nf # stdev value spread dist\&. selfDetect: \&.70 2\&.92 \&.084 Normal .fi .PP Finally, the \fIGrowth:\fP 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 \fIspread: true\fP was specified\&. The age groups must cover ages 0 through the maximum age for simulated cases, and are specified as described at section \fIBreastDensities:\fP\&. The default configuration file contains the following specifications: .nf 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 .fi .PP \fBIncidence:\fP .PP Three carrier types are supported: \fINormal, BRCA1\fP and \fIBRCA2\fP\&. Each having a probability of occurrence\&. The probabilities of specified carriers must add to 1\&. Each carrier is identified by its name (e\&.g\&., \fINormal:\fP) followed by four parameter specifications: .IP o the probability that the carrier is observed; .IP 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\&. .IP 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 \fIspread: true\fP is specified; .IP 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 \fIspread: true\fP is specified; .PP The default configuration file specifies the \fINormal\fP carrier\(cq\&s probability as 1, effectively suppressing the other carriers\&. The default configuration file contains (below the \fIIncidence:\fP parameter line) the following specifications: .nf 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 .fi .PP \fBSurvival:\fP .PP 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 \fIspread: true\fP is specified\&. The default configuration file specifies: .nf # 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 .fi .PP .SH "PARAMETER RESPECIFICATION" .PP Parameters can be respecified by defining a separate parameter configuration file or by providing alternate parameter specifications in \fIanalyses:\fP sections of the program\(cq\&s input file, or by providing alternative parameter specifications as command\-line arguments (cf\&. the \fBsimrisc\fP(3) man\-page) .SH "FILES" .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 \fBsimrisc\fP(1) .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