scikit-survival 0.26.0__cp314-cp314-macosx_11_0_arm64.whl

sksurv/ensemble/survival_loss.py

@@ -0,0 +1,151 @@
+# 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 abc import ABCMeta
+
+import numpy as np
+from sklearn._loss.link import IdentityLink
+from sklearn._loss.loss import BaseLoss
+from sklearn.utils.extmath import squared_norm
+
+from ..nonparametric import ipc_weights
+from ._coxph_loss import coxph_loss, coxph_negative_gradient
+
+
+class SurvivalLossFunction(BaseLoss, metaclass=ABCMeta):  # noqa: B024
+    """Base class for survival loss functions."""
+
+    def __init__(self, sample_weight=None):
+        super().__init__(closs=None, link=IdentityLink())
+
+
+class CoxPH(SurvivalLossFunction):
+    """Cox Partial Likelihood"""
+
+    # pylint: disable=no-self-use
+
+    def __call__(self, y_true, raw_prediction, sample_weight=None):  # pylint: disable=unused-argument
+        """Compute the partial likelihood of prediction ``y_pred`` and ``y``."""
+        # TODO add support for sample weights
+        return coxph_loss(y_true["event"].astype(np.uint8), y_true["time"], raw_prediction.ravel())
+
+    def gradient(self, y_true, raw_prediction, sample_weight=None, **kwargs):  # pylint: disable=unused-argument
+        """Negative gradient of partial likelihood
+
+        Parameters
+        ---------
+        y : tuple, len = 2
+            First element is boolean event indicator and second element survival/censoring time.
+        y_pred : np.ndarray, shape=(n,):
+            The predictions.
+        """
+        ret = coxph_negative_gradient(y_true["event"].astype(np.uint8), y_true["time"], raw_prediction.ravel())
+        if sample_weight is not None:
+            ret *= sample_weight
+        return ret
+
+    def update_terminal_regions(
+        self, tree, X, y, residual, raw_predictions, sample_weight, sample_mask, learning_rate=0.1, k=0
+    ):
+        """Least squares does not need to update terminal regions.
+
+        But it has to update the predictions.
+        """
+        # update predictions
+        raw_predictions[:, k] += learning_rate * tree.predict(X).ravel()
+
+    def _update_terminal_region(self, tree, terminal_regions, leaf, X, y, residual, raw_predictions, sample_weight):
+        """Least squares does not need to update terminal regions"""
+
+    def _scale_raw_prediction(self, raw_predictions):
+        return raw_predictions
+
+
+class CensoredSquaredLoss(SurvivalLossFunction):
+    """Censoring-aware squared loss.
+
+    Censoring is taken into account by only considering the residuals
+    of samples that are not censored, or the predicted survival time
+    is before the time of censoring.
+    """
+
+    # pylint: disable=no-self-use
+    def __call__(self, y_true, raw_prediction, sample_weight=None):
+        """Compute the partial likelihood of prediction ``y_pred`` and ``y``."""
+        pred_time = y_true["time"] - raw_prediction.ravel()
+        mask = (pred_time > 0) | y_true["event"]
+        return 0.5 * squared_norm(pred_time.compress(mask, axis=0))
+
+    def gradient(self, y_true, raw_prediction, **kwargs):  # pylint: disable=unused-argument
+        """Negative gradient of partial likelihood
+
+        Parameters
+        ---------
+        y : tuple, len = 2
+            First element is boolean event indicator and second element survival/censoring time.
+        y_pred : np.ndarray, shape=(n,):
+            The predictions.
+        """
+        pred_time = y_true["time"] - raw_prediction.ravel()
+        mask = (pred_time > 0) | y_true["event"]
+        ret = np.zeros(y_true["event"].shape[0])
+        ret[mask] = pred_time.compress(mask, axis=0)
+        return ret
+
+    def update_terminal_regions(
+        self, tree, X, y, residual, raw_predictions, sample_weight, sample_mask, learning_rate=0.1, k=0
+    ):
+        """Least squares does not need to update terminal regions.
+
+        But it has to update the predictions.
+        """
+        # update predictions
+        raw_predictions[:, k] += learning_rate * tree.predict(X).ravel()
+
+    def _update_terminal_region(self, tree, terminal_regions, leaf, X, y, residual, raw_predictions, sample_weight):
+        """Least squares does not need to update terminal regions"""
+
+    def _scale_raw_prediction(self, raw_predictions):
+        np.exp(raw_predictions, out=raw_predictions)
+        return raw_predictions
+
+
+class IPCWLeastSquaresError(SurvivalLossFunction):
+    """Inverse probability of censoring weighted least squares error"""
+
+    # pylint: disable=no-self-use
+
+    def __call__(self, y_true, raw_prediction, sample_weight=None):
+        sample_weight = ipc_weights(y_true["event"], y_true["time"])
+        return 1.0 / sample_weight.sum() * np.sum(sample_weight * ((y_true["time"] - raw_prediction.ravel()) ** 2.0))
+
+    def gradient(self, y_true, raw_prediction, **kwargs):  # pylint: disable=unused-argument
+        return y_true["time"] - raw_prediction.ravel()
+
+    def update_terminal_regions(self, tree, X, y, residual, y_pred, sample_weight, sample_mask, learning_rate=0.1, k=0):
+        y_pred[:, k] += learning_rate * tree.predict(X).ravel()
+
+    def _update_terminal_region(
+        self, tree, terminal_regions, leaf, X, y, residual, pred, sample_weight
+    ):  # pragma: no cover
+        pass
+
+    def _scale_raw_prediction(self, raw_predictions):
+        np.exp(raw_predictions, out=raw_predictions)
+        return raw_predictions
+
+
+LOSS_FUNCTIONS = {
+    "coxph": CoxPH,
+    "squared": CensoredSquaredLoss,
+    "ipcwls": IPCWLeastSquaresError,
+}

