Symbolic Regression package built for Ecological Modelling.

What is it?

Leaf (Learning Equations for Automated Function discovery) is a symbolic regression (SR) framework designed to make equation discovery accessible and statistically robust for ecological applications.

Ecological systems involve complex, nonlinear relationships, but standard SR implementations often overfit, rarely evaluate model generality, or fail to handle the structured, hierarchical datasets common in ecology.

Leaf solves this by providing a complete workflow built on Multi-view Symbolic Regression (MvSR), which finds a single, generalizable equation structure that can be fitted to multiple groups (e.g., species, sites, archipelagos) independently.

The framework's key innovation is a four-stage workflow that rigorously separates equation discovery from model evaluation, ensuring that selected models are not just accurate but also interpretable and generalizable.

How the API works

The API is structured around the SymbolicRegressor class, which guides the user through the exact four-stage workflow described in the paper. The MinimalExample.py file provides a perfect illustration.

A typical analysis follows these steps:

1. Initialization: The user first creates a regressor, specifying the engine and loss function.

# Initialize the symbolic regressor
regressor = SymbolicRegressor(engine='rsrm', loss='PoissonDeviance')

2. Subset Generation (Paper Stage 1): The user generates the data subsets. The code provides helper functions for this, such as generate_group_subsets which implements the "leave-one-group-out" strategy mentioned in the paper.

# Stage 1: Generate subsets (e.g., leave-one-group-out)
folds = generate_group_folds(df, group_cols = 'species',
                                   n_splits = 'logo')

3. Equation Search (Paper Stage 2): The user calls search_equations. This is where the core discovery happens. The user provides the data, the formula, the normalization method, and the generated folds.

# Stage 2: Discover equation skeletons
regressor.search_equations(
    data=df,
    formula="y ~ f(A, T | species)",
    normalization='divide_by_gmd',
    folds=folds
)

4. Parameter Fitting (Paper Stage 3): The user calls fit_model_parameters. This method iterates over all unique equations found in the search step and fits their parameters. This can be done with or without cross-validation (using the do_cv=True flag).

# Stage 3: Fit parameters and compute loss
regressor.fit_model_parameters(data=df)

5. Evaluation (Paper Stage 4): The user calls evaluate_equations to compute any additional metrics (like PseudoR2 or Elbow) on the fitted models.

# Stage 4: Evaluate additional metrics
regressor.evaluate_equations(metrics=['PseudoR2', 'Elbow'])

6. Inspection: Finally, the user retrieves the results, typically by viewing the Pareto front.

# Show results
print(regressor.get_pareto_front())

More examples in the leaf/examples folder. Please see the API page (NOT CREATED YET) for more information on how to use the package.

Installation

You can install leaf package via pip:

pip install leaf

Core features

Formula Parsing: A user-friendly, R-style formula interface handles complex model specifications, including transformations and group-level parameters. S ~ f(log(Area), Age | species) tells Leaf to find an equation for S using log(Area) and Age as predictors, while fitting separate parameters for each species.

Modular Engine Backend: Leaf wraps several powerful SR engines, including PySR and RSRM (a reinforcement learning-based engine), plus a baseline Exhaustive GLM Search, and a way for the user to directly supply their own equations.

Classification Support: It provides a dedicated function that uses predicted probabilities and k-fold validation to identify the decision cutoff that maximizes a user-specified metric (e.g., the True Skill Statistic). This approach eliminates the need to manually tune thresholds.

Biological Constraints: Enforce biologically plausible constraints, forcing a predictor's effect to have a consistent sign (e.g., always positive) across all groups.

Principled Model Selection: Automatically calculates a Pareto front and an Elbow Metric to help you select the best, most parsimonious model from the complexity-performance trade-off.

Equation Inspection: Provides utilities to print any final equation in its full, un-normalized algebraic form for publication.

Model Management: The SymbolicRegressor object holds the entire state of your analysis. You can save, load, and even merge results from different runs.