.. _data_guide:

==========
Data Guide
==========

This guide focus is a high-level "data dictionary" of files generated within
the CML and supported by the CMLReaders package. For more information on the
locations of the files, see :mod:`cmlreaders.constants`. In the table below,
each row corresponds to a particular file type that is supported by the
CMLReaders package. The table contains the following fields:

- Data Type: Identifier that can be used for loading/interacting with the data
- Description: Short description of the information contained in the file
- Format: The format of the underlying file
- Generated By: A link to the pipeline/code that produces the file
- Used By: One or more links to code repositories or processing pipelines
  that use, or are otherwise dependent upon, this file.
- Level: The level, at which, the file is guaranteed to be unique. For example, a
  level of "subject" indicates that there is one file per subject regardless of
  localization or experiments/tasks completed.

The following "levels" are defined:

- protocol: A synonym for "project" or "study." For example, RAM data is part
  of the "r1" protocol, while scalp experiments are part of the "ltp" protocol.
- subject: A single participant in a study. Typically, subject identifiers are
  6 alpha-numeric characters in length, for example R1001P.
- localization: Each time a subject undergoes surgery to add or remove
  electrodes, this is considered a new localization. Localizations are 0-indexed.
  Data at this level changes whenever there is a new localization,
- montage: Any change to a subject's montage results in a new montage number.
  Montage changes can occur when when the set of contacts used for recording
  changes. Note: Montage numbers do not reset in the case of a new localization.
- session: Data that is unique to a single session of a particular experiment.
  This is the lowest level of data stored since localization/montage/etc. are
  fixed for the duration of a session.

.. csv-table::
    :file: data_dictionary.csv
    :widths: 10, 10, 10, 10, 10, 10

.. _ramutils: https://github.com/pennmem/ram_utils
.. _classiflib: https://github.com/pennmem/classiflib
.. _brainviewer: https://github.com/pennmem/brain_viz
.. _brain_viz_unity: https://github.com/pennmem/brain_viz_unity
.. _event_creation: https://github.com/pennmem/event_creation
.. _neurorad: https://github.com/pennmem/neurorad_pipeline
.. _localization: https://memory.psych.upenn.edu/InternalWiki/Neurorad_Pipeline_v2
.. _bptools: https://github.com/pennmem/bptools