Package {MuTATE}

Title:	Multi-Target Automated Tree Engine (MuTATE)
Version:	0.1.0
Description:	Recursively partitions datasets on binary splits across multiple targets having different dependent variable types, including categorical, continuous, count, and survival outcomes. This overcomes single-target limitations of traditional decision trees while retaining model interpretability. See Ayton and Trevino (2023) <doi:10.1093/bioinformatics/btad507> and Ayton et al. (2025) <doi:10.1038/s44401-025-00025-4> for details.
License:	GPL (≥ 3)
URL:	https://github.com/SarahAyton/MuTATE
BugReports:	https://github.com/SarahAyton/MuTATE/issues
Encoding:	UTF-8
Language:	en-US
Depends:	R (≥ 3.5)
Imports:	reshape2, matrixStats, survival, stringr, irr, Metrics, plotrix, scales, stats, caret, dplyr, igraph, ggraph, grDevices
Suggests:	testthat (≥ 3.0.0), knitr, rmarkdown
Config/testthat/edition:	3
Config/roxygen2/version:	8.0.0
LazyData:	true
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2026-08-20 03:06:13 UTC; sarahayton
Author:	Sarah Ayton [aut, cre, cph]
Maintainer:	Sarah Ayton <sarahgabrielleayton@gmail.com>
Repository:	CRAN
Date/Publication:	2026-08-21 15:40:09 UTC

CV_Tune: Cross-Validated Hyperparameter Tuning for MTPart Models

Description

This function performs hyperparameter tuning for MTPart models using k-fold cross-validation.

Usage

CV_Tune(features, outcomes, outcome_defs, data,
        continuous, quantseq, wt, reuse, kfolds, Y, seedno,
        drange, noderange, splitmin_div, method, alpharange,
        igrange, psplitrange, pdepthrange, cp_val)

Arguments

Value

A data frame containing the results of hyperparameter tuning for the MTPart model.

Examples

data(mutate_example)
features <- c("age", "sex", "biomarker")
outcomes <- c("response", "tumor_size", "ae_count", "OS_definition_time_status")
outcome_defs <- c("Cat", "Cont", "Count", "Surv")

# A minimal single-point grid, just for illustration - a real tuning run
# would search over wider ranges for drange/noderange/method/etc.
cv_results <- CV_Tune(features, outcomes, outcome_defs, mutate_example,
                       kfolds = 2, Y = "response",
                       drange = 2, noderange = 30, splitmin_div = 2,
                       method = "avgIG", alpharange = 0.05, igrange = 0.95,
                       psplitrange = 1, pdepthrange = 1, cp_val = 0)

Evaluate the performance of binary classifiers

Description

A function that evaluates the performance of binary classifiers based on data split criteria

Usage

CVsplitEval(splitvar, X, targets, data)

Arguments

Details

The function takes four inputs - splitvar, X, targets and data - and outputs a list with measures of the performance of binary classifiers. It first splits the data into two groups based on the specified split criteria, and then fits binary classifiers to the resulting data. The performance of the classifiers is then evaluated using various measures, such as accuracy and kappa, and is stored in the output list.

The function first splits the data into two groups based on the split criteria specified in splitvar. The binary classifiers are then fit to the resulting data, and their performance is evaluated using various measures such as accuracy, kappa, and root mean squared error. The results are stored in a list and returned as the output of the function.

Note that the function uses the glm function in R to fit the binary classifiers, and the accuracy, kappa, and root mean squared error are calculated using the accuracy, kappa2, and rmse functions, respectively.

Value

A list with the performance metrics for each target variable

See Also

Other relevant R functions include glm, accuracy, kappa2, and rmse.

Examples

data(mutate_example)
features <- c("age", "sex", "biomarker")
outcomes <- c("response", "tumor_size", "ae_count", "OS_definition_time_status")
outcome_defs <- c("Cat", "Cont", "Count", "Surv")
targets <- list(Definitions = outcome_defs, Z = mutate_example[, outcomes])

result <- CVsplitEval("age < 60", mutate_example[, features], targets, mutate_example)

