betaARMA: Beta Autoregressive Moving Average Models

This repository contains the R package betaARMA, a comprehensive toolkit for fitting, forecasting, and simulating Beta Autoregressive Moving Average models. It provides a unified workflow for modeling time series data bounded on the (0, 1) interval, such as rates, proportions, and indices.

---

Table of Contents

• Project Motivation
• Foundational Literature
• Key Features
• Repository Structure
• Installation
• Getting Started
• Citation
• Contributing
• License
• Contact

---

Project Motivation

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:

1. Unifies the workflow for $\beta$AR, $\beta$MA, and $\beta$ARMA specifications.
2. Ensures stability through numerical optimization with analytic gradients.
3. Provides a standard API consistent with popular time series tools (like forecast).

This project aims to fill that gap, serving as a go-to resource for hydrologists, economists, and data scientists working with bounded data.

---

Foundational Literature

This package implements the methodology established in the following key publications. The original code foundation was developed by Fabio M. Bayer and has been substantially optimized and refactored for this package.

• Rocha, A. V., & Cribari-Neto, F. (2009). "Beta autoregressive moving average models." TEST, 18(3), 529-545. doi:10.1007/s11749-008-0112-z
• Rocha, A. V., & Cribari-Neto, F. (2017). "Erratum to: Beta autoregressive moving average models." TEST, 26(2), 451-459. doi:10.1007/s11749-017-0528-4

Journal Quality Metrics (TEST)

• SJR (2024): 0.505 (Q2)
• H-Index: 52

---

Key Features

This package utilizes modern R development standards (S3 classes, roxygen2 documentation) to provide a seamless user experience.

• Unified Model Fitting: A single core function, barma(), handles any combination of AR and MA lags, as well as exogenous regressors (xreg).
• Estimation: Implements Conditional Maximum Likelihood Estimation (CMLE) using the BFGS algorithm with analytical gradients (score vectors) for improved convergence and speed.
• Correctness: Fully implements the corrections to the Information Matrix and Score Vector detailed in the 2017 Erratum.
• Standard S3 Methods: Works with standard R functions:
  • summary(): Detailed coefficients, standard errors, and significance tests.
  • forecast(): Multi-step-ahead point forecasts.
  • residuals(): Extraction of standardized residuals.
  • fitted(): Extraction of fitted values.

---

Repository Structure

The repository is structured as a standard R package for clarity and reproducibility.

.
├── R/                  # Source code for all R functions.
├── man/                # R package documentation files (generated by roxygen2).
├── tests/              # Unit tests (using testthat).
├── validation/         # Validation scripts comparing results to literature.
├── DESCRIPTION         # Package metadata and dependencies.
├── NAMESPACE           # Manages the package's namespace (generated by roxygen2).
├── LICENSE             # MIT License file.
└── README.md           # This file.

---

Code of Conduct

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.

Installation

You can install the development version of betaARMA directly from GitHub.

First, ensure you have the remotes package installed:

if (!require("remotes")) {
  install.packages("remotes")
}

Then, install the package:

remotes::install_github("Everton-da-Costa/betaARMA", 
                        dependencies = TRUE)

---

Getting Started

Here is a quick example of how to simulate data, fit a model, and generate forecasts.

library(betaARMA)

# 1. Simulate data from a BARMA(1,1) process
set.seed(123)
y <- simu_barma(n = 150, ar = 1, ma = 1, varphi = 0.5, theta = 0.3, phi = 20)

# 2. Fit the model
# We assume a fixed precision (phi) and logit link by default
fit <- barma(y, ar = 1, ma = 1)

# 3. Inspect results
summary(fit)

# 4. Forecast the next 6 steps
pred <- forecast(fit, h = 6)
print(pred)

---

Citation

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.0.0},
  url = {[https://github.com/Everton-da-Costa/betaARMA](https://github.com/Everton-da-Costa/betaARMA)},
}

Contributing

Contributions are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contact

For questions, suggestions, or issues related to the code, please contact:

Everton da Costa 📧 everto.cost@gmail.com