Package {evoFE}

evoFE: Evolutionary Feature Engineering

Description

Automates feature engineering using evolutionary algorithms inspired by genetic programming. Starting from raw input features, the package evolves candidate transformation recipes through selection, crossover, and mutation, evaluating fitness via cross-validation or train/validation splits with gradient-boosted tree models ('LightGBM' or 'XGBoost'). Built-in transformers include arithmetic, logarithmic, and power operations, interaction terms, target encoding, quantile and log-based binning, principal component analysis, truncated singular value decomposition, Uniform Manifold Approximation and Projection (UMAP) dimensionality reduction, and minimum spanning tree (MST) graph-based clustering. The evolutionary search yields an optimised feature recipe that can be applied to new data for prediction. Methods are described in McInnes et al. (2018) doi:10.21105/joss.00861, Ke et al. (2017) doi:10.48550/arXiv.1711.08789, Chen and Guestrin (2016) doi:10.1145/2939672.2939785, Gagolewski (2021) doi:10.1016/j.softx.2021.100722, Gagolewski (2026) doi:10.32614/CRAN.package.lumbermark, and Gagolewski (2026) doi:10.32614/CRAN.package.deadwood.

evoFE automates tabular feature engineering using a genetic algorithm inspired by genetic programming. Starting from raw input features the package evolves candidate transformation recipes through selection, crossover, and mutation, evaluating fitness via cross-validation or train/validation splits with gradient-boosted tree models (LightGBM or XGBoost), linear models (glmnet), or deep-learning models (keras3).

Details

The main entry point is evolve_features, which returns an evo_recipe S3 object that can be predicted on new data.

Key subsystems

Transformer library

42 built-in transformers spanning arithmetic, supervised encoding, group-by aggregations, dimensionality reduction, and manifold/graph learning. Register custom transformers via register_transformer.

Island model

Optionally partition evolution into independent sub-populations (islands) with periodic recipe-level and gene-level migration. Configured via the islands, migration_interval, migration_rate, gene_migration_prob, migration_topology, migration_temperature, pull_stagnation_threshold, row_split_islands, and per_island_validation parameters of evolve_features.

Hybrid Active Feature Mask

Each individual carries an active mask over the raw input columns so that the genetic search simultaneously selects which original features to include and what transformations to apply. Mask mutations are controlled by raw_toggle_prob, recalculate_mask_prob, and mask_temp_factor.

Bayesian hyperparameter tuning

Wrap any registered evaluator in an mlr3mbo Bayesian optimisation loop via make_tunable.

Live evolution viewer

Enable real-time visualisation of the evolutionary search in a browser via record = TRUE in evolve_features.

Package Options

The following options can be set via options() to control package behaviour at runtime:

evoFE.verbose

(integer/logical) Verbosity level. 0 or FALSE for silent; 1 or TRUE for normal; 2 for detailed transformer-level logging. Default 0.

evoFE.threads

(integer) Default number of threads to use for parallel operations inside evaluators and clustering transformers. Default 2.

evoFE.max_clustering_size

(integer) Maximum number of unique training rows used when fitting clustering/manifold transformers (Genie, Lumbermark, UMAP, MST, Deadwood). Excess rows are randomly downsampled before fitting. Set to 0 or NULL to disable downsampling. Default 5000.

evoFE.redundancy_cor_threshold

(numeric in (0, 1]) Pearson correlation threshold above which a newly generated feature column is considered a near-duplicate of an existing column and rejected. Lower values impose stricter redundancy pruning. Set to 1.0 to disable. Default 0.95.

evoFE.importance_threshold

(numeric >= 0) Normalised feature importance threshold below which a feature's weight is zeroed out before importance-guided mutation. Default 0.001.

Author(s)

Maintainer: Gustavo Pereira tanopereira@gmail.com

Authors:

• Gustavo Pereira tanopereira@gmail.com

See Also

Useful links:

• https://github.com/tanopereira/evoFE

• Report bugs at https://github.com/tanopereira/evoFE/issues

Apply a single gene to a dataset

Description

Apply a single gene to a dataset

Usage

apply_gene(
  gene,
  train_data,
  val_data = NULL,
  target_col = NULL,
  state_cache = NULL,
  data_hash = NULL
)

Arguments

Value

A list with three elements: train (the modified training data.table with the new gene column appended), val (the modified validation data.table or NULL), and gene (the gene list, with its state element populated if the transformer is stateful).

Apply an entire individual's recipe to data

Description

Apply an entire individual's recipe to data

Usage

