Merge pull request #236 from StochasticTree/r-doc-abbreviation

Add abbreviated summary of several R functions for the doc site

Author: andrewherren

R/posterior_transformation.R

@@ -1,3 +1,5 @@
+#' Compute a contrast between two outcome prediction specifications for a BCF model
+#'
 #' Compute a contrast using a BCF model by making two sets of outcome predictions and taking their difference.
 #' For simple BCF models with binary treatment, this will yield the same prediction as requesting `terms = "cate"`
 #' in the `predict.bcfmodel` function. For more general models, such as models with continuous / multivariate treatments or
@@ -245,6 +247,8 @@ compute_contrast_bcf_model <- function(
   }
 }
 
+#' Compute a contrast between two outcome prediction specifications for a BART model
+#'
 #' Compute a contrast using a BART model by making two sets of outcome predictions and taking their difference.
 #' This function provides the flexibility to compute any contrast of interest by specifying covariates, leaf basis, and random effects
 #' bases / IDs for both sides of a two term contrast. For simplicity, we refer to the subtrahend of the contrast as the "control" or
@@ -830,7 +834,8 @@ posterior_predictive_heuristic_multiplier <- function(
 
 #' Compute posterior credible intervals for BCF model terms
 #'
-#' This function computes posterior credible intervals for specified terms from a fitted BCF model. It supports intervals for prognostic forests, CATE forests, variance forests, random effects, and overall mean outcome predictions.
+#' Compute posterior credible intervals for specified terms from a fitted BCF model. Supports intervals for prognostic forests, CATE forests, variance forests, random effects, and overall mean outcome predictions.
+#'
 #' @param model_object A fitted BCF model object of class `bcfmodel`.
 #' @param terms A character string specifying the model term(s) for which to compute intervals. Options for BCF models are `"prognostic_function"`, `"mu"`, `"cate"`, `"tau"`, `"variance_forest"`, `"rfx"`, or `"y_hat"`. Note that `"mu"` is only different from `"prognostic_function"` if random effects are included with a model spec of `"intercept_only"` or `"intercept_plus_treatment"` and `"tau"` is only different from `"cate"` if random effects are included with a model spec of `"intercept_plus_treatment"`.
 #' @param level A numeric value between 0 and 1 specifying the credible interval level (default is 0.95 for a 95% credible interval).
@@ -1055,7 +1060,10 @@ compute_bcf_posterior_interval <- function(
   }
 }
 
-#' Compute posterior credible intervals for specified terms from a fitted BART model. It supports intervals for mean functions, variance functions, random effects, and overall predictions.
+#' Compute posterior credible intervals for specified terms from a fitted BART model.
+#'
+#' Compute posterior credible intervals for specified terms from a fitted BART model. Supports intervals for mean functions, variance functions, random effects, and overall outcome predictions.
+#'
 #' @param model_object A fitted BART or BCF model object of class `bartmodel`.
 #' @param terms A character string specifying the model term(s) for which to compute intervals. Options for BART models are `"mean_forest"`, `"variance_forest"`, `"rfx"`, or `"y_hat"`.
 #' @param level A numeric value between 0 and 1 specifying the credible interval level (default is 0.95 for a 95% credible interval).

R/random_effects.R

@@ -1,8 +1,10 @@
-#' Class that wraps the "persistent" aspects of a C++ random effects model
-#' (draws of the parameters and a map from the original label indices to the
+#' Class that wraps the "persistent" aspects of a C++ random effects model.
+#'
+#' Class that wraps the "persistent" aspects of a C++ random effects model, including
+#' draws of the parameters and a map from the original label indices to the
 #' 0-indexed label numbers used to place group samples in memory (i.e. the
 #' first label is stored in column 0 of the sample matrix, the second label
-#' is store in column 1 of the sample matrix, etc...))
+#' is store in column 1 of the sample matrix, etc...)
 #'
 #' @description
 #' Coordinates various C++ random effects classes and persists those

R/utils.R

@@ -20,7 +20,10 @@ preprocessParams <- function(default_params, user_params = NULL) {
   return(default_params)
 }
 
-#' Preprocess covariates. DataFrames will be preprocessed based on their column
+#' Preprocess covariates for use in a `ForestDataset` at train time.
+#'
+#' Preprocess covariates for use in a `ForestDataset` at train time.
+#' DataFrames will be preprocessed based on their column
 #' types. Matrices will be passed through assuming all columns are numeric.
 #'
 #' @param input_data Covariates, provided as either a dataframe or a matrix
@@ -50,7 +53,10 @@ preprocessTrainData <- function(input_data) {
   return(output)
 }
 
-#' Preprocess covariates. DataFrames will be preprocessed based on their column
+#' Preprocess covariates for use in a `ForestDataset` at prediction time.
+#'
+#' Preprocess covariates for use in a `ForestDataset` at prediction time.
+#' DataFrames will be preprocessed based on their column
 #' types. Matrices will be passed through assuming all columns are numeric.
 #'
 #' @param input_data Covariates, provided as either a dataframe or a matrix
@@ -1008,6 +1014,8 @@ expand_dims_1d <- function(input, output_size) {
   return(output)
 }
 
+#' Ensures that input is propagated appropriately to a matrix of dimension `output_rows` x `output_cols`.
+#'
 #' Ensures that input is propagated appropriately to a matrix of dimension `output_rows` x `output_cols`.
 #' Handles the following cases:
 #'  1. `input` is a scalar: output is simply a (`output_rows`, `output_cols`) matrix with `input` repeated for each element