pygformula

https://pygformula.readthedocs.io/en/latest/
Admin
pygformula is a Python package that implements the non-iterative conditional expectation (NICE)...
Tokens:68,313
Snippets:330
Trust Score:9.6
Update:1 day ago
Show doc for...
Tokens:
Raw
### Running example for uniform_grace_period

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Interventions.html

Complete example that loads data, defines covariates and models, and fits a ParametricGformula with a uniform grace period intervention. The intervention starts treatment within 3 time intervals when L1 equals 1.

```python
import numpy as np
from pygformula import ParametricGformula
from pygformula.interventions import uniform_grace_period
from pygformula.data import load_basicdata_nocomp

obs_data = load_basicdata_nocomp()
time_name = 't0'
id = 'id'

covnames = ['L1', 'L2', 'A']
covtypes = ['binary', 'bounded normal', 'binary']
covmodels = ['L1 ~ lag1_A + lag2_A + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0',
             'L2 ~ lag1_A + L1 + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0',
             'A ~ lag1_A + L1 + L2 + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0']

basecovs = ['L3']

time_points = np.max(np.unique(obs_data[time_name])) + 1

int_descript = ['uniform grace period intervention']

outcome_name = 'Y'
ymodel = 'Y ~ L1 + L2 + L3 + A + lag1_A + lag1_L1 + lag1_L2 + t0'

g = ParametricGformula(obs_data = obs_data, id = id, time_name=time_name,
            time_points = time_points, covnames=covnames, covtypes=covtypes,
            covmodels=covmodels, basecovs=basecovs,int_descript = int_descript,
            Intervention1_A = [uniform_grace_period, [3, {'L1': lambda x: x == 1}]],
            outcome_name=outcome_name, ymodel=ymodel, outcome_type='survival')
g.fit()
```

--------------------------------

### Install dependencies from requirements.txt

Source: https://pygformula.readthedocs.io/en/latest/Installation.html

Installs all dependencies listed in the requirements.txt file using pip.

```bash
pip install -r requirements.txt
```

--------------------------------

### Running example with compevent_restrictions

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Deterministic%20knowledge.html

Complete example from the running_examples/test_comp_restrictions.py file, demonstrating how to set up and run a ParametricGformula with compevent_restrictions for a survival outcome.

```python
from pygformula import ParametricGformula
from pygformula.interventions import static
from pygformula.data import load_basicdata

obs_data = load_basicdata()

covnames = ['L1', 'L2', 'A']
covtypes = ['binary', 'bounded normal', 'binary']
covmodels = ['L1 ~ lag1_A + lag2_A + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0',
             'L2 ~ lag1_A + L1 + lag_cumavg1_L1 + lag_cumavg1_L2  + L3 + t0',
             'A ~ lag1_A + L1 + L2 +lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0']

outcome_model = 'Y ~ A + L1 + L2 + L3 + lag1_A + lag1_L1 + lag1_L2'

time_name = 't0'
id = 'id'
outcome_name = 'Y'
basecovs = ['L3']

compevent_name = 'D'
compevent_model = 'D ~ A + L1 + L2 + L3 + t0'
compevent_cens = False

time_points = np.max(np.unique(obs_data[time_name])) + 1
int_descript = ['Never treat', 'Always treat']

compevent_restrictions = [[{'L1': lambda x: x == 0}, 0], [{'L2': lambda x: x > 0.5}, 0.1]]

g = ParametricGformula(obs_data = obs_data, id = id, time_points = time_points,
    time_name=time_name, int_descript = int_descript,
    Intervention1_A = [static, np.zeros(time_points)],
    Intervention2_A = [static, np.ones(time_points)],
    basecovs =basecovs, covnames=covnames,
    covtypes=covtypes, covmodels=covmodels,
    compevent_restrictions = compevent_restrictions,
    compevent_cens= compevent_cens, compevent_name = compevent_name,
    compevent_model=compevent_model, outcome_name=outcome_name,
    outcome_type='survival', ymodel=ymodel)
g.fit()
```

--------------------------------

### Load example dataset

Source: https://pygformula.readthedocs.io/en/latest/Get%20Started.html

Loads the simulated example dataset as a pandas DataFrame using the package's data loader.

```python
from pygformula.data import load_basicdata_nocomp
obs_data = load_basicdata_nocomp()
```

--------------------------------

### Running example with compevent_cens default (False)

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Competing%20event.html

Complete example using load_basicdata and static interventions, with competing event treated as censoring (default). The output is not shown.

