Type:	Package
Title:	Guarded Resampling Workflows for Safe and Automated Machine Learning in R
Version:	0.7.7
Description:	Provides a guarded resampling workflow for training and evaluating machine-learning models. When the guarded resampling path is used, preprocessing and model fitting are re-estimated within each resampling split to reduce leakage risk. Supports multiple resampling schemes, integrates with established engines in the 'tidymodels' ecosystem, and aims to improve evaluation reliability by coordinating preprocessing, fitting, and evaluation within supported workflows. Offers a lightweight AutoML-style workflow by automating model training, resampling, and tuning across multiple algorithms, while keeping evaluation design explicit and user-controlled.
Encoding:	UTF-8
License:	MIT + file LICENSE
URL:	https://selcukorkmaz.github.io/fastml-tutorial/, https://github.com/selcukorkmaz/fastml
BugReports:	https://github.com/selcukorkmaz/fastml/issues
Depends:	R (≥ 4.1.0)
Imports:	stats, recipes, dplyr, ggplot2, reshape2, rsample, parsnip, tune, workflows, yardstick, tibble, rlang, dials, RColorBrewer, baguette, discrim, doFuture, foreach, finetune, future, plsmod, probably, viridisLite, DALEX, magrittr, pROC, janitor, stringr, broom, tidyr, purrr, survival, flexsurv, rstpm2, iml, lime, survRM2, iBreakDown, xgboost, pdp, modelStudio, fairmodels
Suggests:	testthat (≥ 3.0.0), withr, C50, ranger, aorsf, censored, crayon, kernlab, klaR, kknn, keras, lightgbm, rstanarm, mixOmics, patchwork, GGally, glmnet, themis, DT, UpSetR, VIM, dbscan, ggpubr, gridExtra, htmlwidgets, kableExtra, moments, naniar, plotly, scales, skimr, sparsediscrim, knitr, rmarkdown, pec
RoxygenNote:	7.3.3
Config/testthat/edition:	3
NeedsCompilation:	no
Packaged:	2026-01-27 22:12:54 UTC; selcuk
Author:	Selcuk Korkmaz [aut, cre], Dincer Goksuluk [aut], Eda Karaismailoglu [aut]
Maintainer:	Selcuk Korkmaz <selcukorkmaz@gmail.com>
Repository:	CRAN
Date/Publication:	2026-01-27 22:50:18 UTC

Environment for Tracking Warned Defaults

Description

Internal environment to track which default warnings have been shown in the current session to avoid duplicate warnings.

Usage

.fastml_warned_defaults

Format

An object of class environment of length 0.

Align Survival Curve to Evaluation Times

Description

Aligns a survival curve (defined by time points and survival probabilities) to a new set of evaluation times using constant interpolation (last value carried forward). Ensures S(0) = 1 and monotonicity.

Usage

align_survival_curve(curve_times, curve_surv, eval_times)

Arguments

Value

A numeric vector of survival probabilities at eval_times.

Assign Risk Groups

Description

Dichotomizes a continuous risk vector into "low" and "high" risk groups based on the median.

Usage

assign_risk_group(risk_vec)

Arguments

Value

A character vector of "low", "high", or NA.

Get Available Methods

Description

Returns a character vector of algorithm names available for classification, regression or survival tasks.

Usage

availableMethods(type = c("classification", "regression", "survival"), ...)

Arguments

Details

Depending on the specified type, the function returns a different set of algorithm names:

• For "classification", it returns algorithms such as "logistic_reg", "multinom_reg", "decision_tree", "C5_rules", "rand_forest", "xgboost", "lightgbm", "svm_linear", "svm_rbf", "nearest_neighbor", "naive_Bayes", "mlp", "discrim_linear", "discrim_quad", and "bag_tree".

• For "regression", it returns algorithms such as "linear_reg", "ridge_reg", "lasso_reg", "elastic_net", "decision_tree", "rand_forest", "xgboost", "lightgbm", "svm_linear", "svm_rbf", "nearest_neighbor", "mlp", "pls", and "bayes_glm".

• For "survival", it returns algorithms such as "rand_forest", "cox_ph", "penalized_cox", "stratified_cox", "time_varying_cox", "survreg", "royston_parmar", "parametric_surv", "piecewise_exp", and "xgboost".

Value

A character vector containing the names of the available algorithms for the specified task type.

Build Survival Matrix from survfit Object

Description

Extracts survival probabilities from a survfit object and aligns them to a common set of evaluation times, creating a matrix.

Usage

build_survfit_matrix(fit_obj, eval_times, n_obs)

Arguments

Value

A matrix (rows=subjects, cols=eval_times) of survival probabilities, or NULL on failure.

Clamp Values to [0, 1]

Description

Truncates a numeric vector so all values lie within the [0, 1] interval.

Usage

clamp01(x)

Arguments

Value

The clamped numeric vector.

Compare fastml and parsnip defaults

Description

Compares the default engine and parameter choices between fastml and parsnip for a given algorithm.

Usage

compare_defaults(algo, task, fastml_engine, fastml_params = NULL)

Arguments

Value

A list with components:

engine_differs

Logical indicating if engines differ.

fastml_engine

The fastml default engine.

parsnip_engine

The parsnip default engine.

param_differences

Named list of parameters that differ.

Compute Integrated Brier Score and Curve

Description

Calculates the Brier score at specified evaluation times and the Integrated Brier Score (IBS) up to \tau, using IPCW to handle censoring.

Usage

compute_ibrier(
  eval_times,
  surv_mat,
  time_vec,
  status_vec,
  tau,
  censor_eval_fn,
  normalize_by = c("non_missing", "n"),
  include_zero = TRUE
)

Arguments

Value

A list with ibs (the scalar IBS value) and curve (a numeric vector of Brier scores at eval_times).

