NOUSERMACRO(simriscparams N U L)

includefile(../../release.yo)

htmlbodyopt(text)(#27408B)
htmlbodyopt(bgcolor)(#FFFAF0)
whenhtml(mailto(Frank B. Brokken: f.b.brokken@rug.nl))

DEFINEMACRO(itq)(2)(\
    it() verb(ARG1)ARG2
)

DEFINEMACRO(itt)(1)(it() tt(ARG1)nl())

DEFINEMACRO(sr)(0)(bf(simrisc))
DEFINEMACRO(Sr)(0)(bf(Simrisc))

IFDEF(man)(
    DELETEMACRO(tt)
    DEFINEMACRO(tt)(1)(em(ARG1))
)()    

COMMENT( man-request, section, date, distribution file, general name)
manpage(simriscparams)(7)(_CurYrs_)(simrisc._CurVers_)
        (simrisc configuration file organization)

COMMENT( man-request, larger title )
manpagename(simriscparams)(The description of the sc() configuration files)

manpagedescription()

This page describes the organization of the sr() 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.,
tt(Costs:) is a different parameter than tt(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.

manpagesection(DEFAULT CONFIGURATION FILE)

A configuration file provided in the sr() distribution is+nl()
tt(/usr/share/doc/simrisc/simrisc.gz).

Usually this file is unzipped to the tt(~/.config) directory:
    verb(
    gunzip < /usr/share/doc/simrisc/simrisc.gz > ~/.config/
   )
 whereafter tt(~/.config/simrisc) can be edited to contain local
modifications.

Various parameters specify probability distributions. Usually the tt(Normal)
distribution is specified. The program also recognizes the tt(LogNormal) 
and tt(Uniform) COMMENT(and Exponential) 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
tt(#) characters until the end of the line are considered comment and are
ignored.

Parameter specifications starting with uppercase letters (like tt(Scenario:))
specify (sub)sections and contain no additional specifications. Specifications
starting with lowercase letters (like tt(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.

includefile(include/changes)

manpagesection(The Scenario section)

This section starts with a line containing tt(Scenario:) and it 
defines some
general parameters that are used during the simulation process. The default
configuration file contains the following specifications:

    itemization(
    itt(spread: false)
       when specified as tt(true) then parameter spreading is used;

    itt(iterations:  1)
       the (positive) number of iterations used in a simulation loop;

    itt(generator: random)
       in addition to tt(random) modes tt(fixed) and tt(increasing) are
        available.nl()
       This parameter specificies the way tt(simrisc's) random number
        generators are initialized. When mode tt(random) is specified the
        random number generators are initialized using randomly selected seeds
        and tt(seed) (below) is not used. When mode tt(fixed) is used the
        random number generators are initialized with tt(seed's) value. When
        mode tt(increasing) is used the seeds of the random number generators
        are incremented using a fixed increment at each iteration;

    itt(seed: 1) 
       the (positive) value to seed the random number generator with. This
        parameter is ignored when tt(generator: random) was specified;

    itt(cases: 100000)
       the (positive) number of cases to simulate;
    )

manpagesection(The Costs section)

This section starts with a line containing tt(Costs:) and it defines several
parameters used for cost-calculations. Modality-specific cost parameters are
specified at the tt(Modalities) section. The default configuration file
contains the following specifications:

    itemization(
    itt(biop: 176)
        the (positive) cost of performing a biopsy;

    itt(diameters: 0: 6438  20: 7128  50: 7701)
       pairs of tt(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 em(must) be 0. The
        second value of each pair specifies the (non-negative) treatment costs
        for that age-group.

    itt(Discount:)
       the costs discount proportion starting at some age. This line is
        followed by two additional lines specifying the starting age and
        discount proportion:
       verb(
    age:        50
    proportion:  0
        )
    )

manpagesection(The BreastDensities section)

This section starts with a line containing tt(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:
       verb(
    #                  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 tt(*) can be used,
        indicating that all ages at or above the last age group's begin age
        are handled by that group.nl()
       For each age group the probabilities of the four bi-rad classifications
        must sum to 1.0. 


manpagesection(the Modalities  section)

This section starts with a line containing tt(Modalities:) and it specifies
cancer-scanning modalities. Currently three modalities are supported: tt(Mammo,
Tomo) and tt(MRI).

Some modalities specify age groups, which are (like the age ranges used for
tt(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 tt(*).

The default configuration file contains (below the line tt(Modalities:)) the
following specifications (if modalities aren't used their specifications are
optional):

    itemization(
    itt(Mammo:)
       For the tt(Mammo) modality the costs, radiation doses and em(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.nl()
       The default configuration file contains (below the line tt(Mammo:)) the
        following specifications
       verb(
        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;

    itt(Tomo:)
       For the tt(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.nl()
       The default configuration file contains (below the line tt(Tomo:)) the
        following specifications:
       verb(
        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
      )

    itt(MRI:)
       For the tt(MRI) modality the costs, and the sensitivity and
        specificity probabilities must be specified.nl()
       The default configuration file contains (below the line tt(MRI:)) the
        following specifications:
       verb(
        costs:          280
        #               proportion  spread      dist
        sensitivity:      .94        .005       Normal
        specificity:      .95        .005       Normal
        )
    )

manpagesection(The Screening section)

This section starts with a line containing tt(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
        verb(
    round: none
        ) 
    Otherwise, each screening round is defined by the keyword tt(round:)
followed by an age which in turn is followed by a list of at least one space
delimited modality specification (currently tt(Mammo, Tomo) and tt(MRI)). The
default configuration file contains (below the line tt(Screening:)) the
following specifications:
       verb(
    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 tt(round) specification line(s) the tt(Screening) section
specifies the attendance rate proportion. The default configuration file
specifies:
    verb(
    #                   proportion:
    attendanceRate:     .8     
        )

manpagesection(The Tumor  section)

This section starts with a line containing tt(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
tt(spread: true) is specified then these spread and distribution
specifications are used to apply statistical variations to these parameters.

Supported distributions are tt(Normal, Uniform,) and tt(LogNormal). If
tt(value) is the specified tt(value) parameter value, and tt(spread) the
specified tt(spread) parameter then the values that are actually used during
the simulations are:
    itemization(
    it() when using the tt(Normal) distribution tt(N(mean, stddev)):
        verb(   N(value, spread))
    it() when using the tt(Uniform) distribution tt(U(begin, end)):
        verb(   U(value - spread / 2, value + spread / 2))
    it() when using the tt(LogNormal) distribution tt(L(mean, stddev)):
        verb(   L(value, spread))
    )

The tt(spread) parameters may not be negative. If tt(spread) is
specified then the distribution must also be specified. If tt(spread) is not
specified, then the tt(value) parameter won't vary if tt(spread: true) is
specified in the tt(Scenario) section.

The tt(Tumor:) section has four subsections: tt(beir7:, Growth, Incidence:,)
and tt(Survival:). They contain the following parameter specifications:

bf(beir7:)

    BEIR (tumor induction) parameters: only tumor induction type 7 (i.e.,
    beir7) is used. The default configuration file contains this
    specification: 
   verb(
    #       eta     beta    spread  dist. 
    beir7:  -2.0    0.51    0.32    Normal
       )
   If tt(spread: true) is specified then the actually used tt(beta) parameter
    is drawn from the specified distribution having the specified
    std.dev. (spread).

bf(Growth:)

    Tumor growth specifications consist of three elements: the
    start diameter, the self-detect parameters and the doubling time
    specifications. 

    The tt(start) parameter defines the start diameter of emerging tumors. The
    default configuration file contains the following specification:
   verb(
    start:  5
    )

    Four parameters are used to determine the diameter at which
    self-detection is possible. These parameters are:
    itemization(
    it() the standard deviation (tt(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;
    it() the tt(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 tt(spread: true) was
        specified;
    it() the spread (standard deviation) used by the distribution that is used
        to vary the mean if tt(spread: true) was specified. It can be omitted
        in which case the mean won't vary;
    it() 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:
   verb(
    diameter = L(mean, stdev)
   ) 

   The default configuration file contains these parameter specifications:
   verb(
                 #  stdev   value   spread  dist.  
    selfDetect:     .70     2.92    .084    Normal      

   )       

    Finally, the tt(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 tt(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 tt(BreastDensities:). The default
    configuration file contains the following specifications:
   verb(
    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     
   )

bf(Incidence:)

    Three carrier types are supported: tt(Normal, BRCA1) and tt(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.,
    tt(Normal:)) followed by four parameter specifications:
   itemization(
    it() the probability that the carrier is observed;
    it() 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.
        COMMENT(incidence/settumorrisk2.cc)
    it() the lifetime risk: three parameters specifying a probability,
        optionally followed by the standard deviation and distribution that is
        used to vary the probability when tt(spread: true) is specified;
    it() 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 tt(spread: true) is specified;
    )

   The default configuration file specifies the tt(Normal) carrier's
    probability as 1, effectively suppressing the other carriers. The default
    configuration file contains (below the tt(Incidence:) parameter
    line) the following specifications:
   verb(
    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
   )

bf(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 tt(spread: true) is specified. The
default configuration file specifies:
       verb(
    #              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
        )        


manpagesection(PARAMETER RESPECIFICATION)

Parameters can be respecified by defining a separate parameter configuration
file or by providing alternate parameter specifications in tt(analyses:)
sections of the program's input file, or by providing alternative parameter
specifications as command-line arguments (cf. the bf(simrisc)(3) man-page)
manpagefiles()

includefile(include/configfiles.yo)

manpageseealso()

     bf(simrisc)(1)

COMMENT(
    manpagebugs()
    
        too early for that ...
END)

includefile(include/trailer.yo)


