Engine docs for censored (#753)

hfrick · topepo · web-flow · commit eb0d94ac78f1 · 2022-06-12T10:53:53.000-04:00
* add details on time predictions for censored

* udpated `.md` files for censored-related models/enginges

* use templates

* engine doc refresh

* fix broken h2o links in docs

Co-authored-by: Max Kuhn &lt;mxkuhn@gmail.com&gt;
diff --git a/man/details_linear_reg_h2o.Rd b/man/details_linear_reg_h2o.Rd
diff --git a/man/details_logistic_reg_h2o.Rd b/man/details_logistic_reg_h2o.Rd
diff --git a/man/details_multinom_reg_h2o.Rd b/man/details_multinom_reg_h2o.Rd
diff --git a/man/details_poisson_reg_h2o.Rd b/man/details_poisson_reg_h2o.Rd
diff --git a/man/rmd/bag_tree_rpart.Rmd b/man/rmd/bag_tree_rpart.Rmd
@@ -77,6 +77,11 @@ bag_tree(tree_depth = integer(1), min_n = integer(1), cost_complexity = double(1
 ```{r child = "template-uses-case-weights.Rmd"}
 ```
 
+## Other details
+
+```{r child = "template-survival-median.Rmd"}
+```
+
 ## References
 
  - Breiman L. 1996. "Bagging predictors". Machine Learning. 24 (2): 123-140
diff --git a/man/rmd/bag_tree_rpart.md b/man/rmd/bag_tree_rpart.md
@@ -124,6 +124,12 @@ This model can utilize case weights during model fitting. To use them, see the d
 
 The `fit()` and `fit_xy()` arguments have arguments called `case_weights` that expect vectors of case weights. 
 
+## Other details
+
+
+
+Predictions of type `"time"` are predictions of the median survival time.
+
 ## References
 
  - Breiman L. 1996. "Bagging predictors". Machine Learning. 24 (2): 123-140
diff --git a/man/rmd/boost_tree_mboost.Rmd b/man/rmd/boost_tree_mboost.Rmd
@@ -45,6 +45,11 @@ boost_tree() %>%
 ```{r child = "template-tree-split-factors.Rmd"}
 ```
 
+## Other details
+
+```{r child = "template-survival-mean.Rmd"}
+```
+
 ## References
 
  - Buehlmann P, Hothorn T. 2007. Boosting algorithms: regularization, prediction and model fitting. _Statistical Science_, 22(4), 477–505.
diff --git a/man/rmd/boost_tree_mboost.md b/man/rmd/boost_tree_mboost.md
@@ -52,6 +52,12 @@ boost_tree() %>%
 
 This engine does not require any special encoding of the predictors. Categorical predictors can be partitioned into groups of factor levels (e.g. `{a, c}` vs `{b, d}`) when splitting at a node. Dummy variables are not required for this model. 
 
+## Other details
+
+
+
+Predictions of type `"time"` are predictions of the mean survival time.
+
 ## References
 
  - Buehlmann P, Hothorn T. 2007. Boosting algorithms: regularization, prediction and model fitting. _Statistical Science_, 22(4), 477–505.
diff --git a/man/rmd/decision_tree_partykit.Rmd b/man/rmd/decision_tree_partykit.Rmd
@@ -78,6 +78,11 @@ decision_tree(tree_depth = integer(1), min_n = integer(1)) %>%
 ```{r child = "template-tree-split-factors.Rmd"}
 ```
 
+## Other details
+
+```{r child = "template-survival-median.Rmd"}
+```
+
 ## References
 
  - [partykit: A Modular Toolkit for Recursive Partytioning in R](https://jmlr.org/papers/v16/hothorn15a.html)
diff --git a/man/rmd/decision_tree_partykit.md b/man/rmd/decision_tree_partykit.md
@@ -115,6 +115,12 @@ decision_tree(tree_depth = integer(1), min_n = integer(1)) %>%
 
 This engine does not require any special encoding of the predictors. Categorical predictors can be partitioned into groups of factor levels (e.g. `{a, c}` vs `{b, d}`) when splitting at a node. Dummy variables are not required for this model. 
 
+## Other details
+
+
+
+Predictions of type `"time"` are predictions of the median survival time.
+
 ## References
 
  - [partykit: A Modular Toolkit for Recursive Partytioning in R](https://jmlr.org/papers/v16/hothorn15a.html)
diff --git a/man/rmd/decision_tree_rpart.Rmd b/man/rmd/decision_tree_rpart.Rmd
@@ -70,6 +70,11 @@ decision_tree(
 ```{r child = "template-uses-case-weights.Rmd"}
 ```
 
+## Other details
+
+```{r child = "template-survival-mean.Rmd"}
+```
+
 ## Examples 
 
 The "Fitting and Predicting with parsnip" article contains [examples](https://parsnip.tidymodels.org/articles/articles/Examples.html#decision-tree-rpart) for `decision_tree()` with the `"rpart"` engine.
diff --git a/man/rmd/decision_tree_rpart.md b/man/rmd/decision_tree_rpart.md
@@ -115,6 +115,12 @@ This model can utilize case weights during model fitting. To use them, see the d
 
 The `fit()` and `fit_xy()` arguments have arguments called `case_weights` that expect vectors of case weights. 
 
+## Other details
+
+
+
+Predictions of type `"time"` are predictions of the mean survival time.
+
 ## Examples 
 
 The "Fitting and Predicting with parsnip" article contains [examples](https://parsnip.tidymodels.org/articles/articles/Examples.html#decision-tree-rpart) for `decision_tree()` with the `"rpart"` engine.
diff --git a/man/rmd/proportional_hazards_glmnet.Rmd b/man/rmd/proportional_hazards_glmnet.Rmd
@@ -86,7 +86,11 @@ predict(mod, pred_data, type = "survival", time = 500) %>%
 
 Note that columns used in the `strata()` function _will_ also be estimated in the regular portion of the model (i.e., within the linear predictor).
 
-# Linear predictor values
+```{r child = "template-survival-mean.Rmd"}
+```
+
+## Linear predictor values
+
 ```{r child = "template-censored-linear-predictor.Rmd"}
 ```
 
diff --git a/man/rmd/proportional_hazards_glmnet.md b/man/rmd/proportional_hazards_glmnet.md
@@ -97,7 +97,12 @@ predict(mod, pred_data, type = "survival", time = 500) %>%
 
 Note that columns used in the `strata()` function _will_ also be estimated in the regular portion of the model (i.e., within the linear predictor).
 
-# Linear predictor values
+
+
+Predictions of type `"time"` are predictions of the mean survival time.
+
+## Linear predictor values
+
 
 Since risk regression and parametric survival models are modeling different characteristics (e.g. relative hazard versus event time), their linear predictors will be going in opposite directions. 
 
diff --git a/man/rmd/proportional_hazards_survival.Rmd b/man/rmd/proportional_hazards_survival.Rmd
@@ -42,13 +42,14 @@ proportional_hazards() %>%
 
 Note that columns used in the `strata()` function will not be estimated in the regular portion of the model (i.e., within the linear predictor).
 
+```{r child = "template-survival-mean.Rmd"}
+```
 
-# Linear predictor values
+## Linear predictor values
 
 ```{r child = "template-censored-linear-predictor.Rmd"}
 ```
 
-
 ## Case weights
 
 ```{r child = "template-uses-case-weights.Rmd"}
diff --git a/man/rmd/proportional_hazards_survival.md b/man/rmd/proportional_hazards_survival.md
@@ -85,7 +85,10 @@ proportional_hazards() %>%
 Note that columns used in the `strata()` function will not be estimated in the regular portion of the model (i.e., within the linear predictor).
 
 
-# Linear predictor values
+
+Predictions of type `"time"` are predictions of the mean survival time.
+
+## Linear predictor values
 
 
 Since risk regression and parametric survival models are modeling different characteristics (e.g. relative hazard versus event time), their linear predictors will be going in opposite directions. 
@@ -96,7 +99,6 @@ tidymodels does not treat different models differently when computing performanc
 
 This behavior can be changed by using the `increasing` argument when calling `predict()` on a \pkg{parsnip} model object. 
 
-
 ## Case weights
 
 
diff --git a/man/rmd/rand_forest_partykit.Rmd b/man/rmd/rand_forest_partykit.Rmd
@@ -73,6 +73,11 @@ rand_forest() %>%
 ```{r child = "template-tree-split-factors.Rmd"}
 ```
 
+## Other details
+
+```{r child = "template-survival-median.Rmd"}
+```
+
 ## References
 
  - [partykit: A Modular Toolkit for Recursive Partytioning in R](https://jmlr.org/papers/v16/hothorn15a.html)
diff --git a/man/rmd/rand_forest_partykit.md b/man/rmd/rand_forest_partykit.md
@@ -97,6 +97,12 @@ rand_forest() %>%
 
 This engine does not require any special encoding of the predictors. Categorical predictors can be partitioned into groups of factor levels (e.g. `{a, c}` vs `{b, d}`) when splitting at a node. Dummy variables are not required for this model. 
 
+## Other details
+
+
+
+Predictions of type `"time"` are predictions of the median survival time.
+
 ## References
 
  - [partykit: A Modular Toolkit for Recursive Partytioning in R](https://jmlr.org/papers/v16/hothorn15a.html)
diff --git a/man/rmd/survival_reg_flexsurv.Rmd b/man/rmd/survival_reg_flexsurv.Rmd
@@ -42,6 +42,9 @@ The main interface for this model uses the formula method since the model specif
 
 For this engine, stratification cannot be specified via [`strata()`], please see [flexsurv::flexsurvreg()] for alternative specifications.
 
+```{r child = "template-survival-mean.Rmd"}
+```
+
 ## References
 
 - Jackson, C. 2016. `flexsurv`: A Platform for Parametric Survival  Modeling in R. _Journal of Statistical Software_, 70(8), 1 - 33.
diff --git a/man/rmd/survival_reg_flexsurv.md b/man/rmd/survival_reg_flexsurv.md
@@ -44,6 +44,10 @@ The main interface for this model uses the formula method since the model specif
 
 For this engine, stratification cannot be specified via [`strata()`], please see [flexsurv::flexsurvreg()] for alternative specifications.
 
+
+
+Predictions of type `"time"` are predictions of the mean survival time.
+
 ## References
 
 - Jackson, C. 2016. `flexsurv`: A Platform for Parametric Survival  Modeling in R. _Journal of Statistical Software_, 70(8), 1 - 33.
diff --git a/man/rmd/survival_reg_survival.Rmd b/man/rmd/survival_reg_survival.Rmd
@@ -54,6 +54,9 @@ survival_reg() %>%
   extract_fit_engine()
 ```
 
+```{r child = "template-survival-mean.Rmd"}
+```
+
 ## Case weights
 
 ```{r child = "template-uses-case-weights.Rmd"}
diff --git a/man/rmd/survival_reg_survival.md b/man/rmd/survival_reg_survival.md
diff --git a/man/rmd/template-h2o-glm-penalty.Rmd b/man/rmd/template-h2o-glm-penalty.Rmd
diff --git a/man/rmd/template-survival-mean.Rmd b/man/rmd/template-survival-mean.Rmd
diff --git a/man/rmd/template-survival-median.Rmd b/man/rmd/template-survival-median.Rmd
