Updating R docs to include more examples

Author: andrewherren

R/data.R

@@ -228,6 +228,14 @@ RandomEffectsDataset <- R6::R6Class(
 #'
 #' @return `ForestDataset` object
 #' @export
+#' 
+#' @examples
+#' covariate_matrix <- matrix(runif(10*100), ncol = 10)
+#' basis_matrix <- matrix(rnorm(3*100), ncol = 3)
+#' weight_vector <- rnorm(100)
+#' forest_dataset <- createForestDataset(covariate_matrix)
+#' forest_dataset <- createForestDataset(covariate_matrix, basis_matrix)
+#' forest_dataset <- createForestDataset(covariate_matrix, basis_matrix, weight_vector)
 createForestDataset <- function(covariates, basis=NULL, variance_weights=NULL){
     return(invisible((
         ForestDataset$new(covariates, basis, variance_weights)
@@ -240,6 +248,11 @@ createForestDataset <- function(covariates, basis=NULL, variance_weights=NULL){
 #'
 #' @return `Outcome` object
 #' @export
+#' 
+#' @examples
+#' X <- matrix(runif(10*100), ncol = 10)
+#' y <- -5 + 10*(X[,1] > 0.5) + rnorm(100)
+#' outcome <- createOutcome(y)
 createOutcome <- function(outcome){
     return(invisible((
         Outcome$new(outcome)
@@ -254,6 +267,13 @@ createOutcome <- function(outcome){
 #'
 #' @return `RandomEffectsDataset` object
 #' @export
+#' 
+#' @examples
+#' rfx_group_ids <- sample(1:2, size = 100, replace = TRUE)
+#' rfx_basis <- matrix(rnorm(3*100), ncol = 3)
+#' weight_vector <- rnorm(100)
+#' rfx_dataset <- createRandomEffectsDataset(rfx_group_ids, rfx_basis)
+#' rfx_dataset <- createRandomEffectsDataset(rfx_group_ids, rfx_basis, weight_vector)
 createRandomEffectsDataset <- function(group_labels, basis, variance_weights=NULL){
     return(invisible((
         RandomEffectsDataset$new(group_labels, basis, variance_weights)

R/forest.R

@@ -758,6 +758,13 @@ Forest <- R6::R6Class(
 #'
 #' @return `ForestSamples` object
 #' @export
+#' 
+#' @examples
+#' num_trees <- 100
+#' leaf_dimension <- 2
+#' is_leaf_constant <- FALSE
+#' is_exponentiated <- FALSE
+#' forest_samples <- createForestSamples(num_trees, leaf_dimension, is_leaf_constant, is_exponentiated)
 createForestSamples <- function(num_trees, leaf_dimension=1, is_leaf_constant=F, is_exponentiated=F) {
     return(invisible((
         ForestSamples$new(num_trees, leaf_dimension, is_leaf_constant, is_exponentiated)
@@ -773,6 +780,13 @@ createForestSamples <- function(num_trees, leaf_dimension=1, is_leaf_constant=F,
 #'
 #' @return `Forest` object
 #' @export
+#' 
+#' @examples
+#' num_trees <- 100
+#' leaf_dimension <- 2
+#' is_leaf_constant <- FALSE
+#' is_exponentiated <- FALSE
+#' forest <- createForest(num_trees, leaf_dimension, is_leaf_constant, is_exponentiated)
 createForest <- function(num_trees, leaf_dimension=1, is_leaf_constant=F, is_exponentiated=F) {
     return(invisible((
         Forest$new(num_trees, leaf_dimension, is_leaf_constant, is_exponentiated)
@@ -786,6 +800,20 @@ createForest <- function(num_trees, leaf_dimension=1, is_leaf_constant=F, is_exp
 #' @param forest_samples (Optional) Container of forest samples from which to re-initialize active forest. If not provided, active forest will be reset to an ensemble of single-node (i.e. root) trees.
 #' @param forest_num (Optional) Index of forest samples from which to initialize active forest. If not provided, active forest will be reset to an ensemble of single-node (i.e. root) trees.
 #' @export
+#' 
+#' @examples
+#' num_trees <- 100
+#' leaf_dimension <- 1
+#' is_leaf_constant <- TRUE
+#' is_exponentiated <- FALSE
+#' active_forest <- createForest(num_trees, leaf_dimension, is_leaf_constant, is_exponentiated)
+#' forest_samples <- createForestSamples(num_trees, leaf_dimension, is_leaf_constant, is_exponentiated)
+#' forest_samples$add_forest_with_constant_leaves(0.0)
+#' forest_samples$add_numeric_split_tree(0, 0, 0, 0, 0.5, -1.0, 1.0)
+#' forest_samples$add_numeric_split_tree(0, 1, 0, 1, 0.75, 3.4, 0.75)
+#' active_forest$set_root_leaves(0.1)
+#' resetActiveForest(active_forest, forest_samples, 0)
+#' resetActiveForest(active_forest)
 resetActiveForest <- function(active_forest, forest_samples=NULL, forest_num=NULL) {
     if (is.null(forest_samples)) {
         root_reset_active_forest_cpp(active_forest$forest_ptr)
@@ -805,6 +833,42 @@ resetActiveForest <- function(active_forest, forest_samples=NULL, forest_num=NUL
 #' @param residual Residual which will also be updated
 #' @param is_mean_model Whether the model being updated is a conditional mean model
 #' @export
+#' 
+#' @examples
+#' n <- 100
+#' p <- 10
+#' num_trees <- 100
+#' leaf_dimension <- 1
+#' is_leaf_constant <- TRUE
+#' is_exponentiated <- FALSE
+#' alpha <- 0.95
+#' beta <- 2.0
+#' min_samples_leaf <- 2
+#' max_depth <- 10
+#' feature_types <- as.integer(rep(0, p))
+#' leaf_model <- 0
+#' sigma2 <- 1.0
+#' leaf_scale <- as.matrix(1.0)
+#' variable_weights <- rep(1/p, p)
+#' a_forest <- 1
+#' b_forest <- 1
+#' cutpoint_grid_size <- 100
+#' X <- matrix(runif(n*p), ncol = p)
+#' forest_dataset <- createForestDataset(X)
+#' y <- -5 + 10*(X[,1] > 0.5) + rnorm(n)
+#' outcome <- createOutcome(y)
+#' rng <- createCppRNG(1234)
+#' forest_model <- createForestModel(forest_dataset, feature_types, num_trees, n, alpha, beta, min_samples_leaf, max_depth)
+#' active_forest <- createForest(num_trees, leaf_dimension, is_leaf_constant, is_exponentiated)
+#' forest_samples <- createForestSamples(num_trees, leaf_dimension, is_leaf_constant, is_exponentiated)
+#' forest_model$sample_one_iteration(
+#'     forest_dataset, outcome, forest_samples, active_forest, 
+#'     rng, feature_types, leaf_model, leaf_scale, variable_weights, 
+#'     a_forest, b_forest, sigma2, cutpoint_grid_size, keep_forest = TRUE, 
+#'     gfr = FALSE, pre_initialized = TRUE
+#' )
+#' resetActiveForest(active_forest, forest_samples, 0)
+#' resetForestModel(forest_model, active_forest, forest_dataset, outcome, TRUE)
 resetForestModel <- function(forest_model, forest, dataset, residual, is_mean_model) {
     reset_forest_model_cpp(forest_model$tracker_ptr, forest$forest_ptr, dataset$data_ptr, residual$data_ptr, is_mean_model)
 }

R/generics.R

@@ -4,4 +4,15 @@
 #' @param ... Other parameters to be used in random effects extraction
 #' @return List of random effect samples
 #' @export
+#' 
+#' @examples
+#' n <- 100
+#' p <- 10
+#' X <- matrix(runif(n*p), ncol = p)
+#' rfx_group_ids <- sample(1:2, size = n, replace = TRUE)
+#' rfx_basis <- rep(1.0, n)
+#' y <- (-5 + 10*(X[,1] > 0.5)) + (-2*(rfx_group_ids==1)+2*(rfx_group_ids==2)) + rnorm(n)
+#' bart_model <- bart(X_train=X, y_train=y, rfx_group_ids_train=rfx_group_ids,
+#'                    rfx_basis_train = rfx_basis, num_gfr=0, num_mcmc=10)
+#' rfx_samples <- getRandomEffectSamples(bart_model)
 getRandomEffectSamples <- function(object, ...) UseMethod("getRandomEffectSamples")

R/kernel.R

@@ -34,10 +34,18 @@
 #' 
 #' @param forest_inds (Optional) Indices of the forest sample(s) for which to compute leaf indices. If not provided, 
 #' this function will return leaf indices for every sample of a forest. 
-#' This function uses 1-indexing, so the first forest sample corresponds to `forest_num = 1`, and so on.
+#' This function uses 0-indexing, so the first forest sample corresponds to `forest_num = 0`, and so on.
 #' @return List of vectors. Each vector is of size `num_obs * num_trees`, where `num_obs = nrow(covariates)` 
 #' and `num_trees` is the number of trees in the relevant forest of `model_object`. 
 #' @export
+#' 
+#' @examples
+#' X <- matrix(runif(10*100), ncol = 10)
+#' y <- -5 + 10*(X[,1] > 0.5) + rnorm(100)
+#' bart_model <- bart(X, y, num_gfr=0, num_mcmc=10)
+#' computeForestLeafIndices(bart_model, X, "mean")
+#' computeForestLeafIndices(bart_model, X, "mean", 0)
+#' computeForestLeafIndices(bart_model, X, "mean", c(1,3,9))
 computeForestLeafIndices <- function(model_object, covariates, forest_type=NULL, forest_inds=NULL) {
     # Extract relevant forest container
     object_name <- class(model_object)[1]
@@ -84,9 +92,9 @@ computeForestLeafIndices <- function(model_object, covariates, forest_type=NULL,
     if (is.null(forest_inds)) {
         forest_inds <- as.integer(1:num_forests - 1)
     } else {
-        stopifnot(all(forest_inds <= num_forests))
-        stopifnot(all(forest_inds >= 1))
-        forest_inds <- as.integer(forest_inds - 1)
+        stopifnot(all(forest_inds <= num_forests-1))
+        stopifnot(all(forest_inds >= 0))
+        forest_inds <- as.integer(forest_inds)
     }
 
     # Compute leaf indices
@@ -122,9 +130,17 @@ computeForestLeafIndices <- function(model_object, covariates, forest_type=NULL,
 #' 
 #' @param forest_inds (Optional) Indices of the forest sample(s) for which to compute leaf indices. If not provided, 
 #' this function will return leaf indices for every sample of a forest. 
-#' This function uses 1-indexing, so the first forest sample corresponds to `forest_num = 1`, and so on.
+#' This function uses 0-indexing, so the first forest sample corresponds to `forest_num = 0`, and so on.
 #' @return Vector of size `length(forest_inds)` with the leaf scale parameter for each requested forest.
 #' @export
+#' 
+#' @examples
+#' X <- matrix(runif(10*100), ncol = 10)
+#' y <- -5 + 10*(X[,1] > 0.5) + rnorm(100)
+#' bart_model <- bart(X, y, num_gfr=0, num_mcmc=10)
+#' computeForestLeafVariances(bart_model, "mean")
+#' computeForestLeafVariances(bart_model, "mean", 0)
+#' computeForestLeafVariances(bart_model, "mean", c(1,3,5))
 computeForestLeafVariances <- function(model_object, forest_type, forest_inds=NULL) {
     # Extract relevant forest container
     stopifnot(class(model_object) %in% c("bartmodel", "bcfmodel"))
@@ -170,9 +186,9 @@ computeForestLeafVariances <- function(model_object, forest_type, forest_inds=NU
     if (is.null(forest_inds)) {
         forest_inds <- as.integer(1:num_forests)
     } else {
-        stopifnot(all(forest_inds <= num_forests))
-        stopifnot(all(forest_inds >= 1))
-        forest_inds <- as.integer(forest_inds)
+        stopifnot(all(forest_inds <= num_forests-1))
+        stopifnot(all(forest_inds >= 0))
+        forest_inds <- as.integer(forest_inds + 1)
     }
 
     # Gather leaf scale parameters
@@ -205,9 +221,17 @@ computeForestLeafVariances <- function(model_object, forest_type, forest_inds=NU
 #' 
 #' @param forest_inds (Optional) Indices of the forest sample(s) for which to compute max leaf indices. If not provided, 
 #' this function will return max leaf indices for every sample of a forest. 
-#' This function uses 1-indexing, so the first forest sample corresponds to `forest_num = 1`, and so on.
+#' This function uses 0-indexing, so the first forest sample corresponds to `forest_num = 0`, and so on.
 #' @return Vector containing the largest possible leaf index computable by `computeForestLeafIndices` for the forests in a designated forest sample container.
 #' @export
+#' 
+#' @examples
+#' X <- matrix(runif(10*100), ncol = 10)
+#' y <- -5 + 10*(X[,1] > 0.5) + rnorm(100)
+#' bart_model <- bart(X, y, num_gfr=0, num_mcmc=10)
+#' computeForestMaxLeafIndex(bart_model, X, "mean")
+#' computeForestMaxLeafIndex(bart_model, X, "mean", 0)
+#' computeForestMaxLeafIndex(bart_model, X, "mean", c(1,3,9))
 computeForestMaxLeafIndex <- function(model_object, covariates, forest_type=NULL, forest_inds=NULL) {
     # Extract relevant forest container
     object_name <- class(model_object)[1]
@@ -247,9 +271,9 @@ computeForestMaxLeafIndex <- function(model_object, covariates, forest_type=NULL
     if (is.null(forest_inds)) {
         forest_inds <- as.integer(1:num_forests - 1)
     } else {
-        stopifnot(all(forest_inds <= num_forests))
-        stopifnot(all(forest_inds >= 1))
-        forest_inds <- as.integer(forest_inds - 1)
+        stopifnot(all(forest_inds <= num_forests-1))
+        stopifnot(all(forest_inds >= 0))
+        forest_inds <- as.integer(forest_inds)
     }
 
     # Compute leaf indices

R/model.R

@@ -170,6 +170,10 @@ ForestModel <- R6::R6Class(
 #'
 #' @return `CppRng` object
 #' @export
+#' 
+#' @examples
+#' rng <- createCppRNG(1234)
+#' rng <- createCppRNG()
 createCppRNG <- function(random_seed = -1){
     return(invisible((
         CppRNG$new(random_seed)
@@ -189,6 +193,19 @@ createCppRNG <- function(random_seed = -1){
 #'
 #' @return `ForestModel` object
 #' @export
+#' 
+#' @examples
+#' num_trees <- 100
+#' n <- 100
+#' p <- 10
+#' alpha <- 0.95
+#' beta <- 2.0
+#' min_samples_leaf <- 2
+#' max_depth <- 10
+#' feature_types <- as.integer(rep(0, p))
+#' X <- matrix(runif(n*p), ncol = p)
+#' forest_dataset <- createForestDataset(X)
+#' forest_model <- createForestModel(forest_dataset, feature_types, num_trees, n, alpha, beta, min_samples_leaf, max_depth)
 createForestModel <- function(forest_dataset, feature_types, num_trees, n, alpha, beta, min_samples_leaf, max_depth) {
     return(invisible((
         ForestModel$new(forest_dataset, feature_types, num_trees, n, alpha, beta, min_samples_leaf, max_depth)