scikit-survival 0.24.1__cp311-cp311-win_amd64.whl → 0.25.0__cp311-cp311-win_amd64.whl

sksurv/kernels/clinical.py

@@ -62,10 +62,11 @@ def _ordinal_as_numeric(x, ordinal_columns):
 
 
 def clinical_kernel(x, y=None):
-    """Computes clinical kernel
+    """Computes clinical kernel.
 
     The clinical kernel distinguishes between continuous
-    ordinal,and nominal variables.
+    ordinal, and nominal variables.
+    Kernel values are normalized to lie within [0, 1].
 
     See [1]_ for further description.
 
@@ -80,13 +81,30 @@ def clinical_kernel(x, y=None):
     Returns
     -------
     kernel : array, shape = (n_samples_x, n_samples_y)
-        Kernel matrix. Values are normalized to lie within [0, 1].
+        Kernel matrix.
 
     References
     ----------
     .. [1] Daemen, A., De Moor, B.,
            "Development of a kernel function for clinical data".
            Annual International Conference of the IEEE Engineering in Medicine and Biology Society, 5913-7, 2009
+
+    Examples
+    --------
+    >>> import pandas as pd
+    >>> from sksurv.kernels import clinical_kernel
+    >>>
+    >>> data = pd.DataFrame({
+    ...     'feature_num': [1.0, 2.0, 3.0],
+    ...     'feature_ord': pd.Categorical(['low', 'medium', 'high'], ordered=True),
+    ...     'feature_nom': pd.Categorical(['A', 'B', 'A'])
+    ... })
+    >>>
+    >>> kernel_matrix = clinical_kernel(data)
+    >>> print(kernel_matrix)
+    [[1.         0.33333333 0.5       ]
+     [0.33333333 1.         0.16666667]
+     [0.5        0.16666667 1.        ]]
     """
     if y is not None:
         if x.shape[1] != y.shape[1]:
@@ -114,7 +132,7 @@ class ClinicalKernelTransform(BaseEstimator, TransformerMixin):
     """Transform data using a clinical Kernel
 
     The clinical kernel distinguishes between continuous
-    ordinal,and nominal variables.
+    ordinal, and nominal variables.
 
     See [1]_ for further description.
 
@@ -131,7 +149,7 @@ class ClinicalKernelTransform(BaseEstimator, TransformerMixin):
     n_features_in_ : int
         Number of features seen during ``fit``.
 
-    feature_names_in_ : ndarray of shape (`n_features_in_`,)
+    feature_names_in_ : ndarray, shape = (`n_features_in_`,)
         Names of features seen during ``fit``. Defined only when `X`
         has feature names that are all strings.
 
@@ -214,10 +232,12 @@ class ClinicalKernelTransform(BaseEstimator, TransformerMixin):
             Data to estimate parameters from.
 
         y : None
-            Argument is ignored (included for compatibility reasons).
+            Ignored. This parameter exists only for compatibility with
+            :class:`sklearn.pipeline.Pipeline`.
 
         kwargs : dict
-            Argument is ignored (included for compatibility reasons).
+            Ignored. This parameter exists only for compatibility with
+            :class:`sklearn.pipeline.Pipeline`.
 
         Returns
         -------
@@ -281,10 +301,10 @@ class ClinicalKernelTransform(BaseEstimator, TransformerMixin):
 
         Parameters
         ----------
-        x : array-like, shape = (n_samples_x, n_features)
+        x : pandas.DataFrame, shape = (n_samples_x, n_features)
             Training data
 
-        y : array-like, shape = (n_samples_y, n_features)
+        y : pandas.DataFrame, shape = (n_samples_y, n_features)
             Testing data
 
         Returns
@@ -295,18 +315,18 @@ class ClinicalKernelTransform(BaseEstimator, TransformerMixin):
         return self.fit(X).transform(Y).T
 
     def pairwise_kernel(self, X, Y):
