ndx-optogenetics 0.2.0__py3-none-any.whl

ndx_optogenetics/__init__.py

@@ -0,0 +1,43 @@
+from importlib.resources import files
+import os
+from pynwb import load_namespaces, get_class
+
+# Get path to the namespace.yaml file with the expected location when installed not in editable mode
+__location_of_this_file = files(__name__)
+__spec_path = __location_of_this_file / "spec" / "ndx-optogenetics.namespace.yaml"
+
+# If that path does not exist, we are likely running in editable mode. Use the local path instead
+if not os.path.exists(__spec_path):
+    __spec_path = __location_of_this_file.parent.parent.parent / "spec" / "ndx-optogenetics.namespace.yaml"
+
+# Load the namespace
+load_namespaces(str(__spec_path))
+
+ExcitationSourceModel = get_class("ExcitationSourceModel", "ndx-optogenetics")
+ExcitationSource = get_class("ExcitationSource", "ndx-optogenetics")
+OpticalFiberModel = get_class("OpticalFiberModel", "ndx-optogenetics")
+OpticalFiber = get_class("OpticalFiber", "ndx-optogenetics")
+OpticalFiberLocationsTable = get_class("OpticalFiberLocationsTable", "ndx-optogenetics")
+OptogeneticVirus = get_class("OptogeneticVirus", "ndx-optogenetics")
+OptogeneticVirusInjection = get_class("OptogeneticVirusInjection", "ndx-optogenetics")
+OptogeneticViruses = get_class("OptogeneticViruses", "ndx-optogenetics")
+OptogeneticVirusInjections = get_class("OptogeneticVirusInjections", "ndx-optogenetics")
+OptogeneticExperimentMetadata = get_class("OptogeneticExperimentMetadata", "ndx-optogenetics")
+OptogeneticEpochsTable = get_class("OptogeneticEpochsTable", "ndx-optogenetics")
+
+__all__ = [
+    "ExcitationSourceModel",
+    "ExcitationSource",
+    "OpticalFiberModel",
+    "OpticalFiber",
+    "OpticalFiberLocationsTable",
+    "OptogeneticVirus",
+    "OptogeneticVirusInjection",
+    "OptogeneticViruses",
+    "OptogeneticVirusInjections",
+    "OptogeneticExperimentMetadata",
+    "OptogeneticEpochsTable",
+]
+
+# Remove these functions/modules from the package
+del load_namespaces, get_class, files, os, __location_of_this_file, __spec_path

ndx_optogenetics/spec/ndx-optogenetics.extensions.yaml

