Skip to content

Multi-Subject Studies

AIME LOC provides session containers for batch processing multiple subjects and tasks, with built-in summary tables and CSV export.

Session Workflow

from pathlib import Path
from aime_loc import LOC
from aime_loc.eeg import EEG

loc = LOC()
eeg = EEG(loc)

# Create a session
session = eeg.session()

# Add recordings
for f in sorted(Path("data/").glob("sub-*/eeg/*.set")):
    subject = f.parent.parent.name   # e.g., "sub-01"
    task = f.stem                     # e.g., "nback"

    rec = eeg.load(f)
    rec.preprocess()
    epochs = rec.extract_epochs(duration=2.0)
    session.add(epochs, subject=subject, task=task)

print(session)
# EEGSession(15 recordings, 5 subjects, 3 tasks)

Batch Scoring

results = eeg.score_session(session)
print(results)
# SessionResults(15 profiles)

Summary Table

results.summary_table()

Output:

Subject      Task         TC%      Best Function    Epochs
------------------------------------------------------------
sub-01       nback       23.40%   Attention              150
sub-01       rest        31.20%   Mindfulness            200
sub-01       flanker     19.80%   Awareness              180
sub-02       nback       21.10%   Cognition              145
sub-02       rest        28.90%   Consciousness          190
...

Export to CSV

results.export_csv("study_results.csv")

CSV columns: subject, task, tc_score, best_function, worst_function, n_epochs, n_channels, sfreq

Accessing Individual Profiles

# All profiles as a list
for profile in results.profiles:
    print(f"{profile.subject_id} / {profile.task}: TC={profile.tc_score:.2f}%")

# Export each profile individually
for profile in results.profiles:
    name = f"{profile.subject_id}_{profile.task}"
    profile.to_json(f"profiles/{name}.json")
    profile.radar_chart(show=False, save=f"figures/{name}_radar.png")

Session Properties

print(f"Recordings: {session.n_recordings}")
print(f"Subjects: {session.subjects}")   # ['sub-01', 'sub-02', ...]
print(f"Tasks: {session.tasks}")         # ['flanker', 'nback', 'rest']

BIDS-Compatible Directory Structure

AIME LOC works naturally with BIDS-formatted EEG datasets:

dataset/
├── sub-01/
│   └── eeg/
│       ├── sub-01_task-nback_eeg.set
│       ├── sub-01_task-rest_eeg.set
│       └── sub-01_task-flanker_eeg.set
├── sub-02/
│   └── eeg/
│       ├── sub-02_task-nback_eeg.set
│       └── sub-02_task-rest_eeg.set
└── ...

from pathlib import Path

session = eeg.session()
for f in Path("dataset/").glob("sub-*/eeg/*.set"):
    parts = f.stem.split("_")
    subject = parts[0]                                    # "sub-01"
    task = [p for p in parts if p.startswith("task-")][0] # "task-nback"
    task = task.replace("task-", "")                      # "nback"

    rec = eeg.load(f)
    rec.preprocess()
    epochs = rec.extract_epochs()
    session.add(epochs, subject=subject, task=task)

Group-Level Analysis

After scoring, you can perform group-level analyses using the exported data:

import pandas as pd

# Export and load as DataFrame
results.export_csv("study.csv")
df = pd.read_csv("study.csv")

# Mean TC by task
print(df.groupby("task")["tc_score"].mean())

# Mean TC by subject
print(df.groupby("subject")["tc_score"].mean())

# Subject x Task pivot table
pivot = df.pivot_table(values="tc_score", index="subject", columns="task")
print(pivot)

Next Steps