1. Overview

1.1. ndx-ophys-devices Extension for NWB

This is an NWB extension for storing metadata of devices used in optical experimental setups (microscopy, fiber photometry, optogenetic stimulation, etc.).

This extension consists of neurodata types in the following categories:

Container Classes:

  • ViralVector extends NWBContainer to hold metadata on viral vectors used for gene delivery.

  • ViralVectorInjection extends NWBContainer to hold metadata on viral vector injection procedures.

  • Indicator extends NWBContainer to hold metadata on the fluorescent indicator.

  • Effector extends NWBContainer to hold metadata on the effector/opsin.

  • StereotacticPosition extends NWBContainer to hold metadata about the stereotactic position of a device relative to the brain.

Device Model Classes:

  • DeviceModel extends Device to hold metadata on device models.

  • OpticalFiberModel extends DeviceModel to hold metadata on the optical fiber model.

  • ExcitationSourceModel extends DeviceModel to hold metadata on the excitation source model.

  • PhotodetectorModel extends DeviceModel to hold metadata on the photodetector model.

  • DichroicMirrorModel extends DeviceModel to hold metadata on the dichroic mirror model.

  • OpticalFilterModel extends DeviceModel to hold metadata on a general optical filter model.

  • BandOpticalFilterModel extends OpticalFilterModel to hold metadata on any bandpass or bandstop optical filter models.

  • EdgeOpticalFilterModel extends OpticalFilterModel to hold metadata on any edge optical filter models.

  • ObjectiveLensModel extends DeviceModel to hold metadata on the objective lens model.

Device Instance Classes:

  • DeviceInstance extends Device to hold metadata on device instances.

  • OpticalFiber extends DeviceInstance to hold metadata on optical fiber instances.

  • ExcitationSource extends DeviceInstance to hold metadata on excitation source instances.

  • PulsedExcitationSource extends ExcitationSource to hold metadata on pulsed excitation source instances.

  • Photodetector extends DeviceInstance to hold metadata on photodetector instances.

  • DichroicMirror extends DeviceInstance to hold metadata on dichroic mirror instances.

  • OpticalFilter extends DeviceInstance to hold metadata on general optical filter instances.

  • BandOpticalFilter extends OpticalFilter to hold metadata on bandpass or bandstop optical filter instances.

  • EdgeOpticalFilter extends OpticalFilter to hold metadata on edge optical filter instances.

  • ObjectiveLens extends DeviceInstance to hold metadata on objective lens instances.

Note that the container classes cannot be directly added to the NWB file, but instead require extending LabMetaData to contain one or more of these container classes in a separate extension. For example, see ndx-optogenetics.

1.2. Installation

To install the latest stable release through PyPI, run:

pip install ndx-ophys-devices

1.3. Usage

import datetime
import numpy as np
from pynwb import NWBFile
from ndx_ophys_devices import (
    # Container classes
    ViralVector,
    ViralVectorInjection,
    Indicator,
    Effector,
    StereotacticPosition,

    # Model classes
    OpticalFiberModel,
    ExcitationSourceModel,
    PhotodetectorModel,
    DichroicMirrorModel,
    OpticalFilterModel,
    BandOpticalFilterModel,
    EdgeOpticalFilterModel,
    ObjectiveLensModel,

    # Device instance classes
    OpticalFiber,
    ExcitationSource,
    PulsedExcitationSource,
    Photodetector,
    DichroicMirror,
    OpticalFilter,
    BandOpticalFilter,
    EdgeOpticalFilter,
    ObjectiveLens,
)

nwbfile = NWBFile(
    session_description='session_description',
    identifier='identifier',
    session_start_time=datetime.datetime.now(datetime.timezone.utc)
)

# Create container objects
viral_vector = ViralVector(
    name="viral_vector",
    description="AAV viral vector for optogenetic stimulation",
    construct_name="AAV-EF1a-DIO-hChR2(H134R)-EYFP",
    manufacturer="Vector Manufacturer",
    titer_in_vg_per_ml=1.0e12,
)

viral_injection_coordinates = StereotacticPosition(
    name="viral_injection_coordinates",
    anatomical_target="Hippocampus",
    origin="bregma",
    orientation="RAS",
    x_in_mm=1.5,
    y_in_mm=2.0,
    z_in_mm=-3.0,
    pitch_in_deg=0.0,
    yaw_in_deg=0.0,
    roll_in_deg=0.0,
)

viral_vector_injection = ViralVectorInjection(
    name="viral_vector_injection",
    description="Viral vector injection for optogenetic stimulation",
    volume_in_uL=0.45,
    injection_date="1970-01-01T00:00:00+00:00",
    viral_injection_coordinates=viral_injection_coordinates,
    viral_vector=viral_vector,
)

indicator = Indicator(
    name="indicator",
    description="Green indicator",
    label="GCamp6f",
    viral_vector_injection=viral_vector_injection,
)

effector = Effector(
    name="effector",
    description="Excitatory opsin",
    label="hChR2",
    viral_vector_injection=viral_vector_injection,
)

fiber_insertion = StereotacticPosition(
    name="fiber_insertion",
    anatomical_target="Hippocampus",
    origin="bregma",
    orientation="RAS",
    x_in_mm=1.5,
    y_in_mm=2.0,
    z_in_mm=0.0,
    pitch_in_deg=10.0,
    yaw_in_deg=0.0,
    roll_in_deg=0.0,
)

lens_positioning = StereotacticPosition(
    name="lens_positioning",
    anatomical_target="Visual Cortex",
    origin="bregma",
    orientation="RAS",
    x_in_mm=-2.0,
    y_in_mm=1.5,
    z_in_mm=0.0,
    pitch_in_deg=0.0,
    yaw_in_deg=0.0,
    roll_in_deg=0.0,
)

