Help for package nerfplus

Title:

Network-Assisted Random Forest+ (NeRF+)

Version:

1.0.0

Description:

Network-assisted Random Forest+ (NeRF+) is a flexible and interpretable machine learning model for incorporating network data alongside node-level covariate information. Briefly, NeRF+ extends a generalization of random forests (RF) called RF+ to the network-assisted regression setting by incorporating both a network cohesion penalty and network embeddings as additional covariates. Using this approach, NeRF+ inherits both the flexibility and interpretability of RFs while allowing researchers to easily incorporate network information in their model to further improve predictive performance. This package provides tools to fit and interpret NeRF+ models, as detailed in Tang, Levina, and Zhu (2025) <doi:10.48550/arXiv.2509.15611>.

License:

MIT + file LICENSE

Encoding:

UTF-8

Depends:

R (≥ 4.1.0)

Suggests:

DT, fresh, ggplot2, ggraph, htmltools, igraph, kableExtra, knitr, patchwork, plotly, shiny, shinycssloaders, shinydashboard, shinydashboardPlus, shinyjs, shinyWidgets, testthat (≥ 3.0.0), tippy

Config/testthat/edition:

Imports:

abind, caret, dplyr, furrr, glmnet, irlba, Matrix, purrr, ranger, Rcpp, rlang, stringr, tibble, tidyr, tidyselect, yardstick

LinkingTo:

Rcpp, RcppArmadillo

LazyData:

true

URL:

https://tiffanymtang.github.io/nerfplus/

Config/roxygen2/version:

8.0.0

NeedsCompilation:

yes

Packaged:

2026-10-21 20:19:18 UTC; ttang4

Author:

Tiffany Tang

[aut, cre]

Maintainer:

Tiffany Tang <ttang4@nd.edu>

Repository:

CRAN

Date/Publication:

2026-11-03 14:40:08 UTC

Add border class

Description

Add border class

Usage

add_border(obj, border = TRUE)

Arguments

obj

Object to add border to.

border

Logical. Whether or not to add border.

Add spinner when loading

Description

Wrapper around shinycssloaders::withSpinner() with a different default color.

Usage

add_spinner(obj, spinner = TRUE, color = "#18bc9c")

Arguments

obj

Object to add spinner to.

spinner

Logical. Whether or not to add spinner.

color

The color of the spinner in hex format. Ignored if image is used.

Examples

## DON'T RUN
# shiny::htmlOutput({NAME OF UI ELEMENT}) |> add_spinner()

Description

Add a tooltip to an element

Usage

add_tooltip(
  id,
  tooltip,
  placement = "right",
  allowHTML = TRUE,
  use_id_only = FALSE,
  ...
)

Arguments

The id of the element to add the tooltip to.

The tooltip to add.

The placement of the tooltip.

Whether to allow HTML in the tooltip.

Whether to use the id only. Default is FALSE which will add the namespace 'tooltip-icon' to the id. Set to TRUE if the tooltip icon was not added with add_tooltip_icon (e.g., if the tooltip icon was added manually).

Arguments passed to tippy_this.

Value

The element with the tooltip.

Description

Add a tooltip icon to a label

Usage

add_tooltip_icon(..., id, icon = shiny::icon("info-circle"))

Arguments

Arguments passed to span element (e.g., the label to add the tooltip to).

The id of the tooltip.

The icon to use for the tooltip.

Value

The label with the tooltip icon.

Postprocessing helper functions after fitting the RF in NeRF+ models

Description

This function applies some processing steps to the data after fitting the RF in NeRF+ models. Specifically, it converts factor levels to numeric values based on the levels stored in the RF model.

Usage

apply_post_rf_preprocessing(object, x)

Arguments

object

A ranger object that has been fitted to the data.

x

A data frame or matrix containing the data to be processed.

Value

A data frame or matrix with the same structure as x, but with factor levels converted to numeric values based on the levels stored in object.

Wrapper around `prettyCheckbox()`

Description

Wrapper around prettyCheckbox() with different default settings.

Usage

checkbox(
  inputId,
  label,
  value = FALSE,
  status = "primary",
  animation = "jelly",
  icon = shiny::icon("check"),
  bigger = TRUE,
  ...
)

Arguments

inputId

The input slot that will be used to access the value.

label

Display label for the control.

value

Initial value (TRUE or FALSE).

status

Add a class to the checkbox, you can use Bootstrap status like 'info', 'primary', 'danger', 'warning' or 'success'.

animation

Add an animation when checkbox is checked, a value between smooth, jelly, tada, rotate, pulse.

icon

Optional, display an icon on the checkbox, must be an icon created with icon.

bigger

Scale the checkboxes a bit bigger (TRUE or FALSE).

...

Additional arguments to pass to shinyWidgets::prettyCheckbox().

Wrapper around `prettyCheckboxGroup()`

Description

Wrapper around prettyCheckboxGroup() with different default settings.

Usage

checkbox_group(
  inputId,
  label,
  choices,
  selected = NULL,
  status = "primary",
  animation = "jelly",
  icon = shiny::icon("check"),
  bigger = TRUE,
  ...
)

Arguments

inputId

The input slot that will be used to access the value.

label

Display label for the control.

choices

List of values to show checkboxes for. If elements of the list are named then that name rather than the value is displayed to the user. If this argument is provided, then choiceNames and choiceValues must not be provided, and vice-versa. The values should be strings; other types (such as logicals and numbers) will be coerced to strings.

selected

The values that should be initially selected, if any.

status

Add a class to the checkbox, you can use Bootstrap status like 'info', 'primary', 'danger', 'warning' or 'success'.

animation

Add an animation when checkbox is checked, a value between smooth, jelly, tada, rotate, pulse.

icon

Optional, display an icon on the checkbox, must be an icon created with icon.

bigger

Scale the checkboxes a bit bigger (TRUE or FALSE).

...

Additional arguments to pass to shinyWidgets::prettyCheckboxGroup().

Add css styling

Description

Add css styling

Usage

css_styler(...)

Arguments

...

Any number of named arguments with the name being the css selector and the value being the css style value.

Display inline block

Description

Display inline block

Usage

display_inline(obj)

Arguments

obj

Object to display inline.

Dummy code categorical features

Description

Dummy code categorical features

Usage

fit_dummy_code(x)

apply_dummy_code(dummy_fit, x)

Arguments

x

A data frame or matrix containing the data to be dummy-coded.

dummy_fit

A previously fitted dummy coding model; typically the output of fit_dummy_code().

Value

For fit_dummy_code(), a list containing:

dummy_fit: The fitted dummy coding model, which can be used to dummy-code new data.
x: A data frame or matrix containing the dummy-coded data. For apply_dummy_code(), a data frame or matrix containing the dummy-coded data.

Example dataset for NeRF+ demonstration

Description

Example dataset for NeRF+ demonstration

Usage

example_data

Format

`example_data`

A list with the following named components:

x: Training covariate data matrix with 80 rows and 10 columns.
xtest: Test covariate data matrix with 40 rows and 10 columns.
y: Training response vector with 80 elements.
ytest: Test response vector with 40 elements.
A: Training adjacency matrix with 80 rows and 80 columns.
A_full: Full adjacency matrix with 120 rows and 120 columns.

The covariate data matrix was generated from a standard normal distribution. The adjacency matrix was generated from a stochastic block model with 3 blocks. The responses were generated from a linear model with an additive network block effect and a main covariate effect from the first covariate only.

File input module - UI

Description

File input module - UI

File input module - Server

Usage

fileInputUI(
  id,
  label = "File Upload",
  accept = c(".csv", ".txt", ".rds"),
  show_accept = TRUE,
  tooltip = NULL
)

fileInputServer(id, default_data = NULL)

Wrapper to fit various network embedding methods

Description

Wrapper to fit various network embedding methods

Usage

fit_network_embedding(
  A,
  ndim = 2,
  method = c("adjacency", "laplacian", "score"),
  regularization = 0.5,
  varimax_rotation = FALSE
)

Arguments

A

Adjacency matrix.

ndim

Number of dimensions in embedding.

method

Embedding type(s), at least one of "adjacency", "laplacian", or score".

regularization

Regularization parameter for the adjacency matrix.

varimax_rotation

Whether to apply varimax rotation to the embedding.

Value

A list containing the following components:

X: A list of matrices, each corresponding to a method in method, where each matrix has ndim columns representing the embedding.
eval_ls: A list of eigenvalues corresponding to each method in method.
method: The method(s) used for embedding.
regularization: The regularization parameter used for the adjacency matrix.

Examples

data(example_data)
embedding_fit <- fit_network_embedding(
  example_data$A, ndim = 2, method = "laplacian"
)

Compute feature importances for a NeRF+ model

Description

This function computes global and local feature importances given a fitted NeRF+ model.

Usage

get_feature_importances(
  object,
  x,
  x_embed = NULL,
  y = NULL,
  A_full,
  nodeids = NULL,
  method = c("permute", "mdi+", "local"),
  B = 10,
  metric = NULL
)

Arguments

object

