### Install pymsm in development mode

Source: https://github.com/hrossman/pymsm/blob/main/CONTRIBUTING.md

Clones the repository, navigates to the project directory, and installs the library in editable mode using pip. This is the first step to setting up a local development environment.

```bash
git clone https://github.com/your-username-here/pymsm.git
cd pymsm
pip install -e .
```

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

### Serve documentation locally with mkdocs

Source: https://github.com/hrossman/pymsm/blob/main/CONTRIBUTING.md

Installs documentation dependencies and serves the documentation locally using mkdocs. This allows developers to preview changes to the documentation in a web browser.

```bash
pip install -r docs/requirements.txt
mkdocs serve
```

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

### Install PyMSM from GitHub development version

Source: https://github.com/hrossman/pymsm/blob/main/README.md

This describes how to install the latest development version of PyMSM directly from its GitHub repository. It involves cloning the repository, navigating to the correct directory, and using an editable install. This method is useful for accessing the newest features or testing unreleased changes.

```bash
# Clone the repository to REPO_FOLDER (choose your own location)
# cd $REPO_FOLDER
# pip install -e pymsm
```

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

### Install PyMSM Package

Source: https://github.com/hrossman/pymsm/blob/main/docs/index.md

This command installs the PyMSM package using pip. It requires Python version 3.8 or higher. Ensure you have pip installed and updated.

```console
pip install pymsm
```

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

### Load and Plot Rotterdam Dataset with pymsm

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/Rotterdam_example.ipynb

Loads the Rotterdam dataset and plots it using functions from the pymsm package. This involves preparing the dataset and visualizing its structure.

```python
from pymsm.datasets import prep_rotterdam, plot_rotterdam
dataset, state_labels = prep_rotterdam()
plot_rotterdam(dataset, state_labels)
```

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

### Initialize and Fit Multi-State Model with pymsm

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/Rotterdam_example.ipynb

Initializes a MultiStateModel from the pymsm package with the prepared dataset and terminal states, then fits the model. This process involves defining the model structure and allowing it to learn from the data.

```python
from pymsm.multi_state_competing_risks_model import MultiStateModel

multi_state_model = MultiStateModel(
    dataset=dataset, 
    terminal_states=terminal_states, 
    update_covariates_fn=default_update_covariates_function,
    state_labels=state_labels
)

multi_state_model.fit()
```

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

### Quick Example: Fit Multistate Model and Run Simulation in Python

Source: https://github.com/hrossman/pymsm/blob/main/docs/index.md

Demonstrates how to load data, define terminal states, initialize and fit a MultistateModel, and run Monte-Carlo simulations for path prediction. It uses sample data and custom settings for simulation.

```python
# Load data (See Rotterdam example for full details)
from pymsm.datasets import prep_rotterdam
dataset, states_labels = prep_rotterdam()

# Define terminal states
terminal_states = [3]

#Init MultistateModel
from pymsm.multi_state_competing_risks_model import MultiStateModel
multi_state_model = MultiStateModel(dataset,terminal_states)

# Fit model to data
multi_state_model.fit()

# Run Monte-Carlo simulation and sample paths
mcs = multi_state_model.run_monte_carlo_simulation(
              sample_covariates = dataset[0].covariates.values,
              origin_state = 1,
              current_time = 0,
              max_transitions = 2,
              n_random_samples = 10,
              print_paths=True)

```

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

### Run tests with pytest

Source: https://github.com/hrossman/pymsm/blob/main/CONTRIBUTING.md

Installs the pytest testing framework and executes all tests within the project. This command is used to verify code changes and ensure the library's integrity.

```bash
pip install pytest
pytest
```

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

### Load and Inspect Rotterdam Dataset (Python)

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/Preparing_a_dataset.ipynb

Loads the example Rotterdam dataset provided by PyMSM and prints the types of the dataset and its elements. This helps in understanding the structure of the dataset when using a list of PathObjects.

```python
from pymsm.datasets import prep_rotterdam
dataset, _ = prep_rotterdam()

# Print types
print('dataset type: {}'.format(type(dataset)))
print('elements type: {}'.format(type(dataset[0])))

```

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

### Access Simulation Results Format (Python)

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/Rotterdam_example.ipynb

Demonstrates how to access the results of a Monte Carlo simulation. Each simulation run is represented by a list of states and the time spent at each state, mirroring the format of the dataset used for model fitting. This allows for detailed analysis of individual predicted trajectories.

```python
mc = all_mcs[0]
print(mc.states)
print(mc.time_at_each_state)

mc = all_mcs[1]
print(mc.states)
print(mc.time_at_each_state)

```

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

### Inspect Dataset and PathObject Structure in pymsm

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/Rotterdam_example.ipynb

Prints the type of the dataset and its elements, then inspects a specific PathObject to show its attributes like sample ID, states, transition times, and covariates. This helps understand the data structure for analysis.

```python
print('dataset type: {}'.format(type(dataset)))
print('elements type: {}'.format(type(dataset[0])))
```

```python
sample_path = dataset[1314]
sample_path.print_path()
```

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

