scikit-survival 0.26.0__cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl

sksurv/__init__.py

@@ -0,0 +1,183 @@
+from importlib.metadata import PackageNotFoundError, version
+import platform
+import sys
+
+from sklearn.pipeline import Pipeline, _final_estimator_has
+from sklearn.utils.metaestimators import available_if
+
+from .util import property_available_if
+
+
+def _get_version(name):
+    try:
+        pkg_version = version(name)
+    except ImportError:
+        pkg_version = None
+    return pkg_version
+
+
+def show_versions():
+    """Print debugging information."""
+    sys_info = {
+        "Platform": platform.platform(),
+        "Python version": f"{platform.python_implementation()} {platform.python_version()}",
+        "Python interpreter": sys.executable,
+    }
+
+    deps = [
+        "scikit-survival",
+        "scikit-learn",
+        "numpy",
+        "scipy",
+        "pandas",
+        "numexpr",
+        "ecos",
+        "osqp",
+        "joblib",
+        "matplotlib",
+        "pytest",
+        "sphinx",
+        "Cython",
+        "pip",
+        "setuptools",
+    ]
+    minwidth = max(
+        max(map(len, deps)),
+        max(map(len, sys_info.keys())),
+    )
+    fmt = f"{{0:<{minwidth}s}}: {{1}}"
+
+    print("SYSTEM")
+    print("------")
+    for name, version_string in sys_info.items():
+        print(fmt.format(name, version_string))
+
+    print("\nDEPENDENCIES")
+    print("------------")
+    for dep in deps:
+        version_string = _get_version(dep)
+        print(fmt.format(dep, version_string))
+
+
+@available_if(_final_estimator_has("predict_cumulative_hazard_function"))
+def predict_cumulative_hazard_function(self, X, **kwargs):
+    r"""Predict cumulative hazard function for a pipeline.
+
+    The cumulative hazard function for an individual
+    with feature vector :math:`x` is defined as
+
+    .. math::
+
+        H(t \mid x) = \exp(x^\top \beta) H_0(t) ,
+
+    where :math:`H_0(t)` is the baseline hazard function,
+    estimated by Breslow's estimator.
+
+    Parameters
+    ----------
+    X : array-like, shape = (n_samples, n_features)
+        Data matrix.
+
+    Returns
+    -------
+    cum_hazard : ndarray, shape = (n_samples,)
+        Predicted cumulative hazard functions. Each element is an instance
+        of :class:`sksurv.functions.StepFunction`.
+
+    See Also
+    --------
+    predict_survival_function : Predict survival function for a pipeline.
+
+    Examples
+    --------
+    >>> from sksurv.datasets import load_whas500
+    >>> from sksurv.linear_model import CoxPHSurvivalAnalysis
+    >>> from sksurv.preprocessing import OneHotEncoder
+    >>> from sklearn.pipeline import Pipeline
+    >>>
+    >>> X, y = load_whas500()
+    >>> pipe = Pipeline([('encode', OneHotEncoder()),
+    ...                  ('cox', CoxPHSurvivalAnalysis())])
+    >>> pipe.fit(X, y)
+    Pipeline(...)
+    >>> chf = pipe.predict_cumulative_hazard_function(X.iloc[:5])
+    >>> for fn in chf:
+    ...     print(fn.x, fn.y)
+    [...]
+    """
+    Xt = X
+    for _, _, transform in self._iter(with_final=False):
+        Xt = transform.transform(Xt)
+    return self.steps[-1][-1].predict_cumulative_hazard_function(Xt, **kwargs)
+
+
+@available_if(_final_estimator_has("predict_survival_function"))
+def predict_survival_function(self, X, **kwargs):
+    r"""Predict survival function for a pipeline.
+
+    The survival function for an individual
+    with feature vector :math:`x` is defined as
+
+    .. math::
+
+        S(t \mid x) = S_0(t)^{\exp(x^\top \beta)} ,
+
+    where :math:`S_0(t)` is the baseline survival function,
+    estimated by Breslow's estimator.
+
+    Parameters
+    ----------
+    X : array-like, shape = (n_samples, n_features)
+        Data matrix.
+
+    Returns
+    -------
+    survival : ndarray, shape = (n_samples,)
+        Predicted survival functions. Each element is an instance
+        of :class:`sksurv.functions.StepFunction`.
+
+    See Also
+    --------
+    predict_cumulative_hazard_function : Predict cumulative hazard function for a pipeline.
+
+    Examples
+    --------
+    >>> from sksurv.datasets import load_whas500
+    >>> from sksurv.linear_model import CoxPHSurvivalAnalysis
+    >>> from sksurv.preprocessing import OneHotEncoder
+    >>> from sklearn.pipeline import Pipeline
+    >>>
+    >>> X, y = load_whas500()
+    >>> pipe = Pipeline([('encode', OneHotEncoder()),
+    ...                  ('cox', CoxPHSurvivalAnalysis())])
+    >>> pipe.fit(X, y)
+    Pipeline(...)
+    >>> surv_fn = pipe.predict_survival_function(X.iloc[:5])
+    >>> for fn in surv_fn:
+    ...     print(fn.x, fn.y)
+    [...]
+    """
+    Xt = X
+    for _, _, transform in self._iter(with_final=False):
+        Xt = transform.transform(Xt)
+    return self.steps[-1][-1].predict_survival_function(Xt, **kwargs)
+
+
+@property_available_if(_final_estimator_has("_predict_risk_score"))
+def _predict_risk_score(self):
+    return self.steps[-1][-1]._predict_risk_score
+
+
+def patch_pipeline():
+    Pipeline.predict_survival_function = predict_survival_function
+    Pipeline.predict_cumulative_hazard_function = predict_cumulative_hazard_function
+    Pipeline._predict_risk_score = _predict_risk_score
+
+
+try:
+    __version__ = version("scikit-survival")
+except PackageNotFoundError:  # pragma: no cover
+    # package is not installed
+    __version__ = "unknown"
+
+patch_pipeline()