```python
from pygformula import ParametricGformula
from pygformula.interventions import static
from pygformula.data import load_basicdata

obs_data = load_basicdata()

covnames = ['L1', 'L2', 'A']
covtypes = ['binary', 'bounded normal', 'binary']
covmodels = ['L1 ~ lag1_A + lag2_A + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0',
             'L2 ~ lag1_A + L1 + lag_cumavg1_L1 + lag_cumavg1_L2  + L3 + t0',
             'A ~ lag1_A + L1 + L2 +lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0']

ymodel = 'Y ~ A + L1 + L2 + L3 + lag1_A + lag1_L1 + lag1_L2'

time_name = 't0'
id = 'id'
outcome_name = 'Y'
basecovs = ['L3']

compevent_name = 'D'
compevent_model = 'D ~ A + L1 + L2 + L3 + t0'

time_points = np.max(np.unique(obs_data[time_name])) + 1
int_descript = ['Never treat', 'Always treat']

g = ParametricGformula(obs_data = obs_data, id = id, time_points = time_points,
              time_name=time_name, int_descript = int_descript,
              Intervention1_A = [static, np.zeros(time_points)],
              Intervention2_A = [static, np.ones(time_points)],
              basecovs =basecovs, covnames=covnames,
              covtypes=covtypes, covmodels=covmodels,
              compevent_name = compevent_name, compevent_model=compevent_model,
              outcome_name=outcome_name, outcome_type='survival', ymodel=ymodel)
g.fit()
```

--------------------------------

### Running example for categorical time

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Covariate%20models.html

Complete example using the 'test_categorical_time.py' running example. It loads basic data, defines categorical time with time_thresholds [1,3,5], and fits a parametric g-formula with two interventions.

```python
import numpy as np
from pygformula import ParametricGformula
from pygformula.interventions import static
from pygformula.data import load_basicdata_nocomp

obs_data = load_basicdata_nocomp()
time_name = 't0'
id = 'id'

covnames = ['L1', 'L2', 'A', 't0_f']
covtypes = ['binary', 'bounded normal', 'binary', 'categorical time']
covmodels = ['L1 ~ lag1_A + lag2_A + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0 + C(t0_f)',
           'L2 ~ lag1_A + L1 + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0 + C(t0_f)',
           'A ~ lag1_A + L1 + L2 + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0 + C(t0_f)',
           'NA']

time_thresholds = [1, 3, 5]

basecovs = ['L3']

outcome_name = 'Y'
ymodel = 'Y ~ L1 + L2 + L3 + A + lag1_A + lag1_L1 + lag1_L2 + t0'
outcome_type = 'survival'

time_points = np.max(np.unique(obs_data[time_name])) + 1
int_descript = ['Never treat', 'Always treat']

g = ParametricGformula(obs_data = obs_data, id = id, time_name=time_name,
    time_points = time_points, time_thresholds = time_thresholds,
    int_descript = int_descript,
    Intervention1_A = [static, np.zeros(time_points)],
    Intervention2_A = [static, np.ones(time_points)],
    covnames=covnames, covtypes=covtypes,
    covmodels=covmodels, basecovs=basecovs,
    outcome_name=outcome_name, ymodel=ymodel, outcome_type=outcome_type)
g.fit()
```

--------------------------------

### Running example for threshold intervention

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Interventions.html

Complete example using the threshold intervention with the load_threshold_data dataset, specifying covariates, models, and outcome.

```python
import numpy as np
from pygformula import ParametricGformula
from pygformula.interventions import threshold
from pygformula.data import load_threshold_data

obs_data = load_threshold_data()
time_name = 't0'
id = 'id'

covnames = ['L1', 'L2', 'A']
covtypes = ['binary', 'bounded normal', 'normal']
covmodels = ['L1 ~ lag1_L1',
             'L2 ~ lag1_L1 + lag1_L2 + L1',
             'A ~ L1 + L2']

time_points = np.max(np.unique(obs_data[time_name])) + 1

int_descript = ['Threshold intervention']

outcome_name = 'Y'
ymodel = 'Y ~ L1 + L2 + A'

g = ParametricGformula(obs_data = obs_data, id = id, time_name=time_name,
              time_points = time_points, covnames=covnames, covtypes=covtypes,
              covmodels=covmodels, int_descript = int_descript,
              Intervention1_A = [threshold, [0.5, float('inf')]],
              outcome_name=outcome_name, ymodel=ymodel, outcome_type='survival')
g.fit()
```

--------------------------------

### Install pygformula package

Source: https://pygformula.readthedocs.io/en/latest/Installation.html

Installs the pygformula package using pip.

```bash
pip install pygformula
```

--------------------------------

### Running example with yrestrictions

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Deterministic%20knowledge.html

Complete example using ParametricGformula with yrestrictions, including data loading, model specification, interventions, and fitting. The output is not shown in the source.

