Harbinger

Harbinger is a framework for event detection in time series. It offers a unified interface for anomaly detection, change-point detection, motif discovery, transformations, plotting, and evaluation. The package is designed to help users move from exploratory examples to reproducible experiment lines with less friction.

What you can study with Harbinger

• anomaly detection with statistical models, clustering, supervised learning, and deep autoencoders
• change-point detection with classical tests, segmentation methods, and ChangeFinder-based strategies
• motif and discord discovery with symbolic methods and Matrix Profile algorithms
• transformations such as smoothing and symbolic encoding before detection or pattern discovery
• hard and soft evaluation of detected events in univariate and multivariate series

Where to start

The examples are organized so that a new user can understand not only how to run a method, but also why that method is useful and what to look for in the result.

• Tutorials: a numbered guided path from first steps and data understanding to transformations, detection, evaluation, and motifs
• General examples: short guided tours of the package, utilities, and evaluation workflows
• Custom examples: extension-oriented notebooks showing how to plug custom detectors, transformations, and evaluation rules into Harbinger
• Dataset examples: how to load the full benchmark datasets, inspect their structure, and visualize the first available signal
• Transformation examples: smoothing and symbolic representations such as mas(), trans_sax(), and trans_xsax()
• Anomaly examples: detectors for isolated, contextual, collective, and multivariate anomalies
• Change-point examples: examples focused on regime shifts, structural breaks, and volatility changes
• Motif examples: repeated-pattern discovery and discord analysis with symbolic and Matrix Profile approaches

A first example

The snippet below uses the default harbinger() pipeline on a bundled dataset. It is intentionally short so that new users can see the core workflow before exploring the more detailed notebooks in /examples/.

library(harbinger)
library(dplyr)

# Load an example dataset with labeled anomalies
data(examples_anomalies)

# Create the default detector and run it on the series
model <- harbinger()
detection <- detect(model, examples_anomalies$simple$serie)

# Inspect only the detected events
print(detection |> dplyr::filter(event == TRUE))

Installation

The latest release of Harbinger is available on CRAN:

install.packages("harbinger")

To install the development version from GitHub:

library(devtools)
devtools::install_github("cefet-rj-dal/harbinger", force = TRUE, upgrade = "never")

Learn the examples progressively

If you are new to the package, this order works well:

1. start with /examples/tutorial/README.md for the guided path
2. continue with /examples/general/examples_harbinger.md if you want a compact package tour
3. visit /examples/data/README.md to understand the benchmark datasets and how to load their full versions
4. visit /examples/transformations/README.md to see smoothing and symbolic representations before modeling
5. move to one family of methods such as anomalies or change points
6. visit /examples/custom/README.md when you want to see how new components can be integrated into the framework
7. finish with /examples/motifs/README.md when you want to study repeated patterns and symbolic sequence analysis

Bug reports and feature requests

If you find a bug or want to suggest an improvement, please open an issue:

https://github.com/cefet-rj-dal/harbinger/issues