-        """Function to use with :func:`sklearn.metrics.pairwise.pairwise_kernels`
+        """Function to use with :func:`sklearn.metrics.pairwise.pairwise_kernels`.
 
         Parameters
         ----------
-        X : array, shape = (n_features,)
+        X : ndarray, shape = (n_features,)
 
-        Y : array, shape = (n_features,)
+        Y : ndarray, shape = (n_features,)
 
         Returns
         -------
         similarity : float
-            Similarities are normalized to be within [0, 1]
+            Similarities are normalized to be within [0, 1].
         """
         check_is_fitted(self, "X_fit_")
         if X.shape[0] != Y.shape[0]:

sksurv/linear_model/aft.py

@@ -19,15 +19,15 @@ from ..util import check_array_survival
 
 
 class IPCRidge(Ridge, SurvivalAnalysisMixin):
-    """Accelerated failure time model with inverse probability of censoring weights.
+    r"""Accelerated failure time model with inverse probability of censoring weights.
 
     This model assumes a regression model of the form
 
     .. math::
 
-        \\log y = \\beta_0 + \\mathbf{X} \\beta + \\epsilon
+        \log y = \beta_0 + \mathbf{X} \beta + \epsilon
 
-    L2-shrinkage is applied to the coefficients :math:`\\beta` and
+    L2-shrinkage is applied to the coefficients :math:`\beta` and
     each sample is weighted by the inverse probability of censoring
     to account for right censoring (under the assumption that
     censoring is independent of the features, i.e., random censoring).
@@ -57,7 +57,7 @@ class IPCRidge(Ridge, SurvivalAnalysisMixin):
         by scipy.sparse.linalg. For 'sag' solver, the default value is 1000.
         For 'lbfgs' solver, the default value is 15000.
 
-    tol : float, default: 1e-4
+    tol : float, default: 1e-3
         Precision of the solution. Note that `tol` has no effect for solvers 'svd' and
         'cholesky'.
 
@@ -111,18 +111,18 @@ class IPCRidge(Ridge, SurvivalAnalysisMixin):
     coef_ : ndarray, shape = (n_features,)
         Weight vector.
 
-    intercept_ : float or ndarray of shape (n_targets,)
+    intercept_ : float or ndarray, shape = (n_targets,)
         Independent term in decision function. Set to 0.0 if
         ``fit_intercept = False``.
 
-    n_iter_ : None or ndarray of shape (n_targets,)
+    n_iter_ : None or ndarray, shape = (n_targets,)
         Actual number of iterations for each target. Available only for
         sag and lsqr solvers. Other solvers will return None.
 
     n_features_in_ : int
         Number of features seen during ``fit``.
 
-    feature_names_in_ : ndarray of shape (`n_features_in_`,)
+    feature_names_in_ : ndarray, shape = (`n_features_in_`,)
         Names of features seen during ``fit``. Defined only when `X`
         has feature names that are all strings.
 
@@ -171,9 +171,9 @@ class IPCRidge(Ridge, SurvivalAnalysisMixin):
             Data matrix.
 
         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.
+            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.
 
         Returns
         -------
@@ -196,10 +196,13 @@ class IPCRidge(Ridge, SurvivalAnalysisMixin):
 
         Returns
         -------
-        C : array, shape = (n_samples,)
+        y_pred : array, shape = (n_samples,)
             Returns predicted values on original scale (NOT log scale).
         """
         return np.exp(super().predict(X))
 
     def score(self, X, y, sample_weight=None):
         return SurvivalAnalysisMixin.score(self, X, y)
+
+
+IPCRidge.score.__doc__ = SurvivalAnalysisMixin.score.__doc__

sksurv/linear_model/coxnet.py

@@ -35,7 +35,7 @@ __all__ = ["CoxnetSurvivalAnalysis"]
 
 
 class CoxnetSurvivalAnalysis(BaseEstimator, SurvivalAnalysisMixin):
