CHANGELOG.md

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.3.3] - 2026-04-05

Added

• sctrial.benchmark subpackage: hierarchical gamma-Poisson simulator (SimulationConfig, simulate_trial, calibrate_from_real_data) and benchmark orchestrator (run_benchmark) for controlled method comparisons
• run_gsea_cross_sectional() and run_gsea_within_arm() now exported from sctrial.stats
• sensitivity_analysis() now exported from sctrial.stats
• Concepts and Methods documentation page with statistical background and references
• Changelog page in documentation
• API reference split into navigable sections (Design, Statistics, Scoring, Plotting, Datasets, Workflow, Utilities, Benchmark)

Fixed

• stats/__init__.py: missing exports for run_gsea_cross_sectional, run_gsea_within_arm, and sensitivity_analysis
• Documentation URLs standardized to Read the Docs

Improved

• CITATION.cff updated to v0.3.0 with full author list matching the preprint
• README updated with preprint citation, PyPI badge, and corrected API links
• Module-level docstrings added to 8 core modules
• Tutorial notebooks revised for clarity and consistent use of sctrial API

[0.3.0] - 2026-03-18

Added

Single-Arm Power Analysis (sctrial.stats.power)

• power_paired(): Power for paired pre/post designs (vaccine, CAR-T, etc.)
• sample_size_paired(): Required sample size for paired designs
• sensitivity_paired(): Minimum detectable effect size for paired designs

Single-Arm Design Support (sctrial.design)

• TrialDesign.arm_col now accepts None for single-arm studies
• required_cols(), validate(), subset_cells() handle arm_col=None
• arm_bin() raises clear ValueError for single-arm designs

Monte Carlo Simulation (sctrial.stats.simulation)

• simulate_did_data(): Generate synthetic DiD datasets with known ground truth
• run_method_comparison(): Compare sctrial DiD vs pseudobulk OLS vs Wilcoxon

Fixed

• n_boot default: 1000 → 999 in bootstrap_effect_size_ci()
• Zero-SE paired delta returns NaN instead of t=0, p=1
• Non-finite SE coerced to NaN instead of 0.0
• validate() no longer crashes when arm_col=None
• check_covariate_balance() raises clear error for single-arm designs
• mypy: fixed catch_warnings type in comparisons.py

Bayesian DiD (sctrial.stats.bayes)

• prior_predictive_check(): Run prior predictive checks to calibrate Bayesian priors before fitting.
• did_table_bayes() now accepts prior_scale and sigma_scale parameters for prior sensitivity analysis.

Effect Size Module (sctrial.stats.effect_size)

• cohens_d(): Calculate Cohen's d effect size between two groups
• hedges_g(): Bias-corrected effect size (recommended for n < 20)
• add_effect_sizes_to_did(): Add standardized effect sizes to DiD results
• bootstrap_effect_size_ci(): Bootstrap confidence intervals for effect sizes
• effect_size_ci(): Analytical confidence intervals using noncentral t

Power Analysis Module (sctrial.stats.power)

• power_did(): Calculate power for DiD analysis given sample size
• sample_size_did(): Determine required sample size for desired power
• power_curve(): Generate power curves across sample sizes
• design_effect(): Calculate design effect for clustered data
• effective_sample_size(): Compute effective n accounting for ICC

Mixed Effects Models (sctrial.stats.mixed_effects)

• did_table_mixed(): DiD with random participant effects
• compare_fixed_vs_mixed(): Compare both approaches for sensitivity analysis
• Returns ICC (intraclass correlation) and variance components

Time Series Analysis (sctrial.stats.timeseries)

• trend_interaction(): Treatment × time trend for 3+ timepoints
• event_study_did(): Generalized DiD comparing each visit to baseline
• polynomial_trend(): Fit polynomial trajectories by arm
• test_parallel_trends(): Validate parallel trends assumption

Cross-Validation (sctrial.stats.cv)

• loo_cv_did(): Leave-one-out CV for influence diagnostics
• kfold_cv_did(): K-fold CV for effect stability assessment
• influence_diagnostics(): Identify influential participants
• cv_summary(): Summary statistics from CV results

