pySEQTarget 0.9.0__tar.gz

pyseqtarget-0.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 CAUSALab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyseqtarget-0.9.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: pySEQTarget
+Version: 0.9.0
+Summary: Sequentially Nested Target Trial Emulation
+Author-email: Ryan O'Dea <ryan.odea@psi.ch>, Alejandro Szmulewicz <aszmulewicz@hsph.harvard.edu>, Tom Palmer <tom.palmer@bristol.ac.uk>, Miguel Hernan <mhernan@hsph.harvard.edu>
+Maintainer-email: Ryan O'Dea <ryan.odea@psi.ch>
+License: MIT
+Project-URL: Homepage, https://github.com/CausalInference/pySEQTarget
+Project-URL: Repository, https://github.com/CausalInference/pySEQTarget
+Project-URL: Bug Tracker, https://github.com/CausalInference/pySEQTarget/issues
+Project-URL: Ryan O'Dea (ORCID), https://orcid.org/0009-0000-0103-9546
+Project-URL: Alejandro Szmulewicz (ORCID), https://orcid.org/0000-0002-2664-802X
+Project-URL: Tom Palmer (ORCID), https://orcid.org/0000-0003-4655-4511
+Project-URL: Miguel Hernan (ORCID), https://orcid.org/0000-0003-1619-8456
+Project-URL: University of Bristol (ROR), https://ror.org/0524sp257
+Project-URL: Harvard University (ROR), https://ror.org/03vek6s52
+Keywords: causal inference,sequential trial emulation,target trial,observational studies
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: polars
+Requires-Dist: tqdm
+Requires-Dist: statsmodels
+Requires-Dist: matplotlib
+Requires-Dist: pyarrow
+Requires-Dist: lifelines
+Dynamic: license-file
+
+# pySEQTarget - Sequentially Nested Target Trial Emulation
+
+Implementation of sequential trial emulation for the analysis of
+observational databases. The ‘SEQTaRget’ software accommodates
+time-varying treatments and confounders, as well as binary and failure
+time outcomes. ‘SEQTaRget’ allows to compare both static and dynamic
+strategies, can be used to estimate observational analogs of
+intention-to-treat and per-protocol effects, and can adjust for
+potential selection bias.
+
+## Installation
+You can install the development version of pySEQTarget from github with:
+```shell
+pip install git+https://github.com/CausalInference/pySEQTarget
+```
+Or from pypi iwth 
+```shell
+pip install pySEQTarget
+```
+
+## Setting up your Analysis
+The primary API, `SEQuential` uses a dataclass system to handle function input. You can then recover elements as they are built by interacting with the `SEQuential` object you create.
+
+From the user side, this amounts to creating a dataclass, `SEQopts`, and then feeding this into `SEQuential`. If you forgot to add something at class instantiation, you can, in some cases, add them when you call their respective class method.
+
+```python
+import polars as pl
+from pySEQTarget import SEQuential, SEQopts
+
+data = pl.from_pandas(SEQdata)
+options = SEQopts(km_curves = True)
+
+# Initiate the class
+model = SEQuential(data, 
+                   id_col = "ID",
+                   time_col = "time",
+                   eligible_col = "eligible",
+                   time_varying_cols = ["N", "L", "P"],
+                   fixed_cols = ["sex"],
+                   method = "ITT",
+                   options = options)
+model.expand()  # Construct the nested structure
+model.bootstrap(bootstrap_nboot = 20) # Run 20 bootstrap samples
+model.fit() # Fit the model
+model.survival() # Create survival curves
+model.plot() # Create and show a plot of the survival curves
+model.collect() # Collection of important information
+
+```
+
+## Assumptions
+There are several key assumptions in this package -
+1. User provided `time_col` begins at 0 per unique `id_col`, we also assume this column contains only integers and continues by 1 for every time step, e.g. (0, 1, 2, 3, 4, ...) is allowed and (0, 1, 2, 2.5, ...) or (0, 1, 4, 5) are not
+    1. Provided `time_col` entries may be out of order at intake as a sort is enforced at expansion.
+2. `eligible_col`, `excused_column_names` and [TODO] are once 1, only 1 (with respect to `time_col`) flag variables.
+