-    """Cox's proportional hazard's model with elastic net penalty.
+    r"""Cox's proportional hazard's model with elastic net penalty.
 
     See the :ref:`User Guide </user_guide/coxnet.ipynb>` and [1]_ for further description.
 
@@ -46,19 +46,29 @@ class CoxnetSurvivalAnalysis(BaseEstimator, SurvivalAnalysisMixin):
 
     alphas : array-like or None, optional
         List of alphas where to compute the models.
-        If ``None`` alphas are set automatically.
+        If ``None``, alphas are set automatically.
+
+        In this case, the ``alphas`` sequence is determined by :math:`\alpha_\max`
+        and ``alpha_min_ratio``. The latter determines the smallest alpha value
+        :math:`\alpha_\min` in the generated alphas sequence such that
+        ``alpha_min_ratio`` equals the ratio :math:`\frac{\alpha_\min}{\alpha_\max}`.
+        The generated ``alphas`` sequence contains ``n_alphas`` values linear
+        on the log scale from :math:`\alpha_\max` down to :math:`\alpha_\min`.
+        :math:`\alpha_\max` is not user-specified but is computed from the
+        input data.
 
     alpha_min_ratio : float or { "auto" }, optional, default: "auto"
-        Determines minimum alpha of the regularization path
+        Determines the minimum alpha of the regularization path
         if ``alphas`` is ``None``. The smallest value for alpha
-        is computed as the fraction of the data derived maximum
+        is computed as the fraction of the maximum
         alpha (i.e. the smallest value for which all
-        coefficients are zero).
+        coefficients are zero), which is derived from the input data.
 
         If set to "auto", the value will depend on the
-        sample size relative to the number of features.
-        If ``n_samples > n_features``, the default value is 0.0001
-        If ``n_samples <= n_features``, 0.01 is the default value.
+        sample size relative to the number of features:
+
+        - If ``n_samples > n_features``, the default value is 0.0001.
+        - If ``n_samples <= n_features``, the default value is 0.01.
 
     l1_ratio : float, optional, default: 0.5
         The ElasticNet mixing parameter, with ``0 < l1_ratio <= 1``.
@@ -76,7 +86,7 @@ class CoxnetSurvivalAnalysis(BaseEstimator, SurvivalAnalysisMixin):
         Note: the penalty factors are internally rescaled to sum to
         `n_features`, and the alphas sequence will reflect this change.
 
-    normalize : boolean, optional, default: False
+    normalize : bool, optional, default: False
         If True, the features X will be normalized before optimization by
         subtracting the mean and dividing by the l2-norm.
         If you wish to standardize, please use
@@ -91,7 +101,7 @@ class CoxnetSurvivalAnalysis(BaseEstimator, SurvivalAnalysisMixin):
         until all updates are smaller than ``tol``.
 
     max_iter : int, optional, default: 100000
-        The maximum number of iterations.
+        The maximum number of iterations taken for the solver to converge.
 
     verbose : bool, optional, default: False
         Whether to print additional information during optimization.
@@ -122,15 +132,21 @@ class CoxnetSurvivalAnalysis(BaseEstimator, SurvivalAnalysisMixin):
 
     deviance_ratio_ : ndarray, shape=(n_alphas,)
         The fraction of (null) deviance explained.
+        The deviance is defined as :math:`2 \cdot (\text{loglike_sat} - \text{loglike})`,
+        where `loglike_sat` is the log-likelihood for the saturated model
+        (a model with a free parameter per observation). Null deviance is defined as
+        :math:`2 \cdot (\text{loglike_sat} - \text{loglike(Null)})`;
+        The NULL model is the model with all zero coefficients.
+        Hence, ``deviance_ratio_`` is :math:`1 - \frac{\text{deviance}}{\text{null_deviance}}`.
 
     n_features_in_ : int
         Number of features seen during ``fit``.
 
-    feature_names_in_ : ndarray of shape (`n_features_in_`,)
+    feature_names_in_ : ndarray, shape = (`n_features_in_`,)
         Names of features seen during ``fit``. Defined only when `X`
         has feature names that are all strings.
 