A fitted NeRF+ model object.

x

A data frame or matrix used to compute the feature importances.

x_embed

An optional data frame or matrix of network embeddings corresponding to the samples in x. Only needed if training embeddings were manually inputted.

y

A vector of responses.

A_full

An adjacency matrix representing the network structure for the full set of nodes (training + testing nodes in that order)

nodeids

(Optional) vector of node IDs of length n. If provided, node IDs indicate the rows of A, corresponding to each sample. If not provided, the rows of A are assumed to be in the same order as the rows of x and y.

method

A character string indicating the method to use for computing feature importances. Options are:

"permute": Permutation-based global feature importance.
"mdi+": MDI+ global feature importance.
"local": Local feature importance.

B

Number of samples for permutation-based feature importance. Ignored if method is not "permute".

metric

A function to compute the metric used for global feature importances. Defaults to R-squared for regression and AUROC for classification. Ignored if method is "local".

Value

If method is "permute" or "mdi+", a tibble with two columns:

var: The name of the feature.
importance: The computed feature importance score. If method is "local", an n x p

Examples


data(example_data)
nerfplus_out <- nerfplus(
  x = example_data$x, y = example_data$y, A = example_data$A,
  lambda_netcoh = 1,
  lambda_embed = 0.1,
  lambda_raw = 2,
  lambda_stump = 3,
  family = "linear", embedding = "laplacian", sample_split = "none"
)
fi_out <- get_feature_importances(
  nerfplus_out, x = example_data$xtest, y = example_data$ytest,
  A_full = example_data$A_full, method = "mdi+"
)

Extract all root-to-leaf paths in a forest.

Description

Extract all root-to-leaf paths in a forest.

Usage

get_forest_paths(tree_infos)

Arguments

tree_infos

List of size ntrees with each entry being the output of ranger::treeInfo().

Value

A list of size ntrees with each entry being a list of decision paths in each tree.

Get html snippet for built-in icons.

Description

Get html snippet for built-in icons.

Usage

get_icon(src, width = 20, height = 20, ...)

Arguments

src

Name of built-in icon.

width

Width of icon in pixels.

height

Height of icon in pixels.

...

Additional arguments to pass to htmltools::img().

Value

Character vector of icon path.

Return custom icons

Description

Return custom icons

Usage

get_icons(icon_names, width = 20, height = 20, ...)

Arguments

icon_names

Name(s) of built-in icons to return.

width

Width of icon in pixels.

height

Height of icon in pixels.

...

Additional arguments to pass to htmltools::img().

Value

Named character vector of html snippets to display icons

Compute Leave-One-Out (LOO) predictions and parameter changes for a NeRF+ model

Description

This function computes leave-one-out (LOO) predictions and parameter changes for a fitted NeRF+ model. For each sample, it computes the model's predictions and parameter estimates when that sample is left out of the training data. This is useful for assessing model stability and identifying influential observations.

Usage

get_loo(
  object,
  x,
  x_embed = NULL,
  y,
  A = NULL,
  xtest = NULL,
  xtest_embed = NULL,
  ytest = NULL,
  A_full = NULL,
  nodeids = NULL,
  nodeids_test = NULL,
  metric = NULL,
  return_all = FALSE
)

Arguments

object

A fitted NeRF+ model object.

x

A data frame or matrix containing the training data.

x_embed

An optional data frame or matrix of network embeddings corresponding to the training samples. Only needed if training embeddings were manually inputted.

y

A vector of responses for the training data.

A

An adjacency matrix representing the network structure for the training nodes.

xtest

An optional data frame or matrix containing the test data.

xtest_embed

An optional data frame or matrix of network embeddings corresponding to the test samples.

ytest

An optional vector of responses for the test data.

A_full

An optional adjacency matrix representing the network structure for the full set of nodes (training + testing nodes in that order).

nodeids

An optional vector of node IDs of length n. If provided, node IDs indicate the rows of A corresponding to each sample. If not provided, the rows of A are assumed to be in the same order as the rows of x and y.

nodeids_test

An optional vector of node IDs for the test data.

metric

An optional function to compute the metric used for evaluating prediction changes. If NULL, defaults to RMSE for linear models and AUROC for logistic models.

return_all

Logical indicating whether to return all intermediate results for each tree in the forest. Defaults to FALSE.

Value

A list containing:

loo_params

A list of LOO parameter estimates for each tree.

change_alphas

Matrix of changes in alpha parameters when each sample is left out.

mean_change_alphas

Mean change in alpha parameters across all trees.

mean_change_betas

Mean change in beta parameters across all trees.

loo_preds

Matrix of LOO predictions, where each column corresponds to predictions when a different sample is left out.

loo_preds_test

Matrix of LOO predictions on test data (if provided).

mean_change_error_test

Mean change in prediction error on test data across all trees (if provided).

mean_change_preds_test

Mean change in predictions on test data across all trees (if provided).

Examples


data(example_data)
nerfplus_out <- nerfplus(
  x = example_data$x, y = example_data$y, A = example_data$A,
  lambda_netcoh = 1,
  lambda_embed = 0.1,
  lambda_raw = 2,
  lambda_stump = 3,
  family = "linear", embedding = "laplacian", sample_split = "none"
)
loo_out <- get_loo(
  nerfplus_out,
  x = example_data$x, y = example_data$y, A = example_data$A,
  xtest = example_data$xtest, ytest = example_data$ytest,
  A_full = example_data$A_full
)

Extract all root-to-leaf paths in a tree.

Description

Extract all root-to-leaf paths in a tree.

Usage

get_tree_paths(tree_info)

Arguments

tree_info

Output of ranger::treeInfo() for a single tree.

Value

A list of decision paths in a single tree.

Short horizontal rule

Description

Short horizontal rule

Usage

hr_short(
  margin_left = "105px",
  margin_right = margin_left,
  color = "lightblue"
)

Arguments

margin_left

Left margin.

margin_right

Right margin.

color

Color of line.

Radio group button with icons

Description

Wrapper around radio_group_buttons with options to display icons and float the buttons to the right.

Usage

iconRadioGroupUI(
  id,
  ns_id,
  choices,
  selected = NULL,
  individual = FALSE,
  size = "normal",
  justified = FALSE,
  float_right = FALSE,
  ...
)

Arguments

id

Unique identifier.

choices

Choices must be some subset of "ggplot", "plotly", "table"

selected

The initially selected value. If not specified, then it defaults to the first item in choices. To start with no items selected, use character(0).

individual

If TRUE, buttons are separated.

size

Size of the buttons ('xs', 'sm', 'normal', 'lg')

justified

If TRUE, fill the width of the parent div

float_right

Logical. Whether or not to float the buttons to the right.

...

Additional arguments to pass to radio_group_buttons

Interpret NeRF+ Model

Description

Wrapper function around get_feature_importances() and get_loo(). Helpful to format results correctly for input into NeRF+ Interpreter Shiny application.

Usage

interpret_nerfplus(
  object,
  x,
  x_embed = NULL,
  y,
  A,
  nodeids = NULL,
  xtest,
  xtest_embed = NULL,
  ytest,
  A_full,
  nodeids_test = NULL,
  methods = c("permute", "mdi+", "local", "loo"),
  B = 10,
  metric = NULL,
  save = FALSE,
  save_dir = "results_nerfplus"
)

Arguments

object

A fitted NeRF+ model object.

x

A data frame or matrix containing the training data.

x_embed

An optional data frame or matrix of network embeddings corresponding to the training samples. Only needed if training embeddings were manually inputted.

y

A vector of responses for the training data.

A

An adjacency matrix representing the network structure for the training nodes.

nodeids

xtest

An optional data frame or matrix containing the test data.

xtest_embed

An optional data frame or matrix of network embeddings corresponding to the test samples.

ytest

An optional vector of responses for the test data.

A_full

An optional adjacency matrix representing the network structure for the full set of nodes (training + testing nodes in that order).

nodeids_test

An optional vector of node IDs for the test data.

methods

A character vector of methods to run. Can include any of "permute", "mdi+", "local", and "loo".

B

Number of permutations to use for permutation feature importance.

metric

A function to compute the metric used for global feature importances. Defaults to R-squared for regression and AUROC for classification.

save

Whether to save the results to disk.

save_dir

Directory to save results to if save = TRUE.

Value

A list with the following components:

object

The fitted NeRF+ model.

data_list

A list containing the data used for interpretation.

fi_results

A list containing the feature importance results.

loo_results

A list containing the sample influence results.

Examples


data(example_data)
nerfplus_out <- nerfplus(
  x = example_data$x, y = example_data$y, A = example_data$A,
  lambda_netcoh = 1,
  lambda_embed = 0.1,
  lambda_raw = 2,
  lambda_stump = 3,
  family = "linear", embedding = "laplacian", sample_split = "none"
)
out <- interpret_nerfplus(
  nerfplus_out, x = example_data$x, y = example_data$y, A = example_data$A,
  xtest = example_data$xtest, ytest = example_data$ytest,
  A_full = example_data$A_full
)

Construct a dense graph Laplacian with optional ridge adjustment