pyseqtarget-0.9.0/README.md

@@ -0,0 +1,56 @@
+# pySEQTarget - Sequentially Nested Target Trial Emulation
+
+Implementation of sequential trial emulation for the analysis of
+observational databases. The ‘SEQTaRget’ software accommodates
+time-varying treatments and confounders, as well as binary and failure
+time outcomes. ‘SEQTaRget’ allows to compare both static and dynamic
+strategies, can be used to estimate observational analogs of
+intention-to-treat and per-protocol effects, and can adjust for
+potential selection bias.
+
+## Installation
+You can install the development version of pySEQTarget from github with:
+```shell
+pip install git+https://github.com/CausalInference/pySEQTarget
+```
+Or from pypi iwth 
+```shell
+pip install pySEQTarget
+```
+
+## Setting up your Analysis
+The primary API, `SEQuential` uses a dataclass system to handle function input. You can then recover elements as they are built by interacting with the `SEQuential` object you create.
+
+From the user side, this amounts to creating a dataclass, `SEQopts`, and then feeding this into `SEQuential`. If you forgot to add something at class instantiation, you can, in some cases, add them when you call their respective class method.
+
+```python
+import polars as pl
+from pySEQTarget import SEQuential, SEQopts
+
+data = pl.from_pandas(SEQdata)
+options = SEQopts(km_curves = True)
+
+# Initiate the class
+model = SEQuential(data, 
+                   id_col = "ID",
+                   time_col = "time",
+                   eligible_col = "eligible",
+                   time_varying_cols = ["N", "L", "P"],
+                   fixed_cols = ["sex"],
+                   method = "ITT",
+                   options = options)
+model.expand()  # Construct the nested structure
+model.bootstrap(bootstrap_nboot = 20) # Run 20 bootstrap samples
+model.fit() # Fit the model
+model.survival() # Create survival curves
+model.plot() # Create and show a plot of the survival curves
+model.collect() # Collection of important information
+
+```
+
+## Assumptions
+There are several key assumptions in this package -
+1. User provided `time_col` begins at 0 per unique `id_col`, we also assume this column contains only integers and continues by 1 for every time step, e.g. (0, 1, 2, 3, 4, ...) is allowed and (0, 1, 2, 2.5, ...) or (0, 1, 4, 5) are not
+    1. Provided `time_col` entries may be out of order at intake as a sort is enforced at expansion.
+2. `eligible_col`, `excused_column_names` and [TODO] are once 1, only 1 (with respect to `time_col`) flag variables.
+

pyseqtarget-0.9.0/pySEQTarget/SEQopts.py

