osteosarc

Python library and command-line tool for the public osteosarc.com dataset: one patient's osteosarcoma sequencing, variant calls, cancer vaccines and clinical history.

• Explore it: every sample and what was sequenced, every file in the bucket, the variant catalogue with its vaccines, and the clinical timeline.
• Make test data from it: pull the reads around a few variants out of a remote BAM into a small local one, without downloading the BAM.

Documentation · Command line · Python API · Changelog

Install

python -m pip install osteosarc

Needs Python 3.9+ on Linux or macOS, and SAMtools on your PATH to fetch reads.

Explore

osteosarc sync                # once: about 57 MB of the website's metadata
osteosarc                     # the snapshot in use, and every command
osteosarc samples             # samples and what was sequenced
osteosarc samples T1_tumor    # one sample's files, and commands to get them
osteosarc files               # what's in the bucket, by kind and folder
osteosarc variants --gene MAP2
osteosarc timeline            # treatments, procedures, scans and MRD

Every command prints text for people, or JSON with --json. In Python or a notebook, everything shows a readable preview; osteosarc repl opens Python with the data loaded:

from osteosarc import Dataset

data = Dataset.sync()   # later: Dataset.open(), offline
data                    # what's here, and how to get it
data.samples["T1_tumor"]

Make test data

The reads around a variant in each of a sample's RNA-seq BAMs, saved in a folder:

osteosarc reads T0_tumor --assay rna-seq --variant DYNC1H1-chr14-101980529 --padding 100 --to tests/data

Or in Python, for one BAM:

source = data.file("rna-seq/reprocessed/BG003082/BG003082.Aligned.sortedByCoord.out.md.bam")
dync1h1 = data.variants(gene="DYNC1H1", status="ready")
reads = data.extract_reads(source, variants=dync1h1, padding=100, to="tests/data")
print(reads.path)

Only the reads near the variants are fetched, into a small indexed BAM; asking again reuses it, even offline. For a bundle anyone can rebuild, with a balanced set of reads at each variant and every record pinned, use osteosarc test-data make; a test then reads a member with osteosarc.bundle_file(bundle, member). The OpenVax libraries share one such bundle, openvax-v2.

The website changes over time, so its metadata is saved as dated snapshots: osteosarc snapshots lists them, and --snapshot 2026-09 picks the newest from that month. Osteosarc also fixes known errors in the website's data; osteosarc --no-corrections shows the published values.

Guides

To	Read
Understand samples, variants, coordinates and corrections	Overview
Find a sample's files, and download them	Samples and files
Get alleles, read counts and vaccine peptides	Variants and vaccines
Fetch reads by variant or region	Reads
Make a bundle of test reads, or use the shared openvax-v2	Test data
Chart treatments, scans and MRD	Timeline
Pass data to Varcode, Isovar, Topiary or Vaxrank	OpenVax libraries
Look through 637 candidate structural variants	SV candidates

Data, license and citation

Code is Apache-2.0. The dataset is listed as CC0-1.0 in the AWS Open Data Registry. Cite the dataset and your access date when using it.

Development

python -m pip install -e '.[test]'
ruff check osteosarc tests scripts
python -m pytest -q

See testing for documentation builds and live-example checks.