Add metadata to Device

[rly]

To add information about a recording device, e.g. who was the manufacturer, what kind of amplifier, what version is it, what settings were used (or analogous information about an imaging microscope), then I would have to put that into the name field or into fields of the NWBFile like data_collection. It would be more intuitive to include this metadata information as part of the Device object, which is pretty empty - it has only the name field. We could bundle this information in a catch-all description field or we could structure this metadata information with specific fields, such as manufacturer, hardware_version, etc.

Currently, in PyNWB:

device = nwbfile.create_device(name='Plexon Omniplex')

Suggestion:

device = nwbfile.create_device(name='Omniplex', 
                               description='Plexon Omniplex A with Analog Amplifier, software version 1.14.0')

OR

device = nwbfile.create_device(name='Omniplex',
                               manufacturer='Plexon',
                               hardware_version='Omniplex A with Analog Amplifier',
                               software_version='1.14.0')

[oruebel]

@rly since this issue is about the format specifcaiton, can you please move the issue to the https://github.com/NeurodataWithoutBorders/nwb-schema repo.

[bendichter]

As long as these additional fields are optional it won't be schema-breaking.

serial_number might also be a good field

[t-b]

Does it really make sense to add 1+X new ones instead of just an optional description? Both solutions don't help in machine reading so using just description would help equally good.

[bendichter]

@t-b you don't think someone might want to query for a session with a specific software version?

[t-b]

@bendichter The format of the additional strings is fully user defined. So my reasoning is that we only need one these. Does that make sense?

[ajtritt]

The format of the additional strings is fully user defined

@t-b on that same reasoning, any data that is stored as a string is a user-defined format. Until a CV/ontology has been designed for these fields, they won't be optimally useful.

However, In the interest of progress over perfection, I think we should lay out a few common fields that users can populate as they see fit.

[t-b]

@ajtritt

I think we should lay out a few common fields that users can populate as they see fit.

Sounds good, I'm not tied to any particular solution.

[oruebel]

@rly it sounds like you and others will be looking at vendor formats during the hackathon. It might make sense to have a look at what the intersection of common fields are in the vendor formats and add optional fields that are common across vendors. I.e., I would assume that (even though specific name keys will be different) that many vendors will have some set of common metadata they store.

I think this may be a good candidate to play around with for creating the processes for review of extensions to the NWB:N core standard, the reason being a) this is a proposal for an extension to the core, b) it is fairly localized with regard to the NWB:N format (i.e. does not affect many existing types), and c) it seems ok if there is a little bit of a delay.

[rly]

Sounds good. I agree - let's discuss at the hackathon and set up fields based on what is common across vendors of all types.

Just to add to the earlier points, while these Device metadata would not be machine-readable unless they are formatted consistently, an experimenter, lab, data acquisition system, or converter script could create such consistency, which would allow for queries down the road. (They could also just create consistency in the format of a single description field, but I think we should add these fields and encourage them to encode the inherent structure of this metadata.)

Similar to this question is whether we should structure other metadata currently encoded as strings in NWBFile, such as virus, surgery, pharmacology, and slices. I think these metadata are more niche than Device metadata and should be left as is / for an extension to handle.

Reminder to address NeurodataWithoutBorders/pynwb#723 when this is addressed.

[ukos-git]

I would be in favor of adding at least a description field to the device. Similar like the format specification of the electrodes in icephys:

  datasets:
  - name: description
    dtype: text
    doc: 'description of device (e.g.,  manufacturer, model, firmware version etc) COMMENT: Free-form text'

Our devices have a manufacturer, model and a number but this information is mostly encoded in the device name itself. While the device name is machine readable, the description would only be human readable for other labs that do not know of the used setup or the specific device naming specification.

[stephprince]

Several of the fields mentioned in this issue have since been added as optional attributes to Device or will be addressed in #594:

• description
• manufacturer
• model_number (the equivalent to hardware_version as described above)
• serial_number

For now, we will recommend software versions be stored in the was_generated_by field in the NWBFile.

I will close this issue for now. If there are additional Device metadata fields that would be useful, please open a new issue to discuss.