Fleshed out language surrounding instrument naming#47
Fleshed out language surrounding instrument naming#47dougollerenshaw wants to merge 3 commits intomainfrom
Conversation
dbirman
left a comment
dbirman
left a comment
There was a problem hiding this comment.
I think we should be careful not to pull data schema documentation into the AIND docs and I also think we should be clear that an instrument is a single thing, even if operationally users are giving us the metadata in multiple pieces.
| ## Instrument | ||
|
|
||
| [Instrument](https://aind-data-schema.readthedocs.io/en/latest/instrument.html) metadata should be prepared in advance of data acquisition. | ||
| [Instrument](https://aind-data-schema.readthedocs.io/en/latest/instrument.html) metadata should be prepared in advance of data acquisition. Instrument metadata should describe the full set of devices that are combined into the physical instrument that is used to collect an associated dataset, regardless of whether those devices are active on a given session. This makes it possible to specify an instrument.json as a stable collection of devices (just like a physical instrument in the lab) even if some of those devices are used only in a subset of experimental sessions. The actual list of active devices and their configurable settings should be specified separately in the acquisition.json. |
There was a problem hiding this comment.
What you added here is redundant with the aind-data-schema documentation, I don't think we should include this in two places.
| [Instrument](https://aind-data-schema.readthedocs.io/en/latest/instrument.html) metadata should be prepared in advance of data acquisition. | ||
| [Instrument](https://aind-data-schema.readthedocs.io/en/latest/instrument.html) metadata should be prepared in advance of data acquisition. Instrument metadata should describe the full set of devices that are combined into the physical instrument that is used to collect an associated dataset, regardless of whether those devices are active on a given session. This makes it possible to specify an instrument.json as a stable collection of devices (just like a physical instrument in the lab) even if some of those devices are used only in a subset of experimental sessions. The actual list of active devices and their configurable settings should be specified separately in the acquisition.json. | ||
|
|
||
| Examples of physical instruments that should have corresponding instrument.json files are: |
There was a problem hiding this comment.
Does breaking this up help or create more confusion? At the end of the day a data asset will have one single set of Instrument metadata that is the combination of everything that was running. I think that needs to be super clear to people. It's an operational shortcut that we allow people to give us their instrument metadata separated. I'm not sure the top-level section here should be delving into these operational details... Instead of "Other details" maybe we need a section called "How to provide your instrument metadata" where we make clear that there are different paths for different use cases
dougollerenshaw
force-pushed
the
fix_46_clarify_instrument_id_language
branch
from
24bbee0 to
be4b785
Compare
This reverts commit 24bbee0.
Fair point about some of this info already existing in the data schema docs. But I put in this PR in response to actual confusion and a request to clarify, so I think that does point to a need to do better here. Let me see if I can make the language here more of a summary of what's in the data schema doc with an explicit link to look there for more detail. And I also think the points about individual instruments are important. That's leading to a lot of the confusion. Maybe some of the confusion comes from us not being clear when we use the word "instrument" whether we're talking about a physical instrument in the lab or the JSON file describing it. I'll take another pass at this to see if I can write this in a way that clarifies without adding too many words. |
2 participants
This PR closes #46.
Edits are to the
process_before_acquisition.mdfile with the goal of clarifying what constitutes a physical instrument and how those instruments should be named.I added language to the top level
Instrumentsection that clarifies single vs multiple instruments and emphasizes the relationship between a physical instrument and the corresponding instrument.json file.I added language to the
IDsection that links to the SIPE computer/instrument endpoint and tries to clarify the relationship between SIPE IDs and instrument IDs. Since SIPE tracks things primarily by computer ID, I tried to note through examples that instruments can include either single computers (e.g. a behavior box) or multiple computers (e.g. a physiology system).