# Create model objects
optical_fiber_model = OpticalFiberModel(
    name="optical_fiber_model",
    manufacturer="Fiber Manufacturer",
    model_number="OF-123",
    description="Optical fiber model for optogenetics",
    numerical_aperture=0.2,
    core_diameter_in_um=400.0,
    active_length_in_mm=2.0,
    ferrule_name="cFCF - ∅2.5mm Ceramic Ferrule",
    ferrule_model="SM-SC-CF-10-FM",
    ferrule_diameter_in_mm=2.5,
)
nwbfile.add_device(optical_fiber_model)

objective_lens_model = ObjectiveLensModel(
    name="objective_lens_model",
    manufacturer="Lens Manufacturer",
    model_number="OL-123",
    description="Objective lens model for imaging",
    numerical_aperture=0.39,
    magnification=40.0,
)
nwbfile.add_device(objective_lens_model)

excitation_source_model = ExcitationSourceModel(
    name="excitation_source_model",
    manufacturer="Laser Manufacturer",
    model_number="ES-123",
    description="Excitation source model for green indicator",
    source_type="laser",
    excitation_mode="one-photon",
    wavelength_range_in_nm=[400.0, 800.0],
)
nwbfile.add_device(excitation_source_model)

photodetector_model = PhotodetectorModel(
    name="photodetector_model",
    manufacturer="Detector Manufacturer",
    model_number="PD-123",
    description="Photodetector model for green emission",
    detector_type="PMT",
    wavelength_range_in_nm=[400.0, 800.0],
    gain=100.0,
    gain_unit="A/W",
)
nwbfile.add_device(photodetector_model)

dichroic_mirror_model = DichroicMirrorModel(
    name="dichroic_mirror_model",
    manufacturer="Mirror Manufacturer",
    model_number="DM-123",
    description="Dichroic mirror model for green indicator",
    cut_on_wavelength_in_nm=470.0,
    cut_off_wavelength_in_nm=500.0,
    reflection_band_in_nm=[460.0, 480.0],
    transmission_band_in_nm=[490.0, 520.0],
    angle_of_incidence_in_degrees=45.0,
)
nwbfile.add_device(dichroic_mirror_model)

band_optical_filter_model = BandOpticalFilterModel(
    name="band_optical_filter_model",
    manufacturer="Filter Manufacturer",
    model_number="BOF-123",
    description="Band optical filter model for green indicator",
    filter_type="Bandpass",
    center_wavelength_in_nm=480.0,
    bandwidth_in_nm=30.0,  # 480±15nm
)
nwbfile.add_device(band_optical_filter_model)

edge_optical_filter_model = EdgeOpticalFilterModel(
    name="edge_optical_filter_model",
    manufacturer="Filter Manufacturer",
    model_number="EOF-123",
    description="Edge optical filter model for green indicator",
    filter_type="Longpass",
    cut_wavelength_in_nm=585.0,
    slope_in_percent_cut_wavelength=1.0,
    slope_starting_transmission_in_percent=10.0,
    slope_ending_transmission_in_percent=80.0,
)
nwbfile.add_device(edge_optical_filter_model)

# Create device instances
optical_fiber = OpticalFiber(
    name="optical_fiber",
    description="Optical fiber for optogenetics",
    serial_number="OF-SN-123456",
    model=optical_fiber_model,
    fiber_insertion=fiber_insertion,
)

objective_lens = ObjectiveLens(
    name="objective_lens",
    description="Objective lens for imaging",
    serial_number="OL-SN-123456",
    model=objective_lens_model,
    lens_positioning=lens_positioning,
)

excitation_source = ExcitationSource(
    name="excitation_source",
    description="Excitation source for green indicator",
    serial_number="ES-SN-123456",
    model=excitation_source_model,
    power_in_W=0.7,
    intensity_in_W_per_m2=0.005,
    exposure_time_in_s=2.51e-13,
)

pulsed_excitation_source = PulsedExcitationSource(
    name="pulsed_excitation_source",
    description="Pulsed excitation source for red indicator",
    serial_number="PES-SN-123456",
    model=excitation_source_model,
    peak_power_in_W=0.7,
    peak_pulse_energy_in_J=0.7,
    intensity_in_W_per_m2=0.005,
    exposure_time_in_s=2.51e-13,
    pulse_rate_in_Hz=2.0e6,
)

photodetector = Photodetector(
    name="photodetector",
    description="Photodetector for green emission",
    serial_number="PD-SN-123456",
    model=photodetector_model,
)

dichroic_mirror = DichroicMirror(
    name="dichroic_mirror",
    description="Dichroic mirror for green indicator",
    serial_number="DM-SN-123456",
    model=dichroic_mirror_model,
)

band_optical_filter = BandOpticalFilter(
    name="band_optical_filter",
    description="Band optical filter for green indicator",
    serial_number="BOF-SN-123456",
    model=band_optical_filter_model,
)

edge_optical_filter = EdgeOpticalFilter(
    name="edge_optical_filter",
    description="Edge optical filter for green indicator",
    serial_number="EOF-SN-123456",
    model=edge_optical_filter_model,
)

# Add objects to the NWBFile
nwbfile.add_device(optical_fiber)
nwbfile.add_device(objective_lens)
nwbfile.add_device(excitation_source)
nwbfile.add_device(pulsed_excitation_source)
nwbfile.add_device(photodetector)
nwbfile.add_device(dichroic_mirror)
nwbfile.add_device(band_optical_filter)
nwbfile.add_device(edge_optical_filter)