Metadata-Version: 2.4
Name: epipylab
Version: 0.2.5
Summary: A computational epidemiology framework for Python.
Author-email: Shams Rahman <shams16@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: scipy
Requires-Dist: statsmodels
Requires-Dist: scikit-learn
Requires-Dist: matplotlib
Requires-Dist: polars
Requires-Dist: catboost
Requires-Dist: python-docx
Requires-Dist: svy
Requires-Dist: lifelines
Requires-Dist: comprisk==0.7.0
Requires-Dist: openpyxl
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

# EpiPyLab

EpiPyLab is an open-source computational epidemiology framework for Python.

Version 0.2.5 provides epidemiologic measures, statistical methods, study-planning tools, regression and survival models, complex survey analysis, surveillance, pharmacoepidemiology, machine learning, visualization, interpretation, teaching materials, and publication utilities. Causal inference is included as `epipylab.causal`, one of 23 subpackages. There is no separate `epipylab-causal` distribution.

The distribution name and the Python import package are both `epipylab`. The root package exposes the version string. Analysis functions are imported from the subpackages. Those subpackages publish **352 public names** through `__all__`.

## Package status

Version 0.2.5 is an alpha release. Interfaces and numerical details may change in later versions. Estimates produced by this software support epidemiologic analysis. They do not, by themselves, establish causal identification, the absence of bias, or the clinical importance of a result.

Detailed causal-inference documentation, including the worked `g_formula` example and estimator-specific limitations, is in [docs/causal.md](docs/causal.md).

## Installation

EpiPyLab requires Python 3.10 or newer.

```bash
pip install epipylab
```

```python
import epipylab
print(epipylab.__version__)
```

Installation brings in the declared scientific dependencies, including NumPy, pandas, SciPy, statsmodels, scikit-learn, Matplotlib, Polars, lifelines, and related libraries used by individual subpackages.

## Capabilities

| Subpackage | Role | Representative public functions |
|---|---|---|
| `descriptive` | Frequencies, summaries, missingness, and tables | `frequency`, `proportion`, `two_by_two_table`, `describe_dataset`, `frequency_table` |
| `morbidity` | Prevalence, incidence, attack rates, and burden | `prevalence`, `incidence_proportion`, `incidence_rate`, `attack_rate`, `secondary_attack_rate` |
| `mortality` | Mortality rates, standardization, life tables, and years of life lost | `crude_mortality_rate`, `age_adjusted_mortality_rate`, `standardized_mortality_ratio`, `life_table`, `years_of_potential_life_lost` |
| `analytic` | 2×2 effect measures, tests, and confidence intervals | `odds_ratio`, `risk_ratio`, `risk_difference`, `chi_square_test`, `fisher_exact_test` |
| `association` | Effect measures re-exported from `analytic` | `odds_ratio`, `risk_ratio`, `attributable_fraction`, `population_attributable_fraction` |
| `precision` | Standard errors and confidence intervals | `wald_ci_proportion`, `wilson_ci_proportion`, `poisson_rate_ci`, `odds_ratio_ci`, `risk_ratio_ci` |
| `stratified` | Mantel–Haenszel pooling and stratified tests | `mantel_haenszel_odds_ratio`, `mantel_haenszel_risk_ratio`, `mantel_haenszel_test`, `breslow_day_test` |
| `nonparametric` | Rank tests and rank correlations | `mann_whitney_u`, `wilcoxon_signed_rank`, `kruskal_wallis`, `spearman_correlation` |
| `validity` | Diagnostic accuracy, agreement, reliability, and clinical impact | `sensitivity`, `specificity`, `kappa`, `cronbach_alpha`, `number_needed_to_treat` |
| `samplesize` | Sample size, power, and design adjustments | `sample_size_cohort`, `sample_size_case_control`, `sample_size_logrank`, `design_effect` |
| `regression` | Linear, logistic, and count models | `linear_model`, `logistic_model`, `poisson_model`, `modified_poisson_model`, `negative_binomial_model` |
| `survival` | Kaplan–Meier, Cox regression, and competing risks | `kaplan_meier`, `cox_model`, `check_ph_assumption`, `cumulative_incidence`, `fine_gray_model` |
| `survey` | Weights, design effect, complex samples, and weighted regression | `weighted_mean`, `design_effect`, `taylor_linearized_mean`, `survey_logistic_model` |
| `pharmacoepi` | Medication use, adherence, and disproportionality | `medication_possession_ratio`, `proportion_days_covered`, `reporting_odds_ratio`, `proportional_reporting_ratio` |
| `surveillance` | Trends, outbreak assessment, alerts, seasonality, and time series | `trend_summary`, `outbreak_assessment`, `cusum`, `ewma`, `annual_percent_change` |
| `causal` | Time-fixed binary-treatment causal inference | `g_formula`, `iptw`, `aipw`, `tmle`, `propensity_score_matching` |
| `data` | Categorizing, recoding, person-time, and merging | `age_groups`, `bmi_categories`, `prepare_person_time`, `two_by_two_table`, `merge_datasets` |
| `ml` | Splits, tree models, CatBoost, metrics, and comparison | `stratified_train_test_split`, `random_forest_classifier`, `catboost_regressor`, `classification_metrics` |
| `visualization` | Epidemiologic, survival, regression, and surveillance plots | `epidemic_curve`, `kaplan_meier_plot`, `forest_plot`, `surveillance_trend_plot` |
| `interpretation` | Structured wording for measures, tests, models, and diagnostics | `interpret_risk_ratio`, `interpret_confidence_interval`, `interpret_regression_result` |
| `teaching` | Synthetic datasets, cases, exercises, and teaching interpretations | `cohort_teaching_data`, `outbreak_case`, `numeric_exercise`, `check_answer` |
| `publication` | Table 1, result tables, and export | `table1`, `regression_table`, `effect_measure_table`, `export_table` |
| `epicore` | Shared formatting, proportion intervals, and validation | `format_rate`, `wilson_ci_proportion`, `validate_denominator` |