sksurv/exceptions.py

@@ -0,0 +1,18 @@
+# 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/>.
+
+
+class NoComparablePairException(ValueError):
+    """An error indicating that data of censored event times
+    does not contain one or more comparable pairs.
+    """

sksurv/functions.py

@@ -0,0 +1,114 @@
+# 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
+from sklearn.utils.validation import check_consistent_length
+
+__all__ = ["StepFunction"]
+
+
+class StepFunction:
+    r"""A callable step function.
+
+    The function is defined by a set of points :math:`(x_i, y_i)` and is
+    evaluated as:
+
+    .. math::
+
+        f(z) = a \cdot y_i + b \quad \text{if} \quad x_i \leq z < x_{i + 1}
+
+    Parameters
+    ----------
+    x : ndarray, shape = (n_points,)
+        The values on the x-axis, must be in ascending order.
+    y : ndarray, shape = (n_points,)
+        The corresponding values on the y-axis.
+    a : float, optional, default: 1.0
+        A constant factor to scale ``y`` by.
+    b : float, optional, default: 0.0
+        A constant offset term.
+    domain : tuple, optional, default: (0, None)
+        A tuple ``(lower, upper)`` that defines the domain of the step function.
+        If ``lower`` or ``upper`` is ``None``, the first or last value of ``x`` is
+        used as the limit, respectively.
+    """
+
+    def __init__(self, x, y, *, a=1.0, b=0.0, domain=(0, None)):
+        check_consistent_length(x, y)
+        self.x = x
+        self.y = y
+        self.a = a
+        self.b = b
+        domain_lower = self.x[0] if domain[0] is None else domain[0]
+        domain_upper = self.x[-1] if domain[1] is None else domain[1]
+        self._domain = (float(domain_lower), float(domain_upper))
+
+    @property
+    def domain(self):
+        """The domain of the function.
+
+        The domain is the range of values that the function accepts.
+
+        Returns
+        -------
+        lower_limit : float
+            Lower limit of the omain.
+
+        upper_limit : float
+            Upper limit of the domain.
+        """
+        return self._domain
+
+    def __call__(self, x):
+        """Evaluate the step function at given values.
+
+        Parameters
+        ----------
+        x : float or array-like, shape=(n_values,)
+            The values at which to evaluate the step function.
+            Values must be within the function's ``domain``.
+
+        Returns
+        -------
+        y : float or array-like, shape=(n_values,)
+            The value of the step function at ``x``.
+
+        Raises
+        ------
+        ValueError
+            If ``x`` contains values outside the function's ``domain``.
+        """
+        x = np.atleast_1d(x)
+        if not np.isfinite(x).all():
+            raise ValueError("x must be finite")
+        if np.min(x) < self._domain[0] or np.max(x) > self.domain[1]:
+            raise ValueError(f"x must be within [{self.domain[0]:f}; {self.domain[1]:f}]")
+
+        # x is within the domain, but we need to account for self.domain[0] <= x < self.x[0]
+        x = np.clip(x, a_min=self.x[0], a_max=None)
+
+        i = np.searchsorted(self.x, x, side="left")
+        not_exact = self.x[i] != x
+        i[not_exact] -= 1
+        value = self.a * self.y[i] + self.b
+        if value.shape[0] == 1:
+            return value[0]
+        return value
+
+    def __repr__(self):
+        return f"StepFunction(x={self.x!r}, y={self.y!r}, a={self.a!r}, b={self.b!r})"
+
+    def __eq__(self, other):
+        if isinstance(other, type(self)):
+            return all(self.x == other.x) and all(self.y == other.y) and self.a == other.a and self.b == other.b
+        return False