@@ -0,0 +1,105 @@
+import multiprocessing
+from dataclasses import dataclass, field
+from typing import List, Literal, Optional
+
+
+@dataclass
+class SEQopts:
+    bootstrap_nboot: int = 0
+    bootstrap_sample: float = 0.8
+    bootstrap_CI: float = 0.95
+    bootstrap_CI_method: Literal["se", "percentile"] = "se"
+    cense_colname: Optional[str] = None
+    cense_denominator: Optional[str] = None
+    cense_numerator: Optional[str] = None
+    cense_eligible_colname: Optional[str] = None
+    compevent_colname: Optional[str] = None
+    covariates: Optional[str] = None
+    denominator: Optional[str] = None
+    excused: bool = False
+    excused_colnames: List[str] = field(default_factory=lambda: [])
+    followup_class: bool = False
+    followup_include: bool = True
+    followup_max: int = None
+    followup_min: int = 0
+    followup_spline: bool = False
+    hazard_estimate: bool = False
+    indicator_baseline: str = "_bas"
+    indicator_squared: str = "_sq"
+    km_curves: bool = False
+    ncores: int = multiprocessing.cpu_count()
+    numerator: Optional[str] = None
+    parallel: bool = False
+    plot_colors: List[str] = field(
+        default_factory=lambda: ["#F8766D", "#00BFC4", "#555555"]
+    )
+    plot_labels: List[str] = field(default_factory=lambda: [])
+    plot_title: str = None
+    plot_type: Literal["risk", "survival", "incidence"] = "risk"
+    seed: Optional[int] = None
+    selection_first_trial: bool = False
+    selection_probability: float = 0.8
+    selection_random: bool = False
+    subgroup_colname: str = None
+    treatment_level: List[int] = field(default_factory=lambda: [0, 1])
+    trial_include: bool = True
+    weight_eligible_colnames: List[str] = field(default_factory=lambda: [])
+    weight_min: float = 0.0
+    weight_max: float = None
+    weight_lag_condition: bool = True
+    weight_p99: bool = False
+    weight_preexpansion: bool = False
+    weighted: bool = False
+
+    def __post_init__(self):
+        bools = [
+            "excused",
+            "followup_class",
+            "followup_include",
+            "followup_spline",
+            "hazard_estimate",
+            "km_curves",
+            "parallel",
+            "selection_first_trial",
+            "selection_random",
+            "trial_include",
+            "weight_lag_condition",
+            "weight_p99",
+            "weight_preexpansion",
+            "weighted",
+        ]
+        for i in bools:
+            if not isinstance(getattr(self, i), bool):
+                raise TypeError(f"{i} must be a boolean value.")
+
+        if not isinstance(self.bootstrap_nboot, int) or self.bootstrap_nboot < 0:
+            raise ValueError("bootstrap_nboot must be a positive integer.")
+
+        if self.ncores < 1 or not isinstance(self.ncores, int):
+            raise ValueError("ncores must be a positive integer.")
+
+        if not (0.0 <= self.bootstrap_sample <= 1.0):
+            raise ValueError("bootstrap_sample must be between 0 and 1.")
+        if not (0.0 < self.bootstrap_CI < 1.0):
+            raise ValueError("bootstrap_CI must be between 0 and 1.")
+        if not (0.0 <= self.selection_probability <= 1.0):
+            raise ValueError("selection_probability must be between 0 and 1.")
+
+        if self.plot_type not in ["risk", "survival", "incidence"]:
+            raise ValueError(
+                "plot_type must be either 'risk', 'survival', or 'incidence'."
+            )
+
+        if self.bootstrap_CI_method not in ["se", "percentile"]:
+            raise ValueError("bootstrap_CI_method must be one of 'se' or 'percentile'")
+
+        for i in (
+            "covariates",
+            "numerator",
+            "denominator",
+            "cense_numerator",
+            "cense_denominator",
+        ):
+            attr = getattr(self, i)
+            if attr is not None and not isinstance(attr, list):
+                setattr(self, i, "".join(attr.split()))

pyseqtarget-0.9.0/pySEQTarget/SEQoutput.py

