simrisc(1)

📦
version 16.06.00 · 5 versions
, in ubuntu resolute, ubuntu stonking

💖 simrisc(1) — the simrisc cancer simulation program 💖

okay bestie, sit down, hydrate, because this is the manual page for simrisc, and it's a whole moment. ✨

🌸 NAME 🌸

simrisc — this program performs simulations in the context of breast and lung cancer 🎀

🦋 SYNOPSIS 🦋

simrisc [options] analyses

So the analyses argument is the name of the file that tells simrisc which analyses to perform. If you wanna know the whole tea, go look at the ANALYSES section. 👑

✨ DESCRIPTION ✨

Simrisc was originally designed around 2010 by Marcel Greuter at the University Medical Center Groningen, and then it got modified in 2015 by Chris de Jonge. Literally a glow-up. 💅

💅 OPTIONS 💅

okay so here's how the options work, pay attention because this part matters:

Short options are handed to you between parentheses, right after their long option equivalents. Like (--base=basedir (-B)) — the (-B) is the lil short one. 🫶

Several of these parameters specify the path-names of files that simrisc produces. And there's a whole little magic system here:

  • If a path-name starts with a tilde character (~) then that tilde gets replaced by the user's home directory. 🏠
  • An initial + gets replaced by the program's base directory (peep the base option for that one).
  • When an analysis uses multiple iterations, then $ characters in filename specifications get replaced by that analysis' interation index. 💫

And the naming scheme, so you can always tell what's what:

  • All single-letter options referring to filesystem entries (directories, filenames) are capitalized. 🔠
  • All other single-letter options are lowercase. 🔡
  • --base=basedir (-B) — this is the base directory where the output files get written. Default is ./. If basedir doesn't exist, the program creates it. If the directory can't be created, an exception is thrown and the program terminates — no cap, it just ends. The basedir specifications may specify relative or absolute directory locations.
  • --cancer=type (-c) — the simulation type (type) can be specified as breast to perform breast cancer simulations. Breast cancer simulations are performed by default when the --cancer option isn't specified. Alternatively, to perform lung cancer simulations, type must be specified as either male or female, to do simulations for, respectively, male or female cases.
Heads up bestie: the default configuration file specifies Screening Mammo rounds, which must either be changed to CT in locally used configuration files or in Analysis: sections (see the ANALYSES section below). Don't say I didn't warn you. 😭
  • --config=path (-C) — the location of the configuration file. By default ~/.config/simrisc is used.
  • --data=path (-D) — path name of the file that will contain the data of the cases generated by the simulation (default: '<base>/data-$.txt'). If a data file should not be written, specify ! (mnemonic: the logical not operator, i.e., --data !). See the OUTPUT section for a description of the generated data.
  • --death-age=age (-a) — run one simulation using a specific natural death-age. This option also requires the specification of tumor-age, and it is mutually exclusive with the case option. 🙈
  • --help (-h) — shows help information and terminates.
  • --last-case=nCases (-l) — perform simulations until nCases cases have been analyzed, and only write the data for the final case to the data file. The rounds and sensitivity files contain the summarized results of all nCases analyzed cases.
  • --log begin end fname [set] — log process actions of cases begin thru end on the file fname. This includes generated random values. Random values generated in several contexts can be suppressed. Specify:
    • C to suppress generated case-specific uniformly distributed random values
    • L to suppress generated log-normal distributed random values
    • U to suppress generated uniformly distributed random values not associated with cases
    • V to suppress generated uniformly distributed random values associated with VSD computations.

