Provided by: simrisc_14.05.00-4_amd64 bug

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),