Compute Difference in Restricted Mean Survival Time (RMST)

Description

Calculates the difference in RMST between "low" and "high" risk groups up to a time horizon \tau. Groups are defined by median-splitting the risk_vec.

Usage

compute_rmst_difference(
  time_vec,
  status_vec,
  risk_vec,
  tau,
  surv_mat = NULL,
  eval_times_full = NULL,
  model_type = "other"
)

Arguments

Value

The RMST difference (RMST_low - RMST_high), or NA_real_.

Compute Survival Matrix from survreg Model

Description

Generates a matrix of survival probabilities (rows=subjects, cols=times) from a fitted survreg model for new data.

Usage

compute_survreg_matrix(fit_obj, new_data, eval_times)

Arguments

Value

A matrix of survival probabilities, or NULL on failure.

Compute Tau Limit (t_max)

Description

Finds the latest time point t_{max} such that at least a certain proportion of subjects remain at risk.

Usage

compute_tau_limit(times, threshold)

Arguments

Value

The computed t_{max} value, or NA_real_ if no valid times are provided.

Compute Uno's C-index (Time-Dependent AUC)

Description

Calculates Uno's C-index (a time-dependent AUC measure) for survival data, weighted by the inverse probability of censoring (IPCW).

Usage

compute_uno_c_index(
  train_time,
  train_status,
  test_time,
  test_status,
  risk_vec,
  tau,
  censor_eval_fn
)

Arguments

Value

The computed Uno's C-index, or NA_real_ on failure.

Convert Various Prediction Formats to Survival Matrix

Description

Attempts to convert various survival prediction formats (e.g., list of data frames from predict.model_fit with type "survival", matrices) into a standardized [n_obs, n_eval_times] matrix.

Usage

convert_survival_predictions(pred_obj, eval_times, n_obs)

Arguments

Value

A standardized matrix of survival probabilities, or NULL on failure.

Generate counterfactual explanations for a fastml model

Description

Uses DALEX ceteris-paribus profiles ('predict_profile') to compute counterfactual-style what-if explanations for a given observation.

Usage

counterfactual_explain(
  object,
  observation,
  variables = NULL,
  data = c("train", "test"),
  positive_class = NULL,
  event_class = NULL,
  label_levels = NULL,
  ...
)

Arguments

Value

A list (returned invisibly) containing the DALEX profile, filtered lines/points when 'positive_class' is supplied, and the plotted object if rendering succeeds.

Create Censoring Distribution Evaluator

Description

Creates a function to evaluate the survival function of the censoring distribution, G(t) = P(C > t), using a Kaplan-Meier estimator.

Usage

create_censor_eval(time_vec, status_vec)

Arguments

Value

A function that takes a numeric vector of times and returns the estimated censoring survival probabilities G(t) at those times.

Defaults Registry for Engine and Parameter Transparency

Description

Functions to track, compare, and warn about differences between fastml defaults and parsnip defaults, providing users with full transparency and control over model configuration.

Determine rounding digits for time horizons

Description

Computes a sensible number of decimal digits to round time horizons based on the minimal positive separation between unique finite times.

Usage

determine_round_digits(times)

Arguments

Details

Uses the smallest strictly positive difference among sorted unique finite times, then returns ceiling(-log10(min_diff)) truncated to [0, 6].

Value

Integer number of digits between 0 and 6.

Examples

# Not run: determine_round_digits(c(0.1, 0.12, 0.125))
NULL

Estimate Tuning Time

Description

Provides a rough estimate of tuning time based on the configuration.

Usage

estimate_tuning_time(
  n_params,
  n_folds = 10,
  n_rows = 1000,
  complexity = "balanced",
  tuning_strategy = "grid",
  base_fit_time = 1
)

Arguments

Value

A list with estimated total time and breakdown.

Compute Accumulated Local Effects (ALE) for a fastml model

Description

Uses the 'iml' package to calculate ALE for the specified feature.

Usage

explain_ale(object, feature, data = c("train", "test"), ...)

Arguments

Value

An 'iml' object containing ALE results.

Examples

## Not run: 
data(iris)
iris <- iris[iris$Species != "setosa", ]
iris$Species <- factor(iris$Species)
model <- fastml(data = iris, label = "Species")
explain_ale(model, feature = "Sepal.Length")

## End(Not run)

Generate DALEX explanations for a fastml model

Description

Creates a DALEX explainer and computes permutation based variable importance, partial dependence (model profiles) and Shapley values.

Usage

explain_dalex(
  object,
  data = c("train", "test"),
  features = NULL,
  grid_size = 20,
  shap_sample = 5,
  vi_iterations = 10,
  seed = 123,
  loss_function = NULL
)

Arguments

Value

Invisibly returns a list with variable importance, optional model profiles and SHAP values.

Generate LIME explanations for a fastml model

Description

Creates a 'lime' explainer using processed (encoded, scaled) data and returns feature explanations for new observations. The new observation is automatically preprocessed using the same recipe to ensure alignment with the explainer background.

Usage

explain_lime(
  object,
  new_observation,
  data = c("train", "test"),
  n_features = 5,
  n_labels = 1,
  ...
)

Arguments

Value

An object produced by 'lime::explain'.

Examples

## Not run: 
data(iris)
iris <- iris[iris$Species != "setosa", ]
iris$Species <- factor(iris$Species)
model <- fastml(data = iris, label = "Species")
explain_lime(model, new_observation = iris[1, ])

## End(Not run)

Analyze Feature Importance Stability Across Cross-Validation Folds

Description

Computes feature importance for each fold model and aggregates results to assess the stability of feature importance rankings across resamples. This helps identify features that are consistently important vs those whose importance varies across different data subsets.

Usage