apply_individual(
  ind,
  train_data,
  val_data = NULL,
  target_col = NULL,
  state_cache = NULL,
  allow_prune = TRUE
)

Arguments

Value

A list with three elements: train (the transformed training data.table with all gene columns applied), val (the transformed validation data.table or NULL), and ind (the updated evo_individual whose genes now carry fitted states).

Convert evo_topology to Adjacency Matrix

Description

Convert evo_topology to Adjacency Matrix

Usage

## S3 method for class 'evo_topology'
as.matrix(x, ...)

Arguments

Value

N x N integer adjacency matrix.

Compute Calibrated MAE

Description

Computes the Mean Absolute Error (MAE) of y_pred after optimal L1 linear post-calibration. Finds intercept 'a' and slope 'b' minimizing Mean(|y_true - (a + b * y_pred)|) via 2D optimization.

Usage

compute_calibrated_mae(y_true, y_pred)

Arguments

Value

Numeric calibrated MAE score.

Compute Calibrated RMSE

Description

Computes the Root Mean Squared Error (RMSE) of y_pred after optimal linear post-calibration. Mathematically equivalent to SD(y_true) * sqrt(1 - R^2) where R is the Pearson correlation.

Usage

compute_calibrated_rmse(y_true, y_pred)

Arguments

Value

Numeric calibrated RMSE score.

Compute Complexity Penalty for an Individual

Description

Computes the parsimony complexity penalty using Bayesian Information Criterion (BIC) scaling (ln(N) / (2N)) and optional dynamic convergence scaling based on the relative gap to the metric ceiling.

Usage

compute_complexity_penalty(
  n_genes,
  n_samples,
  running_best_fitness = NULL,
  baseline_fitness = NULL,
  metric = "default",
  task = "classification",
  complexity_penalty = 0,
  complexity_mode = "bic_dynamic",
  complexity_floor = 0.2,
  complexity_target = "all_features",
  n_features = NULL,
  epsilon_floor = 0.2
)

Arguments

Value

Non-negative numeric penalty to subtract from raw fitness.

Temperature Scaled Refinement Metric

Description

Computes the Temperature Scaled Refinement (TS-Refinement) metric for binary or multiclass classification. The metric finds the temperature $T$ that minimizes the Laplace-smoothed log-loss of the temperature-scaled prediction margins (logits).

Usage

compute_ts_refinement(
  y_true,
  y_pred,
  task = "classification",
  num_class = NULL,
  alpha = 1,
  is_logits = FALSE
)

Arguments

Value

Numeric. The minimized smoothed log-loss.

Create a single gene

Description

Create a single gene

Usage

create_gene(transformer_name, input_cols)

Arguments

Value

A gene list with elements transformer_name, input_cols, params (transformer-specific parameters), state (NULL until fitted), and output_col (auto-generated column name).

Create an individual

Description

Create an individual

Usage

create_individual(
  genes = list(),
  numeric_cols = character(0),
  categorical_cols = character(0),
  datetime_cols = character(0),
  all_numeric_cols = NULL,
  all_categorical_cols = NULL,
  all_datetime_cols = NULL
)

Arguments

Value

An evo_individual S3 object: a list with elements genes (topologically sorted), numeric_cols, categorical_cols, and fitness (initialised to NA_real_).

Examples

ind <- create_individual(
  genes = list(),
  numeric_cols = c("a", "b"),
  categorical_cols = c("c")
)
print(ind)

Create a transformer definition

Description

Create a transformer definition

Usage

create_transformer(
  name,
  type,
  input_type = "numeric",
  output_type = "numeric",
  fit_func = NULL,
  apply_func,
  name_generator,
  allow_replace = FALSE
)

Arguments

Value

An evo_transformer S3 object: a list with elements name, type, input_type, output_type, fit_func, apply_func, name_generator, and allow_replace.

Examples

# Define a transformer that adds a constant value of 10 to a variable
add_ten_trans <- create_transformer(
  name = "add_ten",
  type = "unary",
  input_type = "numeric",
  apply_func = function(data, gene, state = NULL) {
    data[[gene$input_cols[1]]] + 10
  },
  name_generator = function(gene) paste0("add10_", gene$input_cols[1])
)
print(add_ten_trans)

Crossover two individuals

Description

Crossover two individuals

Usage

crossover(ind1, ind2, verbose = FALSE)

Arguments

Value

An evo_individual child created by randomly sampling genes from both parents with duplicate gene outputs removed.

Examples