-    unique_times_ : array of shape = (n_unique_times,)
+    unique_times_ : ndarray, shape = (n_unique_times,)
         Unique time points.
 
     References
@@ -255,9 +271,9 @@ class CoxnetSurvivalAnalysis(BaseEstimator, SurvivalAnalysisMixin):
             Data matrix
 
         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.
+            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.
 
         Returns
         -------
@@ -349,7 +365,12 @@ class CoxnetSurvivalAnalysis(BaseEstimator, SurvivalAnalysisMixin):
         return coef, offset
 
     def predict(self, X, alpha=None):
-        """The linear predictor of the model.
+        """Predict risk scores.
+
+        The risk score is the linear predictor of the model,
+        computed as the dot product of the input features `X` and the
+        estimated coefficients `coef_`. A higher score indicates a
+        higher risk of experiencing the event.
 
         Parameters
         ----------
@@ -363,8 +384,8 @@ class CoxnetSurvivalAnalysis(BaseEstimator, SurvivalAnalysisMixin):
 
         Returns
         -------
-        T : array, shape = (n_samples,)
-            The predicted decision function
+        risk_score : array, shape = (n_samples,)
+            Predicted risk scores.
         """
         X = validate_data(self, X, reset=False)
         coef, offset = self._get_coef(alpha)
@@ -388,16 +409,16 @@ class CoxnetSurvivalAnalysis(BaseEstimator, SurvivalAnalysisMixin):
         return baseline_model
 
     def predict_cumulative_hazard_function(self, X, alpha=None, return_array=False):
-        """Predict cumulative hazard function.
+        r"""Predict cumulative hazard function.
 
         Only available if :meth:`fit` has been called with `fit_baseline_model = True`.
 
         The cumulative hazard function for an individual
-        with feature vector :math:`x_\\alpha` is defined as
+        with feature vector :math:`x_\alpha` is defined as
 
         .. math::
 
-            H(t \\mid x_\\alpha) = \\exp(x_\\alpha^\\top \\beta) H_0(t) ,
+            H(t \mid x_\alpha) = \exp(x_\alpha^\top \beta) H_0(t) ,
 
         where :math:`H_0(t)` is the baseline hazard function,
         estimated by Breslow's estimator.
@@ -411,68 +432,81 @@ class CoxnetSurvivalAnalysis(BaseEstimator, SurvivalAnalysisMixin):
             Constant that multiplies the penalty terms. The same alpha as used during training
             must be specified. If set to ``None``, the last alpha in the solution path is used.
 
-        return_array : boolean, default: False
-            If set, return an array with the cumulative hazard rate
-            for each `self.unique_times_`, otherwise an array of
-            :class:`sksurv.functions.StepFunction`.
+        return_array : bool, default: False
+            Whether to return a single array of cumulative hazard values
+            or a list of step functions.
+
+            If `False`, a list of :class:`sksurv.functions.StepFunction`
+            objects is returned.
+
+            If `True`, a 2d-array of shape `(n_samples, n_unique_times)` is
+            returned, where `n_unique_times` is the number of unique
+            event times in the training data. Each row represents the cumulative
+            hazard function of an individual evaluated at `unique_times_`.
 
         Returns
         -------
         cum_hazard : ndarray
-            If `return_array` is set, an array with the cumulative hazard rate
-            for each `self.unique_times_`, otherwise an array of length `n_samples`
-            of :class:`sksurv.functions.StepFunction` instances will be returned.
+            If `return_array` is `False`, an array of `n_samples`
+            :class:`sksurv.functions.StepFunction` instances is returned.
+
+            If `return_array` is `True`, a numeric array of shape
+            `(n_samples, n_unique_times_)` is returned.
 
         Examples
         --------
-        >>> import matplotlib.pyplot as plt
-        >>> from sksurv.datasets import load_breast_cancer
-        >>> from sksurv.preprocessing import OneHotEncoder
-        >>> from sksurv.linear_model import CoxnetSurvivalAnalysis
+        .. plot::
 
-        Load and prepare the data.
+            >>> import matplotlib.pyplot as plt
+            >>> from sksurv.datasets import load_breast_cancer
+            >>> from sksurv.preprocessing import OneHotEncoder
+            >>> from sksurv.linear_model import CoxnetSurvivalAnalysis
 
-        >>> X, y = load_breast_cancer()
-        >>> X = OneHotEncoder().fit_transform(X)
+            Load and prepare the data.
 
-        Fit the model.
+            >>> X, y = load_breast_cancer()
+            >>> X = OneHotEncoder().fit_transform(X)
 
-        >>> estimator = CoxnetSurvivalAnalysis(l1_ratio=0.99, fit_baseline_model=True)
-        >>> estimator.fit(X, y)
+            Fit the model.
 
-        Estimate the cumulative hazard function for one sample and the five highest alpha.
+            >>> estimator = CoxnetSurvivalAnalysis(
+            ...     l1_ratio=0.99, fit_baseline_model=True
+            ... ).fit(X, y)
 
-        >>> chf_funcs = {}
-        >>> for alpha in estimator.alphas_[:5]:
-        ...     chf_funcs[alpha] = estimator.predict_cumulative_hazard_function(
-        ...         X.iloc[:1], alpha=alpha)
-        ...
+            Estimate the cumulative hazard function for one sample and the five highest alpha.
 
-        Plot the estimated cumulative hazard functions.
+            >>> chf_funcs = {}
+            >>> for alpha in estimator.alphas_[:5]:
+            ...     chf_funcs[alpha] = estimator.predict_cumulative_hazard_function(
+            ...         X.iloc[:1], alpha=alpha)
+            ...
 
-        >>> for alpha, chf_alpha in chf_funcs.items():
-        ...     for fn in chf_alpha:
-        ...         plt.step(fn.x, fn(fn.x), where="post",
-        ...                  label=f"alpha = {alpha:.3f}")
-        ...
-        >>> plt.ylim(0, 1)
-        >>> plt.legend()
-        >>> plt.show()
+            Plot the estimated cumulative hazard functions.
+
+            >>> for alpha, chf_alpha in chf_funcs.items():
+            ...     for fn in chf_alpha:
+            ...         plt.step(fn.x, fn(fn.x), where="post",
+            ...                  label=f"alpha = {alpha:.3f}")
+            ...
+            [...]
+            >>> plt.legend()
+            <matplotlib.legend.Legend object at 0x...>
+            >>> plt.show()  # doctest: +SKIP
         """
         baseline_model = self._get_baseline_model(alpha)
         return self._predict_cumulative_hazard_function(baseline_model, self.predict(X, alpha=alpha), return_array)
 
     def predict_survival_function(self, X, alpha=None, return_array=False):