@@ -0,0 +1,329 @@
+groups:
+- neurodata_type_def: ExcitationSourceModel
+  neurodata_type_inc: Device
+  doc: Excitation source model. Currently there are no additional attributes.
+  attributes:
+  - name: illumination_type
+    dtype: text
+    doc: 'Type of illumination. Suggested values: LED, Gas Laser (e.g., Argon, Krypton),
+      Solid-State Laser (e.g., Diode, DPSS).'
+  - name: wavelength_range_in_nm
+    dtype: float
+    shape:
+    - 2
+    doc: Excitation wavelength range of the stimulation light in nm. For LEDs, this
+      is the center wavelength +/- half of the full width at half maximum (FWHM).
+      For lasers, this is the peak wavelength (use as both min and max).
+    required: false
+- neurodata_type_def: ExcitationSource
+  neurodata_type_inc: Device
+  doc: Excitation source device.
+  attributes:
+  - name: wavelength_in_nm
+    dtype: float
+    doc: Peak excitation wavelength of the stimulation light in nm.
+  - name: power_in_W
+    dtype: float
+    doc: Excitation power of the stimulation light in W.
+    required: false
+  - name: intensity_in_W_per_m2
+    dtype: float
+    doc: Intensity of the stimulation light in W/m^2.
+    required: false
+  links:
+  - name: model
+    target_type: ExcitationSourceModel
+    doc: The model of the excitation source.
+- neurodata_type_def: OpticalFiberModel
+  neurodata_type_inc: Device
+  doc: Optical fiber device model.
+  attributes:
+  - name: description
+    dtype: text
+    doc: Description of the optical fiber and ferrule equipment, including cleave
+      type or tapering.
+    required: false
+  - name: fiber_name
+    dtype: text
+    doc: Name of the optical fiber.
+  - name: fiber_model
+    dtype: text
+    doc: Model (or product ID) of the optical fiber.
+    required: false
+  - name: manufacturer
+    dtype: text
+    doc: Manufacturer of the optical fiber and ferrule.
+  - name: numerical_aperture
+    dtype: float
+    doc: Numerical aperture, e.g., 0.39 NA.
+  - name: core_diameter_in_um
+    dtype: float
+    doc: Cannula core diameter in um, e.g., 200.0 um.
+  - name: active_length_in_mm
+    dtype: float
+    doc: Active length in mm for a tapered fiber, e.g., Optogenix Lambda fiber. See
+      https://www.optogenix.com/lambda-fibers/ for details of one example.
+    required: false
+  - name: ferrule_name
+    dtype: text
+    doc: Product name of the ferrule.
+    required: false
+  - name: ferrule_model
+    dtype: text
+    doc: Model (or product ID) of the ferrule from the manufacturer.
+    required: false
+  - name: ferrule_diameter_in_mm
+    dtype: float
+    doc: Ferrule diameter in mm, e.g., 1.25 mm (LC) or 2.5 mm (FC).
+    required: false
+- neurodata_type_def: OpticalFiber
+  neurodata_type_inc: Device
+  doc: Optical fiber device.
+  links:
+  - name: model
+    target_type: OpticalFiberModel
+    doc: The model of the optical fiber.
+- neurodata_type_def: OpticalFiberLocationsTable
+  neurodata_type_inc: DynamicTable
+  default_name: optical_fiber_locations_table
+  doc: Information about the targeted stereotactic coordinates of the tip of the implanted
+    optical fiber and the angles of the optical fiber in the brain.
+  attributes:
+  - name: reference
+    dtype: text
+    doc: Zero point for `ap_in_mm`, `ml_in_mm`, and `dv_in_mm` coordinates, e.g.,
+      "Bregma at the cortical surface".
+  datasets:
+  - name: implanted_fiber_description
+    neurodata_type_inc: VectorData
+    dtype: text
+    doc: Description of the implanted optical fiber, e.g., 'Lambda fiber implanted
+      into right GPe'.
+  - name: location
+    neurodata_type_inc: VectorData
+    dtype: text
+    doc: Name of the targeted location of the tip of the optical fiber in the brain.
+  - name: hemisphere
+    neurodata_type_inc: VectorData
+    dtype: text
+    doc: The hemisphere ("left" or "right") of the targeted location of the tip of
+      the optical fiber. Should be consistent with `ml_in_mm` coordinate.
+  - name: ap_in_mm
+    neurodata_type_inc: VectorData
+    dtype: float
+    doc: Anteroposterior coordinate in mm of the targeted location of the tip of the
+      optical fiber (+ is anterior), with reference to `reference`.
+  - name: ml_in_mm
+    neurodata_type_inc: VectorData
+    dtype: float
+    doc: Mediolateral coordinate in mm of the targeted location of the tip of the
+      optical fiber (+ is right), with reference to `reference`.
+  - name: dv_in_mm
+    neurodata_type_inc: VectorData
+    dtype: float
+    doc: Dorsoventral coordinate in mm of the targeted location of the tip of the
+      optical fiber (+ is dorsal/above the brain), with reference to `reference`.
+  - name: pitch_in_deg
+    neurodata_type_inc: VectorData
+    dtype: float
+    doc: Pitch angle in degrees of the implanted optical fiber (rotation around left-right
+      axis, + is rotating the nose upward).
+    quantity: '?'
+  - name: yaw_in_deg
+    neurodata_type_inc: VectorData
+    dtype: float
+    doc: Yaw angle in degrees of the implanted optical fiber (rotation around dorsal-ventral
+      axis, + is rotating the nose rightward).
+    quantity: '?'
+  - name: roll_in_deg
+    neurodata_type_inc: VectorData
+    dtype: float
+    doc: Roll angle in degrees of the implanted optical fiber (rotation around anterior-posterior
+      axis, + is rotating the right side downward).
+    quantity: '?'
+  - name: stereotactic_rotation_in_deg
+    neurodata_type_inc: VectorData
+    dtype: float
+    doc: TODO
+    quantity: '?'
+  - name: stereotactic_tilt_in_deg
+    neurodata_type_inc: VectorData
+    dtype: float
+    doc: TODO
+    quantity: '?'
+  - name: excitation_source
+    neurodata_type_inc: VectorData
+    dtype:
+      target_type: ExcitationSource
+      reftype: object
+    doc: The excitation source device connected to the optical fiber.
+    quantity: '?'
+  - name: optical_fiber
+    neurodata_type_inc: VectorData
+    dtype:
+      target_type: OpticalFiber
+      reftype: object
+    doc: The optical fiber device.
+- neurodata_type_def: OptogeneticVirus
+  neurodata_type_inc: NWBContainer
+  doc: Metadata about the optogenetic virus.
+  attributes:
+  - name: construct_name
+    dtype: text
+    doc: Name of the virus construct/vector, e.g., "AAV-EF1a-DIO-hChR2(H134R)-EYFP".
+  - name: description
+    dtype: text
+    doc: Description of the optogenetic virus.
+    required: false
+  - name: manufacturer
+    dtype: text
+    doc: Manufacturer of the optogenetic virus.
+  - name: titer_in_vg_per_ml
+    dtype: float
+    doc: Titer of the optogenetic virus, in vg/ml, e.g., 1x10^12 vg/ml.
+- neurodata_type_def: OptogeneticVirusInjection
+  neurodata_type_inc: NWBContainer
+  doc: Information about the injection of a virus for optogenetic experiments. The
+    name should be the virus name, e.g., "AAV-EF1a-DIO-hChR2(H134R)-EYFP". Use two
+    OptogeneticVirusInjection objects for a bilateral injection, one per hemisphere.
+  attributes:
+  - name: description
+    dtype: text
+    doc: Description of the optogenetic virus injection.
+    required: false
+  - name: location
+    dtype: text
+    doc: Name of the targeted location of the optogenetic virus injection.
+  - name: hemisphere
+    dtype: text
+    doc: The hemisphere ("left" or "right") of the targeted location of the optogenetic
+      virus injection. Should be consistent with `ml_in_mm` coordinate.
+  - name: reference
+    dtype: text
+    doc: Reference point for `ap_in_mm`, `ml_in_mm`, and `dv_in_mm` coordinates, e.g.,
+      "Bregma at the cortical surface".
+  - name: ap_in_mm
+    dtype: float
+    doc: Anteroposterior coordinate in mm of the optogenetic virus injection site
+      (+ is anterior), with reference to `reference`.
+  - name: ml_in_mm
+    dtype: float
+    doc: Mediolateral coordinate in mm of the optogenetic virus injection site (+
+      is right), with reference to `reference`.
+  - name: dv_in_mm
+    dtype: float
+    doc: Dorsoventral coordinate in mm of the optogenetic virus injection site (+
+      is dorsal/above the brain), with reference to `reference`.
+  - name: pitch_in_deg
+    dtype: float
+    doc: Pitch angle in degrees of the optogenetic virus injection (rotation around
+      left-right axis, + is rotating the nose upward).
+    required: false
+  - name: yaw_in_deg
+    dtype: float
+    doc: Yaw angle in degrees of the optogenetic virus injection (rotation around
+      dorsal-ventral axis, + is rotating the nose rightward).
+    required: false
+  - name: roll_in_deg
+    dtype: float
+    doc: Roll angle in degrees of the optogenetic virus injection (rotation around
+      anterior-posterior axis, + is rotating the right side downward).
+    required: false
+  - name: stereotactic_rotation_in_deg
+    dtype: float
+    doc: TODO
+    required: false
+  - name: stereotactic_tilt_in_deg
+    dtype: float
+    doc: TODO
+    required: false
+  - name: volume_in_uL
+    dtype: float
+    doc: Volume of injection, in uL., e.g., 0.45 uL (450 nL)
+  - name: injection_date
+    dtype: isodatetime
+    doc: Date of injection.
+    required: false
+  links:
+  - name: virus
+    target_type: OptogeneticVirus
+    doc: Link to OptogeneticVirus object with metadata about the name, manufacturer,
+      and titer.
+- neurodata_type_def: OptogeneticViruses
+  neurodata_type_inc: NWBContainer
+  name: optogenetic_viruses
+  doc: Group containing one or more OptogeneticVirus objects, to be used within an
+    OptogeneticExperimentMetadata object.
+  groups:
+  - neurodata_type_inc: OptogeneticVirus
+    doc: OptogeneticVirus object(s).
+    quantity: +
+- neurodata_type_def: OptogeneticVirusInjections
+  neurodata_type_inc: NWBContainer
+  name: optogenetic_virus_injections
+  doc: Group containing one or more OptogeneticVirusInjection objects, to be used
+    within an OptogeneticExperimentMetadata object.
+  groups:
+  - neurodata_type_inc: OptogeneticVirusInjection
+    doc: OptogeneticVirusInjection object(s).
+    quantity: +
+- neurodata_type_def: OptogeneticExperimentMetadata
+  neurodata_type_inc: LabMetaData
+  name: optogenetic_experiment_metadata
+  doc: General metadata about the optogenetic stimulation.
+  attributes:
+  - name: stimulation_software
+    dtype: text
+    doc: Name of the software used to deliver optogenetic stimulation.
+  groups:
+  - name: optical_fiber_locations_table
+    neurodata_type_inc: OpticalFiberLocationsTable
+    doc: Information about the targeted stereotactic coordinates of the tip of the
+      implanted optical fiber and the angles of the optical fiber in the brain.
+  - name: optogenetic_viruses
+    neurodata_type_inc: OptogeneticViruses
+    doc: Group containing of one or more OptogeneticVirus objects.
+  - name: optogenetic_virus_injections
+    neurodata_type_inc: OptogeneticVirusInjections
+    doc: Group containing one or more OptogeneticVirusInjection objects.
+- neurodata_type_def: OptogeneticEpochsTable
+  neurodata_type_inc: TimeIntervals
+  doc: General metadata about the optogenetic stimulation that may change per epoch.
+    Some epochs have no stimulation and are used as control epochs. If the stimulation
+    is on, then the epoch is a stimulation.
+  datasets:
+  - name: stimulation_on
+    neurodata_type_inc: VectorData
+    dtype: bool
+    doc: Whether optogenetic stimulation was used at any time during this epoch. If
+      False, then all other metadata values should be 0.
+  - name: pulse_length_in_ms
+    neurodata_type_inc: VectorData
+    dtype: float
+    doc: Duration of one pulse, in ms. Use NaN if stimulation was off.
+  - name: period_in_ms
+    neurodata_type_inc: VectorData
+    dtype: float
+    doc: Duration between the starts of two pulses, in ms. Use NaN if stimulation
+      was off.Note that the interpulse interval = `period_ms` - `pulse_length_ms`
+  - name: number_pulses_per_pulse_train
+    neurodata_type_inc: VectorData
+    dtype: int
+    doc: Number of pulses in one pulse train. After this number of pulses, no more
+      stimulation occurs until the next train begins (see `intertrain_interval_ms`).
+      Use -1 if stimulation was off.
+  - name: number_trains
+    neurodata_type_inc: VectorData
+    dtype: int
+    doc: Number of trains per stimulus. After this number of trains, no more stimulation
+      occurs until stimulation is re-triggered. Use -1 if stimulation was off.
+  - name: intertrain_interval_in_ms
+    neurodata_type_inc: VectorData
+    dtype: float
+    doc: Duration between the starts of two consecutive pulse trains, in ms. Determines
+      the frequency of stimulation. Use NaN if stimulation was off.
+  - name: power_in_mW
+    neurodata_type_inc: VectorData
+    dtype: float
+    doc: Constant power of excitation source throughout the epoch, in mW, e.g., 77
+      mW.

