This repository contains a collection of utility classes for reading lab-specific file formats. Many of these readers have previously existed in other repositories, but are being migrated to a single repository since they are logically related.

More information and usage examples are provided in the documentation.

The following assumes you have already installed Anaconda or Miniconda.

conda create -y -n environment_name python=3
source activate environment_name
conda install -c pennmem cmlreaders

conda install -y bottleneck

What follows are some basic usage examples. See the documentation for a more complete guide to getting started.

Get the index of all RAM data:

>>> from cmlreaders import CMLReader
>>> ix = CMLReader.get_data_index("r1")

Find unique experiments performed by R1111M:

>>> ix[ix["subject"] == "R1111M"]["experiment"].unique()
array(['FR1', 'FR2', 'PAL1', 'PAL2', 'PS2', 'catFR1'], dtype=object)

Load montage pair data from FR1 session 0:

>>> reader = CMLReader("R1111M", "FR1", 0)
>>> pairs = reader.load("pairs")
>>> pairs.columns()
Index(['contact_1', 'contact_2', 'label', 'is_stim_only', 'type_1', 'type_2',
       'avg.dural.region', 'avg.dural.x', 'avg.dural.y', 'avg.dural.z',
       'avg.region', 'avg.x', 'avg.y', 'avg.z', 'dk.region', 'dk.x', 'dk.y',
       'dk.z', 'id', 'ind.dural.region', 'ind.dural.x', 'ind.dural.y',
       'ind.dural.z', 'ind.region', 'ind.x', 'ind.y', 'ind.z', 'is_explicit',
       'stein.region', 'stein.x', 'stein.y', 'stein.z', 'tal.region', 'tal.x',
       'tal.y', 'tal.z', 'wb.region', 'wb.x', 'wb.y', 'wb.z'],
      dtype='object')

Select word onset events:

>>> events = reader.load("events")
>>> words = events[events["type"] == "WORD"]
>>> len(words)
288

Load EEG 100 ms before and after word onset using the bipolar referencing scheme:

>>> eeg = reader.load_eeg(events=words, rel_start=-100, rel_stop=100, scheme=pairs)
>>> eeg.data.shape
(288, 141, 100)

Contributions are always welcome so that we can read more kinds of data with a common interface. To do so, fork this repository and create a separate branch and submit a pull request with your changes or additions. See the developer's guide in the documentation for more helpful hints.

Since this repository is specific to the data formats of the lab, almost all tests require RHINO access. To run the test suite from a computer with RHINO mounted:

pytest cmlreaders/ --rhino-root [path_to_mount_point] --cov=html

Upon completion, the coverage report will be saved into htmlcov/ in the top level directory of the project.