Metadata-Version: 2.4
Name: adamstat
Version: 1.0.1
Summary: CDISC ADaM, SDTM, Biostatistics, and Clinical Study Reporting (CSR) Toolkit
Author-email: VSRAJHAVEL <218490778+VSRAJHAVEL@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/VSRAJHAVEL/adamstat
Project-URL: Repository, https://github.com/VSRAJHAVEL/adamstat.git
Project-URL: Issues, https://github.com/VSRAJHAVEL/adamstat/issues
Keywords: clinical-trials,biostatistics,cdisc,sdtm,adam,adsl,csr,ich-e3,data-science,pharmaceuticals
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22.0
Requires-Dist: pandas>=1.4.0
Requires-Dist: scipy>=1.8.0
Requires-Dist: statsmodels>=0.13.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: seaborn>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Dynamic: license-file

# 📊 adamstat

[![Python Package](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://www.python.org/)
[![CDISC Standards](https://img.shields.io/badge/CDISC-SDTM%20%7C%20ADaM-brightgreen.svg)](https://www.cdisc.org/)
[![ICH Guidelines](https://img.shields.io/badge/ICH-E3%20CSR%20TFLs-orange.svg)](https://www.ich.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)]()

> **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:

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

Or install with test dependencies:
```bash
pip install -e ".[dev]"
```

---

## 🚀 Quickstart Example

```python
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:

```python
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:

```bash
# 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`:

```bash
python -m pytest tests -v
```

---

## 📂 Laboratory Experiments & Code Mapping

This repository consolidates the laboratory experiments:

| Lab / Module | Topic / Focus | Core Implementation |
| :---: | :--- | :--- |
| **Lab 01** | Clinical Data Exploration & Descriptive Profiling | `adamstat.eda` (`clinical_summary`, `completeness_audit`, `categorical_profiles`) |
| **Lab 02** | Clinical Data Cleaning, Imputation & Deduplication | `adamstat.cleaning` (`ClinicalDataCleaner`, `standardize_demographics`, `impute_clinical_data`) |
| **Lab 03** | Clinical Feature Derivations & Risk Stratification | `adamstat.derivation` (`derive_age_group`, `derive_bp_category`, `derive_high_risk_flag`) |
| **Lab 04** | Clinical Biomarker Visualizations | `adamstat.visualization` (`plot_demographics`, `plot_vitals_scatter`, `plot_treatment_boxplots`) |
| **Lab 05** | CDISC SDTM Domain Generation (DM, VS, LB, AE, EX) | `adamstat.sdtm` (`create_dm`, `create_vs`, `create_lb`, `create_ae`, `create_ex`, `validate_sdtm_domain`) |
| **Lab 06** | CDISC ADaM Datasets (ADSL, BDS, OCCDS) | `adamstat.adam` (`create_adsl`, `create_advs`, `create_adlb`, `create_adae`, `validate_adam`) |
| **Lab 07** | Biostatistics & Hypothesis Testing | `adamstat.stats` (`two_sample_ttest`, `oneway_anova`, `posthoc_tukey`, `ae_contingency_test`) |
| **Lab 08** | ICH E3 Clinical Study Report (CSR) Tables & Figures | `adamstat.reporting` (`generate_table_14_1_1`, `generate_table_14_2_1`, `plot_figure_14_2_2_forest`) |

---

## 📜 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