Description

Construct a dense graph Laplacian with optional ridge adjustment

Usage

make_laplacian(A, lambda_l = 0, nodedegrees = NULL)

Construct a sparse graph Laplacian with optional ridge adjustment

Description

Construct a sparse graph Laplacian with optional ridge adjustment

Usage

make_sparse_laplacian(A, lambda_l = 0, nodedegrees = NULL)

Wrapper around `materialSwitch()`

Description

Wrapper around materialSwitch() with different default settings.

Usage

material_switch(
  inputId,
  label,
  value = TRUE,
  status = "primary",
  right = FALSE,
  inline = FALSE,
  ...
)

Arguments

inputId

The input slot that will be used to access the value.

label

Input label.

value

TRUE or FALSE.

status

Color, must be a valid Bootstrap status : default, primary, info, success, warning, danger.

right

Should the the label be on the right? default to FALSE.

inline

Display the input inline, if you want to place buttons next to each other.

...

Additional arguments to pass to shinyWidgets::materialSwitch().

Fit Network-assisted Random Forest+ (NeRF+)

Description

Fit Network-assisted Random Forest+ (NeRF+)

Usage

nerfplus(
  x,
  y,
  A = NULL,
  nodeids = NULL,
  family = c("linear", "logistic"),
  include_raw = TRUE,
  include_netcoh = TRUE,
  embedding = NULL,
  embedding_options = list(ndim = 2, regularization = 0.5, varimax = FALSE, center =
    TRUE, scale = TRUE),
  standardize_x = TRUE,
  normalize_stump = FALSE,
  sample_split = c("none", "oob", "inbag"),
  ntrees = 500,
  mtry = NULL,
  lambda_netcoh,
  lambda_embed = lambda_raw,
  lambda_raw = lambda_stump,
  lambda_stump,
  lambda_l = 0.05,
  parallel = FALSE,
  num.threads = 1,
  ...
)

Arguments

x

A numeric matrix or data frame of predictors (features); size n x p. Should be centered so that each column has mean 0.

y

A numeric vector of responses of length n. Should be centered so that the mean is 0.

A

An adjacency matrix representing the network structure.

nodeids

family

A character string indicating the type of model to fit. Currently, only "linear" and "logistic" are supported.

include_raw

Logical indicating whether to include the raw covariates in the NeRF+ model. Default is TRUE.

include_netcoh

Logical indicating whether to include the individual node effects and network cohesion regularization in the NeRF+ model. Default is TRUE.

embedding

Embedding type(s), at least one of "adjacency", "laplacian", score", or NULL (i.e., do not include any network embedding features). Alternatively, can directly input an n x d matrix of network embedding features corresponding to x.

embedding_options

A list of options for the network embedding. Ignored if embedding = NULL. If provided, the list should contain the following components:

ndim: Number of dimensions in the embedding (default is 2).
regularization: Regularization parameter for the adjacency matrix (default is 0.5).
varimax: Whether to apply varimax rotation to the embedding (default is FALSE).
center: Whether to center the embedding so that each column has mean 0 (default is TRUE).
scale: Whether to scale the embedding so that first embedding component column has SD 1 (default is TRUE). All other embedding components are scaled, proportional to their eigenvalues.

standardize_x

Logical indicating whether to standardize the covariates so that each column has mean 0 and SD 1. Default is TRUE.

normalize_stump

Logical indicating whether to normalize the decision stump features by number of samples in children nodes. Default is FALSE.

sample_split

Character string indicating how to split the samples for training the model; one of "none" (default), "oob", or "inbag". If "none", all samples are used for estimating coefficients in NeRF+. If "oob", only out-of-bag samples are used for estimating coefficients in NeRF+. If "inbag", only in-bag samples are used for estimating coefficients in NeRF+.

ntrees

Number of trees in ensemble.

mtry

Number of features to consider at each split. Default is the number of features / 3 for regression and the square root of the number of features for classification.

lambda_netcoh

Regularization parameter for the network cohesion term. Can be either a scalar or a vector of length ntrees, specifying the regularization parameter for each tree. Ignored if include_netcoh = FALSE.

lambda_embed

Regularization parameter for the network embedding features. Default is same as lambda_raw. Can be either a scalar or a vector of length ntrees, specifying the regularization parameter for each tree. Ignored if embedding = NULL.

lambda_raw

Regularization parameter for the raw covariates. Default is same as lambda_stump. Can be either a scalar or a vector of length ntrees, specifying the regularization parameter for each tree. Ignored if include_raw = FALSE.

lambda_stump

Regularization parameter for the decision stump features. Can be either a scalar or a vector of length ntrees, specifying the regularization parameter for each tree.

lambda_l

(Optional) Regularization parameter for the graph Laplacian. Default is 0.05. Can be either a scalar or a vector of length ntrees, specifying the regularization parameter for each tree.

parallel

Logical indicating whether to use parallel processing.

num.threads

Number of threads to use for parallel processing. Default is 1. Ignored if parallel = FALSE.

...

Additional arguments passed to the ranger::ranger() function for fitting the random forest model.

Value

A list containing the following:

rf_fit: The fitted random forest model object from ranger::ranger().
nerfplus_fits: A list of fitted NeRF+ models for each tree in the random forest. Each element of the list is a fitted model object that can be used to make predictions.
tree_infos: A list of tree information objects for each tree in the random forest.
pre_rf_preprocessing_info: A list containing preprocessing information for the NeRF+ model; output of fit_pre_rf_preprocessing().
regularization_params: A list containing the regularization parameters used in the NeRF+ model
model_info: A list containing information about the model, such as family, include_raw, include_netcoh, normalize_stump, and sample_split.
unordered_factors: A character vector of variable names that are unordered factors.

Examples

data(example_data)
nerfplus_out <- nerfplus(
  x = example_data$x, y = example_data$y, A = example_data$A,
  lambda_netcoh = 1,
  lambda_embed = 0.1,
  lambda_raw = 2,
  lambda_stump = 3,
  family = "linear", embedding = "laplacian", sample_split = "none"
)

Augment Psi matrix in NeRF+ with raw features

Description

These helper functions augment the Psi matrix in NeRF+ with raw features. Moreover, the raw features are dummy-coded if they are categorical.

Usage

fit_augmentation(x, psi, tree_info = NULL, include_raw = TRUE)

apply_augmentation(
  x,
  psi,
  tree_info = NULL,
  include_raw = TRUE,
  dummy_fit = NULL
)

Arguments

x

A data frame or matrix containing the raw features.

psi

A data frame or matrix containing the Psi matrix, where each column corresponds to a decision stump feature.

tree_info

Output of ranger::treeInfo() for a single tree.

include_raw

Logical indicating whether to include the raw covariates in the NeRF+ model. Default is TRUE.

dummy_fit

A previously fitted dummy coding model; typically the output of fit_dummy_code(). If include_raw = TRUE, this is used to dummy-code raw features.

Value

For fit_augmentation(), a list containing:

x: A matrix containing the augmented data, which includes both the raw features (if include_raw = TRUE) and the Psi features.
dummy_fit: The fitted dummy coding model, which dummy-codes categorical features. For apply_augmentation(), a matrix containing the augmented data, which includes both the raw features (if include_raw = TRUE) and the Psi features. If include_raw = FALSE, only the Psi features are returned.

Conformal prediction method for NeRF+

Description

This function generates conformal prediction intervals for a fitted NeRF+ model, using a specified calibration dataset to compute the nonconformity scores (measured as the absolute residuals between the observed responses and the predictions) and a specified test dataset for which predictions and prediction intervals are to be generated.

Usage

nerfplus_conformal(
  object,
  x_cal,
  x_cal_embed = NULL,
  y_cal,
  x_test,
  x_test_embed = NULL,
  A_full,
  nodeids_cal = NULL,
  nodeids_test = NULL,
  alpha = 0.05
)

Arguments

object

A fitted NeRF+ model object.

x_cal

A data frame or matrix of calibration data.

x_cal_embed

Optional embedding data frame or matrix for the calibration data, whose rows are aligned with those in x_cal. If provided, it will be used to augment the input x_cal data. Only needed if training embeddings were manually inputted.

y_cal

A vector of observed responses for the calibration data.

x_test

A data frame or matrix of test data for which predictions are to be made.

x_test_embed

Optional embedding data frame or matrix for the test data, whose rows are aligned with those in x_test. If provided, it will be used to augment the input x_test data. Only needed if training embeddings were manually inputted.

A_full

An adjacency matrix representing the network structure for the full set of nodes (training + calibration + testing nodes in that order, unless nodeids_cal and nodeids_test are provided, in which case the order of nodes in A_full should align with the order of node IDs in nodeids_cal and nodeids_test).

nodeids_cal

(Optional) vector of node IDs for the calibration data, of length equal to nrows in x_cal. If provided, node IDs indicate the rows of A_full, corresponding to each calibration sample. If not provided, the rows of A_full are assumed to be in the order of (x_train, x_cal, x_test).

nodeids_test