### Define Model Parameters and Display State Labels

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/COVID_hospitalization_example.ipynb

Defines covariate columns, terminal states, and a short mapping for state labels. It then prints the full state labels dictionary. This setup is crucial for configuring the multi-state model.

```python
# Some definitions
covariate_cols = ["is_male", "age", "was_severe"]
terminal_states = [4]
state_labels_short = {0: "C", 1: "R", 2: "M", 3: "S", 4: "D"}
print(state_labels)


```

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

### Run Monte Carlo Simulation for Predictions (Python)

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/Rotterdam_example.ipynb

Initiates a Monte Carlo simulation to predict future patient states. It requires current patient covariates, an origin state, current time, a maximum number of transitions, and the desired number of random samples. The simulation sequentially samples next states using model parameters until a terminal state is reached or the maximum transitions are exceeded.

```python
import numpy as np

all_mcs = multi_state_model.run_monte_carlo_simulation(
    # the current covariates of the patient.
    # especially important to use updated covariates in case of
    # time varying covariates along with a prediction from a point in time
    # during hospitalization
    sample_covariates=dataset[0].covariates.values,
    # in this setting samples start at state 1, but
    # in general this can be any non-terminal state which
    # then serves as the simulation starting point
    origin_state=1,
    # in this setting we start predictions from time 0, but
    # predictions can be made from any point in time during the
    # patient's trajectory
    current_time=0,
    # If there is an observed upper limit on the number of transitions, we recommend
    # setting this value to that limit in order to prevent generation of outlier paths
    max_transitions=2,
    # the number of paths to simulate:
    n_random_samples=100,
)

```

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

### Get and Display Path Frequencies

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/COVID_hospitalization_example.ipynb

Retrieves and displays the frequencies of different state transition paths from a Monte-Carlo simulation. It uses the `get_path_frequencies` function and shows the head of the resulting pandas Series.

```python
path_freqs = get_path_frequencies(mc_paths, state_labels)
path_freqs.head(10)
```

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

### Define Default Covariate Update Function for pymsm

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/Rotterdam_example.ipynb

Defines a default function for updating patient covariates over time in a multi-state model. This function is intended to be used with the pymsm package and handles covariate updates based on state transitions.

```python
def default_update_covariates_function(covariates_entering_origin_state, origin_state=None, target_state=None,
                                       time_at_origin=None, abs_time_entry_to_target_state=None):
    return covariates_entering_origin_state
```

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

### Import PyMSM and Pandas

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/EBMT_example.ipynb

Imports the necessary libraries, pandas for data manipulation and MultiStateModel from pymsm for building multi-state models.

```python
import pandas as pd
from pymsm.multi_state_competing_risks_model import  MultiStateModel
```

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

### Initialize PyMSM MultistateModel

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/COVID_hospitalization_example.ipynb

Initializes the `MultiStateModel` class with dataset, terminal states, covariate functions, covariate names, and state labels. This is the first step before fitting the model.

```python
multi_state_model = MultiStateModel(
    dataset=dataset,
    terminal_states=terminal_states,
    update_covariates_fn=covid_update_covariates_function,
    covariate_names=covariate_cols,
    state_labels=state_labels,
)
```

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

### Initialize and Fit MultiStateModel

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/EBMT_example.ipynb

Initializes a MultiStateModel object with the prepared EBMT dataset, terminal states, covariate names, and state labels. The model is then fitted to the data, which involves fitting transition models for each state.

```python
terminal_states = [5, 6]

multi_state_model = MultiStateModel(
    dataset=competing_risk_dataset,
    terminal_states=terminal_states,
    covariate_names=covariate_cols,
    competing_risk_data_format=True,
    state_labels=state_labels
)


multi_state_model.fit()
```

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

### Initialize and Fit pymsm MultiStateModel

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/fitting_a_multistate_model.ipynb

Initializes the MultiStateModel with the prepared dataset and configurations, then fits the model to the data. The fitting process involves iterating through states and fitting transitions.

```python
# Init MultistateModel
from pymsm.multi_state_competing_risks_model import MultiStateModel

multi_state_model = MultiStateModel(
    dataset=dataset,
    terminal_states=terminal_states,
    update_covariates_fn=covid_update_covariates_function,
    covariate_names=covariate_cols,
    state_labels=state_labels_short,
    event_specific_fitter=event_specific_fitter,
    trim_transitions_threshold=trim_transitions_threshold,
)

multi_state_model.fit()

```

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

### Configure Multi-State Simulator (PyMSM)

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/COVID_hospitalization_example.ipynb

Initializes a MultiStateSimulator with a list of competing risks models, terminal states, and callback functions for covariate updates. It requires covariate names and state labels for proper configuration.

```python
# Configure the simulator
mssim = MultiStateSimulator(
    competing_risks_models_list,
    terminal_states=[5, 6],
    update_covariates_fn=covid_update_covariates_function,
    covariate_names=covariate_cols,
    state_labels=state_labels,
)
```

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

### Prepare AIDS-SI Dataset for Competing Risks in Python

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/AIDSI_example.ipynb