Construct multi-target decision trees

Description

Evaluates multiple outcome variables of different types for a set of features.

Usage

MTPart(
  features,
  outcomes,
  outcome_defs,
  data,
  continuous = "quantile",
  quantseq = seq(0, 1, 0.25),
  wt = NULL,
  evalmethod = "avgIG",
  alpha = 0.05,
  IGcutoff = 0.95,
  depth = 4,
  nodesize = 20,
  cp = -1,
  reuse = FALSE,
  parallelpart = FALSE,
  parallelsplit = NA,
  paralleldepth = NA,
  splitmin = floor(nodesize/2)
)

Arguments

Value

A list with two elements:

• partitions: a data frame of parent/child node ID relationships describing the tree structure.

• tree_nodes: a list of per-node details (split variable/threshold, sample size, target summaries, error metrics).

Pass this object to MTTest to score new data, MTPrune to prune it, MTPartSummary or MTSummary to summarize it, or PlotTree to visualize it.

Examples

data(mutate_example)
features <- c("age", "sex", "biomarker")
outcomes <- c("response", "tumor_size", "ae_count", "OS_definition_time_status")
outcome_defs <- c("Cat", "Cont", "Count", "Surv")

# A 150-row subset keeps this example fast; MTPart's split search scales
# with the number of split candidates evaluated per node.
tree <- MTPart(features, outcomes, outcome_defs, mutate_example[1:150, ],
               depth = 2, nodesize = 30)
str(tree$partitions)

MTPartSummary Function

Description

Extracts summary statistics from a decision tree.

Usage

MTPartSummary(tree)

Arguments

Value

A matrix containing summary statistics including the number of splits, number of leaves, complexity parameter (CP), average relative error, total relative error, cross-validated error (Xerror), standard deviation of cross-validated error (Xstd), and evaluation metric (eval).

Examples

data(mutate_example)
features <- c("age", "sex", "biomarker")
outcomes <- c("response", "tumor_size", "ae_count", "OS_definition_time_status")
outcome_defs <- c("Cat", "Cont", "Count", "Surv")

tree <- MTPart(features, outcomes, outcome_defs, mutate_example[1:150, ],
               depth = 2, nodesize = 30)
summ <- MTPartSummary(tree)
summ$summary_table

MTPrune: Prune a Decision Tree Using Minimal Cost-Complexity Pruning

Description

Prune a MTPart decision tree object using minimal cost-complexity pruning based on the specified complexity parameter (CP) value.

Usage

MTPrune(tree, cp = 0.02)

Arguments

Value

A list with two elements:

• partitions: A data frame representing the pruned parent-child relationships and tree nodes.

• tree_nodes: A list of pruned decision tree objects, one for each node in the original tree.

Examples

data(mutate_example)
features <- c("age", "sex", "biomarker")
outcomes <- c("response", "tumor_size", "ae_count", "OS_definition_time_status")
outcome_defs <- c("Cat", "Cont", "Count", "Surv")

tree <- MTPart(features, outcomes, outcome_defs, mutate_example[1:150, ],
               depth = 2, nodesize = 30)
pruned <- MTPrune(tree, cp = 0.02)

Summarize multiple outcome variables

Description

This function takes in a data frame of outcomes and a target table with definitions for each target, and outputs summary statistics for each target. It currently supports continuous, categorical, survival, and count outcome variable types.

Usage

MTSummary(targets, data)

Arguments

Details

The MTSummary() function computes a summary of the outcomes in a dataset for multiple types of variables, including categorical, survival and count variables. The targets argument is a list containing a vector of outcome definitions and a matrix or data frame of outcomes. The data argument is a matrix or data frame with the data to be summarized.

For continuous targets, the function computes the mean, median, inter-quartile range, and MSE.

For categorical targets, the function computes the counts and proportions of each category, the most frequent category and its proportion, and the expected loss (i.e., proportion of observations that do not belong to the most frequent category).

For survival targets, the function computes the number of missing values, the number of events, the estimated rate of the event, and the deviance.

For count targets, the function computes the number of missing values, the total count, the estimated rate of the count, and the deviance.

