MYNE

MYNE reveals behavior- and stimulus-aligned neuronal motifs beyond firing-rate dynamics.

This repository contains source code for a small end-to-end synthetic demo:

1. Simulate spike trains with embedded motifs.
2. Train/test a conditional spike GAN using GT firing rates.
3. Run MYNE motif detection using GAN-generated surrogate spike trains.

Repository contents

• _data_simulation/: synthetic spike-train and motif generator.
• conditional-spike-GAN/: conditional spike GAN training and surrogate generation code.
• motif-detection/: MYNE motif detection/mining code.
• script/run_synthetic_demo.sh: one-command demo pipeline.
• environment.yml: conda environment specification.

1. System requirements

Operating system

The code is intended for Linux systems. It has been organized and tested in a Linux/NAS workstation environment.

Recommended OS:

• Ubuntu 20.04 or newer, or a comparable Linux distribution

Software dependencies

Recommended environment:

• Python 3.10
• Conda or Mamba
• PyTorch 2.0 or newer
• CUDA 11.8-compatible PyTorch build
• NumPy 1.23 or newer
• SciPy 1.10 or newer
• h5py 3.8 or newer
• PyYAML 6.0 or newer
• tqdm 4.65 or newer
• numba 0.57 or newer
• matplotlib 3.7 or newer
• tensorboard 2.12 or newer
• CN2Simulator installed from https://github.com/NICALab/CN2-Simulator.git

These are listed in environment.yml.

Hardware requirements

The simulation and motif-detection code can run on CPU, but the conditional spike GAN stage requires an NVIDIA GPU for practical use.

Recommended hardware for the demo:

• Linux workstation
• NVIDIA GPU with CUDA support
• At least 16 GB system RAM
• At least 8 GB GPU memory

For larger experiments, more GPU memory and multiple GPUs are recommended.

2. Installation guide

Clone or download this repository, then create the conda environment:

cd MYNE
conda env create -f environment.yml
conda activate myne

If you prefer using an existing environment, install the dependencies listed in environment.yml and make sure CN2Simulator is available:

pip install git+https://github.com/NICALab/CN2-Simulator.git

Typical install time on a normal desktop or workstation is approximately 10-30 minutes, depending on network speed and whether PyTorch/CUDA packages are already cached.

3. Demo

The demo script generates a small simulated dataset, trains/tests the GT-rate conditional spike GAN, and runs motif detection.

Run:

cd MYNE
bash script/run_synthetic_demo.sh

The default demo is intentionally small:

• SEEDS=0
• FREQS=0.1
• RECORDING_TIME=120
• NIDS=20
• N_MOTIFS=2
• GAN_EPOCHS=5
• MINING_MODES=adjust

Expected output is written under:

output/data/_simulation/
output/results/

Expected output includes:

• simulated .mat spike data files
• conditional-spike-GAN model/sample outputs
• GAN-generated surrogate spike files
• motif-detection result .mat files

Expected demo runtime depends strongly on GPU hardware. On a CUDA-capable workstation, the small demo is expected to take minutes to tens of minutes. CPU-only execution is not recommended for the GAN stage.

To run only one stage:

RUN_STAGES=simulation bash script/run_synthetic_demo.sh
RUN_STAGES=gan bash script/run_synthetic_demo.sh
RUN_STAGES=mining bash script/run_synthetic_demo.sh

To run a slightly larger demo:

SEEDS="0 1 2" FREQS="0.032 0.1 0.316" GAN_EPOCHS=50 bash script/run_synthetic_demo.sh

4. Instructions for use

Full synthetic workflow

Use script/run_synthetic_demo.sh as the main template. Most experiment settings can be changed through environment variables:

EXP_DATE=my_run \
NIDS=50 \
N_LATENT=20 \
N_MOTIFS=3 \
RECORDING_TIME=600 \
SEEDS="0 1 2" \
FREQS="0.032 0.1 0.316" \
GAN_EPOCHS=100 \
bash script/run_synthetic_demo.sh

Motif detection on your own data

Your spike data should be stored in a MATLAB .mat file containing either:

• binned_spikes, or
• spikes

The array should have shape:

neurons x time_bins

You also need either:

• --rate_estimation GT, if GT firing-rate information is stored in oscillation_info, or
• a .mat file containing pred_rates, passed with --rate_estimation.

You also need GAN-generated surrogate spikes, passed with --GAN_generated_file.

Example motif-detection command:

cd motif-detection
python -m script.mine \
  --data_file /path/to/spikes.mat \
  --rate_estimation /path/to/pred_rates.mat \
  --GAN_generated_file /path/to/generated_spikes.h5 \
  --mode adjust \
  --alpha 0.05 \
  --binning 10 \
  --max_results_per_iteration 2000 \
  --min_joint_event_count 5

Available mining modes:

• count: product-score count statistic
• adjust: product score divided by expected count

Motif-event propagation uses min(...) internally.

Optional reproduction instructions

The demo script is intentionally small and is not intended to reproduce all manuscript-scale quantitative results. To reproduce larger synthetic experiments, increase:

• SEEDS
• FREQS
• RECORDING_TIME
• NIDS
• N_LATENT
• GAN_EPOCHS
• MINING_MODES

Example larger run template:

EXP_DATE=full_synthetic \
NIDS=50 \
N_LATENT=20 \
N_MOTIFS=3 \
RECORDING_TIME=600 \
SEEDS="0 1 2 3 4 5 6 7 8 9" \
FREQS="0 0.032 0.1 0.316 1 3.162 10 31.62 100" \
GAN_EPOCHS=100 \
MINING_MODES="count adjust" \
bash script/run_synthetic_demo.sh

For manuscript-scale reproduction, use the same dataset paths, seeds, model checkpoints, and hardware configuration reported in the manuscript or supplementary materials.