```python
from pygformula import ParametricGformula
from pygformula.interventions import static
from pygformula.data import load_basicdata_nocomp

obs_data = load_basicdata_nocomp()

time_name = 't0'
id = 'id'

covnames = ['L1', 'L2', 'A']
covtypes = ['binary', 'normal', 'binary']
covmodels = ['L1 ~ lag1_L1 + lag1_A',
             'L2 ~ L1 + lag1_L2',
              'A ~ L1 + L2']

basecovs = ['L3']
outcome_name = 'Y'
ymodel = 'Y ~ L1 + L2 + A'

# define interventions
time_points = np.max(np.unique(obs_data[time_name])) + 1
int_descript = ['Never treat', 'Always treat']

yrestrictions = [[{'L1': lambda x: x == 0}, 0], [{'L2': lambda x: x > 0.5}, 0.1]]

g = ParametricGformula(obs_data = obs_data, id = id, time_name=time_name,
    time_points = time_points,
    int_descript = int_descript,
    Intervention1_A = [static, np.zeros(time_points)],
    Intervention2_A = [static, np.ones(time_points)],
    covnames=covnames,  covtypes=covtypes, covmodels=covmodels, basecovs=basecovs,
    yrestrictions=yrestrictions, outcome_name=outcome_name,
    ymodel=ymodel, outcome_type='survival')
g.fit()
```

--------------------------------

### Running example for hazard ratio

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Hazard%20ratio.html

Complete example using ParametricGformula to calculate hazard ratio between 'Never treat' and 'Always treat' interventions. Requires the pygformula package and the data from load_basicdata_nocomp.

```python
from pygformula import ParametricGformula
from pygformula.interventions import static
from pygformula.data import load_basicdata_nocomp

obs_data = load_basicdata_nocomp()
time_name = 't0'
id = 'id'

covnames = ['L2', 'A']
covtypes = ['bounded normal', 'binary']
covmodels = ['L2 ~ lag1_A + lag_cumavg1_L2 + L3 + t0',
           'A ~ lag1_A + L2 + lag_cumavg1_L2 + L3 + t0']

basecovs = ['L3']

outcome_name = 'Y'
ymodel = 'Y ~ L2 + A + lag1_A + L3 + t0'
outcome_type = 'survival'

time_points = np.max(np.unique(obs_data[time_name])) + 1
int_descript = ['Never treat', 'Always treat']

g = ParametricGformula(obs_data = obs_data, id = id, time_name=time_name,
    time_points = time_points,
    int_descript = int_descript, intcomp=[1, 2],
    Intervention1_A = [static, np.zeros(time_points)],
    Intervention2_A = [static, np.ones(time_points)],
    covnames=covnames, covtypes=covtypes,
    covmodels=covmodels, basecovs=basecovs,
    outcome_name=outcome_name, ymodel=ymodel, outcome_type=outcome_type)
g.fit()
```

--------------------------------

### Sample syntax for natural_grace_period with single condition

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Interventions.html

Example of specifying a natural grace period intervention with a single condition: when L1 equals 1, start treatment within a grace period of duration 3.

```python
from pygformula.interventions import natural_grace_period

int_descript = ['natural grace period intervention']

g = ParametricGformula(..., int_descript = int_descript,
    Intervention1_A = [natural_grace_period, [3, {'L1': lambda x: x == 1}]], ...)
```

--------------------------------

### Running example for natural_grace_period

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Interventions.html

Complete running example of a natural grace period intervention using the basic data without competing events. It sets up the ParametricGformula with covariates, models, and the intervention, then fits the model.

```python
import numpy as np
from pygformula import ParametricGformula
from pygformula.interventions import natural_grace_period
from pygformula.data import load_basicdata_nocomp

obs_data = load_basicdata_nocomp()
time_name = 't0'
id = 'id'

covnames = ['L1', 'L2', 'A']
covtypes = ['binary', 'bounded normal', 'binary']
covmodels = ['L1 ~ lag1_A + lag2_A + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0',
             'L2 ~ lag1_A + L1 + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0',
             'A ~ lag1_A + L1 + L2 + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0']

basecovs = ['L3']

time_points = np.max(np.unique(obs_data[time_name])) + 1

int_descript = ['natural grace period intervention']

outcome_name = 'Y'
ymodel = 'Y ~ L1 + L2 + L3 + A + lag1_A + lag1_L1 + lag1_L2 + t0'

g = ParametricGformula(obs_data = obs_data, id = id, time_name=time_name,
               time_points = time_points,covnames=covnames, covtypes=covtypes,
               covmodels=covmodels, basecovs=basecovs, int_descript = int_descript,
               Intervention1_A = [natural_grace_period, [3, {'L1': lambda x: x == 1}]],
               outcome_name=outcome_name, ymodel=ymodel, outcome_type='survival')
g.fit()
```

--------------------------------

### Running example: full pygformula analysis

Source: https://pygformula.readthedocs.io/en/latest/Get%20Started.html

This complete script demonstrates a parametric g-formula analysis with a survival outcome. It loads example data, defines covariates and models, specifies two static interventions (never treat and always treat), fits the model, and generates plots. The example uses 20 samples and parallel processing with 8 cores.

