Improvement and support roadmap for Miniscope #1536
Description
On 2025-10-02 I had a meeting with @GarrettBlair, who has worked very closely with Miniscope.
Garrett was very generous with his time and I am writing this issue to keep this information in a public place and to provide context for improving NeuroConv's Miniscope support in the future.
1. Sampling rate [Solved]
The sampling rate we are currently extracting from the configuration file is unreliable. The sampling value in the configuration file is set by the user, and the DAQ only follows it on a best-effort basis. Crucially, the DAQ always provides timestamps, so we should use those as the source of truth.
I have a PR in ROIExtractors that implements these changes:
catalystneuro/roiextractors#509
2. Configuration file and folder structure [Solved]
From version 1.0 onward, the DAQ provides a configuration file (according to @GarrettBlair, earlier versions might have had a similar file, but we need to double-check). This configuration file describes the folder structure.
Thanks to the work of @alessandratrapani, we now have a more flexible Miniscope Extractor. I am using these changes in #1528 to automatically parse the folder structure and read all the data. See the PR for more details.
When the configuration file is not available, I fall back to the structure used in the Tye Lab for backward compatibility. This assumes that all the time folders represent back-to-back recordings, which is not generally true. We might want to revisit this assumption, but for now I am keeping it for backward compatibility.
In addition, I am adding documentation for users to build their own converter using the new flexible interface and adjust this themselves in #1524. This will be useful for cases when our assumptions does not hold and should work as a general fallback for this format.
We are in good shape here. The work of @alessandratrapani provides both (1) a flexible core that allows us to use the configuration file in the MiniscopeConverter #1528 and (2) a flexible base that users can adapt to build mostly automated solutions for edge cases #1524.
3. Head orientation
According to @GarrettBlair, the headOrientation.csv file is present most of the time.
In this issue I outlined the structure of this file, and I think we should add support to the converter so it is automatically written for the user’s benefit.
4. Metadata considerations
We discussed the particularities of Miniscope metadata. Most of it is already covered in the work by @weiglszonja with ndx-miniscope:
https://github.com/catalystneuro/ndx-miniscope/blob/ba6f779c0588c34f72367c0321583ea5db6c00be/spec/ndx-miniscope.extensions.yaml#L23-L46
The only missing piece I noticed is the ewl, which measures focal plane position (range: -127 to +127). This corresponds to the voltage passed to the actuator and serves as a proxy measurement.
One important point is that in the GUI, the user can change these parameters within the same experimental session. If they do, a notes.txt file is created as an events log indicating when this happened. While this is not common, according to @GarrettBlair we should at least be aware of it and possibly throw a warning if the notes.txt file is non-empty. I am not sure yet how to handle this, but fortunately it does not seem to be a common case.
Another challenge with Miniscope metadata is that it does not save (nor can it) common fields used in the ophys pipeline, such as excitation/emission wavelengths or the grid size in micrometers of the field of view. It is not very common for users to measure or store those values, so we should be aware of this limitation.
Moreover, for Miniscope parameters, there is enough variation across devices that for most parameters it does not make sense to compare values between different setups. Researchers sometimes measure these parameters, but they are only useful for comparisons within the same experimental setup and may be unreliable across experiments. I am not sure how to annotate or convey that within the current schema.
5. Future experimental setups
The Miniscope field is expanding to more experimental setups, including:
- Two-photon Miniscopes: https://www.biorxiv.org/content/10.1101/2024.03.29.586663v1
- Dual-channel Miniscopes: https://pmc.ncbi.nlm.nih.gov/articles/PMC12219470/
- Volumetric capture Miniscopes: https://www.nature.com/articles/s41377-020-00403-7
Since our team is small, I asked @GarrettBlair which setups to prioritize in the future. His view is that the most common ones will be two-photon and dual-channel. For two-photon systems, the metadata and folder structure may differ substantially, while dual-channel Miniscopes may be closer to what we already support.