sksurv/base.py

@@ -0,0 +1,115 @@
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+import numpy as np
+
+
+class SurvivalAnalysisMixin:
+    def _predict_function(self, func_name, baseline_model, prediction, return_array):
+        fns = getattr(baseline_model, func_name)(prediction)
+
+        if not return_array:
+            return fns
+
+        times = baseline_model.unique_times_
+        arr = np.empty((prediction.shape[0], times.shape[0]), dtype=float)
+        for i, fn in enumerate(fns):
+            arr[i, :] = fn(times)
+        return arr
+
+    def _predict_survival_function(self, baseline_model, prediction, return_array):
+        """Return survival functions.
+
+        Parameters
+        ----------
+        baseline_model : sksurv.linear_model.coxph.BreslowEstimator
+            Estimator of baseline survival function.
+
+        prediction : array-like, shape=(n_samples,)
+            Predicted risk scores.
+
+        return_array : bool
+            If True, return a float array of the survival function
+            evaluated at the unique event times, otherwise return
+            an array of :class:`sksurv.functions.StepFunction` instances.
+
+        Returns
+        -------
+        survival : ndarray of StepFunction
+            If `return_array` is True, an array of shape (n_samples, n_unique_times)
+            containing the survival function values. Otherwise, a list of
+            :class:`sksurv.functions.StepFunction` instances.
+        """
+        return self._predict_function("get_survival_function", baseline_model, prediction, return_array)
+
+    def _predict_cumulative_hazard_function(self, baseline_model, prediction, return_array):
+        """Return cumulative hazard functions.
+
+        Parameters
+        ----------
+        baseline_model : sksurv.linear_model.coxph.BreslowEstimator
+            Estimator of baseline cumulative hazard function.
+
+        prediction : array-like, shape=(n_samples,)
+            Predicted risk scores.
+
+        return_array : bool
+            If True, return a float array of the cumulative hazard function
+            evaluated at the unique event times, otherwise return
+            an array of :class:`sksurv.functions.StepFunction` instances.
+
+        Returns
+        -------
+        cum_hazard : ndarray of StepFunction
+            If `return_array` is True, an array of shape (n_samples, n_unique_times)
+            containing the cumulative hazard function values. Otherwise, a list of
+            :class:`sksurv.functions.StepFunction` instances.
+        """
+        return self._predict_function("get_cumulative_hazard_function", baseline_model, prediction, return_array)
+
+    def score(self, X, y):
+        """Returns the concordance index of the prediction.
+
+        Parameters
+        ----------
+        X : array-like, shape = (n_samples, n_features)
+            Test samples.
+
+        y : structured array, shape = (n_samples,)
+            A structured array containing the binary event indicator
+            as first field, and time of event or time of censoring as
+            second field.
+
+        Returns
+        -------
+        cindex : float
+            Estimated concordance index.
+
+        See also
+        --------
+        sksurv.metrics.concordance_index_censored : Computes the concordance index.
+        """
+        from .metrics import concordance_index_censored
+
+        name_event, name_time = y.dtype.names
+
+        risk_score = self.predict(X)
+        if not getattr(self, "_predict_risk_score", True):
+            risk_score *= -1  # convert prediction on time scale to risk scale
+
+        result = concordance_index_censored(y[name_event], y[name_time], risk_score)
+        return result[0]
+
+    def __sklearn_tags__(self):
+        tags = super().__sklearn_tags__()
+        tags.target_tags.required = True
+        return tags