```python
import numpy as np
from pygformula import ParametricGformula
from pygformula.interventions import static
from pygformula.data import load_basicdata_nocomp

obs_data = load_basicdata_nocomp()
time_name = 't0'
id = 'id'

covnames = ['L1', 'L2', 'A']
covtypes = ['binary', 'bounded normal', 'binary']
covmodels = ['L1 ~ lag1_A + lag2_A + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0',
           'L2 ~ lag1_A + L1 + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0',
           'A ~ lag1_A + L1 + L2 + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0']

basecovs = ['L3']

outcome_name = 'Y'
ymodel = 'Y ~ L1 + L2 + L3 + A + lag1_A + lag1_L1 + lag1_L2 + t0'
outcome_type = 'survival'

time_points = np.max(np.unique(obs_data[time_name])) + 1
int_descript = ['Never treat', 'Always treat']

g = ParametricGformula(obs_data = obs_data, id = id, time_name=time_name,
             time_points = time_points, int_descript = int_descript,
             covnames=covnames, covtypes=covtypes,
             covmodels=covmodels, basecovs=basecovs,
             outcome_name=outcome_name, ymodel=ymodel, outcome_type=outcome_type,
             Intervention1_A = [static, np.zeros(time_points)],
             Intervention2_A = [static, np.ones(time_points)],
             nsamples=20, parallel=True, ncores=8)
g.fit()
g.plot_natural_course()
g.plot_interventions()
```

--------------------------------

### Running example for zero-inflated normal covariate

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Covariate%20models.html

Complete example using the load_zero_inflated_normal dataset. It sets up a parametric g-formula with two interventions (never treat and always treat) and fits the model.

```python
import numpy as np
from pygformula import ParametricGformula
from pygformula.interventions import static
from pygformula.data import load_zero_inflated_normal

obs_data = load_zero_inflated_normal()
time_name = 't0'
id = 'id'

covnames = ['L', 'A']
covtypes = ['zero-inflated normal', 'binary']
covmodels = ['L ~ lag1_L + lag1_A + t0',
              'A ~ lag1_A + L + t0']

outcome_name = 'Y'
ymodel = 'Y ~ L + A + t0'
outcome_type = 'survival'

time_points = np.max(np.unique(obs_data[time_name])) + 1
int_descript = ['Never treat', 'Always treat']

g = ParametricGformula(obs_data = obs_data, id = id, time_name=time_name,
             time_points = time_points, int_descript = int_descript,
             Intervention1_A = [static, np.zeros(time_points)],
             Intervention2_A = [static, np.ones(time_points)],
             covnames=covnames, covtypes=covtypes, covmodels=covmodels,
             outcome_name=outcome_name, ymodel=ymodel, outcome_type=outcome_type)
g.fit()
```

--------------------------------

### Running example for binary_eof outcome

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Outcome%20model.html

Complete example that loads the binary_eof dataset, defines covariates and models, and fits the parametric g-formula with a threshold intervention on A.

```python
import numpy as np
from pygformula import ParametricGformula
from pygformula.interventions import threshold
from pygformula.data import load_binary_eof

obs_data = load_binary_eof()
time_name = 't0'
id = 'id'

covnames = ['L1', 'L2', 'A']
covtypes = ['binary', 'zero-inflated normal', 'normal']
covmodels = ['L1 ~ lag1_A + lag2_A + lag_cumavg1_L1 + L3 + t0',
             'L2 ~ lag1_A + L1 + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0',
             'A ~ lag1_A + L1 + L2 + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0']

basecovs = ['L3']

outcome_name = 'Y'
ymodel = 'Y ~ L1 + A + lag1_A + lag1_L1 + L3 + t0'
outcome_type = 'binary_eof'

int_descript = ['Threshold intervention']

g = ParametricGformula(obs_data = obs_data, id = id, time_name=time_name,
    int_descript = int_descript,
    Intervention1_A = [threshold, [0.5, float('inf')]],
    covnames=covnames, covtypes=covtypes,
    covmodels=covmodels, basecovs=basecovs,
    outcome_name=outcome_name, ymodel=ymodel, outcome_type=outcome_type)
g.fit()
```

--------------------------------

### Running example: dynamic intervention with pygformula

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Interventions.html

Complete example of running a parametric g-formula with a custom dynamic intervention. It loads the basic dataset, defines the dynamic intervention function, and fits the model with survival outcome.