explain_stability(
  object,
  model_name = NULL,
  vi_iterations = 10,
  seed = 123,
  plot = TRUE,
  conf_level = 0.95
)

Arguments

Details

This function requires that the fastml model was trained with store_fold_models = TRUE, which stores the models fitted on each cross-validation fold. Without stored fold models, only the final best model is available, and cross-fold stability analysis is not possible.

The stability analysis computes permutation-based variable importance for each fold's model using DALEX, then aggregates across folds to show:

• Mean importance and standard deviation

• Confidence intervals for importance

• Rank stability (how consistently features rank across folds)

Features with high mean importance but also high variance may be important for some data subsets but not others, suggesting potential instability in the model's reliance on those features.

Value

A list with class "fastml_stability" containing:

importance_summary

Data frame with aggregated feature importance (mean, sd, se, lower/upper CI) across folds.

fold_importance

List of per-fold variable importance results.

rank_stability

Data frame showing how feature ranks vary across folds.

n_folds

Number of folds analyzed.

model_name

Name of the model analyzed.

Examples

# Train model with fold models stored
model <- fastml(
  data = iris,
  label = "Species",
  algorithms = "rand_forest",
  store_fold_models = TRUE
)

# Analyze stability
stability <- explain_stability(model)
print(stability)

Extract survreg Linear Predictor and Scale

Description

Computes the linear predictor (lp) and scale parameter(s) for new data from a fitted survreg model.

Usage

extract_survreg_components(fit_obj, new_data)

Arguments

Value

A list with elements lp (numeric vector) and scale (numeric vector), or NULL on failure.

Explain a fastml model using various techniques

Description

Provides model explainability across several backends. With method = "dalex" it:

• Creates a DALEX explainer from the trained model.

• Computes permutation-based variable importance with vi_iterations permutations and displays the table and plot.

• Computes partial dependence-like model profiles when features are supplied.

• Computes Shapley values (SHAP) for shap_sample training rows, displays the SHAP table, and plots a canonical SHAP summary (beeswarm) plot colored by raw feature values and ordered by \text{mean}(\vert \text{SHAP value} \vert) per feature. For classification, separate panels per class are shown.

Usage

fastexplain(
  object,
  method = "dalex",
  data = c("train", "test"),
  features = NULL,
  n_features = 5,
  variables = NULL,
  observation = NULL,
  grid_size = 20,
  shap_sample = 5,
  vi_iterations = 10,
  seed = 123,
  loss_function = NULL,
  protected = NULL,
  ...
)

Arguments

Details

• Data source selection: By default, explanations are computed on training data (data = "train"), which reflects in-sample model behavior and may be influenced by overfitting. Set data = "test" to compute explanations on held-out test data for a more realistic assessment of how the model uses features on unseen data.

• Method dispatch: method can route to LIME, ICE, ALE, surrogate tree, interaction strengths, DALEX/modelStudio dashboards, fairness diagnostics, iBreakDown contributions, or counterfactual search.

• Variable importance controls: Use vi_iterations to tune permutation stability and loss_function to override the default DALEX loss (cross-entropy for classification, RMSE for regression).

• Fairness and breakdown support: Provide protected for method = "fairness" and an observation for method = "breakdown" or method = "counterfactual". Observations are aligned to the explainer data before scoring.

Value

For DALEX-based methods, prints variable importance, model profiles, and SHAP summaries. Other methods return their respective explainer objects (e.g., LIME explanations, ALE plot, surrogate tree, interaction strengths, modelStudio dashboard, fairmodels object, breakdown object, or counterfactual results), usually invisibly after plotting or printing.

Note

By default, explanations use training data. For unbiased feature importance estimates that better reflect model generalization, use data = "test" to compute explanations on held-out test data.

Lightweight exploratory helper

Description

'fastexplore()' is an optional, lightweight exploratory data analysis (EDA) helper. It returns summary tables and plot objects; it only writes to disk or renders a report when you explicitly request it via 'save_results' or 'render_report'.

Usage

fastexplore(
  data,
  label = NULL,
  visualize = c("histogram", "boxplot", "barplot", "heatmap", "scatterplot"),
  save_results = FALSE,
  render_report = FALSE,
  output_dir = NULL,
  sample_size = NULL,
  interactive = FALSE,
  corr_threshold = 0.9,
  auto_convert_numeric = TRUE,
  visualize_missing = TRUE,
  imputation_suggestions = FALSE,
  report_duplicate_details = TRUE,
  detect_near_duplicates = FALSE,
  auto_convert_dates = FALSE,
  feature_engineering = FALSE,
  outlier_method = c("iqr", "zscore", "dbscan", "lof"),
  run_distribution_checks = TRUE,
  normality_tests = c("shapiro"),
  pairwise_matrix = TRUE,
  max_scatter_cols = 5,
  grouped_plots = TRUE,
  use_upset_missing = TRUE
)

Arguments

Details

This helper is intentionally decoupled from the core modeling workflow. Most of its heavy dependencies are treated as optional and loaded via 'requireNamespace()' when requested features are used.

Value

A list of summaries (tables/tibbles) and plot objects (ggplot/plotly), plus any saved file paths when 'save_results'/'render_report' are enabled.

Fast Machine Learning Function

Description

Trains and evaluates multiple classification or regression models automatically detecting the task based on the target variable type.

Usage

