feat(docs): document generic interface generate() and update examples

README.md

@@ -39,6 +39,21 @@ df = gen_cphm(
 print(df.head())
 ```
 
+```python
+from gen_surv import generate
+
+df = generate(
+    model="cphm",
+    n=100,
+    model_cens="uniform",
+    cens_par=1.0,
+    beta=0.5,
+    covar=2.0
+)
+
+print(df.head())
+```
+
 ## 🔧 Available Generators
 
 | Function     | Description                                |

docs/source/index.md

@@ -30,6 +30,21 @@ df = gen_cphm(n=100, model_cens="uniform", cens_par=1.0, beta=0.5, covar=2.0)
 print(df.head())
 ```
 
+```python
+from gen_surv import generate
+
+df = generate(
+    model="cphm",
+    n=100,
+    model_cens="uniform",
+    cens_par=1.0,
+    beta=0.5,
+    covar=2.0
+)
+
+print(df.head())
+```
+
 ## 🔗 Project Links
 
 - [Source Code](https://github.com/DiogoRibeiro7/genSurvPy)

docs/source/modules.md

@@ -16,6 +16,11 @@
       undoc-members: true
 
 ::: gen_surv.thmm
+    options:
+      members: true
+      undoc-members: true
+
+::: gen_surv.interface
     options:
       members: true
       undoc-members: true

gen_surv-stubs/gen_surv/__init__.pyi

@@ -0,0 +1 @@
+from .interface import generate as generate

gen_surv-stubs/gen_surv/__main__.pyi

@@ -0,0 +1,6 @@
+from gen_surv.cmm import gen_cmm as gen_cmm
+from gen_surv.cphm import gen_cphm as gen_cphm
+from gen_surv.tdcm import gen_tdcm as gen_tdcm
+from gen_surv.thmm import gen_thmm as gen_thmm
+
+def run_example(model: str): ...

gen_surv-stubs/gen_surv/bivariate.pyi

@@ -0,0 +1 @@
+def sample_bivariate_distribution(n, dist, corr, dist_par): ...

gen_surv-stubs/gen_surv/interface.pyi

@@ -0,0 +1,6 @@
+from gen_surv.cmm import gen_cmm as gen_cmm
+from gen_surv.cphm import gen_cphm as gen_cphm
+from gen_surv.tdcm import gen_tdcm as gen_tdcm
+from gen_surv.thmm import gen_thmm as gen_thmm
+
+def generate(model: str, **kwargs): ...

gen_surv-stubs/gen_surv/tdcm.pyi

@@ -1,3 +1,4 @@
+from gen_surv.bivariate import sample_bivariate_distribution as sample_bivariate_distribution
 from gen_surv.censoring import rexpocens as rexpocens, runifcens as runifcens
 from gen_surv.validate import validate_gen_tdcm_inputs as validate_gen_tdcm_inputs
 

gen_surv-stubs/gen_surv/validate.pyi

@@ -2,3 +2,4 @@ def validate_gen_cphm_inputs(n: int, model_cens: str, cens_par: float, covar: fl
 def validate_gen_cmm_inputs(n: int, model_cens: str, cens_par: float, beta: list, covar: float, rate: list): ...
 def validate_gen_tdcm_inputs(n: int, dist: str, corr: float, dist_par: list, model_cens: str, cens_par: float, beta: list, lam: float): ...
 def validate_gen_thmm_inputs(n: int, model_cens: str, cens_par: float, beta: list, covar: float, rate: list): ...
+def validate_dg_biv_inputs(n: int, dist: str, corr: float, dist_par: list): ...

gen_surv/__init__.py

@@ -0,0 +1 @@
+from .interface import generate

gen_surv/interface.py

@@ -0,0 +1,38 @@
+"""
+Interface module to unify access to all survival data generators.
+
+Example:
+    >>> from gen_surv import generate
+    >>> df = generate(model="cphm", n=100, model_cens="uniform", cens_par=1.0, beta=0.5, covar=2.0)
+"""
+
+from gen_surv.cphm import gen_cphm
+from gen_surv.cmm import gen_cmm
+from gen_surv.tdcm import gen_tdcm
+from gen_surv.thmm import gen_thmm
+
+
+_model_map = {
+    "cphm": gen_cphm,
+    "cmm": gen_cmm,
+    "tdcm": gen_tdcm,
+    "thmm": gen_thmm,
+}
+
+
+def generate(model: str, **kwargs):
+    """
+    Generic interface to generate survival data from various models.
+
+    Parameters:
+        model (str): One of ["cphm", "cmm", "tdcm", "thmm"]
+        **kwargs: Arguments forwarded to the selected model generator.
+
+    Returns:
+        pd.DataFrame: Simulated survival data.
+    """
+    model = model.lower()
+    if model not in _model_map:
+        raise ValueError(f"Unknown model '{model}'. Choose from {list(_model_map.keys())}.")
+
+    return _model_map[model](**kwargs)

pyproject.toml

@@ -8,7 +8,7 @@ readme = "README.md"
 packages = [{ include = "gen_surv" }]
 homepage = "https://github.com/DiogoRibeiro7/genSurvPy"
 repository = "https://github.com/DiogoRibeiro7/genSurvPy"
-documentation = "https://gen-surv.readthedocs.io/en/stable/"
+documentation = "https://gensurvpy.readthedocs.io/en/stable/"
 
 [tool.poetry.dependencies]
 python = "^3.9"

tests/test_interface.py

@@ -0,0 +1,16 @@
+from gen_surv import generate
+
+def test_generate_tdcm_runs():
+    df = generate(
+        model="tdcm",
+        n=10,
+        dist="weibull",
+        corr=0.5,
+        dist_par=[1, 2, 1, 2],
+        model_cens="uniform",
+        cens_par=1.0,
+        beta=[0.1, 0.2, 0.3],
+        lam=1.0
+    )
+    assert not df.empty
+