sksurv/io/__init__.py

@@ -0,0 +1,2 @@
+from .arffread import loadarff  # noqa: F401
+from .arffwrite import writearff  # noqa: F401

sksurv/io/arffread.py

@@ -0,0 +1,91 @@
+# 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
+import pandas as pd
+from pandas.api.types import is_string_dtype
+from scipy.io.arff import loadarff as scipy_loadarff
+
+__all__ = ["loadarff"]
+
+
+def _to_pandas(data, meta):
+    data_dict = {}
+    attrnames = sorted(meta.names())
+    for name in attrnames:
+        tp, attr_format = meta[name]
+        if tp == "nominal":
+            raw = []
+            for b in data[name]:
+                # replace missing values with NaN
+                if b == b"?":
+                    raw.append(np.nan)
+                else:
+                    raw.append(b.decode())
+
+            data_dict[name] = pd.Categorical(raw, categories=attr_format, ordered=False)
+        else:
+            arr = data[name]
+            dtype = "str" if is_string_dtype(arr.dtype) else arr.dtype
+            p = pd.Series(arr, dtype=dtype)
+            data_dict[name] = p
+
+    # currently, this step converts all pandas.Categorial columns back to pandas.Series
+    return pd.DataFrame.from_dict(data_dict)
+
+
+def loadarff(filename):
+    """Load ARFF file.
+
+    Parameters
+    ----------
+    filename : str or file-like
+        Path to ARFF file, or file-like object to read from.
+
+    Returns
+    -------
+    data_frame : :class:`pandas.DataFrame`
+        DataFrame containing data of ARFF file
+
+    See Also
+    --------
+    scipy.io.arff.loadarff : The underlying function that reads the ARFF file.
+
+    Examples
+    --------
+    >>> from io import StringIO
+    >>> from sksurv.io import loadarff
+    >>>
+    >>> # Create a dummy ARFF file
+    >>> arff_content = '''
+    ... @relation test_data
+    ... @attribute feature1 numeric
+    ... @attribute feature2 numeric
+    ... @attribute class {A,B,C}
+    ... @data
+    ... 1.0,2.0,A
+    ... 3.0,4.0,B
+    ... 5.0,6.0,C
+    ... '''
+    >>>
+    >>> # Load the ARFF file
+    >>> with StringIO(arff_content) as f:
+    ...     data = loadarff(f)
+    >>>
+    >>> print(data)
+      class  feature1  feature2
+    0     A       1.0       2.0
+    1     B       3.0       4.0
+    2     C       5.0       6.0
+    """
+    data, meta = scipy_loadarff(filename)
+    return _to_pandas(data, meta)

sksurv/io/arffwrite.py

