Fiber Photometry#

Base Fiber Photometry#

Base interface for single-series fiber photometry data.

A BaseFiberPhotometryInterface writes exactly one FiberPhotometryResponseSeries to an NWBFile, assembled from one or more input streams (atomic source signals, e.g. TDT stores or Doric datasets). All the shared containers (device models, devices, optical fibers, indicators, viral vectors/injections, the FiberPhotometryTable, and any CommandedVoltageSeries) live under metadata["FiberPhotometry"] as name-keyed lists and are built once per file — the first interface to run assembles them from the (converter-merged) metadata and subsequent interfaces reuse them. Multiple response series therefore means multiple interfaces sharing one table, exactly like several ecephys recording interfaces sharing one electrodes table.

Child interfaces implement only the format-reading seam:

  • get_available_streams(...) — discover atomic source streams (a classmethod/staticmethod so a converter can be authored before construction).

  • _get_stream_data(stream_name) — return time-major data for one stream.

  • _get_stream_timestamps(stream_name) — return the timestamps for one stream.

  • get_metadata — enrich the base scaffold with whatever the format embeds (e.g. session start time).

class BaseFiberPhotometryInterface(*, stream_names: str | list[str], metadata_key: str | None = None, stream_indices: list[int] | None = None, verbose: bool = False, **source_data)[source]#

Bases: BaseTemporalAlignmentInterface

Base class for single-series fiber photometry interfaces (one FiberPhotometryResponseSeries).

Initialize a single-series fiber photometry interface.

Parameters:

  • stream_names (str or list of str) – The input stream(s) — atomic source signals (e.g. TDT stores) — whose samples are column-stacked into this interface’s single FiberPhotometryResponseSeries.

  • metadata_key (str, optional) – Key under metadata["FiberPhotometry"] holding this interface’s response-series metadata. When None (default), it is generated from stream_names (e.g. stream "_405R" gives "fiber_photometry_405r"), so multiple interfaces over different streams already get distinct keys. Pass an explicit value to override.

  • stream_indices (list of int, optional) – Column indices selecting which channels of the (column-stacked) stream data to keep. None (default) keeps all channels.

  • verbose (bool, default: False) – Whether to print status messages.

  • **source_data – Format-specific source arguments (e.g. folder_path or file_path).

keywords: tuple[str] = ('fiber photometry',)#
get_original_timestamps() → ndarray[source]#

Return the original (unaligned) timestamps of this interface’s primary stream.

get_timestamps() → ndarray[source]#

Return aligned timestamps if set, otherwise the original timestamps.

set_aligned_timestamps(aligned_timestamps: ndarray) → None[source]#

Replace this interface’s timestamps with externally aligned values.

get_metadata() → DeepDict[source]#

Return the NWBFile basics combined with the default top-level FiberPhotometry scaffold.

The scaffold (built by get_default_fiber_photometry_metadata()) pre-fills required fields with sentinels — NaN for the required numeric wavelengths and FIBER_PHOTOMETRY_PLACEHOLDER for required strings — so the interface runs on zero user metadata. add_to_nwbfile warns about any surviving sentinel.

get_metadata_schema() → dict[source]#

Return a permissive schema for the FiberPhotometry and top-level device metadata blocks.

add_to_nwbfile(nwbfile: NWBFile, metadata: dict | None = None, *, stub_test: bool = False, stub_samples: int = 100, always_write_timestamps: bool = False, strict: bool = False) → None[source]#

Add this interface’s FiberPhotometryResponseSeries (and, once, the shared containers).

The shared containers (devices, indicators, table, commanded voltage) are added through idempotent helpers, so this method simply calls them; the first interface to run builds them and subsequent interfaces reuse them. Timing is written as starting_time + rate when the timestamps are regular, otherwise as an explicit timestamps array.

