bidsreader 0.1.0__py3-none-any.whl

bidsreader/__init__.py

@@ -0,0 +1,15 @@
+from .basereader import BaseReader
+from .cmlbidsreader import CMLBIDSReader
+from .filtering import (
+    filter_events_df_by_trial_types,
+    filter_raw_events_by_trial_types,
+    filter_epochs_by_trial_types,
+    filter_by_trial_types,
+)
+from .convert import mne_epochs_to_ptsa, mne_raw_to_ptsa
+from .units import detect_unit, get_scale_factor, convert_unit
+from collections import namedtuple
+
+__version__ = "0.1.0"
+version_info = namedtuple("VersionInfo", "major,minor,patch")(
+    *__version__.split('.'))

bidsreader/_errorwrap.py

@@ -0,0 +1,50 @@
+# _errorwrap.py
+from __future__ import annotations
+from functools import wraps
+import json
+import pandas as pd
+
+from .exc import (
+    BIDSReaderError,
+    InvalidOptionError,
+    MissingRequiredFieldError,
+    FileNotFoundBIDSError,
+    AmbiguousMatchError,
+    DataParseError,
+    ExternalLibraryError,
+)
+
+def public_api(func):
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+
+        # If it's already one of yours, don't touch it.
+        except BIDSReaderError:
+            raise
+
+        # Map common “expected” external exceptions to your hierarchy.
+        except FileNotFoundError as e:
+            raise FileNotFoundBIDSError(str(e)) from e
+
+        except json.JSONDecodeError as e:
+            raise DataParseError(f"Invalid JSON: {e}") from e
+
+        except pd.errors.ParserError as e:
+            raise DataParseError(f"Could not parse TSV/CSV: {e}") from e
+
+        except KeyError as e:
+            # Often means missing expected column like "trial_type"
+            raise DataParseError(f"Missing expected key/column: {e}") from e
+
+        except ValueError as e:
+            # Be careful: ValueError is broad. Only map if you know it's "yours".
+            # Otherwise wrap as ExternalLibraryError.
+            raise ExternalLibraryError(str(e)) from e
+
+        except Exception as e:
+            # Last resort: you still guarantee your hierarchy.
+            raise ExternalLibraryError(f"{type(e).__name__}: {e}") from e
+
+    return wrapper

bidsreader/basereader.py

