Skip to content

Fleshed out language surrounding instrument naming #47

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dougollerenshaw wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Fleshed out language surrounding instrument naming #47

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
beca517
Fleshed out language surrounding instrument naming
dougollerenshaw Feb 17, 2026
24bbee0
Added clarification on acqusition/instrument dependencies
dougollerenshaw Feb 17, 2026
17d0792
Revert "Added clarification on acqusition/instrument dependencies"
dougollerenshaw Feb 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 19 additions & 2 deletions docs/source/acquire_upload/prepare_before_acquisition.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -299,11 +299,28 @@ Subject metadata is populated by lab animal services (LAS) without your involvem

## 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.
Copy link
Copy Markdown
Member

@dbirman dbirman Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What you added here is redundant with the aind-data-schema documentation, I don't think we should include this in two places.


Examples of physical instruments that should have corresponding instrument.json files are:
Copy link
Copy Markdown
Member

@dbirman dbirman Feb 17, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

* Individual behavioral training boxes
* Behavior recording devices that can be combined transiently with physiology rigs
* Physiology rigs (e.g. ephys, fiber photometry, two-photon imaging, etc)

In cases where a devices for multiple modalities are combined in a persistent manner (e.g. behavior equipment that is built into a physiology rig), that combination of devices should generally be tracked as a single instrument with a single corresponding instrument.json file.

When collections of devices are combined transiently (e.g. a physiology system that is combined with a physiology system in a swappable manner), those collections of devices can be described by separate instrument.json files that are combined into a single instrument at the time of upload. See the "Multiple Instruments" section below for details.


### ID

The `instrument_id` for AIND should be the SIPE ID for an instrument. If an instrument is not tracked by SIPE, any string will be accepted.
The `instrument_id` for AIND should be the SIPE ID for an instrument. SIPE instrument IDs are generally tracked relative to the computer(s) included in that instrument. A json-formatted list of SIPE instruments and associated computers can be found [here](http://mpe-computers/v2.0).

Examples of instruments tracked by SIPE:
* a foraging behavior box, "FRG.10-A"
* a mesoscope system, "MESO.1"
* a combined ephys/behavior system, "ND_Ephys.1"

If an instrument is not tracked by SIPE, any string will be accepted.

### Other details

Expand Down