sksurv/bintrees/__init__.py

@@ -0,0 +1,15 @@
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+from ._binarytrees import AATree, AVLTree, RBTree
+
+__all__ = ["RBTree", "AVLTree", "AATree"]

sksurv/column.py

@@ -0,0 +1,204 @@
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+import logging
+
+import numpy as np
+import pandas as pd
+from pandas.api.types import CategoricalDtype, is_string_dtype
+
+__all__ = ["categorical_to_numeric", "encode_categorical", "standardize"]
+
+
+def _apply_along_column(array, func1d, **kwargs):
+    if isinstance(array, pd.DataFrame):
+        return array.apply(func1d, **kwargs)
+    return np.apply_along_axis(func1d, 0, array, **kwargs)
+
+
+def standardize_column(series_or_array, with_std=True):
+    d = series_or_array.dtype
+    if issubclass(d.type, np.number):
+        output = series_or_array.astype(float)
+        m = series_or_array.mean()
+        output -= m
+
+        if with_std:
+            s = series_or_array.std(ddof=1)
+            output /= s
+
+        return output
+
+    return series_or_array
+
+
+def standardize(table, with_std=True):
+    """Standardize numeric features by removing the mean and scaling to unit variance.
+
+    This function performs Z-Normalization on each numeric column of the given
+    table.
+
+    If `table` is a :class:`pandas.DataFrame`, only numeric columns are modified;
+    all other columns remain unchanged. If `table` is a :class:`numpy.ndarray`,
+    it is only modified if it has a numeric dtype, in which case the returned
+    array will have a floating-point dtype.
+
+    Parameters
+    ----------
+    table : pandas.DataFrame or numpy.ndarray
+        Data to standardize.
+    with_std : bool, optional, default: True
+        If ``False``, data is only centered (mean removed) and not scaled to
+        unit variance.
+
+    Returns
+    -------
+    normalized : pandas.DataFrame or numpy.ndarray
+        The standardized data. The output type will be the same as the input type.
+    """
+    new_frame = _apply_along_column(table, standardize_column, with_std=with_std)
+
+    return new_frame
+
+
+def _encode_categorical_series(series, allow_drop=True):
+    values = _get_dummies_1d(series, allow_drop=allow_drop)
+    if values is None:
+        return
+
+    enc, levels = values
+    if enc is None:
+        return pd.Series(index=series.index, name=series.name, dtype=series.dtype)
+
+    if not allow_drop and enc.shape[1] == 1:
+        return series
+
+    names = []
+    for key in range(1, enc.shape[1]):
+        names.append(f"{series.name}={levels[key]}")
+    series = pd.DataFrame(enc[:, 1:], columns=names, index=series.index)
+
+    return series
+
+
+def encode_categorical(table, columns=None, **kwargs):
+    """One-hot encode categorical features.
+
+    This function creates a binary column for each category and, by default,
+    drops one of the categories per feature: a column with `M` categories
+    is encoded as `M-1` integer columns according to the one-hot
+    scheme.
+
+    Parameters
+    ----------
+    table : pandas.DataFrame or pandas.Series
+        Data with categorical columns to encode.
+    columns : list-like, optional, default: None
+        Column names in the DataFrame to be encoded.
+        If `columns` is `None`, all columns with `object` or `category`
+        dtype will be converted. This parameter is ignored if `table` is a
+        pandas.Series.
+    allow_drop : bool, optional, default: True
+        Whether to allow dropping categorical columns that only consist
+        of a single category.
+
+    Returns
+    -------
+    encoded : pandas.DataFrame
+        The transformed data with categorical columns encoded as numeric.
+        Numeric columns in the input table remain unchanged.
+    """
+    if isinstance(table, pd.Series):
+        if not isinstance(table.dtype, CategoricalDtype) and not is_string_dtype(table.dtype):
+            raise TypeError(f"series must be of categorical dtype, but was {table.dtype}")
+        return _encode_categorical_series(table, **kwargs)
+
+    def _is_categorical_or_object(series):
+        return isinstance(series.dtype, CategoricalDtype) or is_string_dtype(series.dtype)
+
+    if columns is None:
+        # for columns containing categories
+        columns_to_encode = {nam for nam, s in table.items() if _is_categorical_or_object(s)}
+    else:
+        columns_to_encode = set(columns)
+
+    items = []
+    for name, series in table.items():
+        if name in columns_to_encode:
+            series = _encode_categorical_series(series, **kwargs)
+            if series is None:
+                continue
+        items.append(series)
+
+    # concat columns of tables
+    new_table = pd.concat(items, axis=1, copy=False)
+    return new_table
+
+
+def _get_dummies_1d(data, allow_drop=True):
+    # Series avoids inconsistent NaN handling
+    cat = pd.Categorical(data)
+    levels = cat.categories
+    number_of_cols = len(levels)
+
+    # if all NaN or only one level
+    if allow_drop and number_of_cols < 2:
+        logging.getLogger(__package__).warning(
+            f"dropped categorical variable {data.name!r}, because it has only {number_of_cols} values"
+        )
+        return
+    if number_of_cols == 0:
+        return None, levels
+
+    dummy_mat = np.eye(number_of_cols).take(cat.codes, axis=0)
+
+    # reset NaN GH4446
+    dummy_mat[cat.codes == -1] = np.nan
+
+    return dummy_mat, levels
+
+
+def categorical_to_numeric(table):
+    """Encode categorical features as integers.
+
+    This function converts each category to a unique integer value.
+
+    Parameters
+    ----------
+    table : pandas.DataFrame or pandas.Series
+        Data with categorical columns to encode.
+
+    Returns
+    -------
+    encoded : pandas.DataFrame or pandas.Series
+        The transformed data with categorical columns encoded as integers.
+        The output type will be the same as the input type.
+    """
+
+    def transform(column):
+        if isinstance(column.dtype, CategoricalDtype):
+            return column.cat.codes
+        if is_string_dtype(column.dtype):
+            try:
+                nc = column.astype(np.int64)
+            except ValueError:
+                classes = column.dropna().unique()
+                nc = column.map(dict(zip(sorted(classes), range(classes.shape[0]))))
+            return nc
+        if column.dtype == bool:
+            return column.astype(np.int64)
+
+        return column
+
+    if isinstance(table, pd.Series):
+        return pd.Series(transform(table), name=table.name, index=table.index)
+    return table.apply(transform, axis=0, result_type="expand")