ind1 <- create_individual(numeric_cols = c("a", "b"))
ind1 <- mutate(ind1, force_add = TRUE)
ind2 <- create_individual(numeric_cols = c("a", "b"))
ind2 <- mutate(ind2, force_add = TRUE)
child <- crossover(ind1, ind2)

Caruana Island Ensemble Selection

Description

Performs Caruana ensemble selection (greedy forward selection with replacement) over the validation/out-of-fold predictions from evolved islands, creating an optimal multi-model ensemble.

Usage

ensemble_islands(
  recipe,
  data,
  target_col = NULL,
  caruana_rounds = 50,
  bag_samples = TRUE,
  sample_ratio = 0.8,
  seed = NULL,
  threads = 2,
  verbose = TRUE,
  ...
)

Arguments

Value

An evo_ensemble object containing:

Examples

data(mtcars)
df <- mtcars
df$am <- as.integer(df$am)

# Evolve features across 3 islands
recipe <- evolve_features(
  data = df,
  target_col = "am",
  task = "classification",
  evaluator = "xgboost",
  generations = 2,
  pop_size = 2,
  islands = 3,
  cv_folds = 2,
  verbose = FALSE
)

# Build Caruana ensemble from island predictions
ens <- ensemble_islands(recipe, data = df, caruana_rounds = 20, verbose = FALSE)
print(ens)

Evaluate the fitness of an individual

Description

Trains a model using the features specified by the individual's recipe and evaluates performance using cross-validation or train/val split.

Usage

evaluate_fitness(
  ind,
  data,
  target_col,
  task = "classification",
  cv_folds = 3,
  evaluation_strategy = "cv",
  split_ids = NULL,
  shared_splits = NULL,
  evaluator = "lightgbm",
  fold_ids = NULL,
  shared_folds = NULL,
  shared_full = NULL,
  state_cache = NULL,
  threads = 2,
  metric = "default",
  verbose = FALSE,
  allow_prune = TRUE,
  complexity_penalty = 0,
  complexity_mode = "bic_dynamic",
  complexity_floor = 0.2,
  complexity_target = "all_features",
  running_best_fitness = NULL,
  baseline_fitness = NULL,
  n_samples = NULL,
  cv_strategy = "random",
  time_col = NULL,
  group_col = NULL,
  ...
)

Arguments

Value

The input evo_individual with its fitness field set to the computed score (higher is better), importances set to a named numeric vector of feature importances, holdout_fitness set to NULL, and genes updated with fitted transformer states.

Evaluate holdout fitness for an individual

Description

Evaluate holdout fitness for an individual

Usage

evaluate_holdout_fitness(
  ind,
  data,
  split_ids,
  shared_splits,
  target_col,
  task,
  evaluator,
  threads,
  state_cache,
  classes,
  num_class,
  metric = "default",
  verbose = FALSE,
  ...
)

Arguments

Value

An updated evo_individual with holdout_fitness evaluated on the holdout partition.

Evaluate all unevaluated individuals in a population

Description

Evaluate all unevaluated individuals in a population

Usage

evaluate_pop(
  pop,
  data,
  target_col,
  task,
  cv_folds,
  evaluation_strategy,
  split_ids,
  shared_splits,
  evaluator,
  fold_ids,
  shared_folds,
  shared_full,
  state_cache,
  fitness_cache,
  threads,
  verbose,
  running_best_fitness,
  metric = "default",
  allow_prune = TRUE,
  complexity_penalty = 0,
  complexity_mode = "bic_dynamic",
  complexity_floor = 0.2,
  complexity_target = "all_features",
  baseline_fitness = NULL,
  n_samples = NULL,
  island = NULL,
  fidelity_tag = "",
  cv_strategy = "random",
  time_col = NULL,
  group_col = NULL,
  ...
)

Global environment for registered model evaluators

Description

Global environment for registered model evaluators

Usage

evo_evaluators

Value

An environment containing registered model evaluators.

Built-in feature transformers

Description

An environment containing all built-in transformer definitions available for the evolutionary feature-engineering search. Every entry is an evo_transformer object produced by create_transformer.

Usage

evo_transformers

Details

Arithmetic (numeric -> numeric)

log

Safe natural logarithm: log1p(|x|).

sqrt

Safe square root: sqrt(|x|).

reciprocal

Reciprocal: 1/x (0 where x == 0).

power

Signed exponentiation: sign(x) * |x|^p where p is sampled from {0.5, 1/3, 2, 3}.

displaced_log

Displaced log: log1p(|x + displacement|) where displacement is sampled from [10, 1000].

add

Element-wise sum of 2+ numeric columns.

subtract

