Getting Started

Prerequisites

Before installing ndx-microscopy, ensure you have:

  • Python 3.7 or later

  • PyNWB installed

  • ndx-ophys-devices extension installed (required for optical components)

Installation

Python Installation

The ndx-microscopy extension can be installed via pip:

pip install ndx-microscopy

This will automatically install all required dependencies.

Basic Concepts

The ndx-microscopy extension provides a standardized way to store and organize microscopy data in the NWB format. Here are the key components:

Device Components

  • MicroscopeModel: Defines the model of a microscope

  • Microscope: The primary device instance used for imaging - Includes technique specification (e.g., scan mirrors, light sheet, widefield)

  • MicroscopyRig: Organizes all optical components in a single container

  • Other optical components (from ndx-ophys-devices):

    • ExcitationSource (lasers, LEDs)

    • OpticalFilter (bandpass, edge filters)

    • Photodetector (PMTs, cameras)

    • DichroicMirror

    • Indicator (fluorescent proteins, dyes)

Illumination Patterns

  • IlluminationPattern: Base class for describing how the sample is illuminated

  • LineScan: For line scanning methods (common in two-photon microscopy)

  • PlaneAcquisition: For whole plane acquisition (common in light sheet and one-photon)

  • RandomAccessScan: For targeted, high-speed imaging of specific regions

Imaging Spaces

  • PlanarImagingSpace: For 2D imaging (single plane)

  • VolumetricImagingSpace: For 3D imaging (z-stacks)

  • Includes physical coordinates, grid spacing, and reference frames

  • Requires an illumination pattern to specify how the space was scanned

Data Series

  • PlanarMicroscopySeries: 2D time series data

  • VolumetricMicroscopySeries: 3D time series data

  • MultiPlaneMicroscopyContainer: Multiple imaging planes

  • MultiChannelMicroscopyContainer: Multiple channel imaging data

Quick Start Example

Here’s a minimal example showing how to create a basic microscopy dataset:

from datetime import datetime
from uuid import uuid4
from pynwb import NWBFile
from ndx_microscopy import (
    MicroscopeModel,
    Microscope,
    MicroscopyRig,
    PlanarImagingSpace,
    PlanarMicroscopySeries,
    LineScan
)
from ndx_ophys_devices import (
    ExcitationSourceModel,
    ExcitationSource,
    BandOpticalFilterModel,
    BandOpticalFilter,
    DichroicMirrorModel,
    DichroicMirror,
    PhotodetectorModel,
    Photodetector,
    Indicator
)
import numpy as np

# Create NWB file
nwbfile = NWBFile(
    session_description='Example microscopy session',
    identifier=str(uuid4()),
    session_start_time=datetime.now()
)

# Set up microscope model
microscope_model = MicroscopeModel(
    name='2p-model',
    description='Two-photon microscope model',
    model_number='2p-001',
    manufacturer='ImagingTech'
)
nwbfile.add_device(microscope_model)

# Set up microscope with technique
microscope = Microscope(
    name='2p-scope',
    description='Custom two-photon microscope',
    serial_number='2p-serial-001',
    model=microscope_model,
    technique='mirror scanning'  # Specify the technique used
)
nwbfile.add_device(microscope)

# Create indicator
indicator = Indicator(
    name='gcamp6f',
    label='GCaMP6f',
    description='Calcium indicator'
)

# Create example optical component models
excitation_source_model = ExcitationSourceModel(
    name="excitation_source_model",
    manufacturer="Laser Manufacturer",
    model_number="ES-123",
    description="Excitation source model",
    source_type="laser",
    excitation_mode="two-photon",
    wavelength_range_in_nm=[800.0, 1000.0]
)
nwbfile.add_device(excitation_source_model)

excitation_filter_model = BandOpticalFilterModel(
    name="excitation_filter_model",
    filter_type="Bandpass",
    manufacturer="Semrock",
    model_number="FF01-920/80",
    center_wavelength_in_nm=920.0,
    bandwidth_in_nm=80.0
)
nwbfile.add_device(excitation_filter_model)

