Skip to content

Commit

Permalink
[pre-commit.ci] auto fixes from pre-commit.com hooks
Browse files Browse the repository at this point in the history
for more information, see https://pre-commit.ci
  • Loading branch information
pre-commit-ci[bot] committed Dec 18, 2024
1 parent 5a2ac9f commit 190eb67
Showing 1 changed file with 86 additions and 86 deletions.
172 changes: 86 additions & 86 deletions src/modality-specific-files/microelectrode-electrophysiology.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,12 +30,12 @@ The current list of allowed data file formats:
| [Neuroscience Information Exchange Format](https://nixio.readthedocs.io/en/latest/) | `.nix` | A generic and open framework with an hdf5 backend and a defined interface to many ephys formats via the [Neo library](https://neo.readthedocs.io/en/latest/). The `.nix` file has to contain a valid Neo structure. |
| [Neurodata Without Borders](https://www.nwb.org) | `.nwb` | An open data standard for neurophysiology, including data from intracellular and extracellular electrophysiology experiments. |

Both of these formats can also store essential metadata of the datasets.
Some of this metadata needs to be duplicated in BIDS `.tsv` and `.json` sidecar files.
Even though the duplication requires additional effort to ensure the consistency of the data, it provides several advantages:
- It makes the dataset easier for humans to scan, as essential information is easily accessible without loading the data files.
- The dataset adheres to the BIDS standard and can benefit from tools built on top of this standard, such as [bids-validator](https://github.com/bids-standard/bids-validator).
- It simplifies the separation of data and basic metadata, enabling, for example, the publication of a dataset in a lightweight fashion with access to the data files on request (as implemented by [DataLad](https://www.datalad.org)).
Both of these formats can also store essential metadata of the datasets.
Some of this metadata needs to be duplicated in BIDS `.tsv` and `.json` sidecar files.
Even though the duplication requires additional effort to ensure the consistency of the data, it provides several advantages:
- It makes the dataset easier for humans to scan, as essential information is easily accessible without loading the data files.
- The dataset adheres to the BIDS standard and can benefit from tools built on top of this standard, such as [bids-validator](https://github.com/bids-standard/bids-validator).
- It simplifies the separation of data and basic metadata, enabling, for example, the publication of a dataset in a lightweight fashion with access to the data files on request (as implemented by [DataLad](https://www.datalad.org)).


##
Expand Down Expand Up @@ -88,11 +88,11 @@ As with all tsv-based metadata files in BIDS the probes, electrodes and channels

## Coordinate System JSON (`*_coordsystem.json`) & Photos of electrode positions (`_photo.jpg`)

This file provides metadata on the global coordinate system in which the electrodes are placed.
This file is **RECOMMENDED**, and the listed required fields below must be included if a `*_coordsystem.json` file is provided.
This file provides metadata on the global coordinate system in which the electrodes are placed.
This file is **RECOMMENDED**, and the listed required fields below must be included if a `*_coordsystem.json` file is provided.

The coordinate system can be defined using reference pictures, anatomical landmarks, brain images, or a reference atlas.
For more details, see the [BIDS Coordinate Systems specifications](../appendices/coordinate-systems.md).
The coordinate system can be defined using reference pictures, anatomical landmarks, brain images, or a reference atlas.
For more details, see the [BIDS Coordinate Systems specifications](../appendices/coordinate-systems.md).


Fields relating to the ephys probe and electrode positions:
Expand All @@ -109,37 +109,37 @@ Fields relating to the ephys probe and electrode positions:

### Allowed 2D coordinate systems

If electrodes are localized in 2D space (only `x` and `y` are specified, and `z` is `"n/a"`),
then the positions in this file MUST correspond to the locations expressed in pixels on the
photo, drawing, or rendering of the electrodes on the brain.
If electrodes are localized in 2D space (only `x` and `y` are specified, and `z` is `"n/a"`),
then the positions in this file MUST correspond to the locations expressed in pixels on the
photo, drawing, or rendering of the electrodes on the brain.

In this case, `ephysCoordinateSystem` MUST be defined as `"Pixels"`,
and `ephysCoordinateUnits` MUST be defined as `"pixels"` (note the difference in capitalization).
In this case, `ephysCoordinateSystem` MUST be defined as `"Pixels"`,
and `ephysCoordinateUnits` MUST be defined as `"pixels"` (note the difference in capitalization).

Furthermore, the coordinates MUST be `(row,column)` pairs,
with `(0,0)` corresponding to the upper-left pixel and `(N,0)` corresponding to the lower-left pixel.
Furthermore, the coordinates MUST be `(row,column)` pairs,
with `(0,0)` corresponding to the upper-left pixel and `(N,0)` corresponding to the lower-left pixel.


### Photos of the electrode positions (`*_photo.jpg`)

These can include photos of the electrodes on the brain surface,
photos of anatomical features or landmarks (such as sulcal structures), and fiducials.
Photos can also include an X-ray picture, a flatbed scan of a schematic drawing made during surgery,
or screenshots of a brain rendering with electrode positions.
These can include photos of the electrodes on the brain surface,
photos of anatomical features or landmarks (such as sulcal structures), and fiducials.
Photos can also include an X-ray picture, a flatbed scan of a schematic drawing made during surgery,
or screenshots of a brain rendering with electrode positions.

The photos may need to be cropped and/or blurred to conceal identifying features
or entirely omitted prior to sharing, depending on the obtained consent.
The photos may need to be cropped and/or blurred to conceal identifying features
or entirely omitted prior to sharing, depending on the obtained consent.

If there are photos of the electrodes, the [`_acq-<label>`](../appendices/entities.md#acq) entity should be specified with:
If there are photos of the electrodes, the [`_acq-<label>`](../appendices/entities.md#acq) entity should be specified with:

- `*_photo.jpg` for an operative photo.
- `*_acq-xray#_photo.<extension>` for an X-ray picture.
- `*_acq-drawing#_photo.<extension>` for a drawing or sketch of electrode placements.
- `*_acq-render#_photo.<extension>` for a rendering.
- `*_photo.jpg` for an operative photo.
- `*_acq-xray#_photo.<extension>` for an X-ray picture.
- `*_acq-drawing#_photo.<extension>` for a drawing or sketch of electrode placements.
- `*_acq-render#_photo.<extension>` for a rendering.

The file `<extension>` for photos MUST be either `.jpg`, `.png`, or `.tif`.
The file `<extension>` for photos MUST be either `.jpg`, `.png`, or `.tif`.

The [`ses-<label>`](../appendices/entities.md#ses) entity may be used to specify when the photo was taken.
The [`ses-<label>`](../appendices/entities.md#ses) entity may be used to specify when the photo was taken.


## **Multiple coordinate systems**
Expand All @@ -149,40 +149,40 @@ The optional[` space-<label>`](../appendices/entities.md#space) entity (`*[_spac

## Probes (*_probes.tsv)

Probes are physical devices used for recording animal electrophysiology (ephys) data.
They can be permanently implanted (chronic recordings) or inserted temporarily for the recording (acute recordings).
Probes are physical devices used for recording animal electrophysiology (ephys) data.
They can be permanently implanted (chronic recordings) or inserted temporarily for the recording (acute recordings).

The probe positions and properties are stored in a `.tsv` file.
This file contains the probe ID, the type of recording (acute/chronic), and the probe coordinates.
The surgical coordinates of the probe can be described using AP, DV, LR, yaw, pitch, and roll.
The probe positions and properties are stored in a `.tsv` file.
This file contains the probe ID, the type of recording (acute/chronic), and the probe coordinates.
The surgical coordinates of the probe can be described using AP, DV, LR, yaw, pitch, and roll.

These measurements follow the convention of the Pinpoint software for surgical planning and are intended to describe the surgical plan:
These measurements follow the convention of the Pinpoint software for surgical planning and are intended to describe the surgical plan:

### Translational Coordinates
- `(0,0,0)` is assumed to be Bregma when working with rodents.
- It may optionally be defined differently and **must** be defined for other species.
- `x, y, z` represents posterior, ventral, and right directions, respectively, in micrometers (`µm`).
- `(0,0,0)` is assumed to be Bregma when working with rodents.
- It may optionally be defined differently and **must** be defined for other species.
- `x, y, z` represents posterior, ventral, and right directions, respectively, in micrometers (`µm`).

### Rotational Coordinates
- `(0,0,0)` corresponds to the probe facing up with the tip pointing forward.
- Rotations are measured in degrees, clockwise, and around the tip.
- For multi-shank probes, the “tip” of the probe is defined as the end of the left shank when facing the electrodes.
- `(0,0,0)` corresponds to the probe facing up with the tip pointing forward.
- Rotations are measured in degrees, clockwise, and around the tip.
- For multi-shank probes, the “tip” of the probe is defined as the end of the left shank when facing the electrodes.

#### Rotation Definitions:
- **Yaw**: Clockwise rotation when looking down.
- **Pitch**: Rotation in the direction of the electrode face.
- **Roll**: Clockwise rotation when looking down at the probe.
- **Yaw**: Clockwise rotation when looking down.
- **Pitch**: Rotation in the direction of the electrode face.
- **Roll**: Clockwise rotation when looking down at the probe.

### ProbeInterface Library
`ProbeInterface` is a library that defines a standard for specifying electrode layouts on probes.
The `ProbeInterface` library includes layouts for many common probes.
`ProbeInterface` is a library that defines a standard for specifying electrode layouts on probes.
The `ProbeInterface` library includes layouts for many common probes.

The `ProbeInterface` model corresponding to your probe can be referenced using:
- `probeinterface_manufacturer`
- `probeinterface_model`
The `ProbeInterface` model corresponding to your probe can be referenced using:
- `probeinterface_manufacturer`
- `probeinterface_model`

If provided, these should point to a `ProbeInterface` model in the `ProbeInterface` library,
at the location:
If provided, these should point to a `ProbeInterface` model in the `ProbeInterface` library,
at the location:


{{ MACROS___make_columns_table("microephys.microephysProbes") }}
Expand All @@ -201,14 +201,14 @@ p021 left -9.94 -1.19 -2.86 utah-array iridium-oxide V3

## Electrodes (*_electrodes.tsv)

Electrodes describe the points of contact between the electrodes and the tissue used for recording electrophysiological signals.
Electrodes describe the points of contact between the electrodes and the tissue used for recording electrophysiological signals.

The electrode positions and properties are stored in a `.tsv` file (amplifier information is in `channels.tsv`).
The electrode positions and properties are stored in a `.tsv` file (amplifier information is in `channels.tsv`).

This file contains the following information:
- The electrode name
- The electrode coordinates in 3 columns (`xyz`)
- The ID of the probe the electrode is located on
This file contains the following information:
- The electrode name
- The electrode coordinates in 3 columns (`xyz`)
- The ID of the probe the electrode is located on

The coordinates are relative to the position on the probe.

Expand All @@ -229,17 +229,17 @@ e234 p021 7.0 -9.94 -1.19 -2.86 iridium-oxide V3

### Channels (*_channels.tsv)

Channels are virtual sources of recorded signals.
These may be of neuronal origin (for example, online filtered LFP signals) or generated by the recording setup (for example, synchronization or behavioral signals).
Channels are virtual sources of recorded signals.
These may be of neuronal origin (for example, online filtered LFP signals) or generated by the recording setup (for example, synchronization or behavioral signals).

The channel properties are stored in a `.tsv` file.
This file contains the following information:
- `channel_id`
- `electrode_id` (in the case of neuronal signals)
- Amplifier information
-
The channel properties are stored in a `.tsv` file.
This file contains the following information:
- `channel_id`
- `electrode_id` (in the case of neuronal signals)
- Amplifier information
-

For more information about the distinction between electrodes and channels, see [the corresponding section in iEEG](./intracranial-electroencephalography.md#terminology-electrodes-vs-channels).
For more information about the distinction between electrodes and channels, see [the corresponding section in iEEG](./intracranial-electroencephalography.md#terminology-electrodes-vs-channels).

Columns in the `*_channel.tsv` file are:

Expand Down Expand Up @@ -471,27 +471,27 @@ please follow the iEEG stimulation documentation.

Two different procedures are supported to handle multi-part recordings. In short, the two options are:
i) each recording is stored in an independent data file, and the corresponding metadata is described
in the `*_scans.tsv` file; or
ii) several recordings are stored in a single data file, and the corresponding metadata is described
in the `*_events.tsv` file.
These two options are made available to support different usages and habits of the experimenters, as
well as to benefit from the capability of the supported data formats (NWB and NIX).
in the `*_scans.tsv` file; or
ii) several recordings are stored in a single data file, and the corresponding metadata is described
in the `*_events.tsv` file.
These two options are made available to support different usages and habits of the experimenters, as
well as to benefit from the capability of the supported data formats (NWB and NIX).
They are described in the following subsections, and made explicit through some of the example data sets.


### Multiple tasks / runs in separate files (*_scans.tsv)

The `*_scans.tsv` should be used to provide information about multiple parts of an acquisition
session (for example, recording start times in case the recording was paused and restarted)
when the data from each of these different recordings is stored in separate files.
Each data file should have a name that contains a `_task-XX` and/or `_run-XX` suffix, and
session (for example, recording start times in case the recording was paused and restarted)
when the data from each of these different recordings is stored in separate files.
Each data file should have a name that contains a `_task-XX` and/or `_run-XX` suffix, and
should be described by at most one row in the `*_scans.tsv` file. See also the BIDS Scans
specification.
Relative paths to files should be used under a compulsory “filename” header.
Relative paths to files should be used under a compulsory “filename” header.
If acquisition time is included, it should be with the “acq_time” header. Datetime should
be expressed in the following format 2009-06-15T13:45:30 (year, month, day, hour (24h),
be expressed in the following format 2009-06-15T13:45:30 (year, month, day, hour (24h),
minute, second; this is equivalent to the RFC3339 “date-time” format, time zone is always
assumed as local time).
assumed as local time).
The run and task keywords and the corresponding `*_scans.tsv` file are OPTIONAL and can be
ignored if the dataset consists of only one continuous recording and a single or no task.

Expand All @@ -511,13 +511,13 @@ ephys/sub-P001_task-push_run-02_ephys.nix 2018-07-15T15:24:00
```


It is recommended to accompany the `*_scans.tsv` file with a corresponding `*_scans.json`
It is recommended to accompany the `*_scans.tsv` file with a corresponding `*_scans.json`
sidecar file, as described in the [BIDS specifications](https://bids-specification.readthedocs.io/en/stable/03-modality-agnostic-files.html#scans-file).


### Multiple recordings in a single data file (*_events.tsv)

The `*_events.tsv` should be used to provide information about multiple parts of an acquisition
The `*_events.tsv` should be used to provide information about multiple parts of an acquisition
session when the data from each of these different recordings is stored in a single data file.
In such a case, this file is REQUIRED.
This allows benefiting from the capability of the supported data formats (NIX and NWB) to store multiple
Expand All @@ -539,17 +539,17 @@ Optional column names in `events.tsv` to support multiple recordings in a single

#### Extracellular Electrophysiology

This dataset contains data from a single subject (subject A), that was recorded on two
days (2022-01-01 and 2022-01-02).
On the first day it performed two tasks (nose-poke & rest), and on the second day only a
This dataset contains data from a single subject (subject A), that was recorded on two
days (2022-01-01 and 2022-01-02).
On the first day it performed two tasks (nose-poke & rest), and on the second day only a
rest task was performed.
Detailed information about these tasks can be found in the `tasks.tsv` and `tasks.json` files.
The electrophysiology data for each of the three recordings are stored in the corresponding
The electrophysiology data for each of the three recordings are stored in the corresponding
session and ephys directories in the `nix` format. Metadata about the probes, their electrodes
and the corresponding recording channels are stored in `tsv` format. Note that in this case,
this information is shared between data files (see BIDS Inheritance Principle): in the first session,
the probe, electrode and channel files apply to both data files of that session, as they do not
contain a `task` entity in their name. For the nose-poke task, additional behavioral timestamps
the probe, electrode and channel files apply to both data files of that session, as they do not
contain a `task` entity in their name. For the nose-poke task, additional behavioral timestamps
(events) were recorded and stored in an additional `events.tsv` file.

<!-- TODO: Use macro for filetree -->
Expand Down

0 comments on commit 190eb67

Please sign in to comment.