ALEA-R is an R package for hydrological frequency analysis.
It provides tools for exploratory summaries, probability distribution fitting, quantile estimation, bootstrap confidence intervals, goodness-of-fit assessment, sample diagnostics, AI-assisted distribution-selection support, batch analysis, publication-ready plots, and export helpers.
ALEA-R is available as a public GitHub release for applied hydrological frequency-analysis workflows, teaching, validation, and reproducible examples.
The package currently passes GitHub Actions R CMD check and local CRAN-oriented checks with 0 errors and 0 warnings. The latest local CRAN-oriented check produced 3 explainable notes: new submission, installed package size due to the bundled FADS_AI light model, and local inability to verify current time.
CRAN submission is intentionally deferred while the package is used more broadly through GitHub.
The public API is intentionally limited to the initial supported distribution families: GEV, GPA, PE3, LN2, LN3, and GUM. LP3 is not included in the current implementation.
FADS_AI output should be interpreted as model-based decision-support evidence, not as proof of the true generating distribution.
You can install the public GitHub release with:
# install.packages("remotes")
remotes::install_github(
"hydrostat/ALEA",
dependencies = TRUE,
upgrade = "never"
)If you also want the installed vignettes to be available through
utils::browseVignettes("ALEA"), install with build_vignettes = TRUE:
# install.packages("remotes")
remotes::install_github(
"hydrostat/ALEA",
dependencies = TRUE,
upgrade = "never",
build_vignettes = TRUE
)After installation, load the package with:
library(ALEA)ALEA-R supports:
- exploratory summaries for hydrological samples;
- fitting of probability distributions used in the FADS_AI selection study;
- quantile estimation;
- percentile bootstrap confidence intervals for quantiles;
- goodness-of-fit statistics and information criteria;
- sample diagnostics for data-quality and frequency-analysis assumptions;
- AI-assisted distribution-selection support;
- batch analysis for multiple stations or sites;
- ggplot-based plotting methods;
- plot and table export helpers.
The initial implementation supports six candidate distributions:
| Code | Distribution |
|---|---|
gev |
Generalized Extreme Value |
gpa |
Generalized Pareto |
pe3 |
Pearson type III |
ln2 |
Two-parameter lognormal |
ln3 |
Three-parameter lognormal |
gum |
Gumbel |
LP3 is not included in the initial implementation.
library(ALEA)
x <- c(
42.1, 38.5, 51.3, 47.0, 62.4,
55.2, 49.8, 58.1, 60.3, 45.7
)
fit <- alea_fit(
x,
distribution = "gev",
method = "lmom"
)
fit
coef(fit)Use alea_fit() for one distribution-method model, alea_compare() for
several models fitted to one hydrological series, and alea_batch_fit()
for several stations or sites.
cmp <- alea_compare(
x,
distributions = c("gev", "gum", "pe3"),
methods = c("lmom", "mle")
)
cmp
as.data.frame(cmp)
coef(cmp)For convenience, alea_fit() also returns an alea_compare object when
more than one distribution or method is supplied:
cmp <- alea_fit(
x,
distribution = c("gev", "gum", "pe3"),
method = c("lmom", "mle")
)Downstream workflows combine successful models automatically and align distribution-specific parameter columns, so users do not need to bind heterogeneous tables manually.
rl <- alea_quantile(cmp, return_period = c(10, 25, 50, 100))
gof <- alea_gof(cmp)
ci <- confint(
cmp,
parm = "quantile",
return_period = c(10, 25, 50, 100),
method = "bootstrap",
n_boot = 500,
seed = 123
)
plot(rl)
plot(ci)rl <- alea_quantile(
fit,
return_period = c(10, 25, 50, 100)
)
rl
plot(rl)ci <- confint(
fit,
parm = "quantile",
return_period = c(10, 25, 50, 100),
level = 0.95,
method = "bootstrap",
n_boot = 500,
seed = 123
)
ci
plot(ci)The initial implementation provides percentile bootstrap confidence intervals for quantiles. Parameter confidence intervals, asymptotic quantile intervals, and generic delta-method intervals are not implemented in the initial release.
gof <- alea_gof(fit)
gof
plot(gof, type = "statistic")
diagnostics <- alea_diagnostics(fit)
diagnostics
plot(diagnostics, type = "status")Goodness-of-fit results report empirical distribution function statistics and information criteria. Calibrated goodness-of-fit p-values and chi-square goodness-of-fit tests are deferred.
Diagnostics are sample-level checks intended to flag possible data-quality issues or assumption concerns. Diagnostic warnings do not automatically invalidate a fitted model.
selection <- alea_select(x)
selection
as.data.frame(selection)
plot(selection)ALEA-R includes AI-assisted distribution-selection support through the bundled FADS_AI lightweight operational application model.
FADS_AI output should be interpreted as model-based decision-support evidence for candidate distribution families. It is not proof of the true generating distribution and should not replace goodness-of-fit assessment, diagnostics, quantile uncertainty evaluation, or hydrological judgement.
batch <- alea_batch_fit(
data = annual_maxima,
station = "station",
time = "year",
value = "value",
distributions = c("gev", "gpa", "pe3", "ln2", "ln3", "gum"),
methods = c("lmom"),
return_period = c(10, 25, 50, 100),
gof = TRUE,
diagnostics = TRUE,
select = "ai"
)
alea_results(batch, "stations")
alea_results(batch, "fits")
alea_results(batch, "selected_models")
alea_results(batch, "quantiles")
alea_results(batch, "gof")
alea_results(batch, "diagnostics")
alea_results(batch, "errors")Batch workflows use structured error capture. A failure for one station, distribution, method, quantile calculation, goodness-of-fit calculation, diagnostic calculation, or selection step does not stop the full workflow.
All plot methods return ggplot objects.
p <- plot(fit, type = "quantile")
alea_save_plot(
p,
filename = "quantile_plot.png",
width = 7,
height = 5,
dpi = 300
)ALEA-R can also export data frames and flat batch result tables:
alea_export(rl, path = "quantiles.csv")
alea_export(batch, path = "batch_results", type = "all")Teaching-oriented ALEA-R workflow scripts are available in the
examples/ folder.
These examples use public Paraopeba hydrological data and demonstrate common frequency-analysis workflows:
- single-site frequency analysis;
- comparison of candidate distributions;
- quantiles and bootstrap confidence intervals;
- goodness-of-fit, diagnostics, and AI-assisted selection;
- small batch analysis;
- plots and exports.
Run the examples from the package root directory. For example:
source("examples/01_single_site_basic_workflow.R")The example data files are stored in:
examples/data/
Generated teaching outputs, such as exported plots and CSV files, are written to:
examples/output/
The examples are designed for learning and classroom use. They use only
the public ALEA-R API and the distributions supported in the current
release: gev, gpa, pe3, ln2, ln3, and gum.
Installed vignettes can be listed with:
utils::browseVignettes("ALEA")When installing from GitHub, use build_vignettes = TRUE if you want
these vignettes to be installed locally.
The initial implementation does not include:
- LP3;
- Portuguese API aliases;
- calibrated goodness-of-fit p-values;
- chi-square goodness-of-fit tests;
- parameter confidence intervals;
- asymptotic or delta-method quantile confidence intervals;
- HidroWeb data access in the core package.
Please cite ALEA-R in reports and publications where it supports the analysis.
citation("ALEA")