Element-wise difference of two numeric columns.

multiply

Element-wise product of 2+ numeric columns.

divide

Element-wise ratio (0 where denominator is 0).

normalized_difference

(a - b) / (|a| + |b| + 1e-6).

log_ratio

log1p(|a|) - log1p(|b|).

Rank / distribution (numeric -> numeric, stateful)

rank_transform

ECDF-based percentile rank mapped to [0, 1]. Fit on training data; robust to outliers.

Group-by aggregations (mixed cat x num -> numeric, stateful)

groupby_mean

Per-group mean.

groupby_sd

Per-group standard deviation.

groupby_max

Per-group maximum.

groupby_min

Per-group minimum.

groupby_ratio

value / group_mean.

groupby_zscore

(value - group_mean) / group_sd.

groupby_median

Per-group median (robust to outliers).

groupby_quantile

Per-group Q1 or Q3 (q sampled from {0.25, 0.75}).

Supervised categorical encodings (categorical -> numeric, stateful)

target_encode

Smoothed mean-target encoding for binary / regression tasks.

pooled_target_encode

Empirical Bayes pooled target encoding for binary / regression tasks using dynamic shrinkage based on target variance.

target_encode_multiclass

Class-wise smoothed target encoding for multiclass tasks.

target_quantile_encode

Category target encoding using smoothed target quantiles (q sampled from {0.25, 0.50, 0.75}).

cat_interaction_target_encode

Smoothed mean-target encoding for joint Cartesian interaction of two categorical columns.

woe_encode

Weight of Evidence encoding for binary classification: ln(P(event|cat) / P(non-event|cat)) with Laplace smoothing. Falls back to 0 for non-binary targets.

Unsupervised categorical / text / datetime

concat

Concatenates 2 or 3 categorical columns row-wise using an underscore separator.

frequency_encode

Count of each category level in training data.

one_hot_encode

Binary indicator for up to 5 top categories plus an "other" bucket (comp_idx 1-6).

similarity_encode

Character 3-gram Jaccard similarity between string levels and top-K prototype categories (inspired by skrub).

minhash_encode

Fast sub-string MinHash hashing for high-cardinality strings (inspired by skrub).

gap_encode

Character 3-gram TF-IDF projection via SVD to extract latent sub-string topics (inspired by skrub).

quantile_binning

Assigns quantile-based bin index (numeric output).

quantile_binning_cat

Same, with categorical output.

log_binning

Log-scale bin index (numeric output).

log_binning_cat

Same, with categorical output.

datetime_extract

Extracts year, month, day, hour, day-of-week, or weekend indicator from date/datetime columns.

datetime_cyclic

Sine and cosine cyclic encoding for periodic date/time components (hour, day of week, month, day of year).

date_diff

Signed difference in days between two datetime columns.

Dimensionality reduction (numeric -> numeric, stateful)

pca

Selected principal component from prcomp.

truncated_svd

Selected component from truncated SVD.

random_projection

Random unit-vector linear combination.

umap

UMAP projection component (requires uwot).

Manifold / graph learning (numeric -> numeric or categorical, stateful)

genie

Genie hierarchical cluster label (requires genieclust).

genie_centroid_dist

Distance to each Genie cluster centroid.

umap_genie

Genie cluster label computed on low-dimensional UMAP embedding (requires uwot and genieclust).

umap_lumbermark

Lumbermark cluster label computed on a low-dimensional UMAP embedding. Combines the non-linear structure discovery of UMAP with the minimum-spanning-tree-based hierarchical clustering of Lumbermark (requires uwot and lumbermark).

lumbermark

Lumbermark hierarchical cluster label (requires lumbermark).

lumbermark_centroid_dist

Distance to each Lumbermark cluster centroid.

mst_score

MST-based anomaly score (requires quitefastmst).

deadwood

Deadwood outlier indicator (requires deadwood).

Value

An environment containing registered feature transformers.

See Also

create_transformer, register_transformer

Run evolutionary feature engineering

Description

Run evolutionary feature engineering

Usage

