Record image and orientation data to file#

Note

This tutorial builds on the Quick Start Guide and previous tutorials, and is part of the custom Bonsai workflows series.

You do not need this workflow to record data. The Open Ephys Miniscope V4 GUI records video, per-frame orientation / digital-input metadata, a session log, and a configuration snapshot from a single Record button, with all file names kept in sync; see Recording Data with the Miniscope GUI. Follow this tutorial when you want to understand how the writers work, or when you need to modify what is saved.

After following this tutorial, the user will be able to save image data and timestamped orientation data from the UCLA Miniscope v4.

uclaminiscopev4-miniscopedaq-savedata.bonsai
uclaminiscopev4-miniscopedaq-savedata

Hint

The MiniscopeGui workflow is a drop-in replacement for the UclaMiniscopeV4 node in this workflow: swap it in to gain the GUI’s visualizations, with no changes to anything downstream. See Swapping the Hardware Node for the GUI.

Workflow Description#

Save Image Data

screenshot of uclaminiscopev4 node boxed

  • The Image node connects to a VideoWriter node. The VideoWriter operator writes data to a video file according to settings in the Properties pane that appears after left-clicking the VideoWriter node.

  • There are two VideoWriter operators. The first one is from the Bonsai.Vision package, and the second one is from the Bonsai.FFmpeg package. They are both sink operators as indicated by the nodes’ purple color and the orientation of their grey arcs. A sink operator saves data or triggers external events.

  • The first VideoWriter operator is enabled. It can be disabled by clicking it and pressing Ctrl+D. It is configured to save video using a Y800 (no compression) codec.

  • The second VideoWriter operator is disabled. It can be enabled by clicking it and pressing Ctrl+Shift+D. It is configured to save video using an 8-bit FFV1 (lossless compression) codec.

  • The Annotation nodes (which contain a “#” symbol) are simply there to indicate the difference between the Bonsai.Vision.VideoWriter operator and the Bonsai.FFmpeg.VideoWriter operator. They don’t provide any functional difference in the workflow. You can think of them like comments in code.

Note

The Miniscope GUI uses the same Bonsai.Vision.VideoWriter operator, with the Y800 codec by default and MJPG when Compress Video is enabled. The FFV1 option shown here is one the GUI does not expose, because it requires a separate Bonsai package (Bonsai.FFmpeg) to handle the encoding, and playback software that supports the codec.

Save Timestamped Orientation (Quaternion) Data

screenshot of uclaminiscopev4 node boxed

  • The FrameNumber, Quaternion node connects to the Timestamp node. The Timestamp operator appends timestamps to items that are emitted by the upstream operator.

  • The Timestamp node connects to the CsvWriter node. The CsvWriter operator writes data to a csv file according to settings in the Properties pane that appears after left-clicking the CsvWriter node.

Tip

The GUI writes a wider CSV from this same operator, adding the hardware clock and both digital input states to each row. If you want that layout, see The Files a Recording Produces for the columns and extend the MemberSelector feeding the Timestamp node accordingly.

Configure the Hardware#

Configure the hardware as in the Quick Start Guide or as in the Automate tether commutation using 3D orientation data tutorial if you are using an Open Ephys Commutator.

Get Started in Bonsai#

In addition to the setup steps outlined in previous tutorials, install the following package:

  • Bonsai.FFmpeg: controls video output encoding.

This package requires installing FFmpeg separately in order to work. Follow the FFmpeg installation guide available in documentation for the Bonsai.FFmpeg package .

Operate the Workflow#

  1. Set the UclaMiniscopeV4 operator’s Index property to the value that corresponds to the index of your miniscope.

  2. If using a commutator, set the COM port associated with your commutator in the workflow. If not using a commutator, delete the nodes corresponding to the commutation.

  3. Save data according to your specifications:

    Image video data:

    Left-click the enabled VideoWriter node and edit fields under the properties pane. Confirm the frame rate matches that of the UclaMiniscopeV4 operator. Make sure the file name has a valid extension (“.avi”). “Y800”, an uncompressed greyscale codec, is specified as the FourCC.

    screenshot of bonsai.vision.videowriter properties

    Alternatively, you can also use VideoWriter from the Bonsai.FFmpeg library to save video. This provides more flexibility to save video files using FFMpeg as the backend.

    Disable the first VideoWriter node and enable the second one. The description of the node in the properties pane can help you distinguish between them. Left-click the enabled VideoWriter node and edit fields under the properties pane. Confirm frame rate matches that of the UCLA Miniscope v4. Make sure the file name has a valid extension (“.avi”). The parameters in OutputArguments specify an 8-bit video with “FFV1”, a lossless compression codec, as the FourCC. Here are FFmpeg settings that output a compressed grayscale 8-bit video: “-c: ffv1 -pix_fmt gray -bits_per_raw_sample 8”.

    screenshot of bonsai.ffmpeg.videowriter properties

    Tip

    The FFV1 codec produces smaller files (~30% reduction can be expected), but it requires software that supports loading/playing back this kind of video.

    Orientation quaternion data:

    Left-click the CsvWriter node and edit fields under the properties pane. Make sure the file name has a valid extension (“.csv”).

    screenshot of csvwriter properties

    Note

    • It is best practice to set the Suffix property to Timestamp or FileCount or set the Overwrite property to False to avoid accidentally overwriting important data.

    • Left-click a property field’s corresponding label to display the property’s detail at the bottom of the properties pane (e.g. how it is for the FileName property in the two above screenshots)

    • To temporarily disable saving image or orientation data, disable the respective Writer operator left-clicking the Disable option in the menu that appears after right-clicking an enabled node (or left-clicking the node and using the Ctrl+D hotkey). Re-enable the Writer node by left-clicking the Enable option in the menu that appears after right-clicking a disabled node (or left-clicking the node and using the Ctrl+Shift+D hotkey).

    Warning

    Each writer resolves its own suffix independently here, so the video and CSV file names can drift apart: a Timestamp suffix is evaluated separately by each writer, and a FileCount suffix is counted per extension. If matching names matter to you, set the suffixes explicitly rather than relying on them lining up. The GUI avoids this by resolving one suffix for the whole set of files it writes.

  4. Run the workflow for some time to collect data.

  5. Navigate to the directory specified in step 3, where the data was saved. Confirm the data exists and comports with expectations. The image can be easily viewed in any media playback software that supports the FourCC value specified in step 3. The orientation data can be easily viewed in any spreadsheet software that supports .csv files.

Viewing the Data#

Double-clicking the Image and Quaternion nodes opens Bonsai’s built-in visualizers, which is enough to confirm data is flowing. Judging image quality is another matter: it is hard to tell by eye whether an image is clipping, or where the cells are in a noisy field of view.

The Miniscope GUI gives you the saturation view and histogram for exposure, \(\Delta F/F\) and the max projection for finding cells, and the reference-image overlay for returning to a field of view across sessions. Because only one program can hold the Miniscope DAQ at a time, use the GUI to focus and dial in LED brightness, sensor gain, and frame rate, export the configuration, then close it and run this workflow with those settings. See Embed the GUI as a Single Node.

Next Steps#