diff --git a/core/nwb.base.yaml b/core/nwb.base.yaml index f926cab3..4562547c 100644 --- a/core/nwb.base.yaml +++ b/core/nwb.base.yaml @@ -128,8 +128,8 @@ groups: doc: Sampling rate, in Hz. - name: unit dtype: text - value: seconds - doc: Unit of measurement for time, which is fixed to 'seconds'. + value: s + doc: Unit of measurement for time, which is fixed to 's'. - name: timestamps dtype: float64 dims: @@ -146,8 +146,8 @@ groups: doc: Value is '1' - name: unit dtype: text - value: seconds - doc: Unit of measurement for timestamps, which is fixed to 'seconds'. + value: s + doc: Unit of measurement for timestamps, which is fixed to 's'. - name: control dtype: uint8 dims: diff --git a/core/nwb.behavior.yaml b/core/nwb.behavior.yaml index 300b48db..cb3fa725 100644 --- a/core/nwb.behavior.yaml +++ b/core/nwb.behavior.yaml @@ -25,9 +25,9 @@ groups: attributes: - name: unit dtype: text - default_value: meters + default_value: m doc: Base unit of measurement for working with the data. The default value - is 'meters'. Actual stored values are not necessarily stored in these units. + is 'm'. Actual stored values are not necessarily stored in these units. To access the data in these units, multiply 'data' by 'conversion'. required: false - name: reference_frame diff --git a/core/nwb.ecephys.yaml b/core/nwb.ecephys.yaml index 90c8655d..f33647ab 100644 --- a/core/nwb.ecephys.yaml +++ b/core/nwb.ecephys.yaml @@ -26,9 +26,9 @@ groups: attributes: - name: unit dtype: text - value: volts + value: V doc: Base unit of measurement for working with the data. This value is fixed to - 'volts'. Actual stored values are not necessarily stored in these units. To + 'V'. Actual stored values are not necessarily stored in these units. To access the data in these units, multiply 'data' by 'conversion' and 'channel_conversion' (if present). - name: electrodes @@ -84,8 +84,8 @@ groups: attributes: - name: unit dtype: text - value: volts - doc: Unit of measurement for waveforms, which is fixed to 'volts'. + value: V + doc: Unit of measurement for waveforms, which is fixed to 'V'. - name: timestamps dtype: float64 dims: @@ -103,8 +103,8 @@ groups: doc: Value is '1' - name: unit dtype: text - value: seconds - doc: Unit of measurement for timestamps, which is fixed to 'seconds'. + value: s + doc: Unit of measurement for timestamps, which is fixed to 's'. - neurodata_type_def: FeatureExtraction neurodata_type_inc: NWBDataInterface @@ -170,8 +170,8 @@ groups: attributes: - name: unit dtype: text - value: seconds - doc: Unit of measurement for event times, which is fixed to 'seconds'. + value: s + doc: Unit of measurement for event times, which is fixed to 's'. links: - name: source_electricalseries target_type: ElectricalSeries diff --git a/core/nwb.file.yaml b/core/nwb.file.yaml index 2376f36d..6cb6acc0 100644 --- a/core/nwb.file.yaml +++ b/core/nwb.file.yaml @@ -7,7 +7,7 @@ groups: attributes: - name: nwb_version dtype: text - value: 2.2.5 + value: 2.3.0-alpha doc: File version string. Use semantic versioning, e.g. 1.2.1. This will be the name of the format with trailing major, minor and patch numbers. datasets: diff --git a/core/nwb.icephys.yaml b/core/nwb.icephys.yaml index a3065166..06dc8c85 100644 --- a/core/nwb.icephys.yaml +++ b/core/nwb.icephys.yaml @@ -46,22 +46,37 @@ groups: attributes: - name: unit dtype: text - value: volts - doc: Base unit of measurement for working with the data. which is fixed to 'volts'. + value: V + doc: Base unit of measurement for working with the data. which is fixed to 'V'. Actual stored values are not necessarily stored in these units. To access the data in these units, multiply 'data' by 'conversion'. - name: bias_current dtype: float32 doc: Bias current, in amps. quantity: '?' + attributes: + - name: unit + dtype: text + value: A + doc: Unit of measurement for bias_current, which is fixed to 'A'. - name: bridge_balance dtype: float32 doc: Bridge balance, in ohms. quantity: '?' + attributes: + - name: unit + dtype: text + value: Ohm + doc: Unit of measurement for bridge_balance, which is fixed to 'Ohm'. - name: capacitance_compensation dtype: float32 doc: Capacitance compensation, in farads. quantity: '?' + attributes: + - name: unit + dtype: text + value: F + doc: Unit of measurement for capacitance_compensation, which is fixed to 'F'. - neurodata_type_def: IZeroClampSeries neurodata_type_inc: CurrentClampSeries @@ -92,8 +107,8 @@ groups: attributes: - name: unit dtype: text - value: amperes - doc: Base unit of measurement for working with the data. which is fixed to 'amperes'. + value: A + doc: Base unit of measurement for working with the data. which is fixed to 'A'. Actual stored values are not necessarily stored in these units. To access the data in these units, multiply 'data' by 'conversion'. @@ -108,8 +123,8 @@ groups: attributes: - name: unit dtype: text - value: amperes - doc: Base unit of measurement for working with the data. which is fixed to 'amperes'. + value: A + doc: Base unit of measurement for working with the data. which is fixed to 'A'. Actual stored values are not necessarily stored in these units. To access the data in these units, multiply 'data' by 'conversion'. - name: capacitance_fast @@ -119,8 +134,8 @@ groups: attributes: - name: unit dtype: text - value: farads - doc: Unit of measurement for capacitance_fast, which is fixed to 'farads'. + value: F + doc: Unit of measurement for capacitance_fast, which is fixed to 'F'. - name: capacitance_slow dtype: float32 doc: Slow capacitance, in farads. @@ -128,8 +143,8 @@ groups: attributes: - name: unit dtype: text - value: farads - doc: Unit of measurement for capacitance_fast, which is fixed to 'farads'. + value: F + doc: Unit of measurement for capacitance_fast, which is fixed to 'F'. - name: resistance_comp_bandwidth dtype: float32 doc: Resistance compensation bandwidth, in hertz. @@ -137,8 +152,8 @@ groups: attributes: - name: unit dtype: text - value: hertz - doc: Unit of measurement for resistance_comp_bandwidth, which is fixed to 'hertz'. + value: Hz + doc: Unit of measurement for resistance_comp_bandwidth, which is fixed to 'Hz'. - name: resistance_comp_correction dtype: float32 doc: Resistance compensation correction, in percent. @@ -146,8 +161,8 @@ groups: attributes: - name: unit dtype: text - value: percent - doc: Unit of measurement for resistance_comp_correction, which is fixed to 'percent'. + value: '%' + doc: Unit of measurement for resistance_comp_correction, which is fixed to '%'. - name: resistance_comp_prediction dtype: float32 doc: Resistance compensation prediction, in percent. @@ -155,8 +170,8 @@ groups: attributes: - name: unit dtype: text - value: percent - doc: Unit of measurement for resistance_comp_prediction, which is fixed to 'percent'. + value: '%' + doc: Unit of measurement for resistance_comp_prediction, which is fixed to '%'. - name: whole_cell_capacitance_comp dtype: float32 doc: Whole cell capacitance compensation, in farads. @@ -164,8 +179,8 @@ groups: attributes: - name: unit dtype: text - value: farads - doc: Unit of measurement for whole_cell_capacitance_comp, which is fixed to 'farads'. + value: F + doc: Unit of measurement for whole_cell_capacitance_comp, which is fixed to 'F'. - name: whole_cell_series_resistance_comp dtype: float32 doc: Whole cell series resistance compensation, in ohms. @@ -173,8 +188,8 @@ groups: attributes: - name: unit dtype: text - value: ohms - doc: Unit of measurement for whole_cell_series_resistance_comp, which is fixed to 'ohms'. + value: Ohm + doc: Unit of measurement for whole_cell_series_resistance_comp, which is fixed to 'Ohm'. - neurodata_type_def: VoltageClampStimulusSeries neurodata_type_inc: PatchClampSeries @@ -185,8 +200,8 @@ groups: attributes: - name: unit dtype: text - value: volts - doc: Base unit of measurement for working with the data. which is fixed to 'volts'. + value: V + doc: Base unit of measurement for working with the data. which is fixed to 'V'. Actual stored values are not necessarily stored in these units. To access the data in these units, multiply 'data' by 'conversion'. diff --git a/core/nwb.misc.yaml b/core/nwb.misc.yaml index c8723ba3..1fea6119 100644 --- a/core/nwb.misc.yaml +++ b/core/nwb.misc.yaml @@ -25,9 +25,9 @@ groups: attributes: - name: unit dtype: text - default_value: see 'feature_units' + default_value: n/a doc: Since there can be different units for different features, store the units - in 'feature_units'. The default value for this attribute is "see 'feature_units'". + in 'feature_units'. The default value for this attribute is "n/a". required: false - name: feature_units dtype: text @@ -35,7 +35,7 @@ groups: - num_features shape: - null - doc: Units of each feature. + doc: Units of measurement of each feature. quantity: '?' - name: features dtype: text @@ -115,13 +115,6 @@ groups: - null - null doc: Data decomposed into frequency bands. - attributes: - - name: unit - dtype: text - default_value: no unit - doc: Base unit of measurement for working with the data. Actual stored values are - not necessarily stored in these units. To access the data in these units, - multiply 'data' by 'conversion'. - name: metric dtype: text doc: The metric used, e.g. phase, amplitude, power. @@ -247,8 +240,8 @@ groups: required: false - name: unit dtype: text - value: volts - doc: Unit of measurement. This value is fixed to 'volts'. + value: V + doc: Unit of measurement. This value is fixed to 'V'. required: false - name: waveform_sd neurodata_type_inc: VectorData @@ -274,6 +267,6 @@ groups: required: false - name: unit dtype: text - value: volts - doc: Unit of measurement. This value is fixed to 'volts'. + value: V + doc: Unit of measurement. This value is fixed to 'V'. required: false diff --git a/core/nwb.namespace.yaml b/core/nwb.namespace.yaml index c3ec78ad..c0d1225e 100644 --- a/core/nwb.namespace.yaml +++ b/core/nwb.namespace.yaml @@ -57,4 +57,4 @@ namespaces: - doc: This source module contains neurodata_type for retinotopy data. source: nwb.retinotopy.yaml title: Retinotopy - version: 2.2.5 + version: 2.3.0-alpha diff --git a/core/nwb.ogen.yaml b/core/nwb.ogen.yaml index 1756ba85..d0f6cecf 100644 --- a/core/nwb.ogen.yaml +++ b/core/nwb.ogen.yaml @@ -13,8 +13,8 @@ groups: attributes: - name: unit dtype: text - value: watts - doc: Unit of measurement for data, which is fixed to 'watts'. + value: W + doc: Unit of measurement for data, which is fixed to 'W'. links: - name: site target_type: OptogeneticStimulusSite diff --git a/core/nwb.ophys.yaml b/core/nwb.ophys.yaml index 386dca9b..50d9f22a 100644 --- a/core/nwb.ophys.yaml +++ b/core/nwb.ophys.yaml @@ -226,8 +226,8 @@ groups: required: false - name: unit dtype: text - default_value: meters - doc: Base unit of measurement for working with the data. The default value is 'meters'. + default_value: m + doc: Base unit of measurement for working with the data. The default value is 'm'. required: false - name: origin_coords dtype: float32 @@ -243,8 +243,8 @@ groups: attributes: - name: unit dtype: text - default_value: meters - doc: Measurement units for origin_coords. The default value is 'meters'. + default_value: m + doc: Measurement units for origin_coords. The default value is 'm'. - name: grid_spacing dtype: float32 dims: @@ -259,8 +259,8 @@ groups: attributes: - name: unit dtype: text - default_value: meters - doc: Measurement units for grid_spacing. The default value is 'meters'. + default_value: m + doc: Measurement units for grid_spacing. The default value is 'm'. - name: reference_frame dtype: text doc: Describes reference frame of origin_coords and grid_spacing. diff --git a/core/nwb.retinotopy.yaml b/core/nwb.retinotopy.yaml index e8972395..117af491 100644 --- a/core/nwb.retinotopy.yaml +++ b/core/nwb.retinotopy.yaml @@ -39,7 +39,7 @@ groups: doc: Size of viewing area, in meters. - name: unit dtype: text - doc: Unit that axis data is stored in (e.g., degrees). + doc: Unit of measurement for axis data, e.g., "o" for degrees. - name: axis_1_power_map dtype: float32 dims: @@ -69,7 +69,7 @@ groups: doc: Size of viewing area, in meters. - name: unit dtype: text - doc: Unit that axis data is stored in (e.g., degrees). + doc: Unit of measurement for axis data, e.g., "o" for degrees. - name: axis_2_phase_map dtype: float32 dims: @@ -97,7 +97,7 @@ groups: doc: Size of viewing area, in meters. - name: unit dtype: text - doc: Unit that axis data is stored in (e.g., degrees). + doc: Unit of measurement for axis data, e.g., "o" for degrees. - name: axis_2_power_map dtype: float32 dims: @@ -127,7 +127,7 @@ groups: doc: Size of viewing area, in meters. - name: unit dtype: text - doc: Unit that axis data is stored in (e.g., degrees). + doc: Unit of measurement for axis data, e.g., "o" for degrees. - name: axis_descriptions dtype: text dims: diff --git a/docs/format/source/conf.py b/docs/format/source/conf.py index 30d39668..23f8f87e 100644 --- a/docs/format/source/conf.py +++ b/docs/format/source/conf.py @@ -83,7 +83,7 @@ def setup(app): # built documents. # # The short X.Y version. -version = 'v2.2.5' +version = 'v2.3.0-alpha' # The full version, including alpha/beta/rc tags. release = version diff --git a/docs/format/source/format_description.rst b/docs/format/source/format_description.rst index b6bc4303..5203c0ad 100644 --- a/docs/format/source/format_description.rst +++ b/docs/format/source/format_description.rst @@ -274,6 +274,112 @@ For fields with a specified size, larger sizes can be used, so long as the selected size encompasses the full range of data, and for floats, without loss of significant precision. +Units of Measurement +-------------------- + +As of NWB 2.3.0, the specification of units of measurement SHOULD follow the +`International System of Units (SI)`_ and SHOULD be formatted using +the `CMIXF-12 format`_. CMIXF provides a consistent system for all units and +prefix symbols with only basic characters, avoiding symbols that can cause +text encoding problems; for example, the CMIXF formatting for "microvolts" +is "uV", "degrees Celsius" is "oC", and "Ohm" is "Ohm". + +Units MUST consist of the unit symbol with an optionally accompanying +prefix symbol. Appropriate upper- or lower-casing MUST be applied as declared +by CMIXF-12. + +Common units in neurophysiology and their symbols: + ++-------------------+-------------+----------------------------------+ +| Unit name | Unit symbol | Quantity name | ++===================+=============+==================================+ +| second | s | time | ++-------------------+-------------+----------------------------------+ +| volt | V | voltage | ++-------------------+-------------+----------------------------------+ +| meter (metre) | m | length | ++-------------------+-------------+----------------------------------+ +| hertz | Hz | frequency | ++-------------------+-------------+----------------------------------+ +| ampere | A | electric current | ++-------------------+-------------+----------------------------------+ +| ohm | Ohm | electric resistance, impedance | ++-------------------+-------------+----------------------------------+ +| farad | F | capcaitance | ++-------------------+-------------+----------------------------------+ +| watt | W | power | ++-------------------+-------------+----------------------------------+ +| joule | J | energy, heat | ++-------------------+-------------+----------------------------------+ +| percent | % | part of 100 | ++-------------------+-------------+----------------------------------+ +| degree | o | plane angle | ++-------------------+-------------+----------------------------------+ +| radian | r | plane angle | ++-------------------+-------------+----------------------------------+ +| decibel | dB | logarithm of power ratio | ++-------------------+-------------+----------------------------------+ +| gram | g | mass | ++-------------------+-------------+----------------------------------+ +| liter (litre) | L | volume | ++-------------------+-------------+----------------------------------+ +| mole | mol | amount of substance | ++-------------------+-------------+----------------------------------+ +| degree Celsius | oC | temperature relative to 273.15 K | ++-------------------+-------------+----------------------------------+ + +Common prefixes: + ++-------------+---------------+--------+ +| Prefix name | Prefix symbol | Factor | ++=============+===============+========+ +| giga | G | 10^9 | ++-------------+---------------+--------+ +| mega | M | 10^6 | ++-------------+---------------+--------+ +| kilo | k | 10^3 | ++-------------+---------------+--------+ +| centi | c | 10^-2 | ++-------------+---------------+--------+ +| milli | m | 10^-3 | ++-------------+---------------+--------+ +| micro | u | 10^-6 | ++-------------+---------------+--------+ +| nano | n | 10^-9 | ++-------------+---------------+--------+ +| pico | p | 10^-12 | ++-------------+---------------+--------+ + +Exceptions to the above formatting: + +- Arbitrary units should be represented as "a.u.". +- Unit-less data should be represented as "n/a". +- "pixel" may be used for measurements of image data. +- "voxel" may be used for measurements of volume data. + +The unit of measurement for a value is most commonly stored in the "unit" +attribute to a dataset, e.g., ``TimeSeries.data..unit``. If the dataset +has no "unit" attribute, consult the docstring for the dataset, which +may specify a unit. Note that attributes cannot have nested attributes, +so all attributes must specify their unit in the docstring. For this +reason, it is recommended that all data and metadata with units be stored +as datasets rather than attributes. NWB extensions should also use the +format and guidance specified in this section. + +This specification follows the adoption of CMIXF-12 by BIDS (TODO include +link). + +Age values of subjects SHOULD be given in `ISO8601 duration format`_ and +it is RECOMMENDED that the age is provided at the highest resolution +available, except when a high resolution should be avoided due to privacy +protection, e.g., of human subjects. For example, the age of a mouse that +is 50 days old should be represented as "P50D". For different types of age +(e.g., days post-fertilization), use the "age_reference" attribute. + +.. _`International System of Units (SI)`: https://en.wikipedia.org/wiki/International_System_of_Units +.. _`CMIXF-12 format`: http://people.csail.mit.edu/jaffer/MIXF/CMIXF-12 +.. _`ISO8601 duration format`: https://en.wikipedia.org/wiki/ISO_8601#Durations + Links and data references ------------------------- diff --git a/docs/format/source/format_release_notes.rst b/docs/format/source/format_release_notes.rst index 8d54affc..c57d27d2 100644 --- a/docs/format/source/format_release_notes.rst +++ b/docs/format/source/format_release_notes.rst @@ -1,6 +1,12 @@ Release Notes ============= +2.3.0 (Upcoming) +---------------------- + +- All "unit" fields representing units of measurement now follow the CMIXF-12 format as described in: + https://nwb-schema.readthedocs.io/en/latest/format_description.html#units-of-measurement + 2.2.5 (May 29, 2020) ----------------------