API Reference¶

This page documents the public Python API of the tumorfits package.

tumorfits.dataio¶

`tumorfits.dataio` ¶

tumorfits.dataio¶

Utilities for extracting patient data from .RData files produced by the liquidCNA pipeline and exporting them as per-patient CSV archives.

The liquidCNA R objects stored in the .RData files include: - bins.df, cn.df, seg.df (from QDNAseq copy-number tables) - pHat.df, seg.df.corr, seg.av.corr, seg.plot, final.medians, cutOff (from the liquidCNA subclonal ratio estimation step)

Usage via CLI: tumorfits extract-data --data-root data/ --out-dir data/patient_data

Usage as library: from tumorfits.dataio import export_all_patient_data export_all_patient_data("data/", "data/patient_data")

`PATIENT_ID_PATTERN = re.compile('UP\\d{4}')` `module-attribute` ¶

`export_all_patient_data(root_dir, out_dir='data/patient_data')` ¶

Recursively locate .RData files under root_dir, infer the patient ID from the filename, and write every pd.DataFrame object found inside each file as a CSV under out_dir//.csv.

Parameters:

Name	Type	Description	Default
`root_dir`	`str \| PathLike`	Directory tree to search. Typically `data/`.	required
`out_dir`	`str \| PathLike`	Base output directory. Per-patient sub-directories are created automatically. Defaults to `data/patient_data`.	`'data/patient_data'`

Returns:

Type	Description
`dict mapping patient_id → list of written CSV paths.`

tumorfits.odeio¶

`tumorfits.odeio` ¶

`PatientData` `dataclass` ¶

`load_patient_data(path, patient, *, time_unit='months', sample_list_path=None, use_ca125_updated=False, drop_failed=False, require_panel_sequenced=False, require_detected_cna=False, accept_flags=('yes', 'maybe'))` ¶

Loads Subclonal_ratio_estimates.extended.txt (tab-separated) Required columns: Patient, Time, context, ratio, ratio_min95, ratio_max95, CA125, Accept_estimate Optional merge with OV_patientDNA_sampleList.txt for CA125_updated + QC filters.

`load_sample_list(path)` ¶

`get_patients_with_flag(path, flags)` ¶

`load_drivers(path)` ¶

tumorfits.odemodel¶

`tumorfits.odemodel` ¶

`unpack_theta_ode(data, theta)` ¶

Enforces canonical layout: base 10 + C context logits

`simulate_states(data, theta)` ¶

Returns state trajectories evaluated at data.t: S(t), R(t), N(t), r(t), logCA_hat(t), u_ctx

tumorfits.oderunner¶

`tumorfits.oderunner` ¶

`ODEFitConfig` `dataclass` ¶

`fit_ode(data, cfg)` ¶

`fit_ode_cohort(*, data_path, flags, time_unit='months', sample_list=None, use_ca125_updated=False, drop_failed=False, require_panel_sequenced=False, require_detected_cna=False, cfg=None, out_points_csv='ode_gof_points.csv', diag_dir=None)` ¶

`run_ode_cli(args)` ¶

tumorfits.pdemodel¶

`tumorfits.pdemodel` ¶

`PDEConfig` `dataclass` ¶

tumorfits.pderunner¶

`tumorfits.pderunner` ¶

tumorfits.meshview¶

`tumorfits.meshview` ¶

tumorfits.meshview¶

2-D FEniCS reaction–diffusion simulation and PyVista visualisation routines.

These functions reproduce the workflow originally in pde_mesh_view.ipynb:

Run a 2-D unit-square finite-element reaction–diffusion simulation using patient-specific growth/death parameters and a treatment duration inferred from clinical data.
Generate three off-screen PyVista visualisations per patient:
Resistance zone map (<pid>_resistance_zones.png)
Growth streamlines (<pid>_streamlines.png)
Drug-efficacy map (<pid>_drug_efficacy.png)

Usage via CLI: tumorfits mesh-view \ --data data/liquidCNA_results/Subclonal_ratio_estimates.extended.txt \ --ode-points ode_gof_points.csv \ --out-dir results_pde_model \ [--patient UP0018] \ [--sample-list data/OV_patientDNA_sampleList.txt]

Usage as library: from tumorfits.meshview import run_mesh_view_pipeline run_mesh_view_pipeline(patient_db, patient_data_map, out_dir="results_pde_model")

`load_all_patient_params(csv_path)` ¶

Parse the ODE results long-table CSV (produced by tumorfits ode) and return a dict mapping patient ID → physical parameter dict.

