Acquisition¶

An acquisition is single episode of data collection that creates one data asset.

The acquisition metadata is split into two parallel pieces the DataStream and the StimulusEpoch. At any given moment in time the active DataStream(s) represents all modalities of data being acquired, while the StimulusEpoch represents all stimuli being presented.

DataStream: A set of devices that are acquiring data and their configurations.
StimulusEpoch: All stimuli being presented to the subject. Not all acquisitions have StimulusEpochs.

A single DataStream should capture all the modalities of data acquired as a group, even when their start/stop times differ by a small amount.

Because the start and stop times are independent for data streams and stimulus epochs almost all acquisitions will fall into one of these three common types:

Single data stream and one stimulus epoch (including no stimulus): these acquisitions are common for imaging experiments with specimens where there might be no stimulus presented.
Single data stream with multiple stimulus epochs: common during animal physiology when you might do both an experimental stimulus and then follow that with one or more epochs of quiet wakefulness, receptive field mapping, etc.
Single stimulus epoch with multiple data streams: less common, but can occur if you switch modalities during an experiment or change the configuration of an acute recording device.

Uniqueness¶

You can uniquely identify acquisition sessions (and therefore a specific data asset) by their acquisition datetime (Acquisition.acquisition_start_time). In addition, the Acquisition.acquisition_type is an open str field where you can put conceptual information that groups similar acquisitions together. This should not be completely redundant with project names, modalities, stimulus names, or any other fields in the metadata.

For example, in the "Brain Computer Interface" project name, good acquisition types would be strings like: "Single neuron stim" and "Group neuron stim". These phrases clearly identify what part of a project these acquisitions belong to, without being overly redundant with controlled fields in the metadata.

Stimulus parameters¶

You should use the Code.parameters field to store your stimulus properties for each StimulusEpoch. We have pre-existing parameter schemas for a subset of stimuli defined here or you can define your own schema.

Manipulations¶

Procedures that occur during an acquisition (between the start_time and end_time) should be recorded in the Acquisition.manipulations using a Manipulation.

FAQs¶

When should a DataStream be split in two¶

The DataStream should be split if there is a change in data modalities or a change in the configuration of devices. Or if a modality is only acquired during a subset of the time the stream is active. For example, if you acquire behavior videos for a full hour of an acquisition and only collect ecephys for twenty minutes you should separate these into two streams. If the start and end times are within a few minutes of each other you should combine the modalities into a single stream.

When should a StimulusEpoch be split in two¶

The StimulusEpoch should be split if the purpose of the presented stimuli changes. For example: receptive field mapping and optogenetic manipulation are two different stimulus epochs. Individual trials of optogenetic manipulation are part of a single stimulus epoch.

Most experimenters will be familiar with the idea of breaking down an experiment into blocks and then further into trials: blocks and trials are part of one stimulus epoch. Information about blocks and trials are parameters that describe a stimulus epoch and can be stored in the StimulusEpoch.code.parameters.

Diagrams¶

Example acquisition demonstrating situation 1: one data stream, one stimulus epoch.

Example acquisition demonstrating situation 2: one data stream, multiple stimulus epochs.

Example acquisition demonstrating 3: one stimulus epoch, multiple data streams.

Examples¶

Core file¶

Acquisition¶

Description of data acquisition metadata including streams, stimuli, and experimental setup.

The acquisition metadata is split into two parallel pieces: the DataStream and the StimulusEpoch. At any given moment in time the active DataStream(s) represents all modalities of data being acquired, while the StimulusEpoch represents all stimuli being presented.