@@ -0,0 +1,208 @@
+import pandas as pd
+from mne_bids import BIDSPath, get_entity_vals
+from pathlib import Path
+from typing import Iterable, Optional, Union, List
+import warnings
+from ._errorwrap import public_api
+from .helpers import add_prefix
+from .exc import InvalidOptionError, MissingRequiredFieldError
+
+
+class BaseReader:
+    _FIELDS = {"root", "subject", "session", "task", "acquisition", "_device", "_space"}
+    # REQUIRED_FIELDS = ("subject", "task", "session", "device")
+
+    def __init__(
+        self,
+        root: Optional[Union[str, Path]] = None,
+        subject: Optional[str] = None,
+        task: Optional[str] = None,
+        session: Optional[str | int] = None,
+        space: Optional[str] = None,
+        acquisition: Optional[str] = None,
+        device: Optional[str] = None,
+    ):
+        if root is None:
+            raise ValueError("root must be provided")
+        self.root = Path(root)
+        self.subject = subject
+        self.session = session
+        self.task = str(task)
+
+        self.acquisition = acquisition
+
+        self._device = device
+
+        self._space = space
+
+    # ---------- magic functions ----------
+    def __str__(self) -> str:
+        parts = [
+            f"root={self.root}",
+            f"subject={self.subject}",
+        ]
+
+        if self.session:
+            parts.append(f"session={self.session}")
+        if self.task:
+            parts.append(f"task={self.task}")
+        if self.device:
+            parts.append(f"type={self.device}")
+        if self.space:
+            parts.append(f"space={self.space}")
+
+        cls = type(self).__name__
+        return f"{cls}({', '.join(parts)})"
+
+    def __repr__(self) -> str:
+        cls = type(self).__name__
+        return (
+            f"{cls}(root={self.root!r}, subject={self.subject!r}, "
+            f"session={self.session!r}, task={self.task!r}, "
+            f"device={self.device!r}, space={self.space!r})"
+        )
+
+    def __setattr__(self, name, value):
+        if name.startswith("_"):
+            object.__setattr__(self, name, value)
+            return
+        if name not in self._FIELDS:
+            raise AttributeError(f"Unknown field: {name}")
+        object.__setattr__(self, name, value)
+
+    # ---------- property ----------
+    @property
+    def space(self) -> Optional[str]:
+        if self._space is not None:
+            return self._space
+
+        try:
+            self._space = self._determine_space()
+        except Exception as e:
+            warnings.warn(
+                f"Could not determine space automatically: {e}",
+                RuntimeWarning,
+            )
+            return None
+
+        return self._space
+
+    @property
+    def device(self) -> Optional[str]:
+        if self._device is not None:
+            return self._device
+
+        try:
+            self._device = self._determine_device()
+        except Exception as e:
+            warnings.warn(
+                f"Could not determine device automatically: {e}",
+                RuntimeWarning,
+            )
+            return None
+
+        if self._device is None:
+            warnings.warn(
+                "device could not be inferred from subject.",
+                RuntimeWarning,
+            )
+
+        return self._device
+
+    # ---------- internal helpers ----------
+
+    def _bp(self, **kwargs) -> BIDSPath:
+        bp = BIDSPath(
+            root=self.root,
+            subject=self.subject,
+            session=str(self.session) if self.session is not None else None,
+            task=self.task,
+            datatype=self.device,
+        )
+        bp.update(**kwargs)
+        return bp
+
+    def _subject_root(self) -> Path:
+        p = self.root / self._add_bids_prefix("subject", self.subject)
+        return p
+
+    def _add_bids_prefix(self, field: str, value: Optional[str]) -> Optional[str]:
+        prefix_map = {
+            "subject": "sub-",
+            "session": "ses-",
+            "acquisition": "acq-",
+            "task": "task-",
+            "space": "space-",
+        }
+
+        if field not in prefix_map:
+            raise InvalidOptionError(f"Unknown BIDS field: {field}")
+
+        return add_prefix(value, prefix_map[field])
+
+    def _require(self, fields: Iterable[str], context: str = "") -> None:
+        missing = [f for f in fields if getattr(self, f, None) in (None, "")]
+        if missing:
+            raise MissingRequiredFieldError(
+                f"{context}: missing required fields: {', '.join(missing)}"
+            )
+
+    # idk if this is useful for anyone, should override for proper checking
+    # def _get_needed_fields(self):
+    #     return self.REQUIRED_FIELDS
+
+    def _determine_space(self) -> Optional[str]:
+        """Override in subclasses to provide automatic space detection."""
+        return None
+
+    def _determine_device(self) -> Optional[str]:
+        """Override in subclasses to provide automatic device detection."""
+        return None
+
+    # ---------- public API ----------
+    @public_api
+    def set_fields(self, **kwargs):
+        for k, v in kwargs.items():
+            setattr(self, k, v)  # validated by __setattr__
+        return self
+
+    # ---- simple metadata queries ----
+    @public_api
+    def get_subject_tasks(self) -> List[str]:
+        subject_root = self._subject_root()
+        return get_entity_vals(subject_root, "task")
+
+    @public_api
+    def get_subject_sessions(self) -> List[str]:
+        subject_root = self._subject_root()
+        return get_entity_vals(subject_root, "session")
+
+    @public_api
+    def get_dataset_subjects(self) -> List[str]:
+        return get_entity_vals(self.root, "subject")
+
+    @public_api
+    def get_dataset_tasks(self) -> List[str]:
+        return get_entity_vals(self.root, "task")
+
+    @public_api
+    def get_dataset_max_sessions(self, outlier_thresh: Optional[int] = None) -> Optional[int]:
+        subs = self.get_dataset_subjects()
+        max_ses: Optional[int] = None
+
+        for sub in subs:
+            subject_root = self.root / f"sub-{str(sub).replace('sub-', '')}"
+            sessions = get_entity_vals(subject_root, "session") or []
+
+            for s in sessions:
+                try:
+                    si = int(str(s).replace("ses-", ""))
+                except ValueError:
+                    continue
+
+                if outlier_thresh is not None and si > outlier_thresh:
+                    warnings.warn(f"Session number is over {outlier_thresh}. Double check dataset.")
+                else:
+                    max_ses = si if max_ses is None else max(max_ses, si)
+
+        return max_ses

