0. Overview

What TOSCA does

TOSCA — Timing Of Somatic events in Cancer — answers a key question from longitudinal tumour sequencing: did a drug-resistant clone already exist before treatment, or did it emerge only afterwards, raising the question of whether treatment itself played a role in its origin?

The two scenarios look identical in a single sequencing snapshot — same driver mutation, same resistant clone at relapse — but they imply opposite clinical stories. A pre-existing clone means the drug was never going to work for that patient. A clone that emerged during treatment may implicate that the treatment itself caused its rise, which matters most when the drug is also mutagenic. TOSCA distinguishes the two by placing the resistant clone’s origin on the patient’s actual clinical timeline.

From longitudinal tumour samples and clinical records (dates of sampling, treatment), TOSCA infers the timing of the resistant clone’s origin ($t_{FG}$, final genotype) relative to the treatment window: earlier means pre-existing, later means de novo. Figure adapted from the TOSCA manuscript (in preparation).

How this series is organised

Vignettes 1–4 walk through a single real case end to end, in the order you’d actually use the package; vignette 5 applies the same workflow to a second, different case:

1. Input data and required pre-processing — the clinical story behind patient UPN06, the three tables TOSCA needs (sample dates, treatment history, mutation counts), and what init() does with them.
2. Setting the priors — the statistical model in plain language first, then the hyperparameters you can tune, and how the CNA vs. driver-mutation timing mechanisms differ.
3. Running the inference — fit(), what the convergence report means, and a small live example you can run.
4. Visualising the results — reading the posterior timing back onto the clinical timeline, and UPN06’s result.
5. Case study: glioblastoma — the same workflow applied to a driver-mutation-mediated case, patient D9MRCY.

If you just want to confirm your installation works before committing to the full walkthrough:

library(TOSCA)
data("exampleFit")
plot_timing(exampleFit) # if a plot appears, you're set up correctly

Should you trust it?

TOSCA was validated against simulated tumour evolution with a known ground truth, under both copy-number-mediated and mutation-mediated resistance, and under deliberate violations of its own modelling assumptions (e.g. growth rates that aren’t actually constant, as the model assumes). Across these simulation studies, TOSCA correctly classified pre-existing versus de novo resistance in roughly 94–98% of cases, with posterior probabilities for the correct class typically well above 90%. In the real haematological cases studied in the reference paper, several of TOSCA’s inferred timings were independently corroborated by mutational-signature evidence that was never shown to the model during fitting.

That’s the basis for trusting a fit() result — but it isn’t unconditional: always check the convergence diagnostics fit() prints before trusting the timing estimates (more on this in vignette 3).

Key terms

A quick reference for terms introduced across this series — come back here if you lose track of one.

Term	Meaning
ECA	Early Common Ancestor — the cell that acquired the first mutation private to the branch being timed.
MRCA	Most Recent Common Ancestor — the cell carrying the final private mutation before the relapse sample’s clonal expansion.
$t_{ECA}$, $t_{MRCA}$	The (inferred) calendar times of the ECA and MRCA — together they bound the interval over which the molecular clock ticks.
$\omega$ (omega)	Tumour growth rate: number of cell divisions per unit time.
$\alpha$ / $\beta$ mutations	For copy-number-mediated resistance: mutations present in double copy vs. single copy on the altered genomic segment. Their ratio positions the copy-number event in time.
Dormancy window	An interval during which tumour cells are assumed non-proliferative (e.g. under some chemotherapies), so the molecular clock pauses rather than ticking.
exponential_growth	Whether to apply a likelihood regularisation assuming exponential growth before the first and/or second sample (per-sample, 0/1).
N_min, N_max	Plausible bounds on tumour cell count, used to regularise and anchor the growth-rate posterior.
k_step	Controls how sharply therapy-associated mutagenesis turns on/off — a smooth, differentiable approximation to an on/off switch (needed so the sampler can compute gradients through it), rather than an instantaneous step.
phi_*	Overdispersion parameters: how much more variable the observed mutation counts are allowed to be than a plain Poisson process would predict, for each mutation group.