added new doc templates and refined some others

man-roxygen/details_method.R

@@ -1,4 +1,4 @@
-#' @section Implementation differences (time-integration):
+#' @section Implementation differences:
 #'
 #' If comparing the integrated graf score to other packages, e.g.
 #' \CRANpkg{pec}, then `method = 2` should be used. However the results may

man-roxygen/param_tmax.R

@@ -1,7 +1,8 @@
 #' @section Parameter details:
 #' - `t_max` (`numeric(1)`)\cr
-#' Cutoff time (i.e. time horizon) to evaluate the measure up to.
+#' Cutoff time \eqn{\tau^*} (i.e. time horizon) to evaluate the measure up to.
 #' Mutually exclusive with `p_max` or `times`.
 #' This will effectively remove test observations for which the observed time
 #' (event or censoring) is strictly more than `t_max`.
 #' It's recommended to set `t_max` to avoid division by `eps`, see Details.
+#' If `t_max` is not specified, an `Inf` time horizon is assumed.

man-roxygen/properness.R

@@ -0,0 +1,9 @@
+#' @section Properness:
+#'
+#' <%=proper_id%> is strictly proper when the censoring distribution is independent
+#' of the survival distribution and when \eqn{G(t)} is fit on a sufficiently large dataset.
+#' <%=improper_id%> is never proper. Use `proper = FALSE` for <%=improper_id%> and
+#' `proper = TRUE` for <%=proper_id%>.
+#' Results may be very different if many observations are censored at the last
+#' observed time due to division by \eqn{1/eps} in `proper = TRUE`.
+#'

man-roxygen/which_times.R

@@ -0,0 +1,21 @@
+#' @section Time points used for evaluation:
+#' If the `times` argument is not specified (`NULL`), then the unique (and
+#' sorted) time points from the **test set** are used for evaluation of the
+#' time-integrated score.
+#' This was a design decision due to the fact that different predicted survival
+#' distributions \eqn{S(t)} usually have a **discretized time domain** which may
+#' differ, i.e. in the case the survival predictions come from different survival
+#' learners.
+#' Essentially, using the same set of time points for the calculation of the score
+#' minimizes the bias that would come from using different time points.
+#' We note that \eqn{S(t)} is by default constantly interpolated for time points that fall
+#' outside its discretized time domain.
+#'
+#' Naturally, if the `times` argument is specified, then exactly these time
+#' points are used for evaluation.
+#' A warning is given to the user in case some of the specified `times` fall outside
+#' of the time point range of the test set.
+#' The assumption here is that if the test set is large enough, it should have a
+#' time domain/range similar to the one from the train set, and therefore time
+#' points outside that domain might lead to interpolation or extrapolation of \eqn{S(t)}.
+#'