Prepares the loaded AIDS-SI dataset for competing risks analysis using prep_aidssi(). This function returns the prepared dataset, covariate columns, and state labels, which are then displayed using .head() for the dataset.

```python
competing_risk_dataset, covariate_cols, state_labels = prep_aidssi(data)
competing_risk_dataset.head()
```

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

### Load and Display EBMT Dataset Head

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/EBMT_example.ipynb

Loads the EBMT dataset using the load_ebmt function and displays the first few rows using .head(). This dataset is from the European Society for Blood and Marrow Transplantation.

```python
from pymsm.datasets import load_ebmt, prep_ebmt_long, plot_ebmt
load_ebmt().head()
```

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

### Load and Display AIDS-SI Dataset Head in Python

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/AIDSI_example.ipynb

Loads the AIDS-SI dataset using the load_aidssi() function from pymsm.datasets and displays the first few rows of the loaded data using .head(). This function is part of a competing risks analysis workflow.

```python
data = load_aidssi()
data.head()
```

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

### Initialize MultistateModel with SurvivalTreeWrapper

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/custom_fitters.md

Demonstrates initializing a MultistateModel using the SurvivalTreeWrapper as the event-specific fitter. This requires the dataset, terminal states, and a default update covariates function. The SurvivalTreeWrapper is imported from pymsm.survival_tree_fitter.

```python
from pymsm.multi_state_competing_risks_model import MultiStateModel
from pymsm.survival_tree_fitter import SurvivalTreeWrapper

multi_state_model = MultiStateModel(
    dataset,
    terminal_states,
    default_update_covariates_function,
    event_specific_fitter=SurvivalTreeWrapper
    )
```

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

### Initialize PyMSM MultistateModel with Trim Threshold

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/COVID_hospitalization_example.ipynb

Initializes the `MultiStateModel` with an added `trim_transitions_threshold` parameter. This helps to ignore transitions with fewer samples than the specified threshold, potentially improving model stability.

```python
multi_state_model = MultiStateModel(
    dataset=dataset,
    terminal_states=terminal_states,
    update_covariates_fn=covid_update_covariates_function,
    covariate_names=covariate_cols,
    state_labels=state_labels,
    trim_transitions_threshold=10
)
```

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

### Configure PyMSM MultiStateSimulator

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/Simulator.md

Initializes a MultiStateSimulator with competing risks models, terminal states, and functions for updating covariates. It requires a list of models, terminal state identifiers, a covariate update function, and covariate names.

```python
from pymsm.simulation import MultiStateSimulator

mssim = MultiStateSimulator(
    competing_risks_models_list,
    terminal_states=[5, 6],
    update_covariates_fn=covid_update_covariates_function,
    covariate_names=covariate_cols,
)
```

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

### Import Libraries and Load Extensions in Python

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/AIDSI_example.ipynb

Imports necessary libraries like numpy, pandas, and matplotlib, along with specific functions from pymsm. It also loads and sets the autoreload extension to automatically reload modules.

```python
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt

from pymsm.datasets import load_aidssi, prep_aidssi, plot_aidssi
from pymsm.plotting import competingrisks_stackplot

%load_ext autoreload
%autoreload 2
```

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

### Import pymsm Libraries and Data Preparation

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/COVID_hospitalization_example.ipynb

Imports necessary libraries from pandas, numpy, matplotlib, and the pymsm package for data manipulation, visualization, and modeling. It also prepares the COVID-19 hospitalization dataset and displays it along with state labels.

```python
# Imports
import pandas as pd
import numpy as np
import matplotlib.pyplot as plt

from pymsm.datasets import prep_covid_hosp_data
from pymsm.multi_state_competing_risks_model import MultiStateModel
from pymsm.statistics import (
    prob_visited_states,
    stats_total_time_at_states,
    get_path_frequencies,
    path_total_time_at_states
)
from pymsm.simulation import MultiStateSimulator

%load_ext autoreload
%autoreload 2

```

```python
from pymsm.datasets import prep_covid_hosp_data, plot_covid_hosp
dataset, state_labels = prep_covid_hosp_data()
plot_covid_hosp(dataset, state_labels)


```

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

### Prepare EBMT Dataset for Competing Risks

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/EBMT_example.ipynb

Prepares the EBMT dataset for competing risks analysis by transforming it into a long format suitable for multi-state modeling. It also returns covariate column names and state labels.

```python
competing_risk_dataset, covariate_cols, state_labels = prep_ebmt_long()
competing_risk_dataset.head()
```

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

### Load and Prepare AIDSI Dataset for PyMSM

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/competing_risks_stackplot.ipynb

Loads the AIDSI dataset and prepares it for competing risks analysis. It requires the `load_aidssi` and `prep_aidssi` functions from `pymsm.datasets`. The output includes the prepared dataset, covariate columns, and state labels.

```python
# Load and prep data
from pymsm.datasets import load_aidssi, prep_aidssi
data = load_aidssi()
competing_risk_dataset, covariate_cols, state_labels = prep_aidssi(data)
```

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

### Access Transition Table

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/COVID_hospitalization_example.ipynb