Parameters:

  • nwbfile (NWBFile) – The in-memory NWBFile to add the data to.

  • metadata (dict, optional) – Metadata dictionary; defaults to self.get_metadata().

  • stub_test (bool, default: False) – If True, add only the first stub_samples samples of each series for testing purposes.

  • stub_samples (int, default: 100) – The number of samples to write when stub_test is True.

  • always_write_timestamps (bool, default: False) – If True, always write an explicit timestamps array even when the series is regularly sampled.

  • strict (bool, default: False) – If True, raise instead of warning when required metadata still holds placeholder sentinels.

Doric Fiber Photometry#

Interface for Doric Neuroscience Studio fiber photometry data (.doric HDF5 or DoricStudio CSV files).

class DoricFiberPhotometryInterface(*, file_path: Annotated[pathlib._local.Path, PathType(path_type='file')], stream_names: str | list[str], metadata_key: str | None = None, stream_indices: list[int] | None = None, verbose: bool = False)[source]#

Bases: BaseFiberPhotometryInterface

Interface for fiber photometry data from Doric Neuroscience Studio.

Reads either of the two formats produced by Doric Neuroscience Studio (compatible with BBC300, BBC600, FPC, and other Doric acquisition hardware) and writes a single FiberPhotometryResponseSeries to NWB using the ndx-fiber-photometry extension, assembled from one or more input streams; use multiple interfaces (with distinct metadata_key values) in a converter to write several series sharing one FiberPhotometryTable.

  • .doric (HDF5): stream names are auto-discovered by walking DataAcquisition for groups that contain a Time sibling dataset. Each non-Time 1-D dataset found this way becomes a stream whose name is the path relative to DataAcquisition with / replaced by _ (e.g. BBC300_ROISignals_Series0001_CAM1EXC1_ROI01). Older “EPConsole”-style exports that instead nest each stream under Traces/<console>/<stream>/<stream> (with a sibling Traces/<console>/Time(s)/... group holding the shared timestamps) are also supported.

  • .csv (DoricStudio CSV export): one shared time column (matched case-insensitively against "Time(s)"/"time") plus one or more data columns; each data column is a stream named after its column header (e.g. sig, ref). The time column may be on the first or second line (older exports prepend a channel/device “group” line above the real header), and trailing unnamed (empty) columns are ignored.

Call get_available_streams() to discover stream names for either format.

Initialize the DoricFiberPhotometryInterface.

Parameters:

  • file_path (FilePath) – Path to the .doric HDF5 file or DoricStudio .csv export.

  • stream_names (str or list of str) – The input stream(s) whose samples are assembled into this interface’s single FiberPhotometryResponseSeries. Call get_available_streams() to discover them.

  • metadata_key (str, optional) – Key under metadata["FiberPhotometry"] holding this interface’s response-series metadata. When None (default), it is generated from stream_names.

  • stream_indices (list of int, optional) – Column indices selecting which channels of the (column-stacked) stream data to keep.

  • verbose (bool, default: False) – Whether to print status messages.

display_name: str | None = 'DoricFiberPhotometry'#
info: str | None = 'Data Interface for converting fiber photometry data from Doric Neuroscience Studio.'#
associated_suffixes: tuple[str] = ('doric', 'csv')#
classmethod get_available_streams(file_path) → list[str][source]#

Return the names of the streams available in a Doric .doric or .csv file.

Parameters:

file_path (FilePath) – Path to the .doric HDF5 file or DoricStudio CSV export.

Returns:

Sorted list of stream names.

Return type:

list[str]

get_metadata() → DeepDict[source]#

Return the NWBFile basics combined with the default top-level FiberPhotometry scaffold.

The scaffold (built by get_default_fiber_photometry_metadata()) pre-fills required fields with sentinels — NaN for the required numeric wavelengths and FIBER_PHOTOMETRY_PLACEHOLDER for required strings — so the interface runs on zero user metadata. add_to_nwbfile warns about any surviving sentinel.

TDT Fiber Photometry#