(Optional) vector of node IDs for the test data, of length equal to nrows in x_test. If provided, node IDs indicate the rows of A_full, corresponding to each test sample. If not provided, the rows of A_full are assumed to be in the order of (x_train, x_cal, x_test).

alpha

Significance level for conformal prediction intervals. Default is 0.05 for 95% prediction intervals.

Value

A tibble with columns pred, lower_bound, and upper_bound, containing the predicted values and the corresponding lower and upper bounds of the conformal prediction intervals for each sample in the test data.

Examples

data(example_data)
train_idx <- 1:(nrow(example_data$x) / 2)
cal_idx <- (nrow(example_data$x) / 2 + 1):nrow(example_data$x)
x_train <- example_data$x[train_idx, ]
y_train <- example_data$y[train_idx]
x_cal <- example_data$x[cal_idx, ]
y_cal <- example_data$y[cal_idx]
nerfplus_out <- nerfplus(
  x = x_train, y = y_train, A = example_data$A[train_idx, train_idx],
  lambda_netcoh = 1,
  lambda_embed = 0.1,
  lambda_raw = 2,
  lambda_stump = 3,
  family = "linear", embedding = "laplacian", sample_split = "none"
)
conformal_out <- nerfplus_conformal(
  nerfplus_out,
  x_cal = x_cal, y_cal = y_cal,
  x_test = example_data$xtest,
  A_full = example_data$A_full,
  alpha = 0.05
)
conformal_out |>
  dplyr::mutate(
   contains_true_y = y_cal >= lower_bound & y_cal <= upper_bound
  ) |>
  dplyr::summarize(
   coverage = mean(contains_true_y)
  )

Fit Network-assisted Random Forest+ (NeRF+) with Cross-Validation

Description

Fit Network-assisted Random Forest+ (NeRF+) with Cross-Validation

Usage

nerfplus_cv(
  x,
  y,
  A = NULL,
  nodeids = NULL,
  cv = 5,
  cv_foldids = NULL,
  family = c("linear", "logistic"),
  include_raw = TRUE,
  include_netcoh = TRUE,
  embedding = NULL,
  embedding_options = list(ndim = 2, regularization = 0.5, varimax = FALSE, center =
    TRUE, scale = TRUE),
  standardize_x = TRUE,
  normalize_stump = FALSE,
  sample_split = c("none", "oob", "inbag"),
  ntrees = 500,
  ntrees_cv = ntrees,
  mtry = NULL,
  lambdas_netcoh,
  lambdas_embed = NULL,
  lambdas_raw = NULL,
  lambdas_stump,
  lambdas_l = 0.05,
  parallel = FALSE,
  num.threads = 1,
  ...
)

Arguments

x

A numeric matrix or data frame of predictors (features); size n x p. Should be centered so that each column has mean 0.

y

A numeric vector of responses of length n. Should be centered so that the mean is 0.

A

An adjacency matrix representing the network structure.

nodeids

cv

Number of cross-validation folds. Default is 5.

cv_foldids

(Optional) List of length cv, where each component in the list is a vector of sample indices in that fold. If NULL (default), cross-validation folds will be created randomly.

family

A character string indicating the type of model to fit. Currently, only "linear" and "logistic" are supported.

include_raw

Logical indicating whether to include the raw covariates in the NeRF+ model. Default is TRUE.

include_netcoh

Logical indicating whether to include the individual node effects and network cohesion regularization in the NeRF+ model. Default is TRUE.

embedding

embedding_options

A list of options for the network embedding. Ignored if embedding = NULL. If provided, the list should contain the following components:

ndim: Number of dimensions in the embedding (default is 2).
regularization: Regularization parameter for the adjacency matrix (default is 0.5).
varimax: Whether to apply varimax rotation to the embedding (default is FALSE).
center: Whether to center the embedding so that each column has mean 0 (default is TRUE).
scale: Whether to scale the embedding so that first embedding component column has SD 1 (default is TRUE). All other embedding components are scaled, proportional to their eigenvalues.

standardize_x

Logical indicating whether to standardize the covariates so that each column has mean 0 and SD 1. Default is TRUE.

normalize_stump

Logical indicating whether to normalize the decision stump features by number of samples in children nodes. Default is FALSE.

sample_split

ntrees

Number of trees in ensemble.

ntrees_cv

Number of trees that will be tuned using cross-validation. Default is ntrees (i.e., every tree will be tuned). Reduce this number to speed up the cross-validation process. For all trees that aren't tuned, the hyperparameter will be chosen randomly from the tuned trees.

mtry

Number of features to consider at each split. Default is the number of features / 3 for regression and the square root of the number of features for classification.

lambdas_netcoh

Vector of regularization parameters for the network cohesion term.

lambdas_embed

Vector of regularization parameters for the network embedding features. If NULL, the regularization parameter corresponding to the network embedding features will be equal to the regularization parameter for the raw covariates.

lambdas_raw

Vector of regularization parameters for the raw covariate features. If NULL, the regularization parameter for the raw covariates will be equal to the regularization parameter for the decision stump features.

lambdas_stump

Vector of regularization parameters for the decision stump features.

lambdas_l

Vector of regularization parameters for the graph Laplacian.

parallel

Logical indicating whether to use parallel processing.

num.threads

Number of threads to use for parallel processing. Default is 1. Ignored if parallel = FALSE.

...

Additional arguments passed to the ranger::ranger() function for fitting the random forest model.

Value

A list containing the following:

rf_fit: The fitted random forest model object from ranger::ranger().
nerfplus_fits: A list of fitted NeRF+ models for each tree in the random forest using the tuned hyperparameters. Each element of the list is a fitted model object that can be used to make predictions.
cv_losses: A list of ntrees_cv data frames containing the cross-validation losses for each tree and each fold. Each item in the list corresponds to a tree in the random forest. Each row in the data frame corresponds to a different set of hyperparameters.
best_cv_params: A data frame containing the used hyperparameters for each tree in the random forest.
tree_infos: A list of tree information objects for each tree in the random forest.
pre_rf_preprocessing_info: A list containing preprocessing information for the NeRF+ model; output of fit_pre_rf_preprocessing().
regularization_params: A list containing the regularization parameters used in the NeRF+ model
model_info: A list containing information about the model, such as family, include_raw, include_netcoh, normalize_stump, and sample_split.
unordered_factors: A character vector of variable names that are unordered factors.

Examples


data(example_data)
nerfplus_cv_out <- nerfplus_cv(
  x = example_data$x, y = example_data$y, A = example_data$A,
  lambdas_netcoh = c(0.1, 1),
  lambdas_embed = c(0, 0.1),
  lambdas_raw = c(1, 2),
  lambdas_stump = c(1, 2),
  family = "linear", embedding = "laplacian", sample_split = "none"
)

Preprocessing helper functions prior to fitting the RF in NeRF+ models

Description

These functions fit or apply preprocessing steps prior to fitting RF in NeRF+ models. Specifically, this function standardizes the numeric features to have mean 0 and SD 1 (if standardize = TRUE) and augments the data with (standardized) network embeddings (if embedding is specified).

Usage

fit_pre_rf_preprocessing(
  x,
  A = NULL,
  standardize = TRUE,
  embedding = NULL,
  embedding_options = list(ndim = 2, regularization = 0.5, varimax = FALSE, center =
    FALSE, scale = FALSE),
  nodeids = NULL
)

apply_pre_rf_preprocessing(
  preprocess_fit,
  x,
  x_embed = NULL,
  A_full,
  nodeids = NULL
)

Arguments

x

A numeric matrix or data frame of predictors (features); size n x p. Should be centered so that each column has mean 0.

A

An adjacency matrix representing the network structure.

standardize

Logical indicating whether to standardize numeric features in x to have mean 0 and SD 1. Defaults to TRUE.

embedding

embedding_options

A list of options for the network embedding. Ignored if embedding = NULL. If provided, the list should contain the following components:

ndim: Number of dimensions in the embedding (default is 2).
regularization: Regularization parameter for the adjacency matrix (default is 0.5).
varimax: Whether to apply varimax rotation to the embedding (default is FALSE).
center: Whether to center the embedding so that each column has mean 0 (default is TRUE).
scale: Whether to scale the embedding so that first embedding component column has SD 1 (default is TRUE). All other embedding components are scaled, proportional to their eigenvalues.

nodeids

preprocess_fit

Output of fit_pre_rf_preprocessing() to be applied to new data.

x_embed

Optional embedding data frame or matrix, whose rows are aligned with those in x. If provided, it will be used to augment the input x data. Only needed if training embeddings were manually inputted.

A_full

An adjacency matrix representing the network structure for the full set of nodes (training + testing nodes in that order).

Value

For fit_pre_rf_preprocessing(), a list containing the following components:

x: The preprocessed data frame
standardize_x: Logical indicating whether the raw data was standardized
x_center_factors: Named numeric vector of means used for standardization
x_scale_factors: Named numeric vector of standard deviations used for standardization
embedding: The method used for embedding
embedding_fit: The output of the network embedding fit
embed_center_factors: Named numeric vector of means used for standardizing the embeddings
embed_scale_factors: Named numeric vector of standard deviations used for standardizing the embeddings
nodeids: The node IDs provided for the embeddings.

