{"id":50124171,"url":"https://github.com/hydrostat/alea","last_synced_at":"2026-05-23T19:00:45.619Z","repository":{"id":359531375,"uuid":"1246486160","full_name":"hydrostat/ALEA","owner":"hydrostat","description":"R package for hydrological frequency analysis with distribution fitting, return levels, diagnostics, AI-assisted selection, batch analysis, and publication-ready plots.","archived":false,"fork":false,"pushed_at":"2026-05-22T11:20:21.000Z","size":3952,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T15:58:13.506Z","etag":null,"topics":["ai-assisted","extreme-values","frequency-analysis","goodness-of-fit","hydrology","r","r-package","statistical-hydrology"],"latest_commit_sha":null,"homepage":"","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hydrostat.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-22T08:36:59.000Z","updated_at":"2026-05-22T11:41:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hydrostat/ALEA","commit_stats":null,"previous_names":["hydrostat/alea"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hydrostat/ALEA","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hydrostat%2FALEA","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hydrostat%2FALEA/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hydrostat%2FALEA/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hydrostat%2FALEA/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hydrostat","download_url":"https://codeload.github.com/hydrostat/ALEA/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hydrostat%2FALEA/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33408490,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T18:09:33.147Z","status":"ssl_error","status_checked_at":"2026-05-23T18:09:31.380Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-assisted","extreme-values","frequency-analysis","goodness-of-fit","hydrology","r","r-package","statistical-hydrology"],"created_at":"2026-05-23T19:00:25.163Z","updated_at":"2026-05-23T19:00:45.609Z","avatar_url":"https://github.com/hydrostat.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\n```\n\n# ALEA-R\n\n[![R-CMD-check](https://github.com/hydrostat/ALEA/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/hydrostat/ALEA/actions/workflows/R-CMD-check.yaml)\n\nALEA-R is an R package for hydrological frequency analysis.\n\nIt provides tools for exploratory summaries, probability distribution fitting,\nreturn-level estimation, bootstrap confidence intervals, goodness-of-fit\nassessment, sample diagnostics, AI-assisted distribution-selection support,\nbatch analysis, publication-ready plots, and export helpers.\n\n## Project status\n\nALEA-R is available as a public GitHub release for applied hydrological\nfrequency-analysis workflows, teaching, validation, and reproducible examples.\n\nThe package currently passes GitHub Actions R CMD check and local CRAN-oriented\nchecks with 0 errors and 0 warnings. The latest local CRAN-oriented check\nproduced 3 explainable notes: new submission, installed package size due to the\nbundled FADS_AI light model, and local inability to verify current time.\n\nCRAN submission is intentionally deferred while the package is used more\nbroadly through GitHub.\n\nThe public API is intentionally limited to the initial supported distribution\nfamilies: GEV, GPA, PE3, LN2, LN3, and GUM. LP3 is not included in the current\nimplementation.\n\nFADS_AI output should be interpreted as model-based decision-support evidence,\nnot as proof of the true generating distribution.\n\n## Installation\n\nYou can install the public GitHub release with:\n\n```{r installation, eval = FALSE}\n# install.packages(\"remotes\")\nremotes::install_github(\n  \"hydrostat/ALEA\",\n  dependencies = TRUE,\n  upgrade = \"never\"\n)\n```\n\nIf you also want the installed vignettes to be available through\n`utils::browseVignettes(\"ALEA\")`, install with `build_vignettes = TRUE`:\n\n```{r installation-vignettes, eval = FALSE}\n# install.packages(\"remotes\")\nremotes::install_github(\n  \"hydrostat/ALEA\",\n  dependencies = TRUE,\n  upgrade = \"never\",\n  build_vignettes = TRUE\n)\n```\n\nAfter installation, load the package with:\n\n```{r load-package, eval = FALSE}\nlibrary(ALEA)\n```\n\n## Main features\n\nALEA-R supports:\n\n- exploratory summaries for hydrological samples;\n- fitting of probability distributions used in the FADS_AI selection study;\n- return-level estimation;\n- percentile bootstrap confidence intervals for return levels;\n- goodness-of-fit statistics and information criteria;\n- sample diagnostics for data-quality and frequency-analysis assumptions;\n- AI-assisted distribution-selection support;\n- batch analysis for multiple stations or sites;\n- ggplot-based plotting methods;\n- plot and table export helpers.\n\n## Supported distributions\n\nThe initial implementation supports six candidate distributions:\n\n| Code | Distribution |\n|---|---|\n| `gev` | Generalized Extreme Value |\n| `gpa` | Generalized Pareto |\n| `pe3` | Pearson type III |\n| `ln2` | Two-parameter lognormal |\n| `ln3` | Three-parameter lognormal |\n| `gum` | Gumbel |\n\nLP3 is not included in the initial implementation.\n\n## Basic workflow\n\n```{r basic-workflow, eval = FALSE}\nlibrary(ALEA)\n\nx \u003c- c(\n  42.1, 38.5, 51.3, 47.0, 62.4,\n  55.2, 49.8, 58.1, 60.3, 45.7\n)\n\nfit \u003c- alea_fit(\n  x,\n  distribution = \"gev\",\n  method = \"lmom\"\n)\n\nfit\ncoef(fit)\n```\n\n## Return levels\n\n```{r return-levels, eval = FALSE}\nrl \u003c- alea_return_level(\n  fit,\n  return_period = c(10, 25, 50, 100)\n)\n\nrl\nplot(rl)\n```\n\n## Bootstrap confidence intervals\n\n```{r bootstrap-ci, eval = FALSE}\nci \u003c- confint(\n  fit,\n  parm = \"return_level\",\n  return_period = c(10, 25, 50, 100),\n  level = 0.95,\n  method = \"bootstrap\",\n  n_boot = 500,\n  seed = 123\n)\n\nci\nplot(ci)\n```\n\nThe initial implementation provides percentile bootstrap confidence intervals\nfor return levels. Parameter confidence intervals, asymptotic return-level\nintervals, and generic delta-method intervals are not implemented in the\ninitial release.\n\n## Goodness-of-fit and diagnostics\n\n```{r gof-diagnostics, eval = FALSE}\ngof \u003c- alea_gof(fit)\ngof\nplot(gof, type = \"statistic\")\n\ndiagnostics \u003c- alea_diagnostics(fit)\ndiagnostics\nplot(diagnostics, type = \"status\")\n```\n\nGoodness-of-fit results report empirical distribution function statistics and\ninformation criteria. Calibrated goodness-of-fit p-values and chi-square\ngoodness-of-fit tests are deferred.\n\nDiagnostics are sample-level checks intended to flag possible data-quality\nissues or assumption concerns. Diagnostic warnings do not automatically\ninvalidate a fitted model.\n\n## AI-assisted distribution selection\n\n```{r ai-selection, eval = FALSE}\nselection \u003c- alea_select(x)\n\nselection\nas.data.frame(selection)\nplot(selection)\n```\n\nALEA-R includes AI-assisted distribution-selection support through the bundled\nFADS_AI lightweight operational application model.\n\nFADS_AI output should be interpreted as model-based decision-support evidence\nfor candidate distribution families. It is not proof of the true generating\ndistribution and should not replace goodness-of-fit assessment, diagnostics,\nreturn-level uncertainty evaluation, or hydrological judgement.\n\n## Batch analysis\n\n```{r batch-analysis, eval = FALSE}\nbatch \u003c- alea_batch_fit(\n  data = annual_maxima,\n  station = \"station\",\n  time = \"year\",\n  value = \"value\",\n  distributions = c(\"gev\", \"gpa\", \"pe3\", \"ln2\", \"ln3\", \"gum\"),\n  methods = c(\"lmom\"),\n  return_period = c(10, 25, 50, 100),\n  gof = TRUE,\n  diagnostics = TRUE,\n  select = \"ai\"\n)\n\nalea_results(batch, \"stations\")\nalea_results(batch, \"fits\")\nalea_results(batch, \"selected_models\")\nalea_results(batch, \"return_levels\")\nalea_results(batch, \"gof\")\nalea_results(batch, \"diagnostics\")\nalea_results(batch, \"errors\")\n```\n\nBatch workflows use structured error capture. A failure for one station,\ndistribution, method, return-level calculation, goodness-of-fit calculation,\ndiagnostic calculation, or selection step does not stop the full workflow.\n\n## Plotting and export\n\nAll plot methods return `ggplot` objects.\n\n```{r plots, eval = FALSE}\np \u003c- plot(fit, type = \"return_level\")\n\nalea_save_plot(\n  p,\n  filename = \"return_level_plot.png\",\n  width = 7,\n  height = 5,\n  dpi = 300\n)\n```\n\nALEA-R can also export data frames and flat batch result tables:\n\n```{r export, eval = FALSE}\nalea_export(rl, path = \"return_levels.csv\")\nalea_export(batch, path = \"batch_results\", type = \"all\")\n```\n\n## Learning examples\n\nTeaching-oriented ALEA-R workflow scripts are available in the `examples/`\nfolder.\n\nThese examples use public Paraopeba hydrological data and demonstrate common\nfrequency-analysis workflows:\n\n- single-site frequency analysis;\n- comparison of candidate distributions;\n- return levels and bootstrap confidence intervals;\n- goodness-of-fit, diagnostics, and AI-assisted selection;\n- small batch analysis;\n- plots and exports.\n\nRun the examples from the package root directory. For example:\n\n```{r learning-examples-source, eval = FALSE}\nsource(\"examples/01_single_site_basic_workflow.R\")\n```\n\nThe example data files are stored in:\n\n```text\nexamples/data/\n```\n\nGenerated teaching outputs, such as exported plots and CSV files, are written to:\n\n```text\nexamples/output/\n```\n\nThe examples are designed for learning and classroom use. They use only the\npublic ALEA-R API and the distributions supported in the current release:\n`gev`, `gpa`, `pe3`, `ln2`, `ln3`, and `gum`.\n\nInstalled vignettes can be listed with:\n\n```{r browse-vignettes, eval = FALSE}\nutils::browseVignettes(\"ALEA\")\n```\n\nWhen installing from GitHub, use `build_vignettes = TRUE` if you want these\nvignettes to be installed locally.\n\n## Current limitations\n\nThe initial implementation does not include:\n\n- LP3;\n- Portuguese API aliases;\n- calibrated goodness-of-fit p-values;\n- chi-square goodness-of-fit tests;\n- parameter confidence intervals;\n- asymptotic or delta-method return-level confidence intervals;\n- HidroWeb data access in the core package.\n\n## Citation\n\nPlease cite ALEA-R in reports and publications where it supports the analysis.\n\n```{r citation, eval = FALSE}\ncitation(\"ALEA\")\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhydrostat%2Falea","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhydrostat%2Falea","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhydrostat%2Falea/lists"}