Retrieves and displays the transition table from the fitted multistate model. This table summarizes the number of events for each state transition.

```python
multi_state_model.transition_table
```

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

### Load EBMT Competing Risk Dataset (Python)

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/Preparing_a_dataset.ipynb

Loads the EBMT dataset formatted for competing risk models using PyMSM. It retrieves the dataset, covariate column names, and state labels, preparing the data for fitting a CompetingRiskModel.

```python
# Load EBMT dataset
from pymsm.datasets import prep_ebmt_long
competing_risk_dataset, covariate_cols, state_labels = prep_ebmt_long()
competing_risk_dataset.head()

```

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

### Inspect EBMT Dataset Columns (Python)

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/Preparing_a_dataset.ipynb

Prints the column names of the loaded EBMT competing risk dataset. This helps in verifying that all necessary columns for fitting the model are present and correctly named.

```python
print(competing_risk_dataset.columns)

```

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

### Load and Inspect AID-SI Dataset with PyMSM

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/Datasets.ipynb

Loads the AID-SI dataset using `load_aidssi` from PyMSM and displays the first few rows. This dataset is suitable for analyzing competing risks scenarios.

```python
from pymsm.datasets import load_aidssi, prep_aidssi, plot_aidssi
data = load_aidssi()
data.head()
```

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

### Mermaid State Diagram: Competing Risk Model

Source: https://github.com/hrossman/pymsm/blob/main/docs/methods.md

Visual representation of a simple competing-risk multistate model with three states (A, B, C) and two possible transitions (A to B, A to C). This diagram illustrates a basic branching scenario in state transitions.

```mermaid
stateDiagram-v2
    A --> B
    A --> C
```

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

### Call Transition Table Method

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/COVID_hospitalization_example.ipynb

Calls the `transition_table` method on the multistate model object. This is an alternative way to access the transition summary after fitting.

```python
multi_state_model.transition_table()
```

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

### Generating Random Multi-state Survival Data with PyMSM

Source: https://github.com/hrossman/pymsm/blob/main/docs/methods.md

This snippet describes the process of generating random multi-state survival data using the PyMSM library. Users can define a multi-state model by specifying transition-specific baseline hazards and hazard coefficients (beta). Optionally, a time-varying covariate update function can be provided. The library then simulates individual trajectories based on these parameters, creating a synthetic dataset suitable for various analyses.

```python
# Example placeholder for PyMSM data generation functionality
# Assumes model parameters (baseline hazards, coefficients) are defined
# and a function for time-varying covariates update if needed.

# from pymsm import MultiStateModel, simulate_data

# # Define model parameters (example)
# baseline_hazards = {...}
# coefficients = {...}
# covariate_update_func = None # or a custom function

# # Initialize the model
# model = MultiStateModel(baseline_hazards, coefficients, covariate_update_func)

# # Simulate trajectories to generate data
# simulated_data = simulate_data(model, num_trajectories=100, max_time=1000)

# print(simulated_data.head())
```

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

### Create Competing Risks Stackplot in Python

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/AIDSI_example.ipynb

Generates a stackplot visualizing competing risks from the prepared dataset. It uses the competingrisks_stackplot function, specifying the data, duration and event columns, and the order of states to display on the plot.

```python
competingrisks_stackplot(
    data=competing_risk_dataset,
    duration_col='time_transition_to_target',
    event_col ='target_state',
    order_top= [2],
    order_bottom = [3],
    state_labels = state_labels);
```

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

### Mermaid State Diagram: Complex Multistate Model

Source: https://github.com/hrossman/pymsm/blob/main/docs/methods.md

Visual representation of a more complex multistate model with four states (A, B, C, D) and six possible transitions. This diagram demonstrates a more intricate network of state changes.

```mermaid
stateDiagram-v2
    A --> B
    A --> C
    A --> D
    B --> A
    B --> D
    C --> A
```

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

### Print Individual Patient Path

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/COVID_hospitalization_example.ipynb

Selects and prints the detailed path information for a specific patient (index 567), including their states, transition times, and covariates. This helps in understanding individual patient trajectories within the model.

```python
dataset[567].print_path()

```

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

### Calculate Probability of Visiting States

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/EBMT_example.ipynb

Calculates and prints the probability of visiting specific states, including individual states like 'Rec' and 'AE', combinations like 'AE & Rec', and terminal states such as 'Relapse' and 'Death'. It utilizes functions from `pymsm.statistics` and requires pre-defined state labels and terminal states.

```python
from pymsm.statistics import prob_visited_states, stats_total_time_at_states

all_states = competing_risk_dataset["target_state"].unique()
# Probability of visiting any of the states
for state in all_states:
    if state == 0:
        continue
    print(
        f"Probabilty of {state_labels[state]} = {prob_visited_states(mc_paths, states=[state])}"
    )

# Probability of terminal states - Death and Relapse
print(
    f"Probabilty of any terminal state = {prob_visited_states(mc_paths, states=multi_state_model.terminal_states)}"
)
```

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

### Display PathObject Details (Python)

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/Preparing_a_dataset.ipynb