@@ -0,0 +1,181 @@
+# 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 os.path
+import re
+
+import numpy as np
+import pandas as pd
+from pandas.api.types import CategoricalDtype, is_string_dtype
+
+_ILLEGAL_CHARACTER_PAT = re.compile(r"[^-_=\w\d\(\)<>\.]")
+
+
+def writearff(data, filename, relation_name=None, index=True):
+    """Write ARFF file
+
+    Parameters
+    ----------
+    data : :class:`pandas.DataFrame`
+        DataFrame containing data
+
+    filename : str or file-like object
+        Path to ARFF file or file-like object. In the latter case,
+        the handle is closed by calling this function.
+
+    relation_name : str, optional, default: 'pandas'
+        Name of relation in ARFF file.
+
+    index : boolean, optional, default: True
+        Write row names (index)
+
+    See Also
+    --------
+    loadarff : Function to read ARFF files.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> import pandas as pd
+    >>> from sksurv.io import writearff
+    >>>
+    >>> # Create a dummy DataFrame
+    >>> data = pd.DataFrame({
+    ...     'feature1': [1.0, 3.0, 5.0],
+    ...     'feature2': [2.0, np.nan, 6.0],
+    ...     'class': ['A', 'B', 'C']
+    ... }, index=['One', 'Two', 'Three'])
+    >>>
+    >>> # Write to ARFF file
+    >>> writearff(data, 'test_output.arff', relation_name='test_data')
+    >>>
+    >>> # Read contents of ARFF file
+    >>> with open('test_output.arff') as f:
+    ...     arff_contents = "".join(f.readlines())
+    >>> print(arff_contents)
+    @relation test_data
+    <BLANKLINE>
+    @attribute index        {One,Three,Two}
+    @attribute feature1     real
+    @attribute feature2     real
+    @attribute class        {A,B,C}
+    <BLANKLINE>
+    @data
+    One,1.0,2.0,A
+    Two,3.0,?,B
+    Three,5.0,6.0,C
+    """
+    if isinstance(filename, str):
+        fp = open(filename, "w")
+
+        if relation_name is None:
+            relation_name = os.path.basename(filename)
+    else:
+        fp = filename
+
+        if relation_name is None:
+            relation_name = "pandas"
+
+    try:
+        data = _write_header(data, fp, relation_name, index)
+        fp.write("\n")
+        _write_data(data, fp)
+    finally:
+        fp.close()
+
+
+def _write_header(data, fp, relation_name, index):
+    """Write header containing attribute names and types"""
+    fp.write(f"@relation {relation_name}\n\n")
+
+    if index:
+        data = data.reset_index()
+
+    attribute_names = _sanitize_column_names(data)
+
+    for column, series in data.items():
+        name = attribute_names[column]
+        fp.write(f"@attribute {name}\t")
+
+        if isinstance(series.dtype, CategoricalDtype) or is_string_dtype(series.dtype):
+            _write_attribute_categorical(series, fp)
+        elif np.issubdtype(series.dtype, np.floating):
+            fp.write("real")
+        elif np.issubdtype(series.dtype, np.integer):
+            fp.write("integer")
+        elif np.issubdtype(series.dtype, np.datetime64):
+            fp.write("date 'yyyy-MM-dd HH:mm:ss'")
+        else:
+            raise TypeError(f"unsupported type {series.dtype}")
+
+        fp.write("\n")
+    return data
+
+
+def _sanitize_column_names(data):
+    """Replace illegal characters with underscore"""
+    new_names = {}
+    for name in data.columns:
+        new_names[name] = _ILLEGAL_CHARACTER_PAT.sub("_", name)
+    return new_names
+
+
+def _check_str_value(x):
+    """If string has a space, wrap it in double quotes and remove/escape illegal characters"""
+    if isinstance(x, str):
+        # remove commas, and single quotation marks since loadarff cannot deal with it
+        x = x.replace(",", ".").replace(chr(0x2018), "'").replace(chr(0x2019), "'")
+
+        # put string in double quotes
+        if " " in x:
+            if x[0] in ('"', "'"):
+                x = x[1:]
+            if x[-1] in ('"', "'"):
+                x = x[: len(x) - 1]
+            x = '"' + x.replace('"', '\\"') + '"'
+    return str(x)
+
+
+_check_str_array = np.frompyfunc(_check_str_value, 1, 1)
+
+
+def _write_attribute_categorical(series, fp):
+    """Write categories of a categorical/nominal attribute"""
+    if isinstance(series.dtype, CategoricalDtype):
+        categories = series.cat.categories
+        string_values = _check_str_array(categories)
+    else:
+        categories = series.dropna().unique()
+        string_values = sorted(_check_str_array(categories), key=lambda x: x.strip('"'))
+
+    values = ",".join(string_values)
+    fp.write("{")
+    fp.write(values)
+    fp.write("}")
+
+
+def _write_data(data, fp):
+    """Write the data section"""
+    fp.write("@data\n")
+
+    def to_str(x):
+        if pd.isna(x):
+            return "?"
+        return str(x)
+
+    data = data.applymap(to_str)
+    n_rows = data.shape[0]
+    for i in range(n_rows):
+        str_values = list(data.iloc[i, :].apply(_check_str_array))
+        line = ",".join(str_values)
+        fp.write(line)
+        fp.write("\n")

sksurv/kernels/__init__.py

@@ -0,0 +1 @@
+from .clinical import ClinicalKernelTransform, clinical_kernel  # noqa: F401