eegprep 0.0.2__tar.gz → 0.1.0__tar.gz

eegprep-0.1.0/LICENSE

@@ -0,0 +1,25 @@
+BSD 2-Clause License
+
+Copyright (c) 2025, Swartz Center for Computational Neuroscience
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+THE POSSIBILITY OF SUCH DAMAGE.

eegprep-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: eegprep
+Version: 0.1.0
+Summary: EEG preprocessing pipeline on Python
+Author-email: Arnaud Delorme <adelorme@gmail.com>, Young Truong <dt.young112@gmail.com>
+License: BSD 2-Clause License
+        
+        Copyright (c) 2025, Swartz Center for Computational Neuroscience
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice,
+        this list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+        this list of conditions and the following disclaimer in the documentation
+        and/or other materials provided with the distribution.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+        ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+        LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+        SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+        INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+        CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+        ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+        THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: Homepage, https://github.com/sccn/eegprep
+Project-URL: Issues, https://github.com/sccn/eegprep/issues
+Keywords: eeg,preprocessing,EEGLAB
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: colorama>=0.4.6
+Requires-Dist: h5py>=3.3.0
+Requires-Dist: matplotlib>=3.4.0
+Requires-Dist: mne>=1.10.0
+Requires-Dist: neo>=0.14.2
+Requires-Dist: numpy<2
+Requires-Dist: oct2py>=5.5.0
+Requires-Dist: psutil>=7.0.0
+Requires-Dist: pybids>=0.4
+Requires-Dist: pyedflib>=0.1.42
+Requires-Dist: python-picard<0.9,>=0.8
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: sympy>=1.14.0
+Requires-Dist: threadpoolctl>=3.6.0
+Provides-Extra: torch
+Requires-Dist: torch>=1.10.0; extra == "torch"
+Provides-Extra: all
+Requires-Dist: torch>=1.10.0; extra == "all"
+Dynamic: license-file
+
+# EEGPrep
+
+EEGPrep is a Python package that reproduces the EEGLAB default preprocessing pipeline with numerical accuracy down to 1e-5 uV, including clean_rawdata and ICLabel, enabling MATLAB-to-Python equivalence for EEG analysis. It takes BIDS data as input and produces BIDS derivative dataset as output, which can then be reimported into other packages as needed (EEGLAB, Fieldtrip, Brainstorm, MNE). It does produce plots. The package will be fully documented for conversion, packaging, and testing workflows, with installation available via PyPI.
+
+## Pre-Release
+
+EEGPrep is currently in a pre-release phase. It functions end-to-end (bids branch) but has not yet been tested with multiple BIDS datasets. The documentation is incomplete, and use is at your own risk. The planned release is scheduled for the end of 2025.
+
+
+## Install
+
+To install the complete EEGPrep including the ICLabel classifier (which can pull in ~7GB of binaries on Linux), use the following line:
+```
+pip install eegprep[all]
+```
+
+To install the lean version:
+```
+pip install eegprep
+```
+
+You can then manually install a lightweight CPU-only version of PyTorch if desired by 
+your operating system.
+
+
+# Comparing MATLAB and Python implementations
+
+The MATLAB and Python implementations were compared using the first two subjects from the BIDS datasets [ds003061](https://nemar.org/dataexplorer/detail?dataset_id=ds003061) and [ds002680](https://nemar.org/dataexplorer/detail?dataset_id=ds002680) available on NEMAR. The observed differences were extremely small, with the largest (during HighpassFilter) below 0.002, indicating excellent numerical consistency between the two implementations.
+
+<img width="1744" height="1049" alt="Screenshot 2025-10-02 at 11 43 03" src="https://github.com/user-attachments/assets/79c17151-e2e3-4acc-b144-accdf34ae4c5" />
+
+# Docker (SCCN Power Users)
+
+## Build Docker
+
+```
+docker run --rm -it -v $(pwd):/usr/src/project dtyoung/eegprep /bin/bash
+docker run -u root --rm -it -v $(pwd):/usr/src/project dtyoung/eegprep /bin/bash
+```
+
+## Remove Docker
+
+```
+docker rmi dtyoung/eegprep
+```
+
+Mounted folder in /usr/src/project
+
+# PYPI Release Process (Maintainers Only)
+
+## Quick Release Workflow
+
+Use the release script for streamlined releases:
+
+```bash
+python scripts/make_release.py
+```
+
+The script will:
+1. Check prerequisites (build, twine, git status)
+2. Confirm the version from `pyproject.toml`
+3. Let you choose: test release, production release, or both
+4. Build and upload the package (automatically uses `eegprep_test` name for TestPyPI)
+5. Create and push git tags for production releases
+
+> **Note:** The script automatically handles a TestPyPI naming conflict by building a package
+> with the name `eegprep_test` for test releases.
+
+## Prerequisites
+
+Install build tools:
+```bash
+pip install build twine
+```
+
+## API Tokens
+- Get API token for PyPI and TestPyPI (both maintainers should have these)
+- Twine will prompt for them during upload
+- Store them in `~/.pypirc` for convenience
+
+## Manual Release Process
+
+**Recommended:** Use `scripts/make_release.py` instead to avoid manual errors with package naming.
+
+If you need to release manually:
+
+**1. Update version in `pyproject.toml`**
+
+**2. Test release (staging):**
+
+> **Note:** A former maintainer owns the `eegprep` package name on TestPyPI, so you will not be able to post a 
+> package named `eegprep` there at this time. 
+> To work around this when performing the build manually (note the `make_release.py` script handles this for you), temporarily change the package name to `eegprep_test` in `pyproject.toml` before building.
+> Remember to change it back to `eegprep` after uploading!
+
+```bash
+# In pyproject.toml, temporarily change: name = "eegprep" to name = "eegprep_test"
+python -m build
+python -m twine upload --repository testpypi dist/*
+# Change name back to "eegprep" in pyproject.toml
+
+# Test the installation:
+pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ eegprep_test==X.Y.Z
+# (imports still work as 'import eegprep')
+```
+
+**3. Production release:**
+```bash
+python -m twine upload dist/*
+git tag -a vX.Y.Z -m "Release version X.Y.Z"
+git push origin vX.Y.Z
+pip install eegprep==X.Y.Z
+```
+
+## Documentation
+https://packaging.python.org/en/latest/tutorials/packaging-projects/
+
+## Install Package
+Packaging was done following the tutorial: https://packaging.python.org/en/latest/tutorials/packaging-projects/ with setuptools
+
+To install the package with all optional dependencies, run:
+```
+pip install eegprep[all]
+```
+
+## Running Tests
+
+Install MATLAB interface `pip install /your/path/to/matlab/extern/engines/python`
+Use tests/main_compare.m
+
+This project uses `unittest`. You can run tests from the project root via the command:
+```
+python -m unittest discover -s tests
+```
+...or use the unittest integration in your IDE (e.g., PyCharm, VS Code, or Cursor).
+
+## Core maintainers
+
+- Arnaud Delorme, UCSD, CA, USA
+- Christian Kothe, Intheon, CA, USA
+- Bruno Aristimunha Pinto, Inria, France

eegprep-0.1.0/README.md

@@ -0,0 +1,141 @@
+# EEGPrep
+
+EEGPrep is a Python package that reproduces the EEGLAB default preprocessing pipeline with numerical accuracy down to 1e-5 uV, including clean_rawdata and ICLabel, enabling MATLAB-to-Python equivalence for EEG analysis. It takes BIDS data as input and produces BIDS derivative dataset as output, which can then be reimported into other packages as needed (EEGLAB, Fieldtrip, Brainstorm, MNE). It does produce plots. The package will be fully documented for conversion, packaging, and testing workflows, with installation available via PyPI.
+
+## Pre-Release
+
+EEGPrep is currently in a pre-release phase. It functions end-to-end (bids branch) but has not yet been tested with multiple BIDS datasets. The documentation is incomplete, and use is at your own risk. The planned release is scheduled for the end of 2025.
+
+
+## Install
+
+To install the complete EEGPrep including the ICLabel classifier (which can pull in ~7GB of binaries on Linux), use the following line:
+```
+pip install eegprep[all]
+```
+
+To install the lean version:
+```
+pip install eegprep
+```
+
+You can then manually install a lightweight CPU-only version of PyTorch if desired by 
+your operating system.
+
+
+# Comparing MATLAB and Python implementations
+
+The MATLAB and Python implementations were compared using the first two subjects from the BIDS datasets [ds003061](https://nemar.org/dataexplorer/detail?dataset_id=ds003061) and [ds002680](https://nemar.org/dataexplorer/detail?dataset_id=ds002680) available on NEMAR. The observed differences were extremely small, with the largest (during HighpassFilter) below 0.002, indicating excellent numerical consistency between the two implementations.
+
+<img width="1744" height="1049" alt="Screenshot 2025-10-02 at 11 43 03" src="https://github.com/user-attachments/assets/79c17151-e2e3-4acc-b144-accdf34ae4c5" />
+
+# Docker (SCCN Power Users)
+
+## Build Docker
+
+```
+docker run --rm -it -v $(pwd):/usr/src/project dtyoung/eegprep /bin/bash
+docker run -u root --rm -it -v $(pwd):/usr/src/project dtyoung/eegprep /bin/bash
+```
+
+## Remove Docker
+
+```
+docker rmi dtyoung/eegprep
+```
+
+Mounted folder in /usr/src/project
+
+# PYPI Release Process (Maintainers Only)
+
+## Quick Release Workflow
+
+Use the release script for streamlined releases:
+
+```bash
+python scripts/make_release.py
+```
+
+The script will:
+1. Check prerequisites (build, twine, git status)
+2. Confirm the version from `pyproject.toml`
+3. Let you choose: test release, production release, or both
+4. Build and upload the package (automatically uses `eegprep_test` name for TestPyPI)
+5. Create and push git tags for production releases
+
+> **Note:** The script automatically handles a TestPyPI naming conflict by building a package
+> with the name `eegprep_test` for test releases.
+
+## Prerequisites
+
+Install build tools:
+```bash
+pip install build twine
+```
+
+## API Tokens
+- Get API token for PyPI and TestPyPI (both maintainers should have these)
+- Twine will prompt for them during upload
+- Store them in `~/.pypirc` for convenience
+
+## Manual Release Process
+
+**Recommended:** Use `scripts/make_release.py` instead to avoid manual errors with package naming.
+
+If you need to release manually:
+
+**1. Update version in `pyproject.toml`**
+
+**2. Test release (staging):**
+
+> **Note:** A former maintainer owns the `eegprep` package name on TestPyPI, so you will not be able to post a 
+> package named `eegprep` there at this time. 
+> To work around this when performing the build manually (note the `make_release.py` script handles this for you), temporarily change the package name to `eegprep_test` in `pyproject.toml` before building.
+> Remember to change it back to `eegprep` after uploading!
+
+```bash
+# In pyproject.toml, temporarily change: name = "eegprep" to name = "eegprep_test"
+python -m build
+python -m twine upload --repository testpypi dist/*
+# Change name back to "eegprep" in pyproject.toml
+
+# Test the installation:
+pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ eegprep_test==X.Y.Z
+# (imports still work as 'import eegprep')
+```
+
+**3. Production release:**
+```bash
+python -m twine upload dist/*
+git tag -a vX.Y.Z -m "Release version X.Y.Z"
+git push origin vX.Y.Z
+pip install eegprep==X.Y.Z
+```
+
+## Documentation
+https://packaging.python.org/en/latest/tutorials/packaging-projects/
+
+## Install Package
+Packaging was done following the tutorial: https://packaging.python.org/en/latest/tutorials/packaging-projects/ with setuptools
+
+To install the package with all optional dependencies, run:
+```
+pip install eegprep[all]
+```
+
+## Running Tests
+
+Install MATLAB interface `pip install /your/path/to/matlab/extern/engines/python`
+Use tests/main_compare.m
+
+This project uses `unittest`. You can run tests from the project root via the command:
+```
+python -m unittest discover -s tests
+```
+...or use the unittest integration in your IDE (e.g., PyCharm, VS Code, or Cursor).
+
+## Core maintainers
+
+- Arnaud Delorme, UCSD, CA, USA
+- Christian Kothe, Intheon, CA, USA
+- Bruno Aristimunha Pinto, Inria, France

eegprep-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "eegprep"
+version = "0.1.0"
+authors = [
+  { name="Arnaud Delorme", email="adelorme@gmail.com" },
+  { name="Young Truong", email="dt.young112@gmail.com" },
+]
+description = "EEG preprocessing pipeline on Python"
+readme = { file = "README.md", content-type = "text/markdown" }
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: BSD License",
+    "Operating System :: OS Independent",
+]
+keywords = ["eeg", "preprocessing", "EEGLAB"]
+dependencies = [
+  "colorama>=0.4.6",
+  "h5py>=3.3.0",
+  "matplotlib>=3.4.0",
+  "mne>=1.10.0",
+  "neo>=0.14.2",
+  "numpy<2",
+  "oct2py>=5.5.0",
+  "psutil>=7.0.0",
+  "pybids>=0.4",
+  "pyedflib>=0.1.42",
+  "python-picard>=0.8,<0.9",
+  "scipy>=1.7.0",
+  "sympy>=1.14.0",
+  "threadpoolctl>=3.6.0",
+]
+
+[project.optional-dependencies]
+torch = [
+  "torch>=1.10.0",
+]
+all = [
+  "torch>=1.10.0",
+]
+
+[tool.setuptools]
+include-package-data = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+exclude = ["eegprep.eeglab*"]
+
+[tool.setuptools.package-data]
+"eegprep" = [
+  "resources/montages/*.locs",
+  "resources/montages/README.md",
+  "resources/*.m"
+]
+
+[tool.setuptools.exclude-package-data]
+"eegprep" = ["eeglab/**"]
+
+
+[project.urls]
+Homepage = "https://github.com/sccn/eegprep"
+Issues = "https://github.com/sccn/eegprep/issues"

{eegprep-0.0.2 → eegprep-0.1.0}/src/eegprep/ICL_feature_extractor.py

@@ -1,12 +1,14 @@
+from copy import deepcopy
 import numpy as np
-from .topoplot import topoplot
-from .eeg_rpsd import eeg_rpsd
-from .eeg_autocorr_welch import eeg_autocorr_welch
-from .eeg_autocorr import eeg_autocorr
-from .eeg_autocorr_fftw import eeg_autocorr_fftw
-from .pop_reref import pop_reref
 
 def ICL_feature_extractor(EEG, flag_autocorr=False):
+    from eegprep import topoplot
+    from eegprep import eeg_rpsd
+    from eegprep import eeg_autocorr_welch
+    from eegprep import eeg_autocorr
+    from eegprep import eeg_autocorr_fftw
+    from eegprep import pop_reref
+    EEG = deepcopy(EEG)
 
     # Check inputs
     ncomp = EEG['icawinv'].shape[1]

eegprep-0.1.0/src/eegprep/__init__.py

@@ -0,0 +1,44 @@
+import logging
+
+from .utils.logs import setup_logging
+setup_logging(logging.INFO)
+
+from .iclabel import iclabel
+from .pop_saveset import pop_saveset
+from .pop_loadset import loadset, pop_loadset
+from .pop_loadset_h5 import pop_loadset_h5
+from .pop_resample import pop_resample
+from .eeg_checkset import eeg_checkset
+from .eeglabcompat import pop_eegfiltnew
+from .eeglabcompat import clean_artifacts as eeglab_clean_artifacts
+from .ICL_feature_extractor import ICL_feature_extractor
+from .topoplot import topoplot
+from .eeg_rpsd import eeg_rpsd
+from .eeg_autocorr_welch import eeg_autocorr_welch
+from .eeg_autocorr import eeg_autocorr
+from .eeg_autocorr_fftw import eeg_autocorr_fftw
+from .pop_reref import pop_reref
+from .eeg_picard import eeg_picard
+from .clean_flatlines import clean_flatlines
+from .clean_drifts import clean_drifts
+from .clean_channels_nolocs import clean_channels_nolocs
+from .clean_channels import clean_channels
+from .clean_asr import clean_asr
+from .clean_windows import clean_windows
+from .eeg_compare import eeg_compare
+from .eeg_interp import eeg_interp
+from .clean_artifacts import clean_artifacts
+from .pop_load_frombids import pop_load_frombids
+from .bids_list_eeg_files import bids_list_eeg_files
+from .bids_preproc import bids_preproc
+from .eeg_decodechan import eeg_decodechan
+from .eegrej import eegrej
+from .eeg_eegrej import eeg_eegrej
+from .eegobj import EEGobj
+from .redefine_functions import *
+from .eeg_mne2eeg import eeg_mne2eeg
+from .eeg_mne2eeg_epochs import eeg_mne2eeg_epochs
+from .eeg_lat2point import eeg_lat2point
+from .eeg_point2lat import eeg_point2lat
+from .eeg_options import EEG_OPTIONS
+from .eeg_checkset import eeg_checkset, strict_mode as eeg_checkset_strict_mode

eegprep-0.1.0/src/eegprep/bids_list_eeg_files.py

@@ -0,0 +1,108 @@
+import os
+import logging
+from typing import List, Sequence
+from types import NoneType
+from eegprep.utils.bids import layout_for_fpath
+
+logger = logging.getLogger(__name__)
+
+
+# list of valid file extensions for raw EEG data files in BIDS format
+eeg_extensions = ('.vhdr', '.edf', '.bdf', '.set')
+
+
+def bids_list_eeg_files(
+        root: str,
+        subjects: Sequence[str | int] | str | int = (),
+        sessions: Sequence[str | int] | str | int = (),
+        runs: Sequence[str | int] | str | int = (),
+        tasks: Sequence[str | int] | str | int = (),
+) -> List[str]:
+    """
+    Return a list of all EEG raw-data files in a BIDS dataset.
+
+    Parameters:
+    -----------
+    root : str
+        The root directory containing BIDS data.
+    subjects : Sequence[str | int], optional
+        A sequence of subject identifiers or (zero-based) indices to filter the files by.
+        If empty, all subjects are included.
+    sessions : Sequence[str | int], optional
+        A sequence of session identifiers or (zero-based) indices to filter the files by.
+        If empty, all sessions are included.
+    runs : Sequence[str | int], optional
+        A sequence of run numbers or identifiers to filter the files by. If empty, all runs
+        are included. Note that zero-based indexing does not apply to runs, unlike
+        subjects and sessions since runs are already integers.
+    tasks : Sequence[str] | str, optional
+        A sequence of task names or single task to filter the files by. If empty, all
+        tasks are included (default is an empty sequence).
+
+    Returns:
+    --------
+
+    List[str]
+        A list of file paths to EEG files in the BIDS dataset.
+    """
+    layout = layout_for_fpath(root)
+    
+    # prepare filters, if any
+    filters = {
+        'subject': [subjects] if isinstance(subjects, (str, int)) else subjects,
+        'session': [sessions] if isinstance(sessions, (str, int)) else sessions,
+        'run': [runs] if isinstance(runs, (str, int)) else runs,
+        'task': [tasks] if isinstance(tasks, (str, int)) else tasks,
+    }
+    filters = {k: v for k, v in filters.items() if v}  # remove empty filters
+
+    # first get all EEG files
+    eeg_files = layout.get(suffix='eeg', return_type='filename' if not filters else 'object')
+    
+    # apply filters
+    if filters:
+        for key, query_values in filters.items():
+            for v in query_values:
+                if isinstance(v, str) and '-' in v and v.split('-')[0] in ('sub', 'ses', 'run', 'task'):
+                    raise ValueError("Query values should not be formatted with 'sub-', 'ses-', "
+                                     "'run-', or 'task-' prefixes. Use the raw identifiers instead.")
+            data_values = [f.entities.get(key, None) for f in eeg_files]
+            if all(v is None for v in data_values):
+                # key is missing from entire dataset: ignore the filter
+                logger.info(f"Dataset at {root} does not contain any files with the key '{key}'; "
+                            f"ignoring the filter.")
+            elif all(isinstance(v, int) for v in data_values):
+                # all items are integers; make sure our queries are also integers if they're not already
+                if any(isinstance(v, str) for v in query_values):
+                    # uniformize query values to integer
+                    try:
+                        query_values = [int(v) for v in query_values]
+                    except Exception as e:
+                        raise ValueError(f"When filtering by {key}, use integers for the query ({e})")
+                eeg_files = [f for f in eeg_files if f.entities[key] in query_values]
+            else:
+                # data values might be some sort of mix of ints, strings, or None
+                # querying those strings by index (with integers)
+                if all(isinstance(v, int) for v in query_values):
+                    # index the applicable values (eg subjects) with integers, alphabetically
+                    # strip any missing candidates
+                    data_values = [dv for dv in data_values if dv is not None and dv != '']
+                    # normalize data values to strings
+                    data_values = [str(dv) for dv in data_values]
+                    # get unique values, sorted alphabetically
+                    uq_values = sorted(set(data_values))
+                    # rewrite the query values into the first k sorted unique strings
+                    query_values = [uq_values[i] for i in query_values if i < len(uq_values)]
+                if all(isinstance(v, str) for v in query_values):
+                    # all query values are strings now, can do a direct lookup
+                    eeg_files = [f for f in eeg_files if str(f.entities.get(key)) in query_values]
+                else:
+                    raise ValueError(f"query values for {key} must either all be strings or all "
+                                     f"integers, but were: {query_values}")
+        # reduce to file paths
+        eeg_files = [eeg_file.path for eeg_file in eeg_files]
+
+    # have to filter by extension since the layout will also return the sidecar files
+    # (e.g., .fdt and .vmrk) and other files that are not raw EEG data files
+    filelist = [fn for fn in eeg_files if fn.endswith(eeg_extensions)]
+    return filelist