For apply_pre_rf_preprocessing(), a data frame with the preprocessed data.

Get the Psi matrix in NeRF+ containing decision stump features

Description

These helper functions fit or apply a previously fitted Psi mapping (i.e., decision stump feature mapping) to data.

Usage

fit_psi(
  x,
  tree_info,
  tree_paths,
  node_preds,
  unordered_factors = NULL,
  normalize = FALSE,
  inbag_counts = NULL,
  as_matrix = FALSE
)

apply_psi(
  x,
  tree_info,
  tree_paths,
  node_preds,
  unordered_factors = NULL,
  psi_unique_values = NULL,
  as_matrix = FALSE
)

Arguments

x

A data frame or matrix containing the data to feed through decision tree to obtain the Psi (i.e., decision stump features) matrix.

tree_info

Output of ranger::treeInfo() for a single tree.

tree_paths

List of size ntrees with paths for each tree; typically the output of get_forest_paths().

node_preds

Matrix of terminal node predictions for each tree in the random forest; typically, output from predict(rf_fit, x, type = "terminalNodes")$predictions, where rf_fit is a fitted ranger object and x is the data frame or matrix.

unordered_factors

Vector of column names corresponding to unordered factor variables in the data.

normalize

Logical indicating whether to normalize the Psi matrix by number of training samples in each child node. Defaults to FALSE.

inbag_counts

List of size ntrees with inbag counts for each tree; typically the output from rf_fit$inbag.counts, where rf_fit is a fitted ranger object. Ignored if normalize = FALSE.

psi_unique_values

A named list of unique values for each Psi feature, typically obtained from the output of fit_psi().

Value

For fit_psi(), a list of two:

psi: A data frame containing the Psi matrix, where each column corresponds to a decision stump feature
psi_unique_values: A named list of unique values for each Psi feature (only returned if normalize = TRUE). For apply_psi(), a data frame containing the Psi matrix, where each column corresponds to a decision stump feature.

Out-of-sample network embedding method

Description

This function takes in out-of-sample points (which were not available at training time) and embeds them in a previously trained network embedding space.

Usage

oos_network_embedding(embedding_fit, A, A_full)

Arguments

embedding_fit

Previously trained network embedding; should be output of fit_network_embedding().

A

Adjacency matrix corresponding to the training data points.

A_full

Adjacency matrix representing the full set of nodes (training + testing nodes in that order).

Value

A list of two:

X: A list of matrices, each corresponding to a method in embedding_fit$method, where each matrix has ndim columns representing the embedding for the out-of-sample points.
method: The method(s) used for embedding.

Examples

data(example_data)
embedding_fit <- fit_network_embedding(
  example_data$A, ndim = 2, method = "laplacian"
)
oos_embedding <- oos_network_embedding(
  embedding_fit, A = example_data$A, A_full = example_data$A_full
)

Wrapper around `dropdown()`

Description

Wrapper around dropdown() with different default settings

Usage

options_dropdown(
  ...,
  status = "primary",
  size = "sm",
  icon = shiny::icon("cog"),
  width = "300px",
  right = TRUE,
  style = "material-circle",
  tooltip = FALSE
)

Arguments

...

List of tag to be displayed into the dropdown menu.

status

Color of the button, see actionBttn().

size

Size of the button : xs,sm, md, lg.

icon

An optional icon to appear on the button.

width

Width of the dropdown menu content.

right

Logical. The dropdown menu starts on the right.

style

Style of the button, to choose between simple, bordered, minimal, stretch, jelly, gradient, fill, material-circle, material-flat, pill, float, unite.

Put a tooltip on the button, you can customize tooltip with tooltipOptions().

Wrapper around `pickerInput()` to select one choice

Description

Wrapper around pickerInput() to select one choice but with different default settings.

Usage

picker_input(inputId, label, choices, selected = NULL, options = NULL, ...)

Arguments

inputId

The input slot that will be used to access the value.

label

Display label for the control, or NULL for no label.

choices

List of values to select from. If elements of the list are named then that name rather than the value is displayed to the user.

selected

The initially selected value (or multiple values if multiple = TRUE). If not specified then defaults to the first value for single-select lists and no values for multiple select lists.

options

List of options, see pickerOptions for all available options. To limit the number of selection possible, see example below.

...

Additional arguments to pass to shinyWidgets::pickerInput().

Basic Plot Options

Description

Basic Plot Options

Usage

plotOptionsUI(
  id,
  multicol = FALSE,
  heatmap = FALSE,
  strip_options = FALSE,
  total_width = 12,
  height = 500,
  x_axis_text_size = 12,
  y_axis_text_size = 12,
  legend_text_size = 12,
  strip_text_size = 14,
  x_axis_title_size = 14,
  y_axis_title_size = 14,
  legend_title_size = 14,
  title_size = 16,
  axis_line_width = 1,
  x_text_angle = FALSE,
  strip_text_color = "white",
  bg_color = "grey98",
  other_options = NULL
)

Arguments

id

Unique identifier.

multicol

Logical. If TRUE, use multiple columns.

heatmap

Logical. If TRUE, include heatmap options.

strip_options

Logical. If TRUE, include strip options.

total_width

Total width of html element.

height

Height of html element.

x_axis_text_size

Default size of x-axis text.

y_axis_text_size

Default size of y-axis text.

legend_text_size

Default size of legend text.

strip_text_size

Default size of strip text.

x_axis_title_size

Default size of x-axis title.

y_axis_title_size

Default size of y-axis title.

legend_title_size

Default size of legend title.

title_size

Default size of title.

axis_line_width

Default width of axis lines.

x_text_angle

Default angle of x-axis text. If FALSE, x-axis text is horizontal. Otherwise, it is angled 45 degrees.

strip_text_color

Default color of strip text.

bg_color

Default background color.

other_options

Additional shiny widgets/tags to add to plot options.

Value

List of shiny tags.

Basic plot module - UI

Description

Basic plot module - UI

Basic plot module - Server

Usage

plotUI(id, border = FALSE, spinner = FALSE)

plotServer(
  id,
  plot_fun,
  plot_options = TRUE,
  modes = c("ggplot", "plotly"),
  border = FALSE,
  spinner = TRUE,
  error_msg = ""
)

Predict method for a NeRF+ model

Description

Predict method for a NeRF+ model

Usage

## S3 method for class 'nerfplus'
predict(
  object,
  x,
  x_embed = NULL,
  A_full,
  nodeids = NULL,
  type = c("response", "alpha"),
  return_all = FALSE,
  ...
)

Arguments

object

A fitted NeRF+ model object.

x

A data frame or matrix of new data for which predictions are to be made.

x_embed

A_full

An adjacency matrix representing the network structure for the full set of nodes (training + testing nodes in that order). Note: if nrow(x) == nrow(A_full), then x is assumed to be the training data.

nodeids

(Optional) vector of node IDs of length equal to nrows in x. If provided, node IDs indicate the rows of A_full, corresponding to each sample. If not provided, the rows of A_full are assumed to be in the order of (x_train, x).

type

Type of prediction to return; one of "response" (default) or "alpha". If "response", the predicted values are returned. If "alpha", the estimated individual node effects are returned.

return_all

If TRUE, returns a list of predictions for each tree in the ensemble. If FALSE (default), returns the average prediction across all trees.

...

Additional arguments, currently unused.

Value

If return_all = FALSE, this function returns a vector of predicted values (if type = "response") or estimated individual node effects (if type = "alpha"). If return_all = TRUE, this function returns a list of predicted values or estimated individual node effects, where each element in the list corresponds to a different tree in the ensemble.

Examples

data(example_data)
nerfplus_out <- nerfplus(
  x = example_data$x, y = example_data$y, A = example_data$A,
  lambda_netcoh = 1,
  lambda_embed = 0.1,
  lambda_raw = 2,
  lambda_stump = 3,
  family = "linear", embedding = "laplacian", sample_split = "none"
)
predicted_y <- predict(
  nerfplus_out, x = example_data$xtest, A_full = example_data$A_full,
  type = "response"
)
estimated_alphas <- predict(
  nerfplus_out, x = example_data$xtest, A_full = example_data$A_full,
  type = "alpha"
)

Predict method for rnc (regression with network cohesion) objects

Description

Predict method for rnc (regression with network cohesion) objects

Usage

## S3 method for class 'rnc'
predict(object, x, A_full, nodeids = NULL, ...)

Arguments

object

An object of class rnc containing the fitted model.

x

A numeric matrix or data frame of predictors (features) to make predictions for; size n x p.

A_full

An adjacency matrix representing the network structure for the full set of nodes (training + testing nodes in that order)

nodeids

(Optional) vector of node IDs of length n. If provided, node IDs indicate the rows of A_full, corresponding to each sample. If not provided, the rows of A_full are assumed to be in the order of (x_train, x).

...

Not used.

Value

A list of two:

