Standardize core schema documentation style

core/nwb.base.yaml

@@ -13,15 +13,15 @@ datasets:
       TimeSeries. The first dimension of those arrays is always time.
   - name: count
     dtype: int32
-    doc: Number of data samples available in this time series, during this epoch
+    doc: Number of data samples available in this time series, during this epoch.
   - name: timeseries
     dtype:
       target_type: TimeSeries
       reftype: object
-    doc: The TimeSeries that this index applies to
-  doc: Column storing references to a TimeSeries (rows). For each TimeSeries this
-    VectorData column stores the start_index and count to indicate the range in time
-    to be selected as well as an object reference to the TimeSeries.
+    doc: The TimeSeries object that this reference refers to.
+  doc: Column storing references into one or more TimeSeries objects. Each row of
+    this column stores a start index and count into a referenced TimeSeries and an
+    object reference to that TimeSeries.
 
 - neurodata_type_def: BaseImage
   neurodata_type_inc: NWBData
@@ -54,7 +54,7 @@ datasets:
     - null
     - 4
   doc: A type for storing image data directly. Shape can be 2-D (x, y), or 3-D where the
-    third dimension can have three or four elements, e.g. (x, y, (r, g, b)) or
+    third dimension can have three or four elements, e.g., (x, y, (r, g, b)) or
     (x, y, (r, g, b, a)).
   attributes:
   - name: resolution
@@ -152,7 +152,7 @@ groups:
       doc: Scalar to multiply each element in data to convert it to the specified 'unit'.
         If the data are stored in acquisition system units or other units
         that require a conversion to be interpretable, multiply the data by 'conversion'
-        to convert the data to the specified 'unit'. e.g. if the data acquisition system
+        to convert the data to the specified 'unit'. For example, if the data acquisition system
         stores values in this object as signed 16-bit integers (int16 range
         -32,768 to 32,767) that correspond to a 5V range (-2.5V to 2.5V), and the data
         acquisition system gain is 8000X, then the 'conversion' multiplier to get from
@@ -171,7 +171,7 @@ groups:
       dtype: float32
       default_value: -1.0
       doc: Smallest meaningful difference between values in data, stored in the specified
-        by unit, e.g., the change in value of the least significant bit, or a larger
+        unit, e.g., the change in value of the least significant bit, or a larger
         number if signal noise is known to be present. If unknown, use -1.0.
       required: false
     - name: unit
@@ -212,7 +212,7 @@ groups:
     shape:
     - null
     doc: Timestamps for samples stored in data, in seconds, relative to the
-      common experiment master-clock stored in NWBFile.timestamps_reference_time.
+      common experiment master clock stored in NWBFile.timestamps_reference_time.
     quantity: '?'
     attributes:
     - name: interval
@@ -231,7 +231,7 @@ groups:
     - null
     doc: Numerical labels that apply to each time point in data for the purpose of
       querying and slicing data by these values. If present, the length of this
-      array should be the same size as the first dimension of data.
+      array should be the same as the length of the first dimension of data.
     quantity: '?'
   - name: control_description
     dtype: text

core/nwb.behavior.yaml

@@ -2,7 +2,7 @@ groups:
 - neurodata_type_def: SpatialSeries
   neurodata_type_inc: TimeSeries
   doc: "Direction, e.g., of gaze or travel, or position. The TimeSeries::data field\
-    \ is a 2D array storing position or direction relative to some reference frame.\
+    \ is a 2-D array storing position or direction relative to some reference frame.\
     \ Array structure: [num measurements] [num dimensions]. Each SpatialSeries has\
     \ a text dataset reference_frame that indicates the zero-position, or the zero-axes\
     \ for direction. For example, if representing gaze direction, 'straight-ahead'\
@@ -46,13 +46,13 @@ groups:
 - neurodata_type_def: BehavioralEpochs
   neurodata_type_inc: NWBDataInterface
   default_name: BehavioralEpochs
-  doc: TimeSeries for storing behavioral epochs.  The objective of this and the other
-    two Behavioral interfaces (e.g. BehavioralEvents and BehavioralTimeSeries) is
+  doc: TimeSeries for storing behavioral epochs. The objective of this and the other
+    two Behavioral interfaces (e.g., BehavioralEvents and BehavioralTimeSeries) is
     to provide generic hooks for software tools/scripts. This allows a tool/script