Note that begin end defines an inclusive range. To log the process for a single case (e.g. case 100) ignoring the L, U, and V generated values, specify --log "100 100 fname LUV". Also note that only a single argument is passed to --log. Therefore its argument must be surrounded by quotes. 🎀

  • --one-analysis (-o) — the program's arguments specify the parameters of a single analysis, rather than the name of an analyses-specification file. The program's arguments are optional and are used to alter the parameter values as defined in the config file, or to define label specifications. See the ANALYSES section for details.
  • --parameters=path (-P) — path name of the file showing the actually used parameter specifications. By default no parameter file is written. If the --base (-B) option was specified, then path is written in the base directory if path does not contain a slash (/) — use ./path to write the parameters file in the current directory if --base was specified. 🧚
  • --rounds=path (-R) — path name of the file that will contain the summary info of the simulation rounds (default: '<base>/rounds-$.txt'). If a rounds file should not be written, specify ! (i.e., --rounds !). See the OUTPUT section for a description of the generated summary info.
  • --spread=path (-s) — path name of the file containing the configured and actually used parameter values when spread: true is specified (default: '<base>/spread-$.txt'). If this file should not be written, specify ! (mnemonic: the logical not operator, i.e., --spread !). If a parameter doesn't use spreading then the 'using' part is omitted. See the OUTPUT section for a sample of its content.
  • --sensitivity=path (-S) — path name of the file that will contain the summary info of the simulation's sensitivity data (default: '<base>/sensitivity.txt'). If a sensitivity file should not be written, specify ! (i.e., --sensitivity !). See the OUTPUT section for a description of the produced sensitivity summary.
  • --tnm (-T) — the data file contains a column labeled TNM showing the (0-based) TNM categories for cases having developed tumors (see also the simiscparams(7) man-page). By default this column remains empty for cases not having developed tumors, which may be inconvenient when processing the data (e.g., to perform statistical analyses). When specifying the --tnm option, cases not having developed tumors receive TNM column entries -1,0 to avoid missing data.
  • --tumor-age=age (-t) — run one simulation using a specific tumor self-detect age. This option also requires the specification of death-age, and it is mutually exclusive with the case option. 😭
  • --verbose (-V) — provides additional information while running.
  • --version (-v) — shows simrisc's version information and terminates.

💅 ANALYSES 💅

okay so, unless you're using the --one-analysis option, the program's first and only required argument is the name of a file that spills all the deets about which analyses to perform. These files are called analysis files. And bestie, they have to be standard ascii text files — like, they can only contain 7-bit ascii printable characters and white-space characters, that's the whole vibe. Identifiers used in analysis files and in configuration files are interpreted case sensitively, so don't be out here assuming Scenario: and scenario: are the same thing, they are not, periodt.

Configuration specifications starting with uppercase letters (like Scenario: and Costs:) specify (sub)sections and don't contain additional specifications. Specifications starting with lowercase letters (like ageGroup:) are the ones followed by actual parameter values. For a complete overview, go check the simriscparams(7) man-page. iykyk ✨

Analysis files may define multiple analyses. Each analysis specification must begin with a line containing

Analysis:

At each Analysis: specification the program's initial configuration is reset. Fresh start energy, every single time 💅.

Options specified on the command-line cannot be specified in Analysis: sections and remain active while simrisc is running. The default option values are reset at each separate Analysis: — unless an option has been specified on the command-line, in which case those option values are used throughout the simrisc run. Like, command-line options are the main characters and they do not reset. 👑

Following Analysis: lines the characteristics of the analysis are specified, which can be specified for each Analysis: specification, in the following order:

  • a label: line: label: lines, when used, must immediately follow Analysis: lines. The text following label: is written at the top of the output files;
  • option lines: specifying simrisc options (not specified on the command line) which are then used for that analysis. When program options are specified their long option names must be used. E.g.:
base:       /tmp/
last-case:  20
  • parameter specifications: modify (some) parameter specifications defined in configuration files. When parameters of configuration file sections (cf. simriscparams(7)) are not specified then the parameters specified in the configuration file are used.

All specifications in Analysis: sections are optional. An Analysis: section merely containing the line Analysis: defines an analysis using the explicitly specified command-line options or the default program options and using the parameter specifications provided in the configuration file. Minimalist queen 🫶.