bidsreader/cmlbidsreader.py

@@ -0,0 +1,269 @@
+import numpy as np
+import pandas as pd
+import mne
+from mne_bids import read_raw_bids
+from pathlib import Path
+from typing import Iterable, Tuple, Optional, Union, Dict
+import warnings
+import json
+from .basereader import BaseReader
+from ._errorwrap import public_api
+from .helpers import validate_option, space_from_coordsystem_fname, combine_bipolar_electrodes
+from .exc import InvalidOptionError, FileNotFoundBIDSError, AmbiguousMatchError, DataParseError
+
+CML_ROOT = "/data/LTP_BIDS"
+
+
+class CMLBIDSReader(BaseReader):
+    VALID_ACQ = ("bipolar", "monopolar")
+    VALID_DEVICES = ("eeg", "ieeg")
+    INTRACRANIAL_FIELDS = ("subject", "task", "session", "device")
+    SCALP_FIELDS = ("subject", "task", "session", "device")
+
+    def __init__(
+        self,
+        root: Optional[Union[str, Path]] = CML_ROOT,
+        subject: Optional[str] = None,
+        task: Optional[str] = None,
+        session: Optional[str | int] = None,
+        space: Optional[str] = None,
+        acquisition: Optional[str] = None,
+        device: Optional[str] = None,
+    ):
+        device = validate_option(
+            "device", device, self.VALID_DEVICES
+        )
+        super().__init__(
+            root=root,
+            subject=subject,
+            task=task,
+            session=session,
+            space=space,
+            acquisition=acquisition,
+            device=device,
+        )
+
+    # ---------- internal helpers ----------
+
+    def _determine_device(self) -> Optional[str]:
+        if self.subject is None:
+            return None
+        if self.subject.startswith("LTP"):
+            return "eeg"
+        if self.subject.startswith("R"):
+            return "ieeg"
+        return None
+
+    def _determine_space(self) -> str:
+        subject_root = self._subject_root()
+        data_dir = subject_root / self._add_bids_prefix("session", self.session) / self.device
+
+        if not data_dir.exists():
+            raise FileNotFoundBIDSError(
+                f"determine_space: data directory does not exist.\n"
+                f"subject_root={subject_root}\n"
+                f"data_dir={data_dir}"
+            )
+
+        matches = list(data_dir.glob("*_coordsystem.json"))
+        if not matches:
+            raise FileNotFoundBIDSError(
+                f"determine_space: no *_coordsystem.json file found.\n"
+                f"data_dir={data_dir}"
+            )
+
+        if len(matches) > 1:
+            raise AmbiguousMatchError(
+                f"determine_space: multiple coordsystem files found.\n"
+                f"files={[m.name for m in matches]}"
+            )
+
+        fname = matches[0].name
+        space = space_from_coordsystem_fname(fname)
+
+        if space is None:
+            raise DataParseError(
+                f"determine_space: could not parse space from filename.\n"
+                f"filename={fname}"
+            )
+
+        return space
+
+    def _validate_acq(self, acquisition: Optional[str]) -> Optional[str]:
+        if not self.is_intracranial():
+            return None
+        if acquisition is None:
+            raise InvalidOptionError("acquisition is set to None")
+        return validate_option("acquisition", acquisition, self.VALID_ACQ)
+
+    def _get_needed_fields(self):
+        return self.INTRACRANIAL_FIELDS if self.is_intracranial() else self.SCALP_FIELDS
+
+    def _attach_bipolar_midpoint_montage(self, raw: mne.io.BaseRaw) -> None:
+        pairs_df = self.load_channels("bipolar")
+        elec_df = self.load_electrodes()
+        combo = combine_bipolar_electrodes(pairs_df, elec_df)
+
+        if not {"name", "x_mid", "y_mid", "z_mid"}.issubset(combo.columns):
+            return
+
+        ch_pos = {
+            str(r["name"]): (float(r["x_mid"]), float(r["y_mid"]), float(r["z_mid"]))
+            for _, r in combo.iterrows()
+            if np.isfinite(r["x_mid"]) and np.isfinite(r["y_mid"]) and np.isfinite(r["z_mid"])
+        }
+        if not ch_pos:
+            return
+
+        montage = mne.channels.make_dig_montage(ch_pos=ch_pos, coord_frame="mni_tal")
+        raw.set_montage(montage, on_missing="ignore")
+
+    # ---------- public API ----------
+
+    @public_api
+    def is_intracranial(self) -> bool:
+        return self.device == "ieeg"
+
+    # ---------- loaders ----------
+
+    @public_api
+    def load_events(self, event_type: str = "beh") -> pd.DataFrame:
+        self._require(self._get_needed_fields(), context="load_events")
+        allowed = ["beh", self.device]
+        event_type = validate_option("event_type", event_type, allowed)
+        suffix = "beh" if event_type == "beh" else "events"
+
+        bp = self._bp(
+            datatype=event_type,
+            suffix=suffix,
+            extension=".tsv",
+        )
+
+        matches = bp.match()
+        if not matches:
+            raise FileNotFoundBIDSError(f"load_events: no file matched for {bp}")
+
+        return pd.read_csv(matches[0].fpath, sep="\t")
+
+    @public_api
+    def load_electrodes(self) -> pd.DataFrame:
+        self._require(self._get_needed_fields(), context="load_electrodes")
+
+        _task = self.task if self.is_intracranial() else None
+        bp = self._bp(datatype=self.device, suffix="electrodes", space=self.space, task=_task, extension=".tsv")
+        return pd.read_csv(bp.fpath, sep="\t")
+
+    @public_api
+    def load_channels(self, acquisition: Optional[str] = None) -> pd.DataFrame:
+        self._require(self._get_needed_fields(), context="load_channels")
+
+        acq = self._validate_acq(acquisition)
+        bp = self._bp(datatype=self.device, suffix="channels", acquisition=acq, extension=".tsv")
+        return pd.read_csv(bp.fpath, sep="\t")
+
+    @public_api
+    def load_combined_channels(self, acquisition: Optional[str] = None) -> pd.DataFrame:
+        self._require(self._get_needed_fields(), context="load_combined_channels")
+
+        channel_df = self.load_channels(acquisition)
+        elec_df = self.load_electrodes()
+        if acquisition == "monopolar" or acquisition is None:
+            return channel_df.merge(elec_df, on="name", how="left", suffixes=("", "_elec"))
+        if acquisition == "bipolar":
+            return combine_bipolar_electrodes(channel_df, elec_df)
+
+    @public_api
+    def load_coordsystem_desc(self) -> Dict:
+        self._require(self._get_needed_fields(), context="load_coordsystem")
+
+        _task = self.task if self.is_intracranial() else None
+        bp = self._bp(datatype=self.device, suffix="coordsystem", space=self.space, task=_task, extension=".json")
+
+        with open(bp.fpath, "r") as f:
+            return json.load(f)
+
+    @public_api
+    def load_raw(self, acquisition: Optional[str] = None) -> mne.io.BaseRaw:
+        self._require(self._get_needed_fields(), context="load_raw")
+
+        acq = self._validate_acq(acquisition)
+
+        bp_kwargs = {"datatype": self.device}
+        if acq is not None:
+            bp_kwargs["acquisition"] = acq
+        bp = self._bp(**bp_kwargs)
+
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                "ignore",
+                message=r"DigMontage is only a subset of info\.",
+                category=RuntimeWarning,
+            )
+            warnings.filterwarnings(
+                "ignore",
+                message=r".*is not an MNE-Python coordinate frame.*",
+                category=RuntimeWarning,
+            )
+            raw = read_raw_bids(bp)
+
+        if self.is_intracranial() and acq == "bipolar":
+            self._attach_bipolar_midpoint_montage(raw)
+
+        return raw
+
+    @public_api
+    def load_epochs(
+        self,
+        tmin: float,
+        tmax: float,
+        events: Optional[pd.DataFrame] = None,
+        baseline: Optional[Tuple[float | None, float | None]] = None,
+        acquisition: Optional[str] = None,
+        event_repeated: str = "merge",
+        channels: Optional[Iterable[str]] = None,
+        preload: bool = False,
+    ) -> mne.Epochs:
+        self._require(self._get_needed_fields(), context="load_epochs")
+        raw = self.load_raw(acquisition=acquisition)
+
+        all_events_raw, all_event_id = mne.events_from_annotations(raw)
+
+        if events is not None:
+            if "sample" not in events.columns:
+                raise ValueError("Events DataFrame must contain a 'sample' column")
+
+            if "trial_type" in events.columns:
+                codes = events["trial_type"].map(all_event_id)
+                if codes.isna().any():
+                    missing = set(events.loc[codes.isna(), "trial_type"].unique())
+                    raise ValueError(
+                        f"trial_type values not found in raw annotations: {missing}"
+                    )
+                codes = codes.values.astype(int)
+                present_types = set(events["trial_type"].unique())
+                event_id = {k: v for k, v in all_event_id.items() if k in present_types}
+            else:
+                codes = np.ones(len(events), dtype=int)
+                event_id = {"event": 1}
+
+            events_raw = np.column_stack([
+                events["sample"].values.astype(int),
+                np.zeros(len(events), dtype=int),
+                codes,
+            ])
+        else:
+            events_raw = all_events_raw
+            event_id = all_event_id
+
+        picks = list(channels) if channels is not None else None
+        return mne.Epochs(
+            raw,
+            events=events_raw,
+            event_id=event_id,
+            tmin=tmin,
+            tmax=tmax,
+            baseline=baseline,
+            preload=preload,
+            event_repeated=event_repeated,
+            picks=picks,
+        )