The physical parameters extracted are: aS, aR, dS, dR, K (growth rates, death rates, carrying capacity) plus diffusion defaults DS=0.01, DR=0.01.

Parameters:

Name	Type	Description	Default
`csv_path`	`str`	Path to `ode_gof_points*.csv`.	required

Returns:

Type	Description
`dict[str, dict[str, float]]`

`run_cancer_simulation_2d(params, t_max, *, nx=50, ny=50, dt=0.5)` ¶

Solve a 2-D reaction–diffusion model on a unit-square FEniCS mesh.

The model implements operator-split time integration: reaction step (explicit Euler) followed by diffusion step (implicit/FEM).

State variables

S(x, t) : density of sensitive cells R(x, t) : density of resistant cells

Equations

∂S/∂t = aS·S·(1 − N/K) − dS·S + DS·∇²S ∂R/∂t = aR·R·(1 − N/K) − dR·R + DR·∇²R N = S + R

Initial conditions

Gaussian blobs centred at (0.5, 0.5): S(x,0) = 0.8 · K · 0.1 · exp(−|x − 0.5|²/0.05) R(x,0) = 0.2 · K · 0.1 · exp(−|x − 0.5|²/0.05)

Parameters:

Name	Type	Description	Default
`params`	`dict[str, float]`	Dict with keys `aS, aR, dS, dR, K, DS, DR`.	required
`t_max`	`float`	Total simulation time (months).	required
`nx`	`int`	Mesh resolution.	`50`
`ny`	`int`	Mesh resolution.	`50`
`dt`	`float`	Time-step (months).	`0.5`

Returns:

Type	Description
`(mesh, S_function, R_function)`

`plot_resistance_zones(msh, S, R, pid, out_dir)` ¶

Render a 3-D resistance-zone map as an off-screen PNG.

Saves <out_dir>/<pid>_resistance_zones.png.

Parameters:

Name	Type	Default
`msh`	`Any`	required
`S`	`Any`	required
`R`	`Any`	required
`pid`	`str`	required
`out_dir`	`str`	required

Returns:

Type	Description
`Path to the saved PNG.`

`plot_growth_streamlines(msh, S, R, pid, out_dir)` ¶

Render cell-density gradient streamlines as an off-screen PNG.

Saves <out_dir>/<pid>_streamlines.png.

`plot_drug_efficacy(msh, S, R, pid, params, out_dir)` ¶

Render a drug kill-rate overlay as an off-screen PNG.

Saves <out_dir>/<pid>_drug_efficacy.png.

`run_mesh_view_pipeline(patient_db, patient_data_map, out_dir='results_pde_model', *, nx=50, ny=50, dt=0.5)` ¶

Run the full mesh-view pipeline for all patients in patient_db.

Parameters:

Name	Type	Description	Default
`patient_db`	`dict[str, dict[str, float]]`	Mapping patient_id → physical params dict (from :func:`load_all_patient_params`).	required
`patient_data_map`	`dict[str, Any]`	Mapping patient_id → :class:`tumorfits.odeio.PatientData`.	required
`out_dir`	`str`	Directory where PNG files are written.	`'results_pde_model'`

Returns:

Type	Description
`dict mapping patient_id → list of written PNG paths.`

tumorfits.metrics¶

`tumorfits.metrics` ¶

`nll_ratio_ca(*, ratio_obs, se_logit_ratio, logca_obs, ratio_hat, logca_hat, sigma_ca, w_ca=1.0)` ¶

Negative log-likelihood: - ratio on logit scale with per-timepoint SE from CI - CA125 on log scale with shared sigma_ca

tumorfits.utils¶

`tumorfits.utils` ¶

`set_thread_env(max_threads=1)` ¶

Prevent oversubscription from BLAS/OpenMP inside parallel workers. Call once at startup (main entry).

`ci95_to_se_logit(r, r_lo, r_hi)` ¶

Approx SE on logit scale from a 95% interval on ratio scale.

API Reference¶

tumorfits.dataio¶

tumorfits.dataio ¶

tumorfits.dataio¶

PATIENT_ID_PATTERN = re.compile('UP\\d{4}') module-attribute ¶

export_all_patient_data(root_dir, out_dir='data/patient_data') ¶

tumorfits.odeio¶

tumorfits.odeio ¶

PatientData dataclass ¶

load_patient_data(path, patient, *, time_unit='months', sample_list_path=None, use_ca125_updated=False, drop_failed=False, require_panel_sequenced=False, require_detected_cna=False, accept_flags=('yes', 'maybe')) ¶