-        """Predict survival function.
+        r"""Predict survival function.
 
         Only available if :meth:`fit` has been called with `fit_baseline_model = True`.
 
         The survival function for an individual
-        with feature vector :math:`x_\\alpha` is defined as
+        with feature vector :math:`x_\alpha` is defined as
 
         .. math::
 
-            S(t \\mid x_\\alpha) = S_0(t)^{\\exp(x_\\alpha^\\top \\beta)} ,
+            S(t \mid x_\alpha) = S_0(t)^{\exp(x_\alpha^\top \beta)} ,
 
         where :math:`S_0(t)` is the baseline survival function,
         estimated by Breslow's estimator.
@@ -486,54 +520,69 @@ class CoxnetSurvivalAnalysis(BaseEstimator, SurvivalAnalysisMixin):
             Constant that multiplies the penalty terms. The same alpha as used during training
             must be specified. If set to ``None``, the last alpha in the solution path is used.
 
-        return_array : boolean, default: False
-            If set, return an array with the probability
-            of survival for each `self.unique_times_`,
-            otherwise an array of :class:`sksurv.functions.StepFunction`.
+        return_array : bool, default: False
+            Whether to return a single array of survival probabilities
+            or a list of step functions.
+
+            If `False`, a list of :class:`sksurv.functions.StepFunction`
+            objects is returned.
+
+            If `True`, a 2d-array of shape `(n_samples, n_unique_times)` is
+            returned, where `n_unique_times` is the number of unique
+            event times in the training data. Each row represents the survival
+            function of an individual evaluated at `unique_times_`.
 
         Returns
         -------
         survival : ndarray