@@ -0,0 +1,86 @@
+from dataclasses import dataclass
+from typing import List, Literal, Optional
+
+import matplotlib.figure
+import polars as pl
+from statsmodels.base.wrapper import ResultsWrapper
+
+from .SEQopts import SEQopts
+
+
+@dataclass
+class SEQoutput:
+    options: SEQopts = None
+    method: str = None
+    numerator_models: List[ResultsWrapper] = None
+    denominator_models: List[ResultsWrapper] = None
+    outcome_models: List[List[ResultsWrapper]] = None
+    compevent_models: List[List[ResultsWrapper]] = None
+    weight_statistics: dict = None
+    hazard: pl.DataFrame = None
+    km_data: pl.DataFrame = None
+    km_graph: matplotlib.figure.Figure = None
+    risk_ratio: pl.DataFrame = None
+    risk_difference: pl.DataFrame = None
+    time: dict = None
+    diagnostic_tables: dict = None
+
+    def plot(self):
+        print(self.km_graph)
+
+    def summary(
+        self, type=Optional[Literal["numerator", "denominator", "outcome", "compevent"]]
+    ):
+        match type:
+            case "numerator":
+                models = self.numerator_models
+            case "denominator":
+                models = self.denominator_models
+            case "compevent":
+                models = self.compevent_models
+            case _:
+                models = self.outcome_models
+
+        return [model.summary() for model in models]
+
+    def retrieve_data(
+        self,
+        type=Optional[
+            Literal[
+                "km_data",
+                "hazard",
+                "risk_ratio",
+                "risk_difference",
+                "unique_outcomes",
+                "nonunique_outcomes",
+                "unique_switches",
+                "nonunique_switches",
+            ]
+        ],
+    ):
+        match type:
+            case "hazard":
+                data = self.hazard
+            case "risk_ratio":
+                data = self.risk_ratio
+            case "risk_difference":
+                data = self.risk_difference
+            case "unique_outcomes":
+                data = self.diagnostic_tables["unique_outcomes"]
+            case "nonunique_outcomes":
+                data = self.diagnostic_tables["nonunique_outcomes"]
+            case "unique_switches":
+                if self.diagnostic_tables.has_key("unique_switches"):
+                    data = self.diagnostic_tables["unique_switches"]
+                else:
+                    data = None
+            case "nonunique_switches":
+                if self.diagnostic_tables.has_key("nonunique_switches"):
+                    data = self.diagnostic_tables["nonunique_switches"]
+                else:
+                    data = None
+            case _:
+                data = self.km_data
+        if data is None:
+            raise ValueError("Data {type} was not created in the SEQuential process")
+        return data

pyseqtarget-0.9.0/pySEQTarget/SEQuential.py

