Harbinger

CRAN Downloads

Harbinger is an R framework for time series event detection. It provides a unified interface for anomaly detection, change-point detection, motif discovery, discord discovery, transformations, plotting, online execution, and event-oriented evaluation.

Time-series event analysis is rarely a matter of calling one isolated function. In practice, the analyst needs to understand the signal, choose a suitable family of methods, inspect the result visually, and evaluate whether the detected events actually correspond to the phenomenon of interest. Harbinger supports this full learning and experimentation path with consistent method APIs and reusable experiment workflows.

Current package version in this repository: 2.1.707.

Installation

The stable version is available on CRAN:

https://CRAN.R-project.org/package=harbinger

install.packages("harbinger")

The development version is available on GitHub:

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

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

Documentation

Documentation and examples are available in the package site and in the repository:

The documentation is organized around two complementary entry points:

a guided tutorial track for readers who want to learn the workflow step by step
thematic example collections for readers who want to inspect a specific family of methods

If you are new to harbinger, start with the tutorials. If you already know the basic workflow, the thematic collections provide focused examples by event type, data source, transformation, and execution mode.

Guided Tutorial Track

The tutorials are part of the examples collection. They form a 10-part learning sequence covering first contact with the package, data inspection, plotting, baseline anomaly detection, residual-based detection, evaluation, change points, smoothing, symbolic transformations, and motif analysis.

The sequence is cumulative. It introduces event detection through small workflows before moving to richer event families and representations.

Thematic Example Collections

The examples collection includes thematic subcollections:

General examples - package orientation, utility helpers, candidate selection, deviation measures, filtering criteria, and evaluation objects.
Dataset examples - benchmark archives and domain datasets, including Yahoo, NAB, UCR, MIT-BIH, 3W oil well, and GECCO-style datasets.
Transformation examples - smoothing and symbolic encodings that prepare a series for later anomaly, change-point, motif, or discord analysis.
Anomaly examples - anomaly detection methods grouped from simple baselines to residual models, machine-learning detectors, clustering, ensembles, autoencoders, and multivariate workflows.
Change-point examples - change-point methods ordered from single-break intuition to multiple-break, structural-break, probabilistic, volatility-oriented, streaming, ensemble, and online detectors.
Motif examples - repeated-pattern and discord analysis grouped into Matrix Profile, symbolic, and discord-oriented studies.
Online examples - online execution with sources, sessions, memory policies, batch traces, experiment grids, and the Kafka integration boundary.
Custom examples - extension-oriented notebooks showing how to plug new transformations, detectors, motif methods, and evaluators into Harbinger.

Main Capabilities

Unified abstractions for event detectors, transformations, ensembles, evaluators, online sessions, and data sources.
Anomaly detection through statistical, residual, machine-learning, clustering, discord, ensemble, autoencoder, and multivariate approaches.
Change-point detection through single-break, multiple-break, structural-break, probabilistic, volatility, streaming, and online approaches.
Motif and discord discovery using Matrix Profile and symbolic representations.
Time series transformations including moving average smoothing, SAX, and extended SAX.
Event-oriented visualization and evaluation, including strict and soft evaluation protocols.
Online execution abstractions for simulated, dataframe, callback, and Kafka-oriented sources.

A First Example

The snippet below uses the default harbinger() pipeline on a bundled dataset. It is intentionally short so that a new reader can see the minimum workflow before moving to the more didactic notebooks in examples/.

library(harbinger)

# 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
subset(detection, event == TRUE)

Suggested Learning Order

Start with the tutorials in the examples collection to understand the basic workflow.
Continue with the general examples for package scope, utilities, and evaluation.
Visit the dataset examples before choosing a method.
Visit the transformation examples to see how smoothing and symbolic encodings change the signal.
Move to one modeling family, usually anomaly examples or change-point examples.
Study motif examples after you are comfortable with subsequences, windows, and symbolic representations.
Explore online examples when moving from offline analysis to stream-oriented detection.
Finish with custom examples when you want to integrate your own components into the framework.

Course Material

The public course material includes a compact slide sequence that introduces Harbinger and demonstrates the main package workflows: overview, tutorial, general workflow, datasets, transformations, anomalies, change points, motifs, and custom extensions.

Related DAL Projects

Playlist

Harbinger videos

Slides and Videos

Slide decks - one presentation per topic, indexed in examples/slides/README.md.
Video index - one entry per published video, indexed in examples/videos/README.md.

Bug Reports and Feature Requests

Please report bugs, questions, and feature requests at:

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