Accesses and displays the detailed path and covariate information for a specific sample (patient) from the loaded dataset. This is useful for examining individual sample trajectories within the PathObject list format.

```python
# Display paths and covariates of one sample (#1314)
sample_path = dataset[1314]
sample_path.print_path()

```

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

### Prepare and Plot Rotterdam Dataset with PyMSM

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/Datasets.ipynb

Prepares and plots the Rotterdam dataset using `prep_rotterdam` and `plot_rotterdam`. This function is used for analyzing illness-death transitions and visualizing the patient data.

```python
dataset, state_labels = prep_rotterdam()
plot_rotterdam(dataset, state_labels)
```

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

### Fit PyMSM MultistateModel

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/COVID_hospitalization_example.ipynb

Fits the initialized multistate model. This process involves iterating through states and fitting transitions based on the provided dataset and configuration.

```python
multi_state_model.fit()
```

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

### Run Monte Carlo Simulation with pymsm

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/path_sampling.ipynb

Executes Monte Carlo simulations using a pre-fitted multistate model to generate random path samples. It requires initial covariates, origin state, and optionally current time, number of samples, maximum transitions, and parallel jobs. The output is a list of simulated paths.

```python
simulated_paths = multi_state_model.run_monte_carlo_simulation(
              sample_covariates = dataset[0].covariates.values,
              origin_state = 1,
              current_time = 0,
              n_random_samples = 10,
              max_transitions = 2,
              n_jobs = 3,
              print_paths=True
              )
```

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

### Run Monte Carlo Simulation for a Single Patient

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/EBMT_example.ipynb

Executes a Monte Carlo simulation for a single patient using a multi-state model. It takes sample covariates, origin state, current time, number of random samples, and maximum transitions as input. The output contains paths generated by the simulation.

```python
mc_paths = multi_state_model.run_monte_carlo_simulation(
    sample_covariates=competing_risk_dataset.loc[0, covariate_cols],
    origin_state=1,
    current_time=0,
    n_random_samples=1000,
    max_transitions=10,
)
```

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

### Fit Multistate Model with pymsm

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/path_sampling.ipynb

Initializes and fits a multistate competing risks model using the pymsm library. It requires dataset and state labels as input and can utilize default or custom covariate update functions. The fit method processes transitions between states.

```python
from pymsm.datasets import prep_rotterdam
dataset, states_labels = prep_rotterdam()

from pymsm.multi_state_competing_risks_model import MultiStateModel, default_update_covariates_function
multi_state_model = MultiStateModel(
    dataset,
    terminal_states=[3],
    update_covariates_fn=default_update_covariates_function)

multi_state_model.fit()
```

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

### Compute and Display Path Frequencies with Pymsm

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/examining_a_model.ipynb

Computes and displays the frequencies of different state transition paths within the dataset using the get_path_frequencies function from pymsm.statistics. It requires a dictionary of state labels for concise output.

```python
state_labels_short = {0: "C", 1: "R", 2: "M", 3: "S", 4: "D"}

from pymsm.statistics import get_path_frequencies
path_freqs = get_path_frequencies(dataset, state_labels_short)
path_freqs.head(20)
```

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

### Run Monte Carlo Simulation with PyMSM

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/Simulator.md

Executes a Monte Carlo simulation to generate sample paths from a configured multi-state model. It takes sample covariates, an origin state, current time, number of samples, and simulation parameters as input.

```python
# Run MC for a sample single patient
sim_paths = multi_state_model.run_monte_carlo_simulation(
    sample_covariates=pd.Series({"is_male":0, "age":75, "was_severe": 0}),
    origin_state=3,
    current_time=2,
    n_random_samples=5,
    max_transitions=10,
    print_paths=True,
    n_jobs=-1
)
```

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

### Mermaid State Diagram: Illness-Death Model

Source: https://github.com/hrossman/pymsm/blob/main/docs/methods.md

Visual representation of an illness-death multistate model with three states (A, B, C) and three possible transitions (A to B, A to C, B to C). This diagram shows a sequential and branching transition possibility.

```mermaid
stateDiagram-v2
    A --> B
    A --> C
    B --> C
```

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

### Plot AIDS-SI Competing Risks Data in Python

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/AIDSI_example.ipynb

Generates a plot of the prepared AIDS-SI competing risks dataset using plot_aidssi(). This function requires the processed dataset and state labels for accurate visualization of the event types and their progression.

```python
plot_aidssi(competing_risk_dataset, state_labels)
```

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

### Prepare and Display Transition Table with Pymsm

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/examining_a_model.ipynb

Prepares and displays a transition table for a multistate model, showing counts of transitions between states, including censored events. Requires the MultiStateModel class from pymsm.multi_state_competing_risks_model.

```python
from pymsm.multi_state_competing_risks_model import MultiStateModel

msm = MultiStateModel(
    dataset=dataset,
    terminal_states=[4],
    state_labels=state_labels,
)

msm.prep_transition_table()
```

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

### Monte Carlo Simulation for Multi-State Model Prediction

Source: https://github.com/hrossman/pymsm/blob/main/docs/methods.md

