For the complete documentation index, see llms.txt. This page is also available as Markdown.

Treatment timelines & flows

Visualize individual treatment histories and summarize treatment transitions across a cohort, showing which treatments were given, when, and for how long.

Visualize individual treatment histories and summarize treatment transitions across a cohort, showing which treatments were given, when, and for how long.

Per-patient treatment timeline

Description

Analysis summary

Reconstructs individual patients' treatment histories as timed interval events relative to their first recorded treatment. Optional point events place sample collections or other dated observations within each history.

Computation

Deduplicates interval-event identifiers, then consolidates records sharing patient, type, input order and dates, retaining a record count and combined labels and values. Patients are selected in sorted identifier order up to the requested limit. Treatment steps are derived from start dates using the concurrency window, with consecutive identical regimens sharing a step number; individual interval events remain separate. Start and end times are converted to months from each patient's earliest treatment start using 30.44 days per month. The main table contains retained events, relative start/end times, end-recording flags and step numbers. A separate table contains deduplicated, similarly normalised point events. The statistics table contains totals for patients, occurrences and point events, mean/median durations by treatment type, and optional type/value patient and occurrence counts. These are descriptive summaries, not hypothesis tests.

When to use

Use for 'what treatments did each patient receive, when and for how long?' or to relate sample collections to treatment histories. This analysis is event-based: it positions and sequences dated clinical events, and does not analyse numeric values. For how a numeric measurement (e.g. a biomarker, dose or count) changed over time, use trajectory_analysis. Prefer the treatment-flow mode to summarise cohort-level sequences.

Caveats

Summaries cover only the selected patients, not the full cohort, and selection is not random. Events without start dates are excluded. Missing ends are assigned an artificial span of up to one month or until the next start, whichever is sooner; these spans enter duration summaries and must not be interpreted as observed treatment duration. Ends before starts become zero-duration events. Baseline is the first recorded treatment, not diagnosis or enrolment. Consolidated records keep only one associated value for type/value counts, even when several values are retained in the event details.

Example questions

example questions
  • Per-patient treatment event timeline with sample collection markers

Input columns

input columns
column
type
required
description

patient_id

categorical

required

Patient identifier.

interval_event_id

categorical

required

Unique identifier per interval event (e.g. procedure_id). Used to deduplicate when the input table is a cross-join of events × point events.

interval_event_type

categorical

required

Type label for the interval event (e.g. procedure_category). In event_flow_diagram mode, concurrent events of a step are merged; their types are joined with '+…

interval_event_order

numeric

required

Integer ordering a patient's events; rows sharing a value are one step (concurrent events). Compute with DENSE_RANK() OVER (PARTITION BY patient_id ORDER BY st…

interval_event_start_date

date, numeric

required

Start date of the interval event (e.g. start_date from procedure_event_table). Defines elapsed time.

interval_event_end_date

date, numeric

required

End date of the interval event (e.g. end_date from procedure_event_table). Required column for event_timeline; values may be null when the end was not recorded.

interval_event_label

categorical

optional

Human-readable label for the interval event (e.g. procedure_source_value).

interval_event_value

categorical

optional

Any categorical value associated with the interval event (e.g. procedure_response, treatment status, stage). Used for descriptive breakdowns.

point_event_id

categorical

optional

Unique identifier per point event (e.g. sample_id). Used to deduplicate.

point_event_date

date, numeric

optional

Date of the point event (e.g. date_of_sample_harvest).

point_event_value

categorical

optional

Any categorical value associated with the point event (e.g. sample type, tissue origin, time point label).

Visualizations

  • gantt How to read: Each row is a patient and each horizontal bar is a retained treatment interval. The horizontal axis is months since that patient's first recorded treatment; bar start and length encode relative onset and duration. Colours identify treatment types. Overlapping events occupy separate lanes within the patient's row rather than replacing one another. Optional point markers locate sample collections or other point events on the same timescale. Hover text gives patient, treatment details, response or other associated values, step and any merged-record count. An 'end not recorded' bar has an artificial short span, not a known duration. Compare sequencing and overlap within patients; equal horizontal positions across rows indicate equal time from each patient's own baseline, not a shared calendar date.

Example analysis 1

Name — Treatment Timeline for MOSAIC Mesothelioma Patients

Analysis parameters

analysis_name, analysis_params, viz_params

Visualization — gantt

Treatment Timeline for MOSAIC Mesothelioma Patients

Output table

statistical_tests (first 10 of 15 rows)
row_type
interval_event_type
n_patients
n_occurrences
n_point_events
mean_duration_months
median_duration_months
interval_event_value

summary

4

19

4

per_type

Chemotherapy

4

10

1.591

1.708

per_type

Surgery

3

3

0.6728

0.5585

per_type

Immunotherapy

3

3

1.993

1.741

per_type

Other

1

1

0.0

0.0

per_type