y: A numeric vector of predictions for the response variable.
alpha: A numeric vector of node-specific effects (intercepts).

Examples

data(example_data)

# demonstrate prediction for RNC fit
rnc_fit <- rnc(
  x = example_data$x, y = example_data$y, A = example_data$A,
  lambda_netcoh = 1, lambda_x = 0.5
)
predicted_out <- predict(
  rnc_fit, x = example_data$xtest, A_full = example_data$A_full
)

# demonstrate prediction for RNC CV fit
cv_fit <- rnc_cv(
  x = example_data$x, y = example_data$y, A = example_data$A,
  lambdas_netcoh = c(0, 0.1, 1),
  lambdas_x = c(0.1, 0.5)
)
predicted_out <- predict(
  cv_fit, x = example_data$xtest, A_full = example_data$A_full
)

Predict method for rnc linear regression objects

Description

Predict method for rnc linear regression objects

Usage

predict_rnc_linear(object, x, A_full, nodeids = NULL)

Arguments

object

An object of class rnc containing the fitted model.

x

A numeric matrix or data frame of predictors (features) to make predictions for; size n x p.

A_full

An adjacency matrix representing the network structure for the full set of nodes (training + testing nodes in that order)

nodeids

Predict method for rnc logistic regression objects

Description

Predict method for rnc logistic regression objects

Usage

predict_rnc_logistic(object, x, A_full, nodeids = NULL)

Arguments

object

An object of class rnc containing the fitted model.

x

A numeric matrix or data frame of predictors (features) to make predictions for; size n x p.

A_full

An adjacency matrix representing the network structure for the full set of nodes (training + testing nodes in that order)

nodeids

Pretty box

Description

Wrapper around shinydashboardPlus::box().

Usage

prettyBox(
  ...,
  title = NULL,
  width = 12,
  color = NULL,
  status = "primary",
  solidHeader = TRUE,
  box_only = FALSE
)

Arguments

...

Arguments passed to shinydashboardPlus::box().

title

Optional title.

width

The width of the box, using the Bootstrap grid system. This is used for row-based layouts. The overall width of a region is 12, so the default valueBox width of 4 occupies 1/3 of that width. For column-based layouts, use NULL for the width; the width is set by the column that contains the box.

color

Box outline color.

status

Box status controlling the header and border color. Supported values are "primary", "success", "info", "warning", "danger", "navy", "teal", "purple", "orange", "maroon", and "black". Only the first five values support a solid header.

solidHeader

Should the header be shown with a solid color background?

box_only

If TRUE, only return the box and not the box wrapped inside shiny::fluidRow().

Pretty dashboard header

Description

Wrapper around shinydashboard::dashboardHeader() that allows for the title to be positioned to the left or center.

Usage

prettyDashboardHeader(
  title,
  title_position = c("left", "center"),
  title_style = list(),
  ...
)

Arguments

title

An optional title to show in the header bar.. By default, this will also be used as the title shown in the browser's title bar. If you want that to be different from the text in the dashboard header bar, set the title in dashboardPage().

title_position

Position of the title, either "left" or "center".

title_style

(Optional) list of CSS styling options for the title.

...

Arguments passed to shinydashboard::dashboardHeader().

Wrapper around `prettyRadioButtons()`

Description

Wrapper around prettyRadioButtons() but with different default settings.

Usage

radio_buttons(
  inputId,
  label,
  choices,
  selected = NULL,
  status = "primary",
  animation = "jelly",
  icon = shiny::icon("check"),
  bigger = TRUE,
  ...
)

Arguments

inputId

The input slot that will be used to access the value.

label

Display label for the control.

choices

List of values to show radio buttons for. If elements of the list are named then that name rather than the value is displayed to the user. If this argument is provided, then choiceNames and choiceValues must not be provided, and vice-versa. The values should be strings; other types (such as logicals and numbers) will be coerced to strings.

selected

The values that should be initially selected, (if not specified then defaults to the first value).

status

Add a class to the radio, you can use Bootstrap status like 'info', 'primary', 'danger', 'warning' or 'success'.

animation

Add an animation when radio is checked, a value between smooth, jelly, tada, rotate, pulse.

icon

Optional, display an icon on the radio, must be an icon created with icon.

bigger

Scale the radio a bit bigger (TRUE or FALSE).

...

Additional arguments to pass to shinyWidgets::prettyRadioButtons().

Wrapper around `radioGroupButtons()`

Description

Wrapper around radioGroupButtons() but with different default settings.

Usage

radio_group_buttons(
  inputId,
  label,
  choices,
  selected = NULL,
  status = "default",
  size = "sm",
  justified = FALSE,
  ...
)

Arguments

inputId

The input slot that will be used to access the value.

label

Display label for the control, or NULL for no label.

choices

List of values to select from (if elements of the list are named then that name rather than the value is displayed to the user). If this argument is provided, then choiceNames and choiceValues must not be provided, and vice-versa. The values should be strings; other types (such as logicals and numbers) will be coerced to strings.

selected

The initially selected value. If not specified, then it defaults to the first item in choices. To start with no items selected, use character(0).

status

Add a class to the buttons, you can use Bootstrap status like 'info', 'primary', 'danger', 'warning' or 'success'. Or use an arbitrary strings to add a custom class, e.g. : with status = "custom-class", buttons will have class btn-custom-class.

size

Size of the buttons ('xs', 'sm', 'normal', 'lg')

justified

If TRUE, fill the width of the parent div

...

Additional arguments to pass to shinyWidgets::radioGroupButtons().

Reset button

Description

Customized action button using actionButton().

Usage

reset_button(inputId = "reset_input", label = "Reset all inputs", ...)

Arguments

inputId

The input slot that will be used to access the value.

label

The contents of the button or link–usually a text label, but you could also use any other HTML, like an image.

...

Additional arguments to pass to shiny::actionButton().

Reset all inputs

Description

Reset all inputs to their default values. Note that shinyjs::useShinyjs() needs to be includes in the UI for this to work.

Usage

reset_inputs(input, session, reset_input_ids = NULL)

Arguments

input

Shiny input.

session

Shiny session.

reset_input_ids

A character vector of input IDs to reset. If NULL, all inputs will be reset.

Fit regression with network cohesion

Description

This function fits a regression model with network cohesion regularization. This code has been adapted from the netcoh R package with minor tweaks for increased speed and flexibility. Currently, it can handle linear and logistic regression only.

Usage

rnc(
  x,
  y,
  A,
  nodedegrees = NULL,
  nodeids = NULL,
  lambda_netcoh,
  lambda_x = 0,
  lambda_l = 0.05,
  family = c("linear", "logistic"),
  low_dim = NULL,
  init = NULL,
  newton_maxit = 50,
  newton_tol = 1e-04,
  verbose = FALSE
)

Arguments

x

A numeric matrix or data frame of predictors (features); size n x p. Should be centered so that each column has mean 0.

y

A numeric vector of responses of length n. Should be centered so that the mean is 0.

A

An adjacency matrix representing the network structure.

nodedegrees

(Optional) A vector of node degrees. If provided, it is used to compute the graph Laplacian. If not provided, it is computed from the adjacency matrix A.

nodeids

lambda_netcoh

Regularization parameter for the network cohesion term.

lambda_x

(Optional) Regularization parameter for the (linear) covariates. Default is 0 (i.e., no regularization).

lambda_l

(Optional) Regularization parameter for the graph Laplacian. Default is 0.05.

family

A character string indicating the type of model to fit. Currently, only "linear" and "logistic" are supported.

low_dim

(Optional) If TRUE, the algorithm will use a naive solver for low-dimensional problems. Default is NULL, which will use the navie low-dimensional solver if the number of covariates is <= 1/5 * the number of samples. Only used if family = "linear".

init

(Optional) initial values for the optimization algorithm to fit logistic regression. Ignored for linear regression.

newton_maxit

Maximum number of Newton iterations when fitting logistic regression. Default is 50. Ignored for linear regression.

newton_tol

Tolerance for convergence of Newton iterations when fitting logistic regression. Default is 1e-4. Ignored for linear regression.

verbose

Logical indicating whether to print progress messages.

Value

A list with the following components:

alpha: n x 1 matrix of coefficients corresponding to the individual node effects
beta: p x 1 matrix of coefficients corresponding to the covariates
lambda_netcoh: Regularization parameter for the network cohesion term.
lambda_x: Regularization parameter for the covariates.
lambda_l: Regularization parameter for the graph Laplacian.
nalpha_train: Number of distinct nodes in the training set (i.e., number of rows in A).
family: The type of model fitted, either "linear" or "logistic".

Examples

data(example_data)
rnc_fit <- rnc(
  x = example_data$x, y = example_data$y, A = example_data$A,
  lambda_netcoh = 1, lambda_x = 0.5
)

Fit regression with network cohesion with cross-validation wrapper

Description

This function fits a regression model with network cohesion regularization with a cross-validation wrapper. This code has been adapted from the netcoh R package with minor tweaks for increased speed and flexibility. Currently, it can handle linear and logistic regression only.

Usage