evolve_features(
  data,
  target_col,
  task = "classification",
  generations = 10,
  pop_size = 10,
  cv_folds = 3,
  evaluation_strategy = "cv",
  split_ratio = c(0.6, 0.2, 0.2),
  split_ids = NULL,
  holdout_frac = 0,
  cv_strategy = "random",
  time_col = NULL,
  group_col = NULL,
  multi_fidelity = FALSE,
  mf_sample_frac = 0.5,
  mf_warmup_frac = 0.5,
  early_stopping_generations = 3,
  evaluator = "lightgbm",
  seed = NULL,
  dynamic_population = TRUE,
  dynamic_population_growth_rate = 1.5,
  dynamic_population_decay_rate = 0.7,
  crossover_type = "both",
  threads = 2,
  max_clustering_size = 5000,
  verbose = TRUE,
  metric = "default",
  model_all_final_genes = FALSE,
  model_all_historical_genes = FALSE,
  allowed_transformers = "all",
  complexity_penalty = 0,
  complexity_mode = "bic_dynamic",
  complexity_floor = 0.2,
  complexity_target = "all_features",
  migration = NULL,
  islands = 1,
  migration_interval = 5,
  migration_rate = 1,
  gene_migration_prob = 0.2,
  migration_topology = "ring",
  migration_temperature = 1,
  pull_stagnation_threshold = 3,
  raw_toggle_prob = 0.15,
  recalculate_mask_prob = 0.05,
  mask_temp_factor = 0.5,
  row_split_islands = FALSE,
  per_island_validation = FALSE,
  record = FALSE,
  port = NULL,
  ...
)

Arguments

Value

An evo_recipe S3 object: a list with elements best_individual (the top-scoring evo_individual), history (list of all evaluated individuals across generations), task, best_model (the trained model object), evaluator, and classes (class levels for multiclass tasks, otherwise NULL).

Examples

# Quick classification example using mtcars
data(mtcars)
df <- mtcars
df$am <- as.integer(df$am)

set.seed(42)
recipe <- evolve_features(
  data = df,
  target_col = "am",
  task = "classification",
  evaluator = "xgboost",
  generations = 2,
  pop_size = 2,
  cv_folds = 2,
  verbose = FALSE
)
print(recipe)

Convert a gene to a formula string

Description

Convert a gene to a formula string

Usage

gene_to_formula(gene, truncate = TRUE)

Arguments

Value

A character string representing the gene as a human-readable formula, e.g. "log(col1)" or "pca2(col1, col2)".

Convert a gene to a formula string for state caching (ignoring component index)

Description

Convert a gene to a formula string for state caching (ignoring component index)

Usage

gene_to_state_formula(gene)

Arguments

Value

A character string representing the gene formula suitable for state caching. For multi-component transformers (PCA, SVD, UMAP) the component index is omitted so that all components share one cache key.

Convert an individual to a recipe string of formulas

Description

Convert an individual to a recipe string of formulas

Usage

individual_to_recipe_string(ind)

Arguments

Value

A character string listing all gene formulas in bracket notation, e.g. "[log(x), sqrt(y)]", or "[Original features only]" when the individual has no genes.

Initialize a population

Description

Initialize a population

Usage

initialize_population(
  pop_size,
  numeric_cols,
  categorical_cols,
  datetime_cols = character(0),
  initial_genes = 2,
  task = "classification",
  importances = NULL,
  allowed_transformers = NULL,
  mask_temp_factor = 0.5
)

Arguments

Value

A list of evo_individual objects of length pop_size. The first individual is a baseline with no genes; the remaining individuals each carry initial_genes randomly generated genes.

Check whether a candidate individual is a duplicate or known-inferior

Description

Check whether a candidate individual is a duplicate or known-inferior

Usage

is_invalid_individual(c_ind, pop_list, cache, best_fit, evaluator = NULL)

Create a Tunable Evaluator from a Registered Base Model

Description

Wraps an existing registered model evaluator in a Bayesian Optimization tuning loop using the mlr3mbo framework. It automatically generates a parameter space, constructs a cross-validation or split-validation objective function, searches for the optimal hyperparameters, and registers the tuned evaluator.

Usage

make_tunable(
  base_model_name,
  param_ranges,
  tuner_name = paste0(base_model_name, "_mbo")
)

Arguments

Details

The tuning loop uses a Latin Hypercube Design (LHS) for the initial parameters layout. It uses the mlr3mbo package to run Bayesian Optimization to optimize hyperparameters.

Evaluators registered via make_tunable accept several control parameters passed via ...:

mbo_iters

Integer: Number of Bayesian Optimization iterations (default 5).

mbo_init_design

Integer: Number of initial layout designs generated (default 8).

mbo_folds

Integer: Number of internal CV folds used for evaluation when no validation split is provided (default 3).

mbo_infill_opt

Character: Strategy for infill optimization to find the next candidate parameter set. Supported values are "focussearch" (default) and "ea" (deprecated).

best_params

List: Optional list of initial parameters to seed the MBO search.

Value

Invisibly returns NULL. Registers the tuned evaluator in the global evo_evaluators environment.