fastml(
  data = NULL,
  train_data = NULL,
  test_data = NULL,
  label,
  algorithms = "all",
  task = "auto",
  test_size = 0.2,
  resampling_method = if (identical(task, "survival")) "none" else "cv",
  folds = ifelse(grepl("cv", resampling_method), 10, 25),
  repeats = NULL,
  group_cols = NULL,
  block_col = NULL,
  block_size = NULL,
  initial_window = NULL,
  assess_window = NULL,
  skip = 0,
  outer_folds = NULL,
  event_class = "first",
  exclude = NULL,
  recipe = NULL,
  tune_params = NULL,
  engine_params = list(),
  metric = NULL,
  class_threshold = "auto",
  algorithm_engines = NULL,
  use_parsnip_defaults = FALSE,
  warn_engine_defaults = TRUE,
  n_cores = 1,
  stratify = TRUE,
  impute_method = "error",
  encode_categoricals = TRUE,
  scaling_methods = c("center", "scale"),
  balance_method = "none",
  resamples = NULL,
  summaryFunction = NULL,
  use_default_tuning = FALSE,
  tuning_strategy = "grid",
  tuning_iterations = 10,
  tuning_complexity = "balanced",
  grid_levels = NULL,
  early_stopping = FALSE,
  adaptive = FALSE,
  learning_curve = FALSE,
  seed = 123,
  verbose = FALSE,
  eval_times = NULL,
  survival_metric_convention = "fastml",
  bootstrap_ci = TRUE,
  bootstrap_samples = 500,
  bootstrap_seed = NULL,
  at_risk_threshold = 0.1,
  audit_mode = FALSE,
  multiclass_auc = "macro",
  store_fold_models = FALSE
)

Arguments

Details

Fast Machine Learning Function

Trains and evaluates multiple classification or regression models. The function automatically detects the task based on the target variable type and can perform advanced hyperparameter tuning using various tuning strategies.

Model selection is based exclusively on resampling metrics (cross-validation or nested CV). The holdout split is reserved for final performance estimation and is never used to choose the best model, mirroring tidymodels::last_fit() semantics.

For multiclass ROC AUC, fastml defaults to macro averaging (tidymodels). Macro treats each class equally, while macro_weighted weights by class prevalence and can change model rankings on imbalanced data. Keep the same setting when comparing runs.

## Tuning: Speed vs Robustness Trade-offs

Hyperparameter tuning involves a fundamental trade-off between computational cost and the likelihood of finding optimal hyperparameters. fastml provides presets via tuning_complexity to make this trade-off explicit:

*Grid size shown for 5 tunable parameters (levels^5)

**Recommendations:**

• Start with tuning_complexity = "quick" during development

• Use "balanced" (default) for most production pipelines

• Switch to "thorough" for final model selection

• Consider tuning_strategy = "bayes" instead of exhaustive grid search

• Enable adaptive = TRUE for early stopping of poor configurations

Use print_tuning_presets to see all presets and estimate_tuning_time to estimate runtime before starting.

Value

An object of class fastml containing the best model, performance metrics, and other information.

Factor Level Warning

For binary classification, the interpretation of metrics like sensitivity, specificity, and ROC AUC depends on which factor level is treated as the "positive" class (the event of interest). The event_class parameter controls this:

• "first" (default): The first factor level is treated as positive

• "second": The second factor level is treated as positive

Important: Recipe preprocessing steps like step_other() or step_unknown() can modify factor levels, potentially changing which level is "first" or "second". Always verify factor levels after preprocessing.

To ensure consistent behavior, explicitly set factor levels before calling fastml:

# Ensure "positive" is the second level (event_class = "second")
data$outcome <- factor(data$outcome, levels = c("negative", "positive"))

# Or ensure "positive" is the first level (event_class = "first")
data$outcome <- factor(data$outcome, levels = c("positive", "negative"))

Examples

# Example 1: Using the iris dataset for binary classification (excluding 'setosa')
data(iris)
iris <- iris[iris$Species != "setosa", ]  # Binary classification
iris$Species <- factor(iris$Species)

# Define a custom tuning grid for the ranger engine
tune <- list(
  rand_forest = list(
    ranger = list(mtry = c(1, 3))
  )
)

# Train models with custom tuning
model <- fastml(
  data = iris,
  label = "Species",
  algorithms = "rand_forest",
  tune_params = tune,
  use_default_tuning = TRUE
)

# View model summary
summary(model)


  

Evaluate Models Function

Description

Evaluates the trained models on the test data and computes performance metrics.

Usage

fastml_compute_holdout_results(
  models,
  train_data,
  test_data,
  label,
  start_col = NULL,
  time_col = NULL,
  status_col = NULL,
  task,
  metric = NULL,
  event_class,
  class_threshold = "auto",
  eval_times = NULL,
  bootstrap_ci = TRUE,
  bootstrap_samples = 500,
  bootstrap_seed = 1234,
  at_risk_threshold = 0.1,
  survival_metric_convention = "fastml",
  precomputed_predictions = NULL,
  summaryFunction = NULL,
  multiclass_auc = "macro"
)

Arguments

Value

A list with two elements:

performance

A named list of performance metric tibbles for each model.

predictions

A named list of data frames with columns including truth, predictions, and probabilities per model.

Guarded Resampling Utilities

Description

Internal helpers that enforce the Guarded Resampling Principle by fitting preprocessing pipelines independently within each resampling split. These functions are not exported.

Usage

fastml_guard_validate_indices(indices, label)

Arguments

Internal helpers for survival-specific preprocessing

Description

These utilities standardize survival status indicators so that downstream metrics always receive the conventional coding (0 = censored, 1 = event). The functions are intentionally unexported and are used across multiple internal modules. Normalize survival status coding to 0/1 representation

Usage

fastml_normalize_survival_status(status_vec, reference_length = NULL)

Arguments

Details

This helper attempts to coerce a status vector into a numeric format where 0 represents censoring and 1 represents the event indicator. It accepts a variety of common encodings such as 1/2, logical values, factors, or character labels. When the supplied values deviate from the canonical coding, the function records that a recode was performed so callers can communicate this to the user (once).

Value

