pnpl.datasets.pallier2025.dataset.Pallier2025

pnpl.datasets.pallier2025.dataset.Pallier2025#

class pnpl.datasets.pallier2025.dataset.Pallier2025(data_path, task, preprocessing='notch+bp+ds', preprocessing_config=None, include_subjects=None, exclude_subjects=None, include_sessions=None, exclude_sessions=None, include_tasks=None, exclude_tasks=None, include_runs=None, exclude_runs=None, include_run_keys=None, exclude_run_keys=None, standardize=True, clipping_boundary=10.0, channel_means=None, channel_stds=None, include_info=False, create_h5_if_missing=True, download=True, preload_h5=False)[source]#

LittlePrince audiobook-listening continuous MEG dataset.

Parameters:

  • data_path (str) – Local data directory (BIDS root mirroring the OpenNeuro release). Created if missing.

  • task – Object implementing pnpl.tasks.base.TaskProtocol. See pnpl.tasks.pallier2025 for ready-made tasks.

  • preprocessing (Optional[str]) – Preprocessing string used in derivative filenames. Defaults to "notch+bp+ds". The companion paper (d’Ascoli et al., 2025, Nat Commun 16:10521) uses a 0.1–40 Hz bandpass and 50 Hz resample with no notch / SSS, which can be reproduced via preprocessing="bp+ds" together with preprocessing_config={"bp": {"l_freq": 0.1, "h_freq": 40.0}, "ds": {"sfreq": 50.0}}.

  • preprocessing_config (Optional[Dict[str, Dict[str, Any]]]) – Optional preprocessing-step overrides forwarded to pnpl.preprocessing.Pipeline.

  • exclude_subjects (Optional[Sequence[str]]) – BIDS subject ids without the sub- prefix ("01"..``”58”``).

  • exclude_sessions (Optional[Sequence[str]]) – "01" (the only one).

  • exclude_tasks (Optional[Sequence[str]]) – "listen" (the only one).

  • exclude_runs (Optional[Sequence[str]]) – "01"..``”09”``.

  • exclude_run_keys (Optional[Sequence[tuple]]) – 4-tuples (subject, session, task, run) for fully-specified inclusion/exclusion. Wins over the per-axis filters.

  • channel_stds (ndarray | None) – See pnpl.datasets.mixins.StandardizationMixin.

  • include_info (bool) – If True, __getitem__ returns (x, y, info).

  • create_h5_if_missing (bool) – If True (default), materialize the cached H5 from a local preprocessed FIF or — failing that — by running the preprocessing pipeline against the raw FIF.

  • download (bool) – If True, fetch missing files from OpenNeuro on demand.

  • preload_h5 (bool) – Read each H5 into RAM on first access.

  • include_subjects (Optional[Sequence[str]])

  • exclude_subjects

  • include_sessions (Optional[Sequence[str]])

  • exclude_sessions

  • include_tasks (Optional[Sequence[str]])

  • exclude_tasks

  • include_runs (Optional[Sequence[str]])

  • exclude_runs

  • include_run_keys (Optional[Sequence[tuple]])

  • exclude_run_keys

  • standardize (bool)

  • clipping_boundary (Optional[float])

  • channel_means (ndarray | None)

  • channel_stds

__init__(data_path, task, preprocessing='notch+bp+ds', preprocessing_config=None, include_subjects=None, exclude_subjects=None, include_sessions=None, exclude_sessions=None, include_tasks=None, exclude_tasks=None, include_runs=None, exclude_runs=None, include_run_keys=None, exclude_run_keys=None, standardize=True, clipping_boundary=10.0, channel_means=None, channel_stds=None, include_info=False, create_h5_if_missing=True, download=True, preload_h5=False)[source]#
Parameters:

  • data_path (str)

  • preprocessing (str | None)

  • preprocessing_config (Dict[str, Dict[str, Any]] | None)

  • include_subjects (Sequence[str] | None)

  • exclude_subjects (Sequence[str] | None)

  • include_sessions (Sequence[str] | None)

  • exclude_sessions (Sequence[str] | None)

  • include_tasks (Sequence[str] | None)

  • exclude_tasks (Sequence[str] | None)

  • include_runs (Sequence[str] | None)

  • exclude_runs (Sequence[str] | None)

  • include_run_keys (Sequence[tuple] | None)

  • exclude_run_keys (Sequence[tuple] | None)

  • standardize (bool)

  • clipping_boundary (float | None)

  • channel_means (ndarray | None)

  • channel_stds (ndarray | None)

  • include_info (bool)

  • create_h5_if_missing (bool)

  • download (bool)

  • preload_h5 (bool)

Methods

__init__(data_path, task[, preprocessing, ...])

calculate_standardization_params(h5_data_loader)

Calculate channel means and stds across all runs.

clip_sample(sample, boundary)

Clip sample values to [-boundary, boundary].

close_h5_files()

Close all open H5 file handles and drop preloaded arrays.

ensure_file(fpath)

Ensure a file exists locally, downloading from OpenNeuro if needed.

get_bids_raw_path(subject, session, task, run)

Construct path to raw BIDS MEG file.

get_calibration_files()

Get paths to Maxwell filter calibration files.

get_derivatives_path(subject, session[, ...])

Construct path to derivatives directory.

get_events_path(subject, session, task, run)

Construct path to events TSV file.

get_h5_dataset(run_key)

Get (cached) H5 dataset for a run.

get_h5_path(subject, session, task, run[, ...])

Construct path to H5 file.

get_headpos_path(subject, session, task, run)

Construct path to cached head position file.

get_meg_dir(subject, session)

get_preprocessed_path(subject, session, ...)

Construct path to preprocessed file in derivatives.

get_sfreq_from_h5(h5_path)

Get sampling frequency from H5 file.

init_continuous_h5([preload_h5])

Initialize the H5 data cache.

list_remote_files([refresh])

Return dataset-relative file paths advertised by OpenNeuro's GraphQL API for the configured snapshot.

load_continuous_window(subject, session, ...)

Load a time window from continuous H5 data.

load_continuous_window_from_sample(sample)

Load time window from a sample tuple.

load_head_positions(subject, session, task, run)

Load cached head positions from CSV file.

load_preprocessed_bids(subject, session, ...)

Load a preprocessed FIF file from the derivatives directory.

load_raw_bids(subject, session, task, run[, ...])

Load the raw Elekta FIF, allowing the Internal Active Shielding flag MNE refuses by default.

prefetch_files(file_paths)

Prefetch multiple files in parallel (skips already-present).

raw_bids_exists(subject, session, task, run)

Check if raw BIDS data exists for given identifiers.

resolve_remote_file(rel_path)

Return {"size", "url"} for a remote path via HEAD.

setup_standardization([standardize, ...])

Set up standardization parameters.

standardize(data)

Apply z-score normalization and optional clipping to data.

Attributes

OPENNEURO_DATASET_ID

OPENNEURO_S3_BASE

OPENNEURO_SNAPSHOT_TAG

broadcasted_means

broadcasted_stds

channel_means

channel_stds

label_info

n_channels

n_times