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.