This snippet illustrates the process of reconstructing the complete distribution of a path for a new observation in a multi-state model using Monte Carlo simulation. It involves sampling the next state based on discrete conditional probabilities and then sampling the time spent in the current state. The process iterates until a terminal state is reached or a specified condition is met. Dependencies include pre-defined model parameters such as baseline hazards and coefficients.

```mathematical
p_{j|j^*,Z}= 
\frac{\widehat{\Pr} (J_N=j | J_C=j^*, Z(0)=Z) }{\sum_{j'=1}^{K_{j^*}} \widehat{\Pr} (J_N=j' | J_C=j^*, Z(0)=Z)}  \ .
U=\widehat{\Pr} (T\leq t| J_N=j', J_C=j^* , Z(0)=Z)
$$
```

```mathematical
\Pr(T \leq t, J_N=j|J_C=j^*,Z(0)=Z) = \int_0^t \lambda_{j^*,j}(u|Z)\exp\left\{-\sum_{k=1}^{|K_{j^\*|}|} \Lambda_{j^*,k}(u-|Z) \right\}du  \ .
```

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

### Plot EBMT Dataset

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/EBMT_example.ipynb

Generates a plot of the EBMT dataset using the plot_ebmt function. This function requires the prepared dataset, state labels, covariate columns, and a list of terminal states.

```python
plot_ebmt(competing_risk_dataset, state_labels, covariate_cols, terminal_states=[5, 6])
```

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

### Prepare and Configure pymsm Model

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/fitting_a_multistate_model.ipynb

Loads COVID hospitalization data and defines configurations for a multi-state competing risks model. This includes setting terminal states, a custom update function for covariates, covariate names, state labels, a threshold for data transitions, and the event-specific fitter.

```python
# Load data
from pymsm.datasets import prep_covid_hosp_data

dataset, state_labels = prep_covid_hosp_data()


# 1) Define terminal states
terminal_states = [4]

# 2) Define a custom update function for time-varying covariates.
# Default is No updating:
from pymsm.multi_state_competing_risks_model import default_update_covariates_function
update_covariates_fn = default_update_covariates_function

# Let's define one:
def covid_update_covariates_function(
    covariates_entering_origin_state,
    origin_state=None,
    target_state=None,
    time_at_origin=None,
    abs_time_entry_to_target_state=None,
):
    covariates = covariates_entering_origin_state.copy()
    # update is_severe covariate
    if origin_state == 3:
        covariates['was_severe'] = 1
    return covariates

# 3) Define covariate columns
covariate_cols = ["is_male", "age", "was_severe"]

# 4) Define state labels
state_labels_short = {0: "C", 1: "R", 2: "M", 3: "S", 4: "D"}

# 5) Define minimum number of data transitions needed to fit a transition
trim_transitions_threshold = 10

# 6) Define the event specific fitters. Default is CoxWrapper. See custom_fitters for more
from pymsm.event_specific_fitter import CoxWrapper

event_specific_fitter = CoxWrapper

```

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

### Probability of Transition Estimation (Cox Models)

Source: https://github.com/hrossman/pymsm/blob/main/docs/methods.md

Calculates the estimated probability of transitioning from state j* to state j, given covariates Z. This formula is derived from Cox models and assumes observed failure times and estimated parameters.

```latex
\begin{equation}
    \begin{aligned}
\widehat{\Pr} (J_N=j | J_C=j^*,Z(0)=Z) \\
    =   \sum_{t_m \leq \tau_{j^*,j}} \exp\left( \widehat\beta_{j^*,j}^T Z\right) \widehat\lambda_{0j^*,j}(t_m) \exp \left\{-\sum_{k=1}^{|K_{j^}|} \widehat\Lambda_{0j^*,k}(t_{m-1})\exp\left( \widehat\beta_{j^*,k}^T Z\right) \right} \
    \end{aligned}
\end{equation}
```

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

### Calculate and Display Path Frequencies

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/COVID_hospitalization_example.ipynb

Calculates and prints the frequency of all unique state transition paths observed in the dataset using the `get_path_frequencies` function. This provides insights into the most common trajectories patients follow.

```python
path_freqs = get_path_frequencies(dataset, state_labels_short)
print(path_freqs)

```

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

### Load and Inspect Rotterdam Dataset with PyMSM

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/Datasets.ipynb

Loads the Rotterdam dataset, a 3-state illness-death dataset, using `load_rotterdam` from PyMSM and displays the initial rows. This dataset contains information on breast cancer patients.

```python
from pymsm.datasets import load_rotterdam, prep_rotterdam, plot_rotterdam
rotterdam = load_rotterdam()
rotterdam.head()
```

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

### Cox Transition-Specific Hazard Model Estimation

Source: https://github.com/hrossman/pymsm/blob/main/paper.md

Demonstrates the estimation procedure for Cox transition-specific hazard models. This method handles right censoring and competing events by maximizing partial likelihoods separately for each transition, treating competing events as censoring. It uses standard partial-likelihood estimators for coefficients and Breslow estimators for cumulative baseline hazards.

