adamstat 1.0.0__py3-none-any.whl

adamstat/__init__.py

@@ -0,0 +1,162 @@
+"""
+adamstat: CDISC ADaM, SDTM, Biostatistics, and Clinical Study Reporting Toolkit.
+
+A comprehensive Python package for clinical trial data analytics, standardization,
+biostatistical modeling, and ICH E3 compliant CSR generation.
+"""
+
+__version__ = "1.0.0"
+__author__ = "VSRAJHAVEL"
+
+# Exploratory data analysis
+from adamstat.eda import (
+    clinical_summary,
+    completeness_audit,
+    categorical_profiles,
+    column_structure,
+)
+
+# Clinical cleaning and harmonization
+from adamstat.cleaning import (
+    standardize_demographics,
+    clean_biometric_outliers,
+    standardize_dates,
+    deduplicate_clinical,
+    impute_clinical_data,
+    ClinicalDataCleaner,
+)
+
+# Derived variables and classifications
+from adamstat.derivation import (
+    derive_age_group,
+    derive_bmi_category,
+    derive_bp_category,
+    derive_days_on_study,
+    derive_high_risk_flag,
+    derive_clinical_features,
+)
+
+# Visualizations
+from adamstat.visualization import (
+    plot_demographics,
+    plot_vitals_scatter,
+    plot_treatment_boxplots,
+    plot_correlation_matrix,
+    plot_risk_proportions,
+)
+
+# CDISC SDTM domains
+from adamstat.sdtm import (
+    create_dm,
+    create_vs,
+    create_lb,
+    create_ae,
+    create_ex,
+    validate_sdtm_domain,
+)
+
+# CDISC ADaM datasets
+from adamstat.adam import (
+    create_adsl,
+    create_advs,
+    create_adlb,
+    create_adae,
+    derive_bds_dataset,
+    validate_adam,
+)
+
+# Clinical Biostatistics and Hypothesis Testing
+from adamstat.stats import (
+    summary_by_arm,
+    check_normality,
+    check_homogeneity,
+    two_sample_ttest,
+    oneway_anova,
+    posthoc_tukey,
+    ae_contingency_test,
+    run_clinical_inferential_pipeline,
+)
+
+# CSR Reporting (Tables, Figures, Narratives)
+from adamstat.reporting import (
+    generate_table_14_1_1_demographics,
+    generate_table_14_2_1_efficacy,
+    generate_table_14_3_1_adverse_events,
+    plot_figure_14_2_1_boxplot,
+    plot_figure_14_2_2_forest,
+    generate_csr_narrative,
+)
+
+# Pipeline and Sample Data
+from adamstat.pipeline import ClinicalStudyPipeline
+from adamstat.sample_data import (
+    load_sample_demographics,
+    load_sample_vitals_labs,
+    load_sample_clinical_trial,
+    generate_synthetic_clinical_trial,
+)
+
+__all__ = [
+    "__version__",
+    # eda
+    "clinical_summary",
+    "completeness_audit",
+    "categorical_profiles",
+    "column_structure",
+    # cleaning
+    "standardize_demographics",
+    "clean_biometric_outliers",
+    "standardize_dates",
+    "deduplicate_clinical",
+    "impute_clinical_data",
+    "ClinicalDataCleaner",
+    # derivation
+    "derive_age_group",
+    "derive_bmi_category",
+    "derive_bp_category",
+    "derive_days_on_study",
+    "derive_high_risk_flag",
+    "derive_clinical_features",
+    # visualization
+    "plot_demographics",
+    "plot_vitals_scatter",
+    "plot_treatment_boxplots",
+    "plot_correlation_matrix",
+    "plot_risk_proportions",
+    # sdtm
+    "create_dm",
+    "create_vs",
+    "create_lb",
+    "create_ae",
+    "create_ex",
+    "validate_sdtm_domain",
+    # adam
+    "create_adsl",
+    "create_advs",
+    "create_adlb",
+    "create_adae",
+    "derive_bds_dataset",
+    "validate_adam",
+    # stats
+    "summary_by_arm",
+    "check_normality",
+    "check_homogeneity",
+    "two_sample_ttest",
+    "oneway_anova",
+    "posthoc_tukey",
+    "ae_contingency_test",
+    "run_clinical_inferential_pipeline",
+    # reporting
+    "generate_table_14_1_1_demographics",
+    "generate_table_14_2_1_efficacy",
+    "generate_table_14_3_1_adverse_events",
+    "plot_figure_14_2_1_boxplot",
+    "plot_figure_14_2_2_forest",
+    "generate_csr_narrative",
+    # pipeline & data
+    "ClinicalStudyPipeline",
+    "load_sample_demographics",
+    "load_sample_vitals_labs",
+    "load_sample_clinical_trial",
+    "generate_synthetic_clinical_trial",
+]

