Guide/Data Acquisition

Workflow

Prerequisites — complete these first:

Guide/Pre-Experiment Checklist

Next steps — these build on this guide:

(none — this is an end node)

Overview

This guide covers the full recording session procedure, from pre-session preparation through post-session data verification. It includes setting the focal plane and LED intensity, which must be established before the first recording session and held constant for any experiment requiring cross-session cell tracking.

Before your first recording session, the behavioral setup should already be validated (see Guide/Behavioral Setup) and the Guide/Pre-Experiment Checklist should be the last thing you complete before placing the animal in the apparatus.

This guide is part of the Freely Moving Behavior Workflow. Prerequisites: Guide/Behavioral Setup. Run the Guide/Pre-Experiment Checklist at the start of every session.

Software Setup

The Miniscope DAQ Software must be configured before your first session. The software constructs its GUI and data streams from a User Configuration File (JSON format), which you select at launch.

First-time setup

Download the latest release from the Miniscope DAQ Software releases page and unzip to a permanent location on your recording computer
Open the example User Configuration Files included with the software and edit one to match your setup (suggested editors: VS Code, Sublime, Notepad++)
At minimum, set the following fields in your config file:
- "researcherName" — your name; used in folder structure and metadata
- "dataDirectory" — root folder where data will be saved
- "directoryStructure" — array defining folder hierarchy (e.g. ["animalName", "date", "time"])
- "animalName" and "experimentName"
- "recordLengthinSeconds" — set to 0 or omit for unlimited recording duration
- Under "devices" → "miniscopes": confirm "deviceType" matches your hardware (e.g. "Miniscope_V4") and set "deviceID" to the correct camera enumeration number
Save the config file with a descriptive name. Keep a copy per animal if focal plane or gain settings differ between animals.

Video compression

The DAQ software compresses video as it is saved. Set the "compression" field for each device in your config file. Available codecs depend on your OS and installed software; the main window displays which are available on your computer.

Codec	Type	Notes
`GREY`	Lossless (uncompressed)	Largest files; lowest CPU load. Use if other lossless options cause buffer overruns.
`FFV1`	Lossless	Recommended for Miniscope streams. Fast, but requires adequate CPU for multiple streams.
`LAGS`	Lossless	Alternative to FFV1; may be slightly slower.
`MJPG`	Lossy	Fast; acceptable for behavioral camera streams.
`XVID`	Lossy	Comparable to MJPG; acceptable for behavior cameras.

Watch for buffer overruns. If the bufferCount display in the video window turns red, the software is dropping frames. Switch to a less CPU-intensive codec or reduce the number of simultaneous streams. Buffer overruns mean data is being lost silently during the experiment.

Use lossless compression (FFV1 or GREY) for Miniscope streams. Lossy compression is acceptable for behavioral camera streams where pixel-level fidelity is less critical.

Setting Focal Plane and LED (First Session Only)

These parameters must be set before your first recording session and locked for the duration of your experiment. Do this during a habituation session — not on your first experimental day — so that problems can be identified and corrected before experimental data collection begins.

Starting the DAQ software

Run the .exe from the folder you downloaded and unzipped
Select your User Configuration File (or drag and drop it onto the window)
Click Run — the software will validate the config and report any issues
The GUI and device windows will be constructed based on the loaded config
Use the sliders and spinboxes in the Miniscope window to adjust parameters (see below)

DAQ software controls

The Miniscope window exposes the following adjustable parameters:

Parameter	Config key	Notes
LED intensity	`"led0"`	Set to the minimum that produces a clear image
Focal plane (EWL)	`"ewl"`	Electrowetting lens; adjust to focus on cell bodies
Frame rate	`"frameRate"`	e.g. `"30FPS"`
Gain	`"gain"`	e.g. `"Low"`, `"Medium"`, `"High"`
Alpha (upper display level)	—	Display only; does not affect saved data
Beta (lower display level)	—	Display only; does not affect saved data

Alpha and Beta adjust the display contrast only. They have no effect on the data written to disk. Do not mistake a visually improved image from alpha/beta adjustment for a change in actual signal quality.

Setting the focal plane

Focal plane adjustment differs between Miniscope versions:

Miniscope V4 adjusts focus electronically via the EWL (electrowetting lens) slider in the DAQ software ("ewl" parameter). The EWL provides approximately 200 µm of focus range without touching the hardware.
Miniscope V3 uses a fixed focal plane set by mechanical lens placement at the time of assembly. There is no in-software focus adjustment — the focal plane is determined by how the objective GRIN lens was positioned.

For V4, set the focal plane by adjusting the EWL slider in the Miniscope window of the DAQ software. For V3, confirm the focal plane was set correctly during assembly; if it is incorrect, adjustment requires disassembly.

V4: Setting the EWL

Mount the Miniscope on the animal
Open the Miniscope DAQ software, load your config file, and click Run to enable the live view
Slowly adjust the EWL slider in small increments, watching the live image
Look for clearly resolvable cell bodies and visible blood vessels — blood vessels serve as landmarks for across-session FOV alignment
Once you have identified the optimal plane, record the EWL value and save it to your config file ("ewl" field)

Do not change the EWL value after locking it in, for the full duration of your experiment, if you need to track the same cells across sessions. Changing the focal plane shifts which cells are in view and makes cross-session cell registration unreliable.

V3: Verifying the focal plane

On V3, the focal plane cannot be adjusted via software. Before your first session, confirm that the image shows clearly resolvable cell bodies and visible blood vessels. If the focal plane is incorrect, this must be corrected at the hardware level before proceeding.

Per-animal focal plane records

