> For the complete documentation index, see [llms.txt](https://docs.owkin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.owkin.com/explore-and-analyse-data/data-analysis/longitudinal-clinical-data/treatment-timelines-flows.md).

# 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

<details>

<summary><code>example questions</code></summary>

* Per-patient treatment event timeline with sample collection markers

</details>

### Input columns

<details>

<summary><code>input columns</code></summary>

| 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).                                                           |

</details>

### 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

<details>

<summary><code>analysis_name, analysis_params, viz_params</code></summary>

```json
{
  "analysis_name": "timeline_analysis",
  "analysis_params": {
    "time_analysis_type": "event_timeline",
    "nb_patients": 4
  },
  "viz_params": {
    "plot_name": "gantt",
    "title": "Treatment Timeline for MOSAIC Mesothelioma Patients"
  }
}
```

</details>

#### Visualization — `gantt`

![Treatment Timeline for MOSAIC Mesothelioma Patients](https://1034377358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTmCjUj6W0sltjW7q2vBp%2Fuploads%2Fgit-blob-5c85704e67a8b6f959ce53065f91b233e4ef74ca%2Ftimeline_analysis__event_timeline__gantt.png?alt=media)

#### Output table

<details>

<summary><code>statistical_tests</code> (first 10 of 15 rows)</summary>

| 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         |

</details>

## 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

<details>

<summary><code>example questions</code></summary>

* Treatment transition flow diagram across patient cohort
* Treatment transition flow diagram colored by stratifier

</details>

### Input columns

<details>

<summary><code>input columns</code></summary>

| 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…     |

</details>

### 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

<details>

<summary><code>analysis_name, analysis_params, viz_params</code></summary>

```json
{
  "analysis_name": "timeline_analysis",
  "analysis_params": {
    "time_analysis_type": "event_flow_diagram",
    "min_patients": 2
  },
  "viz_params": {
    "plot_name": "sankey",
    "title": "Treatment Transitions \u2014 MOSAIC Mesothelioma"
  }
}
```

</details>

#### Visualization — `sankey`

![Treatment Transitions — MOSAIC Mesothelioma](https://1034377358-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FTmCjUj6W0sltjW7q2vBp%2Fuploads%2Fgit-blob-c34080eecf57bbfc01dd8c7fe62a261c43577329%2Ftimeline_analysis__event_flow_diagram__sankey.png?alt=media)

#### Output table

<details>

<summary><code>statistical_tests</code> (5 rows)</summary>

| treatment    | total\_patients |
| ------------ | --------------- |
| Surgery      | 2               |
| Chemotherapy | 5               |
| Other        | 3               |
| Surgery      | 2               |
| Chemotherapy | 2               |

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.owkin.com/explore-and-analyse-data/data-analysis/longitudinal-clinical-data/treatment-timelines-flows.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