dichroic_mirror_model = DichroicMirrorModel(
    name="dichroic_mirror_model",
    manufacturer="Semrock",
    model_number="FF757-Di01",
    cut_on_wavelength_in_nm=757.0
)
nwbfile.add_device(dichroic_mirror_model)

photodetector_model = PhotodetectorModel(
    name="photodetector_model",
    detector_type="PMT",
    manufacturer="Hamamatsu",
    model_number="R6357",
    gain=70.0,
    gain_unit="dB"
)
nwbfile.add_device(photodetector_model)

emission_filter_model = BandOpticalFilterModel(
    name="emission_filter_model",
    filter_type="Bandpass",
    manufacturer="Semrock",
    model_number="FF01-510/84",
    center_wavelength_in_nm=510.0,
    bandwidth_in_nm=84.0
)
nwbfile.add_device(emission_filter_model)

# Create optical component instances
laser = ExcitationSource(
    name='laser',
    description='Two-photon excitation laser',
    serial_number="ES-SN-123456",
    model=excitation_source_model,
    intensity_in_W_per_m2=1000.0,
    exposure_time_in_s=0.001
)
nwbfile.add_device(laser)

ex_filter = BandOpticalFilter(
    name='ex_filter',
    description='Excitation filter',
    serial_number="EF-SN-123456",
    model=excitation_filter_model
)
nwbfile.add_device(ex_filter)

dichroic = DichroicMirror(
    name='dichroic',
    description='Dichroic mirror',
    serial_number="DM-SN-123456",
    model=dichroic_mirror_model
)
nwbfile.add_device(dichroic)

detector = Photodetector(
    name='detector',
    description='PMT detector',
    serial_number="PD-SN-123456",
    model=photodetector_model
)
nwbfile.add_device(detector)

em_filter = BandOpticalFilter(
    name='em_filter',
    description='Emission filter',
    serial_number="EF-SN-123456",
    model=emission_filter_model
)
nwbfile.add_device(em_filter)

# Create microscopy rig
microscopy_rig = MicroscopyRig(
    name='2p_rig',
    description='Two-photon microscopy rig',
    microscope=microscope,
    excitation_source=laser,
    excitation_filter=ex_filter,
    dichroic_mirror=dichroic,
    photodetector=detector,
    emission_filter=em_filter
)

# Define illumination pattern
line_scan = LineScan(
    name='line_scanning',
    description='Line scanning two-photon microscopy',
    scan_direction='horizontal',
    line_rate_in_Hz=1000.0,
    dwell_time_in_s=1.0e-6
)

# Define imaging space with illumination pattern
planar_imaging_space = PlanarImagingSpace(
    name='cortex_plane',
    description='Layer 2/3 of visual cortex',
    pixel_size_in_um=[1.0, 1.0],
    dimensions_in_pixels=[512, 512],
    origin_coordinates=[-1.2, -0.6, -2.0],
    illumination_pattern=line_scan  # Include the illumination pattern
)

# Create example imaging data
data = np.random.rand(100, 512, 512)  # 100 frames, 512x512 pixels

# Create imaging series
microscopy_series = PlanarMicroscopySeries(
    name='imaging_data',
    microscopy_rig=microscopy_rig,
    planar_imaging_space=planar_imaging_space,
    data=data,
    unit='a.u.',
    rate=30.0,
    starting_time=0.0,
)
nwbfile.add_acquisition(microscopy_series)

# Save file
from pynwb import NWBHDF5IO
with NWBHDF5IO('microscopy_session.nwb', 'w') as io:
    io.write(nwbfile)

Next Steps

After getting familiar with the basics:

  1. Check out the Examples section for more detailed examples including: - Volumetric imaging - Multi-plane imaging - ROI segmentation and response series

  2. Read the User Guide for best practices and detailed workflows

  3. Review the API documentation for complete reference

  4. See the format section to understand the underlying data organization