Some animals require a different focal plane setting from the rest of the cohort due to variation in implant geometry. Keep per-animal records:

ID#

Animal ID	Miniscope version	EWL value (V4) or lens position notes (V3)	Gain setting	Miniscope serial number/ID	Date set	Notes

Copy this table into your lab notebook and complete it for each animal before beginning experimental sessions.

Setting LED intensity

Use the lowest LED intensity that produces a clear image. Higher intensity accelerates photobleaching and can cause phototoxicity over long or repeated sessions.

Indicators of good image quality	Indicators of a problem
Clearly visible cell bodies when cells are active	Saturated (blown-out) regions in the image
Visible blood vessels for frame alignment	Signal that drops significantly over the first 5 minutes (photobleaching)
Stable baseline fluorescence between transients	Fluorescence that fluctuates with gross movement but shows no clear transients
Image quality stable across the session duration	Progressive dimming over the session without recovery

Taking a reference snapshot

After locking in both the focal plane and LED intensity, take a high-quality snapshot and save it with a consistent naming scheme:

AnimalID_YYYY-MM-DD_reference.tif

At the start of every subsequent session, compare the live image to this reference snapshot before beginning recording. Blood vessel positions, overall brightness, and the apparent positions of identifiable cell bodies should match closely. If they do not, troubleshoot before recording.

Pre-Session Procedure

Complete the Guide/Pre-Experiment Checklist before every session. Do not begin recording until every item on that checklist is confirmed.

Recording Procedure

Placing the animal

Mount the Miniscope as practiced during habituation
Confirm the image matches the reference snapshot before starting the recording
Place the animal in the apparatus and allow a brief settling period (typically 1–2 minutes) before triggering the recording start, unless your protocol requires immediate recording onset

Starting a recording

In the DAQ software, click and hold the Record button to begin recording
Alternatively, if External Switch is enabled in the config, recording will start and stop based on a digital TTL input to an SMA connection on the DAQ box — use this for precise alignment with behavioral or stimulus hardware

During the session

Monitor the live image periodically for focus drift, motion artifact, or sudden changes in baseline fluorescence
Monitor the bufferCount display — if it turns red, the recording drive or codec cannot keep up and frames are being dropped
Monitor the animal for signs of stress that were not present during habituation
If using a commutator, check that it is rotating freely and that cable twist is not accumulating
If cable twist is being managed manually, note when rotations are performed — this may be relevant during analysis if it produces artifacts
Do not make changes to focus or LED settings during a session

Session monitoring log

Maintain a brief session log for every recording. At minimum, record:

Animal ID	Date / Start time	Duration	LED (`led0`)	EWL	Gain	FPS	Codec	Scope ID	Snapshot match	Buffer overruns	Anomalies	De-twist events

This log becomes essential during analysis when trying to understand why a particular session looks different from others.

Post-Session Procedure

Immediate steps

Gently remove the Miniscope from the animal
Replace the protective cap on the baseplate
Return the animal to its home cage
Immediately open the data folder and confirm the expected files are present and non-zero in size before doing anything else

Data folder structure

The DAQ software creates a nested folder structure based on the "directoryStructure" array in your config file. A typical structure might be:

dataDirectory / animalName / date / time /

Within each session folder, expect:

One or more .avi video files per device (split at the "framesPerFile" interval set in config)
Timestamp files for each video stream
A metadata file containing the config parameters used for that recording

Verify the folder path matches what you expect based on your config before archiving.

Data backup

Back up your data before the next session. Session-level data loss from hard drive failure or accidental deletion is unrecoverable. There is no post-hoc solution. Back up immediately after every session.

Initial data quality check

Before the next session, perform a brief quality check:

☐	Check
☐	Miniscope video opens and plays without corruption
☐	Behavioral camera video is present and plays for the correct duration
☐	Timestamp files are present and have the expected number of entries
☐	Number of video splits matches expected count given session duration and `framesPerFile` setting
☐	A brief visual inspection of the Miniscope video shows that cell bodies are visible and the image is not uniformly dark, saturated, or severely out of focus
☐	No buffer overrun errors were logged during the session

If any of these checks fail, troubleshoot before the next session. Discovering a recording failure two sessions later is more disruptive than catching it immediately.

Troubleshooting

Problem	Response
Live image does not match reference snapshot at session start	Check scope seating, EWL value, gain, and LED settings. If the mismatch is substantial, do not record. See Guide/Pre-Experiment Checklist for a systematic troubleshooting sequence.
Signal drops significantly in the first few minutes	Likely photobleaching from excessive LED intensity. Reduce `led0` value. If this has already occurred in a session, note it in the session log — the early portion of the recording may not be usable.
Fluorescence fluctuates with movement but no clear transients visible	Check focal plane (has the EWL value shifted from your locked setting?), verify viral expression is sufficient for the brain region, and confirm the LED wavelength is correct for your indicator. Review the reference snapshot for comparison.
`bufferCount` turns red / dropped frames reported	The recording drive or CPU cannot keep up. Switch to a less CPU-intensive codec (e.g. GREY instead of FFV1), ensure the recording drive is not nearly full, and do not run other write-intensive applications during a session.
DAQ software reports errors on config load	Open the config file in a text editor and check JSON syntax. The software will report which field is malformed. Compare against an example config from the repository.
Cable twist causing restoring force on the animal	Install a commutator if not already using one, or plan for more frequent manual de-twisting. Note any de-twist events in the session log.
Motion artifact in the recorded video	Verify that the Miniscope is fully seated and secured. Some motion artifact is expected and addressable in post-processing; severe motion artifact from a loose scope is not.