Proposal: Standardise doc strings for multi-series container types in the core namespace

[ehennestad]

Summary

The core namespace defines a set of types whose primary role is to group one or more child neurodata objects into a named collection. These types are sometimes referred to as multi-series containers. Currently, their doc strings follow several different patterns, making the schema inconsistent and harder to read and understand.

This issue proposes a standard doc template for this class of type, for discussion.

---

Affected types

Type	File	Child type held
ProcessingModule	nwb.base	NWBDataInterface (any)
Images	nwb.base	BaseImage
BehavioralEpochs	nwb.behavior	IntervalSeries
BehavioralTimeSeries	nwb.behavior	TimeSeries
PupilTracking	nwb.behavior	TimeSeries
EyeTracking	nwb.behavior	SpatialSeries
Position	nwb.behavior	SpatialSeries
CompassDirection	nwb.behavior	SpatialSeries
FilteredEphys	nwb.ecephys	ElectricalSeries
LFP	nwb.ecephys	ElectricalSeries
DfOverF	nwb.ophys	RoiResponseSeries
Fluorescence	nwb.ophys	RoiResponseSeries
ImageSegmentation	nwb.ophys	PlaneSegmentation
MotionCorrection	nwb.ophys	CorrectedImageStack
BehavioralEvents	nwb.behavior	TimeSeries (deprecated)
EventWaveform	nwb.ecephys	SpikeEventSeries (deprecated)

---

Current inconsistency

The existing doc strings use at least four distinct patterns:

1. Describes the data as if the type were a dataset (most common):

• "LFP data from one or more channels." — LFP
• "Eye-tracking data, representing direction of gaze." — EyeTracking
• "Position data, whether along the x, x/y or x/y/z axis." — Position
• "dF/F information about a region of interest (ROI)." — DfOverF

2. Uses old module-centric language (stale):

• "With a CompassDirection interface, a module publishes a SpatialSeries object..." — CompassDirection
• "FilteredEphys modules publish an ElectricalSeries for each filtered channel..." — FilteredEphys

3. Starts with the type's own name (redundant):

• "TimeSeries for storing behavioral epochs." — BehavioralEpochs
• "TimeSeries for storing behavioral time series data." — BehavioralTimeSeries (also names the wrong child type)

4. Uses correct container framing:

• "A collection of processed data." — ProcessingModule
• "A collection of images with an optional way to specify the order..." — Images

---

Proposed template

A container for one or more [ChildType] objects storing [semantic description].
[Optional: constraint on child naming, ordering, or required fields.]
[Optional: cross-reference to a related container in the same processing module.]

Rules:

1. Always open with "A container for" — never describe the payload as if the type were a dataset.
2. Always name the child type explicitly: "one or more [ChildType] objects".
3. Follow with "storing [noun phrase]".
4. Do not open with the type name itself.
5. Cross-references and constraints go in a second sentence.
6. End with a period.

---

Proposed rewrites

Type	Proposed doc
ProcessingModule	A container for one or more NWBDataInterface objects storing the results of a processing pipeline.
Images	A container for one or more BaseImage objects. The 'order_of_images' dataset may be used to specify the display order; an order is required if the images are referenced by index, e.g., from an IndexSeries.
BehavioralEpochs	A container for one or more IntervalSeries objects storing behavioral epochs. Use alongside BehavioralTimeSeries and BehavioralEvents to provide generic hooks for software tools that search NWBFile groups by neurodata type.
BehavioralTimeSeries	A container for one or more TimeSeries objects storing continuous behavioral data. See BehavioralEpochs for usage context.
PupilTracking	A container for one or more TimeSeries objects storing pupil size data.
EyeTracking	A container for one or more SpatialSeries objects storing the direction of gaze.
Position	A container for one or more SpatialSeries objects storing position data along one or more spatial axes (x, x/y, or x/y/z).
CompassDirection	A container for one or more SpatialSeries objects storing heading direction (theta). The 'reference_frame' attribute of each SpatialSeries should indicate which direction corresponds to 0 and in which direction values increase.
FilteredEphys	A container for one or more ElectricalSeries objects storing filtered electrophysiology data. Each ElectricalSeries should correspond to one filtered channel or group of channels. The source and filter properties should be noted in each ElectricalSeries 'description' and 'filtering' attributes. See also LFP for low-frequency filtered data.
LFP	A container for one or more ElectricalSeries objects storing local field potential (LFP) data. The electrode map in each ElectricalSeries identifies the contributing channels. Filter properties should be recorded in the ElectricalSeries 'filtering' attribute.
DfOverF	A container for one or more RoiResponseSeries objects storing dF/F (normalized fluorescence change) values for regions of interest (ROIs). The name of each RoiResponseSeries should match the name of the corresponding PlaneSegmentation in the sibling ImageSegmentation container.
Fluorescence	A container for one or more RoiResponseSeries objects storing raw fluorescence values for regions of interest (ROIs). The name of each RoiResponseSeries should match the name of the corresponding PlaneSegmentation in the sibling ImageSegmentation container.
ImageSegmentation	A container for one or more PlaneSegmentation objects, each storing pixel masks or ROIs for a single imaging plane.
MotionCorrection	A container for one or more CorrectedImageStack objects, each storing a motion-corrected image series alongside the applied x/y translation offsets.

---

Questions for discussion

• Is "A container for one or more [ChildType] objects storing..." the right opening, or would "A collection of [ChildType] objects..." be preferred (to align with ProcessingModule and Images)?
• Should deprecated types be updated to match the new template, or left as-is?
• Should this convention be recorded somewhere (e.g., CONTRIBUTING.md or a neurodata type authoring guide) so that extension namespaces can follow the same pattern?