BEAST: Bayesian Change-Point Detection and Time-Series Decomposition

BEAST — the Bayesian Estimator of Abrupt change, Seasonality, and Trend — is a fast Bayesian model-averaging algorithm for decomposing time series and other one-dimensional sequential data into abrupt-change, trend, and seasonal/periodic components. BEAST is useful for:

• change-point detection: breakpoints, structural breaks, joinpoints, regime shifts, and anomalies;
• trend analysis and nonlinear trend detection;
• decomposition of trend and seasonal/periodic components (i.e., seasonal-Trend decomposition );
• time-series segmentation;
• interrupted time-series analysis;
• outlier detection;
• curve fitting and smotthing
• gap-filing of 1D curves

The algorithm is described in Zhao et al. (2019). Examples on the use of BEAST/Rbeast across remote sensing, ecology, hydrology, public health, finance, paleoclimate, and other fields are provided in <ins>selected publications using BEAST/Rbeast</ins>.

---

Contents

• Quick installation
• Quick examples
• Installation
  • R
  • Python
  • MATLAB
  • Octave
• Description of BEAST
• Notes on computation
• Compilation from C source code
• References
• Reporting bugs and requesting help
• Acknowledgements
• Selected publications using BEAST/Rbeast

---

Quick installation

BEAST is implemented in C/C++ as a package named Rbeast and is available through R, Python, MATLAB, and Octave interfaces.

| Interface | Installation command | |---|---| | Python | pip install Rbeast | | R | install.packages("Rbeast") | | MATLAB | eval(webread('http://b.link/rbeast', weboptions('cert',''))) | | Octave | eval(webread('http://b.link/rbeast')) |

---

Quick examples

Python

import Rbeast as rb

nile, year = rb.load_example("nile")
out = rb.beast(nile, start=1871, season="none")
rb.print(out)
rb.plot(out)

MATLAB / Octave

load('Nile.mat')
out = beast(Nile, 'start', 1871, 'season', 'none');
printbeast(out)
plotbeast(out)

R

library(Rbeast)

data(Nile)
out <- beast(Nile, season = "none")
print(out)
plot(out)

---

Installation

R <a name=r-id> </a>

Rbeast is available from CRAN. It is also listed in several CRAN Task Views, including Time Series Analysis, Bayesian inference, and Environmetrics. Install it from CRAN:

install.packages("Rbeast")

Note: CRAN also hosts another package named beast, which is unrelated to this project. The package described here is Rbeast. It is also unrelated to the evolutionary-analysis software BEAST, which stands for Bayesian Evolutionary Analysis by Sampling Trees.

Run and test Rbeast in R

The main R functions are beast(), beast.irreg(), and beast123().

library(Rbeast)

data(Nile)                          # Annual streamflow of the Nile River
out <- beast(Nile, season = "none") # Trend-only data without seasonality
print(out)
plot(out)

?Rbeast                            # See package documentation

<table border="0" style='border:none;' bordercolor="#ffffff" width=100% > <tr style='border:none;' > <td valign="center" style='border:none;' > <img height="300" align="left" src="https://github.com/zhaokg/Rbeast/raw/master/R/Images/beach.png"> </td> <td valign="center" style='border:none;' > <img height="300" align="center" src="https://github.com/zhaokg/Rbeast/raw/master/R/Images/Nile.png"> </td> </tr> </table>

The package also includes two small games:

tetris()                         # if you dare to waste a few moments of your life 
minesweeper()                    # if you dare to waste a few more moments of your life 

---

Python <a name=python-id></a>

Rbeast is available from PyPI at https://pypi.org/project/Rbeast/. Install the binary wheel package using:

pip install Rbeast

Binary wheel files are available for Windows, macOS, and Linux for common Python versions and CPU architectures. If the installation above from a wheel fails, install from source:

pip install Rbeast --no-binary :all:

