Question for new DeviceModel type

[ehennestad]

In NWB v2.8.0 the following properties were added to Device:

• model_number,
• model_name,
• serial_number

Now these are moved to the new DeviceModel type, but I see some inconsistencies between issue discussions, new schema and the current release notes.

1. Deprecated serial_number

The current release notes for upcoming v2.9.0 states the following:
Deprecated Device.model_number, Device.model_name, Device.serial_number. Use Device.model link and new DeviceModel neurodata type instead. (#608)

nwb-schema/docs/format/source/format_release_notes.rst

Lines 11 to 12 in c288427

	- Deprecated ``Device.model_number``, ``Device.model_name``, ``Device.serial_number``. Use
	``Device.model`` link and new ``DeviceModel`` neurodata type instead. (#608)

However, the serial_number is not deprecated in the schema (i.e "Deprecated" is not present in the doc):

nwb-schema/core/nwb.device.yaml

Lines 31 to 34 in c288427

	- name: serial_number
	dtype: text
	doc: The serial number of the device.
	required: false

I assume the serial number should still be a property of Device, but manufacturer should be mentioned as deprecated in the release notes?

2. model_name is deprecated from Device, but not added to Device_Model

nwb-schema/core/nwb.device.yaml

Lines 25 to 29 in c288427

	- name: model_name
	dtype: text
	doc: DEPRECATED. The model name of the device, e.g., Neuropixels 1.0, V-Probe, Bergamo III.
	Instead of using this field, storing the value in DeviceModel.name and link to that
	DeviceModel from this Device.

[rly]

1. Sorry, the release notes were incorrect.
2. If a user has a Device model name, they should use DeviceModel.name to store it.

[rly]

I am fixing this in #634

[ehennestad]

If a user has a Device model name, they should use DeviceModel.name to store it.

This is a bit unclear as name is not an attribute/dataset of DeviceModel. I know name is generally an attribute of neurodata types in pynwb, but in matnwb name is not intrinsic to neurodata types. Trying to set the name using DeviceModel.name = 'some name' would fail. Maybe there is some documentation of the name attribute I am not aware of?

[rly]

You're right that PyNWB and MatNWB specify name differently. If I understand MatNWB correctly, the name of an object is set when the object is added as a child to another object. So in this case, when a user adds a DeviceModel to a file, using something like:

device_model = types.core.DeviceModel(...
'description', 'A 12-channel array with 4 shanks and 3 channels per shank', ...
'manufacturer', 'Array Technologies', ...
'model_number', 'PRB_1_4_0480_123', ...
);

% Add device to nwb object
nwb.general_devices_models.set('Neurovoxels 0.99', device_model);

Then the device model gets the name "Neurovoxels 0.99". And then they can link to this device model object from a new device. I can try to clarify the release notes to reflect this.

[ehennestad]

Yes, thats correct wrt to matnwb

I am more interested in clarifying the doc for Device.

nwb-schema/core/nwb.device.yaml

Line 28 in 1078e4a

Instead of using this field, storing the value in DeviceModel.name and link to that

The description here should ideally be self-referential wrt to the schema, unless i am missing a broader context wrt names

[rly]

Would this be better?

    doc: DEPRECATED. The model name of the device, e.g., Neuropixels 1.0, V-Probe, Bergamo III.
      Instead of using this field, create and add a new DeviceModel named the model name and 
      link to that DeviceModel from this Device.