Using the Plugin¶

The ConfUSIus sidebar contains six collapsible panels. Each panel operates independently and can be expanded or collapsed by clicking its header. For an in-app introduction, click Take a Tour in the sidebar header.

• Data I/O — load and save fUSI files (NIfTI, Zarr, SCAN).
• Video — load videos side-by-side, temporally synced with the fUSI acquisition.
• Signals — plot voxel, point, or label-region signals in a bottom dock.
• Events — annotate periods of time (BIDS events) and shade them on the signal plot.
• QC — compute DVARS, carpet, CV, tSNR for a selected layer.
• Registration — run between-scan or within-scan registration, inspect progress, and save/apply transforms.

Data I/O Panel¶

The Data I/O Panel handles both loading and saving fUSI files without leaving the viewer.

Loading data¶

Click Browse to pick a file—it loads immediately on selection. Or paste a path directly in the text field and press Enter. Enable Load lazily beforehand to keep the array Dask-backed for large files. A progress bar animates during loading, and any error is reported in the napari notification bar.

Saving data¶

1. Select the layer to save from the Save layer dropdown.
2. Optionally select a layer in the Coordinates from dropdown to borrow its physical coordinates and attributes. This is useful when saving a labels layer drawn on top of a fUSI image: selecting the image layer as the template preserves the full physical coordinate system. If the labels layer has fewer dimensions than the template (e.g. a 3D labels layer against a 4D image), the trailing spatial dimensions are used automatically.
3. Type an output path or click Browse. The format is inferred from the extension: .nii / .nii.gz for NIfTI and .zarr for Zarr.
4. Click Save. A notification confirms success.

Three save modes are applied automatically depending on what is available:

Video Panel¶

The Video Panel loads one or more videos (.mp4, .mov, .avi) and overlays them beside a fUSI scan in a synchronized grid. Each video becomes its own napari Image layer whose time axis is locked to the reference scan, so scrubbing the time slider plays every video in lockstep with the fUSI recording.

Loading a video¶

1. Pick the fUSI image layer to synchronize against in the Reference layer dropdown. The reference must have ConfUSIus coordinate metadata, so load it through the Data I/O Panel or the confusius CLI command.
2. Insert a path or click Browse to pick a video file.
3. Click Add video. The video appears as a new Image layer, grid mode is enabled with a single-row layout, and the viewer shows the reference scan and the video side by side.

Repeat to add more videos (each will get its own cell). All videos share the reference layer's axis labels, time index, and dimensionality; their spatial scale is chosen so the video height matches the fUSI height, with isotropic pixels and the frame centered on the scan.

confusius path/to/scan.nii.gz --video path/to/camera.mp4

Playback¶

The time scale of each video layer is frame_step / fps seconds, so the napari time slider and the time overlay continue to report physical seconds regardless of the chosen step.

Signals Panel¶

The Signals Panel plots signals extracted from image layers along any non-spatial dimension (time, lag, feature, etc.). The plot appears in a bottom dock that is created the first time you click Show Signal Plot.

Choosing a data source¶

Pick one of three source modes in the Source group:

Mouse

Hold Shift and move the mouse over the canvas. The plot updates live with the single-voxel signal at the cursor position.

Points

Select a Points layer from the dropdown (or click + to create one). Each point is plotted as a separate line colored by its face color. Add or remove points in napari and the plot updates automatically.

Labels

Select a Labels layer from the dropdown (or click + to create one). The mean signal is extracted for each distinct non-zero label and plotted as a separate line, colored by the label's color in the napari colormap. This is useful for quickly comparing region-averaged signals after painting ROIs with napari's brush tool.

In Points and Labels modes, the Reference dropdown selects which image layer to extract signals from. It defaults to All image layers, which plots each layer as a separate line (distinguished by line style).

Axis parameters¶

Display options¶

Managing signals¶

