Skip to main content

Fiber Photometry System Configuration

CI PyPI - Version License ruff uv

For FIP photometry data acquisition and hardware control.

Overview

The FIP (Frame-projected Independent Photometry) system is a low-cost, scalable photometry setup designed for chronic recording of optical signals from behaving mice during daily training. The system is based on a modified design of Frame-projected Independent Photometry (Kim et al., 2016), using inexpensive, commercially available, off-the-shelf components.

FIP System Light Path

For more information, see the AIND Fiber Photometry Platform Page and the following protocols:

Wavelength Information

The table below summarizes the photometry system's optical configuration, showing the relationship between emission channels and their corresponding excitation sources.

Excitation Emission
Name Wavelength (nm) Led Name name Wavelength (nm) Detector Name
Yellow 565 565 nm LED Red ~590 (peak) Red CMOS
Blue 470 470 nm LED Green ~510 (peak) Green CMOS
UV 415 415 nm LED Isosbestic 490-540 (passband) Green CMOS

Signal Detection

  • Green Channel: Primarily used for green GFP based indicators
  • Red Channel: Primarily used for RFP-based indicators (e.g., RdLight)
  • Isosbestic Channel: Used as a control measurement; shares same emission path as green but with different excitation

The system uses dedicated CMOS cameras for the red and green emissions, with the isosbestic signal being captured by the green camera under different excitation conditions.

Temporal Multiplexing

The system employs temporal multiplexing to acquire signals from multiple fluorescent indicators through the same optical fiber. This is achieved by rapidly cycling through different excitation wavelengths while synchronizing camera acquisitions:

            --->|              |<--- period = 16.67 ms
Blue LED(470)   ████░░░░░░░░░░░████░░░░░░░░░░░████░░░░░░░░░░░████░░░░░░░░░░░████░░░░░░░░░░░

UV LED (415)    ░░░░░████░░░░░░░░░░░████░░░░░░░░░░░████░░░░░░░░░░░████░░░░░░░░░░░████░░░░░░

Yellow LED (560)░░░░░░░░░░████░░░░░░░░░░░████░░░░░░░░░░░████░░░░░░░░░░░████░░░░░░░░░░░████░

Green CMOS      ████░████░░░░░░████░████░░░░░░████░████░░░░░░████░████░░░░░░████░████░░░░░░  (captures 470/415)
Red CMOS        ░░░░░░░░░░████░░░░░░░░░░░████░░░░░░░░░░░████░░░░░░░░░░░████░░░░░░░░░░░████░  (captures 560)
                ───────────────────────────────────────────────────────────────────────────►
                                    Time

The temporal multiplexing sequence:

  1. Blue LED (470nm) excitation -> Green CMOS camera captures signal from GFP-based sensors
  2. UV LED (415nm) excitation -> Green CMOS camera captures isosbestic signal
  3. Yellow LED (560nm) excitation -> Red CMOS camera captures signal from RFP-based sensors

This cycling occurs at 60 Hz, allowing near-simultaneous measurement of multiple signals while preventing crosstalk between channels. Each LED is activated in sequence and cameras are synchronized to capture data only during their respective LED's ON period.

Camera exposure and LED timing

Timing is configured per light source through the task field (FipTask) of light_source_uv, light_source_blue and light_source_lime in the rig configuration. Four durations (in µs) define one acquisition cycle:

Rig field Default (µs) Meaning
delta_1 15650 Camera exposure time, i.e. the window in which the LED is on and the camera integrates
delta_2 666 Guard interval between LED/camera transitions
delta_3 300 Guard interval before the camera exposure
delta_4 50 Guard interval after the camera exposure

The four values sum to the cycle period, so the acquisition frequency follows from them: delta_1 + delta_2 + delta_3 + delta_4 = 1 / frequency. With the defaults this is 16666 µs, i.e. 60 Hz. The guard intervals (delta_2 to delta_4) should be minimized for better signal, but if they are too short, LED instability contributes periodic noise, so they should be optimized empirically. For more information, check the cuttlefish-fip firmware documentation.

Other task fields that shape the waveform:

  • light_source_port and camera_port: the output ports that trigger the LED and the camera of that channel.
  • pwm_frequency: PWM frequency (Hz) of the light source output (minimum 10000).
  • events_enabled and mute_output: whether trigger events are emitted, and whether outputs are silenced while timing is preserved.

LED intensity is set separately from timing, through the PWM duty cycle (0-1) of each light source:

  • If the light source has no calibration, power is used directly as the duty cycle and must be between 0 and 1.
  • If calibration is provided, power is expressed in µW and converted to a duty cycle using the power_lut look-up table (duty cycle -> power).

Using the acquisition system

See wiki for AIND internal installation instructions.

Installation Steps

  1. Clone this repository
  2. Create the environments for Bonsai, run ./.bonsai/setup.cmd (can be by double-clickin it too). This is required to run experiments using the Bonsai script in an experimental PC.
  3. [Optional] Create the environments for Python, run uv venv if using uv, or create a virtual environment using your preferred method. This is only used to run the Python script generating configuration files. (rig PCs can inherit those files from somewhere else)
  • Alternatively, if you are using uv, run ./scripts/deploy.ps1 to bootstrap a Python and Bonsai environment at the same time for the project automatically.