```latex
\lambda_{j,j'}(t|Z) = \lambda_{0j,j'}(t) \exp(Z^T \beta_{j,j'})
```

```latex
\widehat{\Pr} (J_N=j | J_C=j^*,Z(0)=Z) \\ = \sum_{t_m \leq \tau_{j^*,j}} \exp\left( \widehat\beta_{j^*,j}^T Z\right) \widehat\lambda_{0j^*,j}(t_m) \exp \left\{-\sum_{k=1}^{|K_{j^*}|} \widehat\Lambda_{0j^*,k}(t_{m-1})\exp\left( \widehat\beta_{j^*,k}^T Z\right) \right\} \\ ,
```

```latex
\widehat{\Pr} (T\leq t| J_N=j', J_C=j^* , Z(0)=Z)\\ = \frac{\sum_{t_m \leq t} \exp\left( \widehat\beta_{j^*,j'}^T Z\right) \widehat\lambda_{0j^*,j'}(t_m) \exp \left\{-\sum_{k=1}^{|K_{j^*}|} \widehat\Lambda_{0j^*,k}(t_{m-1})\exp\left( \widehat\beta_{j^*k}^T Z\right) \right\} }{ \sum_{t_m \leq \tau_{j^*,j'}} \exp\left( \widehat\beta_{j^*,j'}^T Z\right) \widehat\lambda_{0j^*,j'}(t_m) \exp \left\{-\sum_{k=1}^{K_{j^*}} \widehat\Lambda_{0j^*,k}(t_{m-1})\exp\left( \widehat\beta_{j^*,k}^T Z\right) \right\} } \\ ,
```

```latex
\widehat{\Pr} (T\leq t| J_N=\breve{j}, J_C=j' , Z(t')=Z) \\ = \frac{\sum_{t' < t_m \leq t} \exp\left( \widehat\beta_{j',reve{j}}^T Z\right) \widehat\lambda_{0j',reve{j}}(t_m) \exp \left\{-\sum_{k=1}^{|K_{j'}|} \widehat\Lambda_{0j',k}(t_{m-1})\exp\left( \widehat\beta_{j',k}^T Z\right) \right\} }{ \sum_{t' < t_m \leq \tau_{j',reve{j}}} \exp\left( \widehat\beta_{j',reve{j}}^T Z\right) \widehat\lambda_{0j',reve{j}}(t_m) \exp \left\{-\sum_{k=1}^{K_{j'}} \widehat\Lambda_{0j',k}(t_{m-1})\exp\left( \widehat\beta_{j',k}^T Z\right) \right\} } \\ .
```

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

### Load and Inspect EBMT Dataset

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/Datasets.ipynb

Loads the European Society for Blood and Marrow Transplantation (EBMT) multi-state dataset using the load_ebmt function and displays the first few rows. This dataset contains patient information for transplantation analysis.

```python
from pymsm.datasets import load_ebmt, prep_ebmt_long, plot_ebmt

load_ebmt().head()
```

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

### Run Monte-Carlo Simulation for a Single Patient

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/COVID_hospitalization_example.ipynb

Executes a Monte-Carlo simulation for a single patient to model state transitions. It takes sample covariates, origin state, current time, number of random samples, maximum transitions, and job parallelism as inputs. The output is a collection of simulated paths.

```python
# Run MC for a sample single patient
mc_paths = multi_state_model.run_monte_carlo_simulation(
    sample_covariates=pd.Series({"is_male":0, "age":75, "was_severe":0}),
    origin_state=2,
    current_time=0,
    n_random_samples=100,
    max_transitions=10,
    print_paths=False,
    n_jobs=-1
)
```

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

### Generate Competing Risks Stackplot with PyMSM

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/competing_risks_stackplot.ipynb

Generates a stackplot to visualize competing risks. It utilizes the `competingrisks_stackplot` function from `pymsm.plotting`. Key inputs include the prepared dataset, duration and event columns, state orderings, and state labels. The output is a matplotlib Figure object.

```python
from pymsm.plotting import competingrisks_stackplot

competingrisks_stackplot(
    data=competing_risk_dataset,
    duration_col='time_transition_to_target',
    event_col ='target_state',
    order_top= [2],
    order_bottom = [3],
    state_labels = state_labels);
```

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

### Simulate Trajectories for Multi-State Survival Data in PyMSM

Source: https://github.com/hrossman/pymsm/blob/main/paper.md

PyMSM enables users to simulate trajectories for pre-defined multi-state models. This functionality allows for the creation of new multi-state datasets, which can be valuable for various analytical purposes. It requires specifying transition-specific baseline hazards, regression coefficient vectors, and optionally a time-varying covariate update function.

```python
import pymsm

# Example usage (conceptual):
# Define your multi-state model parameters (baseline hazards, coefficients, etc.)
model_params = {
    "baseline_hazards": {...},
    "coefficients": {...},
    "covariate_update_func": lambda Z, t: Z # Example: no time-varying covariates
}

# Initialize the PyMSM model
model = pymsm.MultiStateModel(**model_params)

# Simulate trajectories
num_simulations = 1000
simulated_data = model.simulate_trajectories(num_simulations=num_simulations, initial_state=1, start_time=0)

# The simulated_data will contain trajectories with states and times.
```

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

