msig 0.1.2

Statistical Significance Criteria for Multivariate Time Series Motifs

MSig

Statistical Significance Testing for Multivariate Time Series Motifs

MSig evaluates whether discovered motifs occur more frequently than expected by chance, using rigorous statistical methods.

Installation

Using uv (recommended)

# Clone the repository
git clone https://github.com/MiguelGarcaoSilva/msig.git
cd msig

# Sync dependencies (includes STUMPY and LAMA)
uv sync

# Optional: Install MOMENTI (for MOMENTI experiments - Linux/Windows only)
uv pip install git+https://github.com/aidaLabDEI/MOMENTI-motifs

Note: MOMENTI has platform-specific dependencies and may not install on macOS.

Using pip

# Clone repository
git clone https://github.com/MiguelGarcaoSilva/msig.git
cd msig

# Install with experiment dependencies (includes STUMPY, LAMA, and MOMENTI)
pip install -e ".[experiments]"

# Or install dependencies manually
pip install -e .
pip install stumpy  # For STUMPY experiments
pip install leitmotif  # For LAMA experiments
pip install git+https://github.com/aidaLabDEI/MOMENTI-motifs  # For MOMENTI experiments

Quick Start

from msig import Motif, NullModel
import numpy as np

# Your multivariate time series (m variables × n time points)
data = np.array([...])

# Create null model
model = NullModel(data, dtypes=[float, float], model="empirical")

# Test motif significance
motif = Motif(pattern, variables, thresholds, n_matches)
probability = motif.set_pattern_probability(model, vars_indep=True)
pvalue = motif.set_significance(max_possible_matches, n_variables)

print(f"p-value: {pvalue:.2e}")

See the examples/ folder for complete examples (simple_example.py and example.ipynb).

Running Experiments

The repository includes case studies on three datasets with three discovery methods (STUMPY, LAMA, MOMENTI):

# Run individual experiments
uv run python experiments/audio/run_stumpy.py
uv run python experiments/audio/run_lama.py
uv run python experiments/audio/run_momenti.py

uv run python experiments/populationdensity/run_stumpy.py
uv run python experiments/populationdensity/run_lama.py
uv run python experiments/populationdensity/run_momenti.py

uv run python experiments/washingmachine/run_stumpy.py
uv run python experiments/washingmachine/run_lama.py
uv run python experiments/washingmachine/run_momenti.py

Results are saved to results/<dataset>/<method>/.

Citation

@article{silva2024msig,
  title={On Why and How Statistical Significance Criteria Can Guide Multivariate Time Series Motif Analysis},
  author={Silva, Miguel G. and Henriques, Rui and Madeira, Sara C.},
  year={2024}
}

License

MIT License - see LICENSE file.