Click Manage Signals to open a floating dialog where you can customize both live signals (from the current source mode) and imported signals:

• Rename: Double-click a signal's name to edit it.
• Recolor: Click the color swatch to pick a new color. Changes are synced back to the napari layer (point face color or label colormap).
• Show / Hide: Toggle individual signal visibility with the checkbox.

Importing and exporting signals¶

Import

In the Manage Signals dialog, click Import to load one or more signal files at once. Standard CSV / TSV files must contain a column whose header matches the current x-axis dimension name (e.g. time) plus one or more numeric value columns. BIDS physio files ending in _physio.tsv.gz are also supported: ConfUSIus reads their JSON sidecar, uses the declared column names, and synthesizes time from SamplingFrequency and StartTime when needed. Each value column becomes a separate signal overlaid on the plot.

Export

Click the Export button in the plot toolbar to export all currently plotted signals—both live and imported—to a CSV or TSV file.

Events Panel¶

The Events Panel allows annotating periods of time—not individual frames—following the BIDS events convention (onset, duration, and an optional trial_type). Annotated events shade the signal plot and are named in the time overlay while they are active.

Annotating events¶

1. Type a name for the event in the Event field (defaults to event).
2. Press Start (S) to mark the onset at the current time step, scrub the time slider forward, then press End (E) to mark the offset. Cancel (Esc) discards an in-progress annotation. The shortcuts are active whenever the panel is open.
3. The event appears in the table with its trial type, onset, end, and duration.

The End time must not be before the Start time. Ending at the Start time creates an instantaneous (zero-duration) event, as allowed by BIDS; it is drawn as a vertical line instead of a shaded band.

Loading and saving¶

Use Load to import a BIDS events .tsv file (onset and duration are required; a missing trial_type defaults to event) and Save to write the current events back out as a BIDS events .tsv.

from confusius.bids import load_events
from confusius.glm import FirstLevelModel

events = load_events("sub-01_task-rest_events.tsv")
model = FirstLevelModel(hrf_model="glover").fit(fusi_scan, events=events)

Display options¶

QC Panel¶

The QC Panel computes quality control metrics for a selected image layer.

Select a layer from the Layer dropdown, check the metrics you want, and click Compute.

Registration Panel¶

The Registration Panel runs the ConfUSIus registration workflows directly from napari. Use Between scans for registering different recordings, or Within-scan for volume-wise motion correction within a single recording. The panel supports modifying registration parameters, live preview, and saving/loading/applying computed transforms.

Between scans¶

Use Between scans when you want to register one layer onto another, for example two recordings from different animals or a functional recording onto an angiography.

1. Select the Moving layer and Fixed layer.
2. Choose a transform model.
3. Optionally choose a Scale for to compress the intensity dynamics.
4. Optionally choose an Initialization transform if layers are very misaligned.
5. Click Run registration.

Available transform models are:

• translation for x/y/z-only shifts,
• rigid for translations and rotations,
• affine for translations, rotations, scaling, and shear,
• bspline for non-linear local deformations.

For bspline, a staged workflow usually works best: first run rigid or affine, then run bspline and select the previous transform in Initialization. This lets the B-spline model refine a good global alignment instead of trying to solve both large-scale and local deformation at once.

Main parameters¶

Advanced parameters¶

The animation below uses between-session angiography volumes from the same animal across different days. ConfUSIus keeps the original layers untouched, adds dedicated preview layers for inspection, and stores the final registered result as a new layer when the run completes.

Within-scan¶

Use Within-scan for motion correction inside a single time series.

1. Switch Mode to Within-scan.
2. Select the time-series Moving layer.
3. Choose the Reference volume index used as the registration target.
4. Pick a transform model (translation, rigid, or affine).
5. Click Run registration.

Main parameters¶

Advanced parameters¶

This workflow returns a Motion corrected layer and updates the progress bar as frames finish. The animation below uses a short open-field recording chunk and shows the result filling in progressively.