Note: Building from source requires a C/C++ compiler, such as MinGW GCC on Windows, GNU GCC on Linux or Xcode/Clang on macOS. If needed, contact Kaiguang Zhao (zhao.1423@osu.edu) to help build the package for your OS platform and Python version.

Run and test Rbeast in Python

Nile is the annual streamflow of the River Nile, starting in 1871. Because these are annual observations, the series has no seasonal component.

import Rbeast as rb

nile, year = rb.load_example("nile")
out = rb.beast(nile, start=1871, season="none")
rb.print(out)
rb.plot(out)

out  # Show the output fields

The second example, googletrend, is a monthly time series of Google Search popularity for the word beach in the United States. It is regularly spaced and has a yearly periodic component. Since the time step is one month, there are 12 data points per year.

import Rbeast as rb

beach, year = rb.load_example("googletrend")

# Equivalent ways to specify a monthly time step and a yearly period
out = rb.beast(beach, start= 2004.0, deltat=1/12, period = 1.0)       # the time unit is unknown or arbitrary
out = rb.beast(beach, start= 2004.0, deltat=1/12, period ='1.0 year') # the time unit is fractional year
out = rb.beast(beach, start= 2004.0, deltat='1 month', period =1.0)   # the time unit is fractional year

rb.print(out)
rb.plot(out)

---

MATLAB <a name=matlab-id> </a>

Install the MATLAB version of BEAST automatically to a local folder of your choice:

beastPath = 'C:\beast';                 % Specify a target folder
eval(webread('http://b.link/rbeast'))   % Install to beastPath

If webread gives a certificate error, try:

beastPath = 'C:\beast';
eval(webread('http://b.link/rbeast', weboptions('cert','')))

Notes: <br/> - The above will automatically download the files in the Rbeast\Matlab folder at Github to the chosen local path <br/> - You need write permission for the folder specified by beastPath.<br/> - The variable name must be exactly beastPath.<br/> - If beastPath is not specified, the installer uses a temporary folder by default.<br/> - If automatic installation fails, manually download the MATLAB files from the Rbeast GitHub repository.<br/>

The MATLAB distribution includes:

• a compiled MEX binary bary library from the C/C++ soure code, such as Rbeast.mexw64 on Windows, Rbeast.mexa64 on Linux, or Rbeast.mexmaci64/Rbeast.mexmaca64 on macOS;
• MATLAB wrapper functions such as beast.m and beast123.m;
• example datasets such as Nile.mat and co2.mat.

Precompiled MEX binaries such as Rbeast.mexw64 and Rbeast.mexa64 are provided for Windows, Linux, and MacOS. If the included MEX binary does not work on your machine, you can compile it from the C source files in the Rbeast/Source folder. If needed, we are happy to work with you to compile for your specific machine. Additional information on compilations from the C source is also given below.

Run and test Rbeast in MATLAB

The MATLAB API is similar to those of R. Below is a quick example:

help beast
help beast123

load('Nile.mat')
out = beast(Nile, 'season', 'none', 'start', 1871);
printbeast(out)
plotbeast(out)

---

Octave <a name=octave-id> </a>

The Octave interface is similar to the MATLAB interface. Currently, the precompiled Octave version is primarily supported on Windows. For Octave on Linux or macOS, please contact Kaiguang Zhao at zhao.1423@osu.edu for assistance.

eval(webread('http://b.link/rbeast'))

---

Julia and IDL

Wrappers for Julia and IDL are under development. Contributions are welcome. Interested developers may contact Kaiguang Zhao at zhao.1423@osu.edu.

---

Description of BEAST

Interpreting time-series data is often affected by model choice. Different models can produce different, or even contradictory, estimates of trends, patterns, and mechanisms from the same data. BEAST addresses this limitation by moving away from a single-best-model strategy and using Bayesian model averaging across competing models.

BEAST is designed to detect abrupt changes, cyclic or seasonal variations, and nonlinear trends in time-series observations. It not only estimates when changes occur