Metadata-Version: 2.4
Name: splitpopsurv
Version: 0.1.0
Summary: Split-population (cure / mover-stayer) survival models
Author-email: Nobutaka Fukuda <nobutaka.fukuda@tohoku.ac.jp>
License-Expression: MIT
Project-URL: Homepage, https://github.com/nobifukuda/splitpopsurv-py
Project-URL: Bug Tracker, https://github.com/nobifukuda/splitpopsurv-py/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: scipy>=1.7
Requires-Dist: pandas>=1.3
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Dynamic: license-file

# splitpopsurv (Python)

Split-population (cure / mover–stayer) survival models in Python: an
accelerated failure-time regression for event timing among "movers",
combined with a logistic regression on the probability of belonging to
the immune "stayer" population.

Five baseline timing distributions are provided — **log-logistic**,
**Weibull**, **log-normal**, **gamma**, and the **generalized gamma** that
nests the other four — following Schmidt & Witte (1989) and Yamaguchi
(1992, 1998). This package is a Python translation of a set of Stata `ml`
programs, with the log-likelihood corrected to match the published model
and verified by simulation against known parameters.

📖 **Full manual** (theory, formulas, the likelihood correction, and a
complete function reference): [`docs/manual.html`](https://htmlpreview.github.io/?https://github.com/nobifukuda/splitpopsurv-py/blob/main/docs/manual.html)

Companion packages implementing the same corrected models are available
for [R](https://github.com/nobifukuda/splitpopsurv) and
[Stata](https://github.com/nobifukuda/splitpopsurv-stata).

## Author

**Nobutaka Fukuda**, Tohoku University — <nobutaka.fukuda@tohoku.ac.jp>

## Installation

```bash
pip install git+https://github.com/nobifukuda/splitpopsurv-py.git
```

## Usage

```python
import pandas as pd
from splitpopsurv import fit_splitpop_weibull

# mydata needs: time, event (0/1), and your covariates
fit = fit_splitpop_weibull(
    data=mydata,
    time="time",
    event="event",
    h_vars=["x1"],       # H_regression: covariates for timing
    p_vars=["x2"],       # P_regression: covariates for cure probability
)

print(fit.summary())     # coefficients, SEs, z-values, log-likelihood
fit.params               # named parameter vector (numpy array)
fit.as_dataframe()        # coefficients table as a pandas DataFrame
```

The other four distributions use the same signature:
`fit_splitpop_loglogistic()`, `fit_splitpop_lognormal()`,
`fit_splitpop_gamma()`, `fit_splitpop_ggamma()`.

## A note on the original Stata code

All five Stata programs this package translates compute a log-likelihood
term that turns out to be the marginal *density* where the formula requires
the marginal *hazard* (density divided by survival) — a discrepancy from
Yamaguchi's own published model. This was confirmed by fitting simulated
data with known parameters: the as-translated formula gives visibly biased
estimates, or fails to converge outright, while the corrected formula
implemented here recovers the true parameters accurately. See
[`docs/manual.html`](https://htmlpreview.github.io/?https://github.com/nobifukuda/splitpopsurv-py/blob/main/docs/manual.html#correction)
for the full derivation and the simulation results. This is the same
correction independently verified for the R and Stata ports of this model.

## Development

```bash
pip install -e ".[test]"
pytest
```

## License

MIT — see [LICENSE](LICENSE).

## References

Prentice, R. L. (1974). A log gamma model and its maximum likelihood
estimation. *Biometrika*, 61(3), 539–544.

Schmidt, P., & Witte, A. D. (1989). Predicting criminal recidivism using
"split population" survival time models. *Journal of Econometrics*, 40(1),
141–159.

Yamaguchi, K. (1992). Accelerated failure-time regression models with a
regression model of surviving fraction: An application to the analysis of
"permanent employment" in Japan. *Journal of the American Statistical
Association*, 87(418), 284–292.

Yamaguchi, K., & Ferguson, L. R. (1995). The stopping and spacing of
childbirths and their birth-history predictors: Rational-choice theory and
event-history analysis. *American Sociological Review*, 60(2), 272–298.

Yamaguchi, K. (1998). Mover-stayer models for analyzing event nonoccurrence
and event timing with time-dependent covariates: An application to an
analysis of remarriage. *Sociological Methodology*, 28(1), 327–361.