rnc_cv(
  x,
  y,
  A,
  nodeids = NULL,
  lambdas_netcoh,
  lambdas_x = 0,
  lambdas_l = 0.05,
  lambda_grid = NULL,
  family = c("linear", "logistic"),
  cv = 5,
  cv_foldids = NULL,
  refit = TRUE,
  newton_maxit = 50,
  newton_tol = 1e-04,
  verbose = FALSE
)

Arguments

x

A numeric matrix or data frame of predictors (features); size n x p. Should be centered so that each column has mean 0.

y

A numeric vector of responses of length n. Should be centered so that the mean is 0.

A

An adjacency matrix representing the network structure.

nodeids

lambdas_netcoh

Vector or list of regularization parameters for the network cohesion term.

lambdas_x

Vector or list of regularization parameters for the (linear) covariates. Default is 0 (i.e., no regularization).

lambdas_l

(Optional) Vector or list of regularization parameters for the graph Laplacian.

lambda_grid

(Optional) A data frame with columns lambda_netcoh, lambda_x, and lambda_l, where each row specifies a different set of regularization parameters to try. If NULL, a grid of regularization parameters will be generated based upon all possible combination of the provided lambdas_netcoh, lambdas_x, and lambdas_l.

family

A character string indicating the type of model to fit. Currently, only "linear" and "logistic" are supported.

cv

Number of cross-validation folds. Default is 5.

cv_foldids

(Optional) List of length cv, where each component in the list is a vector of sample indices in that fold. If NULL (default), cross-validation folds will be created randomly.

refit

Logical indicating whether or not to refit tuned model on full training set after cross-validation. Default is TRUE.

newton_maxit

Maximum number of Newton iterations when fitting logistic regression. Default is 50. Ignored for linear regression.

newton_tol

Tolerance for convergence of Newton iterations when fitting logistic regression. Default is 1e-4. Ignored for linear regression.

verbose

Logical indicating whether to print progress messages.

Value

A list with the following components:

lambda_grid: A data frame with the regularization parameters used in the cross-validation.
best_params: A data frame with the best regularization parameters found during cross-validation.
cv_errs: A matrix of cross-validation errors, where each row corresponds to a set of regularization parameters and each column corresponds to a fold. If regression, the RMSE is returned. If classification, the AUROC is returned.
cv_means: A vector of mean cross-validation errors for each set of regularization parameters.
cv_sds: A vector of standard deviations of cross-validation errors for each set of regularization parameters.
Other components from the fitted model if refit = TRUE (see output of rnc()).

Examples

data(example_data)

# fit RNC with CV
cv_fit <- rnc_cv(
  x = example_data$x, y = example_data$y, A = example_data$A,
  lambdas_netcoh = c(0, 0.1, 1),
  lambdas_x = c(0.1, 0.5)
)

# fit RNC with CV, specifying lambda grid manually (equivalent to above)
lambda_grid <- expand.grid(
  lambda_netcoh = c(0, 0.1, 1),
  lambda_x = c(0.1, 0.5),
  lambda_l = 0.05
)
cv_fit <- rnc_cv(
  x = example_data$x, y = example_data$y, A = example_data$A,
  lambda_grid = lambda_grid
)

Fit linear regression with network cohesion

Description

Fit linear regression with network cohesion

Usage

rnc_linear(
  x,
  y,
  A,
  nodedegrees = NULL,
  nodeids = NULL,
  lambda_netcoh,
  lambda_x = 0,
  lambda_l = 0.05,
  low_dim = NULL
)

Arguments

x

A numeric matrix or data frame of predictors (features); size n x p. Should be centered so that each column has mean 0.

y

A numeric vector of responses of length n. Should be centered so that the mean is 0.

A

An adjacency matrix representing the network structure.

nodedegrees

(Optional) A vector of node degrees. If provided, it is used to compute the graph Laplacian. If not provided, it is computed from the adjacency matrix A.

nodeids

lambda_netcoh

Regularization parameter for the network cohesion term.

lambda_x

(Optional) Regularization parameter for the (linear) covariates. Default is 0 (i.e., no regularization).

lambda_l

(Optional) Regularization parameter for the graph Laplacian. Default is 0.05.

low_dim

Fit regularization path for linear regression with network cohesion

Description

Fit regularization path for linear regression with network cohesion

Usage

rnc_linear_path(
  x,
  y,
  L,
  x_test = NULL,
  y_test = NULL,
  L22 = NULL,
  L21 = NULL,
  lambda_grid,
  nodeids = NULL,
  nodeids_test = NULL,
  ...
)

Fit logistic regression with network cohesion

Description

Fit logistic regression with network cohesion

Usage

rnc_logistic(
  x,
  y,
  A,
  nodedegrees = NULL,
  nodeids = NULL,
  lambda_netcoh,
  lambda_x = 0,
  lambda_l = 0.05,
  init = NULL,
  newton_maxit = 50,
  newton_tol = 1e-04,
  verbose = FALSE
)

Arguments

x

A numeric matrix or data frame of predictors (features); size n x p. Should be centered so that each column has mean 0.

y

A numeric vector of responses of length n. Should be centered so that the mean is 0.

A

An adjacency matrix representing the network structure.

nodedegrees

(Optional) A vector of node degrees. If provided, it is used to compute the graph Laplacian. If not provided, it is computed from the adjacency matrix A.

nodeids

lambda_netcoh

Regularization parameter for the network cohesion term.

lambda_x

(Optional) Regularization parameter for the (linear) covariates. Default is 0 (i.e., no regularization).

lambda_l

(Optional) Regularization parameter for the graph Laplacian. Default is 0.05.

init

(Optional) initial values for the optimization algorithm to fit logistic regression. Ignored for linear regression.

newton_maxit

Maximum number of Newton iterations when fitting logistic regression. Default is 50. Ignored for linear regression.

newton_tol

Tolerance for convergence of Newton iterations when fitting logistic regression. Default is 1e-4. Ignored for linear regression.

verbose

Logical indicating whether to print progress messages.

Fit regularization path for logistic regression with network cohesion

Description

Fit regularization path for logistic regression with network cohesion

Usage

rnc_logistic_path(
  x,
  y,
  A = NULL,
  x_test = NULL,
  y_test = NULL,
  A_full = NULL,
  L_unreg = NULL,
  L_full_unreg = NULL,
  lambda_grid,
  nodeids = NULL,
  nodeids_test = NULL,
  newton_maxit = 50,
  newton_tol = 1e-04,
  ...
)

Fit scaled logistic regression with a precomputed network Laplacian

Description

Fit scaled logistic regression with a precomputed network Laplacian

Usage

rnc_logistic_scaled_laplacian(
  x,
  y,
  L,
  lambda_netcoh,
  lambda_x = 0,
  init = NULL,
  newton_maxit = 50,
  newton_tol = 1e-04,
  verbose = FALSE
)

Evaluate r-squared with NA handling

Description

This function computes the R-squared value and returns 0 (instead of NA) if the estimate is a constant vector.

Usage

rsq_narm_vec(truth, estimate, ...)

Arguments

truth

A numeric vector of true values.

estimate

A numeric vector of estimated values.

...

Additional arguments passed to yardstick::rsq_vec()

Value

A numeric value representing the R-squared value, or 0 if the estimate is a constant vector.

Run Shiny NeRF+ Interpret application

Description

Run Shiny NeRF+ Interpret application

Usage

run_app(
  data_list = NULL,
  object = NULL,
  fi_results = NULL,
  loo_results = NULL,
  max_request_size = 100 * 1024^2,
  ...
)

Arguments

data_list

A list containing the data used for interpretation. Should have the same format as the data_list output from interpret_nerfplus().

object

The fitted NeRF+ model. Should have the same format as the object output from interpret_nerfplus().

fi_results

A list containing the feature importance results. Should have the same format as the fi_results output from interpret_nerfplus().

loo_results

A list containing the sample influence results. Should have the same format as the loo_results output from interpret_nerfplus().

max_request_size

Maximum request size for file uploads. Defaults to 100 MB.

...

Additional arguments to pass to shiny::shinyApp()

Value

A shiny application

Examples


if (interactive()) {
  # launch app
  run_app()
}

# or run with arguments
data(example_data)
nerfplus_out <- nerfplus(
  x = example_data$x, y = example_data$y, A = example_data$A,
  lambda_netcoh = 1,
  lambda_embed = 0.1,
  lambda_raw = 2,
  lambda_stump = 3,
  family = "linear", embedding = "laplacian", sample_split = "none"
)
out <- interpret_nerfplus(
  nerfplus_out, x = example_data$x, y = example_data$y, A = example_data$A,
  xtest = example_data$xtest, ytest = example_data$ytest,
  A_full = example_data$A_full
)

if (interactive()) {
  run_app(
    data_list = out$data_list,
    object = out$object,
    fi_results = out$fi_results,
    loo_results = out$loo_results
  )
}

Run button

Description

Customized action button using actionButton().

Usage

run_button(inputId = "run_methods", label = "Run methods", ...)

Arguments

inputId

The input slot that will be used to access the value.

label