Value

A list of lists with each element corresponding to an outcome in targets.

Examples

data(mutate_example)
outcomes <- c("response", "tumor_size", "ae_count", "OS_definition_time_status")
outcome_defs <- c("Cat", "Cont", "Count", "Surv")
targets <- list(Definitions = outcome_defs, Z = mutate_example[, outcomes])
summ <- MTSummary(targets, mutate_example)

MTTest: Test Multi-Target Tree

Description

A function to perform tree-based evaluation on test data using a trained tree model.

Usage

MTTest(tree, features, outcomes, outcome_defs, data_test, wt = NULL)

Arguments

Value

A list of evaluation results for the test data.

Examples

data(mutate_example)
features <- c("age", "sex", "biomarker")
outcomes <- c("response", "tumor_size", "ae_count", "OS_definition_time_status")
outcome_defs <- c("Cat", "Cont", "Count", "Surv")

train <- mutate_example[1:150, ]
tree <- MTPart(features, outcomes, outcome_defs, train,
               depth = 2, nodesize = 30)
test_result <- MTTest(tree, features, outcomes, outcome_defs, train)

Evaluate features across multiple outcomes and outcome types

Description

Evaluates multiple outcome variables of different types for a set of features. MultiEval evaluates multiple outcomes of varying types across all features. Cat_Eval performs evaluation of a categorical outcome across all features. Cont_Eval performs evaluation of a continuous outcome across all features. Count_Eval performs evaluation of an event rate or count outcome across all features. Surv_Eval performs evaluation of a time-to-event or survival outcome across all features

Usage

MultiEval(X, Ztype, data, continuous = "quantile",
          quantseq = seq(0,1,0.05), wt=NULL,
          evalmethod = "avgIG", alpha = 0.05,
          IGcutoff = 0.95, splitmin)

Cat_Eval(X, m, Z, k, data, continuous,
         quantseq = seq(0,1,0.05), splitmin=10)

Cont_Eval(X, m, Z, k, data, continuous,
          quantseq = seq(0,1,0.05), splitmin=10)

Count_Eval(X, m, Z, k, data, continuous,
           quantseq = seq(0,1,0.05), splitmin=10)

Surv_Eval(X, m, Z, k, data, continuous,
          quantseq = seq(0,1,0.05), splitmin=10)

Arguments

Details

The following function requires inputs including all features to be evaluated (X), which specific feature to evaluate (m), all outcomes being evaluated (Z), the specific outcome to evaluate (k), and the data (data). In addition, there are options for the user to specify how to handle partition evaluation of continuous features, in which all potential split candidates may be examined ("all") or split candidates are derived from quantiles ("quantile"); the option quantseq takes a user specified sequence ranging from 0 to 1 from which quantiles may be specified (ex: seq(0,1,0.05)). If continuous and quantseq are not manually specified the function will default to the "all" setting for continuous variables with fewer than 100 unique values. If there are more than 100 unique values, the function will use the "quantile" option with the default setting of seq(0,1,0.05).

The function outputs a matrix including information about the outcome (Zk), outcome variable type (Ztype), the feature (Xm), feature type (Xtype), the split threshold being evaluated (Split), evaluation method (Eval), and the entropy of a partition using that split threshold (SplitEntropy), information gain relative to the root node (Inf_Gain) and the proportion of information gain (Inf_GainProp), the significance of association between the split threshold and outcome (P_Value), relative ranking of split thresholds based on how much their respective partitions reduced entropy (Rank), and the standard normalized proportion of information gain associated with each threshold.

All evaluation functions operate internally within the multi-target evaluation function in which all outcomes and all features are assessed at a node. Therefore, m and k options are specified by a loop from the user supplied inputs: X, Z, and data. Again, continuous and quantseq are optional arguments initialized by the user.

Value

The MultiEval function returns a vector including of the evaluation metrics for each possible split of each feature in the dataset.

Examples

data(mutate_example)
features <- c("age", "sex", "biomarker")
outcomes <- c("response", "tumor_size", "ae_count", "OS_definition_time_status")
outcome_defs <- c("Cat", "Cont", "Count", "Surv")
Ztype <- list(Definitions = outcome_defs, Z = mutate_example[, outcomes])

