add doc for PipeOpBreslow

NAMESPACE

@@ -69,6 +69,7 @@ export(MeasureSurvUnoAUC)
 export(MeasureSurvUnoTNR)
 export(MeasureSurvUnoTPR)
 export(MeasureSurvXuR2)
+export(PipeOpBreslow)
 export(PipeOpCrankCompositor)
 export(PipeOpDistrCompositor)
 export(PipeOpPredRegrSurv)

R/PipeOpBreslow.R

@@ -1,14 +1,73 @@
 #' @title PipeOpBreslow
 #' @name mlr_pipeops_compose_breslow_distr
+#' @template param_pipelines
 #' @description
-#' A short description...
+#' Composes a survival distribution (`distr`) from the linear predictor
+#' predictions (`lp`) of a given [LearnerSurv] generated during training and
+#' prediction using the [breslow] estimator.
+#' The input `learner` needs to be able to predict `lp` type of predictions (eg
+#' a Cox-type of model).
 #'
+#' @section Dictionary:
+#' This [PipeOp][mlr3pipelines::PipeOp] can be instantiated via the
+#' [Dictionary][mlr3misc::Dictionary] [mlr_pipeops][mlr3pipelines::mlr_pipeops]
+#' or with the associated sugar function [po()][mlr3pipelines::po]:
+#' ```
+#' PipeOpBreslow$new(learner)
+#' mlr_pipeops$get("breslowcompose", learner)
+#' po("breslowcompose", learner, overwrite = TRUE)
+#' ```
+#'
+#' @section Input and Output Channels:
+#' [PipeOpBreslow] is like a [LearnerSurv].
+#' It has one input channel, named `input` that takes a [TaskSurv] during training
+#' and another [TaskSurv] during prediction.
+#' [PipeOpBreslow] has one output channel named `output`, producing `NULL` during
+#' training and a [PredictionSurv] during prediction.
+#'
+#' @section State:
+#' The `$state` slot stores the `times` and `status` survival target variables of
+#' the train [TaskSurv] as well as the `lp` predictions on the train set.
+#'
+#' @section Parameters:
+#' The parameters are:
+#' * `overwrite` :: `logical(1)` \cr
+#'    If `FALSE` (default) then the compositor does nothing and returns the
+#'    input `learner`'s [PredictionSurv].
+#'    If `TRUE` or in the case that the input `learner` doesn't have `distr`
+#'    predictions, then the `distr` is overwritten with the `distr` composed
+#'    from `lp` and the train set information using [breslow].
+#'    This is useful for changing the prediction `distr` from one model form to
+#'    another.
+#' @seealso [pipeline_distrcompositor]
+#' @export
+#' @family survival compositors
+#' @examples
+#' \dontrun{
+#' if (requireNamespace("mlr3pipelines", quietly = TRUE)) {
+#'   library(mlr3)
+#'   library(mlr3pipelines)
+#'   task = tsk("rats")
+#'   part = partition(task, ratio = 0.8)
+#'   train_task = task$clone()$filter(part$train)
+#'   test_task  = task$clone()$filter(part$test)
+#'
+#'   learner = lrn("surv.coxph") # learner with lp predictions
+#'   b = po("breslowcompose", learner = learner, overwrite = TRUE)
+#'
+#'   b$train(list(train_task))
+#'   p = b$predict(list(test_task))[[1L]]
+#' }
+#' }
 PipeOpBreslow = R6Class("PipeOpBreslow",
   inherit = mlr3pipelines::PipeOp,
   public = list(
     #' @description
     #' Creates a new instance of this [R6][R6::R6Class] class.
-    #' @param id description
+    #' @param learner ([LearnerSurv])\cr
+    #' Survival learner which must provide `lp`-type predictions
+    #' @param id (character(1))\cr
+    #' Identifier of the resulting object.
     initialize = function(learner, id = "po_breslow", param_vals = list(overwrite = FALSE)) {
       if ("lp" %nin% learner$predict_types) {
         stopf("Learner %s must provide lp predictions", learner$id)
@@ -37,6 +96,8 @@ PipeOpBreslow = R6Class("PipeOpBreslow",
   ),
 
   active = list(
+    #' @field learner \cr
+    #' The input learner.
     learner = function(rhs) {
       assert_ro_binding(rhs)
       private$.learner
@@ -86,8 +147,11 @@ PipeOpBreslow = R6Class("PipeOpBreslow",
       p = learner$predict(task)
 
       pv = self$param_set$get_values(tags = "predict")
-      if (is.null(pv$overwrite) || !pv$overwrite) {
-        #browser()
+      overwrite = pv$overwrite
+
+      # If learner predicts `distr` and overwrite is FALSE don't use breslow
+      if ("distr" %in% learner$predict_types & !overwrite) {
+        browser()
         pred = list(p)
       } else {
         # missing lp