diff --git a/src/schema/objects/columns.yaml b/src/schema/objects/columns.yaml index 5010d2453f..c97719519e 100644 --- a/src/schema/objects/columns.yaml +++ b/src/schema/objects/columns.yaml @@ -47,8 +47,7 @@ alpha_rotation: display_name: Alpha rotation description: | Euler angle to match probe extension dimensions (width, height, depth) to global x, y, z coordinates. - unit: - degree + unit: degree associated_brain_region: name: associated_brain_region display_name: Associated brain region @@ -67,16 +66,15 @@ associated_brain_region_quality_type: name: associated_brain_region_quality_type display_name: Associated brain region quality type description: | - The method used to identify the associated brain region (estimated|proof) - depending on anatomical pictures proofing the location or indirect estimation of the location. + The method used to identify the associated brain region (estimated|proof) + depending on anatomical pictures proofing the location or indirect estimation of the location. type: string beta_rotation: name: beta_rotation display_name: Beta rotation description: | Euler angle to match probe extension dimensions (width, height, depth) to global x, y, z coordinates. - unit: - degree + unit: degree cardiac: name: cardiac display_name: Cardiac measurement @@ -95,6 +93,24 @@ channel: In the absence of a delimiter, tools MUST interpret any character as being part of a channel name. type: string +channel_id: + name: channel_id + display_name: Channel ID + description: | + Unique identifier of the channel, only containing letters and numbers. + This id must be reflected in the data files, for example, as signal annotations in the nix file. + When inserting existing nwb files into a BIDS structure, one can combine + the nwb record_id and channel_index to create this unique identifier. + type: string + pattern: ^[0-9a-zA-Z]+$ +channel_label: + name: channel_label + display_name: Channel label + description: | + Human readable identifier. Use this name to specify the + content of signals not generated by electrodes. For example, + 'DAQ internal synchronization signals', 'behavioral signals', 'behavioral cues', etc. + type: string color: name: color display_name: Color label @@ -125,13 +141,30 @@ contact_count: description: | Number of miscellaneous analog contacts for auxiliary signals. type: number +coordinate_reference_point: + name: coordinate_reference_point + display_name: Coordinate reference point + description: | + Point of the probe that is described by the probe coordinates and + on which the alpha, beta and gamma rotations are applied. + type: string +data_entity_id: + name: data_entity_id + display_name: Data entity ID + description: | + The corresponding (UUID) identifier of the recording trace in the data file. + The same `data_entity_id` can be listed multiple times with different + `onset` and `duration` values to select a subset of a recording trace. + type: string depth__probes: - name: height - display_name: Height + name: depth + display_name: Depth description: | - Physical height of the probe. + Physical depth of the probe, for example, '0.3'. + This dimension should be omitted or set to 0 for two-dimensional (shank-type) probes. + This dimension corresponds to the z’axis of the Euler transformation defined by + alpha, beta and gamma rotations values. type: number - unit: mm detector__channels: name: detector display_name: Detector Name @@ -204,6 +237,14 @@ dimension: Size of the group (grid/strip/probe) that this electrode belongs to. Must be of form `[AxB]` with the smallest dimension first (for example, `[1x8]`). type: string +# TODO: Add unit enums if everyone agrees to keep this column. +dimension_unit: + name: dimension_unit + display_name: Dimension unit + description: | + Units of the physical dimensions 'width', 'height' and 'depth' of the probe. + For example, `mm`. + type: string duration: name: duration display_name: Event duration @@ -219,6 +260,31 @@ duration: - type: string enum: - n/a +duration_index: + name: duration_index + display_name: Duration index + description: | + Number of recording samples included in the event. + type: number +electrode_count: + name: electrode_count + display_name: Electrode count + description: | + Number of miscellaneous analog electrodes for auxiliary signals (for example, '2'). + type: number +electrode_id: + name: electrode_id + display_name: Electrode ID + description: | + A unique identifier of the electrode. + (expected to match electrode_ids listed in `*_channels.tsv`). + type: string +electrode_shape: + name: electrode_shape + display_name: Electrode shape + description: | + Description of the shape of the electrode (for example, `square`, `circle`). + type: string filename: name: filename display_name: Filename @@ -226,13 +292,29 @@ filename: Relative paths to files. type: string format: participant_relative +# TODO: Figure out and add rule for default values. +gain: + name: gain + display_name: Gain + description: | + Amplification factor applied from signal detection at the electrode + to the signal stored in the data file. + If no gain factor is provided it is assumed to be 1. + type: number gamma_rotation: name: gamma_rotation display_name: Gamma rotation description: | Euler angle to match probe extension dimensions (width, height, depth) to global x, y, z coordinates. - unit: - degree + unit: degree +# TODO: Clarify if the optionality of the column be defined here or as an addendum in the rules. +ground: + name: ground + display_name: Ground + description: | + Information on the ground. For example, 'chamber screw', 'head post', 'ear clip'. + Only should be used to optionally override the global ground in the `_ecephys.json` or `_icephys.json` file. + type: string group__channel: name: group display_name: Channel group @@ -274,13 +356,26 @@ handedness: - AMBIDEXTROUS - Ambidextrous - n/a +hardware_filters: + name: hardware_filters + display_name: Hardware filters + description: | + List of hardware (amplifier) filter keys applied. + Note that parameters should be defined in the general microephys sidecar .json file. + Indicate `n/a` in the absence of hardware filters applied. + anyOf: + - type: string + - type: string + enum: + - n/a height__probes: name: height display_name: Height description: | - Physical height of the probe. + Physical height of the probe, for example, '5'. + This dimension corresponds to the y’axis of the Euler transformation defined by + alpha, beta and gamma rotations values below. type: number - unit: mm hemisphere: name: hemisphere display_name: Electrode hemisphere @@ -290,6 +385,16 @@ hemisphere: enum: - $ref: objects.enums.left_hemisphere.value - $ref: objects.enums.right_hemisphere.value +# TODO: Should the hemisphere details be unified for electrodes and probes or will it break other modality? +hemisphere__probes: + name: hemisphere + display_name: Hemisphere + description: | + Hemisphere in which the probe is placed. + type: string + enum: + - $ref: objects.enums.left_hemisphere.value + - $ref: objects.enums.right_hemisphere.value high_cutoff: name: high_cutoff display_name: High cutoff @@ -325,6 +430,12 @@ index: description: | The label integer index. type: integer +location: + name: location + display_name: Location + description: | + An indication on the location of the electrode (for example, `cortical layer 3`, `CA1`). + type: string low_cutoff: name: low_cutoff display_name: Low cutoff @@ -344,6 +455,13 @@ manufacturer: The manufacturer for each electrode. Can be used if electrodes were manufactured by more than one company. type: string +# TODO: Should the manufacturer details be unified for electrodes and probes? +manufacturer__probes: + name: manufacturer + display_name: Manufacturer + description: | + Manufacturer of the probes system (for example, 'openephys', 'alphaomega','blackrock'). + type: string mapping: name: mapping display_name: Label mapping @@ -434,6 +552,12 @@ onset: acquired data point. type: number unit: s +onset_index: + name: onset_index + display_name: Onset index + description: | + Index of the onset recording sample (0 based) within the data entity. + type: integer pathology: name: pathology display_name: Pathology @@ -451,6 +575,28 @@ participant_id: matching a participant entity found in the dataset. type: string pattern: ^sub-[0-9a-zA-Z]+$ +pipette_solution: + name: pipette_solution + display_name: Pipette solution + description: | + The solution used to fill the pipette. + See also [openMINDS Pipette] + (https://github.com/openMetadataInitiative/openMINDS_ephys/blob/v1/schemas/device/pipetteUsage.schema.tpl.json). + type: string +internal_pipette_diameter: + name: internal_pipette_diameter + display_name: Internal pipette diameter + description: | + The internal diameter of the pipette in micrometers. + type: number + unit: mm +external_pipette_diameter: + name: external_pipette_diameter + display_name: External pipette diameter + description: | + The external diameter of the pipette in micrometers. + type: number + unit: mm placement__motion: name: placement display_name: Placement @@ -466,6 +612,19 @@ plasma_radioactivity: Radioactivity in plasma, in unit of plasma radioactivity (for example, `kBq/mL`). type: number # reference column for channels.tsv files for EEG data +probe_id: + name: probe_id + display_name: Probe ID + description: | + A unique identifier of the probe, can be identical with the `device_serial_number`. + (expected to match probe_ids listed in `*_eletrodes.tsv`). + type: string +recording_mode: + name: recording_mode + display_name: Recording mode + description: | + The mode of recording for patch clamp datasets (for example, `voltage clamp`, `current clamp`). + type: string reference__eeg: name: reference display_name: Electrode reference @@ -474,6 +633,13 @@ reference__eeg: This column is not needed when it is common to all channels. In that case the reference electrode(s) can be specified in `*_eeg.json` as `EEGReference`). type: string +reference__microephys: + name: reference + display_name: Reference + description: | + Name of the electrode used as physical reference. + For example, electrode_id, physical location (subdural, chamber screw). + type: string # reference column for channels.tsv files for iEEG data reference__ieeg: name: reference @@ -490,7 +656,8 @@ reference_atlas: name: reference_atlas display_name: Reference atlas description: | - Name of reference atlas used for associated brain region identification, preferably an ebrains supported atlas. + Name of reference atlas used for associated brain region identification, + preferably an [ebrains supported atlas](https://ebrains.eu/services/atlases#services). type: string reference_frame: name: reference_frame @@ -593,6 +760,13 @@ sex: - OTHER - Other - n/a +shank_id: + name: shank_id + display_name: Shank ID + description: | + A unique identifier to specify which shank of the probe the electrode is on. + This is useful for spike sorting when the electrodes are on a multi-shank probe. + type: string short_channel: name: short_channel display_name: Short Channel @@ -621,6 +795,20 @@ software_filters: - type: string enum: - n/a +# TODO: This seems very confusing. Should be merge with the column above? +software_filters__channels: + name: software_filters + display_name: Software filters + description: | + List of temporal and/or spatial software filters applied + (for example, `SSS`, `SpatialCompensation`). + Note that parameters should be defined in the general microephys sidecar .json file. + Indicate `n/a` in the absence of software filters applied. + anyOf: + - type: string + - type: string + enum: + - n/a source__channels: name: source display_name: Source name @@ -699,6 +887,22 @@ strain_rrid: of the strain of the species, for example: `RRID:IMSR_JAX:000664`. type: string format: rrid +stream_id: + name: stream_id + display_name: Stream ID + description: | + Data stream of the recording the signal. + type: string +# TODO: Clarify if column values can be arrays. +surgery_date: + name: surgery_date + display_name: Surgery date + description: | + Date(s) of surgery. Datetime format and their anonymization + are described in [Units](SPEC_ROOT/common-principles.md#units). + The details of the surgery should be described in the sidecar json file. + type: string + format: datetime time: name: time display_name: Time @@ -707,6 +911,19 @@ time: For example, 5. type: number unit: s +time_offset: + name: time_offset + display_name: Time offset + description: | + Time shift between signal of this channel to a reference channel in seconds. + type: number + unit: s +time_reference_channel: + name: time_reference_channel + display_name: Time reference channel + description: | + Name of the channel that is used for time alignment of signals. + type: string tracked_point__channels: name: tracked_point display_name: Tracked point channel @@ -714,6 +931,16 @@ tracked_point__channels: Label of the point that is being tracked, for example, label of a tracker or a marker (for example,`"LeftFoot"`, `"RightWrist"`). type: string +# TODO: Add relative links to `trial_type` column and events.tsv description. +trial_id: + name: trial_id + display_name: Trial ID + description: | + If the data entity belongs to set of data_entities forming a trial, + they have to be linked to the same trial_id. This can be used to e.g. group stimulation and response records. + The optional `trial_type` events.tsv column can be used to provide the further information on the trial like + `electric stimulation`,`rest`, or `pharmaceutical stimulation`, etc. + type: string trial_type: name: trial_type display_name: Trial type @@ -730,6 +957,7 @@ trigger: description: | continuous measurement of the scanner trigger signal type: number +# TODO: Populate enums that make sense for channels in the microephys datasets. # type column in channels.tsv files type__channels: name: type @@ -819,6 +1047,15 @@ units: (see [Units](SPEC_ROOT/common-principles.md#units)). type: string format: unit +units__channels: + name: units + display_name: Units + description: | + Physical unit of the value represented in this channel, + for example, `V` for Volt, or `uV` for micro Volt + (see [Units](SPEC_ROOT/common-principles.md#units)). + type: string + format: unit units__nirs: name: units display_name: Units @@ -896,9 +1133,10 @@ width__probes: name: width display_name: Width description: | - Physical width of the probe. + Physical width of the probe, for example, '5'. + This dimension corresponds to the x’axis of the Euler transformation defined by + alpha, beta and gamma rotations values. type: number - unit: mm x: name: x display_name: X position @@ -954,6 +1192,46 @@ z__optodes: - type: string enum: - n/a +# TODO: How are the units specified for the probe x, y and z fields? +x__probes: + name: x + display_name: Probe X position + description: | + Probe position along the global coordinate system x-axis. + type: number +y__probes: + name: y + display_name: Probe Y position + description: | + Probe position along the global coordinate system y-axis. + type: number +z__probes: + name: z + display_name: Probe Z position + description: | + Probe position along the global coordinate system z-axis. + type: number +x__electrodes: + name: x + display_name: Electrode X position + description: | + Recorded position along the local width-axis relative + to the probe origin and rotation (see `_probes.tsv`) + type: number +y__electrodes: + name: y + display_name: Electrode Y position + description: | + Recorded position along the local height-axis relative + to the probe origin and rotation (see `_probes.tsv`) + type: number +z__electrodes: + name: z + display_name: Electrode Z position + description: | + Recorded position along the local depth-axis relative + to the probe origin and rotation (see `_probes.tsv`) + type: number template_x: name: template_x display_name: X template position diff --git a/src/schema/objects/metadata.yaml b/src/schema/objects/metadata.yaml index 57515dd6f0..38c944c79d 100644 --- a/src/schema/objects/metadata.yaml +++ b/src/schema/objects/metadata.yaml @@ -1853,6 +1853,54 @@ MEGREFChannelCount: `MEGREFChannelCount` should be set to `0`. type: integer minimum: 0 +# TODO: Change if needs to be broken down into ecephys and icephys +# TODO: Add links to the 2D coordinate system, Pixels and glossary entry. +# TODO: Add enums for the valid values specific to microephys +MicroephysCoordinateSystem: + name: MicroephysCoordinateSystem + display_name: Microephys Coordinate System + description: | + Defines the coordinate system for the microelectrode probes. + See the + [Coordinate Systems Appendix](SPEC_ROOT/appendices/coordinate-systems.md) + for a list of restricted keywords for coordinate systems. + If `"Other"`, provide definition of the coordinate system in + `"MicroephysCoordinateSystemDescription"`. If positions correspond to + pixel indices in a 2D image (of either a volume-rendering, + surface-rendering, operative photo, or operative drawing), + this MUST be "Pixels". For more information, see the section + on 2D coordinate systems. + For a list of valid values for this field, see the associated glossary entry. + anyOf: + # - $ref: objects.enums._MicroephysCoordSys + - $ref: objects.enums._StandardTemplateCoordSys +MicroephysCoordinateSystemDescription: + name: MicroephysCoordinateSystemDescription + display_name: Microephys Coordinate System Description + description: | + Free-form text description of the coordinate system. + May also include a link to a documentation page or paper describing the + system in greater detail. + type: string +MicroephysCoordinateUnits: + name: MicroephysCoordinateUnits + display_name: Microephys Coordinate Units + description: | + Units of the coordinates of `"MicroephysCoordinateSystem"`. + type: string +# TODO: Clarify if units need to be used or enums, if units, define pixels + enum: + - m + - mm + - cm + - pixels +MicroephysCoordinateSystemPhoto: + name: MicroephysCoordinateSystemPhoto + display_name: Microephys Coordinate System Photo + description: | + A link to a photo or drawing of the microelectrode probe system. + type: string + format: uri MISCChannelCount: name: MISCChannelCount display_name: Miscellaneous channel count @@ -1970,6 +2018,12 @@ ManufacturersModelName: description: | Manufacturer's model name of the equipment that produced the measurements. type: string +ManufacturersModelVersion: + name: ManufacturersModelVersion + display_name: Manufacturers Model Version + description: | + Manufacturer's model version of the equipment that produced the measurements. + type: string MatrixCoilMode: name: MatrixCoilMode display_name: Matrix Coil Mode @@ -2657,6 +2711,12 @@ RecordingDuration: Length of the recording in seconds (for example, `3600`). type: number unit: s +RecordingSetupName: + name: RecordingSetupName + display_name: Recording Setup Name + description: | + Custom name of the recording setup. + type: string RecordingType: name: RecordingType display_name: Recording Type @@ -3392,6 +3452,13 @@ SubjectArtefactDescription: If this field is set to `"n/a"`, it will be interpreted as absence of major source of artifacts except cardiac and blinks. type: string +SupplementarySignals: + name: SupplementarySignals + display_name: Supplementary Signals + description: | + Description of the supplementary signal (additional modalities) recorded + in parallel and are also stored in the data file. + type: string TaskDescription: name: TaskDescription display_name: Task Description diff --git a/src/schema/rules/modalities.yaml b/src/schema/rules/modalities.yaml index 2f290ca014..e4bdf56974 100644 --- a/src/schema/rules/modalities.yaml +++ b/src/schema/rules/modalities.yaml @@ -31,3 +31,7 @@ motion: nirs: datatypes: - nirs +microephys: + datatypes: + - ecephys + - icephys diff --git a/src/schema/rules/sidecars/microephys.yaml b/src/schema/rules/sidecars/microephys.yaml new file mode 100644 index 0000000000..9ba92c2665 --- /dev/null +++ b/src/schema/rules/sidecars/microephys.yaml @@ -0,0 +1,117 @@ +# +# Groups of related metadata fields +# +# Assumptions: never need disjunction of selectors +# Assumptions: top-to-bottom overrides is sufficient logic + +--- +# Groups are defined as they appear in the proposal + +microephysInstitutionInformation: + selectors: + - datatype == ["ecephys", "icephys"] + - suffix == ["ecephys", "icephys"] + fields: + InstitutionName: recommended + InstitutionAddress: recommended + InstitutionalDepartmentName: recommended + +microephysSetup: + selectors: + - datatype == ["ecephys", "icephys"] + - suffix == ["ecephys", "icephys"] + fields: + PowerLineFrequency: required + Manufacturer: + level: recommended + description_addendum: For example, `"TDT"`, `"Blackrock"`. + ManufacturersModelName: recommended + ManufacturersModelVersion: recommended + RecordingSetupName: recommended + SamplingFrequency: + level: required + description_addendum: | + Internal (maximum) sampling frequency (in Hz) + of the recording (for example, "24000"). + DeviceSerialNumber: + level: recommended + description_addendum: | + The serial number of the components of the setup, + recommended to add serial numbers and versions of + ALL components constituting the setup. + SoftwareName: + level: recommended + description_addendum: | + The name of the software suite used to + record the data. + SoftwareVersions: recommended + +microephysProcessing: + selectors: + - datatype == ["ecephys", "icephys"] + - suffix == ["ecephys", "icephys"] + fields: + SoftwareFilters: required + HardwareFilters: recommended + +microephysPharmaceuticals: + selectors: + - datatype == ["ecephys", "icephys"] + - suffix == ["ecephys", "icephys"] + fields: + PharmaceuticalName: recommended + PharmaceuticalDoseAmount: recommended + PharmaceuticalDoseUnits: recommended + PharmaceuticalDoseRegimen: recommended + PharmaceuticalDoseTime: recommended + +# TODO: Check how to conditionally change level to required for photo if +# MicroephysCoordinateSystem is Pixels +microephysCoordsystemGeneral: + selectors: + - datatype == ["ecephys", "icephys"] + - suffix == "coordsystem" + fields: + MicroephysCoordinateSystem: required + MicroephysCoordinateSystemDescription: recommended + MicroephysCoordinateUnits: required + MicroephysCoordinateSystemPhoto: optional + +microephysSupplementary: + selectors: + - datatype == ["ecephys", "icephys"] + - suffix == ["ecephys", "icephys"] + fields: + SupplementarySignals: optional + +microephysSample: + selectors: + - datatype == ["ecephys", "icephys"] + - suffix == ["ecephys", "icephys"] + fields: + BodyPart: recommended + BodyPartDetails: recommended + BodyPartDetailsOntology: optional + SampleEnvironment: recommended + SampleEmbedding: optional + SliceThickness: optional + SampleExtractionProtocol: optional + +microephysTaskInformation: + selectors: + - datatype == ["ecephys", "icephys"] + - suffix == ["ecephys", "icephys"] + fields: + TaskName: + level: recommended + description_addendum: | + A recommended convention is to name resting state task using labels + beginning with `rest`. + TaskDescription: recommended + Instructions: + level: recommended + description_addendum: | + This is especially important in context of resting state recordings and + distinguishing between eyes open and eyes closed paradigms. + CogAtlasID: recommended + CogPOID: recommended diff --git a/src/schema/rules/tabular_data/microephys.yaml b/src/schema/rules/tabular_data/microephys.yaml new file mode 100644 index 0000000000..a16655257e --- /dev/null +++ b/src/schema/rules/tabular_data/microephys.yaml @@ -0,0 +1,100 @@ +--- +microephysProbes: + selectors: + - datatype == ["ecephys", "icephys"] + - suffix == "probes" + - extension == ".tsv" + initial_columns: + - probe_id + - type__probes + - x__probes + - y__probes + - z__probes + columns: + probe_id: required + type__probes: required + x__probes: recommended + y__probes: recommended + z__probes: recommended + manufacturer__probes: recommended + device_serial_number: recommended + electrode_count: optional + width__probes: optional + height__probes: optional + depth__probes: optional + dimension_unit: optional + alpha_rotation: recommended + beta_rotation: recommended + gamma_rotation: recommended + coordinate_reference_point: recommended + hemisphere__probes: recommended + associated_brain_region: recommended + associated_brain_region_id: recommended + associated_brain_region_quality_type: recommended + reference_atlas: recommended + material__probes: optional + index_columns: [probe_id] + additional_columns: allowed_if_defined + +microephysElectrodes: + selectors: + - datatype == ["ecephys", "icephys"] + - suffix == "electrodes" + - extension == ".tsv" + initial_columns: + - electrode_id + - probe_id + - hemisphere + - x__electrodes + - y__electrodes + - z__electrodes + columns: + electrode_id: required + probe_id: required + hemisphere: recommended + x__electrodes: recommended + y__electrodes: recommended + z__electrodes: recommended + impedance: recommended + shank_id: optional + size: optional + electrode_shape: optional + material: optional + location: recommended + pipette_solution: optional + internal_pipette_diameter: optional + external_pipette_diameter: optional + index_columns: [electrode_id] + additional_columns: allowed_if_defined + +microephysCCChannelsss: + selectors: + - datatype == ["ecephys", "icephys"] + - suffix == "channels" + - extension == ".tsv" + initial_columns: + - channel_id + - reference__microephys + - type__channels + - units__channels + - sampling_frequency + columns: + channel_id: required + reference__microephys: required + type__channels: required + units__channels: required + sampling_frequency: optional + channel_label: optional + stream_id: optional + description: optional + hardware_filters: recommended + software_filters: recommended + status: optional + status_description: optional + gain: recommended + time_offset: optional + time_reference_channel: optional + ground: optional + recording_mode: recommended + index_columns: [channel_id] + additional_columns: allowed_if_defined diff --git a/src/schema/rules/tabular_data/task.yaml b/src/schema/rules/tabular_data/task.yaml index 0ca01afe25..405a6d674b 100644 --- a/src/schema/rules/tabular_data/task.yaml +++ b/src/schema/rules/tabular_data/task.yaml @@ -15,6 +15,27 @@ TaskEvents: description_addendum: | Note that this column only applies to data types where channels are specified, such as EEG, iEEG, MEG or NIRS. +# TODO: Make the addendums more clear and descriptive + data_entity_id: + level: optional + description_addendum: | + Note that this column only applies to + microelectrode eleectrophysiology data type. + duration_index: + level: optional + description_addendum: | + Note that this column only applies to + microelectrode eleectrophysiology data type. + onset_index: + level: optional + description_addendum: | + Note that this column only applies to + microelectrode eleectrophysiology data type. + trial_id: + level: optional + description_addendum: | + Note that this column only applies to + microelectrode eleectrophysiology data type. additional_columns: allowed initial_columns: - onset