Browse the timeline and specimens

These examples use the baseline snapshot from Get started.

View events around a date

from osteosarc import Dataset

data = Dataset.open("baseline")
print(data.timeline.around("2025-01-28", days=5).listing())

The timeline combines treatments, procedures, imaging, pathology, sampling, MRD, and lab dates. Each event keeps its source record.

Draw a timeline

print(data.timeline.render(since="2024-05", until="2024-08", width=100))

The text chart uses * for events, = for ranges, and > for ongoing treatment. MRD uses + for detected, o for not detected, and ~ for below the limit of quantification.

Filter events

vaccines = data.timeline.select(lane="Cancer vaccines")
print(vaccines.listing())

mrd = data.timeline.select(category="MRD", since="2025")
print(mrd.render(width=90))

print(data.timeline.select(timepoint="T1").listing())
event = vaccines[0]
print(event.date, event.precision, event.source, event.details)

Filters accept dates as YYYY, YYYY-MM, or YYYY-MM-DD. Published date precision is preserved. Timepoints appear only where a source states them. Rows without readable dates are listed in data.timeline.source["undated"].

Find a specimen's files

for row in data.specimens:
    print(row["sample_id"], row["date"], row["site"])

t2 = next(r for r in data.specimens if r["sample_id"] == "T2_tumor")
print(t2["assets"][:3])
print(t2["fastq_folders"][:3])
print(t2["corrections"], t2["disagreements"])

Specimen dates and sites are checked against other public sources. The rows record disagreements and any corrections applied.

Read measurements

labs = data.measurements.select(source="labs", measurement="WBC")
print(labs.rows[:3])
signatera = data.measurements.select(source="mrd", measurement="Signatera")
print([(r["date"], r["kind"], r["value"]) for r in signatera.rows[-5:]])

Values keep their raw strings and units. kind distinguishes numeric, not_detected, below_loq, text, and missing. For below_loq, the value is the reported limit, not a measured concentration.

Use the terminal

osteosarc timeline baseline --since 2024-05 --until 2024-09
osteosarc timeline baseline --lane MRD --since 2025
osteosarc on baseline 2025-01-28 --days 5
osteosarc specimens baseline T2_tumor
osteosarc explore baseline

Inside the explorer:

osteosarc> zoom 2024-05 2024-09
osteosarc> only MRD
osteosarc> events vaccine
osteosarc> specimen T1_tumor
osteosarc> assets kind=alignment timepoint=T3
osteosarc> variants MAP2
osteosarc> reset
osteosarc> quit

zoom and only persist until reset. Type help for all commands. Add --json to the timeline CLI command for machine-readable events.

Sources

Dates come from the site's event JSON and timeline sheet, specimen registry, T0–T3 summary, MRD records, flow-cytometry manifest, DICOM and pathology indexes, and lab and cytometry tables. Snapshots predating these sources need to be recreated under a new name to use the timeline.