A list with two elements: 'status', the recoded numeric vector, and 'recoded', a logical flag indicating whether a non-standard encoding was detected.

Internal helper to prepare explainer inputs from a fastml object

Description

Internal helper to prepare explainer inputs from a fastml object

Usage

fastml_prepare_explainer_inputs(object, data = c("train", "test"))

Arguments

Flatten and Rename Models

Description

Flatten and Rename Models

Usage

flatten_and_rename_models(models)

Arguments

Format Default Override Warning Message

Description

Creates a human-readable warning message about default overrides.

Usage

format_default_override_warning(algo, comparison, show_params = TRUE)

Arguments

Value

Character string with the warning message.

Get Best Model Indices by Metric and Group

Description

Get Best Model Indices by Metric and Group

Usage

get_best_model_idx(df, metric, group_cols = c("Model", "Engine"))

Arguments

Get Best Model Names

Description

Extracts and returns the best engine names from a named list of model workflows.

Usage

get_best_model_names(models)

Arguments

Details

For each algorithm, the function extracts the engine names from the model workflows using tune::extract_fit_parsnip. It then chooses "randomForest" if it is available; otherwise, it selects the first non-NA engine. If no engine names can be extracted for an algorithm, NA_character_ is returned.

Value

A named character vector. The names of the vector correspond to the algorithm names, and the values represent the chosen best engine name for that algorithm.

Get Best Workflows

Description

Extracts the best workflows from a nested list of model workflows based on the provided best model names.

Usage

get_best_workflows(models, best_model_name)

Arguments

Get All Default Differences Summary

Description

Returns a summary of all differences between fastml and parsnip defaults for the specified algorithms.

Usage

get_default_differences(algorithms, task = "classification")

Arguments

Value

A data frame summarizing the differences.

Get Default Engine

Description

Returns the default engine corresponding to the specified algorithm.

Usage

get_default_engine(algo, task = NULL)

Arguments

Details

The function uses a switch statement to select the default engine based on the given algorithm. For survival random forests, the function defaults to "aorsf". If the provided algorithm does not have a defined default engine, the function terminates with an error.

Value

A character string containing the default engine name associated with the provided algorithm.

Get Default Parameters for an Algorithm

Description

Returns a list of default tuning parameters for the specified algorithm based on the task type, number of predictors, and engine.

Usage

get_default_params(algo, task, num_predictors = NULL, engine = NULL)

Arguments

Details

The function employs a switch statement to select and return a list of default parameters tailored for the given algorithm, task, and engine. The defaults vary by algorithm and, in some cases, by engine. For example:

• For "rand_forest", if engine is not provided, it defaults to "ranger". The parameters such as mtry, trees, and min_n are computed based on the task and the number of predictors.

• For "C5_rules", the defaults include trees, min_n, and sample_size.

• For "xgboost" and "lightgbm", default values are provided for parameters like tree depth, learning rate, and sample size.

• For "logistic_reg" and "multinom_reg", the function returns defaults for regularization parameters (penalty and mixture) that vary with the specified engine.

• For "decision_tree", the parameters (such as tree_depth, min_n, and cost_complexity) are set based on the engine (e.g., "rpart", "C5.0", "partykit", "spark").

• Other algorithms, including "svm_linear", "svm_rbf", "nearest_neighbor", "naive_Bayes", "mlp", "deep_learning", "elastic_net", "bayes_glm", "pls", "linear_reg", "ridge_reg", and "lasso_reg", have their respective default parameter lists.

Value

A list of default parameter settings for the specified algorithm. If the algorithm is not recognized, the function returns NULL.

Get Default Parameters with Transparency Warnings

Description

Wrapper around get_default_params that optionally warns when fastml's default parameters differ from parsnip/engine defaults.

Usage

get_default_params_with_warnings(
  algo,
  task,
  num_predictors = NULL,
  engine = NULL,
  warn_param_defaults = TRUE,
  verbose = FALSE
)

Arguments

Value

A list of default parameters.

Get Default Tuning Parameters

Description

Returns a list of default tuning parameter ranges for a specified algorithm based on the provided training data, outcome label, and engine.

Usage

get_default_tune_params(algo, train_data, label, engine)

Arguments

Details

The function first determines the number of predictors by removing the outcome variable (specified by label) from train_data. It then uses a switch statement to select a list of default tuning parameter ranges tailored for the specified algorithm and engine. The tuning ranges have been adjusted for efficiency and may include parameters such as mtry, trees, min_n, and others depending on the algorithm.

Value

A list of tuning parameter ranges for the specified algorithm. If no tuning parameters are defined for the given algorithm, the function returns NULL.

Get Engine Names from Model Workflows

Description

Extracts and returns a list of unique engine names from a list of model workflows.

Usage

get_engine_names(models)

Arguments

Details

The function applies tune::extract_fit_parsnip to each model workflow to extract the fitted model object. It then retrieves the engine name from the model specification (spec$engine). If the extraction fails, NA_character_ is returned for that workflow. Finally, the function removes any duplicate engine names using unique.

Value

A list of character vectors. Each vector contains the unique engine names extracted from the corresponding element of models.

Expanded Default Tuning Parameters

Description

Returns expanded tuning parameter ranges that provide better coverage than the minimal defaults. These are used when tuning_complexity is set to "thorough" or "exhaustive".

Usage

get_expanded_tune_params(algo, train_data, label, engine)

Arguments

Value

A list of expanded tuning parameter ranges.

Get Model Engine Names

Description

Extracts and returns a named vector mapping algorithm names to engine names from a nested list of model workflows.

Usage

get_model_engine_names(models)

Arguments

Details

The function iterates over a nested list of model workflows and, for each workflow, attempts to extract the fitted model object using tune::extract_fit_parsnip. If successful, it retrieves the algorithm name from the first element of the class attribute of the model specification and the engine name from the specification. The results are combined into a named vector.