ndx_optogenetics/spec/ndx-optogenetics.namespace.yaml

@@ -0,0 +1,15 @@
+namespaces:
+- author:
+  - Ryan Ly
+  - Horea Christian
+  - Ben Dichter
+  contact:
+  - rly@lbl.gov
+  - uni@chymera.eu
+  - ben.dichter@catalystneuro.com
+  doc: NWB extension to improve support for optogenetics data and metadata
+  name: ndx-optogenetics
+  schema:
+  - namespace: core
+  - source: ndx-optogenetics.extensions.yaml
+  version: 0.2.0

ndx_optogenetics-0.2.0.dist-info/METADATA

@@ -0,0 +1,453 @@
+Metadata-Version: 2.4
+Name: ndx-optogenetics
+Version: 0.2.0
+Summary: NWB extension to enhance support for optogenetics data and metadata in NWB
+Project-URL: Homepage, https://github.com/rly/ndx-optogenetics
+Project-URL: Bug Tracker, https://github.com/rly/ndx-optogenetics/issues
+Project-URL: Discussions, https://github.com/rly/ndx-optogenetics/discussions
+Project-URL: Changelog, https://github.com/rly/ndx-optogenetics/blob/main/CHANGELOG.md
+Author-email: Ryan Ly <rly@lbl.gov>, Horea Christian <rly@lbl.gov>, Ben Dichter <ben.dichter@catalystneuro.com>
+License-Expression: BSD-3-Clause
+License-File: LICENSE.txt
+Keywords: NWB,NeurodataWithoutBorders,ndx-extension,nwb-extension
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.9
+Requires-Dist: hdmf>=3.14.1
+Requires-Dist: pynwb>=2.8.0
+Provides-Extra: dev
+Requires-Dist: black>=24.4.2; extra == 'dev'
+Requires-Dist: codespell>=2.3.0; extra == 'dev'
+Requires-Dist: coverage>=7.5.4; extra == 'dev'
+Requires-Dist: hdmf-docutils>=0.4.7; extra == 'dev'
+Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest-subtests>=0.12.1; extra == 'dev'
+Requires-Dist: pytest>=8.2.2; extra == 'dev'
+Requires-Dist: python-dateutil>=2.8.2; extra == 'dev'
+Requires-Dist: ruff>=0.4.10; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: hdmf-docutils>=0.4.7; extra == 'docs'
+Provides-Extra: min-reqs
+Requires-Dist: hdmf==3.14.1; extra == 'min-reqs'
+Requires-Dist: pynwb==2.8.0; extra == 'min-reqs'
+Provides-Extra: test
+Requires-Dist: coverage>=7.5.4; extra == 'test'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
+Requires-Dist: pytest-subtests>=0.12.1; extra == 'test'
+Requires-Dist: pytest>=8.2.2; extra == 'test'
+Requires-Dist: python-dateutil>=2.8.2; extra == 'test'
+Description-Content-Type: text/markdown
+
+# ndx-optogenetics Extension for NWB
+
+NWB extension to enhance support for optogenetics data and metadata in NWB. This extension provides neurodata types for documenting optogenetic experiments, including excitation sources, optical fibers, virus injections, and stimulation parameters.
+
+## Installation
+
+```bash
+pip install ndx-optogenetics
+```
+
+## Neurodata Types
+
+### Device Types
+
+#### ExcitationSourceModel
+A model of an excitation source device (e.g., laser, LED) with attributes:
+- `illumination_type`: Type of illumination (e.g., LED, Gas Laser, Solid-State Laser)
+- `wavelength_range_in_nm`: Excitation wavelength range in nm [min, max]
+
+#### ExcitationSource
+A specific excitation source device instance with attributes:
+- `wavelength_in_nm`: Peak excitation wavelength
+- `power_in_W`: Excitation power in Watts
+- `intensity_in_W_per_m2`: Light intensity in W/m²
+- Links to its corresponding `ExcitationSourceModel`
+
+#### OpticalFiberModel
+A model of an optical fiber with attributes for the fiber and ferrule specifications:
+- `fiber_name`: Name of the optical fiber
+- `fiber_model`: Model/product ID
+- `manufacturer`: Manufacturer name
+- `numerical_aperture`: Numerical aperture value
+- `core_diameter_in_um`: Core diameter in micrometers
+- `active_length_in_mm`: Active length for tapered fibers
+- Various ferrule specifications (name, model, diameter)
+
+#### OpticalFiber
+A specific optical fiber device instance that links to its corresponding `OpticalFiberModel`
+
+### Experimental Metadata Types
+
+#### OptogeneticVirus
+Metadata about an optogenetic virus with attributes:
+- `construct_name`: Name of the virus construct/vector
+- `manufacturer`: Virus manufacturer
+- `titer_in_vg_per_ml`: Titer in viral genomes per mL
+
+#### OptogeneticVirusInjection
+Information about a virus injection with attributes:
+- Location coordinates (AP, ML, DV) relative to a reference point
+- Injection angles (pitch, yaw, roll)
+- `volume_in_uL`: Injection volume
+- `injection_date`: Date of injection
+- Links to the corresponding `OptogeneticVirus`
+
+#### OpticalFiberLocationsTable
+A dynamic table for documenting implanted optical fiber locations with columns for:
+- Stereotactic coordinates (AP, ML, DV)
+- Implant angles (pitch, yaw, roll)
+- Links to the corresponding `ExcitationSource` and `OpticalFiber` devices
+
+Because this type extends the `DynamicTable` class, you can add new columns to it without having to define a new type. You can also annotate a row of it with anatomical localization information using the [ndx-anatomical-localization](https://github.com/bendichter/ndx-anatomical-localization) extension.
+
+#### OptogeneticEpochsTable
+A dynamic table for documenting stimulation parameters per epoch:
+- `stimulation_on`: Whether stimulation was active
+- `pulse_length_in_ms`: Duration of each pulse
+- `period_in_ms`: Time between pulse starts
+- `number_pulses_per_pulse_train`: Number of pulses per train
+- `number_trains`: Number of trains per stimulus
+- `intertrain_interval_in_ms`: Time between train starts
+- `power_in_mW`: Stimulation power
+
+Because this type extends the `DynamicTable` class, you can add new columns to it without having to define a new type.
+
+#### OptogeneticExperimentMetadata
+Container for all optogenetics-related metadata including:
+- `OpticalFiberLocationsTable`
+- Collection of `OptogeneticVirus` objects
+- Collection of `OptogeneticVirusInjection` objects
+- `stimulation_software`: Name of software used for stimulation
+
+You can define extensions to this ndx-optogenetics extension to store additional metadata in a structured
+way. For example, the upcoming update to the
+[ndx-franklab-novela extension](https://github.com/LorenFrankLab/ndx-franklab-novela) 
+defines a `FrankLabOptogeneticEpochsTable` that extends the `OptogeneticEpochsTable` defined here to store Frank Lab-specific optogenetic stimulation parameters for each epoch.
+
+## Entity Relationship Diagram
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#ffffff', "primaryBorderColor': '#144E73', 'lineColor': '#D96F32'}}}%%
+classDiagram
+    direction LR
+
+    class OptogeneticEpochsTable {
+        <<TimeIntervals>>
+        --------------------------------------
+        attributes
+        --------------------------------------
+        name : str
+        description : str
+
+        --------------------------------------
+        columns
+        --------------------------------------
+        start_time : VectorData[float]
+        stop_time : VectorData[float]
+        stimulation_on : VectorData[bool]
+        pulse_length_in_ms : VectorData[float]
+        period_in_ms : VectorData[float]
+        number_pulses_per_pulse_train : VectorData[int]
+        number_trains : VectorData[int]
+        intertrain_interval_in_ms : VectorData[float]
+        power_in_mW : VectorData[float]
+    }
+
+    class OptogeneticExperimentMetadata {
+        <<LabMetaData>>
+        --------------------------------------
+        attributes
+        --------------------------------------
+        optical_fiber_locations_table : OpticalFiberLocationsTable
+        optogenetic_viruses : OptogeneticViruses
+        optogenetic_virus_injections : OptogeneticVirusInjections
+        stimulation_software : str
+    }
+
+    class OpticalFiberLocationsTable {
+        <<DynamicTable>>
+        --------------------------------------
+        attributes
+        --------------------------------------
+        description : str
+        reference : str
+
+        --------------------------------------
+        columns
+        --------------------------------------
+        implanted_fiber_description : VectorData[str]
+        location : VectorData[str]
+        hemisphere : VectorData[str]
+        ap_in_mm : VectorData[float]
+        ml_in_mm : VectorData[float]
+        dv_in_mm : VectorData[float]
+        roll_in_deg : VectorData[float]
+        pitch_in_deg : VectorData[float]
+        yaw_in_deg : VectorData[float]
+        stereotactic_rotation_in_deg : VectorData[float]
+        stereotactic_tilt_in_deg : VectorData[float]
+        excitation_source : VectorData[ExcitationSource]
+        optical_fiber : VectorData[OpticalFiber]
+    }
+
+    namespace Devices {
+        class ExcitationSourceModel {
+            <<Device>>
+            --------------------------------------
+            attributes
+            --------------------------------------
+            illumination_type : str
+            wavelength_range_in_nm : float[2]
+        }
+
+        class ExcitationSource {
+            <<Device>>
+            --------------------------------------
+            attributes
+            --------------------------------------
+            wavelength_in_nm : float
+            power_in_W : float
+            intensity_in_W_per_m2 : float
+            model : ExcitationSourceModel
+        }
+
+        class OpticalFiberModel {
+            <<Device>>
+            --------------------------------------
+            attributes
+            --------------------------------------
+            fiber_name : str
+            fiber_model : str
+            numerical_aperture : float
+            core_diameter_in_um : float
+            active_length_in_mm : float
+            ferrule_name : str
+            ferrule_model : str
+            ferrule_diameter_in_mm : float
+        }
+
+        class OpticalFiber {
+            <<Device>>
+            --------------------------------------
+            attributes
+            --------------------------------------
+            model : OpticalFiberModel
+        }
+    }
+
+    namespace Virus {
+        class OptogeneticVirus {
+            <<NWBContainer>>
+            --------------------------------------
+            attributes
+            --------------------------------------
+            construct_name : str
+            manufacturer : str
+            titer_in_vg_per_ml : float
+        }
+
+        class OptogeneticVirusInjection {
+            <<NWBContainer>>
+            --------------------------------------
+            attributes
+            --------------------------------------
+            location : str
+            hemisphere : str
+            ap_in_mm : float
+            ml_in_mm : float
+            dv_in_mm : float
+            roll_in_deg : float
+            pitch_in_deg : float
+            yaw_in_deg : float
+            stereotactic_rotation_in_deg : float
+            stereotactic_tilt_in_deg : float
+            reference : str
+            volume_in_uL : float
+            virus : OptogeneticVirus
+        }
+
+        class OptogeneticViruses {
+            <<NWBContainer>>
+            --------------------------------------
+            contains
+            --------------------------------------
+            optogenetic_virus : OptogeneticVirus[]
+        }
+
+        class OptogeneticVirusInjections {
+            <<NWBContainer>>
+            --------------------------------------
+            contains
+            --------------------------------------
+            optogenetic_virus_injections : OptogeneticVirusInjection[]
+        }
+    }
+
+    OptogeneticExperimentMetadata *--> OpticalFiberLocationsTable
+    OptogeneticExperimentMetadata *--> OptogeneticViruses
+    OptogeneticExperimentMetadata *--> OptogeneticVirusInjections
+    OpticalFiberLocationsTable ..> ExcitationSource
+    OpticalFiberLocationsTable ..> OpticalFiber
+    ExcitationSource *..> ExcitationSourceModel
+    OpticalFiber *..> OpticalFiberModel
+    OptogeneticVirusInjection *..> OptogeneticVirus
+    OptogeneticViruses *--> OptogeneticVirus
+    OptogeneticVirusInjections *--> OptogeneticVirusInjection
+```
+
+## Usage Example
+
+```python
+from datetime import datetime, timezone
+from pynwb import NWBFile, NWBHDF5IO
+from ndx_optogenetics import (
+    ExcitationSourceModel,
+    ExcitationSource,
+    OpticalFiberModel,
+    OpticalFiber,
+    OpticalFiberLocationsTable,
+    OptogeneticVirus,
+    OptogeneticVirusInjection,
+    OptogeneticViruses,
+    OptogeneticVirusInjections,
+    OptogeneticExperimentMetadata,
+    OptogeneticEpochsTable,
+)
+
+# Initialize NWB file
+nwbfile = NWBFile(
+    session_description="session_description",
+    identifier="identifier",
+    session_start_time=datetime.now(timezone.utc),
+)
+
+# Create and add excitation source devices
+excitation_source_model = ExcitationSourceModel(
+    name="Omicron LuxX+ 488-100 Model",
+    description="Laser for optogenetic stimulation.",
+    manufacturer="Omicron",
+    illumination_type="laser",
+    wavelength_range_in_nm=[488.0, 488.0],
+)
+excitation_source = ExcitationSource(
+    name="Omicron LuxX+ 488-100",
+    model=excitation_source_model,
+    wavelength_in_nm=488.0,
+    power_in_W=0.077,
+    intensity_in_W_per_m2=1.0e10,
+)
+nwbfile.add_device(excitation_source_model)
+nwbfile.add_device(excitation_source)
+
+# Create and add optical fiber devices
+optical_fiber_model = OpticalFiberModel(
+    name="Lambda Model",
+    description="Lambda fiber (tapered fiber) from Optogenix.",
+    fiber_name="Lambda",
+    fiber_model="lambda_b5",
+    manufacturer="Optogenix",
+    numerical_aperture=0.39,
+    core_diameter_in_um=200.0,
+    active_length_in_mm=2.0,
+    ferrule_name="cFCF - ∅2.5mm Ceramic Ferrule",
+    ferrule_diameter_in_mm=2.5,
+)
+optical_fiber = OpticalFiber(
+    name="Lambda",
+    model=optical_fiber_model,
+)
+nwbfile.add_device(optical_fiber_model)
+nwbfile.add_device(optical_fiber)
+
+# Create optical fiber locations table
+optical_fiber_locations_table = OpticalFiberLocationsTable(
+    description="Information about implanted optical fiber locations",
+    reference="Bregma at the cortical surface",
+)
+optical_fiber_locations_table.add_row(
+    implanted_fiber_description="Lambda fiber implanted into right GPe.",
+    location="GPe",
+    hemisphere="right",
+    ap_in_mm=-1.5,
+    ml_in_mm=3.2,
+    dv_in_mm=-5.8,
+    roll_in_deg=0.0,
+    pitch_in_deg=0.0,
+    yaw_in_deg=0.0,
+    excitation_source=excitation_source,
+    optical_fiber=optical_fiber,
+)
+
+# Create virus and injection metadata
+virus = OptogeneticVirus(
+    name="AAV-EF1a-DIO-hChR2(H134R)-EYFP",
+    construct_name="AAV-EF1a-DIO-hChR2(H134R)-EYFP",
+    description="Excitatory optogenetic construct for ChR2-EYFP expression",
+    manufacturer="UNC Vector Core",
+    titer_in_vg_per_ml=1.0e12,
+)
+optogenetic_viruses = OptogeneticViruses(optogenetic_virus=[virus])
+
+virus_injection = OptogeneticVirusInjection(
+    name="AAV-EF1a-DIO-hChR2(H134R)-EYFP Injection",
+    description="AAV-EF1a-DIO-hChR2(H134R)-EYFP injection into GPe.",
+    hemisphere="right",
+    location="GPe",
+    ap_in_mm=-1.5,
+    ml_in_mm=3.2,
+    dv_in_mm=-6.0,
+    roll_in_deg=0.0,
+    pitch_in_deg=0.0,
+    yaw_in_deg=0.0,
+    reference="Bregma at the cortical surface",
+    virus=virus,
+    volume_in_uL=0.45,
+)
+optogenetic_virus_injections = OptogeneticVirusInjections(
+    optogenetic_virus_injections=[virus_injection]
+)
+
+# Create experiment metadata container
+optogenetic_experiment_metadata = OptogeneticExperimentMetadata(
+    optical_fiber_locations_table=optical_fiber_locations_table,
+    optogenetic_viruses=optogenetic_viruses,
+    optogenetic_virus_injections=optogenetic_virus_injections,
+    stimulation_software="FSGUI 2.0",
+)
+nwbfile.add_lab_meta_data(optogenetic_experiment_metadata)
+
+# Create stimulation epochs table
+opto_epochs_table = OptogeneticEpochsTable(
+    name="optogenetic_epochs",
+    description="Metadata about optogenetic stimulation parameters per epoch",
+)
+opto_epochs_table.add_row(
+    start_time=0.0,
+    stop_time=100.0,
+    stimulation_on=True,
+    pulse_length_in_ms=40.0,
+    period_in_ms=250.0,
+    number_pulses_per_pulse_train=100,
+    number_trains=1,
+    intertrain_interval_in_ms=0.0,
+    power_in_mW=77.0,
+)
+nwbfile.add_time_intervals(opto_epochs_table)
+
+# Write the file
+with NWBHDF5IO('example.nwb', mode='w') as io:
+    io.write(nwbfile)
+```
+
+---
+This extension was created using [ndx-template](https://github.com/nwb-extensions/ndx-template).

ndx_optogenetics-0.2.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+ndx_optogenetics/spec/ndx-optogenetics.extensions.yaml,sha256=qfDixwqMtT2FBhwgR6cExyxUbPoPVnV98WQT-f1bBks,12471
+ndx_optogenetics/spec/ndx-optogenetics.namespace.yaml,sha256=vi1bME85P65sG9JYnvL0bh1T_RQaaB8Lt-Uo0rMPS8s,342
+ndx_optogenetics/__init__.py,sha256=tt6-tpkLSWdfzhyshJ8fEa0ZOR3HtquF2BF4AAvaJgE,1945
+ndx_optogenetics-0.2.0.dist-info/METADATA,sha256=_DGF0BjhcvnQ1yBiPledZYTdZVz4wlIJXVgjBJwBCfg,16109
+ndx_optogenetics-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+ndx_optogenetics-0.2.0.dist-info/licenses/LICENSE.txt,sha256=36_TjzPOi-sCdEQAgSITjymt6O9NEs-ia7QoAnp_IaA,1545
+ndx_optogenetics-0.2.0.dist-info/RECORD,,

ndx_optogenetics-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ndx_optogenetics-0.2.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Ryan Ly, Horea Christian, Ben Dichter
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.