-            If `return_array` is set, an array with the probability of
-            survival for each `self.unique_times_`, otherwise an array of
-            length `n_samples` of :class:`sksurv.functions.StepFunction`
-            instances will be returned.
+            If `return_array` is `False`, an array of `n_samples`
+            :class:`sksurv.functions.StepFunction` instances is returned.
+
+            If `return_array` is `True`, a numeric array of shape
+            `(n_samples, n_unique_times_)` is returned.
+
 
         Examples
         --------
-        >>> import matplotlib.pyplot as plt
-        >>> from sksurv.datasets import load_breast_cancer
-        >>> from sksurv.preprocessing import OneHotEncoder
-        >>> from sksurv.linear_model import CoxnetSurvivalAnalysis
+        .. plot::
+
+            >>> import matplotlib.pyplot as plt
+            >>> from sksurv.datasets import load_breast_cancer
+            >>> from sksurv.preprocessing import OneHotEncoder
+            >>> from sksurv.linear_model import CoxnetSurvivalAnalysis
 
-        Load and prepare the data.
+            Load and prepare the data.
 
-        >>> X, y = load_breast_cancer()
-        >>> X = OneHotEncoder().fit_transform(X)
+            >>> X, y = load_breast_cancer()
+            >>> X = OneHotEncoder().fit_transform(X)
 
-        Fit the model.
+            Fit the model.
 
-        >>> estimator = CoxnetSurvivalAnalysis(l1_ratio=0.99, fit_baseline_model=True)
-        >>> estimator.fit(X, y)
+            >>> estimator = CoxnetSurvivalAnalysis(
+            ...     l1_ratio=0.99, fit_baseline_model=True
+            ... ).fit(X, y)
 
-        Estimate the survival function for one sample and the five highest alpha.
+            Estimate the survival function for one sample and the five highest alpha.
 
-        >>> surv_funcs = {}
-        >>> for alpha in estimator.alphas_[:5]:
-        ...     surv_funcs[alpha] = estimator.predict_survival_function(
-        ...         X.iloc[:1], alpha=alpha)
-        ...
+            >>> surv_funcs = {}
+            >>> for alpha in estimator.alphas_[:5]:
+            ...     surv_funcs[alpha] = estimator.predict_survival_function(
+            ...         X.iloc[:1], alpha=alpha)
+            ...
 
-        Plot the estimated survival functions.
+            Plot the estimated survival functions.
 
-        >>> for alpha, surv_alpha in surv_funcs.items():
-        ...     for fn in surv_alpha:
-        ...         plt.step(fn.x, fn(fn.x), where="post",
-        ...                  label=f"alpha = {alpha:.3f}")
-        ...
-        >>> plt.ylim(0, 1)
-        >>> plt.legend()
-        >>> plt.show()
+            >>> for alpha, surv_alpha in surv_funcs.items():
+            ...     for fn in surv_alpha:
+            ...         plt.step(fn.x, fn(fn.x), where="post",
+            ...                  label=f"alpha = {alpha:.3f}")
+            ...
+            [...]
+            >>> plt.ylim(0, 1)
+            (0.0, 1.0)
+            >>> plt.legend()
+            <matplotlib.legend.Legend object at 0x...>
+            >>> plt.show()  # doctest: +SKIP
         """
         baseline_model = self._get_baseline_model(alpha)
         return self._predict_survival_function(baseline_model, self.predict(X, alpha=alpha), return_array)