Value

A named character vector where the names correspond to algorithm names (e.g., "rand_forest", "logistic_reg") and the values correspond to the associated engine names (e.g., "ranger", "glm").

Get Parsnip Default Engine for an Algorithm

Description

Returns the default engine that parsnip would use for a given algorithm, allowing comparison with fastml's optimized defaults.

Usage

get_parsnip_default_engine(algo, task = NULL)

Arguments

Details

This function documents parsnip's default engine choices as of tidymodels 1.x. These may change with future parsnip versions.

Value

Character string of the parsnip default engine, or NULL if unknown.

Get Parsnip Default Parameters for an Algorithm

Description

Returns the default parameter values that parsnip would use for a given algorithm and engine combination.

Usage

get_parsnip_default_params(algo, engine = NULL, task = NULL)

Arguments

Details

These defaults are based on parsnip's internal defaults and the underlying engine defaults. They may differ from fastml's optimized defaults which are tuned for better out-of-box performance.

Value

A named list of default parameter values, or NULL if unknown.

Extract Time and Status from Survival Matrix

Description

Helper function to extract "time" and "status" columns from a matrix (like one returned by survival::Surv()), falling back to defaults.

Usage

get_surv_info(surv_matrix_vals, default_time, default_status)

Arguments

Value

A list with elements time and status.

Tuning Complexity Presets

Description

Returns the configuration for a given tuning complexity level, including grid levels, parameter ranges, and expected computational characteristics.

Usage

get_tuning_complexity(
  complexity = c("balanced", "quick", "thorough", "exhaustive")
)

Arguments

Details

## Speed-Robustness Trade-offs

Hyperparameter tuning involves a fundamental trade-off between computational cost and the likelihood of finding optimal hyperparameters:

### Recommendations:

1. **Start with "quick"** during development to iterate fast 2. **Use "balanced"** for most production pipelines 3. **Switch to "thorough"** for final model selection 4. **Consider Bayesian tuning** ('tuning_strategy = "bayes"') for high-dimensional parameter spaces instead of exhaustive grid search 5. **Use adaptive/racing** ('adaptive = TRUE') to early-stop poor configurations

### Computational Scaling:

Grid search scales as O(L^P * F * N) where: - L = number of levels per parameter - P = number of parameters being tuned - F = number of cross-validation folds - N = dataset size

For a model with 5 tunable parameters and 10-fold CV: - quick (L=2): 2^5 * 10 = 320 model fits - balanced (L=3): 3^5 * 10 = 2,430 model fits - thorough (L=5): 5^5 * 10 = 31,250 model fits

Value

A list with components:

grid_levels

Integer number of levels per parameter for grid search.

bayes_iterations

Integer number of iterations for Bayesian tuning.

description

Human-readable description of the complexity level.

speed_estimate

Relative speed estimate (1 = baseline).

robustness_estimate

Relative robustness estimate (1-5 scale).

Examples

# Get configuration for balanced tuning
config <- get_tuning_complexity("balanced")
print(config$grid_levels)  # 3

# See all available presets
print_tuning_presets()

Get Tuning Parameters for Complexity Level

Description

Returns algorithm-specific tuning parameter ranges adjusted for the specified complexity level.

Usage

get_tuning_params_for_complexity(
  algo,
  train_data,
  label,
  engine,
  complexity = "balanced"
)

Arguments

Details

