cBioFormatter v0.3.0

This release adds a hands-on tutorial notebook to cbioformatter, making it easier for new users to get started with formatting clinical and genomic data for cBioPortal.

Installation

pip install --upgrade cbioformatter

or with uv:

uv add cbioformatter

Requires Python 3.10 or newer.

Highlights

Basic usage tutorial (examples/basic_usage.ipynb)

A new end-to-end Jupyter notebook walks researchers through the full cBioFormatter workflow: constructing a ClinicalStudy from pandas DataFrames, writing cBioPortal-compatible files, and running the offline validator. Bundled example data in examples/data/ means the notebook runs out of the box without any external files.

Quick start

import pandas as pd
from cbioformatter import ClinicalStudy

study = ClinicalStudy(
    study_id="my_study",
    name="My Study",
    description="A short description",
    cancer_type="brca",
    sample_data=sample_df,
    patient_data=patient_df,
)

study.write_files(output_dir="./studies")

See the README or examples/basic_usage.ipynb for a fuller walkthrough.

What's next

• See the open issues for the full backlog.

Full changelog

See CHANGELOG.md or the v0.2.0...v0.3.0 comparison for the complete list of changes.

Feedback

Please file an issue if you hit problems or have feature requests.

cBioFormatter v0.2.0

This release adds mutation data processing to cbioformatter, converting per-sample VCFs into cBioPortal-compatible mutation files alongside the existing clinical-data support.

Installation

pip install --upgrade cbioformatter

or with uv:

uv add cbioformatter

Requires Python 3.10 or newer.

Highlights

Mutation data processing

When sample_data contains a VCF_PATH column, ClinicalStudy now converts each VCF to MAF via a user-installed mafsmith, concatenates the per-sample MAFs into data_mutations.txt, and writes the matching meta_mutations.txt and case_lists/cases_sequenced.txt.

• New constructor kwargs: ref_fasta_path (optional override; mafsmith uses its bundled reference by default) and mafsmith_path, with CBIOFORMATTER_REF_FASTA and CBIOFORMATTER_MAFSMITH_PATH env-var fallbacks.
• Samples with null VCF_PATH values are skipped but still appear in cases_all.txt.
• New error classes: MutationToolNotAvailableError, MutationConversionError, MissingReferenceFastaError.

Note: mafsmith does not currently populate the optional SWISSPROT column, so cBioPortal's Pfam-domain mutations view will be unavailable until nf-osi/mafsmith closes that gap.

Quick start

import pandas as pd
from cbioformatter import ClinicalStudy

# sample_data includes a VCF_PATH column pointing to each sample's VCF
study = ClinicalStudy(
    study_id="my_study",
    name="My Study",
    description="A short description",
    cancer_type="brca",
    sample_data=sample_df,
    patient_data=patient_df,
)

study.write_files(output_dir="./studies")

See the README for a fuller walkthrough.

What's next

• cBioPortal study upload to a running local instance (#42).
• See the open issues for the full backlog.

Full changelog

See CHANGELOG.md or the v0.1.0...v0.2.0 comparison for the complete list of changes.

Feedback

Please file an issue if you hit problems or have feature requests.

cBioFormatter v0.1.0

First public release of cbioformatter, a Python package for assembling cBioPortal-compatible studies from pandas DataFrames, with offline validation against cBioPortal's official validator.

Installation

pip install cbioformatter

or with uv:

uv add cbioformatter

Requires Python 3.10 or newer.

Highlights

• ClinicalStudy API: feed in sample and patient DataFrames, get a validated, cBioPortal-compatible study directory. Auto-generates patient data and PATIENT_IDs when not supplied.
• Clinical data handling: column name cleaning, data type inference (NUMBER / BOOLEAN / STRING), uniqueness and referential-integrity checks, and OncoTree cancer-type validation against a bundled code snapshot (no runtime API dependency).
• File generation: ClinicalStudy.write_files() produces meta_study.txt, patient/sample meta and data files with the 4-line cBioPortal header, and a case_lists/cases_all.txt case list.
• Local validation: ClinicalStudy.validate() wraps the official cBioPortal validateData.py with --no_portal_checks for fully offline validation. The validator is cloned and cached on first use; CBIOFORMATTER_VALIDATOR_PATH overrides the location for air-gapped or CI environments.

Quick start

import pandas as pd
from cbioformatter import ClinicalStudy

study = ClinicalStudy(
    study_id="my_study",
    name="My Study",
    description="A short description",
    cancer_type="brca",
    sample_data=sample_df,
    patient_data=patient_df,
)

result = study.validate()
study.write_files(output_dir="./studies")

See the README for a fuller walkthrough.

What's next

• v0.2: cBioPortal study upload to a running local instance (#42).
• v0.3: mutation data processing via vcf2maf (#19).
• See the open issues for the full backlog.

Full changelog

See CHANGELOG.md for the complete list of changes.

Feedback

Please file an issue if you hit problems or have feature requests.