### Extract Competing Risks Models (PyMSM)

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/COVID_hospitalization_example.ipynb

Extracts a list of competing risks models from a multi-state model object. This function is used to prepare models for configuring a simulator, with an option to control verbosity.

```python
from pymsm.simulation import extract_competing_risks_models_list_from_msm

competing_risks_models_list = extract_competing_risks_models_list_from_msm(
    multi_state_model, verbose=True
)
```

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

### Calculate Probability of Visiting States (PyMSM)

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/COVID_hospitalization_example.ipynb

Calculates and prints the probability of a simulated patient ever being in specific states based on Monte Carlo simulation results. It iterates through defined state labels and uses the `prob_visited_states` function.

```python
for state, state_label in state_labels.items():
    if state == 0:
        continue
    print(
        f"Probabilty of ever being {state_label} = {prob_visited_states(mc_paths_severe, states=[state])}"
    )
```

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

### Run Monte Carlo Simulation for Single Patient (PyMSM)

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/COVID_hospitalization_example.ipynb

Executes a Monte Carlo simulation for a single patient using specified covariates, origin state, and simulation parameters. This function is part of the PyMSM library for multi-state modeling.

```python
mc_paths_severe = multi_state_model.run_monte_carlo_simulation(
    sample_covariates=pd.Series({"is_male":0, "age":75, "was_severe": 1}),
    origin_state=3,
    current_time=2,
    n_random_samples=100,
    max_transitions=10,
    print_paths=False,
    n_jobs=-1
)
```

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

### Display Transition Table Attribute with Pymsm

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/examining_a_model.ipynb

Accesses and displays the pre-computed transition table as an attribute of the MultiStateModel object. This provides a summary of state transitions and censored events.

```python
msm.transition_table
```

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

### Calculate Time Statistics at Non-Terminal States

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/EBMT_example.ipynb

Computes and consolidates statistics for the time spent in non-terminal states. It iterates through defined states, calculates mean, standard deviation, median, min, max, and quantiles for time spent in each state using `stats_total_time_at_states`, and presents the results in a pandas DataFrame.

```python
# Stats for times at states
dfs = []
for state in all_states:
    if state == 0 or state in terminal_states:
        continue
    dfs.append(
        pd.DataFrame(
            data=stats_total_time_at_states(mc_paths, states=[state]),
            index=[state_labels[state]],
        )
    )
pd.concat(dfs)
```

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

### Access Transition Matrix with Pymsm

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/examining_a_model.ipynb

Retrieves and displays the transition matrix of a multistate model, which quantifies the rates or probabilities of moving between states. This is a direct attribute of the fitted MultiStateModel object.

```python
msm.transition_matrix
```

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

### Plot Competing Risks Stackplot with Pymsm

Source: https://github.com/hrossman/pymsm/blob/main/docs/usage/examining_a_model.ipynb

Generates a stackplot visualizing competing risks from a specified origin state over time. This function helps understand how different paths behave. It requires filtering the competing risk dataset by origin state.

```python
origin_state = 3
competing_risk_dataset = msm.competing_risk_dataset
competing_risk_dataset = competing_risk_dataset[competing_risk_dataset['origin_state'] == origin_state]


from pymsm.plotting import competingrisks_stackplot

competingrisks_stackplot(
    data=competing_risk_dataset,
    duration_col='time_transition_to_target',
    event_col ='target_state',
    order_top= [1],
    order_bottom = [4,2],
    state_labels = state_labels);

```

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

### Calculate and Print State Visit Probabilities and Time-in-State Statistics

Source: https://github.com/hrossman/pymsm/blob/main/docs/full_examples/COVID_hospitalization_example.ipynb

Calculates the probability of a patient ever being in specific states and computes statistics for the total time spent in each state. It iterates through defined state labels, filters out terminal or irrelevant states, and aggregates the results into a pandas DataFrame.

```python
# Probability of visiting any of the states
for state, state_label in state_labels.items():
    if state == 0:
        continue
    print(
        f"Probabilty of ever being {state_label} = {prob_visited_states(mc_paths, states=[state])}"
    )


# Stats for times at states
dfs = []
for state, state_label in state_labels.items():
    if state == 0 or state in terminal_states:
        continue
    dfs.append(
        pd.DataFrame(
            data=stats_total_time_at_states(mc_paths, states=[state]),
            index=[state_label],
        )
    )
pd.concat(dfs).round(3).T
```

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

### Cox Model Hazard Function Estimation

Source: https://github.com/hrossman/pymsm/blob/main/docs/methods.md

Estimates transition-specific hazard functions using Cox proportional hazards models. It handles right censoring, competing events, left truncation, and recurrent events by leveraging partial likelihood and Breslow estimators. Standard errors are robust to correlated outcomes for recurrent events.

```latex
\lambda_{j,j'}(t|Z) = \lambda_{0j,j'}(t) \exp(Z^T \beta_{j,j'})
```