```python
from pygformula import ParametricGformula
from pygformula.data import load_basicdata_nocomp

obs_data = load_basicdata_nocomp()
time_name = 't0'
id = 'id'

covnames = ['L1', 'L2', 'A']
covtypes = ['binary', 'bounded normal', 'binary']
covmodels = ['L1 ~ lag1_A + lag2_A + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0',
             'L2 ~ lag1_A + L1 + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0',
             'A ~ lag1_A + L1 + L2 + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0']

basecovs = ['L3']

time_points = np.max(np.unique(obs_data[time_name])) + 1

def dynamic_intervention(new_df, pool, int_var, time_name, t):
    new_df.loc[new_df[time_name] == t, int_var] = 0
    new_df.loc[new_df['L2'] > 0.75, int_var] = 1

int_descript = ['Dynamic intervention']

outcome_name = 'Y'
ymodel = 'Y ~ L1 + L2 + L3 + A + lag1_A + lag1_L1 + lag1_L2 + t0'

g = ParametricGformula(obs_data = obs_data, id = id, time_name=time_name,
             time_points = time_points, covnames=covnames, covtypes=covtypes,
             covmodels=covmodels, basecovs=basecovs, int_descript = int_descript,
             Intervention1_A = [dynamic_intervention],
             outcome_name=outcome_name, ymodel=ymodel, outcome_type='survival')
g.fit()
```

--------------------------------

### Install cmprsk R package

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Hazard%20ratio.html

Run this command in the R environment to install the cmprsk package, required for hazard ratio calculation with competing events.

```R
install.packages("cmprsk")
```

--------------------------------

### Running example of static intervention on one treatment variable

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Interventions.html

Example of applying a static intervention to a single treatment variable (A) using the ParametricGformula class. The intervention sets A to 1 at all time points.

```python
import numpy as np
from pygformula import ParametricGformula
from pygformula.interventions import static
from pygformula.data import load_basicdata_nocomp

obs_data = load_basicdata_nocomp()
time_name = 't0'
id = 'id'

covnames = ['L1', 'L2', 'A']
covtypes = ['binary', 'bounded normal', 'binary']
covmodels = ['L1 ~ lag1_A + lag2_A + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0',
             'L2 ~ lag1_A + L1 + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0',
             'A ~ lag1_A + L1 + L2 + lag_cumavg1_L1 + lag_cumavg1_L2 + L3 + t0']

basecovs = ['L3']

time_points = np.max(np.unique(obs_data[time_name])) + 1
int_descript = ['Always treat']

outcome_name = 'Y'
ymodel = 'Y ~ L1 + L2 + L3 + A + lag1_A + lag1_L1 + lag1_L2 + t0'

g = ParametricGformula(obs_data = obs_data, id = id, time_name=time_name,
              time_points = time_points, covnames=covnames, covtypes=covtypes,
              covmodels=covmodels, basecovs=basecovs, int_descript = int_descript,
              Intervention1_A = [static, np.ones(time_points), [0, 1, 4]],
              outcome_name=outcome_name, ymodel=ymodel, outcome_type='survival')
g.fit()
```

--------------------------------

### Running example for censoring event

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Censoring%20event.html

Complete example using load_censor_data to fit a g-formula with censoring. It specifies covariates, models, and interventions for never and always treat scenarios.

```python
import numpy as np
from pygformula import ParametricGformula
from pygformula.interventions import static
from pygformula.data import load_censor_data

obs_data = load_censor_data()
time_name = 't0'
id = 'id'

covnames = ['L', 'A']
covtypes = ['binary', 'normal']

covmodels = ['L ~ lag1_L + t0',
             'A ~ lag1_A + L + t0']

outcome_name = 'Y'
ymodel = 'Y ~ A + L'

censor_name = 'C'
censor_model = 'C ~ A + L'

time_points = np.max(np.unique(obs_data[time_name])) + 1
int_descript = ['Never treat', 'Always treat']

g = ParametricGformula(obs_data = obs_data, id = id, time_name=time_name,
    time_points = time_points,
    int_descript=int_descript,
    Intervention1_A = [static, np.zeros(time_points)],
    Intervention2_A = [static, np.ones(time_points)],
    censor_name= censor_name, censor_model=censor_model,
    covnames = covnames, covtypes = covtypes, covmodels = covmodels,
    outcome_name=outcome_name, ymodel=ymodel, outcome_type='survival')
g.fit()
```

--------------------------------

### Running example for binary covariate model

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Covariate%20models.html

Complete example using the pygformula API to fit a parametric g-formula with a binary covariate 'L1'. It loads sample data, defines interventions, and runs the model.

```python
import numpy as np
from pygformula import ParametricGformula
from pygformula.interventions import static
from pygformula.data import load_basicdata_nocomp

obs_data = load_basicdata_nocomp()
time_name = 't0'
id = 'id'

covnames = ['L1', 'A']
covtypes = ['binary', 'binary']
covmodels = ['L1 ~ lag1_A + lag2_A + lag_cumavg1_L1 + L3 + t0',
           'A ~ lag1_A + L1 + lag_cumavg1_L1 + L3 + t0']

basecovs = ['L3']

outcome_name = 'Y'
ymodel = 'Y ~ L1 + A + lag1_A + lag1_L1 + L3 + t0'
outcome_type = 'survival'

time_points = np.max(np.unique(obs_data[time_name])) + 1
int_descript = ['Never treat', 'Always treat']

g = ParametricGformula(obs_data = obs_data, id = id, time_name=time_name,
             time_points = time_points, int_descript = int_descript,
             Intervention1_A = [static, np.zeros(time_points)],
             Intervention2_A = [static, np.ones(time_points)],
             covnames=covnames, covtypes=covtypes,
             covmodels=covmodels, basecovs=basecovs,
             outcome_name=outcome_name, ymodel=ymodel, outcome_type=outcome_type)
g.fit()
```