Improved

• add_effect_sizes_to_did() now uses residual SD directly from the OLS/WLS fit when available, instead of back-calculating from standard errors with a balanced-design assumption.
• module_score_did_by_pool() now accepts fdr_global parameter; emits a global FDR column (FDR_DiD_global) and a warning when per-group FDR is used.
• kfold_cv_did() now stratifies fold assignment by treatment arm for balanced folds.
• did_table_mixed() convergence handling improved: trusts fit.converged as primary indicator with lbfgs fallback optimizer.
• design_effect() and effective_sample_size() now validate inputs (ICC, cluster_size).
• Missing feature error messages in did_fit() now show total count when more than 5 are missing.
• add_log1p_cpm_layer() now supports overwrite=True to replace an existing layer and inplace=True to modify the AnnData in place without copying.
• _to_bool_series() now emits a WARNING-level log when non-finite values are encountered in a boolean column, aiding data quality diagnostics.
• profile_features() docstring now documents that aggregation is cell-weighted; for balanced participant-level comparisons, pre-aggregate to pseudobulk first.
• Replaced print() with logging throughout convenience, datasets, and validation modules.
• Enhanced did_fit() docstring with full mathematical model specification
• Added explicit null hypothesis statements to all statistical functions
• Expanded FAQ with bootstrap vs standard errors guidance
• Expanded FAQ with minimum sample size recommendations
• Expanded FAQ with missing data handling guidance
• Reorganized API documentation by statistical method category

Fixed

• Statistical: Fixed WLS weighting in did_fit() — now uses n_cells (correct inverse-variance weights) instead of sqrt(n_cells) for pre-aggregated participant-level means.
• Statistical: Fixed pseudobulk_expression() to drop groups with zero total counts before CPM normalization instead of adding a 1e-12 epsilon.
• Preprocessing: add_log1p_cpm_layer() now validates input: raises ValueError on negative counts, warns on NaN/inf values, and warns when all cells in the counts layer are zero.
• Preprocessing: add_log1p_cpm_layer() now records provenance metadata in adata.uns["log1p_cpm_info"] (source layer, target layer, timestamp).
• adata_tools: Fixed _to_bool_series() truncating fractional crossover values (e.g. 0.5 was cast to int → 0 → False). Now any non-zero finite value is truthy.
• adata_tools: Fixed _to_bool_series() crashing with IntCastingNaNError on np.inf crossover values. Non-finite values (NaN, inf) are now treated as False with a logged warning.
• analysis: Fixed DiDAnalyzer.fit() returning a mutable alias to internal results_ DataFrame. Now returns a copy so external mutations cannot corrupt internal state.
• Fixed duplicate _params_match() definition in datasets.py that silently overwrote the robust version; also fixed numpy array comparison bug.
• Fixed README.md example with incorrect arm_col parameter value.
• Fixed auto_detect_design docstring example showing incorrect mutation of frozen dataclass.
• Fixed test_plot_gsea_heatmap test to skip when matplotlib is not installed.

Internal

• Added __all__ exports to all modules for better API clarity: design, preprocessing, scoring, adata_tools, utils, plotting.
• Added validation and convenience modules to API documentation.

[0.2.0] - 2026-01-01

Added

• Core trial-aware inference engine: Difference-in-Differences (DiD) with participant fixed effects and covariate support.
• Robust statistical methods: Wild Cluster Bootstrap (Rademacher) and Permutation tests.
• Cell-type abundance DiD for compositional analysis.
• GSEA integration with trial-aware rankings (signed confidence, beta, or t-statistic).
• Stratified DiD analysis across cell-type hierarchies (did_table_by_celltype).
• Advanced visualizations: Trial interaction plots, forest plots, spaghetti plots, radar plots, and trial-stratified UMAP panels.
• Automated summary reporting for DiD results.
• Comprehensive Sphinx documentation with API reference and detailed tutorials.
• Professional infrastructure: MIT License, pre-commit hooks, and GitHub Actions CI.
• Full support for sparse AnnData objects.