adamstat 1.0.0__tar.gz

adamstat-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VSRAJHAVEL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

adamstat-1.0.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include pyproject.toml
+recursive-include src/adamstat/data *.csv
+recursive-include tests *.py
+recursive-include records *.docx *.pdf
+recursive-include notebooks *.ipynb

adamstat-1.0.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: adamstat
+Version: 1.0.0
+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.

adamstat-1.0.0/README.md

@@ -0,0 +1,159 @@
+# 📊 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.