-    to take the output one specific interface (e.g., UnitTimes) and plot that data
+    to take the output of one specific interface (e.g., UnitTimes) and plot that data
     relative to another data modality (e.g., behavioral events) without having to
     define all possible modalities in advance. Declaring one of these interfaces means
-    that one or more TimeSeries of the specified type is published. These TimeSeries
+    that one or more TimeSeries of the specified type are published. These TimeSeries
     should reside in a group having the same name as the interface. For example, if
     a BehavioralTimeSeries interface is declared, the module will have one or more
     TimeSeries defined in the module sub-group 'BehavioralTimeSeries'. BehavioralEpochs
@@ -116,7 +116,7 @@ groups:
   doc: With a CompassDirection interface, a module publishes a SpatialSeries object
     representing a floating point value for theta. The SpatialSeries::reference_frame
     field should indicate what direction corresponds to 0 and which is the direction
-    of rotation (this should be clockwise). The si_unit for the SpatialSeries should
+    of rotation (this should be clockwise). The unit for the SpatialSeries should
     be radians or degrees.
   groups:
   - neurodata_type_inc: SpatialSeries
@@ -126,7 +126,7 @@ groups:
 - neurodata_type_def: Position
   neurodata_type_inc: NWBDataInterface
   default_name: Position
-  doc: Position data, whether along the x, x/y or x/y/z axis.
+  doc: Position data, whether along the x, x/y, or x/y/z axes.
   groups:
   - neurodata_type_inc: SpatialSeries
     doc: SpatialSeries object containing position data.

core/nwb.ecephys.yaml

@@ -52,11 +52,11 @@ groups:
     doc: Channel-specific conversion factor. Multiply the data in the 'data' dataset by these
       values along the channel axis (as indicated by axis attribute) AND by the global
       conversion factor in the 'conversion' attribute of 'data' to get the data values in
-      Volts, i.e, data in Volts = data * data.conversion * channel_conversion. This
+      Volts, i.e., data in Volts = data * data.conversion * channel_conversion. This
       approach allows for both global and per-channel data conversion factors needed
       to support the storage of electrical recordings as native values generated by data
       acquisition systems. If this dataset is not present, then there is no channel-specific
-      conversion factor, i.e. it is 1 for all channels.
+      conversion factor, i.e., it is 1 for all channels.
     quantity: '?'
     attributes:
     - name: axis
@@ -127,7 +127,7 @@ groups:
     - num_features
     shape:
     - null
-    doc: Description of features (eg, ''PC1'') for each of the extracted features.
+    doc: Description of features (e.g., ''PC1'') for each of the extracted features.
   - name: features
     dtype: float32
     dims:
@@ -170,8 +170,8 @@ groups:
     - - null
       - 2
     doc: Indices (zero-based) into the linked source ElectricalSeries::data array corresponding
-      to time of event or time and channel of event. ''description'' should define what is meant
-      by time of event (e.g., .25 ms before action potential peak, zero-crossing time, etc).
+      to the time of each event, or the time and channel of each event. ''description'' should define what is meant
+      by time of event (e.g., .25 ms before action potential peak, zero-crossing time, etc.).
       The index points to each event from the raw data.
   - name: times
     dtype: float64
@@ -191,7 +191,7 @@ groups:
     target_type: ElectricalSeries
     doc: Link to the ElectricalSeries that this data was calculated from. Metadata
       about electrodes and their position can be read from that ElectricalSeries so
-      it's not necessary to include that information here.
+      it is not necessary to include that information here.
 
 - neurodata_type_def: EventWaveform
   neurodata_type_inc: NWBDataInterface
@@ -212,8 +212,8 @@ groups:
     FilteredEphys modules publish an ElectricalSeries for each filtered channel or
     set of channels. The name of each ElectricalSeries is arbitrary but should be
     informative. The source of the filtered data, whether this is from analysis of