Parameter ranges are scaled based on the complexity level: - quick: Narrower ranges (70 - balanced: Standard ranges (100 - thorough: Wider ranges (130 - exhaustive: Very wide ranges (150

Value

A list of tuning parameter ranges.

Compute feature interaction strengths for a fastml model

Description

Uses the 'iml' package to quantify the strength of feature interactions.

Usage

interaction_strength(object, data = c("train", "test"), ...)

Arguments

Value

An 'iml::Interaction' object.

Examples

## Not run: 
data(iris)
iris <- iris[iris$Species != "setosa", ]
iris$Species <- factor(iris$Species)
model <- fastml(data = iris, label = "Species")
interaction_strength(model)

## End(Not run)

Load Model Function

Description

Loads a trained model object from a file.

Usage

load_model(filepath)

Arguments

Value

An object of class fastml.

Map Brier Curve Values to Specific Horizons

Description

Extracts Brier score values from a pre-computed curve at specific time horizons by finding the closest matching evaluation time.

Usage

map_brier_values(curve, eval_times, horizons)

Arguments

Value

A numeric vector of Brier scores corresponding to horizons.

Plot Methods for fastml Objects

Description

plot.fastml produces visual diagnostics for a trained fastml object.

Usage

## S3 method for class 'fastml'
plot(
  x,
  algorithm = "best",
  type = c("all", "bar", "roc", "calibration", "residual", "learning_curve"),
  ...
)

Arguments

Details

When type = "all", plot.fastml will produce a bar plot of metrics, ROC curves (classification), calibration plot, and residual diagnostics (regression). If you specify a subset of types, only those will be drawn.

Examples

  ## Create a binary classification dataset from iris
  data(iris)
  iris <- iris[iris$Species != "setosa",]
  iris$Species <- factor(iris$Species)

  ## Fit fastml model on binary classification task
  model <- fastml(data = iris, label = "Species", algorithms = c("rand_forest", "svm_rbf"))

  ## 1. Plot all available diagnostics
  plot(model, type = "all")

  ## 2. Bar plot of performance metrics
  plot(model, type = "bar")

  ## 3. ROC curves (only for classification models)
  plot(model, type = "roc")

  ## 4. Calibration plot (requires 'probably' package)
  plot(model, type = "calibration")

  ## 5. ROC curves for specific algorithm(s) only
  plot(model, type = "roc", algorithm = "rand_forest")

  ## 6. Residual diagnostics (only available for regression tasks)
  model <- fastml(data = mtcars, label = "mpg", algorithms = c("linear_reg", "xgboost"))
  plot(model, type = "residual")

Plot method for fastml_stability objects

Description

Plot method for fastml_stability objects

Usage

## S3 method for class 'fastml_stability'
plot(x, top_n = 15, ...)

Arguments

Value

A ggplot object.

Plot ICE curves for a fastml model

Description

Generates Individual Conditional Expectation (ICE) plots for selected features using the 'pdp' package (ggplot2 engine), and returns both the underlying data and the plot object.

Usage

plot_ice(object, features, data = c("train", "test"), target_class = NULL, ...)

Arguments

Value

A list with two elements: 'data' (the ICE data frame) and 'plot' (the ggplot object).

Examples

## Not run: 
data(iris)
iris <- iris[iris$Species != "setosa", ]
iris$Species <- factor(iris$Species)
model <- fastml(data = iris, label = "Species")
plot_ice(model, features = "Sepal.Length")

## End(Not run)

Predict method for fastml objects

Description

Generates predictions from a trained 'fastml' object on new data. Supports both single-model and multi-model workflows, and handles classification and regression tasks with optional post-processing and verbosity.

Usage

## S3 method for class 'fastml'
predict(
  object,
  newdata,
  type = "auto",
  model_name = NULL,
  verbose = FALSE,
  postprocess_fn = NULL,
  eval_time = NULL,
  ...
)

Arguments

Value

A vector of predictions, or a named list of predictions (if multiple models are used). If 'postprocess_fn' is supplied, its output will be returned instead.

Internal predict_model method for parsnip fits

Description

Shim for parsnip model objects so that lime's predict_model generic ignores unused arguments passed via '...'.

Usage

predict_model.model_fit(x, newdata, type, ...)

Predict Risk Scores from a Survival Model

Description

Provides a consistent interface for computing linear predictors (risk scores) across various survival modeling engines, including native fastml models (e.g., Cox proportional hazards, XGBoost Cox) and parsnip/workflow objects.

Usage

predict_risk(fit, newdata, ...)

## S3 method for class 'fastml_native_survival'
predict_risk(fit, newdata, ...)

## S3 method for class 'workflow'
predict_risk(fit, newdata, ...)

## Default S3 method:
predict_risk(fit, newdata, ...)

Arguments

Value

A numeric vector of risk scores, where higher values indicate greater predicted risk.

Predict survival probabilities from a survival model

Description

Predict survival probabilities from a survival model

Usage

predict_survival(fit, newdata, times, ...)

## S3 method for class 'fastml_native_survival'
predict_survival(fit, newdata, times, ...)

## S3 method for class 'workflow'
predict_survival(fit, newdata, times, ...)

## Default S3 method:
predict_survival(fit, newdata, times, ...)

Arguments

Value

A numeric matrix with one row per observation and one column per time.

Print method for fastml_stability objects

Description

Print method for fastml_stability objects

Usage

## S3 method for class 'fastml_stability'
print(x, top_n = 10, ...)

Arguments

Value

The input object invisibly.

Print Default Differences Table

Description

Prints a formatted table showing differences between fastml and parsnip defaults for the specified task type.

Usage

print_default_differences(task = "classification", algorithms = NULL)

Arguments

Value

Invisibly returns the differences data frame.

Print Tuning Presets Summary

Description

Prints a formatted summary of all available tuning complexity presets with their characteristics and recommended use cases.

Usage

print_tuning_presets()

Value

Invisibly returns a data frame with preset information.

Process and Evaluate a Model Workflow

Description

This function processes a fitted model or a tuning result, finalizes the model if tuning was used, makes predictions on the test set, and computes performance metrics depending on the task type (classification or regression). It supports binary and multiclass classification, and handles probabilistic outputs when supported by the modeling engine.

Usage

process_model(
  model_obj,
  model_id,
  task,
  test_data,
  label,
  event_class,
  class_threshold = "auto",
  start_col = NULL,
  time_col = NULL,
  status_col = NULL,
  engine,
  train_data,
  metric,
  eval_times_user = NULL,
  bootstrap_ci = TRUE,
  bootstrap_samples = 500,
  bootstrap_seed = 1234,
  at_risk_threshold = 0.1,
  survival_metric_convention = "fastml",
  metrics = NULL,
  summaryFunction = NULL,
  precomputed_predictions = NULL,
  multiclass_auc = "macro"
)

Arguments

Details

- If the input 'model_obj' is a 'tune_results' object, the function finalizes the model using the best hyperparameters according to the specified 'metric', and refits the model on the full training data.

- For classification tasks, performance metrics include accuracy, kappa, sensitivity, specificity, precision, F1-score, and ROC AUC (if probabilities are available).

- For multiclass ROC AUC, the estimator is controlled by 'multiclass_auc'.

- For regression tasks, RMSE, R-squared, and MAE are returned.

- For models with missing prediction lengths, a helpful imputation error is thrown to guide data preprocessing.

Value

A list with two elements:

performance

A tibble with computed performance metrics.

predictions

A tibble with predicted values and corresponding truth values, and probabilities (if applicable).

Recommend Tuning Configuration

Description

Provides recommendations for tuning configuration based on dataset characteristics and time constraints.

Usage

recommend_tuning_config(
  n_rows,
  n_predictors,
  n_algorithms = 1,
  max_time_minutes = 30,
  tuning_strategy = "grid"
)

Arguments

Value

A list with recommended configuration.

Reset Default Override Warnings

Description

Resets the tracking of which default override warnings have been shown. Useful for testing or when starting a new analysis session.

Usage

reset_default_warnings()

Resolve the positive class for binary classification

Description

Determines the positive class respecting event_class settings from fastml(). This ensures consistency across all explainer functions.

Usage

resolve_positive_class(prep, y_levels)

Arguments

Value

Character string of the resolved positive class name

Clean Column Names or Character Vectors by Removing Special Characters

Description

This function can operate on either a data frame or a character vector:

• Data frame: Detects columns whose names contain any character that is not a letter, number, or underscore, removes colons, replaces slashes with underscores, and spaces with underscores.

• Character vector: Applies the same cleaning rules to every element of the vector.

Usage

sanitize(x)

Arguments

Value

• If x is a data frame: returns a data frame with cleaned column names.

• If x is a character vector: returns a character vector with cleaned elements.

Save Model Function

Description

Saves the trained model object to a file.

Usage

save.fastml(model, filepath)

Arguments

Value

No return value, called for its side effect of saving the model object to a file.

Summary Function for fastml (Using yardstick for ROC Curves)

Description

Summarizes the results of machine learning models trained using the 'fastml' package. Depending on the task type (classification or regression), it provides customized output such as performance metrics, best hyperparameter settings, and confusion matrices. It is designed to be informative and readable, helping users quickly interpret model results.

Usage

## S3 method for class 'fastml'
summary(
  object,
  algorithm = "best",
  type = c("all", "metrics", "params", "conf_mat"),
  sort_metric = NULL,
  show_ci = FALSE,
  brier_times = NULL,
  ...
)

Arguments

Details

For classification tasks, the summary includes metrics such as Accuracy, F1 Score, Kappa, Precision, ROC AUC, Sensitivity, and Specificity. A confusion matrix is also provided for the best model(s). For regression tasks, the summary reports RMSE, R-squared, and MAE.

Users can control the type of output with the 'type' argument: 'metrics' displays model performance metrics. 'params' shows the best hyperparameter settings. 'conf_mat' prints confusion matrices (only for classification). 'all' includes all of the above.

If multiple algorithms are trained, the summary highlights the best model based on the optimized metric. For survival tasks, Harrell's C-index, Uno's C-index, the integrated Brier score, and (when available) the RMST difference are shown by default. Specific Brier(t) horizons can be requested through the brier_times argument.

Value

Prints summary of fastml models.

Fit a surrogate decision tree for a fastml model

Description

Builds an interpretable tree approximating the behaviour of the underlying model using the 'iml' package.

Usage

surrogate_tree(object, maxdepth = 3, data = c("train", "test"), ...)

Arguments

Value

An 'iml::TreeSurrogate' object.

Examples

## Not run: 
data(iris)
iris <- iris[iris$Species != "setosa", ]
iris$Species <- factor(iris$Species)
model <- fastml(data = iris, label = "Species")
surrogate_tree(model)

## End(Not run)

Train Specified Machine Learning Algorithms on the Training Data

Description

Trains specified machine learning algorithms on the preprocessed training data.

Usage

train_models(
  train_data,
  label,
  task,
  algorithms,
  resampling_method,
  folds,
  repeats,
  group_cols = NULL,
  block_col = NULL,
  block_size = NULL,
  initial_window = NULL,
  assess_window = NULL,
  skip = 0,
  outer_folds = NULL,
  resamples = NULL,
  tune_params,
  engine_params = list(),
  metric,
  summaryFunction = NULL,
  seed = 123,
  recipe,
  use_default_tuning = FALSE,
  tuning_strategy = "grid",
  tuning_iterations = 10,
  tuning_complexity = "balanced",
  grid_levels = 3L,
  early_stopping = FALSE,
  adaptive = FALSE,
  algorithm_engines = NULL,
  use_parsnip_defaults = FALSE,
  warn_engine_defaults = TRUE,
  n_cores = 1,
  verbose = FALSE,
  event_class = "first",
  class_threshold = "auto",
  start_col = NULL,
  time_col = NULL,
  status_col = NULL,
  eval_times = NULL,
  at_risk_threshold = 0.1,
  survival_metric_convention = "fastml",
  audit_env = NULL,
  multiclass_auc = "macro",
  store_fold_models = FALSE
)

Arguments

Value

A list of trained model objects.

Tuning Configuration and Complexity Presets

Description

Functions and presets for configuring hyperparameter tuning grids with explicit speed-robustness trade-offs.

Validate Defaults Registry Against Parsnip

Description

Compares the hardcoded parsnip default engines in fastml's registry against the actual defaults reported by parsnip::show_engines(). Returns a list of any mismatches found, which may indicate that parsnip has updated its defaults since fastml's registry was last updated.

Usage

validate_defaults_registry()

Details

This function queries parsnip for model specifications and compares against the hardcoded parsnip_defaults list in get_parsnip_default_engine(). Mismatches may occur when:

• Parsnip updates its default engine for a model type

• New engines are added to parsnip that become the new default

• fastml's registry has not been updated after a parsnip release

This validation is intended for package maintenance and testing purposes.

Value

A list of mismatches. Each element is a list with components:

algorithm

The algorithm name.

fastml_default

The default engine recorded in fastml's registry.

parsnip_default

The actual default engine from parsnip.

Returns an empty list if no mismatches are found.

Examples

## Not run: 
mismatches <- validate_defaults_registry()
if (length(mismatches) > 0) {
  message("Found ", length(mismatches), " mismatch(es) with parsnip defaults")
}

## End(Not run)

Warn About Default Overrides

Description

Issues a warning if fastml defaults differ from parsnip defaults and the warning hasn't been shown yet in this session.

Usage

warn_default_override(
  algo,
  task,
  fastml_engine,
  fastml_params = NULL,
  verbose = FALSE,
  warn_once = TRUE
)

Arguments

Value

Invisibly returns the comparison result.