
<!-- README.md is generated from README.Rmd. Please edit that file -->

# leaf

<!-- badges: start -->
<!-- badges: end -->

**leaf** (Learning Equations for Automated Function discovery) is an R
package for symbolic regression designed for ecological modelling. It
discovers interpretable mathematical equations from data using a
principled four-stage workflow — separating equation discovery from
model evaluation — to ensure selected models are accurate, parsimonious,
and generalizable.

leaf wraps powerful SR engines including
[PySR](https://github.com/MilesCranmer/PySR) and
[RSRM](https://github.com/intell-sci-comput/RSRM), and is built around
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.

## Installation

You can install leaf from CRAN with:

``` r
install.packages("leaf")
```

After installing, you need to install the Python backend once:

``` r
library(leaf)
leaf::install_leaf()
```

## Example

``` r
library(leaf)

# Initialize a symbolic regressor
regressor <- SymbolicRegressor$new(
  engine = "rsrm",
  loss = "MSE"
)

# Search for candidate equations
train_data <- leaf_data("eg_train")
regressor$search_equations(
  data = train_data,
  formula = "y ~ f(x1, x2)"
)

# Fit parameters and evaluate
regressor$fit(data = train_data)
regressor$evaluate(metrics = c("RMSE", "R2"), data = leaf_data("eg_test"))

# Inspect results
print(regressor$get_pareto_front())
```

## Core features

- **Formula interface**: R-style formula syntax supporting
  transformations and group-level parameters,
  e.g. `S ~ f(log(Area), Age | species)`
- **Multiple SR engines**: Wraps PySR, RSRM, and a baseline Exhaustive
  GLM Search
- **Multi-view Symbolic Regression**: Finds equations that generalise
  across groups
- **Classification support**: Includes sigmoid-based classification with
  cross-validated threshold selection
- **Biological constraints**: Enforce sign consistency of predictor
  effects across groups
- **Principled model selection**: Pareto front and Elbow Metric for
  complexity-performance trade-offs
- **Equation inspection**: Print final equations in full un-normalised
  algebraic form
- **Model management**: Save, load, and merge results across runs

## Documentation

See the vignettes for detailed usage:

- `vignette("getting_started", package = "leaf")`
- `vignette("minimal_example", package = "leaf")`
- `vignette("cross_validation", package = "leaf")`
- `vignette("MvSR", package = "leaf")`

## Citation

A citation will be available once the accompanying paper is published.

## Acknowledgements

This work was developed at INESC-ID and supported by national funds
through FCT - Fundação para a Ciência e a Tecnologia, under project
\[REF\].