adamstat/adam.py

@@ -0,0 +1,280 @@
+"""
+CDISC ADaM (Analysis Data Model) Generation and Validation.
+Includes ADSL, BDS (ADVS, ADLB), and OCCDS (ADAE).
+"""
+
+from typing import Callable, Dict, List, Optional
+import numpy as np
+import pandas as pd
+
+
+def create_adsl(
+    dm: pd.DataFrame,
+    ex: Optional[pd.DataFrame] = None,
+    vs: Optional[pd.DataFrame] = None,
+    age_bins: Optional[List[float]] = None,
+    age_labels: Optional[List[str]] = None
+) -> pd.DataFrame:
+    """
+    Generate Subject-Level Analysis Dataset (ADSL) according to CDISC ADaM standards.
+    
+    Includes population flags (SAFFL, ITTFL, EFFFL), treatment dates (TRTSDT, TRTEDT),
+    baseline vitals, age categorization, and clinical high risk flags.
+    """
+    adsl = dm.copy()
+
+    # 1. Baseline Vital Signs (VISITNUM == 1)
+    if vs is not None:
+        vs_clean = vs.copy()
+        if "VISITNUM" in vs_clean.columns and "VSTESTCD" in vs_clean.columns:
+            vs_base = (
+                vs_clean.loc[pd.to_numeric(vs_clean["VISITNUM"], errors="coerce").eq(1)]
+                .assign(VSRESN=lambda x: pd.to_numeric(x["VSRESN"], errors="coerce"))
+                .sort_values(["USUBJID", "VSTESTCD"])
+                .dropna(subset=["VSRESN"])
+                .drop_duplicates(["USUBJID", "VSTESTCD"])
+            )
+            sbp_base = vs_base.loc[vs_base["VSTESTCD"].eq("SYSBP"), ["USUBJID", "VSRESN"]].rename(columns={"VSRESN": "BASE_SBP"})
+            dbp_base = vs_base.loc[vs_base["VSTESTCD"].eq("DIABP"), ["USUBJID", "VSRESN"]].rename(columns={"VSRESN": "BASE_DBP"})
+            adsl = adsl.merge(sbp_base, on="USUBJID", how="left")
+            adsl = adsl.merge(dbp_base, on="USUBJID", how="left")
+
+    # 2. Exposure integration
+    if ex is not None:
+        ex_clean = ex.copy()
+        drug_col = "EXDRUG" if "EXDRUG" in ex_clean.columns else ("EXTRT" if "EXTRT" in ex_clean.columns else None)
+        cols_to_pick = ["USUBJID"]
+        for c in [drug_col, "EXDOSE", "EXUNIT", "EXFREQ", "EXROUTE"]:
+            if c and c in ex_clean.columns:
+                cols_to_pick.append(c)
+        dose = ex_clean.sort_values("USUBJID").drop_duplicates("USUBJID")[cols_to_pick]
+        adsl = adsl.merge(dose, on="USUBJID", how="left")
+
+    # 3. Age Group Derivation
+    if "AGE" in adsl.columns:
+        adsl["AGE"] = pd.to_numeric(adsl["AGE"], errors="coerce")
+        if age_bins is None:
+            age_bins = [17.0, 40.0, 60.0, np.inf]
+        if age_labels is None:
+            age_labels = ["18-40", "41-60", "61+"]
+        adsl["AGE_GROUP"] = pd.cut(adsl["AGE"], bins=age_bins, labels=age_labels, right=True).astype("object")
+
+    # 4. High Risk Flag
+    if "BASE_SBP" in adsl.columns and "AGE" in adsl.columns:
+        adsl["HIGH_RISK"] = np.where(
+            adsl["AGE"].ge(60) & adsl["BASE_SBP"].ge(140), "Y", "N"
+        )
+    elif "AGE" in adsl.columns:
+        adsl["HIGH_RISK"] = np.where(adsl["AGE"].ge(65), "Y", "N")
+
+    # 5. CDISC Population Flags
+    adsl["SAFFL"] = "Y"
+    adsl["ITTFL"] = "Y"
+    adsl["EFFFL"] = "Y"
+
+    # 6. Treatment Start/End dates
+    if "RFSTDTC" in adsl.columns:
+        adsl["TRTSDT"] = pd.to_datetime(adsl["RFSTDTC"], errors="coerce").dt.strftime("%Y-%m-%d")
+    if "RFENDTC" in adsl.columns:
+        adsl["TRTEDT"] = pd.to_datetime(adsl["RFENDTC"], errors="coerce").dt.strftime("%Y-%m-%d")
+
+    adsl.insert(0, "ADSL", "ADSL")
+    return adsl
+
+
+def derive_bds_dataset(
+    data: pd.DataFrame,
+    domain: str,
+    test_col: str,
+    value_col: str,
+    date_col: str,
+    response_rule: Optional[Callable[[pd.DataFrame], pd.Series]] = None,
+    adsl: Optional[pd.DataFrame] = None
+) -> pd.DataFrame:
+    """
+    Generate CDISC ADaM Basic Data Structure (BDS) analysis dataset.
+    
+    Derives:
+      - AVAL: Analysis Value (numeric)
+      - PARAMCD & PARAM: Parameter Code and Description
+      - AVISIT & AVISITN: Analysis Visit Name and Number
+      - ADT: Analysis Date
+      - BASE: Baseline observation (AVISITN == 1)
+      - CHG: Change from baseline (AVAL - BASE)
+      - PCHG: Percent change from baseline ((CHG / BASE) * 100)
+      - ANL01FL: Analysis record flag (Baseline record)
+      - RESPONSE: Responder flag ('Y'/'N') based on clinical threshold rule
+    """
+    out = data.copy()
+    out["AVAL"] = pd.to_numeric(out[value_col], errors="coerce")
+    out["PARAMCD"] = out[test_col].astype("string")
+
+    name_col = "VSTEST" if (domain == "ADVS" and "VSTEST" in out.columns) else (
+        "LBTEST" if "LBTEST" in out.columns else test_col
+    )
+    out["PARAM"] = out[name_col].astype("string")
+
+    vis_col = "VISIT" if "VISIT" in out.columns else "AVISIT"
+    out["AVISIT"] = out[vis_col].astype("string") if vis_col in out.columns else "Baseline"
+
+    visnum_col = "VISITNUM" if "VISITNUM" in out.columns else "AVISITN"
+    out["AVISITN"] = pd.to_numeric(out[visnum_col], errors="coerce").fillna(1) if visnum_col in out.columns else 1
+
+    out["ADT"] = pd.to_datetime(out[date_col], errors="coerce").dt.strftime("%Y-%m-%d") if date_col in out.columns else "2025-01-01"
+
+    out = out.sort_values(["USUBJID", "PARAMCD", "AVISITN"]).reset_index(drop=True)
+
+    # Baseline: AVISITN == 1
+    baseline = (
+        out.loc[out["AVISITN"].eq(1) & out["AVAL"].notna(), ["USUBJID", "PARAMCD", "AVAL"]]
+        .drop_duplicates(["USUBJID", "PARAMCD"])
+        .rename(columns={"AVAL": "BASE"})
+    )
+    out = out.merge(baseline, on=["USUBJID", "PARAMCD"], how="left")
+
+    out["CHG"] = out["AVAL"] - out["BASE"]
+    out["PCHG"] = np.nan
+    valid_base = out["BASE"].notna() & out["BASE"].ne(0) & out["CHG"].notna()
+    out.loc[valid_base, "PCHG"] = (out.loc[valid_base, "CHG"] / out.loc[valid_base, "BASE"]) * 100
+
+    out["ANL01FL"] = np.where(out["AVISITN"].eq(1) & out["AVAL"].notna(), "Y", "")
+
+    # Responder derivation
+    valid_eval = out["AVAL"].notna() & out["BASE"].notna()
+    out["RESPONSE"] = pd.Series(np.nan, index=out.index, dtype="object")
+    out.loc[valid_eval, "RESPONSE"] = "N"
+
+    if response_rule is not None:
+        try:
+            meets_rule = response_rule(out)
+            out.loc[meets_rule, "RESPONSE"] = "Y"
+        except Exception:
+            pass
+
+    out.insert(0, "ADaM", domain)
+
+    # Merge ADSL demographic and treatment covariates if provided
+    if adsl is not None:
+        covar_cols = [c for c in ["USUBJID", "ARM", "ARMCD", "AGE", "AGE_GROUP", "SEX", "SAFFL", "ITTFL", "EFFFL"] if c in adsl.columns]
+        out = out.merge(adsl[covar_cols].drop_duplicates("USUBJID"), on="USUBJID", how="left")
+
+    return out
+
+
+def create_advs(
+    vs: pd.DataFrame,
+    adsl: Optional[pd.DataFrame] = None,
+    response_rule: Optional[Callable[[pd.DataFrame], pd.Series]] = None
+) -> pd.DataFrame:
+    """
+    Generate Vital Signs BDS Analysis Dataset (ADVS).
+    Default response rule: Systolic Blood Pressure reduction >= 10 mmHg (CHG <= -10).
+    """
+    if response_rule is None:
+        response_rule = lambda d: d["PARAMCD"].eq("SYSBP") & d["CHG"].le(-10)
+
+    val_col = "VSRESN" if "VSRESN" in vs.columns else "VALUE"
+    date_col = "VSSTDTC" if "VSSTDTC" in vs.columns else ("VISITDATE" if "VISITDATE" in vs.columns else None)
+    return derive_bds_dataset(
+        data=vs,
+        domain="ADVS",
+        test_col="VSTESTCD",
+        value_col=val_col,
+        date_col=date_col,
+        response_rule=response_rule,
+        adsl=adsl
+    )
+
+
+def create_adlb(
+    lb: pd.DataFrame,
+    adsl: Optional[pd.DataFrame] = None,
+    response_rule: Optional[Callable[[pd.DataFrame], pd.Series]] = None
+) -> pd.DataFrame:
+    """
+    Generate Laboratory BDS Analysis Dataset (ADLB).
+    Default response rule: Glucose reduction >= 10 mg/dL (CHG <= -10).
+    """
+    if response_rule is None:
+        response_rule = lambda d: d["PARAMCD"].astype("string").str.upper().str.contains("GLUC", na=False) & d["CHG"].le(-10)
+
+    val_col = "LBRESN" if "LBRESN" in lb.columns else "VALUE"
+    date_col = "LBSTDTC" if "LBSTDTC" in lb.columns else ("VISITDATE" if "VISITDATE" in lb.columns else None)
+    return derive_bds_dataset(
+        data=lb,
+        domain="ADLB",
+        test_col="LBTESTCD",
+        value_col=val_col,
+        date_col=date_col,
+        response_rule=response_rule,
+        adsl=adsl
+    )
+
+
+def create_adae(
+    ae: pd.DataFrame,
+    adsl: Optional[pd.DataFrame] = None
+) -> pd.DataFrame:
+    """
+    Generate Adverse Event OCCDS Analysis Dataset (ADAE).
+    
+    Includes numeric severity grading (AESEVN), causality grading (AERELN),
+    sequence indices (ASEQ), and treatment emergent flags.
+    """
+    adae = ae.copy()
+
+    if adsl is not None:
+        adsl_cols = [c for c in ["USUBJID", "ARM", "ARMCD", "EXDRUG", "EXDOSE", "EXUNIT", "SAFFL", "ITTFL", "EFFFL"] if c in adsl.columns]
+        adae = adae.merge(adsl[adsl_cols].drop_duplicates("USUBJID"), on="USUBJID", how="left")
+
+    if "AESEV" in adae.columns:
+        sev_map = {"mild": 1, "moderate": 2, "severe": 3}
+        adae["AESEVN"] = adae["AESEV"].astype("string").str.strip().str.casefold().map(sev_map).astype("Int64")
+
+    if "AEREL" in adae.columns:
+        rel_map = {"related": 1, "possibly related": 1, "possibly-related": 1, "unrelated": 0, "not related": 0}
+        adae["AERELN"] = adae["AEREL"].astype("string").str.strip().str.casefold().map(rel_map).astype("Int64")
+
+    if "AESTDTC" in adae.columns:
+        adae["ASTDT"] = pd.to_datetime(adae["AESTDTC"], errors="coerce").dt.strftime("%Y-%m-%d")
+    if "AEENDTC" in adae.columns:
+        adae["AENDT"] = pd.to_datetime(adae["AEENDTC"], errors="coerce").dt.strftime("%Y-%m-%d")
+
+    sort_cols = ["USUBJID"]
+    if "AESTDTC" in adae.columns: sort_cols.append("AESTDTC")
+    if "AETERM" in adae.columns: sort_cols.append("AETERM")
+    adae = adae.sort_values(sort_cols).reset_index(drop=True)
+    adae["ASEQ"] = adae.groupby("USUBJID").cumcount() + 1
+    adae.insert(0, "ADaM", "ADAE")
+
+    return adae
+
+
+def validate_adam(datasets: Dict[str, pd.DataFrame]) -> Dict[str, Dict[str, any]]:
+    """
+    Validate conformance of generated ADaM datasets.
+    """
+    report = {}
+    for name, df in datasets.items():
+        summary = {
+            "rows": len(df),
+            "columns": len(df.columns),
+            "missing_usubjid": int(df["USUBJID"].isna().sum()) if "USUBJID" in df.columns else -1,
+            "unique_subjects": int(df["USUBJID"].nunique()) if "USUBJID" in df.columns else 0,
+            "status": "PASS"
+        }
+
+        if name == "ADSL":
+            summary["one_row_per_subject"] = not df["USUBJID"].duplicated().any()
+            if not summary["one_row_per_subject"]:
+                summary["status"] = "FAIL"
+        elif name in ["ADVS", "ADLB"]:
+            if "BASE" in df.columns and "AVAL" in df.columns and "CHG" in df.columns:
+                valid_mask = df["BASE"].notna() & df["AVAL"].notna()
+                errors = ((df.loc[valid_mask, "CHG"] - (df.loc[valid_mask, "AVAL"] - df.loc[valid_mask, "BASE"])).abs() > 1e-8).sum()
+                summary["chg_errors"] = int(errors)
+                if errors > 0:
+                    summary["status"] = "FAIL"
+        report[name] = summary
+
+    return report