--------------------------------

### Running example of a static intervention on multiple treatment variables

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Interventions.html

Example of applying static interventions to two treatment variables (A1 and A2) simultaneously using the ParametricGformula class. Both interventions set the treatments to 1 at all time points.

```python
import numpy as np
from pygformula import ParametricGformula
from pygformula.interventions import static
from pygformula.data import load_multiple_treatments_data

obs_data = load_multiple_treatments_data()
time_name = 't0'
id = 'id'

covnames = ['L1', 'L2', 'A1', 'A2']
covtypes = ['binary', 'bounded normal', 'binary', 'binary']
covmodels = ['L1 ~ lag1_L1',
             'L2 ~ lag1_L1 + lag1_L2 + lag1_A2 + L1',
             'A1 ~ lag1_L1 + lag1_L2',
             'A2 ~ lag1_A1']

time_points = np.max(np.unique(obs_data[time_name])) + 1
int_descript = ['Always treat on A1 & A2']


outcome_name = 'Y'
ymodel = 'Y ~ L1 + L2 + A1 + A2'

g = ParametricGformula(obs_data = obs_data, id = id, time_name=time_name,
             time_points = time_points, covnames=covnames, covtypes=covtypes,
             covmodels=covmodels, int_descript = int_descript,
             Intervention1_A1 = [static, np.ones(time_points)],
             Intervention1_A2 = [static, np.ones(time_points)],
             outcome_name=outcome_name, ymodel=ymodel, outcome_type='survival')
g.fit()
```

--------------------------------

### Running example for restrictions

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Deterministic%20knowledge.html

Complete example loading data, defining covariates, models, interventions, and restrictions, then fitting the parametric g-formula. The restrictions set L2 to 0.5 when L1 is 0, and A to 1 when L1 is 0 and L2 > 0.5.

```python
import numpy as np
from pygformula.interventions import static
from pygformula import ParametricGformula
from pygformula.data import load_basicdata_nocomp

obs_data = load_basicdata_nocomp()

time_name = 't0'
id = 'id'

covnames = ['L1', 'L2', 'A']
covtypes = ['binary', 'normal', 'binary']
covmodels = ['L1 ~ lag1_L1 + lag1_A',
             'L2 ~ L1 + lag1_L2',
              'A ~ L1 + L2']

basecovs = ['L3']
outcome_name = 'Y'
ymodel = 'Y ~ L1 + L2 + A'

# define interventions
time_points = np.max(np.unique(obs_data[time_name])) + 1
int_descript = ['Never treat', 'Always treat']

restrictions = [['L2', {'L1': lambda x: x == 0}, 0.5], ['A', {'L1': lambda x: x == 0, 'L2': lambda x: x > 0.5}, 1]]

g = ParametricGformula(obs_data = obs_data, id = id, time_name=time_name,
    time_points = time_points,
    int_descript = int_descript,
    Intervention1_A = [static, np.zeros(time_points)],
    Intervention2_A = [static, np.ones(time_points)],
    covnames=covnames, covtypes=covtypes,
    covmodels=covmodels, basecovs=basecovs,
    restrictions=restrictions, outcome_name=outcome_name,
    ymodel=ymodel, outcome_type='survival')
g.fit()
```

--------------------------------

### Running example for normal covariate model

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Covariate%20models.html

Complete example using the pygformula API to fit a parametric g-formula with a normal covariate 'L2'. It loads sample data, defines interventions, and runs the model.

```python
import numpy as np
from pygformula import ParametricGformula
from pygformula.interventions import static
from pygformula.data import load_basicdata_nocomp

obs_data = load_basicdata_nocomp()
time_name = 't0'
id = 'id'

covnames = ['L2', 'A']
covtypes = ['normal', 'binary']
covmodels = ['L2 ~ lag1_A + lag_cumavg1_L2 + L3 + t0',
           'A ~ lag1_A + L2 + lag_cumavg1_L2 + L3 + t0']

basecovs = ['L3']

outcome_name = 'Y'
ymodel = 'Y ~ L2 + A + lag1_A + L3 + t0'
outcome_type = 'survival'

time_points = np.max(np.unique(obs_data[time_name])) + 1
int_descript = ['Never treat', 'Always treat']

g = ParametricGformula(obs_data = obs_data, id = id, time_name=time_name,
          time_points = time_points, int_descript = int_descript,
          Intervention1_A = [static, np.zeros(time_points)],
          Intervention2_A = [static, np.ones(time_points)],
          covnames=covnames, covtypes=covtypes,
          covmodels=covmodels, basecovs=basecovs,
          outcome_name=outcome_name, ymodel=ymodel, outcome_type=outcome_type)
g.fit()
```