Generating input configurations [Optional]

The current pipeline relies on two input configuration files. These configure the rig/instruments and session parameters, respectively. These files are formalized as pydantic models as shown in ./examples/example.py. Template configuration files are included in the ./examples/ folder, and running the example.py will create configuration files into ./local/

Briefly:

from aind_behavior_services.session import Session
from aind_physiology_fip.rig import AindPhysioFipRig

this_rig = AindPhysioFipRig(...)
this_session = Session(...)

for model in [this_session, this_rig]:
    with open(model.__class__.__name__ + ".json", "w", encoding="utf-8") as f:
        f.write(model.model_dump_json(indent=2))

Running the acquisition

Running manually

Acquisition is done through Bonsai via a single entry-point workflow. As any Bonsai workflow, one can run the acquisition workflow via the editor:

  • Open Bonsai from the bootstrapped environment in ./.bonsai/bonsai.exe
  • Open the workflow file ./src/main.bonsai
  • Manually set the two highest level properties RigPath and SessionPath to the paths of the configuration files generated in the previous step.
  • Launch the workflow by clicking the "Run" button in the Bonsai editor.
  • Settings in FipRig.json such as camera_green_iso serial_number and cuttlefish_fip port_name needs to be modified per PC for Bonsai to detect those hardware.

Running via CLI

The workflow can be launched via the Bonsai Command Line Interface (CLI). Additional documentation on the CLI can be found here. To run the acquisition workflow using the CLI, use the following command:

"./.bonsai/bonsai.exe" "./src/main.bonsai" -p RigPath="../path/to/rig.json" -p SessionPath="../path/to/session.json"

Additional flags can be passed to automatically start the workflow (--start) or run in headless mode (--no-editor) as stated in the Bonsai CLI documentation.

Acquiring data

Once the workflow is running, a UI will pop up and users can start acquisition by clicking Start. The system will then begin to acquire data from the cameras and store it in the specified session directory. Once the session is ready to stop, users can click Stop in the UI. The system will then save the session data and stop/close the workflow.

Contributors

Contributions to this repository are welcome! However, please ensure that your code adheres to the recommended DevOps practices below:

Linting

We use ruff as our primary linting tool:.

    uv run ruff format .
    uv run ruff check .

Testing

Attempt to add tests when new features are added. To run the currently available tests, run uv run python -m unittest from the root of the repository.

Lock files

We use uv to manage our lock files and therefore encourage everyone to use uv as a package manager as well.

CLI

The package provides a command line interface (CLI) to facilitate common tasks. The CLI can be accessed by running the following command from the root of the repository:

    uv run fip <subcommand> [options]

For a list of available subcommands and options, run:

    uv run fip --help

(If you are not using uv, activate your python environment and run the fip tool directly.)

Generating aind-data-schema metadata

The repository will maintain tools to generate aind-data-schema compliant metadata for experiments run using the FIP system:

  1. Install the mappers optional dependencies:
uv sync --extra mappers
  1. Run the metadata generation tool via the command line and provide the necessary arguments
uv run fip data-mappers -h

Alternatively, you can use the mapping classes directly. For instance to run the mapper/extractor for acquisition data:

from aind_physiology_fip.data_mappers import ProtoAcquisitionMapper

data_path = "path to dataset"
acquisition_mapped = ProtoAcquisitionMapper(data_path).map()
with open("fip.json", "w", encoding="utf-8") as f:
    f.write(acquisition_mapped.model_dump_json(indent=2))

Regenerating schemas

Instructions for regenerating schemas can be found here.

Metadata

Release files for aind-physiology-fip 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aind-physiology-fip 0.4.0
File Size Uploaded Provenance Actions
aind_physiology_fip-0.4.0.tar.gz 21.4 kB Without provenance Details for aind_physiology_fip-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aind-physiology-fip 0.4.0
File Interpreter ABI Platform Actions
aind_physiology_fip-0.4.0-py3-none-any.whl Python 3 none any Details for aind_physiology_fip-0.4.0-py3-none-any.whl

Total release size: 46.0 kB

Release files / aind_physiology_fip-0.4.0.tar.gz

Download URL aind_physiology_fip-0.4.0.tar.gz
Size 21.4 kB
Tags Source
SHA-256 checksum
How to use checksums
88ca39425e4f58bbaad168db56fffbc4b26f763c8e1ff87da3f5692892279a8f
BLAKE2b-256 checksum
How to use checksums
9ea2b7c9097ae26f9573f11470798afa3432aa7958d55e771dc5ee6510d839e5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / aind_physiology_fip-0.4.0-py3-none-any.whl

Download URL aind_physiology_fip-0.4.0-py3-none-any.whl
Size 24.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b354908ecf3588a2ab3cbf0ed7eefa27f73eb2787c39aad6462dda9efa8e91d0
BLAKE2b-256 checksum
How to use checksums
e807ca1cee3f48df3d20fd8529297c55d40c08882aa8528b471ababf8e27a39e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for aind-physiology-fip 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page