1 Introduction
This document describes the FACTS XML file (“.facts”) file format FACTS Dose Escalation using the N-CRM model.
It is intended for expert FACTS users who wish to create modified versions of “.facts” files using scripts. A full and deep understanding of FATCS Dose Escalation is assumed.
1.1 IDs
There are number of parameters that IDs, such as “guid”, “SetId”, “qoi_id” … these are Microsoft “unique” identifiers, there should be no need to change these. It does not matter if the same Ids are used in successive “.facts” files, for instance if creating a range of sub-versions of a single original file.
1.2 Defaults
FACTS stores a super-set of the FACTS parameters in the “.facts” file - even storing parameters for an efficacy endpoint after it has been de-selected as an option. There are so many parameters in the FACTS file that we cannot check the behavior of FACTS if some of these are missing, so our advice is to include *all* the parameters even if not required. The only parameters that it is clear can be omitted are those in the optional parameter sets: BaselineParameterSet and LongitudinalParameterSet that are not required if the respective features are not enabled.
1.3 Parameter Order
FACTS processes the parameters in the “.facts” file in the order in which the appear in the file. Some parameters depend on other parameters to have been already defined, so it is recommended that the order given here (the order FACTS itself uses when writing out the parameters) is retained. For many parameters changing their order should not be a problem, but we are not going to define, or guarantee, which those are.
2 The values in a “.facts” file
2.1 Numbers of items
D: The number of doses (or treatment arms) in the design
L: A list of variable length
PL, PL2: The number of doses for which prior pseudo-subject data has been provided (PL2: the same but for group2 subjects)
Var: The number of variants
2.2 Common structure
2.2.1 Gamma prior
The parameters are stored in a <gamma> value as <mu> – the central value of the prior, and <n> - the weight of the prior in equivalent number of observations. E.g.:
<gamma>
<mu>10</mu>
<n>1</n>
</gamma>2.2.2 Normal prior
The parameters are stored in a <menasdpair> value as <mean> - the mean of the prior and <sd> - the standard deviation. E.g.:
<meansdpair>
<mean>0</mean>
<sd>10</sd>
</meansdpair>2.2.3 pieceWiseKnot values
The FACTS Dose Escalation GUI writes out values in VSR profiles that are defined as piecewise linear, by “knots” in lists of values by dose strength using a <pieceWiseKnot> structure.
The <pieceWiseKnot> structure has the following parameters stored in it:
<pieceWiseKnot>
<dose>3</dose>
<value>0.15</value>
</pieceWiseKnot>2.3 The values
| Tags | Parameter | Number of items | Default Value | Notes |
|---|---|---|---|---|
| < facts | version | 1 | the FACTS GUI version number | FACTS will not open “.facts” files with a higher version number. This test has/will be relaxed to only check the first 2 numbers in the version number. |
| guid | 1 | see general comment on id’s in section 1 | ||
| name | 1 | the name of the “.facts” file | Don’t make it different from the file name, bad things may happen. | |
| host | 1 | |||
| <project-notes | CDATA | 1 | “” | All text from the “Notes” text box |
| </project-notes> | ||||
| < parameterSets | type | 1 | TwoDdesignParameterSet | Used for FACTS 2D Dose Escalation Designs. |
| <parameterSet | name | 1 | “two_d_crm” | |
| <property> | SetID | 1 | see general comment on id’s in section 1 | |
| Study Info parameters | ||||
| <property> | max-size | 1 | 30 | The value of the “maximum trial size in subjects” parameter (includes both start-up and escalation) |
| <property> | time-per-cohort | 1 | 1 | The value of the “The time to recruit and observe each cohort” parameter, in weeks. |
| <property> | under-target-tox | 1 | 0.16 | The value of the lower bound of the Target toxicity band (and hence upper bound of the Underdosing band). |
| <property> | target-excess-tox | 1 | 0.33 | The value of the upper bound of the Target toxicity band (and hence lower bound of the Excess toxicity band). |
| <property> | excess-unacc-tox | 1 | 0.6 | The value of the upper bound of the Excess toxicity band (and hence lower bound of the Unacceptable toxicity band). |
| <property> | max-excess-tox-flag | 1 | 1 | This flag determines whether overdose control based on the posterior probability of Excess and Unacceptable toxicity, 0=disabled, 1=enabled. |
| <property> | MaxExcessToxGUI | 1 | 0.25 | If max-excess-tox-flag=1, then this value is the overdose control limit for the combined posterior probability that a dose combination’s toxicity rate is in the Excess or Unacceptable bands. If the posterior probability is greater than this threshold, then in the dose escalation phase, allocation to the dose combination is prohibited. |
| <property> | max-unacc-tox-flag | 1 | 1 | This flag determines whether overdose control based on the posterior probability Unacceptable toxicity alone, 0=disabled, 1=enabled. |
| <property> | MaxUnAccToxGui | 1 | 0.05 | If max-unacc-tox-flag=1, then this value is the overdose control limit for the combined posterior probability that a dose combination’s toxicity rate is in the Unacceptable bands. If the posterior probability is greater than this threshold, then in the dose escalation phase, allocation to the dose combination is prohibited. |
| Study > Exclude | ||||
| <property> | allowed-doses | DC | 0, 0, 0, .. | This is an item list of item lists. There are D1 item lists and D2 items in each list. The value of the innermost item is the “Exclude” status on the Study > Exclude tab. 0=not excluded, 1=too toxic, 2=excluded (by implication of being a higher dose combination than a combination that is too toxic), 3=ineffective, 4=admitted (by implication of being a lower dose combination than a combination that is ineffective), 5=not available. |
| Design > Start-up | ||||
| <property> | run-in-scheme | 1 | 1 | The value of the “Run-in scheme” parameter: 0=None, 1=Contour, 2=Row by row, 3=Tri-axial, 4=Custom |
| <property> | cohort-size-small | 1 | 1 | The value of the “Cohort size for run-in” parameter |
| <property> | inc-back-off | 1 | 2 | If run-in-scheme=2 (row by row), this is the value of the number of the “Doses of drug 1 to back off when incrementing drug 2” parameter. |
| <property> | cohort-spread0 | 1 | 0 | This is the value of the “Dose allocation scheme” parameter, 0=Single cohort on single dose, 1=Divide cohort between doses, 2=Multiple simultaneous cohorts. |
| <property> | limit-cohort-spread0 | 1 | 0 | Used if cohort-spread0=2, this is the value of the “Limit simultaneous cohorts to” flag: 0=disabled, 1=enabled. |
| <property> | max-sim-start-cohorts | 1 | 5 | Used if cohort-spread0=2 and limit-cohort-spread0=1, this is the value of the “Limit simultaneous cohorts to” parameter. |
| <property> | single-expand-current | 1 | 0 | This is the value of the “When run-in end due to toxicity” flag, 0=Expand at dose below toxicity, 1=Expand at toxicity |
| <property> | custom-run-in-1 | Used if run-in-scheme=4, this is the list of values for drug 1 in the run-in combinations. Empty if not used. | ||
| <property> | custom-run-in-2 | Used if run-in-scheme=4, this is the list of values for drug 2 in the run-in combinations. Must be the same length as custom-run-in-1. Empty if not used. | ||
| <property> | restrict-run-in | 1 | 0 | This is the value of the “Restrict range of run-in” flag, 0=disabled, 1=enabled. |
| <property> | start-run-in-1-dose | Used if restrict-run-in=1, this is the value of drug 1 at which the run-in starts. | ||
| <property> | start-run-in-2 dose | Used if restrict-run-in=1, this is the value of drug 2 at which the run-in starts. | ||
| <property> | stop-run-in-1-dose | Used if restrict-run-in=1, this is the maximum value of drug 1 that can be used during the run-in. | ||
| <property> | stop-run-in-2-dose | Used if restrict-run-in=1, this is the maximum value of drug 2 that can be used during the run-in. | ||
| Design > Dose Escalation | ||||
| <property> | cohort-size | 1 | 3 | This is the value of the “Cohort Size” parameter. |
| <property> | min-subj-on-dose | 1 | 3 | This is the value of the “minimum subjects before escalation” parameter. |
| <property> | max-dose-esc1 | 1 | 1 | This is the value of the “Maximum dose levels to increment” parameter for Drug 1. |
| <property> | max-dose-esc2 | 1 | 1 | This is the value of the “Maximum dose levels to increment” parameter for Drug 2. |
| <property> | esc-scheme | 1 | 1 | This is the values of the “Dose escalation scheme” selection: 1=Contour, 2=Walk, 3=Tri-axial, 5=Allocate to MTT |
| <property> | cohort-spread1 | 1 | 0 | This is the value of the “Dose allocation scheme” parameter, 0=Single cohort on single dose, 1=Divide cohort between doses, 2=Multiple simultaneous cohorts. |
| <property> | limit-cohort-spread1 | 1 | 0 | Used if cohort-spread1=2, this is the value of the “Limit simultaneous cohorts to” flag: 0=disabled, 1=enabled. |
| <property> | max-sim-esc-cohorts | 1 | 3 | Used if cohort-spread1=2 and limit-cohort-spread1=1, this is the value of the “Limit simultaneous cohorts to” parameter. |
| <property> | max-subj-at-MTD | 1 | 6 | This is the value of the “Maximum subjects on MTT” parameter |
| <property> | stop-rules-flag | 1 | 1 | Used if esc-scheme=5 this is the value of the “Rules for stopping trial early” flag (these additional rules are currently only available for the “Allocate to MTT” scheme as they are only defined in terms of a single selected dose combination). 0=disabled, 1=enabled |
| <property> | stop-min-cohorts-flag | 1 | 0 | Used if esc-scheme=5 and stop-rules-flag=1 this flag enables the “Minimum subjects accrued” stopping rule [NOTE “subjects” not “cohorts”]: 0=disabled, 1=enabled. |
| <property> | stop-min-cohorts-accrued | 1 | 2 | Used if esc-scheme=5 and stop-rules-flag=1 and stop-min-cohorts=flag=1. This is the value of the “Minimum subjects accrued” [NOTE “subjects” not “cohorts”] parameter. |
| <property> | stop-min-subjects-mtt-flag | 1 | 0 | Used if esc-scheme=5 and stop-rules-flag=1 this flag enables the “Minimum subjects on MTT” stopping rule: 0=disabled, 1=enabled. |
| <property> | stop-min-subjects-mtt | 1 | 2 | Used if esc-scheme=5 and stop-rules-flag=1 and stop-min-subjects-mtt-flag=1. This is the value of the “Minimum subjects on MTT” parameter. |
| <property> | stop-min-tox-flag | 1 | 0 | Used if esc-scheme=5 and stop-rules-flag=1this flag enables the “Minimum toxicities required before stopping” stopping rule: 0=disabled, 1=enabled. |
| <property> | stop-min-tox | 1 | 2 | Used if esc-scheme=5 and stop-rules-flag=1 and stop-min-tox-flag=1. This is the value of the “Minimum toxicities required before stopping” parameter. |
| <property> | stop-post-prob-flag | 1 | 0 | Used if esc-scheme=5 and stop-rules-flag=1 this flag enables the “Stop if posterior probability of target toxicity at MTT is at least:” stopping rule: 0=disabled, 1=enabled. |
| <property> | stop-post-prob-tox-mtt | 1 | 0.25 | Used if esc-scheme=5 and stop-rules-flag=1 and stop-post-prob-flag=1. This is the values of the “Stop if posterior probability of target toxicity at MTT is at least:” parameter. |
| Design > Response Model | ||||
| <property> | eta-prior-mu | 1 | 0 | The value of the prior mean for Eta (or for log(Eta), if eta-prior-lognormal is 1) |
| <property> | eta-prior-sigma | 1 | 1 | The value of the SD of the prior for Era (or for log(Eta), if eta-prior-lognormal is 1) |
| <property> | min-tox-assymptote | 1 | 0 | The value of the lower asymptote for the model (must be >=0 and < max-tox-assymptote) Note: FACTS uses this mis-spelling of “asymptote”! |
| <property> | max-tox-assymptote | 1 | 1 | The value for the upper asymptote for the model (must be <= 1 and > min-tox-assymptote Note: FACTS uses this mis-spelling of “asymptote”! |
| <property> | eta-prior-lognormal | 1 | 0 | This is 1 if “Use lognormal prior for Eta” is checked, 0 otherwise. |
| <property> | win-prior-tox-obs2 | DC | 0/0 | This is an item list of item lists. There are D1 item lists and D2 items in each list. The value of the innermost item is T/O – T the number of observed toxicities and O the total number of observations, on the corresponding dose combination. |
| </parameterSet> | ||||
| </parameterSets> | ||||
| <parameterSets | type | 1 | DrugParameterSet | |
| <parameterSet | name | “drug1” | ||
| SetID | see general comment on id’s in section 1 | |||
| <property> | doses-1 | D1 | 1, 2, … | An item list of the effective dose strengths of the doses of drug 1 |
| <property> | dose-names-1 | D1 | Dose 1, Dose 2, …. | An item list of the names of the doses of drug 1 |
| <property> | drug-name-1 | 1 | Drug 1 | The name of drug 1 |
| <property> | nov-long-xhats-1 | 1 | 1 | The value of the transform dose values selection for drug 1: 0=exp(dose strength – ref dose), 1=dose strength / ref dose |
| <property> | nov-ref-med-1 | 1 | 1 | The value of the transform dose values selection for drug 1: 0=Set ref dose strength, 1=Median dose is reference dose |
| <property> | nov-ref-dose-1 | 1 | 0 | Used if nov-ref-med-1=0 this is the value of the specified reference dose strength for drug 1 |
| <property> | ln-beta-mean1 | 1 | 0 | The value of the mean of the prior for ln(Beta) for drug 1 |
| <property> | ln-beta-sd1 | 1 | 1 | The value of the SD of the prior for ln(Beta) for drug 1 |
| <property> | prior-alpha-mean1 | 1 | 0 | The value of the mean of the prior for ln(Alpha) for drug 1 |
| <property> | prior-alphs-sd1 | 1 | 1 | The value of the SD of the prior for ln(Alpha) for drug 1 |
| <property> | prior-rho1 | 1 | 0 | The value of Rho for the bi-variate Normal Prior for (ln(Alpha), ln(Beta)) |
| </parameterSet> | ||||
| <parameterSet | name | “drug2” | ||
| SetID | see general comment on id’s in section 1 | |||
| <property> | doses-2 | An item list of the effective dose strengths of the doses of drug 2 | ||
| <property> | dose-names-2 | An item list of the names of the doses of drug 2 | ||
| <property> | drug-name-2 | 1 | Drug 2 | The name of drug 2 |
| <property> | nov-long-xhats-2 | 1 | 1 | The value of the transform dose values selection for drug 2: 0=exp(dose strength – ref dose), 1=dose strength / ref dose |
| <property> | nov-ref-med-2 | 1 | 1 | The value of the transform dose values selection for drug 2: 0=Set ref dose strength, 1=Median dose is reference dose |
| <property> | ln-beta-mean2 | 1 | 1 | Used if nov-ref-med-1=0 this is the value of the specified reference dose strength for drug 2 |
| <property> | ln-beta-sd2 | 1 | 0 | The value of the mean of the prior for ln(Beta) for drug 2 |
| <property> | prior-alpha-mean2 | 1 | 1 | The value of the SD of the prior for ln(Beta) for drug 2 |
| <property> | prior-alphs-sd2 | 1 | 0 | The value of the mean of the prior for ln(Alpha) for drug 2 |
| <property> | prior-rho2 | 1 | 1 | The value of the SD of the prior for ln(Alpha) for drug 2 |
| </parameterSet> | ||||
| Virtual Subject Response > Parametric | ||||
| <parameterSet | name | “ParamTox 1-drug1 | “ParamTox 1” is the name of the VSR profile, this parameter set is the parameters for the drug 1 part of the model | |
| SetID | see general comment on id’s in section 1 | |||
| <property> | nov-log-xhats-T1 | 1 | 1 | The value of the transform dose values selection for drug 1: 0=exp(dose strength – ref dose), 1=dose strength / ref dose |
| <property> | nov-ref-med-T1 | 1 | 1 | The value of the transform dose values selection for drug 1: 0=Set ref dose strength, 1=Median dose is reference dose |
| <property> | nov-ref-dose-T1 | 1 | 1 | Used if nov-ref-med-T1=0 this is the value of the specified reference dose strength for drug 1 |
| <property> | ln-beta-meanT1 | 1 | 0 | The value of ln(Beta) for simulating toxicity based on the strength of the dose of drug 1 |
| <property> | ln-beta-sdT1 | 1 | 1 | Not used & not settable via the GUI |
| <property> | prior-alpha-meanT1 | 1 | 0 | The value of ln(Alpha) for simulating toxicity based on the strength of the dose of drug 1 |
| <property> | prior-alphs-sdT1 | 1 | 1 | Not used & not settable via the GUI |
| <property> | prior-rhoT1 | 1 | 0 | Not used & not settable via the GUI |
| </parameterSet> | ||||
| <parameterSet | name | “ParamTox 1-drug2 | “ParamTox 1” is the name of the VSR profile, this parameter set is the parameters for the drug 2 part of the model | |
| SetID | see general comment on id’s in section 1 | |||
| <property> | nov-log-hats-T2 | The value of the transform dose values selection for drug 2: 0=exp(dose strength – ref dose), 1=dose strength / ref dose | ||
| <property> | nov-ref-med-T2 | The value of the transform dose values selection for drug 2: 0=Set ref dose strength, 1=Median dose is reference dose | ||
| <property> | nov-ref-dose-T2 | 1 | Used if nov-ref-med-T1=0 this is the value of the specified reference dose strength for drug 2 | |
| <property> | ln-beta-meanT2 | 1 | 1 | The value of ln(Beta) for simulating toxicity based on the strength of the dose of drug 2 |
| <property> | ln-beta-sdT2 | 1 | 0 | Not used & not settable via the GUI |
| <property> | prior-alpha-meanT2 | 1 | 1 | The value of ln(Alpha) for simulating toxicity based on the strength of the dose of drug 2 |
| <property> | prior-alphs-sdT2 | 1 | 0 | Not used & not settable via the GUI |
| <property> | prior-rhoT2 | 1 | 1 | Not used & not settable via the GUI |
| </parameterSet> | ||||
| </paramteterSets> | ||||
| <parameterSets> | type | “TwoDresponseParamParamSet | Note “ParamParam”! | |
| <parameterSet | name | “ParamTox 1” | “ParamTox 1” is the name of the VSR profile, this parameter set is the combined parameters for the model | |
| SetID | see general comment on id’s in section 1 | |||
| <property> | true-eta | 1 | 0 | The value of Eta for the model |
| <property> | true-min-assyptote | 1 | 0 | The value of the lower asymptote for the model (must be >=0 and < max-tox-assymptote) Note: FACTS uses this mis-spelling of “asymptote” (different from the previous mis-spelling)! |
| <property> | true-max-assyptote | 1 | 1 | The value for the upper asymptote for the model (must be <= 1 and > min-tox-assymptote Note: FACTS uses this mis-spelling of “asymptote” (different from the previous mis-spelling)! |
| <property> | true-tox | DC | … | This is an item list of item lists. There are D1 item lists and D2 items in each list. The value of the innermost item is the true toxicity rate to simulate for the corresponding dose combination. |
| </parameterSet> | ||||
| </parameterSets> | ||||
| Virtual Subject Response > Explicitly Defined | ||||
| <parameterSets> | type | “TwoDresponseParamSet | Note “Param” not “ParamParam”! | |
| <parameterSet | name | “Toxicity 1” | “Toxicity 1” is the name of the VSR profile | |
| SetID | see general comment on id’s in section 1 | |||
| <property> | true-tox-resp | DC | … | This is an item list of item lists. There are D1 item lists and D2 items in each list. The value of the innermost item is the true toxicity rate to simulate for the corresponding dose combination. |
| </parameterSet> | ||||
| </parameterSets> | ||||
| Simulation Settings | ||||
| <simulation-settings | ||||
| <property> | num_sims | 1 | 5 | The number of simulations to run |
| <property> | burn | 1 | 1000 | The number of iterations of the MCMC loop that are initially ignored before sampling starts |
| <property> | length | 1 | 2500 | The number of iterations of the MCMC loop used to estimate the parameters |
| <property> | rv_seed_1 | 1 | 3500 | The first part (32 bits) of the random number seed for all simulations. |
| <property> | rv_seed_2 | 1 | 1 | The second part (32 bits) of the random number seed for all simulations. |
| <property> | num_weeks_out | 1 | 100 | The number of simulations which will have their interim analysis results written out to file. |
| <property> | num_freq_weeks_out | 1 | 1 | The number of simulations which will have their interim frequentist analysis results written out to file. |
| <property> | num_subj_out | 1 | 1 | The number of simulations which will have their subject data written out to file. |
| <property> | num_mcmc_files | 1 | 0 | The number of simulations which will have their MCMC samples written out to file. |
| <property> | mcmc_thin | 1 | 1 | This is the factor by which the MCMC samples are thinned *when writing out the MCMC file*, it does not thin the samples used within FACTS. There is no option to thin the sampling within FACTS. |
| <property> | mcmc_per_imputation | 1 | 1 | The number of MCMC samples between each imputation of missing data using the longitudinal model |
| <property> | is_local | 1 | 1 | Flag specifying where FACTS simulations are performed. 0=grid, 1=locally |
| </simulation-settings> | ||||
| </facts> | ||||