Field	Type	Title (Description)
`subject_id`	`str`	Subject ID (Unique identifier for the subject)
`specimen_id`	`str or List[str] or NoneType`	Specimen ID (Required for in vitro modalities. Standard format is {subject_id} with a _### suffix, as needed)
`acquisition_start_time`	`datetime (timezone-aware)`	Acquisition start time (During validation, timezone information will be moved into the acquisition_start_tz field.)
`acquisition_start_tz`	`int or pydantic_extra_types.timezone_name.TimeZoneName or NoneType`	Acquisition start timezone (Automatically populated by a validator based on acquisition_start_time. Will be a TimeZoneName (IANA name) when the datetime uses a ZoneInfo timezone, or an integer UTC offset in hours for fixed-offset timezones. Use ZoneInfo (from the zoneinfo standard library) to preserve the named timezone.)
`acquisition_end_time`	`datetime (timezone-aware)`	Acquisition end time
`experimenters`	`List[str]`	experimenter(s)
`ethics_review_id`	`Optional[List[str]]`	Ethics review ID
`instrument_id`	`Optional[str]`	Instrument ID (Should match the Instrument.instrument_id. Required when instrument metadata is available.)
`acquisition_type`	`str`	Acquisition type (Descriptive string detailing the type of acquisition, should be consistent across similar acquisitions for the same experiment.)
`notes`	`Optional[str]`	Notes
`coordinate_system`	Optional[CoordinateSystem]	Coordinate system (Origin and axis definitions for determining the configured position of devices during acquisition. Required when coordinates are provided within the Acquisition)
`calibrations`	List[Calibration or VolumeCalibration or PowerCalibration]	Calibrations (List of calibration measurements taken prior to acquisition.)
`maintenance`	List[Maintenance]	Maintenance (List of maintenance on instrument prior to acquisition.)
`data_streams`	List[DataStream or ExternalDataStream]	Data streams (A data stream is a collection of devices that are acquiring data simultaneously. Each acquisition can include multiple streams. Streams should be split when configurations are changed. Use ExternalDataStream for acquisitions where instrument metadata is unavailable.)
`stimulus_epochs`	List[StimulusEpoch]	Stimulus (A stimulus epoch captures all stimuli being presented during an acquisition. Epochs should be split when the purpose of the stimulus changes.)
`manipulations`	List[Manipulation]	Manipulations (Procedures performed during the acquisition.)
`subject_details`	Optional[AcquisitionSubjectDetails]	Subject details (Required for in vivo acquisitions.)
`protocol_id`	`Optional[List[str]]`	Protocol ID (DOI for protocols.io)

Model definitions¶

AcquisitionSubjectDetails¶

Details about the subject during an acquisition

Field	Type	Title (Description)
`animal_weight_prior`	`Optional[decimal.Decimal]`	Animal weight (g) (Animal weight before procedure)
`animal_weight_post`	`Optional[decimal.Decimal]`	Animal weight (g) (Animal weight after procedure)
`weight_unit`	MassUnit	Weight unit
`anaesthesia`	Optional[Anaesthetic]	Anaesthesia (Anaesthesia present during entire acquisition, use Manipulation for partial anaesthesia)
`mouse_platform_name`	`str`	Mouse platform (The surface that the mouse is on during the acquisition)
`reward_consumed_total`	`Optional[decimal.Decimal]`	Total reward consumed (mL)
`reward_consumed_unit`	Optional[VolumeUnit]	Reward consumed unit

DataStream¶

A set of devices that are acquiring data and their configurations starting and stopping at approximately the same time.

Field	Type	Title (Description)
`stream_start_time`	`datetime (timezone-aware)`	Stream start time
`stream_end_time`	`datetime (timezone-aware)`	Stream stop time
`modalities`	List[Modality]	Modalities (Modalities that are acquired in this stream)
`code`	Optional[List[Code]]	Acquisition code
`notes`	`Optional[str]`	Notes
`active_devices`	`List[str]`	Active devices (Device names must match devices in the Instrument)
`configurations`	List[LightEmittingDiodeConfig or LaserConfig or ManipulatorConfig or DetectorConfig or PatchCordConfig or FiberAssemblyConfig or MISCameraConfig or MRIScan or LickSpoutConfig or AirPuffConfig or ImagingConfig or SampleChamberConfig or ProbeConfig or EphysAssemblyConfig or CatheterConfig]	Device configurations (Configurations are parameters controlling active devices during this stream)
`connections`	List[Connection]	Connections (Connections are links between devices that are specific to this acquisition (i.e. not already defined in the Instrument))

ExternalDataStream¶

A simplified data stream for acquisitions where instrument metadata is unavailable.

Field	Type	Title (Description)
`stream_start_time`	`datetime (timezone-aware)`	Stream start time
`stream_end_time`	`datetime (timezone-aware)`	Stream stop time
`modalities`	List[Modality]	Modalities (Modalities that are acquired in this stream)
`notes`	`Optional[str]`	Notes

Manipulation¶

Description of procedures performed during an acquisition.

Field	Type	Title (Description)
`start_time`	`datetime (timezone-aware)`	Manipulation start time (Must be between the acquisition start and end times)
`end_time`	`datetime (timezone-aware)`	Manipulation end time (Must be between the acquisition start and end times)
`procedures`	Optional[List[Injection or BrainInjection or Reagent]]	Procedures (Procedures performed during the manipulation)
`anaesthesia`	Optional[Anaesthetic]	Anaesthesia
`notes`	`Optional[str]`	Notes
`protocol_id`	`Optional[List[str]]`	Protocol ID (DOI for protocols.io)

PerformanceMetrics¶

Summary of a StimulusEpoch

Field	Type	Title (Description)
`output_parameters`	`Optional[dict]`	Additional metrics
`reward_consumed_during_epoch`	`Optional[decimal.Decimal]`	Reward consumed during training (uL)
`reward_consumed_unit`	Optional[VolumeUnit]	Reward consumed unit
`trials_total`	`Optional[int]`	Total trials
`trials_finished`	`Optional[int]`	Finished trials
`trials_rewarded`	`Optional[int]`	Rewarded trials

StimulusEpoch¶

All stimuli being presented to the subject. starting and stopping at approximately the same time. Not all acquisitions have StimulusEpochs.

Field	Type	Title (Description)
`stimulus_start_time`	`datetime (timezone-aware)`	Stimulus start time (When a specific stimulus begins. This might be the same as the acquisition start time.)
`stimulus_end_time`	`datetime (timezone-aware)`	Stimulus end time (When a specific stimulus ends. This might be the same as the acquisition end time.)
`stimulus_name`	`str`	Stimulus name
`code`	Optional[Code]	Code or script (Custom code/script used to control the behavior/stimulus. Use the Code.parameters field to store stimulus properties)
`stimulus_modalities`	List[StimulusModality]	Stimulus modalities
`performance_metrics`	Optional[PerformanceMetrics]	Performance metrics
`notes`	`Optional[str]`	Notes
`active_devices`	`List[str]`	Active devices (Device names must match devices in the Instrument)
`configurations`	List[SpeakerConfig or LightEmittingDiodeConfig or LaserConfig or MousePlatformConfig or OlfactometerConfig]	Device configurations
`training_protocol_name`	`Optional[str]`	Training protocol name (Name of the training protocol used during the acquisition, must match a protocol in the Procedures)
`curriculum_status`	`Optional[str]`	Curriculum status (Status within the training protocol curriculum)