sksurv/compare.py

@@ -0,0 +1,123 @@
+from collections import OrderedDict
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+from sklearn.utils.validation import check_array
+
+from .util import check_array_survival
+
+__all__ = ["compare_survival"]
+
+
+def compare_survival(y, group_indicator, return_stats=False):
+    """Compare survival functions of two or more groups using the log-rank test.
+
+    The log-rank test is a non-parametric hypothesis test for comparing the
+    survival functions of two or more independent groups. The null hypothesis is
+    that the survival functions of the groups are identical. The alternative
+    hypothesis is that at least one survival function differs from the others.
+
+    The test statistic is approximately chi-squared distributed with :math:`K-1`
+    degrees of freedom, where :math:`K` is the number of groups.
+
+    See [1]_ for more details.
+
+    Parameters
+    ----------
+    y : structured array, shape = (n_samples,)
+        A structured array with two fields. The first field is a boolean
+        where ``True`` indicates an event and ``False`` indicates right-censoring.
+        The second field is a float with the time of event or time of censoring.
+    group_indicator : array-like, shape = (n_samples,)
+        Group membership of each sample.
+    return_stats : bool, optional, default: False
+        Whether to return a data frame with statistics for each group and the
+        covariance matrix of the test statistic.
+
+    Returns
+    -------
+    chisq : float
+        The test statistic.
+    pvalue : float
+        The two-sided p-value for the test.
+    stats : pandas.DataFrame, optional
+        A DataFrame with summary statistics for each group. This includes the
+        number of samples, observed number of events, expected number of events,
+        and the test statistic. Only returned if ``return_stats`` is ``True``.
+    covariance : ndarray, shape=(n_groups, n_groups), optional
+        The covariance matrix of the test statistic. Only returned if
+        ``return_stats`` is ``True``.
+
+    References
+    ----------
+    .. [1] Fleming, T. R. and Harrington, D. P.
+           A Class of Hypothesis Tests for One and Two Samples of Censored Survival Data.
+           Communications In Statistics 10 (1981): 763-794.
+    """
+
+    event, time = check_array_survival(group_indicator, y)
+    group_indicator = check_array(
+        group_indicator,
+        dtype="O",
+        ensure_2d=False,
+        estimator="compare_survival",
+        input_name="group_indicator",
+    )
+
+    n_samples = time.shape[0]
+    groups, group_counts = np.unique(group_indicator, return_counts=True)
+    n_groups = groups.shape[0]
+    if n_groups == 1:
+        raise ValueError("At least two groups must be specified, but only one was provided.")
+
+    # sort descending
+    o = np.argsort(-time, kind="mergesort")
+    x = group_indicator[o]
+    event = event[o]
+    time = time[o]
+
+    at_risk = np.zeros(n_groups, dtype=int)
+    observed = np.zeros(n_groups, dtype=int)
+    expected = np.zeros(n_groups, dtype=float)
+    covar = np.zeros((n_groups, n_groups), dtype=float)
+
+    covar_indices = np.diag_indices(n_groups)
+
+    k = 0
+    while k < n_samples:
+        ti = time[k]
+        total_events = 0
+        while k < n_samples and ti == time[k]:
+            idx = np.searchsorted(groups, x[k])
+            if event[k]:
+                observed[idx] += 1
+                total_events += 1
+            at_risk[idx] += 1
+            k += 1
+
+        if total_events != 0:
+            total_at_risk = k
+            expected += at_risk * (total_events / total_at_risk)
+            if total_at_risk > 1:
+                multiplier = total_events * (total_at_risk - total_events) / (total_at_risk * (total_at_risk - 1))
+                temp = at_risk * multiplier
+                covar[covar_indices] += temp
+                covar -= np.outer(temp, at_risk) / total_at_risk
+
+    df = n_groups - 1
+    zz = observed[:df] - expected[:df]
+    chisq = np.linalg.solve(covar[:df, :df], zz).dot(zz)
+    pval = stats.chi2.sf(chisq, df)
+
+    if return_stats:
+        table = OrderedDict()
+        table["counts"] = group_counts
+        table["observed"] = observed
+        table["expected"] = expected
+        table["statistic"] = observed - expected
+        table = pd.DataFrame.from_dict(table)
+        table.index = pd.Index(groups, name="group")
+        return chisq, pval, table, covar
+
+    return chisq, pval

sksurv/datasets/__init__.py

@@ -0,0 +1,12 @@
+from .base import (
+    get_x_y,  # noqa: F401
+    load_aids,  # noqa: F401
+    load_arff_files_standardized,  # noqa: F401
+    load_bmt,  # noqa: F401
+    load_breast_cancer,  # noqa: F401
+    load_cgvhd,  # noqa: F401
+    load_flchain,  # noqa: F401
+    load_gbsg2,  # noqa: F401
+    load_veterans_lung_cancer,  # noqa: F401
+    load_whas500,  # noqa: F401
+)