Add scikit-survival integration (#56)

Author: DiogoRibeiro7

.github/workflows/test.yml

@@ -9,6 +9,9 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
 
     steps:
       - name: Checkout code
@@ -17,7 +20,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: "3.9"
+          python-version: ${{ matrix.python-version }}
 
       - name: Install Poetry
         run: |

CHANGELOG.md

@@ -1,5 +1,36 @@
 # CHANGELOG
 
+## v1.0.9 (Unreleased)
+
+### Features
+- export datasets to RDS files
+- test workflow runs on a Python version matrix
+- scikit-learn compatible data generator
+- compatibility helpers for lifelines and scikit-survival
+
+### Documentation
+- updated usage examples and tutorials
+
+### Misc
+- README quick example uses `covariate_range`
+
+## v1.0.8 (2025-07-30)
+
+### Documentation
+- ensure absolute path resolution in `conf.py`
+- drop unsupported theme option
+- define bibliography anchors and headings
+- fix tutorial links to non-existing docs
+- add additional references to the bibliography
+
+### Testing
+- add CLI integration test
+- expand piecewise generator test coverage
+
+### Misc
+- remove fix_recommendations.md
+
+
 
 ## v1.0.0 (2025-06-06)
 

README.md

@@ -20,6 +20,8 @@
 - Mixture cure and piecewise exponential models
 - Competing risks generators (constant and Weibull hazards)
 - Command-line interface and export utilities
+- Scikit-learn compatible data generator
+- Conversion helper for scikit-survival and lifelines
 
 ## Installation
 
@@ -40,11 +42,30 @@ poetry install
 ## Quick Example
 
 ```python
-from gen_surv import generate
+from gen_surv import export_dataset, generate
 
 # basic Cox proportional hazards data
-sim = generate(model="cphm", n=100, beta=0.5, covar=2.0,
-               model_cens="uniform", cens_par=1.0)
+sim = generate(
+    model="cphm",
+    n=100,
+    beta=0.5,
+    covariate_range=2.0,
+    model_cens="uniform",
+    cens_par=1.0,
+)
+
+# save to an RDS file
+export_dataset(sim, "survival_data.rds")
+```
+
+You can also convert the resulting DataFrame for use with
+[scikit-survival](https://scikit-survival.readthedocs.io) or
+[lifelines](https://lifelines.readthedocs.io):
+
+```python
+from gen_surv import to_sksurv
+
+sks_dataset = to_sksurv(sim)
 ```
 
 See the [usage guide](docs/source/getting_started.md) for more examples.

TODO.md

@@ -9,9 +9,9 @@ This document outlines future enhancements, features, and ideas for improving th
 - [✅] Add property-based tests using Hypothesis to cover edge cases
 - [✅] Build a CLI for generating datasets from the terminal
 - [ ] Expand documentation with multilingual support and more usage examples
-- [ ] Implement Weibull and log-logistic AFT models and add visualization utilities
+- [✅] Implement Weibull and log-logistic AFT models and add visualization utilities
 - [✅] Provide CITATION metadata for proper referencing
-- [ ] Ensure all functions include Google-style docstrings with inline comments
+- [✅] Ensure all functions include Google-style docstrings with inline comments
 
 ---
 
@@ -37,35 +37,35 @@ This document outlines future enhancements, features, and ideas for improving th
 
 - [✅] Add tests for each model (e.g., `test_tdcm.py`, `test_thmm.py`, `test_aft.py`)
 - [✅] Add property-based tests with `hypothesis`
-- [ ] Cover edge cases (e.g., invalid parameters, n=0, negative censoring)
-- [ ] Run tests on multiple Python versions (CI matrix)
+- [✅] Cover edge cases (e.g., invalid parameters, n=0, negative censoring)
+- [✅] Run tests on multiple Python versions (CI matrix)
 
 ---
 
 ## 🧠 4. Advanced Models
 
-- [ ] Add Piecewise Exponential Model support
-- [ ] Add competing risks / multi-event simulation
+- [✅] Add Piecewise Exponential Model support
+- [✅] Add competing risks / multi-event simulation
 - [✅] Implement parametric AFT models (log-normal)
-- [ ] Implement parametric AFT models (log-logistic, weibull)
+- [✅] Implement parametric AFT models (log-logistic, weibull)
 - [ ] Simulate time-varying hazards
 - [ ] Add informative or covariate-dependent censoring
 
 ---
 
 ## 📊 5. Visualization and Analysis
 
-- [ ] Create `plot_survival(df, model=...)` utilities
-- [ ] Create `describe_survival(df)` summary helpers
-- [ ] Export data to CSV / JSON / Feather
+- [✅] Create `plot_survival(df, model=...)` utilities
+- [✅] Create `describe_survival(df)` summary helpers
+- [✅] Export data to CSV / JSON / Feather
 
 ---
 
 ## 🌍 6. Ecosystem Integration
 
-- [ ] Add a `GenSurvDataGenerator` compatible with `sklearn`
-- [ ] Enable use with `lifelines`, `scikit-survival`, `sksurv`
-- [ ] Export in R-compatible formats (.csv, .rds)
+- [✅] Add a `GenSurvDataGenerator` compatible with `sklearn`
+- [✅] Enable use with `lifelines`, `scikit-survival`, `sksurv`
+- [✅] Export in R-compatible formats (.csv, .rds)
 
 ---
 
@@ -80,12 +80,12 @@ This document outlines future enhancements, features, and ideas for improving th
 ## 🧠 8. New Survival Models to Implement
 
 - [✅] Log-Normal AFT
-- [ ] Log-Logistic AFT
-- [ ] Weibull AFT
-- [ ] Piecewise Exponential
-- [ ] Competing Risks
+- [✅] Log-Logistic AFT
+- [✅] Weibull AFT
+- [✅] Piecewise Exponential
+- [✅] Competing Risks
 - [ ] Recurrent Events
-- [ ] Mixture Cure Model
+- [✅] Mixture Cure Model
 
 ---
 

docs/source/bibliography.md

@@ -6,21 +6,54 @@ orphan: true
 
 Below is a selection of references covering the statistical models implemented in **gen_surv**.
 
-.. _Cox1972:
+(Cox1972)=
+## Cox (1972)
 Cox, D. R. (1972). Regression Models and Life-Tables. *Journal of the Royal Statistical Society: Series B*, 34(2), 187-220.
 
-.. _Farewell1982:
+(Farewell1982)=
+## Farewell (1982)
 Farewell, V.T. (1982). The Use of Mixture Models for the Analysis of Survival Data with Long-Term Survivors. *Biometrics*, 38(4), 1041-1046.
 
-.. _FineGray1999:
+(FineGray1999)=
+## Fine and Gray (1999)
 Fine, J.P., & Gray, R.J. (1999). A Proportional Hazards Model for the Subdistribution of a Competing Risk. *Journal of the American Statistical Association*, 94(446), 496-509.
 
-.. _Andersen1993:
+(Andersen1993)=
+## Andersen et al. (1993)
 Andersen, P.K., Borgan, Ø., Gill, R.D., & Keiding, N. (1993). *Statistical Models Based on Counting Processes*. Springer.
 
-.. _Zucchini2017:
+(Zucchini2017)=
+## Zucchini et al. (2017)
 Zucchini, W., MacDonald, I.L., & Langrock, R. (2017). *Hidden Markov Models for Time Series*. Chapman and Hall/CRC.
 
-- Klein, J.P., & Moeschberger, M.L. (2003). *Survival Analysis: Techniques for Censored and Truncated Data*. Springer.
-- Kalbfleisch, J.D., & Prentice, R.L. (2002). *The Statistical Analysis of Failure Time Data*. Wiley.
-- Cook, R.J., & Lawless, J.F. (2007). *The Statistical Analysis of Recurrent Events*. Springer.
+(KleinMoeschberger2003)=
+## Klein and Moeschberger (2003)
+Klein, J.P., & Moeschberger, M.L. (2003). *Survival Analysis: Techniques for Censored and Truncated Data*. Springer.
+
+(KalbfleischPrentice2002)=
+## Kalbfleisch and Prentice (2002)
+Kalbfleisch, J.D., & Prentice, R.L. (2002). *The Statistical Analysis of Failure Time Data*. Wiley.
+
+(CookLawless2007)=
+## Cook and Lawless (2007)
+Cook, R.J., & Lawless, J.F. (2007). *The Statistical Analysis of Recurrent Events*. Springer.
+
+(KaplanMeier1958)=
+## Kaplan and Meier (1958)
+Kaplan, E.L., & Meier, P. (1958). Nonparametric Estimation from Incomplete Observations. *Journal of the American Statistical Association*, 53(282), 457-481.
+(TherneauGrambsch2000)=
+## Therneau and Grambsch (2000)
+Therneau, T.M., & Grambsch, P.M. (2000). *Modeling Survival Data: Extending the Cox Model*. Springer.
+
+(FlemingHarrington1991)=
+## Fleming and Harrington (1991)
+Fleming, T.R., & Harrington, D.P. (1991). *Counting Processes and Survival Analysis*. Wiley.
+
+(Collett2015)=
+## Collett (2015)
+Collett, D. (2015). *Modelling Survival Data in Medical Research*. CRC Press.
+
+(KleinbaumKlein2012)=
+## Kleinbaum and Klein (2012)
+Kleinbaum, D.G., & Klein, M. (2012). *Survival Analysis: A Self-Learning Text*. Springer.
+

docs/source/conf.py

@@ -2,8 +2,8 @@
 import sys
 from pathlib import Path
 
-# Add the package to the Python path
-project_root = Path(__file__).parent.parent.parent
+# Add the package to the Python path using an absolute path
+project_root = Path(__file__).resolve().parent.parent.parent
 sys.path.insert(0, str(project_root / "gen_surv"))
 
 # Project information
@@ -74,7 +74,6 @@
     'canonical_url': 'https://gensurvpy.readthedocs.io/',
     'analytics_id': '',
     'logo_only': False,
-    'display_version': True,
     'prev_next_buttons_location': 'bottom',
     'style_external_links': False,
     'style_nav_header_background': '#2980B9',

docs/source/getting_started.md

@@ -33,8 +33,8 @@ from gen_surv import generate
  df = generate(
      model="cphm",      # Model type
      n=100,             # Sample size
-     beta=0.5,          # Covariate effect
-     covar=2.0,         # Covariate range
+    beta=0.5,          # Covariate effect
+    covariate_range=2.0,  # Covariate range
      model_cens="uniform",  # Censoring type
      cens_par=3.0       # Censoring parameter
  )

docs/source/index.md

@@ -22,7 +22,7 @@ pip install gen-surv
 Generate your first dataset:
 ```python
 from gen_surv import generate
-df = generate(model="cphm", n=100, beta=0.5, covar=2.0)
+df = generate(model="cphm", n=100, beta=0.5, covariate_range=2.0)
 ```
 ```
 
@@ -72,7 +72,7 @@ df = gs.generate(
     model="cphm", 
     n=500, 
     beta=0.5, 
-    covar=2.0,
+    covariate_range=2.0,
     model_cens="uniform", 
     cens_par=3.0
 )

docs/source/tutorials/basic_usage.md

@@ -15,7 +15,7 @@ import pandas as pd
      model="cphm",
      n=200,
      beta=0.7,
-     covar=1.5,
+    covariate_range=1.5,
      model_cens="exponential",
      cens_par=2.0,
      seed=42  # For reproducibility
@@ -43,7 +43,7 @@ All models share these parameters:
 Each model has unique parameters. For CPHM:
 
 - `beta`: Covariate effect (hazard ratio = exp(beta))
-- `covar`: Range for uniform covariate generation [0, covar]
+- `covariate_range`: Range for uniform covariate generation [0, covariate_range]
 
 ## Censoring Mechanisms
 
@@ -56,7 +56,7 @@ df_uniform = generate(
     model="cphm",
     n=100,
     beta=0.5,
-    covar=2.0,
+    covariate_range=2.0,
     model_cens="uniform",
     cens_par=3.0
 )
@@ -69,7 +69,7 @@ df_exponential = generate(
     model="cphm",
     n=100,
     beta=0.5,
-    covar=2.0,
+    covariate_range=2.0,
     model_cens="exponential",
     cens_par=2.0
 )
@@ -93,8 +93,8 @@ ax1.set_ylabel('Frequency')
 ax1.set_title('Distribution of Observed Times')
 
 # Event rate vs covariate
-df['covar_bin'] = pd.cut(df['covariate'], bins=5)
-event_rate = df.groupby('covar_bin')['status'].mean()
+df['covariate_bin'] = pd.cut(df['covariate'], bins=5)
+event_rate = df.groupby('covariate_bin')['status'].mean()
 event_rate.plot(kind='bar', ax=ax2, rot=45)
 ax2.set_ylabel('Event Rate')
 ax2.set_title('Event Rate by Covariate Level')
@@ -105,6 +105,6 @@ plt.show()
 
 ## Next Steps
 
-- Try different models: {doc}`model_comparison`
-- Learn advanced features: {doc}`advanced_features`  
-- See integration examples: {doc}`integration_examples`
+- Try different models (model_comparison)
+- Learn advanced features (advanced_features)
+- See integration examples (integration_examples)

docs/source/usage.md

@@ -21,10 +21,20 @@ This will create a virtual environment and install all required packages.
 Generate datasets directly in Python:
 
 ```python
-from gen_surv import generate
+from gen_surv import export_dataset, generate
 
 # Cox Proportional Hazards example
-generate(model="cphm", n=100, model_cens="uniform", cens_par=1.0, beta=0.5, covariate_range=2.0)
+df = generate(
+    model="cphm",
+    n=100,
+    model_cens="uniform",
+    cens_par=1.0,
+    beta=0.5,
+    covariate_range=2.0,
+)
+
+# Save to RDS for use in R
+export_dataset(df, "simulated_data.rds")
 ```
 
 You can also generate data from the command line:
@@ -47,3 +57,27 @@ make html
 
 The generated files will be available under `docs/build/html`.
 
+## Scikit-learn Integration
+
+You can wrap the generator in a transformer compatible with scikit-learn:
+
+```python
+from gen_surv import GenSurvDataGenerator
+
+est = GenSurvDataGenerator("cphm", n=10, beta=0.5, covariate_range=1.0)
+df = est.fit_transform()
+```
+
+## Lifelines and scikit-survival
+
+Datasets generated with **gen_surv** can be directly used with
+[lifelines](https://lifelines.readthedocs.io). For
+[scikit-survival](https://scikit-survival.readthedocs.io) you can convert the
+DataFrame using ``to_sksurv``:
+
+```python
+from gen_surv import to_sksurv
+
+struct = to_sksurv(df)
+```
+