docs: add mathematical foundations page for all survival models

Author: DiogoRibeiro7

TODO.md

@@ -0,0 +1,63 @@
+# TODO – Roadmap for gen_surv
+
+This document outlines future enhancements, features, and ideas for improving the gen_surv package.
+
+---
+
+## 📦 1. Interface and UX
+
+- [ ] Create a `generate(..., return_type="df" | "dict")` interface
+- [ ] Add `__version__` using `importlib.metadata` or `poetry-dynamic-versioning`
+- [ ] Build a CLI with `typer` or `click`
+- [ ] Add example notebooks for each model (`notebooks/` folder)
+
+---
+
+## 📚 2. Documentation
+
+- [ ] Add a "Model Comparison Guide" section
+- [ ] Add "How It Works" sections for each model
+- [ ] Include usage tutorials in Jupyter format on RTD
+- [ ] Optional: add multilingual docs using `sphinx-intl`
+
+---
+
+## 🧪 3. Testing and Quality
+
+- [ ] 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)
+
+---
+
+## 🧠 4. Advanced Models
+
+- [ ] Add Piecewise Exponential Model support
+- [ ] Add competing risks / multi-event simulation
+- [ ] Implement parametric AFT models (log-normal, log-logistic)
+- [ ] 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
+
+---
+
+## 🌍 6. Ecosystem Integration
+
+- [ ] Add a `GenSurvDataGenerator` compatible with `sklearn`
+- [ ] Enable use with `lifelines`, `scikit-survival`, `sksurv`
+- [ ] Export in R-compatible formats (.csv, .rds)
+
+---
+
+## 🔁 7. Other Ideas
+
+- [ ] Add performance benchmarks for each model
+- [ ] Improve PyPI discoverability (add keywords)
+- [ ] Create a Streamlit or Gradio live demo

docs/source/index.md

@@ -18,6 +18,7 @@ It includes generators for:
 :caption: Contents
 
 modules
+theory
 ```
 
 

docs/source/theory.md

@@ -0,0 +1,89 @@
+# 📘 Mathematical Foundations of `gen_surv`
+
+This page presents the mathematical formulation behind the survival models implemented in the `gen_surv` package.
+
+---
+
+## 1. Cox Proportional Hazards Model (CPHM)
+
+The hazard function conditioned on covariates is:
+
+$$
+h(t \mid X) = h_0(t) \exp(X \\beta)
+$$
+
+Where:
+
+- \( h_0(t) \) is the baseline hazard
+- \( X \\beta \) is the linear predictor
+
+### Weibull baseline hazard:
+
+$$
+h_0(t) = \\lambda \\rho t^{\\rho - 1}
+$$
+
+The cumulative hazard is:
+
+$$
+\\Lambda_0(t) = \\lambda t^{\\rho}
+$$
+
+And the survival function becomes:
+
+$$
+S(t \mid X) = \\exp\\left(-\\Lambda_0(t) \\exp(X \\beta)\\right)
+$$
+
+---
+
+## 2. Time-Dependent Covariate Model (TDCM)
+
+A generalization of CPHM where covariates change over time:
+
+$$
+h(t \mid Z(t)) = h_0(t) \\exp(Z(t) \\beta)
+$$
+
+In this package, piecewise covariate values are simulated with dependence across segments using correlated normal draws.
+
+---
+
+## 3. Continuous-Time Multi-State Markov Model (CMM)
+
+Markov model with generator matrix \( Q \). The transition probability matrix is given by:
+
+$$
+P(t) = \\exp(Qt)
+$$
+
+Where:
+
+- \( Q \) is the rate matrix
+- \( P(t)_{ij} \) gives the probability of being in state j at time t given starting in state i
+
+---
+
+## 4. Time-Homogeneous Hidden Markov Model (THMM)
+
+This model simulates observed states with unobserved latent state transitions.
+
+Let:
+
+- \( S_t \) be the latent state at time t
+- \( Y_t \) be the observed variable conditional on \( S_t \)
+
+The transition structure is governed by a homogeneous Markov chain with transition matrix \( P \), and emissions are Gaussian:
+
+$$
+Y_t \mid S_t = k \\sim \\mathcal{N}(\\mu_k, \\sigma_k^2)
+$$
+
+---
+
+## Notes
+
+All models support censoring:
+
+- **Uniform:** \( C_i \\sim U(0, \\text{cens\\_par}) \)
+- **Exponential:** \( C_i \\sim \\text{Exp}(\\text{cens\\_par}) \)