The contents of the button or link–usually a text label, but you could also use any other HTML, like an image.

...

Additional arguments to pass to shiny::actionButton().

Select visualization type (table, ggplot, plotly)

Description

Select visualization type (table, ggplot, plotly)

Usage

selectVizUI(
  id,
  choices = c("ggplot", "plotly", "table"),
  selected = NULL,
  individual = FALSE,
  size = "normal",
  justified = FALSE,
  float_right = FALSE,
  ...
)

Arguments

id

Unique identifier.

choices

Choices must be some subset of "ggplot", "plotly", "table"

selected

The initially selected value. If not specified, then it defaults to the first item in choices. To start with no items selected, use character(0).

individual

If TRUE, buttons are separated.

size

Size of the buttons ('xs', 'sm', 'normal', 'lg')

justified

If TRUE, fill the width of the parent div

float_right

Logical. Whether or not to float the buttons to the right.

...

Additional arguments to pass to radio_group_buttons

Set margins

Description

Set margins

Usage

set_margins(obj, top = NULL, bottom = NULL, left = NULL, right = NULL)

Arguments

obj

Object to set margins.

top

Top margin.

bottom

Bottom margin.

left

Left margin.

right

Right margin.

Arguments that are shared by multiple functions

Description

Arguments that are shared by multiple functions

Arguments

x

A numeric matrix or data frame of predictors (features); size n x p. Should be centered so that each column has mean 0.

y

A numeric vector of responses of length n. Should be centered so that the mean is 0.

A

An adjacency matrix representing the network structure.

nodeids

family

A character string indicating the type of model to fit. Currently, only "linear" and "logistic" are supported.

lambda_netcoh

Regularization parameter for the network cohesion term.

lambda_l

(Optional) Regularization parameter for the graph Laplacian. Default is 0.05.

lambdas_netcoh

Vector or list of regularization parameters for the network cohesion term.

lambdas_l

(Optional) Vector or list of regularization parameters for the graph Laplacian.

cv

Number of cross-validation folds. Default is 5.

cv_foldids

(Optional) List of length cv, where each component in the list is a vector of sample indices in that fold. If NULL (default), cross-validation folds will be created randomly.

refit

Logical indicating whether or not to refit tuned model on full training set after cross-validation. Default is TRUE.

low_dim

init

(Optional) initial values for the optimization algorithm to fit logistic regression. Ignored for linear regression.

newton_maxit

Maximum number of Newton iterations when fitting logistic regression. Default is 50. Ignored for linear regression.

newton_tol

Tolerance for convergence of Newton iterations when fitting logistic regression. Default is 1e-4. Ignored for linear regression.

verbose

Logical indicating whether to print progress messages.

parallel

Logical indicating whether to use parallel processing.

num.threads

Number of threads to use for parallel processing. Default is 1. Ignored if parallel = FALSE.

Shared arguments for NeRF+ utility functions

Description

Shared arguments for NeRF+ utility functions

Arguments

tree_info

Output of ranger::treeInfo() for a single tree.

tree_infos

List of size ntrees with each entry being the output of ranger::treeInfo().

tree_paths

List of size ntrees with paths for each tree; typically the output of get_forest_paths().

node_preds

unordered_factors

Vector of column names corresponding to unordered factor variables in the data.

inbag_counts

List of size ntrees with inbag counts for each tree; typically the output from rf_fit$inbag.counts, where rf_fit is a fitted ranger object. Ignored if normalize = FALSE.

include_raw

Logical indicating whether to include the raw covariates in the NeRF+ model. Default is TRUE.

Basic Table Options

Description

Basic Table Options

Usage

tableOptionsUI(
  id,
  digits = NA,
  digits_label = "Digits",
  sigfig = FALSE,
  sigfig_label = "Use Significant Digits",
  total_width = NULL
)

Arguments

id

Unique identifier.

digits

Default number of digits to display.

digits_label

Displayed label for digits input.

sigfig

Logical. If TRUE, use significant digits.

sigfig_label

Displayed label for significant digits checkbox.

total_width

Total width of html element.

Value

List of shiny tags.

Basic table module - Server

Description

Basic table module - Server

Usage

tableServer(
  id,
  table_fun,
  table_options = TRUE,
  mode = c("DT", "kable"),
  caption = NULL,
  border = FALSE,
  spinner = TRUE,
  error_msg = "",
  ...
)

Compute local feature importance for a tree in NeRF+

Description

Compute local feature importance for a tree in NeRF+

Usage

tree_local_fi(
  tree_object,
  x,
  A_full = NULL,
  nodeids = NULL,
  x_means = NULL,
  grouped_features = NULL,
  L_full = NULL,
  solve_cache = NULL
)

Arguments

tree_object

A fitted tree object from NeRF+.

x

A data frame or matrix used to compute the feature importances.

A_full

An adjacency matrix representing the network structure for the full set of nodes (training + testing nodes in that order)

nodeids

x_means

A named vector of means for each feature in x. If NULL, the means are computed from x.

grouped_features

A list of features to group together for permutation importance. Each element of the list should be a character vector of feature names. If NULL, each feature is treated as a separate group. Typically, this is the output of get_grouped_tree_features().

Value

A tibble with n rows and p columns, where n is the number of samples and p is the number of features. Each column corresponds to a feature, and each row corresponds to a sample. The values represent the local feature importance scores for each feature and sample.

Compute MDI+ feature importance for a tree in NeRF+

Description

Compute MDI+ feature importance for a tree in NeRF+

Usage

tree_mdiplus_fi(
  tree_object,
  x,
  y,
  A_full = NULL,
  nodeids = NULL,
  metric,
  x_means = NULL,
  grouped_features = NULL,
  L_full = NULL,
  solve_cache = NULL
)

Arguments

tree_object

A fitted tree object from NeRF+.

x

A data frame or matrix used to compute the feature importances.

y

A vector of responses.

A_full

An adjacency matrix representing the network structure for the full set of nodes (training + testing nodes in that order)

nodeids

metric

A function to compute the metric used for global feature importances. Defaults to R-squared for regression and AUROC for classification. Ignored if method is "local".

x_means

A named vector of means for each feature in x. If NULL, the means are computed from x.

grouped_features

Value

A tibble with two columns:

var: The name of the feature.
importance: The computed feature importance score.

Compute permutation importance for a tree in NeRF+

Description

Compute permutation importance for a tree in NeRF+

Usage

tree_permute_fi(
  tree_object,
  x,
  y,
  A_full = NULL,
  nodeids = NULL,
  metric,
  grouped_features = NULL,
  B = 10,
  return_preds = FALSE,
  L_full = NULL,
  solve_cache = NULL
)

Arguments

tree_object

A fitted tree object from NeRF+.

x

A data frame or matrix used to compute the feature importances.

y

A vector of responses.

A_full

An adjacency matrix representing the network structure for the full set of nodes (training + testing nodes in that order)

nodeids

metric

A function to compute the metric used for global feature importances. Defaults to R-squared for regression and AUROC for classification. Ignored if method is "local".

grouped_features

B

Number of bootstrap samples for permutation-based feature importance. Alternatively, a list of permutation indices can be passed to B, where each element is a vector of indices for permuting features.

return_preds

Logical indicating whether to return the predictions for each permutation. If TRUE, the function returns a list of predictions for each permutation. If FALSE, it returns the computed feature importance scores.

Value

If return_preds is FALSE, a tibble with two columns:

var: The name of the feature.
importance: The computed feature importance score. If return_preds is TRUE, a list where each element corresponds to a feature group and contains a list of predictions for each permutation.

Use pretty css style

Description

Use pretty css style

Usage

use_pretty_style()

Add vertical space

Description

Add vertical space

Usage

vspace(size = "3px")

Arguments

size

Size of vertical space.

Package {nerfplus}

Add border class

Description

Usage

Arguments

Add spinner when loading

Description

Usage

Arguments

Examples

Add a tooltip to an element

Description

Usage

Arguments

Value

Add a tooltip icon to a label

Description

Usage

Arguments

Value

Postprocessing helper functions after fitting the RF in NeRF+ models

Description

Usage

Arguments

Value

Wrapper around prettyCheckbox()

Description

Usage

Arguments

Wrapper around prettyCheckboxGroup()

Description

Usage

Arguments

Add css styling

Description

Usage

Arguments

Display inline block

Description

Usage

Arguments

Dummy code categorical features

Description

Usage

Arguments

Value

Example dataset for NeRF+ demonstration

Description

Usage

Format

example_data

File input module - UI

Description

Usage

Wrapper to fit various network embedding methods

Description

Usage

Arguments

Value

Examples

Compute feature importances for a NeRF+ model

Description

Usage

Arguments

Value

Examples

Extract all root-to-leaf paths in a forest.

Description

Usage

Arguments

Value

Get html snippet for built-in icons.

Description

Usage

Arguments

Value

Return custom icons

Description

Usage

Arguments

Wrapper around `prettyCheckbox()`

Wrapper around `prettyCheckboxGroup()`

`example_data`

Wrapper around `materialSwitch()`