[ci skip] more infos in front page and new figure to illustrate the c…

…ompeting risks setting (#83)

* more infos in front page

* more on lifelines, boxes

* some rephrasing

* metrics

---------

Co-authored-by: Vincent Maladiere <[email protected]> e1285f3

_sources/auto_examples/plot_01_survival_analysis.rst.txt

@@ -1090,7 +1090,7 @@ doesn't depend on the patient features.
 
 .. rst-class:: sphx-glr-timing
 
-   **Total running time of the script:** (0 minutes 9.745 seconds)
+   **Total running time of the script:** (0 minutes 9.501 seconds)
 
 
 .. _sphx_glr_download_auto_examples_plot_01_survival_analysis.py:

_sources/auto_examples/plot_02_marginal_cumulative_incidence_estimation.rst.txt

@@ -277,17 +277,17 @@ theoretical CIFs:
 
  .. code-block:: none
 
-    Integrated theoretical any event survival curve in 0.672 s
+    Integrated theoretical any event survival curve in 0.676 s
     /opt/hostedtoolcache/Python/3.10.16/x64/lib/python3.10/site-packages/sklearn/utils/deprecation.py:151: FutureWarning: 'force_all_finite' was renamed to 'ensure_all_finite' in 1.6 and will be removed in 1.8.
       warnings.warn(
-    SurvivalBoost fit: 4.221 s
-    SurvivalBoost prediction: 2.969 s
-    Integrated theoretical cumulative incidence curve for event 1 in 3.030 s
-    Aalen-Johansen for event 1 fit in 5.123 s
-    Integrated theoretical cumulative incidence curve for event 2 in 5.220 s
-    Aalen-Johansen for event 2 fit in 5.135 s
-    Integrated theoretical cumulative incidence curve for event 3 in 5.218 s
-    Aalen-Johansen for event 3 fit in 5.185 s
+    SurvivalBoost fit: 4.093 s
+    SurvivalBoost prediction: 2.934 s
+    Integrated theoretical cumulative incidence curve for event 1 in 2.995 s
+    Aalen-Johansen for event 1 fit in 5.076 s
+    Integrated theoretical cumulative incidence curve for event 2 in 5.178 s
+    Aalen-Johansen for event 2 fit in 5.082 s
+    Integrated theoretical cumulative incidence curve for event 3 in 5.163 s
+    Aalen-Johansen for event 3 fit in 5.051 s
 
 
 
@@ -330,17 +330,17 @@ of censoring.
 
  .. code-block:: none
 
-    Integrated theoretical any event survival curve in 0.593 s
+    Integrated theoretical any event survival curve in 0.589 s
     /opt/hostedtoolcache/Python/3.10.16/x64/lib/python3.10/site-packages/sklearn/utils/deprecation.py:151: FutureWarning: 'force_all_finite' was renamed to 'ensure_all_finite' in 1.6 and will be removed in 1.8.
       warnings.warn(
-    SurvivalBoost fit: 4.291 s
-    SurvivalBoost prediction: 3.008 s
-    Integrated theoretical cumulative incidence curve for event 1 in 3.069 s
-    Aalen-Johansen for event 1 fit in 5.322 s
-    Integrated theoretical cumulative incidence curve for event 2 in 5.417 s
-    Aalen-Johansen for event 2 fit in 5.243 s
-    Integrated theoretical cumulative incidence curve for event 3 in 5.325 s
-    Aalen-Johansen for event 3 fit in 5.227 s
+    SurvivalBoost fit: 4.198 s
+    SurvivalBoost prediction: 2.943 s
+    Integrated theoretical cumulative incidence curve for event 1 in 3.003 s
+    Aalen-Johansen for event 1 fit in 5.047 s
+    Integrated theoretical cumulative incidence curve for event 2 in 5.143 s
+    Aalen-Johansen for event 2 fit in 5.012 s
+    Integrated theoretical cumulative incidence curve for event 3 in 5.097 s
+    Aalen-Johansen for event 3 fit in 5.057 s
 
 
 
@@ -364,7 +364,7 @@ the large time horizons:
 
 .. rst-class:: sphx-glr-timing
 
-   **Total running time of the script:** (0 minutes 47.790 seconds)
+   **Total running time of the script:** (0 minutes 46.561 seconds)
 
 
 .. _sphx_glr_download_auto_examples_plot_02_marginal_cumulative_incidence_estimation.py:

_sources/index.rst.txt

@@ -6,46 +6,68 @@
 HΛZΛRDOUS
 =========
 
-Gradient-boosting survival analysis
------------------------------------
+Gradient-boosting Survival Analysis and Competing Risks
+-------------------------------------------------------
 
 .. container:: index-features
 
-   * survival and competing risks
+   * Survival Analysis, Competing Risks
 
    * scikit-learn compatible
 
    * scalable gradient boosting
 
-A scalable **time-to-event and competing risk prediction model**
-implemented in Python.
+**hazardous** is a Python library for **survival analysis** -i.e. time-to-event prediction- 
+and **competing risks** settings. It introduces **SurvivalBoost**, a **scalable**
+gradient-boosting model designed for this task.
 
-.. container:: index-box sd-card
+With a **scikit-learn-compatible API**, the library also offers various metrics
+for model evaluation adapted for the competing risks setting: 
 
-   **Competing risks settings**
+- **Integrated Brier Score** 
+- **C-index**
+- **Accuracy in Time**: the ability to predict the observed event at a given time horizon.
 
-   Predicting which event will happen first, and when, from data where some
-   events have not yet been observed:
+What is the difference between Survival Analysis and the Competing risks setting?
+---------------------------------------------------------------------------------
+In contrast to the Survival Analysis setting, the Competing Risks setting accounts
+for the possibility that multiple event of interest may occur,
+not just a single event.
 
-   .. image:: competing_risk_diagram.svg
+It focuses on predicting which event will occur first and when, based on data where
+some events have not yet been observed.
 
-The model is **a gradient-boosting variant**, that offers prediction for
+.. image:: competing_risk_diagram.svg
+
+What is SurvivalBoost?
+----------------------
+**SurvivalBoost** is **a gradient-boosting variant**, that offers prediction for
 survival and competing risks settings, fully compatible with
 `scikit-learn <https://scikit-learn.org>`_. It can be used with
 scikit-learn tools such as pipelines, column transformers,
 cross-validation, hyper-parameter search tools, etc.
-
-.. This package will also offer neural network based estimators by leveraging
-   `PyTorch <https://pytorch.org>`_ and `skorch
-   <https://skorch.readthedocs.io/>`_.
-
-This library puts a focus on predictive accuracy rather than on inference.
-Quantifying the statistical association or causal effect of covariates with/on
-the cumulated event incidence or instantaneous hazard rate is not in the scope
-of this library at this time.
-
-The theory behind the model is described in `this paper
-<https://arxiv.org/abs/2406.14085>`_.
+Using a novel strictly proper scoring rule, the model is trained to predict the
+cumulative incidence function and the survival function at any horizon.
+SurvivalBoost puts a focus on predictive the accuracy -defined as the ability to predict 
+the observed event- rather than on inference. 
+
+Additional theoretical details about the model can be found in `Survival Models:
+Proper Scoring Rule and Stochastic Optimization with Competing Risks
+<https://arxiv.org/pdf/2410.16765>`_.
+
+.. seealso::
+
+   The library relies on `lifelines <https://lifelines.readthedocs.io/en/latest/>`_ 
+   for the Kaplan-Meier estimator used in SurvivalBoost. We extend our gratitude to
+   the authors of lifelines for their significant contributions to the survival
+   analysis community, including the implementation of models such as
+   the Kaplan-Meier, Cox model, and Aalen-Johansen, as well as metrics
+   like the C-index and Brier Score.
+
+.. note::
+   Quantifying the statistical association or causal effect of covariates on the
+   cumulative event incidence or instantaneous hazard rate is currently beyond
+   the scope of this library.
 
 - License: MIT
 - GitHub repository: https://github.com/soda-inria/hazardous

auto_examples/plot_01_survival_analysis.html

@@ -1231,7 +1231,7 @@ <h2>Survival model evaluation<a class="headerlink" href="#survival-model-evaluat
 <div class="sphx-glr-script-out highlight-none notranslate"><div class="highlight"><pre><span></span>Concordance index for SurvivalBoost: 0.67
 </pre></div>
 </div>
-<p class="sphx-glr-timing"><strong>Total running time of the script:</strong> (0 minutes 9.745 seconds)</p>
+<p class="sphx-glr-timing"><strong>Total running time of the script:</strong> (0 minutes 9.501 seconds)</p>
 <div class="sphx-glr-footer sphx-glr-footer-example docutils container" id="sphx-glr-download-auto-examples-plot-01-survival-analysis-py">
 <div class="sphx-glr-download sphx-glr-download-jupyter docutils container">
 <p><a class="reference download internal" download="" href="../_downloads/a6916f06450964ef8d10eb5f311100d1/plot_01_survival_analysis.ipynb"><code class="xref download docutils literal notranslate"><span class="pre">Download</span> <span class="pre">Jupyter</span> <span class="pre">notebook:</span> <span class="pre">plot_01_survival_analysis.ipynb</span></code></a></p>

auto_examples/plot_02_marginal_cumulative_incidence_estimation.html

@@ -564,17 +564,17 @@ <h2>CIFs estimated on uncensored data<a class="headerlink" href="#cifs-estimated
 <span class="p">)</span>
 </pre></div>
 </div>
-<img src="../_images/sphx_glr_plot_02_marginal_cumulative_incidence_estimation_001.png" srcset="../_images/sphx_glr_plot_02_marginal_cumulative_incidence_estimation_001.png" alt="Cause-specific cumulative incidence functions (0.0% censoring), Event 1, Event 2, Event 3" class = "sphx-glr-single-img"/><div class="sphx-glr-script-out highlight-none notranslate"><div class="highlight"><pre><span></span>Integrated theoretical any event survival curve in 0.672 s
+<img src="../_images/sphx_glr_plot_02_marginal_cumulative_incidence_estimation_001.png" srcset="../_images/sphx_glr_plot_02_marginal_cumulative_incidence_estimation_001.png" alt="Cause-specific cumulative incidence functions (0.0% censoring), Event 1, Event 2, Event 3" class = "sphx-glr-single-img"/><div class="sphx-glr-script-out highlight-none notranslate"><div class="highlight"><pre><span></span>Integrated theoretical any event survival curve in 0.676 s
 /opt/hostedtoolcache/Python/3.10.16/x64/lib/python3.10/site-packages/sklearn/utils/deprecation.py:151: FutureWarning: &#39;force_all_finite&#39; was renamed to &#39;ensure_all_finite&#39; in 1.6 and will be removed in 1.8.
   warnings.warn(
-SurvivalBoost fit: 4.221 s
-SurvivalBoost prediction: 2.969 s
-Integrated theoretical cumulative incidence curve for event 1 in 3.030 s
-Aalen-Johansen for event 1 fit in 5.123 s
-Integrated theoretical cumulative incidence curve for event 2 in 5.220 s
-Aalen-Johansen for event 2 fit in 5.135 s
-Integrated theoretical cumulative incidence curve for event 3 in 5.218 s
-Aalen-Johansen for event 3 fit in 5.185 s
+SurvivalBoost fit: 4.093 s
+SurvivalBoost prediction: 2.934 s
+Integrated theoretical cumulative incidence curve for event 1 in 2.995 s
+Aalen-Johansen for event 1 fit in 5.076 s
+Integrated theoretical cumulative incidence curve for event 2 in 5.178 s
+Aalen-Johansen for event 2 fit in 5.082 s
+Integrated theoretical cumulative incidence curve for event 3 in 5.163 s
+Aalen-Johansen for event 3 fit in 5.051 s
 </pre></div>
 </div>
 </section>
@@ -597,17 +597,17 @@ <h2>CIFs estimated on censored data<a class="headerlink" href="#cifs-estimated-o
 <span class="n">plot_cumulative_incidence_functions</span><span class="p">(</span><a href="../generated/hazardous.SurvivalBoost.html#hazardous.SurvivalBoost" title="hazardous.SurvivalBoost" class="sphx-glr-backref-module-hazardous sphx-glr-backref-type-py-class sphx-glr-backref-instance"><span class="n">survival_boost</span></a><span class="o">=</span><a href="../generated/hazardous.SurvivalBoost.html#hazardous.SurvivalBoost" title="hazardous.SurvivalBoost" class="sphx-glr-backref-module-hazardous sphx-glr-backref-type-py-class sphx-glr-backref-instance"><span class="n">survival_boost</span></a><span class="p">,</span> <span class="n">aj</span><span class="o">=</span><span class="n">aj</span><span class="p">,</span> <span class="n">y</span><span class="o">=</span><span class="n">y_censored</span><span class="p">)</span>
 </pre></div>
 </div>
-<img src="../_images/sphx_glr_plot_02_marginal_cumulative_incidence_estimation_002.png" srcset="../_images/sphx_glr_plot_02_marginal_cumulative_incidence_estimation_002.png" alt="Cause-specific cumulative incidence functions (40.4% censoring), Event 1, Event 2, Event 3" class = "sphx-glr-single-img"/><div class="sphx-glr-script-out highlight-none notranslate"><div class="highlight"><pre><span></span>Integrated theoretical any event survival curve in 0.593 s
+<img src="../_images/sphx_glr_plot_02_marginal_cumulative_incidence_estimation_002.png" srcset="../_images/sphx_glr_plot_02_marginal_cumulative_incidence_estimation_002.png" alt="Cause-specific cumulative incidence functions (40.4% censoring), Event 1, Event 2, Event 3" class = "sphx-glr-single-img"/><div class="sphx-glr-script-out highlight-none notranslate"><div class="highlight"><pre><span></span>Integrated theoretical any event survival curve in 0.589 s
 /opt/hostedtoolcache/Python/3.10.16/x64/lib/python3.10/site-packages/sklearn/utils/deprecation.py:151: FutureWarning: &#39;force_all_finite&#39; was renamed to &#39;ensure_all_finite&#39; in 1.6 and will be removed in 1.8.
   warnings.warn(
-SurvivalBoost fit: 4.291 s
-SurvivalBoost prediction: 3.008 s
-Integrated theoretical cumulative incidence curve for event 1 in 3.069 s
-Aalen-Johansen for event 1 fit in 5.322 s
-Integrated theoretical cumulative incidence curve for event 2 in 5.417 s
-Aalen-Johansen for event 2 fit in 5.243 s
-Integrated theoretical cumulative incidence curve for event 3 in 5.325 s
-Aalen-Johansen for event 3 fit in 5.227 s
+SurvivalBoost fit: 4.198 s
+SurvivalBoost prediction: 2.943 s
+Integrated theoretical cumulative incidence curve for event 1 in 3.003 s
+Aalen-Johansen for event 1 fit in 5.047 s
+Integrated theoretical cumulative incidence curve for event 2 in 5.143 s
+Aalen-Johansen for event 2 fit in 5.012 s
+Integrated theoretical cumulative incidence curve for event 3 in 5.097 s
+Aalen-Johansen for event 3 fit in 5.057 s
 </pre></div>
 </div>
 <p>Note that the Aalen-Johansen estimator is unbiased and empirically recovers
@@ -622,7 +622,7 @@ <h2>CIFs estimated on censored data<a class="headerlink" href="#cifs-estimated-o
 <p>Alternatively, we could try to enable a monotonicity constraint at training
 time, however, in practice this often causes a sever over-estimation bias for
 the large time horizons:</p>
-<p class="sphx-glr-timing"><strong>Total running time of the script:</strong> (0 minutes 47.790 seconds)</p>
+<p class="sphx-glr-timing"><strong>Total running time of the script:</strong> (0 minutes 46.561 seconds)</p>
 <div class="sphx-glr-footer sphx-glr-footer-example docutils container" id="sphx-glr-download-auto-examples-plot-02-marginal-cumulative-incidence-estimation-py">
 <div class="sphx-glr-download sphx-glr-download-jupyter docutils container">
 <p><a class="reference download internal" download="" href="../_downloads/8da6be5df74b4f584c69dbcd5de4f948/plot_02_marginal_cumulative_incidence_estimation.ipynb"><code class="xref download docutils literal notranslate"><span class="pre">Download</span> <span class="pre">Jupyter</span> <span class="pre">notebook:</span> <span class="pre">plot_02_marginal_cumulative_incidence_estimation.ipynb</span></code></a></p>