BEAST: A Bayesian Ensemble Algorithm for Change-Point Detection and Time Series Decomposition

BEAST (Bayesian Estimator of Abrupt change, Seasonality, and Trend) is a fast, generic Bayesian model averaging algorithm to decompose time series or 1D sequential data into individual components, such as abrupt changes, trends, and periodic/seasonal variations, as described in <ins>Zhao et al. (2019)</ins>. BEAST is useful for changepoint detection (e.g., breakpoints, structural breaks, joinpoints, regime shifts, or anomalies), trend analysis, time series decomposition (e.g., trend vs seasonality), time series segmentation, and interrupted time series analysis. See a list of <a href="#publicationid"> selected studies using BEAST </a>.

Quick Installation

BEAST was impemented in C/C++ but accessible from R, Python, Matlab, and Octave. Install it as follows:

Python: pip install Rbeast
Matlab: eval(webread('http://b.link/rbeast',weboptions('cert','')))
Octave: eval(webread('http://b.link/rbeast'))
R lang: install.packages("Rbeast")

Quick Usage

One-liner code for Python, Matlab and R:

# Python example
import Rbeast as rb; (Nile, Year)=rb.load_example('nile'); o=rb.beast(Nile,season='none'); rb.plot(o)

# Matlab/Octave example
load('Nile'); o = beast(Nile, 'season','none'); plotbeast(o)

# R example
library(Rbeast); data(Nile); o = beast(Nile); plot(o)

Installation for R <a name=r> </a>

<p align="left"> <a href= "https://cran.r-project.org/package=Rbeast"> <img src="https://www.r-pkg.org/badges/version/Rbeast?color=green" height="20"> <img src="https://cranlogs.r-pkg.org/badges/grand-total/Rbeast?color=green" height="20"> <img src="https://img.shields.io/static/v1?style=plastic&logo=r&label=Rbeast%20%20&message= In CRAN-Task-View&color=brightgreen" height="20"> </a> </p>

Rbeast in CRAN-TASK-VIEW: <a href="https://cran.r-project.org/web/views/TimeSeries.html#forecasting-and-univariate-modeling">[Time Series Analysis]</a> <a href="https://cran.r-project.org/web/views/Bayesian.html#time-series-models">[Bayesian inference]</a> <a href="https://cran.r-project.org/web/views/Environmetrics.html#environmental-time-series">[Environmetrics]</a>

An R package Rbeast has been deposited at CRAN. ( On CRAN, there is another Bayesian time-series package named "beast", which has nothing to do with the BEAST algorithim. Our package is Rbeast. Also, Rbeast has nothing to do with the famous "Bayesian evolutionary analysis by sampling trees" aglorithm.) Install Rbeast in R using

install.packages("Rbeast")

Run and test Rbeast in R

The main functions in Rbeast are beast(Y, ...), beast.irreg(Y, ...), and beast123(Y, metadata, prior, mcmc, extra). The code snippet below provides a starting point for the basic usage.

library(Rbeast)
data(Nile)                       #  annual streamflow of the Nile River    
out = beast(Nile, season='none') #  'none': trend-only data without seasonlaity   
print(out)                   
plot(out)
?Rbeast                          # See more details about the usage of `beast`    
     
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

Installation for Matlab <a name=matlab> </a>

Install the Matlab version of BEAST automatically to a local folder of your choice by running

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

%%%%%%%%%%%%%%%%%%%%%%%%%%% Note on Automatic Installtion %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 
% 1. Write permission needed for your chosen path; the variable name must be 'beastPath'.   %
% 2. If webread has a certificate error, run the following line instead:                    %
    eval(  webread( 'http://b.link/rbeast', weboptions('cert','') )  )                       %
% 3. If the automatic installation fails, please manually download all the files (see blow) %       
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

The above will download all the files in the Rbeast\Matlab folder at Github to the chosen folder: if beastPath is missing, a default temporary folder (e.g., C:\Users\$user_name$\AppData\Local\Temp\Rbeast for Windows 10) will be used. If the automatic script fails, please download the Matlab files from Github manually. These files include a Matlab mex library compiled from the C soure code (e.g., Rbeast.mexw64 for Windows, Rbeast.mexa64 for Linux, Rbeast.mexmaci64 for MacOS) and some Matlab wrapper functions (e.g.,beast.m, and beast123.m) similar to the R interface, as well as some test datasets (e.g., Nile.mat, and co2.mat).

We generated the Matlab mex binary library on our own machines with Win10, Ubuntu 22.04, and macOS High Sierra. If they fail on your machine, the mex library can be compiled from the C source code files under Rbeast\Source. If needed, we are happy to work with you to compile for your specific OS or machines. 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')                                   % annual streamflow of the Nile River startin from year 1871
 out = beast(Nile, 'season', 'none','start', 1871)  % trend-only data without seasonality
 printbeast(out)
 plotbeast(out)

Installation for Octave <a name=octave> </a>

The same as for Matlab. Now, only Windows platforms are supported. If needed for other platforms (e.g., Octave in Linux and Mac), please contact the author at zhao.1423@osu.edu for support.

Installation for Python <a name=python> </a>

A package Rbeast has been deposited at PyPI: https://pypi.org/project/Rbeast/. Run the command below in a console to install:

  pip install Rbeast

Binary wheel files were built on Windows, MacOS, and Linux for Python version 3.7 to 3.11 (either x86_64 or arm64 CPU)

Rbeast

Install / Use

README