@@ -0,0 +1,315 @@
+import datetime
+import time
+from collections import Counter
+from dataclasses import asdict
+from typing import List, Literal, Optional
+
+import numpy as np
+import polars as pl
+
+from .analysis import (_calculate_hazard, _calculate_survival, _outcome_fit,
+                       _pred_risk, _risk_estimates, _subgroup_fit)
+from .error import _datachecker, _param_checker
+from .expansion import _binder, _diagnostics, _dynamic, _random_selection
+from .helpers import _col_string, _format_time, bootstrap_loop
+from .initialization import (_cense_denominator, _cense_numerator,
+                             _denominator, _numerator, _outcome)
+from .plot import _survival_plot
+from .SEQopts import SEQopts
+from .SEQoutput import SEQoutput
+from .weighting import (_fit_denominator, _fit_LTFU, _fit_numerator,
+                        _weight_bind, _weight_predict, _weight_setup,
+                        _weight_stats)
+
+
+class SEQuential:
+    def __init__(
+        self,
+        data: pl.DataFrame,
+        id_col: str,
+        time_col: str,
+        eligible_col: str,
+        treatment_col: str,
+        outcome_col: str,
+        time_varying_cols: Optional[List[str]] = None,
+        fixed_cols: Optional[List[str]] = None,
+        method: Literal["ITT", "dose-response", "censoring"] = "ITT",
+        parameters: Optional[SEQopts] = None,
+    ) -> None:
+        self.data = data
+        self.id_col = id_col
+        self.time_col = time_col
+        self.eligible_col = eligible_col
+        self.treatment_col = treatment_col
+        self.outcome_col = outcome_col
+        self.time_varying_cols = time_varying_cols
+        self.fixed_cols = fixed_cols
+        self.method = method
+
+        self._time_initialized = datetime.datetime.now()
+
+        if parameters is None:
+            parameters = SEQopts()
+
+        for name, value in asdict(parameters).items():
+            setattr(self, name, value)
+
+        self._rng = (
+            np.random.RandomState(self.seed) if self.seed is not None else np.random
+        )
+
+        if self.covariates is None:
+            self.covariates = _outcome(self)
+
+        if self.weighted:
+            if self.numerator is None:
+                self.numerator = _numerator(self)
+
+            if self.denominator is None:
+                self.denominator = _denominator(self)
+
+            if self.cense_colname is not None:
+                if self.cense_numerator is None:
+                    self.cense_numerator = _cense_numerator(self)
+
+                if self.cense_denominator is None:
+                    self.cense_denominator = _cense_denominator(self)
+
+        _param_checker(self)
+        _datachecker(self)
+
+    def expand(self):
+        start = time.perf_counter()
+        kept = [
+            self.cense_colname,
+            self.cense_eligible_colname,
+            self.compevent_colname,
+            *self.weight_eligible_colnames,
+            *self.excused_colnames,
+        ]
+
+        self.data = self.data.with_columns(
+            [
+                pl.when(pl.col(self.treatment_col).is_in(self.treatment_level))
+                .then(self.eligible_col)
+                .otherwise(0)
+                .alias(self.eligible_col),
+                pl.col(self.treatment_col).shift(1).over([self.id_col]).alias("tx_lag"),
+                pl.lit(False).alias("switch"),
+            ]
+        ).with_columns(
+            [
+                pl.when(pl.col(self.time_col) == 0)
+                .then(pl.lit(False))
+                .otherwise(
+                    (pl.col("tx_lag").is_not_null())
+                    & (pl.col("tx_lag") != pl.col(self.treatment_col))
+                )
+                .cast(pl.Int8)
+                .alias("switch")
+            ]
+        )
+
+        self.DT = _binder(
+            self,
+            kept_cols=_col_string(
+                [
+                    self.covariates,
+                    self.numerator,
+                    self.denominator,
+                    self.cense_numerator,
+                    self.cense_denominator,
+                ]
+            ).union(kept),
+        ).with_columns(pl.col(self.id_col).cast(pl.Utf8).alias(self.id_col))
+
+        self.data = self.data.with_columns(
+            pl.col(self.id_col).cast(pl.Utf8).alias(self.id_col)
+        )
+
+        if self.method != "ITT":
+            _dynamic(self)
+        if self.selection_random:
+            _random_selection(self)
+        _diagnostics(self)
+
+        end = time.perf_counter()
+        self._expansion_time = _format_time(start, end)
+
+    def bootstrap(self, **kwargs):
+        allowed = {
+            "bootstrap_nboot",
+            "bootstrap_sample",
+            "bootstrap_CI",
+            "bootstrap_method",
+        }
+        for key, value in kwargs.items():
+            if key in allowed:
+                setattr(self, key, value)
+            else:
+                raise ValueError(f"Unknown argument: {key}")
+
+        UIDs = self.DT.select(pl.col(self.id_col)).unique().to_series().to_list()
+        NIDs = len(UIDs)
+
+        self._boot_samples = []
+        for _ in range(self.bootstrap_nboot):
+            sampled_IDs = self._rng.choice(
+                UIDs, size=int(self.bootstrap_sample * NIDs), replace=True
+            )
+            id_counts = Counter(sampled_IDs)
+            self._boot_samples.append(id_counts)
+        return self
+
+    @bootstrap_loop
+    def fit(self):
+        if self.bootstrap_nboot > 0 and not hasattr(self, "_boot_samples"):
+            raise ValueError(
+                "Bootstrap sampling not found. Please run the 'bootstrap' method before fitting with bootstrapping."
+            )
+
+        if self.weighted:
+            WDT = _weight_setup(self)
+            if not self.weight_preexpansion and not self.excused:
+                WDT = WDT.filter(pl.col("followup") > 0)
+
+            WDT = WDT.to_pandas()
+            for col in self.fixed_cols:
+                if col in WDT.columns:
+                    WDT[col] = WDT[col].astype("category")
+
+            _fit_LTFU(self, WDT)
+            _fit_numerator(self, WDT)
+            _fit_denominator(self, WDT)
+
+            WDT = pl.from_pandas(WDT)
+            WDT = _weight_predict(self, WDT)
+            _weight_bind(self, WDT)
+            self.weight_stats = _weight_stats(self)
+
+        if self.subgroup_colname is not None:
+            return _subgroup_fit(self)
+
+        models = {
+            "outcome": _outcome_fit(
+                self,
+                self.DT,
+                self.outcome_col,
+                self.covariates,
+                self.weighted,
+                "weight",
+            )
+        }
+        if self.compevent_colname is not None:
+            models["compevent"] = _outcome_fit(
+                self,
+                self.DT,
+                self.compevent_colname,
+                self.covariates,
+                self.weighted,
+                "weight",
+            )
+        return models
+
+    def survival(self):
+        if not hasattr(self, "outcome_model") or not self.outcome_model:
+            raise ValueError(
+                "Outcome model not found. Please run the 'fit' method before calculating survival."
+            )
+
+        start = time.perf_counter()
+
+        risk_data = _pred_risk(self)
+        surv_data = _calculate_survival(self, risk_data)
+        self.km_data = pl.concat([risk_data, surv_data])
+        self.risk_estimates = _risk_estimates(self)
+
+        end = time.perf_counter()
+        self._survival_time = _format_time(start, end)
+
+    def hazard(self):
+        start = time.perf_counter()
+
+        if not hasattr(self, "outcome_model") or not self.outcome_model:
+            raise ValueError(
+                "Outcome model not found. Please run the 'fit' method before calculating hazard ratio."
+            )
+        self.hazard_ratio = _calculate_hazard(self)
+
+        end = time.perf_counter()
+        self._hazard_time = _format_time(start, end)
+
+    def plot(self):
+        self.km_graph = _survival_plot(self)
+
+    def collect(self):
+        self._time_collected = datetime.datetime.now()
+
+        generated = [
+            "numerator_model",
+            "denominator_model",
+            "outcome_model",
+            "hazard_ratio",
+            "risk_estimates",
+            "km_data",
+            "km_graph",
+            "diagnostics",
+            "_survival_time",
+            "_hazard_time",
+            "_model_time",
+            "_expansion_time",
+            "weight_stats",
+        ]
+        for attr in generated:
+            if not hasattr(self, attr):
+                setattr(self, attr, None)
+
+        # Options ==========================
+        base = SEQopts()
+
+        for name, value in vars(self).items():
+            if name in asdict(base).keys():
+                setattr(base, name, value)
+
+        # Timing =========================
+        time = {
+            "start_time": self._time_initialized,
+            "expansion_time": self._expansion_time,
+            "model_time": self._model_time,
+            "survival_time": self._survival_time,
+            "hazard_time": self._hazard_time,
+            "collection_time": self._time_collected,
+        }
+
+        if self.compevent_colname is not None:
+            compevent_models = [model["compevent"] for model in self.outcome_models]
+        else:
+            compevent_models = None
+
+        if self.outcome_model is not None:
+            outcome_models = [model["outcome"] for model in self.outcome_model]
+
+        if self.risk_estimates is None:
+            risk_ratio = risk_difference = None
+        else:
+            risk_ratio = self.risk_estimates["risk_ratio"]
+            risk_difference = self.risk_estimates["risk_difference"]
+
+        output = SEQoutput(
+            options=base,
+            method=self.method,
+            numerator_models=self.numerator_model,
+            denominator_models=self.denominator_model,
+            outcome_models=outcome_models,
+            compevent_models=compevent_models,
+            weight_statistics=self.weight_stats,
+            hazard=self.hazard_ratio,
+            km_data=self.km_data,
+            km_graph=self.km_graph,
+            risk_ratio=risk_ratio,
+            risk_difference=risk_difference,
+            time=time,
+            diagnostic_tables=self.diagnostics,
+        )
+
+        return output

pyseqtarget-0.9.0/pySEQTarget/__init__.py

@@ -0,0 +1,5 @@
+from .SEQopts import SEQopts
+from .SEQoutput import SEQoutput
+from .SEQuential import SEQuential
+
+__all__ = ["SEQuential", "SEQopts", "SEQoutput"]