Metadata-Version: 2.4
Name: multisim-neuro
Version: 0.1
Summary: A package for simulating time resolved data with multivariate effects
Author-email: Alex Lepauvre <alex.lepauvre@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Alex lepauvre
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/AlexLepauvre/multisim-neuro
Project-URL: Repository, https://github.com/AlexLepauvre/multisim-neuro
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Provides-Extra: docs
Requires-Dist: mne; extra == "docs"
Requires-Dist: eeglabio; extra == "docs"
Requires-Dist: scikit-learn; extra == "docs"
Requires-Dist: scipy; extra == "docs"
Requires-Dist: pydata-sphinx-theme; extra == "docs"
Requires-Dist: numpydoc; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: ruff; extra == "docs"
Requires-Dist: ipython; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
Requires-Dist: myst-nb; extra == "docs"
Provides-Extra: export
Requires-Dist: mne; extra == "export"
Requires-Dist: eeglabio; extra == "export"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# MultiSim

**Simulate realistic MEG/EEG data with ground-truth multivariate effects**

## Installation

```bash
pip install multisim-neuro
```

Or clone and install the development version:

```bash
git clone https://github.com/AlexLepauvre/multisim-neuro
cd multisim-neuro
pip install -e .[full]
```

## Features

- Design-driven simulation: specify arbitrary experimental design matrices (conditions, interactions, parametric regressors).

- Time‑locked effects: inject multivariate patterns in chosen time windows with exact control over effect size (Mahalanobis distance).

- Noise modeling: control within‑subject sensor noise and between‑subject variability.

- Spatial covariance: simulate correlated sensors or modes via any user‑supplied covariance matrix.

- MNE & EEGLAB export: seamless conversion to mne.EpochsArray or EEGLAB .set files.

- Power analysis: predict group‑level statistical power from trials, subjects, and effect sizes.

## Quickstart
```python
import numpy as np
from multisim import Simulator

# 1. Create a simple design: two conditions, 100 trials
X = np.vstack([np.zeros(100), np.ones(100)]).T  
t_win   = np.array([[0.1, 0.3]])    # effect between 100–300 ms
effects = np.array([1])             # effect on condition 1

# 2. Instantiate simulator
sim = Simulator(
    X, noise_std=1.0, n_channels=64, n_subjects=10,
    tmin=-0.2, tmax=0.8, sfreq=250,
    t_win=t_win, effects=effects,
    effect_size=[0.5],               # multivariate d′ = 0.5
    intersub_noise_std=0.1           # between-subject σ
)

# 3. Export to MNE Epochs and decode
epochs_list = sim.export_to_mne()
# ... run your decoding pipeline on epochs_list ...
```

## API
After installation, see full class and method documentation at: https://alexlepauvre.github.io/multisim-neuro/index.html

You can find extensive tutorials at:
https://alexlepauvre.github.io/multisim-neuro/tutorial/index.html

## Customization

- Spatial pattern: pass a custom covariance matrix or weight vector to concentrate signal in subsets of channels.

- Temporal kernel: supply any causal kernel to shape the time-course of effects.

- Effect size: Simulate multivariate effect at particular effect size to test the ability of your pipelines to retrieve it given the number of subjects and trials for each subject

## How to cite us:
If you use the scripts found in this repository, you can use the DOI provided by Zenodo to cite us. And here is a bibtex:

```
@article{LepauvreEtAl2024,
  title = {MultiSim},
  author = {Lepauvre, Alex and Chu, Qian and Zeidman, Peter and Melloni, Lucia},
  year = {2025},
  doi = {TBA},
}
```