Examples

## Not run: 
# 1. Register a simple mock evaluator
register_evaluator(
  "mock_base",
  train_func = function(x_train, y_train, x_val = NULL, y_val = NULL,
                        task = "regression", ...) {
    args <- list(...)
    val_score <- 100 - abs(args$param_a - 4.5)
    list(
      model = list(args = args, val_score = val_score),
      predictions = if (!is.null(x_val)) {
        rep(val_score, nrow(x_val))
      } else {
        NULL
      }
    )
  },
  predict_func = function(model, x_new, task, ...) {
    rep(model$val_score, nrow(x_new))
  }
)

# 2. Make it tunable
param_ranges <- list(
  param_a = list(type = "numeric", lower = 1.0, upper = 8.0)
)
make_tunable("mock_base", param_ranges, tuner_name = "mock_tuned")

# 3. Train the tuned model on mock data
x_train <- matrix(rnorm(20), ncol = 2)
colnames(x_train) <- c("x1", "x2")
y_train <- rnorm(10)
x_val <- matrix(rnorm(10), ncol = 2)
y_val <- rnorm(5)

fit <- train_model(
  x_train, y_train, x_val = x_val, y_val = y_val,
  task = "regression", evaluator = "mock_tuned",
  mbo_iters = 3, mbo_init_design = 5, mbo_folds = 2
)
print(fit$best_params)

## End(Not run)

Migration Policy Constructors and Generics for Island Models

Description

Functions to specify and resolve migration dynamics, target selection, and admission rules.

Usage

policy_push_uniform()

policy_gibbs_push(
  temperature = 0.5,
  weight_by = c("stagnation", "fitness", "feature_distance", "uniform")
)

policy_gibbs_pull(
  temperature = 0.5,
  stagnation_threshold = 3,
  weight_by = c("fitness", "feature_distance", "uniform")
)

policy_tiered_admission(min_fitness_threshold = "min_peer")

migration_config(
  topology = topology_ring(),
  policy = policy_push_uniform(),
  payload = "gene_only"
)

resolve_migration_transactions(policy, topology, state, ...)

## S3 method for class 'evo_policy_push_uniform'
resolve_migration_transactions(policy, topology, state, ...)

## S3 method for class 'evo_policy_gibbs_push'
resolve_migration_transactions(policy, topology, state, ...)

## S3 method for class 'evo_policy_gibbs_pull'
resolve_migration_transactions(policy, topology, state, ...)

## S3 method for class 'evo_policy_tiered_admission'
resolve_migration_transactions(policy, topology, state, ...)

Arguments

Value

An object of class evo_policy or evo_migration_config, or a transaction list.

Mutate an individual

Description

Mutate an individual

Usage

mutate(
  ind,
  verbose = FALSE,
  force_add = FALSE,
  importances = numeric(0),
  temperature = 1,
  task = "classification",
  tested_gene_outputs = NULL,
  allowed_transformers = NULL,
  migrated_genes = list(),
  gene_migration_prob = 0.2,
  raw_toggle_prob = 0.15,
  recalculate_mask_prob = 0.05
)

Arguments

Value

An evo_individual with the mutation applied (gene added, removed, or modified) and fitness reset to NA_real_.

Examples

ind <- create_individual(
  numeric_cols = c("a", "b"),
  categorical_cols = c("c")
)
mutated_ind <- mutate(ind)

Plot an evo_recipe object

Description

Plots either the fitness trajectory over generations or the feature importances of the best individual.

Usage

## S3 method for class 'evo_recipe'
plot(x, type = "fitness", ...)

Arguments

Value

Invisible NULL. Called for its side effect of plotting the fitness curve or feature importances.

Examples

data(mtcars)
df <- mtcars
df$am <- as.integer(df$am)

recipe <- evolve_features(
  data = df,
  target_col = "am",
  task = "classification",
  evaluator = "xgboost",
  generations = 2,
  pop_size = 2,
  cv_folds = 2,
  seed = 42,
  verbose = FALSE
)

# Plot the fitness curve
plot(recipe, type = "fitness")

# Plot feature importances
plot(recipe, type = "importance")

Apply engineered features from an ensemble of recipes

Description

Apply engineered features from an ensemble of recipes

Usage

## S3 method for class 'evo_ensemble'
predict(object, newdata, ...)

Arguments

Value

A data.table containing the combined engineered features across all active recipes in the ensemble.

Apply feature engineering recipe to new data

Description

Apply feature engineering recipe to new data

Usage