eval_result <- MultiEval(X = mutate_example[, features], Ztype = Ztype,
                          data = mutate_example)

# Single-feature/single-outcome evaluators used internally by MultiEval:
Cat_Eval(X = mutate_example[, features], m = 1,
         Z = mutate_example[, outcomes], k = 1,
         data = mutate_example, continuous = "quantile")

PlotTree: Plot Decision Tree

Description

Plot a multi-target decision tree.

Usage

PlotTree(tree)

Arguments

Value

A plot of the multi-target decision tree (invisible; called for its plotting side effect).

Examples

data(mutate_example)
features <- c("age", "sex", "biomarker")
outcomes <- c("response", "tumor_size", "ae_count", "OS_definition_time_status")
outcome_defs <- c("Cat", "Cont", "Count", "Surv")

tree <- MTPart(features, outcomes, outcome_defs, mutate_example[1:150, ],
               depth = 2, nodesize = 30)
PlotTree(tree)

Prepare data for splitting in a decision tree

Description

SplitPrep() is a function that prepares data frames for use in tree-based models by identifying and removing candidate predictor variables that are unsuitable for splitting at a given node. This function takes in three data frames, Xdf, df, and data_splt and a character string parentsplit. It returns a list of two data frames: splitX_df, which contains the predictor variables that can be used for splitting at a given node, and split_data_df, which contains the response variables and any other variables that should be included in the data frame for further analysis.

Usage

SplitPrep(Xdf, df, data_splt, parentsplit)

Arguments

Details

SplitPrep() takes in two data frames, one containing the predictor variables and another containing the response variable. It identifies which predictor variables to use for splitting in the decision tree and returns a list containing two data frames: the modified predictor variable data frame and the modified response variable data frame.

The function first drops any unused factor levels in both input data frames (Xdf and df) using the droplevels() function. It then loops through the predictor variables in Xdf to determine which ones should be kept for splitting at the current node.

For each predictor variable, the function first checks if it was used for splitting at the parent node (identified by the parentsplit argument). If so, it is added to a list of variables to drop (droplist).

If the predictor variable is categorical (i.e., a factor variable), the function checks if it has less than 2 levels or a prevalence of less than 5% in the current node. If either of these conditions is true, the variable is added to droplist.

If the predictor variable is continuous, the function checks if it has only one observed value. If so, it is added to droplist.

Finally, if droplist exists, the function removes the corresponding columns from splitX_df and renames the remaining columns to match the original column names. The function then returns a list containing splitX_df and split_data_df.

This function is used to pre-process data before fitting tree-based models to ensure that only suitable predictor variables are used for splitting.

Value

A list containing two data frames: the modified predictor variable data frame and the modified response variable data frame.

Examples

data(mutate_example)
features <- c("age", "sex", "biomarker")
prep <- SplitPrep(Xdf = mutate_example[, features], df = mutate_example,
                   data_splt = mutate_example, parentsplit = "skip")

Synthetic example dataset for MuTATE

Description

A small simulated dataset used in function examples and tests. It is purely illustrative (not derived from real patient data) and is designed to exercise all four outcome types supported by MTPart: categorical, continuous, count, and survival.

Usage

mutate_example

Format

A data frame with 200 rows and 9 variables:

age

Continuous feature: simulated patient age.

sex

Categorical feature: "F" or "M".

biomarker

Continuous feature: simulated biomarker level.

response

Categorical outcome: "responder" or "non_responder".

tumor_size

Continuous outcome: simulated tumor size.

ae_count

Count outcome: simulated adverse event count.

time

Survival outcome: time-to-event.

status

Survival outcome: event indicator (1 = event, 0 = censored).

OS_definition_time_status

Placeholder column required by MTPart's survival-outcome naming convention: the outcome name passed via outcomes must itself be a column in data, and its 3rd and 4th underscore-separated tokens (time, status) must match the actual time/event column names.

Examples

data(mutate_example)
head(mutate_example)