Metadata-Version: 2.4
Name: msig
Version: 0.1.2
Summary: Statistical Significance Criteria for Multivariate Time Series Motifs
Author-email: "Miguel G. Silva" <mmsilva@ciencias.ulisboa.pt>
Maintainer-email: "Miguel G. Silva" <mmsilva@ciencias.ulisboa.pt>
License-Expression: MIT
Project-URL: Homepage, https://github.com/MiguelGarcaoSilva/msig
Project-URL: Repository, https://github.com/MiguelGarcaoSilva/msig
Project-URL: Documentation, https://github.com/MiguelGarcaoSilva/msig#readme
Project-URL: Bug Tracker, https://github.com/MiguelGarcaoSilva/msig/issues
Project-URL: Changelog, https://github.com/MiguelGarcaoSilva/msig/blob/main/CHANGELOG.md
Keywords: time-series,motif-discovery,statistical-significance,multivariate
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Provides-Extra: experiments
Requires-Dist: pandas>=1.3.0; extra == "experiments"
Requires-Dist: matplotlib>=3.4.0; extra == "experiments"
Requires-Dist: stumpy>=1.11.0; extra == "experiments"
Requires-Dist: librosa>=0.9.0; extra == "experiments"
Requires-Dist: statsmodels>=0.13.0; extra == "experiments"
Requires-Dist: jinja2>=3.0.0; extra == "experiments"
Requires-Dist: leitmotif; extra == "experiments"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Provides-Extra: all
Requires-Dist: msig[dev,experiments]; extra == "all"
Dynamic: license-file

# 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)

```bash
# 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

```bash
# 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

```python
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):

```bash
# 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

```bibtex
@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.


