# 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
### From PyPI (recommended)
```bash
# Core package only
pip install msig
# With experiment dependencies (includes STUMPY and LAMA)
pip install "msig[experiments]"
```
### From source with uv
```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
```
### From source with pip
```bash
# Clone repository
git clone https://github.com/MiguelGarcaoSilva/msig.git
cd msig
# Install with experiment dependencies
pip install -e ".[experiments]"
```
**Notes**:
- MOMENTI has platform-specific dependencies and may not install on macOS.
- Audio experiments require **ffmpeg** for MP3 processing: `brew install ffmpeg` (macOS) or `apt-get install ffmpeg` (Linux)
## Quick Start
```python
from msig import Motif, NullModel
import numpy as np
# Create sample multivariate time series (3 sensors × 100 time points)
np.random.seed(42)
t = np.linspace(0, 10, 100)
sensor1 = 10 + 2 * np.sin(2 * np.pi * t) + np.random.randn(100) * 0.5
sensor2 = 5 + 1.5 * np.cos(2 * np.pi * t) + np.random.randn(100) * 0.3
sensor3 = 15 + 3 * np.sin(2 * np.pi * t + np.pi/4) + np.random.randn(100) * 0.7
data = np.stack([sensor1, sensor2, sensor3])
# Create null model (assumes Gaussian distributions)
model = NullModel(data, dtypes=[float, float, float], model="gaussian_theoretical")
# Define a motif: length 10, all 3 sensors, 8 occurrences
motif_length = 10
motif_pattern = data[:, 5:15] # Extract pattern from position 5
motif_vars = np.array([0, 1, 2]) # Use all sensors
delta_thresholds = np.array([0.3, 0.3, 0.3]) # Tolerance for matching
# Create motif and test significance
motif = Motif(motif_pattern, motif_vars, delta_thresholds, n_matches=8)
prob = motif.set_pattern_probability(model, vars_indep=True)
pvalue = motif.set_significance(
max_possible_matches=100 - motif_length + 1,
data_n_variables=3,
idd_correction=False
)
print(f"Pattern probability: {prob:.6e}")
print(f"P-value: {pvalue:.6e}")
print(f"Significant at α=0.01? {pvalue <= 0.01}")
```
See the `examples/` folder for more 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.
Raw data
{
"_id": null,
"home_page": null,
"name": "msig",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "\"Miguel G. Silva\" <mmsilva@ciencias.ulisboa.pt>",
"keywords": "time-series, motif-discovery, statistical-significance, multivariate",
"author": null,
"author_email": "\"Miguel G. Silva\" <mmsilva@ciencias.ulisboa.pt>",
"download_url": "https://files.pythonhosted.org/packages/10/0d/acfa4cb0a53629ff52b35edecc7714397619c5b7fa3f0d81f655649dacb8/msig-0.1.3.tar.gz",
"platform": null,
"description": "# MSig\n\n**Statistical Significance Testing for Multivariate Time Series Motifs**\n\nMSig evaluates whether discovered motifs occur more frequently than expected by chance, using rigorous statistical methods.\n\n## Installation\n\n### From PyPI (recommended)\n\n```bash\n# Core package only\npip install msig\n\n# With experiment dependencies (includes STUMPY and LAMA)\npip install \"msig[experiments]\"\n```\n\n### From source with uv\n\n```bash\n# Clone the repository\ngit clone https://github.com/MiguelGarcaoSilva/msig.git\ncd msig\n\n# Sync dependencies (includes STUMPY and LAMA)\nuv sync\n\n# Optional: Install MOMENTI (for MOMENTI experiments - Linux/Windows only)\nuv pip install git+https://github.com/aidaLabDEI/MOMENTI-motifs\n```\n\n### From source with pip\n\n```bash\n# Clone repository\ngit clone https://github.com/MiguelGarcaoSilva/msig.git\ncd msig\n\n# Install with experiment dependencies\npip install -e \".[experiments]\"\n```\n\n**Notes**: \n- MOMENTI has platform-specific dependencies and may not install on macOS.\n- Audio experiments require **ffmpeg** for MP3 processing: `brew install ffmpeg` (macOS) or `apt-get install ffmpeg` (Linux)\n\n## Quick Start\n\n```python\nfrom msig import Motif, NullModel\nimport numpy as np\n\n# Create sample multivariate time series (3 sensors \u00d7 100 time points)\nnp.random.seed(42)\nt = np.linspace(0, 10, 100)\nsensor1 = 10 + 2 * np.sin(2 * np.pi * t) + np.random.randn(100) * 0.5\nsensor2 = 5 + 1.5 * np.cos(2 * np.pi * t) + np.random.randn(100) * 0.3\nsensor3 = 15 + 3 * np.sin(2 * np.pi * t + np.pi/4) + np.random.randn(100) * 0.7\ndata = np.stack([sensor1, sensor2, sensor3])\n\n# Create null model (assumes Gaussian distributions)\nmodel = NullModel(data, dtypes=[float, float, float], model=\"gaussian_theoretical\")\n\n# Define a motif: length 10, all 3 sensors, 8 occurrences\nmotif_length = 10\nmotif_pattern = data[:, 5:15] # Extract pattern from position 5\nmotif_vars = np.array([0, 1, 2]) # Use all sensors\ndelta_thresholds = np.array([0.3, 0.3, 0.3]) # Tolerance for matching\n\n# Create motif and test significance\nmotif = Motif(motif_pattern, motif_vars, delta_thresholds, n_matches=8)\nprob = motif.set_pattern_probability(model, vars_indep=True)\npvalue = motif.set_significance(\n max_possible_matches=100 - motif_length + 1,\n data_n_variables=3,\n idd_correction=False\n)\n\nprint(f\"Pattern probability: {prob:.6e}\")\nprint(f\"P-value: {pvalue:.6e}\")\nprint(f\"Significant at \u03b1=0.01? {pvalue <= 0.01}\")\n```\n\nSee the `examples/` folder for more examples (`simple_example.py` and `example.ipynb`).\n\n## Running Experiments\n\nThe repository includes case studies on three datasets with three discovery methods (STUMPY, LAMA, MOMENTI):\n\n```bash\n# Run individual experiments\nuv run python experiments/audio/run_stumpy.py\nuv run python experiments/audio/run_lama.py\nuv run python experiments/audio/run_momenti.py\n\nuv run python experiments/populationdensity/run_stumpy.py\nuv run python experiments/populationdensity/run_lama.py\nuv run python experiments/populationdensity/run_momenti.py\n\nuv run python experiments/washingmachine/run_stumpy.py\nuv run python experiments/washingmachine/run_lama.py\nuv run python experiments/washingmachine/run_momenti.py\n```\n\nResults are saved to `results/<dataset>/<method>/`.\n\n## Citation\n\n```bibtex\n@article{silva2024msig,\n title={On Why and How Statistical Significance Criteria Can Guide Multivariate Time Series Motif Analysis},\n author={Silva, Miguel G. and Henriques, Rui and Madeira, Sara C.},\n year={2024}\n}\n```\n\n## License\n\nMIT License - see LICENSE file.\n\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Statistical Significance Criteria for Multivariate Time Series Motifs",
"version": "0.1.3",
"project_urls": {
"Bug Tracker": "https://github.com/MiguelGarcaoSilva/msig/issues",
"Documentation": "https://github.com/MiguelGarcaoSilva/msig#readme",
"Homepage": "https://github.com/MiguelGarcaoSilva/msig",
"Repository": "https://github.com/MiguelGarcaoSilva/msig"
},
"split_keywords": [
"time-series",
" motif-discovery",
" statistical-significance",
" multivariate"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "15e3b6bd8fb8f5ddf13522a9095e5c153bb9f89a41951697cbe54f834ebb2746",
"md5": "1355b41e8da2d43d8b5d7298d379b0a3",
"sha256": "735eacd7bb7a07d106fb034209d67e71dcc3924cfb67a7f59caa8e067053cc18"
},
"downloads": -1,
"filename": "msig-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1355b41e8da2d43d8b5d7298d379b0a3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 10776,
"upload_time": "2025-10-27T10:33:10",
"upload_time_iso_8601": "2025-10-27T10:33:10.712524Z",
"url": "https://files.pythonhosted.org/packages/15/e3/b6bd8fb8f5ddf13522a9095e5c153bb9f89a41951697cbe54f834ebb2746/msig-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "100dacfa4cb0a53629ff52b35edecc7714397619c5b7fa3f0d81f655649dacb8",
"md5": "f572ce3adb41cf8d2b6078e1dfb7d7c9",
"sha256": "9acb752fde2a59032847aac1c03b56c4eea8ab6912bfe7864aa2aaa0024010aa"
},
"downloads": -1,
"filename": "msig-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "f572ce3adb41cf8d2b6078e1dfb7d7c9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 14499,
"upload_time": "2025-10-27T10:33:11",
"upload_time_iso_8601": "2025-10-27T10:33:11.714375Z",
"url": "https://files.pythonhosted.org/packages/10/0d/acfa4cb0a53629ff52b35edecc7714397619c5b7fa3f0d81f655649dacb8/msig-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-27 10:33:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MiguelGarcaoSilva",
"github_project": "msig",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "msig"
}
JSON