-    another time series or as acquired by hardware, should be noted in each's TimeSeries::description
-    field. There is no assumed 1::1 correspondence between filtered ephys signals
+    another time series or as acquired by hardware, should be noted in the TimeSeries::description field of each
+    ElectricalSeries. There is no assumed 1:1 correspondence between filtered ephys signals
     and electrodes, as a single signal can apply to many nearby electrodes, and one
     electrode may have different filtered (e.g., theta and/or gamma) signals represented.
     Filter properties should be noted in the ElectricalSeries 'filtering' attribute.
@@ -259,7 +259,7 @@ groups:
     - name: z
       dtype: float32
       doc: z coordinate
-    doc: stereotaxic or common framework coordinates
+    doc: Stereotaxic or common framework coordinates of the electrode group position.
     quantity: '?'
   links:
   - name: device
@@ -268,7 +268,7 @@ groups:
 
 - neurodata_type_def: ElectrodesTable
   neurodata_type_inc: DynamicTable
-  doc: A table of all electrodes (i.e. channels) used for recording. Introduced in NWB 2.8.0. Replaces the "electrodes"
+  doc: A table of all electrodes (i.e., channels) used for recording. Introduced in NWB 2.8.0. Replaces the "electrodes"
     table (neurodata_type_inc DynamicTable, no neurodata_type_def) that is part of NWBFile.
   datasets:
   - name: location
@@ -339,7 +339,7 @@ groups:
 - neurodata_type_def: ClusterWaveforms
   neurodata_type_inc: NWBDataInterface
   default_name: ClusterWaveforms
-  doc: DEPRECATED The mean waveform shape, including standard deviation, of the different
+  doc: DEPRECATED. The mean waveform shape, including standard deviation, of the different
     clusters. Ideally, the waveform analysis should be performed on data that is only
     high-pass filtered. This is a separate module because it is expected to require
     updating. For example, IMEC probes may require different storage requirements
@@ -358,9 +358,9 @@ groups:
     - null
     - null
     doc: The mean waveform for each cluster, using the same indices for each wave
-      as cluster numbers in the associated Clustering module (i.e, cluster 3 is in
+      as cluster numbers in the associated Clustering module (i.e., cluster 3 is in
       array slot [3]). Waveforms corresponding to gaps in cluster sequence should
-      be empty (e.g., zero- filled)
+      be empty (e.g., zero-filled).
   - name: waveform_sd
     dtype: float32
     dims:
@@ -369,22 +369,22 @@ groups:
     shape:
     - null
     - null
-    doc: Stdev of waveforms for each cluster, using the same indices as in mean
+    doc: Stdev of waveforms for each cluster, using the same indices as in mean.
   links:
   - name: clustering_interface
     target_type: Clustering
-    doc: Link to Clustering interface that was the source of the clustered data
+    doc: Link to Clustering interface that was the source of the clustered data.
 
 - neurodata_type_def: Clustering
   neurodata_type_inc: NWBDataInterface
   default_name: Clustering
-  doc: DEPRECATED Clustered spike data, whether from automatic clustering tools (e.g.,
+  doc: DEPRECATED. Clustered spike data, whether from automatic clustering tools (e.g.,
     klustakwik) or as a result of manual sorting.
   datasets:
   - name: description
     dtype: text
-    doc: Description of clusters or clustering, (e.g. cluster 0 is noise, clusters
-      curated using Klusters, etc)
+    doc: Description of clusters or clustering (e.g., cluster 0 is noise, clusters
+      curated using Klusters, etc.).
   - name: num
     dtype: int32
     dims:

core/nwb.event.yaml

@@ -6,8 +6,8 @@ datasets:
   - num_times
   shape:
   - null
-  doc: A 1-dimensional VectorData that stores timestamps in seconds from the
-    session start time. Timestamp are not required to be sorted in time.
+  doc: A 1-D VectorData that stores timestamps in seconds from the
+    session start time. Timestamps are not required to be sorted in time.
   attributes:
   - name: unit
     dtype: text
@@ -27,7 +27,7 @@ datasets:
   - num_times
   shape:
   - null
-  doc: A 1-dimensional VectorData that stores durations in seconds.
+  doc: A 1-D VectorData that stores durations in seconds.
   attributes:
   - name: unit
     dtype: text