--------------------------------

### Running example for continuous end-of-follow-up outcome

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Outcome%20model.html

Complete example using the load_continuous_eof dataset. It defines covariates, base covariates, outcome model, and two static interventions (never treat vs always treat). The model is fitted with ParametricGformula.fit().

```python
import numpy as np
from pygformula import ParametricGformula
from pygformula.interventions import static
from pygformula.data import load_continuous_eof

obs_data = load_continuous_eof()
time_name = 't0'
id = 'id'

covnames = ['L1', 'L2', 'A']
covtypes = ['categorical', 'normal', 'binary']
covmodels = ['L1 ~ C(lag1_L1) + lag1_L2 + t0',
             'L2 ~ lag1_L2 + C(lag1_L1) + lag1_A + t0',
              'A ~ C(L1) + L2 + t0']

basecovs = ['L3']

outcome_name = 'Y'
outcome_model = 'Y ~ C(L1) + L2 + A'
outcome_type = 'continuous_eof'

time_points = np.max(np.unique(obs_data[time_name])) + 1
int_descript = ['Never treat', 'Always treat']

g = ParametricGformula(obs_data = obs_data, id = id, time_name=time_name,
    int_descript=int_descript,
    Intervention1_A = [static, np.zeros(time_points)],
    Intervention2_A = [static, np.ones(time_points)],
    covnames=covnames, covtypes=covtypes,
    covmodels=covmodels, basecovs=basecovs,
    outcome_name=outcome_name, ymodel=ymodel, outcome_type=outcome_type)
g.fit()
```

--------------------------------

### Running example with custom ymodel functions

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Outcome%20model.html

Complete example using ParametricGformula with custom fit and predict functions. Loads continuous end-of-follow-up data, defines covariates, interventions, and runs the g-formula. Note: categorical covariates in custom functions require additional processing.

```python
import numpy as np
import pygformula
from pygformula import ParametricGformula
from pygformula.interventions import static
from pygformula.data import load_continuous_eof

obs_data = load_continuous_eof()

time_name = 't0'
id = 'id'

covnames = ['L1', 'L2', 'A']
covtypes = ['categorical', 'normal', 'binary']
covmodels = ['L1 ~ C(lag1_L1) + lag1_L2 + t0',
             'L2 ~ lag1_L2 + C(lag1_L1) + lag1_A + t0',
              'A ~ C(L1) + L2 + t0']

basecovs = ['L3']

outcome_name = 'Y'

ymodel = 'Y ~ lag1_L2 + L2 + lag1_A + A'

# define interventions
time_points = np.max(np.unique(obs_data[time_name])) + 1
int_descript = ['Never treat', 'Always treat']


def ymodel_fit_custom(ymodel, fit_data):
    y_name, x_name = re.split('~', ymodel.replace(' ', ''))
    x_name = re.split('\+', x_name.replace(' ', ''))
    # get feature and target data to fit ymodel
    y = fit_data[y_name].to_numpy()
    X = fit_data[x_name].to_numpy()
    fit_rf = RandomForestRegressor()
    fit_rf.fit(X, y)
    return fit_rf

def ymodel_predict_custom(ymodel, new_df, fit):
    y_name, x_name = re.split('~', ymodel.replace(' ', ''))
    x_name = re.split('\+', x_name.replace(' ', ''))
    # get feature data to predict
    X = new_df[x_name].to_numpy()
    prediction = fit.predict(X)
    return prediction


g = ParametricGformula(obs_data = obs_data, id = id, time_name=time_name, time_points = time_points,
             int_descript = int_descript,
             Intervention1_A = [static, np.zeros(time_points)], basecovs=['L3'],
             Intervention2_A = [static, np.ones(time_points)],
             covnames=covnames,  covtypes=covtypes, covmodels=covmodels,
             ymodel_fit_custom = ymodel_fit_custom, ymodel_predict_custom=ymodel_predict_custom,
             outcome_name=outcome_name, ymodel=ymodel, outcome_type='continuous_eof')
g.fit()
```

--------------------------------

### Running example: random forest custom covariate model

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Covariate%20models.html

Complete example using a random forest custom covariate model with pygformula. It loads data, defines covariate specifications, custom fit and predict functions, and fits a ParametricGformula with two interventions (never treat and always treat).

