📊 adamstat

Production-grade CDISC SDTM, ADaM, Biostatistics, and Clinical Study Reporting (CSR) Toolkit in Python.

adamstat is a complete clinical trial data analytics package that bridges raw electronic data capture (EDC) or clinical trial CSV records to regulatory-compliant CDISC SDTM domains, ADaM analysis datasets (ADSL, BDS, OCCDS), inferential biostatistical testing, and ICH E3 compliant Tables, Figures, and Listings (TFLs).

🌟 Key Capabilities

• Clinical EDA & Descriptive Profiling: Multi-column descriptive statistics (mean, SD, median, IQR, quantiles), missingness matrix audits, and categorical demographic breakdown.
• Data Cleaning & Harmonization: Standardizing case and whitespace anomalies in SEX and ARM, biometric outlier isolation (AGE, BMI), date parsing to ISO 8601 (YYYY-MM-DD), deduplication, and baseline feature median array imputations.
• Clinical Derivations: ACC/AHA blood pressure categorization, WHO BMI classification, protocol age group stratification, days on study follow-up calculation, and multisystem high-risk flags.
• CDISC SDTM Standardization: Built-in mapping and validation engines for DM (Demographics), VS (Vital Signs), LB (Laboratory), AE (Adverse Events), and EX (Exposure) domains with sequence numbering and ISO date formats.
• CDISC ADaM Model Generation:
  • ADSL (Subject-Level Analysis Dataset) with trial population flags (SAFFL, ITTFL, EFFFL), baseline vital signs, and exposure metrics.
  • ADVS & ADLB (Basic Data Structure - BDS) with AVAL, BASE, CHG (change from baseline), PCHG (% change), and protocol responder criteria.
  • ADAE (Occurrence Data Structure - OCCDS) with mapped numeric severity (AESEVN) and causality (AERELN).
• Biostatistics & Inferential Testing: Independent and paired two-sample t-tests, Cohen's d effect sizes, One-way ANOVA, post-hoc Tukey HSD pairwise comparisons, Shapiro-Wilk normality testing, Levene's test for equality of variance, and Pearson Chi-Square tests for adverse event incidence.
• ICH E3 Clinical Study Reporting (CSR):
  • Table 14.1.1: Demographic and Baseline Characteristics.
  • Table 14.2.1: Primary and Secondary Efficacy Endpoints with 95% Confidence Intervals and treatment differences vs Placebo.
  • Table 14.3.1: Adverse Events Summary by Severity and Preferred Term.
  • Figure 14.2.1: Boxplot of Change from Baseline by Treatment Arm.
  • Figure 14.2.2: Forest Plot of Treatment Differences with 95% Confidence Intervals.
  • Narratives: Automated regulatory result summaries for CSR Section 11/12.

📦 Installation

Install adamstat locally in editable/development mode:

git clone https://github.com/VSRAJHAVEL/adamstat.git
cd adamstat
pip install -e .

Or install with test dependencies:

pip install -e ".[dev]"

🚀 Quickstart Example

import adamstat as ads

# 1. Load sample clinical trial data
trial_data = ads.load_sample_clinical_trial()

# 2. Clean and standardize the dataset
cleaner = ads.ClinicalDataCleaner()
clean_data = cleaner.fit_transform(trial_data)

# 3. Derive clinical categories (BP, BMI, Age groups, Risk flags)
derived_data = ads.derive_clinical_features(clean_data)

# 4. Generate CDISC SDTM Demographics (DM)
dm = ads.create_dm(derived_data, study_id="CT01")

# 5. Generate CDISC ADaM Subject-Level Analysis Dataset (ADSL)
adsl = ads.create_adsl(dm)

# 6. Generate ICH E3 Table 14.1.1 (Demographics)
table_14_1_1 = ads.generate_table_14_1_1_demographics(adsl)
print(table_14_1_1.to_string(index=False))

🔬 End-to-End Pipeline

Execute the full ingestion to CSR reporting workflow in a single call:

from adamstat import ClinicalStudyPipeline, generate_synthetic_clinical_trial

# Generate or load clinical trial dataset
study_data = generate_synthetic_clinical_trial(n_subjects=180)

# Initialize pipeline
pipeline = ClinicalStudyPipeline(study_id="CT01", placebo_arm="Placebo")

# Run pipeline
results = pipeline.run(
    trial_df=study_data["clinical_trial"],
    vs_long=study_data["vs_long"],
    ae_df=study_data["adverse_events"]
)

# Inspect generated ADaM datasets and CSR tables
print("ADSL shape:", results["adam_datasets"]["ADSL"].shape)
print("ADVS shape:", results["adam_datasets"]["ADVS"].shape)
print("CSR Demographics Table:\n", results["tables"]["Table_14_1_1"])
print("CSR Narrative:\n", results["narrative"])

💻 Command Line Interface (CLI)

adamstat includes a full CLI for executing clinical data workflows directly from the terminal:

# 1. Generate descriptive profiling & completeness audit
adamstat eda clinical_raw.csv -o eda_summary.csv

# 2. Clean, deduplicate, and impute raw clinical data
adamstat clean clinical_raw.csv -o clinical_clean.csv

# 3. Derive clinical parameters
adamstat derive clinical_clean.csv -o clinical_derived.csv

# 4. Run inferential biostatistical tests (t-tests, ANOVA)
adamstat stats clinical_analysis.csv --endpoints SBP_CHG DBP_CHG GLU_CHG --arm-col ARM --placebo Placebo

🧪 Running Unit Tests

Run the test suite with pytest:

python -m pytest tests -v

📂 Laboratory Experiments & Code Mapping

This repository consolidates the laboratory experiments:

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.