## S3 method for class 'evo_recipe'
predict(object, newdata, ...)

Arguments

Value

A data.table containing the engineered feature columns (original plus all gene-derived columns) for newdata, ready for downstream modelling.

Examples

data(mtcars)
df <- mtcars
df$am <- as.integer(df$am)

recipe <- evolve_features(
  data = df,
  target_col = "am",
  task = "classification",
  evaluator = "xgboost",
  generations = 2,
  pop_size = 2,
  cv_folds = 2,
  seed = 42,
  verbose = FALSE
)

# Extract engineered features
engineered_features <- predict(recipe, df[1:5, ])
print(engineered_features)

Predict target values using the fully evolved model or ensemble

Description

Predict target values using the fully evolved model or ensemble

Usage

predict_model(object, newdata, ...)

## S3 method for class 'evo_recipe'
predict_model(object, newdata, ...)

## S3 method for class 'evo_ensemble'
predict_model(object, newdata, ...)

Arguments

Value

For binary classification and regression tasks a numeric vector of predictions. For multiclass tasks a numeric matrix with one column per class (columns named after class levels).

Examples

data(mtcars)
df <- mtcars
df$am <- as.integer(df$am)

recipe <- evolve_features(
  data = df,
  target_col = "am",
  task = "classification",
  evaluator = "xgboost",
  generations = 2,
  pop_size = 2,
  cv_folds = 2,
  seed = 42,
  verbose = FALSE
)

# Get model predictions
predictions <- predict_model(recipe, df[1:5, ])
print(predictions)

Print an evo_ensemble object

Description

Prints a human-readable summary of the Caruana island ensemble.

Usage

## S3 method for class 'evo_ensemble'
print(x, ...)

Arguments

Value

Invisible x. Called for its side effect of printing the ensemble overview.

Print an evo_recipe object

Description

Prints a human-readable summary of the evolutionary feature engineering recipe.

Usage

## S3 method for class 'evo_recipe'
print(x, ...)

Arguments

Value

Invisible x. Called for its side effect of printing the recipe overview.

Print summary of an evo_ensemble object

Description

Prints summary details of the Caruana island ensemble.

Usage

## S3 method for class 'summary_evo_ensemble'
print(x, ...)

Arguments

Value

Invisible x. Called for its side effect of printing the ensemble summary.

Print summary of an evo_recipe object

Description

Prints the summary details of the evolutionary feature engineering recipe.

Usage

## S3 method for class 'summary_evo_recipe'
print(x, ...)

Arguments

Value

Invisible x. Called for its side effect of printing the recipe summary.

Register a model evaluator

Description

Register a model evaluator

Usage

register_evaluator(
  name,
  train_func,
  predict_func,
  base_evaluator = NULL,
  cleanup_func = NULL
)

Arguments

Value

Invisible NULL. Called for the side effect of registering the evaluator in evo_evaluators.

Examples

# Register a simple mock evaluator
register_evaluator(
  "mock_eval",
  train_func = function(x_train, y_train, x_val = NULL,
                        task = "regression", ...) {
    list(
      model = list(weights = colMeans(x_train)),
      predictions = if (!is.null(x_val)) rowMeans(x_val) else NULL,
      importances = stats::setNames(
        rep(1, ncol(x_train)), colnames(x_train)
      )
    )
  },
  predict_func = function(model, x_new, task, ...) {
    rowMeans(x_new)
  }
)

# Verify it is registered
exists("mock_eval", envir = evo_evaluators)

Register a custom feature transformer

Description

Adds a user-defined feature transformer to the available pool for feature evolution.

Usage

register_transformer(name, transformer)

Arguments

Value

Invisible transformer, the registered transformer object.

Examples

# Create a custom transformer
add_ten_trans <- create_transformer(
  name = "add_ten",
  type = "unary",
  input_type = "numeric",
  apply_func = function(data, gene, state = NULL) {
    data[[gene$input_cols[1]]] + 10
  },
  name_generator = function(gene) paste0("add10_", gene$input_cols[1])
)

# Register it
register_transformer("add_ten", add_ten_trans)

# Verify it is registered
exists("add_ten", envir = evo_transformers)

Start the Evolution Live Viewer Server

Description

Launches an httpuv web server and returns a controller list to interact with it.

Usage

start_evolution_viewer(port = NULL)

Arguments

Value

A list with url, server, send, and stop functions.

Stratified or random splitting helper

Description

Stratified or random splitting helper

Usage

stratified_split(y, ratio)

Summary of an evo_ensemble object

Description

Computes and formats a detailed summary of the Caruana island ensemble.