class TDTFiberPhotometryInterface(folder_path: Annotated[pathlib._local.Path, PathType(path_type='dir')], *, stream_names: str | list[str] | None = None, metadata_key: str | None = None, stream_indices: list[int] | None = None, verbose: bool = False)[source]#

Bases: BaseTemporalAlignmentInterface

Data Interface for converting fiber photometry data from a TDT output folder.

Each interface writes a single FiberPhotometryResponseSeries, assembled from one or more input streams (TDT stores); use multiple interfaces (with distinct metadata_key values) in a converter to write several series sharing one FiberPhotometryTable. Call get_available_streams() to discover stream names.

Deprecated since version Constructing: without stream_names routes to the deprecated multi-series implementation, which writes every stream at once and will be removed on or after January 2027. Pass stream_names to use the single-series interface.

Initialize the TDTFiberPhotometryInterface.

Parameters:

  • folder_path (DirectoryPath) – The path to the folder containing the TDT data.

  • stream_names (str or list of str, optional) – The input stream(s) (TDT stores) whose samples are assembled into this interface’s single FiberPhotometryResponseSeries. If omitted, the deprecated multi-series behavior is used (see class docstring).

  • metadata_key (str, optional) – Key under metadata["FiberPhotometry"] holding this interface’s response-series metadata. When None (default), it is generated from stream_names.

  • stream_indices (list of int, optional) – Column indices selecting which channels of the (column-stacked) stream data to keep.

  • verbose (bool, default: False) – Whether to print status messages.

keywords: tuple[str] = ('fiber photometry',)#
display_name: str | None = 'TDTFiberPhotometry'#
info: str | None = 'Data Interface for converting fiber photometry data from TDT files.'#
associated_suffixes: tuple[str] = ('Tbk', 'Tdx', 'tev', 'tin', 'tsq')#
classmethod get_available_streams(folder_path: Annotated[Path, PathType(path_type=dir)]) → list[str][source]#

Return the names of the stream stores available in a TDT tank.

get_metadata() → DeepDict[source]#

Child DataInterface classes should override this to match their metadata.

Returns:

The metadata dictionary containing basic NWBFile metadata.

Return type:

DeepDict

get_metadata_schema() → dict[source]#

Retrieve JSON schema for metadata.

Returns:

The JSON schema defining the metadata structure.

Return type:

dict

get_conversion_options_schema() → dict[source]#

Infer the JSON schema for the conversion options from the method signature (annotation typing).

Returns:

The JSON schema for the conversion options.

Return type:

dict

get_original_timestamps(*args, **kwargs)[source]#

Retrieve the original unaltered timestamps for the data in this interface.

This function should retrieve the data on-demand by re-initializing the IO.

Returns:

timestamps – The timestamps for the data stream.

Return type:

numpy.ndarray

get_timestamps(*args, **kwargs)[source]#

Retrieve the timestamps for the data in this interface.

Returns:

timestamps – The timestamps for the data stream.

Return type:

numpy.ndarray

set_aligned_timestamps(*args, **kwargs) → None[source]#

Replace all timestamps for this interface with those aligned to the common session start time.

Must be in units seconds relative to the common ‘session_start_time’.

Parameters:

aligned_timestamps (numpy.ndarray) – The synchronized timestamps for data in this interface.

set_aligned_starting_time(*args, **kwargs) → None[source]#

Align the starting time for this interface relative to the common session start time.

Must be in units seconds relative to the common ‘session_start_time’.

Parameters:

aligned_starting_time (float) – The starting time for all temporal data in this interface.

add_to_nwbfile(nwbfile: NWBFile, metadata: dict | None = None, **conversion_options) → None[source]#

Define a protocol for mapping the data from this interface to NWB neurodata objects.

These neurodata objects should also be added to the in-memory pynwb.NWBFile object in this step.

Parameters:

  • nwbfile (pynwb.NWBFile) – The in-memory object to add the data to.

  • metadata (dict) – Metadata dictionary with information used to create the NWBFile.

  • **conversion_options – Additional keyword arguments to pass to the .add_to_nwbfile method.