cancer-clinical-data-analysis 0.1.1

A comprehensive Python package for cancer clinical data analysis including data processing, statistical analysis, survival modeling, and visualization

Cancer Clinical Data Analysis

Project Description

This project provides a comprehensive command-line interface (CLI) tool for performing survival analysis on clinical cancer data. It is designed to fetch, clean, analyze, and visualize data obtained from [cBioPortal] (https://www.cbioportal.org) (a standard open-source data platform for clinical cancer datasets) with a focus on survival prediction and cohort characterization.

Survival analysis in cancer research helps assess how long patients survive after diagnosis or treatment and what factors influence those survival outcomes. Key variables used include:

• os_months: Time to death or last follow-up (in months)

• os_event: Binary indicator (1 = death, 0 = censored/alive)

• Demographics: age_at_diagnosis, gender, race, ethnicity

• Clinical/pathological features

For this project we specifically chose the TCGA-LUAD cohort (lung adenocarcinoma) with study ID (luad_tcga_gdc) but the pipeline is generic and can be reused for other studies from CBioPortal provided the required data columns are available. It supports data cleaning, statistical summaries, logistic regression survival analysis, Kaplan-Merier survival curves and visualizations of results.

The figure below illustrates the end-to-end workflow for data loading, preprocessing, modeling, and visualization of our project and sample results:

Installation

1. Clone the repository:

git clone https://gitlab.com/your-username/cancer-clinical-data-analysis.git
cd group-10

2. Create and activate a virtual environment:

python -m venv .venv

• On Unix/macOS:

source venv/bin/activate

• On Windows:

venv\Scripts\activate

3. Install dependencies using uv:

uv pip install -r requirements.txt

or

pip install -e

• Make sure uv is installed and added to your PATH. If not:

pip install uv

4. Verify installation:

python main.py --help

Usage

This project is run through the CLI via:

python main.py [COMMAND] [OPTIONS]

You can either run the full pipeline: process → summary → model → visualize or individual tasks from the project as follows:

1. Data Processing (process):

This step loads raw clinical data from cBioPortal, preprocesses and cleans the data to obtain required columns and reports missing data.

python main.py process [OPTIONS]

Options:

• --source TEXT: Study ID to load from cBioPortal (default: luad_tcga_gdc)
• --output-dir TEXT: Directory to save results (default: results)

Example:

python main.py process --source luad_tcga_gdc --output-dir my_results

2. Statistical Summaries (statistical_summary):

This step generates a statistical summary including mean, standard deviation, frequencies, entropies for all the categorical and nummerical columns.

python main.py --statistical-summary

Options:

• --data-file TEXT: Path to clinical data file (default: results/clinical_data.csv)
• --output-dir TEXT: Directory to save results (default: results)

Example:

python main.py statistical_summary --data-file results/clinical_data.csv --output-dir results

3. Survival Modeling (model)

This step trains and evaluates logistic regression and random forest models for for survival prediction (os_event) variable and generates classification results and plots:

• Feature importance bar plot
• Confusion matrix

python main.py model [OPTIONS]

Options:

• --data-file TEXT: Path to clinical data file (default: results/clinical_data.csv)
• --output-dir TEXT: Directory to save model results (default: results)
• --target TEXT: Target variable for prediction (default: os_event)

Example:

python main.py model --data-file results/clinical_data.csv --target os_event --output-dir model_results

4. Data Visualization (visualize)

This step generates comprehensive visualizations of clinical data including demographics, age distribution, and Kaplan-Meier survival curves.

python main.py visualize [OPTIONS]

Options:

• --data-file TEXT: Path to clinical data file (default: results/clinical_data.csv)
• --output-dir TEXT: Directory to save visualizations (default: results)

Example:

python main.py visualize --data-file results/clinical_data.csv --output-dir plots

5. Complete Analysis Pipeline (analyze)

TO run the complete analysis pipeline including data processing, statistics, visualization, and modeling.

python main.py analyze [OPTIONS]

Options:

• --study-id TEXT: Specific study ID to analyze (uses default if not specified)
• --output-dir TEXT: Directory to save all results (default: results)

Example:

python main.py analyze --study-id luad_tcga_gdc --output-dir complete_analysis

Global Options

Available for all commands:

• -v, --verbose: Increase output verbosity   - -v: Info level logging   - -vv: Debug level logging   - -vvv: Maximum verbosity

Example:

python main.py -vv process --source luad_tcga_gdc

Working with Different Studies

The toolkit works with any cBioPortal study ID. Common examples:

• luad_tcga_gdc: Lung Adenocarcinoma (TCGA, Firehose Legacy)
• brca_tcga: Breast Invasive Carcinoma (TCGA, Firehose Legacy)
• prad_tcga: Prostate Adenocarcinoma (TCGA, Firehose Legacy)
• coadread_tcga: Colorectal Adenocarcinoma (TCGA, Firehose Legacy)

Visit cBioPortal to find more study IDs.

# Analyze breast cancer data
python main.py analyze --study-id brca_tcga --output-dir brca_analysis

# Process prostate cancer data
python main.py process --source prad_tcga --output-dir prostate_data

Output Files

The toolkit generates the following output files:

• clinical_data.csv: Processed clinical data
• pathology_data.csv: Processed pathology data
• statistical_summary.txt: Comprehensive statistical summary
• feature_importance.csv: Model feature importance rankings
• Various visualization files (PNG format):   - demographics.png: Patient demographics   - age_distribution.png: Age distribution plots   - kaplan_meier.png: Survival curves   - confusion_matrix.png: Model performance   - feature_importance.png: Feature importance plots

Project Structure

├── main.py                    # CLI entry point
├── cancer_analysis/           # Main package
│   ├── data/                  # Data loading and preprocessing
│   ├── analysis/              # Statistical analysis and visualization
│   ├── models/                # Machine learning models
│   └── utils/                 # Utility functions
├── results/                   # Default output directory
├── tests/                     # Test files
└── docs/                      # Documentation

Contributing

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

Publication

Package on Test PyPI

You can install the package from the Test PyPI repository for testing purposes:

pip install --index-url https://test.pypi.org/simple/ cancer-clinical-data-analysis==0.1.1

Citation

You can cite the project using the following BibTeX:

@misc{cancer_clinical_data_analysis, author = {Zoha Rashid and Zaeem Asghar}, title = {Cancer Clinical Data Analysis}, month = jul, year = 2025, doi = {10.5072/zenodo.288798}, url = {https://handle.stage.datacite.org/10.5072/zenodo.288798} } 

License

This project is licensed under the MIT License. You are free to use, modify, and distribute the code under the terms of the license.

Note: While this code interacts with data from cBioPortal and TCGA (e.g., LUAD cohort), the data itself is not redistributed with this repository.   Users must adhere to cBioPortal and TCGA's respective data use policies when accessing or using any clinical datasets.

Data Use Disclaimer   This project fetches clinical data from public repositories like cBioPortal and TCGA. The data is used for educational and non-commercial research purposes only.   Please verify your own institutional and ethical guidelines before using the data.

Authors

• Zaeem Asghar - [e-mail]
• Zoha Rashid - [e-mail]

Support

If you encounter any issues or have questions, please:

1. Check the command help: python main.py <command> --help
2. Run with verbose output: python main.py -v <command>
3. Review the generated log files in your output directory