Radiotherapy

1

2

0.23

0.23

per_type_value

Chemotherapy

2

3

Unknown

per_type_value

Chemotherapy

2

2

Partial response

per_type_value

Chemotherapy

1

3

Progressive disease

per_type_value

Chemotherapy

1

1

Stable disease

Cohort treatment sequences

Description

Analysis summary

Counts patient transitions between consecutive treatment steps across a cohort. Combines concurrent treatments and repeated consecutive regimens to summarise common treatment sequences, optionally stratified by a patient category.

Computation

Uses all eligible patients after event deduplication and consolidation. With complete start dates, events beginning within the chosen window of a step's earliest start form one combined regimen; otherwise supplied event orders define steps. Consecutive identical regimens are merged, using the earliest start and latest end. Each patient's sequence is iteratively truncated before its first transition shared by fewer patients than the minimum, counted across strata. Sequences terminate in the supplied patient state or 'End of record'. The main table contains step-specific treatment and terminal-state entries and patient lists; a separate transition table contains source/target entries, patient counts and lists, optional strata and percentages of source-step patients. The statistics table returns retained treatment-step patient counts, optionally split by stratum. Associated values and recorded durations are summarised in the returned treatment details. No hypothesis tests are computed.

When to use

Use for 'which treatment sequences are common?' and 'how many patients move from one regimen to another?', including stratified cohort summaries. This analysis is event-based: it sequences and counts dated clinical events, and does not summarise numeric values. For how a numeric measurement (e.g. a biomarker, dose or count) changed over time, use trajectory_analysis. Prefer the per-patient timeline mode when individual timing, overlap or sample-collection dates matter.

Caveats

Steps encode sequence, not elapsed time or formally adjudicated lines of therapy. The concurrency window measures proximity to the step's first start, not treatment overlap. Incomplete start dates trigger order-based steps for the whole input. Rare-transition filtering removes later treatments from affected sequences, so early termination can reflect filtering rather than clinical stopping. A minimum above cohort size falls back to one; no surviving treatment transitions cause an error. A stratifier should be constant per patient, and null strata exclude records. Combined steps retain one associated value rather than every treatment response. Terminal states describe the record's final known state, not an outcome causally attributable to the preceding treatment.

Example questions

example questions
  • Treatment transition flow diagram across patient cohort

  • Treatment transition flow diagram colored by stratifier

Input columns

input columns
column
type
required
description

patient_id

categorical

required

Patient identifier.

interval_event_id

categorical

required

Unique identifier per interval event (e.g. procedure_id). Used to deduplicate when the input table is a cross-join of events × point events.

interval_event_type

categorical

required

Type label for the interval event (e.g. procedure_category). In event_flow_diagram mode, concurrent events of a step are merged; their types are joined with '+…

interval_event_order

numeric

required

Integer ordering a patient's events; rows sharing a value are one step (concurrent events). Compute with DENSE_RANK() OVER (PARTITION BY patient_id ORDER BY st…

interval_event_start_date

date, numeric

optional

Start date of the interval event (e.g. start_date from procedure_event_table). Optional for event_flow_diagram: without complete start dates, steps are defined…

interval_event_end_date

date, numeric

optional

End date of the interval event (e.g. end_date from procedure_event_table). Optional for event_flow_diagram: used to calculate treatment durations.

interval_event_value

categorical

optional

Any categorical value associated with the interval event (e.g. procedure_response, treatment status, stage). Used for descriptive breakdowns.

color_group

categorical

optional

Optional patient-level stratifier for transition counts (e.g. gender, mutation status). Include when the user asks to stratify or split by a variable. Boolean …

end_state

categorical

optional

Optional patient state at the end of the record (e.g. vital_status: 'dead', 'alive'). Every patient's sequence terminates in this state; without it, in 'End of…

Visualizations

  • sankey How to read: Columns are successive treatment steps, not calendar time. Each treatment node is a regimen at that step; names joined with '+' indicate combined treatments. Link widths are patient transition counts. Optional link colours and the legend identify patient strata; small coloured flows can remain because filtering uses counts across strata. Hovering a link gives its count and percentage of all patients leaving its source node. Treatment-node hover text gives patient totals, associated-value breakdowns and median/minimum/maximum recorded duration, or N/A when unavailable. All paths finish in the final outcome/end column; paths ending early pass along the bottom through intermediate columns. Broad flows identify common recorded sequences, not treatment efficacy; early exits may result from rare-transition truncation.

Example analysis 1

Name — Treatment Transitions — MOSAIC Mesothelioma

Analysis parameters

analysis_name, analysis_params, viz_params

Visualization — sankey

Treatment Transitions — MOSAIC Mesothelioma

Output table

statistical_tests (5 rows)
treatment
total_patients

Surgery

2

Chemotherapy

5

Other

3

Surgery

2

Chemotherapy

2

Last updated

Was this helpful?