Usage

## S3 method for class 'evo_ensemble'
summary(object, ...)

Arguments

Value

An object of class summary_evo_ensemble containing detailed ensemble statistics.

Summary of an evo_recipe object

Description

Computes and formats a detailed summary of the evolutionary feature engineering recipe.

Usage

## S3 method for class 'evo_recipe'
summary(object, ...)

Arguments

Value

An object of class summary_evo_recipe containing detailed recipe statistics.

Examples

data(mtcars)
df <- mtcars
df$am <- as.integer(df$am)

recipe <- evolve_features(
  data = df,
  target_col = "am",
  task = "classification",
  evaluator = "xgboost",
  generations = 2,
  pop_size = 2,
  cv_folds = 2,
  seed = 42,
  verbose = FALSE
)

# Print the recipe overview
print(recipe)

# Inspect a detailed summary
recipe_summary <- summary(recipe)
print(recipe_summary)

Check if terminal supports ANSI colors

Description

Check if terminal supports ANSI colors

Usage

supports_color()

Graph Topology Constructors and Generics for Island Models

Description

Functions to specify and query graph topologies connecting evolution islands. Topologies define island adjacency ($G = (V, E)$) independent of migration movement policies. Every topology object pre-builds and exposes an explicit adj_list and adj_matrix.

Usage

topology_ring(islands = 10)

topology_grid(islands = 10, rows = NULL, cols = NULL)

topology_torus(islands = 10, rows = NULL, cols = NULL)

topology_hypercube(islands = NULL, dimension = NULL)

topology_tiered(islands = 10, tiers = 3)

topology_complete(islands = 10)

get_neighbors(topology, island_id, state = NULL, ...)

## S3 method for class 'evo_topology'
get_neighbors(topology, island_id, state = NULL, ...)

get_in_neighbors(topology, island_id, state = NULL, ...)

## S3 method for class 'evo_topology'
get_in_neighbors(topology, island_id, state = NULL, ...)

## S3 method for class 'evo_topology_ring'
get_neighbors(topology, island_id, state = NULL, ...)

## S3 method for class 'evo_topology_grid'
get_neighbors(topology, island_id, state = NULL, ...)

## S3 method for class 'evo_topology_torus'
get_neighbors(topology, island_id, state = NULL, ...)

## S3 method for class 'evo_topology_hypercube'
get_neighbors(topology, island_id, state = NULL, ...)

## S3 method for class 'evo_topology_tiered'
get_neighbors(topology, island_id, state = NULL, ...)

## S3 method for class 'evo_topology_complete'
get_neighbors(topology, island_id, state = NULL, ...)

## S3 method for class 'evo_topology_custom'
get_neighbors(topology, island_id, state = NULL, ...)

Arguments

Value

An object of class evo_topology (and specific subclass), or neighbor node IDs.

Custom Graph Topology Constructor

Description

Custom Graph Topology Constructor

Usage

topology_custom(adj)

Arguments

Value

Object of class evo_topology_custom.

Selects the individual with the highest fitness among a randomly chosen tournament of size k.

Description

Selects the individual with the highest fitness among a randomly chosen tournament of size k.

Usage

tournament_select(pop, k = 3)

Arguments

Value

The winning candidate individual object from pop.

Examples

pop <- list(
  list(fitness = 0.5),
  list(fitness = 0.8),
  list(fitness = 0.2)
)
best <- tournament_select(pop, k = 2)

Train a boosted tree model

Description

Internal helper that encapsulates LightGBM / XGBoost parameter construction and training. Returns the fitted model, optional predictions on validation data, and feature importances.

Usage

train_model(
  x_train,
  y_train,
  x_val = NULL,
  y_val = NULL,
  task = "classification",
  evaluator = "lightgbm",
  threads = 2,
  num_class = NULL,
  nrounds = 50,
  ...
)

Arguments

Value

A list with elements model, predictions (NULL when x_val is NULL), and importances (named numeric vector or NULL).

Union Crossover of two individuals

Description

Union Crossover of two individuals

Usage

union_crossover(ind1, ind2, verbose = FALSE)

Arguments

Value

An evo_individual child created by taking the union of all genes from both parents with duplicate gene outputs removed.

View the evolution history of an evo_recipe

Description

Opens an interactive HTML page in the browser to visualize the evolutionary feature engineering process, either in real-time or post-hoc.

Usage

view(recipe, ...)

## S3 method for class 'evo_recipe'
view(recipe, ...)

Arguments

Value

Invisible file path string to the generated HTML viewer file.