# Authors: The MNE-Python contributors.
# License: BSD-3-Clause
# Copyright the MNE-Python contributors.
import os.path as op
import time
from pathlib import Path
import numpy as np
from scipy.io import loadmat
from ..._fiff.meas_info import create_info
from ...channels import make_standard_montage
from ...epochs import EpochsArray
from ...utils import _check_pandas_installed, logger, verbose
from ..utils import _do_path_update, _downloader_params, _get_path, _log_time_size
# root url for LIMO files
root_url = "https://files.de-1.osf.io/v1/resources/52rea/providers/osfstorage/"
@verbose
def data_path(
subject, path=None, force_update=False, update_path=None, *, verbose=None
):
"""Get path to local copy of LIMO dataset URL.
This is a low-level function useful for getting a local copy of the
remote LIMO dataset :footcite:`Rousselet2016`. The complete dataset is
available at datashare.is.ed.ac.uk/.
Parameters
----------
subject : int
Subject to download. Must be of :class:`ìnt` in the range from 1
to 18 (inclusive).
path : None | str
Location of where to look for the LIMO data storing directory.
If None, the environment variable or config parameter
``MNE_DATASETS_LIMO_PATH`` is used. If it doesn't exist, the
"~/mne_data" directory is used. If the LIMO dataset
is not found under the given path, the data
will be automatically downloaded to the specified folder.
force_update : bool
Force update of the dataset even if a local copy exists.
update_path : bool | None
If True, set the MNE_DATASETS_LIMO_PATH in mne-python
config to the given path. If None, the user is prompted.
%(verbose)s
Returns
-------
path : str
Local path to the given data file.
Notes
-----
For example, one could do:
>>> from mne.datasets import limo
>>> limo.data_path(subject=1, path=os.getenv('HOME') + '/datasets') # doctest:+SKIP
This would download the LIMO data file to the 'datasets' folder,
and prompt the user to save the 'datasets' path to the mne-python config,
if it isn't there already.
References
----------
.. footbibliography::
""" # noqa: E501
import pooch
t0 = time.time()
downloader = pooch.HTTPDownloader(**_downloader_params())
# local storage patch
config_key = "MNE_DATASETS_LIMO_PATH"
name = "LIMO"
subj = f"S{subject}"
path = _get_path(path, config_key, name)
base_path = op.join(path, "MNE-limo-data")
subject_path = op.join(base_path, subj)
# the remote URLs are in the form of UUIDs:
urls = dict(
S18={
"Yr.mat": "5cf839833a4d9500178a6ff8",
"LIMO.mat": "5cf83907e650a2001ad592e4",
},
S17={
"Yr.mat": "5cf838e83a4d9500168aeb76",
"LIMO.mat": "5cf83867a542b80019c87602",
},
S16={
"Yr.mat": "5cf83857e650a20019d5778f",
"LIMO.mat": "5cf837dc3a4d9500188a64fe",
},
S15={
"Yr.mat": "5cf837cce650a2001ad591e8",
"LIMO.mat": "5cf83758a542b8001ac7d11d",
},
S14={
"Yr.mat": "5cf837493a4d9500198a938f",
"LIMO.mat": "5cf836e4a542b8001bc7cc53",
},
S13={
"Yr.mat": "5cf836d23a4d9500178a6df7",
"LIMO.mat": "5cf836543a4d9500168ae7cb",
},
S12={
"Yr.mat": "5cf83643d4c7d700193e5954",
"LIMO.mat": "5cf835193a4d9500178a6c92",
},
S11={
"Yr.mat": "5cf8356ea542b8001cc81517",
"LIMO.mat": "5cf834f7d4c7d700163daab8",
},
S10={
"Yr.mat": "5cf833b0e650a20019d57454",
"LIMO.mat": "5cf83204e650a20018d59eb2",
},
S9={
"Yr.mat": "5cf83201a542b8001cc811cf",
"LIMO.mat": "5cf8316c3a4d9500168ae13b",
},
S8={
"Yr.mat": "5cf8326ce650a20017d60373",
"LIMO.mat": "5cf8316d3a4d9500198a8dc5",
},
S7={
"Yr.mat": "5cf834a03a4d9500168ae59b",
"LIMO.mat": "5cf83069e650a20017d600d7",
},
S6={
"Yr.mat": "5cf830e6a542b80019c86a70",
"LIMO.mat": "5cf83057a542b80019c869ca",
},
S5={
"Yr.mat": "5cf8115be650a20018d58041",
"LIMO.mat": "5cf80c0bd4c7d700193e213c",
},
S4={
"Yr.mat": "5cf810c9a542b80019c8450a",
"LIMO.mat": "5cf80bf83a4d9500198a6eb4",
},
S3={
"Yr.mat": "5cf80c55d4c7d700163d8f52",
"LIMO.mat": "5cf80bdea542b80019c83cab",
},
S2={
"Yr.mat": "5cde827123fec40019e01300",
"LIMO.mat": "5cde82682a50c4001677c259",
},
S1={
"Yr.mat": "5d6d3071536cf5001a8b0c78",
"LIMO.mat": "5d6d305f6f41fc001a3151d8",
},
)
# these can't be in the registry file (mne/data/dataset_checksums.txt)
# because of filename duplication
hashes = dict(
S18={
"Yr.mat": "md5:87f883d442737971a80fc0a35d057e51",
"LIMO.mat": "md5:8b4879646f65d7876fa4adf2e40162c5",
},
S17={
"Yr.mat": "md5:7b667ec9eefd7a9996f61ae270e295ee",
"LIMO.mat": "md5:22eaca4e6fad54431fd61b307fc426b8",
},
S16={
"Yr.mat": "md5:c877afdb4897426421577e863a45921a",
"LIMO.mat": "md5:86672d7afbea1e8c39305bc3f852c8c2",
},
S15={
"Yr.mat": "md5:eea9e0140af598fefc08c886a6f05de5",
"LIMO.mat": "md5:aed5cb71ddbfd27c6a3ac7d3e613d07f",
},
S14={
"Yr.mat": "md5:8bd842cfd8588bd5d32e72fdbe70b66e",
"LIMO.mat": "md5:1e07d1f36f2eefad435a77530daf2680",
},
S13={
"Yr.mat": "md5:d7925d2af7288b8a5186dfb5dbb63d34",
"LIMO.mat": "md5:ba891015d2f9e447955fffa9833404ca",
},
S12={
"Yr.mat": "md5:0e1d05beaa4bf2726e0d0671b78fe41e",
"LIMO.mat": "md5:423fd479d71097995b6614ecb11df9ad",
},
S11={
"Yr.mat": "md5:1b0016fb9832e43b71f79c1992fcbbb1",
"LIMO.mat": "md5:1a281348c2a41ee899f42731d30cda70",
},
S10={
"Yr.mat": "md5:13c66f60e241b9a9cc576eaf1b55a417",
"LIMO.mat": "md5:3c4b41e221eb352a21bbef1a7e006f06",
},
S9={
"Yr.mat": "md5:3ae1d9c3a1d9325deea2f2dddd1ab507",
"LIMO.mat": "md5:5e204e2a4bcfe4f535b4b1af469b37f7",
},
S8={
"Yr.mat": "md5:7e9adbca4e03d8d7ce8ea07ccecdc8fd",
"LIMO.mat": "md5:88313c21d34428863590e586b2bc3408",
},
S7={
"Yr.mat": "md5:6b5290a6725ecebf1022d5d2789b186d",
"LIMO.mat": "md5:8c769219ebc14ce3f595063e84bfc0a9",
},
S6={
"Yr.mat": "md5:420c858a8340bf7c28910b7b0425dc5d",
"LIMO.mat": "md5:9cf4e1a405366d6bd0cc6d996e32fd63",
},
S5={
"Yr.mat": "md5:946436cfb474c8debae56ffb1685ecf3",
"LIMO.mat": "md5:241fac95d3a79d2cea081391fb7078bd",
},
S4={
"Yr.mat": "md5:c8216af78ac87b739e86e57b345cafdd",
"LIMO.mat": "md5:8e10ef36c2e075edc2f787581ba33459",
},
S3={
"Yr.mat": "md5:ff02e885b65b7b807146f259a30b1b5e",
"LIMO.mat": "md5:59b5fb3a9749003133608b5871309e2c",
},
S2={
"Yr.mat": "md5:a4329022e57fd07ceceb7d1735fd2718",
"LIMO.mat": "md5:98b284b567f2dd395c936366e404f2c6",
},
S1={
"Yr.mat": "md5:076c0ae78fb71d43409c1877707df30e",
"LIMO.mat": "md5:136c8cf89f8f111a11f531bd9fa6ae69",
},
)
# create the download manager
fetcher = pooch.create(
path=subject_path,
base_url="",
version=None, # Data versioning is decoupled from MNE-Python version.
registry=hashes[subj],
urls={key: f"{root_url}{uuid}" for key, uuid in urls[subj].items()},
retry_if_failed=2, # 2 retries = 3 total attempts
)
# use our logger level for pooch's logger too
pooch.get_logger().setLevel(logger.getEffectiveLevel())
# fetch the data
sz = 0
for fname in ("LIMO.mat", "Yr.mat"):
destination = Path(subject_path, fname)
if destination.exists():
if force_update:
destination.unlink()
else:
continue
if sz == 0: # log once
logger.info("Downloading LIMO data")
# fetch the remote file (if local file missing or has hash mismatch)
fetcher.fetch(fname=fname, downloader=downloader)
sz += destination.stat().st_size
# update path in config if desired
_do_path_update(path, update_path, config_key, name)
if sz > 0:
_log_time_size(t0, sz)
return base_path
@verbose
def load_data(subject, path=None, force_update=False, update_path=None, verbose=None):
"""Fetch subjects epochs data for the LIMO data set.
Parameters
----------
subject : int
Subject to use. Must be of class ìnt in the range from 1 to 18.
path : str
Location of where to look for the LIMO data.
If None, the environment variable or config parameter
``MNE_DATASETS_LIMO_PATH`` is used. If it doesn't exist, the
"~/mne_data" directory is used.
force_update : bool
Force update of the dataset even if a local copy exists.
update_path : bool | None
If True, set the MNE_DATASETS_LIMO_PATH in mne-python
config to the given path. If None, the user is prompted.
%(verbose)s
Returns
-------
epochs : instance of Epochs
The epochs.
""" # noqa: E501
pd = _check_pandas_installed()
# subject in question
if isinstance(subject, int) and 1 <= subject <= 18:
subj = f"S{subject}"
else:
raise ValueError("subject must be an int in the range from 1 to 18")
# set limo path, download and decompress files if not found
limo_path = data_path(subject, path, force_update, update_path)
# -- 1) import .mat files
# epochs info
fname_info = op.join(limo_path, subj, "LIMO.mat")
data_info = loadmat(fname_info)
# number of epochs per condition
design = data_info["LIMO"]["design"][0][0]["X"][0][0]
data_info = data_info["LIMO"]["data"][0][0][0][0]
# epochs data
fname_eeg = op.join(limo_path, subj, "Yr.mat")
data = loadmat(fname_eeg)
# -- 2) get epochs information from structure
# sampling rate
sfreq = data_info["sampling_rate"][0][0]
# tmin and tmax
tmin = data_info["start"][0][0]
# create events matrix
sample = np.arange(len(design))
prev_id = np.zeros(len(design))
ev_id = design[:, 1]
events = np.array([sample, prev_id, ev_id]).astype(int).T
# event ids, such that Face B == 1
event_id = {"Face/A": 0, "Face/B": 1}
# -- 3) extract channel labels from LIMO structure
# get individual labels
labels = data_info["chanlocs"]["labels"]
labels = [label for label, *_ in labels[0]]
# get montage
montage = make_standard_montage("biosemi128")
# add external electrodes (e.g., eogs)
ch_names = montage.ch_names + ["EXG1", "EXG2", "EXG3", "EXG4"]
# match individual labels to labels in montage
found_inds = [ind for ind, name in enumerate(ch_names) if name in labels]
missing_chans = [name for name in ch_names if name not in labels]
assert labels == [ch_names[ind] for ind in found_inds]
# -- 4) extract data from subjects Yr structure
# data is stored as channels x time points x epochs
# data['Yr'].shape # <-- see here
# transpose to epochs x channels time points
data = np.transpose(data["Yr"], (2, 0, 1))
# initialize data in expected order
temp_data = np.empty((data.shape[0], len(ch_names), data.shape[2]))
# copy over the non-missing data
for source, target in enumerate(found_inds):
# avoid copy when fancy indexing
temp_data[:, target, :] = data[:, source, :]
# data to V (to match MNE's format)
data = temp_data / 1e6
# create list containing channel types
types = ["eog" if ch.startswith("EXG") else "eeg" for ch in ch_names]
# -- 5) Create custom info for mne epochs structure
# create info
info = create_info(ch_names, sfreq, types).set_montage(montage)
# get faces and noise variables from design matrix
event_list = list(events[:, 2])
faces = ["B" if event else "A" for event in event_list]
noise = list(design[:, 2])
# create epochs metadata
metadata = {"face": faces, "phase-coherence": noise}
metadata = pd.DataFrame(metadata)
# -- 6) Create custom epochs array
epochs = EpochsArray(
data, info, events, tmin, event_id, metadata=metadata, verbose=False
)
epochs.info["bads"] = missing_chans # missing channels are marked as bad.
return epochs
Datasets
Models
