The betaARMA package provides a comprehensive suite of
tools for fitting, diagnosing, and forecasting Beta Autoregressive
Moving Average models. These models are specifically tailored for time
series data that assume values in the standard unit interval (0, 1),
such as rates, proportions, and relative indices.
penalty
argument in barma() enables Penalized CMLE (PCMLE) as
proposed by Cribari-Neto, Costa, and Fonseca (2025). Addresses numerical
instability caused by flat log-likelihood surfaces in challenging data
structures.optimization
argument in barma(). Supported methods include
stats::optim (BFGS and L-BFGS-B with bounds) and
lbfgs::lbfgs.summary() method has been significantly upgraded. It now
outputs significance levels (stars) for coefficients, explicitly details
the optimization procedure and convergence status used, and reports the
\(\lambda\) penalty parameter when
ridge penalization is applied.plot() method
for barma objects displays a comprehensive diagnostic
grid.Modeling time series data bounded within the unit interval \((0, 1)\) presents unique challenges. Standard Gaussian methods (like ARIMA) are often inappropriate because they do not respect the natural boundaries of the data, potentially leading to fitted values or forecasts outside the admissible range.
The \(\beta\text{ARMA}\) model addresses this by assuming the conditional distribution of the variable follows a Beta law. While the theoretical foundations exist, there has been a need for a modern, robust R package that:
forecast).This project aims to fill that gap, serving as a go-to resource for hydrologists, economists, and data scientists working with bounded data.
The foundational methodology implemented in this package was published in TEST, journal in the fields of Statistics and Probability.
Key Publications:
penalty argument in
barma().This package utilizes modern R development standards (S3 classes, roxygen2 documentation) to provide a seamless user experience.
barma(), handles any combination of AR and MA lags,
exogenous regressors (xreg), and ridge penalization
(penalty = TRUE).BFGS,
L-BFGS-B, or lbfgs) utilizing
analytical gradients (score vectors) for improved
convergence and speed.logit,
cloglog, loglog, probit).summary(): Detailed coefficients, significance levels
(stars), optimization tracking, and penalization metrics.plot(): Six-panel diagnostic grid (observed vs. fitted,
residuals over time, ACF, PACF, Ljung-Box p-values, Monti p-values) via
which = ‘all’, or a four-panel default view.forecast(): Multi-step-ahead point forecasts.residuals(): Extraction of Pearson, quantile, raw, or
link-scale residuals.fitted(): Extraction of fitted values.loglik_barma(), score_vector_barma(),
fim_barma()) are exported for researchers who need direct
access to gradients or model internals.The repository is structured as a standard R package for clarity and reproducibility.
.
├── R/ # Source code for all R functions.
├── data/ # Processed data objects (e.g., brasilia_ts).
├── data-raw/ # Scripts and raw CSV files used to generate the datasets.
├── doc/ # Compiled HTML vignettes and extracted R code.
├── inst/ # Additional package files (CITATION, REFERENCES.bib).
├── man/ # R package documentation files (generated by roxygen2).
├── vignettes/ # R Markdown source files for vignettes.
├── DESCRIPTION # Package metadata and dependencies.
├── NAMESPACE # Manages the package's namespace (generated by roxygen2).
├── NEWS.md # Package changelog.
├── LICENSE # MIT License file.
├── betaARMA.Rproj # RStudio project file.
└── README.md # This file.You can install the stable version of betaARMA directly
from CRAN:
install.packages("betaARMA")You can install the development version from GitHub using the remotes package:
# install.packages("remotes")
remotes::install_github("Everton-da-Costa/betaARMA", dependencies = TRUE)The package includes a detailed vignette demonstrating a complete modeling workflow, including how to handle convergence failures using the penalized estimator.
To explore the application of betaARMA modeling on empirical data, check out the main vignette:
vignette("humidity_brasilia", package = "betaARMA")This vignette walks through a full analysis of monthly relative humidity in Brasília, Brazil. It highlights a specific lag specification where standard CMLE fails to converge. It demonstrates how applying the PCMLE (ridge-penalized) estimator achieves convergence, allows for valid model reduction, and ultimately produces a stable, well-specified model that passes all residual diagnostic tests.
Here is a quick example of how to simulate data, fit a model, and generate forecasts.
library(betaARMA)
# Example 1: Fit a BAR(1) model
# 1. Simulate data from a BAR(1) process
set.seed(2025)
y_sim_bar <- simu_barma(
n = 250,
alpha = 0.0,
varphi = 0.6,
phi = 25.0,
link = "logit",
freq = 12
)
# 2. Fit the model
fit_bar <- barma(y_sim_bar, ar = 1, link = "logit")
# 3. Inspect results
summary(fit_bar)
coef(fit_bar)
# 4. Diagnostic plots
plot(fit_bar)
# 5. Forecast the next 6 steps
pred_bar <- forecast(fit_bar, h = 6)
print(pred_bar)
# Example 2: Fit a BARMA(1,1) model using L-BFGS-B optimization
# 1. Simulate data from a BARMA(1,1) process
set.seed(2025)
y_sim_barma <- simu_barma(
n = 250,
alpha = 0.0,
varphi = 0.6,
theta = 0.3,
phi = 25,
link = "logit",
freq = 12
)
# 2. Fit the model explicitly using L-BFGS-B
fit_barma <- barma(
y_sim_barma,
ar = 1,
ma = 1,
link = "logit",
optimization = list(method = "L-BFGS-B")
)
# 3. Inspect results
summary(fit_barma)
coef(fit_barma)
# 4. Forecast the next 6 steps
pred_barma <- forecast(fit_barma, h = 6)
print(pred_barma)
# Example 3: Ridge-penalized estimation (PCMLE)
# Useful when standard CMLE produces implausible estimates.
fit_penalized <- barma(y_sim_barma, ar = 1, ma = 1, link = "logit", penalty = TRUE)
summary(fit_penalized)If you use this package in your research, please cite it as follows:
@Manual{,
title = {betaARMA: Beta Autoregressive Moving Average Models},
author = {Everton da Costa, Francisco Cribari-Neto and Vinícius T. Scher},
year = {2026},
note = {R package version 1.2.0},
doi = {10.32614/CRAN.package.betaARMA},
url = {https://CRAN.R-project.org/package=betaARMA}
}If you use the ridge penalization (penalty = TRUE),
please also cite:
@Article{Cribari_Costa_Fonseca2025,
title = {Numerical stability enhancements in beta autoregressive moving
average model estimation},
author = {Francisco Cribari-Neto and Everton Costa and Rodney V. Fonseca},
journal = {Brazilian Journal of Probability and Statistics},
year = {2025},
volume = {39},
number = {4},
pages = {410--437},
doi = {10.1214/25-BJPS645}
}If your application involves hydro-environmental modeling, please consider citing:
@Article{Costa_Cribari_Scher2024,
title = {Test inferences and link function selection in dynamic beta
modeling of seasonal hydro-environmental time series with
temporary abnormal regimes},
author = {Costa, E. and Cribari-Neto, F. and Scher, V. T.},
journal = {Journal of Hydrology},
year = {2024},
note = {forthcoming}
}Contributions are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.
This project is licensed under the MIT License. See
the LICENSE file for details.
For questions, suggestions, or issues related to the code, please contact:
Everton da Costa 📧 everto.cost@gmail.com
Please note that the betaARMA project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.