`association` re-exports the six effect measures defined in `analytic`. `precision` re-exports proportion and rate intervals from `epicore` and the odds-ratio, risk-ratio, and risk-difference intervals from `analytic`.

The same public name in two subpackages can refer to different functions:

| Name | First meaning | Second meaning |
|---|---|---|
| `design_effect` | `samplesize`: `1 + (m − 1) × ICC` | `survey`: Kish unequal-weighting design effect |
| `proportion` | `descriptive` | `epicore` |
| `two_by_two_table` | `descriptive`: table from cell counts | `data`: table constructed from dataset columns |
| `cumulative_incidence` | `morbidity`: same calculation as incidence proportion | `survival`: Aalen–Johansen cumulative incidence |
| `epidemic_curve` | `surveillance`: aggregated case counts | `visualization`: epidemic-curve plot |
| `interpret_ratio_measure`, `interpret_difference_measure`, `interpret_confidence_interval`, `interpret_p_value` | `interpretation` | `teaching` |

## Usage

These calls use the documented signatures and default multipliers. `incidence_proportion` defaults to per 100. `crude_mortality_rate` defaults to per 100,000. `risk_ratio` and `odds_ratio` take the 2×2 cells in the order exposed-outcome, exposed-nonoutcome, unexposed-outcome, unexposed-nonoutcome.

```python
from epipylab.morbidity import incidence_proportion
from epipylab.mortality import crude_mortality_rate
from epipylab.analytic import risk_ratio, odds_ratio

incidence_proportion(new_cases=25, population_at_risk=500)
crude_mortality_rate(deaths=50, population=100000)
risk_ratio(a=20, b=30, c=10, d=40)
odds_ratio(a=20, b=30, c=10, d=40)
```

With those inputs the four results are `5.0`, `50.0`, `2.0`, and `2.6667`.

## Scientific limitations

The analyst remains responsible for study design, coding, missing data, dependence, model specification, and the assumptions required to interpret a number as a causal or population effect.

- `case_fatality_rate` is deaths among diagnosed cases. The quantity is a proportion.
- Standardization, standardized ratios, and years of life lost depend on the standard population, reference rates, and age cut point supplied by the analyst.
- `confounding_present` and `effect_modification_range` are descriptive screens for crude-versus-adjusted and stratum-specific comparisons.
- `modified_poisson_model` fits a log-link Poisson model with HC0 robust standard errors for a binary outcome. Person-time offsets belong to `poisson_model`.
- `weighted_variance` is a descriptive weighted variance. `taylor_linearized_mean` estimates a mean with strata and primary sampling units. The public survey regression functions use weights with HC0 robust covariance.
- Metrics in `ml` describe predictive performance on the supplied sample.
- Surveillance thresholds, CUSUM, EWMA, and alert rules compare a series with a supplied or rolling baseline.
- Causal estimates are for a time-fixed binary treatment. Observational interpretation depends on identification assumptions recorded by the analyst. Matching targets the effect in the treated. Augmented inverse-probability weighting and targeted maximum likelihood estimation target the average treatment effect. Full estimator limitations and the `g_formula` example are in [docs/causal.md](docs/causal.md).
- Publication and interpretation helpers format or describe values they are given. Teaching datasets, cases, and exercises are synthetic instructional examples.

## Author

Shams Rahman  
Email: shams16@gmail.com

## License

EpiPyLab is released under the MIT License.

Copyright (c) 2026 Shams Rahman