Empty lines, initial and trailing white-space, and all characters on lines starting at the hash-mark (#) are ignored and may be used anywhere in analysis files. Comment your little heart out.

Lines not conforming to the above description result in error messages, causing simrisc to end. 💀 No soft launch, no warning, it just ends. Be careful out there.

Filenames specified in Analysis: sections may start with a tilde character (~) which is replaced by the user's home directory, or they may start with an initial + character, which is replaced by the program's base directory (see option base). When an analysis performs multiple iterations then $ characters in filename specifications are replaced by the analysis' interation index. Cute, right? 🎀

Multiple analysis sections should not specify identically named output files, as the output files are (re)written for each separate analysis. So if two of your analyses are writing to the same file name, that's a collision and it's not the serve you think it is 🙈.

Analysis sections are commonly used to alter the default specifications of the configuration file. E.g., the default number of iterations equals 1. By specifying

Scenario:
    iterations: 3

the analysis performs 3 iterations. Slay. ✨

Parameters are either read from the configuration file or they are redefined in Analysis: sections. E.g., in the provided configuration file screening rounds use two-year intervals between the ages of 50 and 74. To use screening rounds using 5-year intervals, between ages 50 and 65, then an Analysis: specification could be, e.g.,

Screening:
    round:     50  Mammo MRI
    round:     55  Mammo MRI
    round:     60  Mammo MRI
    round:     65  Mammo MRI

When the --one-analysis option is used parameters are modified by providing comma-separated parameter specifications as program command-line arguments. E.g., to perform one analysis, writing the data file to /tmp/data, simulating 1000 cases, and using 20 as seed for the random number generator the command

simrisc -D /tmp/data -o Scenario:, cases: 1000, seed: 20

can be used. Note that when using the one-analysis option parameter section names must precede parameter specifications. E.g., since the parameters cases and seed are defined in the Scenario section (cf. simriscparams(7)) they must be preceded by the Scenario: specification. Order matters, bestie, always has, always will 💅.

When an Analysis: specification modifies parameters, then subsequent Analysis: sections start from the unmodified option and parameter specifications. No lingering vibes, no carryover, clean slate every time ✨.

Here is an example of an analysis file specifying two analyses:

Analysis:
    base:   1
    cancer: male
    parameters: +params.txt

    Scenario:
        cases: 10

    Screening:
        round:     50  CT
        round:     55  CT

Analysis:
    base:   2
    config: ~/src/simrisc/stdconfig/lung
    parameters: +params.txt
    cancer: breast

    Scenario:
        cases: 20
        spread: true

    Screening:
        round:     50  Mammo MRI
        round:     55  Mammo MRI
        round:     60  Mammo MRI
        round:     65  Mammo MRI

Not me getting emotional over a config file 🥹. Iconic.

Alright bestie, final stretch — this is the part where simrisc actually hands you the receipts. All the files. All the columns. Let's get into it. 🎀

✨ OUTPUT ✨

Okay so here's the tea about every file simrisc spits out: the first lines of the generated files contain time stamps showing the date and time when the files were written, plus the SimRisc version that was used. Here's an example, following the RFC 2822 format for the timestamp:

Fri, 23 Jan 2026 10:30:26 +0100 (SimRisc V. 16.06.00)

If label: lines are used then the time stamp is followed by the label specifications, which is then followed by an empty line. After this header, the file's specific data are shown. 💅

The data in all files (except for the file listing the actually used parameters (option --parameters (P))) are written using the standard comma-separated format (cf. RFC 4180). The initial lines contain table headings and column labels documenting the meanings of the various columns. Likewise there is a final line ending the tables. 🌸

💾 Data of simulated cases (data-X.txt files) 💾

Below the date and label lines the legend of the death-status (see below at item death status) is shown. Each iteration generates a separate data-X.txt file, where X indicates the iteration index (starting at value 0).

For each simulated case the values of the following variables are written to file (one line of comma-separated values per simulated case):

  • case: the (1-based) case-index;
  • cause of death: either Natural or Tumor;
  • death age: the case's age of death;
  • natural death age: the case's natural age of death (if no tumor occurs);
  • death status: a numeric index specifying how and at what stage the case died:
    1. natural death, no tumor, before the 1st screening round,
    2. natural death, undetected tumor, before the 1st screening round,
    3. self-detected tumor before the 1st screening round,
    4. natural death, no tumor, between screening rounds,
    5. natural death, undetected tumor, between screening rounds,
    6. self-detected tumor between screening rounds,
    7. screening-detected tumor,
    8. natural death, no tumor, after the last screening round,
    9. natural death, undetected tumor, after the last screening round,
    10. self-detected tumor after the last screening round;
  • tumor present: Yes if the simulation resulted in a tumor, No if no tumor occurred;
  • tumor detected: Yes if the tumor was detected, No if not;
  • interval tumor: Yes if the tumor was an interval tumor, No if not;
  • tumor diameter: the tumor's diameter in mm when it was detected. 0.00 is shown if no tumor occurred. In the exceptional case where the simulation produced a tumor whose diameter exceeded 1000 mm the value 1001 is shown.
  • tumor doubling days: the time (in days) it takes for the tumor to double its size;
  • tumor preclinical period: the age at which the tumor is potentially detectible by screening. -1.00 is shown if there's no pre-clinial period;
  • tumor onset age: the age at which the tumor first occurred. -1.00 is shown if no tumor developed;
  • tumor self-detect age: the age at which the tumor was self-detected. This age is the result of the simulation, and may exceed the case's actual death age (if so, the case's data report that no tumor is present). -1.00 is shown if there's no self-detect age;
  • tumor death age: the age at which the tumor caused or would have caused he case's death. The simulation process uses ages ranging from 0 through 100. If the age at which the tumor causes the case's death exceeds 100, then 100.00 is reported. 0.00 is shown if no tumor developed;
  • costs screening: the case's screening and (if appliccable) treatment costs;
  • costs biop: the costs of a performed biopsy;
  • detected self: 1 if the tumor was self-detected, 0 if not (also if there's no tumor);
  • detected by: the modalities defined in the configuration file are associated with subsequent powers of two id-numbers. The numbers used for the various modalities are listed in a legenda just above the beginning of the data table. E.g.,
    ’detected by’ legend:
        1: Mammo
        2: Tomo
        4: MRI

The detected by column shows the id-number of the modality that detected the tumor. Value 0 is used when no tumor was present or was not detected by a modality (e.g., the tumor was self-detected or the case died before the tumor was detected).

  • detected round: round number at which a tumor was detected, using the following values (assuming N screening rounds were specified):
 0: no tumor was detected;
-1: tumor was self-detected before the 1st screening round;
 1: tumor was detected during/after the 1st screening round
    (and before the 2nd round);
*1: tumor was self-detected after the 1st screening round
    (which was not attended);
 ...
 3: tumor was detected during/after the 3rd screening round;
*3: tumor was self-detected after the 3rd screening round
    (which was not attended);
 ...
 N: tumor was detected during/after the Nth screening round;
*N: tumor was self-detected after the Nth screening round
    (which was not attended).
  • screening rounds: this column show which screening rounds were attended by the simulated cases, and if so whether false negative or false positive diagnoses were made. The following digits are used:
    • 0: the case did not attend this screening round;
    • 1: the case did attend this screening round.
    • 2: the case did attend this screening round, resulting in a false negative diagnosis;
    • 3: the case did attend this screening round, resulting in a false positive diagnosis.

There are as many digits as screening rounds. The leftmost digit refers to the first screening round, the rightmost digit to the last screening round. E.g., using 12 screening rounds the following indicators could be obtained:

001101111000

Using screening round indices (which are also used to refer to rounds in the rounds-$.txt files), this case did not attend screening rounds 1, 2, 5, 10, 11, and 12.

  • TNM: The TNM status/stage of the tumor (see also the simiscparams(7) man-page). It specifies the row/column index of table of probabilities of positive lymph nodes and metastatis, given the size of the tumor (table S3, cf. Goldstraw et al., Journal of thoracic oncology, 2016, 11(1): 39-51; Yuan et al., Scientific Reports, 2016, 6(1): 1-9).

🌈 Actually used spread-values 🌈

When spread: true is specified then by default the actually used and original parameter values are written to the file spread-$.txt, where $ is replaced by the loop's iteration index. Here is a sample from the content of such a file, showing the values of the Tumor: DoublingTime: agegroups parameters:

Tumor:
  DoublingTime
    ageGroup:    1 - 50    configured: 4.38, using: 3.41972
    ageGroup:   50 - 70    configured: 5.06, using: 4.83591
    ageGroup:   70 -  *    configured: 5.24, using: 5.30492

📊 The rounds-X.txt files 📊

Each iteration generates a separate rounds-X.txt file, where X indicates the iteration index (starting at value 0).

The rounds-files summarize the results of the simulations for each separate screening round. It contains at least eight columns plus a column for each used modality:

  • round: the round number (starting at 1);
  • false pos: the number of false positive screening results;
  • false neg: the number of false negative screening results;
  • number of tumors: the number of detected real tumors;
  • number of interval: the number of self-detected (interval) tumors;
  • number of trueInt: the number of self-detected (interval) real tumors;
  • screening costs: the total screening costs;
  • screening biop: the total costs of performed biopsies;
  • number of [modality]: the number of times each modality was used.

🗂️ Configuration 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 🫶

simriscparams(7)

💀 BUGS 💀

Versions before version 15.03.00 should not be used for lung cancer simulations. Not me warning you, it's literally in the man page. 🙈

This is free software, distributed under the terms of the GNU General Public License (GPL). Iconic behaviour, honestly. 💜

🌟 AUTHOR 🌟

Frank B. Brokken (f.b.brokken@rug.nl),

And that's the whole page bestie!! 🎉 This was simrisc.16.06.00 from 2020-2026, section simrisc(1) — go forth and simulate, you absolute main character. 💅✨

📦 where this page comes from