bidsreader/convert.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import mne
+import numpy as np
+import pandas as pd
+from typing import Iterable, Optional, TYPE_CHECKING
+from ._errorwrap import public_api
+from .helpers import merge_duplicate_sample_events
+
+if TYPE_CHECKING:
+    from ptsa.data.timeseries import TimeSeries
+
+
+@public_api
+def mne_epochs_to_ptsa(epochs: mne.Epochs, events: pd.DataFrame) -> TimeSeries:
+    from ptsa.data.timeseries import TimeSeries
+    events = merge_duplicate_sample_events(events)
+    return TimeSeries.from_mne_epochs(epochs, events)
+
+
+@public_api
+def mne_raw_to_ptsa(raw: mne.io.BaseRaw, picks: Optional[Iterable[str]] = None, tmin: float = None, tmax: float = None) -> TimeSeries:
+    from ptsa.data.timeseries import TimeSeries
+
+    inst = raw.copy()
+    if tmin is not None or tmax is not None:
+        inst.crop(tmin=tmin, tmax=tmax)
+
+    if picks is not None:
+        if all(isinstance(p, str) for p in picks):
+            pick_idx = [inst.ch_names.index(ch) for ch in picks]
+        else:
+            pick_idx = list(picks)
+
+        data = inst.get_data(picks=pick_idx)
+        ch_names = [inst.ch_names[i] for i in pick_idx]
+    else:
+        data = inst.get_data()
+        ch_names = inst.ch_names
+
+    sfreq = float(inst.info["sfreq"])
+    times = inst.times
+
+    ts = TimeSeries.create(
+        data,
+        samplerate=sfreq,
+        dims=("channel", "time"),
+        coords={
+            "channel": np.asarray(ch_names, dtype=object),
+            "time": np.asarray(times, dtype=float),
+        },
+        attrs={
+            "mne_meas_date": str(inst.info.get("meas_date")),
+            "mne_first_samp": int(inst.first_samp),
+        },
+    )
+    return ts

bidsreader/exc.py

@@ -0,0 +1,23 @@
+class BIDSReaderError(Exception):
+    """ Generic exception for all BIDS Reader exceptions """
+
+class InvalidOptionError(BIDSReaderError, ValueError):
+    """ Raised when an input is not among options. """
+
+class MissingRequiredFieldError(BIDSReaderError, ValueError):
+     """ Raised when a required field is missing when loading file using BIDSPath. """
+
+class FileNotFoundBIDSError(BIDSReaderError, FileNotFoundError):
+    """ Raised when a BIDS file is not found. """
+
+class AmbiguousMatchError(BIDSReaderError, Exception):
+    """ Raised when multiple files are returned when searching. """
+
+class DataParseError(BIDSReaderError):
+    """TSV/JSON parsing, schema issues, etc."""
+
+class DependencyError(BIDSReaderError):
+    """Errors originating from optional deps or incompatible versions."""
+
+class ExternalLibraryError(BIDSReaderError):
+    """Fallback wrapper when MNE/pandas/etc. throws something unexpected."""