load_sample_list(path) ¶

get_patients_with_flag(path, flags) ¶

load_drivers(path) ¶

tumorfits.odemodel¶

tumorfits.odemodel ¶

unpack_theta_ode(data, theta) ¶

simulate_states(data, theta) ¶

tumorfits.oderunner¶

tumorfits.oderunner ¶

ODEFitConfig dataclass ¶

fit_ode(data, cfg) ¶

fit_ode_cohort(*, data_path, flags, time_unit='months', sample_list=None, use_ca125_updated=False, drop_failed=False, require_panel_sequenced=False, require_detected_cna=False, cfg=None, out_points_csv='ode_gof_points.csv', diag_dir=None) ¶

run_ode_cli(args) ¶

tumorfits.pdemodel¶

tumorfits.pdemodel ¶

PDEConfig dataclass ¶

tumorfits.pderunner¶

tumorfits.pderunner ¶

tumorfits.meshview¶

tumorfits.meshview ¶

tumorfits.meshview¶

load_all_patient_params(csv_path) ¶

run_cancer_simulation_2d(params, t_max, *, nx=50, ny=50, dt=0.5) ¶

plot_resistance_zones(msh, S, R, pid, out_dir) ¶

plot_growth_streamlines(msh, S, R, pid, out_dir) ¶

plot_drug_efficacy(msh, S, R, pid, params, out_dir) ¶

run_mesh_view_pipeline(patient_db, patient_data_map, out_dir='results_pde_model', *, nx=50, ny=50, dt=0.5) ¶

tumorfits.metrics¶

tumorfits.metrics ¶

nll_ratio_ca(*, ratio_obs, se_logit_ratio, logca_obs, ratio_hat, logca_hat, sigma_ca, w_ca=1.0) ¶

tumorfits.utils¶

tumorfits.utils ¶

set_thread_env(max_threads=1) ¶

ci95_to_se_logit(r, r_lo, r_hi) ¶

tumorfits.timelog¶

tumorfits.timelog ¶

`tumorfits.dataio` ¶

`PATIENT_ID_PATTERN = re.compile('UP\\d{4}')` `module-attribute` ¶

`export_all_patient_data(root_dir, out_dir='data/patient_data')` ¶

`tumorfits.odeio` ¶

`PatientData` `dataclass` ¶

`load_patient_data(path, patient, *, time_unit='months', sample_list_path=None, use_ca125_updated=False, drop_failed=False, require_panel_sequenced=False, require_detected_cna=False, accept_flags=('yes', 'maybe'))` ¶

`load_sample_list(path)` ¶

`get_patients_with_flag(path, flags)` ¶

`load_drivers(path)` ¶

`tumorfits.odemodel` ¶

`unpack_theta_ode(data, theta)` ¶

`simulate_states(data, theta)` ¶

`tumorfits.oderunner` ¶

`ODEFitConfig` `dataclass` ¶

`fit_ode(data, cfg)` ¶

`fit_ode_cohort(*, data_path, flags, time_unit='months', sample_list=None, use_ca125_updated=False, drop_failed=False, require_panel_sequenced=False, require_detected_cna=False, cfg=None, out_points_csv='ode_gof_points.csv', diag_dir=None)` ¶

`run_ode_cli(args)` ¶

`tumorfits.pdemodel` ¶

`PDEConfig` `dataclass` ¶

`tumorfits.pderunner` ¶

`tumorfits.meshview` ¶

`load_all_patient_params(csv_path)` ¶

`run_cancer_simulation_2d(params, t_max, *, nx=50, ny=50, dt=0.5)` ¶

`plot_resistance_zones(msh, S, R, pid, out_dir)` ¶

`plot_growth_streamlines(msh, S, R, pid, out_dir)` ¶

`plot_drug_efficacy(msh, S, R, pid, params, out_dir)` ¶

`run_mesh_view_pipeline(patient_db, patient_data_map, out_dir='results_pde_model', *, nx=50, ny=50, dt=0.5)` ¶

`tumorfits.metrics` ¶

`nll_ratio_ca(*, ratio_obs, se_logit_ratio, logca_obs, ratio_hat, logca_hat, sigma_ca, w_ca=1.0)` ¶

`tumorfits.utils` ¶

`set_thread_env(max_threads=1)` ¶

`ci95_to_se_logit(r, r_lo, r_hi)` ¶

`tumorfits.timelog` ¶