```python
import numpy as np
import re
from sklearn.ensemble import RandomForestRegressor
from pygformula import ParametricGformula
from pygformula.interventions import static
from pygformula.data import load_basicdata_nocomp

obs_data = load_basicdata_nocomp()

time_name = 't0'
id = 'id'

covnames = ['L1', 'L2', 'A']
covtypes = ['binary', 'custom', 'binary']
covmodels = ['L1 ~ lag1_A + lag2_A + lag1_L1 + lag_cumavg1_L2 + t0',
             'L2 ~ lag1_A + L1 + lag1_L1 + lag_cumavg1_L2 + t0',
             'A ~ lag1_A + L1 + L2 +lag1_L1 + lag_cumavg1_L2 + t0']

outcome_name = 'Y'
ymodel = 'Y ~ L1 + L2 + A'

time_points = np.max(np.unique(obs_data[time_name])) + 1
int_descript = ['Never treat', 'Always treat']

def fit_rf(covmodel, covname, fit_data):
    max_depth = 2
    y_name, x_name = re.split('~', covmodel.replace(' ', ''))
    x_name = re.split('\+', x_name.replace(' ', ''))
    y = fit_data[y_name].to_numpy()
    X = fit_data[x_name].to_numpy()
    fit_rf = RandomForestRegressor(max_depth=max_depth, random_state=0)
    fit_rf.fit(X, y)
    return fit_rf

def predict_rf(covmodel, new_df, fit):
    y_name, x_name = re.split('~', covmodel.replace(' ', ''))
    x_name = re.split('\+', x_name.replace(' ', ''))
    X = new_df[x_name].to_numpy()
    prediction = fit.predict(X)
    return prediction

covfits_custom = ['NA', fit_rf, 'NA']
covpredict_custom = ['NA', predict_rf, 'NA']

g = ParametricGformula(obs_data = obs_data, id = id, time_name=time_name,
            time_points = time_points, int_descript = int_descript,
            Intervention1_A = [static, np.zeros(time_points)],
            Intervention2_A = [static, np.ones(time_points)],
            covnames=covnames,  covtypes=covtypes, covmodels=covmodels,
            covfits_custom = covfits_custom, covpredict_custom=covpredict_custom,
            outcome_name=outcome_name, ymodel=ymodel, outcome_type='survival')
g.fit()
```

--------------------------------

### Download example dataset with load_basicdata_nocomp

Source: https://pygformula.readthedocs.io/en/latest/Datasets.html

Use this command to download the 'example_data_basicdata_nocomp' dataset. It imports the loader function from pygformula.data.

```python
from pygformula.data import load_basicdata_nocomp
```

--------------------------------

### Install rpy2 Python package

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Hazard%20ratio.html

Install the rpy2 package in the Python environment to interface with R for hazard ratio calculations.

```bash
pip install rpy2
```

--------------------------------

### Sample syntax for threshold intervention

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Interventions.html

Shows how to specify a threshold intervention in the int_descript argument and the Intervention1_A parameter with a two-element list of threshold values.

```python
int_descript = ['Threshold intervention']

g = ParametricGformula(..., int_descript = int_descript,
    Intervention1_A = [threshold, [0.5, float('inf')]], ...)
```

--------------------------------

### Install cmprsk Python package

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Hazard%20ratio.html

Install the cmprsk package in the Python environment, required for subdistribution hazard ratio with competing events.

```bash
pip install cmprsk
```

--------------------------------

### Sample syntax for uniform_grace_period intervention

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Interventions.html

Shows how to specify a uniform grace period intervention with a duration of 3 and a condition on L1. The int_descript list and Intervention1_A argument are used in ParametricGformula.

```python
from pygformula.interventions import uniform_grace_period

int_descript = ['uniform grace period intervention']

g = ParametricGformula(..., int_descript = int_descript,
    Intervention1_A = [uniform_grace_period, [3, {'L1': lambda x: x == 1}]], ...)
```

--------------------------------

### Custom Predict Function Example

Source: https://pygformula.readthedocs.io/en/latest/Specifications/Covariate%20models.html

Example of a user-defined predict function for a custom covariate type. It takes covmodel, new_df, and fit as input and returns a list of predicted values.

```APIDOC
## Custom Predict Function

### Description
A user-defined function to predict covariate values at time t using a fitted custom model. It should accept the parameters `covmodel`, `new_df`, and `fit` and return a list of predicted values.

### Parameters
- **covmodel** (string) - Required - Model statement of the covariate.
- **new_df** (DataFrame) - Required - Simulated data at time t.
- **fit** (object) - Required - Fitted model from the custom fit function.

### Returns
- **predictions** (list) - List of predicted values at time t.

### Example
```python
def predict_rf(covmodel, new_df, fit):
    y_name, x_name = re.split('~', covmodel.replace(' ', ''))
    x_name = re.split('\+', x_name.replace(' ', ''))
    X = new_df[x_name].to_numpy()
    prediction = fit.predict(X)
    return prediction
```
```
Tokens:
Raw