GA Engine API Reference¶
Complete documentation for genetic algorithm components.
Module: ga_trees.ga.engine¶
GAConfig¶
Configuration dataclass for genetic algorithm.
Attributes:
population_size(int): Number of individuals per generation (default: 100)n_generations(int): Number of evolution cycles (default: 50)crossover_prob(float): Crossover probability [0, 1] (default: 0.7)mutation_prob(float): Mutation probability [0, 1] (default: 0.2)tournament_size(int): Tournament selection size (default: 3)elitism_ratio(float): Fraction of elite preserved [0, 1] (default: 0.1)mutation_types(dict): Mutation operator probabilities (must sum to 1.0). The operator is drawn by position, so the key order matters for reproducing a run.random_state(int | None): Seedsrandomandnumpy.randomat the start ofevolve(default: None)early_stopping_rounds(int | None): Stop after this many generations without the best fitness improving by more thanearly_stopping_tol; None disables it (default: None)early_stopping_tol(float): Minimum improvement that resets the counter (default: 1e-6)
Example:
from ga_trees.ga.engine import GAConfig
config = GAConfig(
population_size=80,
n_generations=40,
crossover_prob=0.72,
mutation_prob=0.18,
tournament_size=4,
elitism_ratio=0.12,
mutation_types={
"threshold_perturbation": 0.45,
"feature_replacement": 0.25,
"prune_subtree": 0.25,
"expand_leaf": 0.05,
},
)
TreeInitializer¶
Initialize random decision trees.
Constructor¶
TreeInitializer(
n_features,
n_classes,
max_depth,
min_samples_split,
min_samples_leaf,
task_type="classification",
growth_stop_prob=0.3,
split_strategy="midpoint",
)
Parameters:
n_features(int): Number of input featuresn_classes(int): Number of target classesmax_depth(int): Maximum tree depthmin_samples_split(int): Minimum samples to splitmin_samples_leaf(int): Minimum samples in leaftask_type(str): 'classification' or 'regression'growth_stop_prob(float): Per-node probability of stopping growth when seeding the population, in [0, 1). Lower values seed bushier trees; defaults toDEFAULT_GROWTH_STOP_PROB(0.3)split_strategy(str): Where split thresholds come from."midpoint"(default) picks a midpoint between observed values of the samples reaching the node, keepingmin_samples_leafon both sides."uniform"is the original draw across the feature's whole range, which often produces splits that send every sample one way.
Methods¶
create_random_tree(X, y)¶
Create a random valid tree.
Parameters:
X(np.ndarray): Training featuresy(np.ndarray): Training labels
Returns:
TreeGenotype: Random tree respecting constraints
Example:
from ga_trees.ga.engine import TreeInitializer
import numpy as np
X = np.random.rand(100, 4)
y = np.random.randint(0, 2, 100)
initializer = TreeInitializer(
n_features=4, n_classes=2, max_depth=5, min_samples_split=10, min_samples_leaf=5
)
tree = initializer.create_random_tree(X, y)
print(f"Created tree: depth={tree.get_depth()}, nodes={tree.get_num_nodes()}")
Mutation¶
The four mutation operators.
Constructor¶
Parameters:
n_features(int): Number of input featuresfeature_ranges(dict):{feature_index: (min, max)}, used when noXis givenX(np.ndarray | None): The data the GA trains on. With it,threshold_perturbation,feature_replacementandexpand_leafdraw thresholds from the values that actually reach the node being mutated. Without it they fall back tofeature_ranges. Pass the GA's training split only, never the validation split, or the search sees the data it's scored on.min_samples_leaf(int): Minimum samples a new split must leave on each sidesplit_strategy(str):"midpoint"or"uniform", as forTreeInitializer
mutate(tree, mutation_types) picks one operator by the given probabilities and applies it
in place.
GAEngine¶
Main genetic algorithm engine.
Constructor¶
Parameters:
config(GAConfig): GA configurationinitializer(TreeInitializer): Tree initializerfitness_function(callable):f(tree, X, y)returning a float. If you pass a validation set toevolve, it's called asf(tree, X, y, X_val, y_val)instead;FitnessCalculator.calculate_fitnessaccepts both.mutation(Mutation): Mutation operatorrepair(callable | None): Applied to every offspring after crossover and mutation. Without it,min_samples_split/min_samples_leafare only enforced when the initial population is created.ga_trees.ga.repair.repair_from_config(tree_config, X, y)builds one that collapses splits the constraints wouldn't allow.
Methods¶
evolve(X, y, verbose=True, X_val=None, y_val=None)¶
Run the evolution process.
Parameters:
X(np.ndarray): Training features; leaf predictions are fitted on thesey(np.ndarray): Training labelsverbose(bool): Log progressX_val,y_val(np.ndarray | None): Held-out data to score fitness on. Pass both or neither. Without them fitness is resubstitution (leaves fitted and scored on the same rows), which rewards whichever tree overfits hardest.
Returns:
TreeGenotype: Best individual found, by validation fitness when a validation set is given
Example:
import numpy as np
from sklearn.datasets import load_breast_cancer
from sklearn.model_selection import train_test_split
from ga_trees.fitness.calculator import FitnessCalculator
from ga_trees.ga.engine import GAConfig, GAEngine, Mutation, TreeInitializer
X, y = load_breast_cancer(return_X_y=True)
X_fit, X_val, y_fit, y_val = train_test_split(
X, y, test_size=0.25, stratify=y, random_state=0
)
n_features = X.shape[1]
ga_engine = GAEngine(
config=GAConfig(population_size=60, n_generations=30, random_state=42),
initializer=TreeInitializer(
n_features=n_features,
n_classes=2,
max_depth=5,
min_samples_split=10,
min_samples_leaf=5,
),
fitness_function=FitnessCalculator(
accuracy_weight=0.9, interpretability_weight=0.1
).calculate_fitness,
mutation=Mutation(
n_features=n_features,
feature_ranges={
i: (X_fit[:, i].min(), X_fit[:, i].max()) for i in range(n_features)
},
X=X_fit,
min_samples_leaf=5,
),
)
best_tree = ga_engine.evolve(X_fit, y_fit, X_val=X_val, y_val=y_val, verbose=False)
print(
f"Best validation fitness: {best_tree.fitness_:.4f}, {best_tree.get_num_nodes()} nodes"
)
get_history()¶
Get evolution history.
Returns:
dict: History with keys:best_fitness: List of best fitness per generationavg_fitness: List of average fitness per generationdiversity: List of population diversity (if tracked)
Example:
history = ga_engine.get_history()
import matplotlib.pyplot as plt
plt.plot(history["best_fitness"], label="Best")
plt.plot(history["avg_fitness"], label="Average")
plt.xlabel("Generation")
plt.ylabel("Fitness")
plt.legend()
plt.show()
See Genotype API for tree structure documentation.