# Getting started with leafareaR

# Overview

`leafareaR` provides a workflow for leaf area analysis based on leaf length (`L`), leaf width (`W`), and observed leaf area (`LA`). The package includes tools for input validation, predictor generation, model fitting, model evaluation and ranking, equation extraction, prediction, graphics, and an interactive Shiny application.

A typical analysis in `leafareaR` follows six steps:

1. validate the input data;
2. generate derived predictors;
3. fit candidate models;
4. evaluate and rank the fitted models;
5. inspect the selected equation;
6. generate predictions and graphics.

# Example dataset

The package includes a sample dataset named `leafarea_sample`. The example below shows only the core variables used in most analyses.

    kable(leafarea_sample[1:6, c("L", "W", "LA")], digits = 3)

L | W | LA
--- | --- | ---
7.539 | 0.974 | 4.878
6.423 | 1.304 | 6.032
5.960 | 3.128 | 10.663
4.041 | 2.159 | 5.750
8.492 | 1.920 | 9.030
4.680 | 2.184 | 6.846

Additional grouping variables such as `block`, `species`, and `genotype` may also be present and can be used in mixed-model workflows.

# Data preparation

The first step is to validate the required variables and, when needed, create derived predictors from `L` and `W`.

    dat <- la_validate_input(leafarea_sample)

    dat2 <- la_create_derived(
      dat,
      variables = c("LW", "L2", "W2", "L3", "W3", "L_plus_W")
    )

A compact descriptive summary of selected variables is shown below.

    kable(desc_out, digits = 3)

Variable | Mean | SD | Min | Max
--- | --- | --- | --- | ---
L | 5.871 | 2.144 | 1.454 | 13.892
W | 2.165 | 1.146 | 0.238 | 6.572
LA | 8.600 | 6.631 | 1.000 | 48.671
LW | 13.848 | 11.170 | 1.275 | 76.265

# A linear modeling workflow

Linear candidate models can be fitted directly from the prepared data and then ranked according to the selected evaluation criteria.

    fit_linear <- la_fit_linear_models(dat2)
    met_linear <- la_evaluate_linear_models(fit_linear)
    ranked_linear <- la_rank_models(met_linear)

For illustration, the next table shows only the three best-ranked linear models.

    kable(top_linear_out, digits = 4)

Model | RMSE | MAE | R2 | AIC
--- | --- | --- | --- | ---
lm_full_poly3 | 1.1985 | 0.6587 | 0.9673 | 32014.47
lm_full_poly2 | 1.2014 | 0.6598 | 0.9672 | 32059.03
lm_L_plus_W_plus_LW | 1.2028 | 0.6611 | 0.9671 | 32078.25

In this example, the top-ranked model is lm_full_poly3.

# Equation extraction

A readable equation can be obtained from the selected model.

    cat(best_equation)

LA = -0.1013 - 0.3075 * L + 0.8508 * W + 0.4653 * L × W + 0.0939 * L² - 0.0853 * W² - 0.0042 * L³ + 0.0142 * W³

This equation can be reported directly or used as the basis for prediction.

# Prediction

Predictions can be generated from the top-ranked model for a new set of observations.

    pred <- la_predict_top_ranked(
      ranked_table = ranked_linear,
      fit_object = fit_linear,
      rank_position = 1,
      newdata = dat2[1:10, ]
    )

A small subset of the prediction output is shown below.

    kable(pred_out, digits = 4)

Observed LA | Predicted LA | Residual
--- | --- | ---
4.878 | 5.2823 | -0.4043
6.032 | 5.5693 | 0.4627
10.663 | 11.4407 | -0.7777
5.750 | 5.5514 | 0.1986
9.030 | 10.4746 | -1.4446
6.846 | 6.4371 | 0.4089

# Graphics

The package also includes simple graphics for exploratory analysis and model inspection.

## Scatter plot

    la_plot_scatter(dat2, x = "LW", y = "LA")

## Observed versus predicted values

    la_plot_observed_predicted(
      observed = vals$observed,
      predicted = vals$fitted,
      model_name = best_id
    )

# Extensions to nonlinear and mixed models

The same general strategy can be extended to nonlinear and mixed models: fit, evaluate, rank, inspect the selected equation, and predict.

    fit_nonlinear <- la_fit_nonlinear_models(dat2, models = c("power_LW"))
    met_nonlinear <- la_evaluate_nonlinear_models(fit_nonlinear)
    ranked_nonlinear <- la_rank_models(met_nonlinear)

    fit_mixed <- la_fit_mixed_models(dat2, group_var = "species")
    met_mixed <- la_evaluate_mixed_models(fit_mixed)
    ranked_mixed <- la_rank_models(met_mixed)

# Interactive use

`leafareaR` also provides a Shiny application for interactive analysis.

    run_leafareaR_app()

The application can be used to load the built-in example dataset (`leafarea_sample`) or upload your own data, then select predictors, fit and compare candidate models, inspect equations, and export results and graphics.

# Summary

`leafareaR` provides a reproducible workflow for leaf area analysis, from data preparation to model comparison, equation reporting, prediction, and visualization. The package can be used both in script-based analyses and through its interactive Shiny interface.