Getting Started¶

Welcome to ConfUSIus! This guide introduces the package and helps you understand how it fits into a typical fUSI data analysis workflow.

What is fUSI?¶

Functional ultrasound imaging (fUSI) is a neuroimaging technique that measures brain activity by detecting changes in cerebral blood volume^{1 2 3}. fUSI offers:

• High spatiotemporal resolution: Sub-millimeter spatial resolution (~100 μm in-plane and ~500 μm out-of-plane with 15 MHz linear probes) with temporal resolution on the order of 0.5–10 Hz, depending on the acquisition protocol.
• Wide field of view: Ability to image large cortical and subcortical regions simultaneously.
• Awake preclinical imaging: Compatible with awake, behaving animals and various experimental paradigms.
• Multimodal integration: Can be combined with electrophysiology, optogenetics, and other techniques for comprehensive studies of brain function.

For more information on fUSI, check out this review article: Functional Ultrasound Neuroimaging by Montaldo et al. (2022).

fUSI data typically consists of large 3D+t datasets (time × z × y × x) acquired from fUSI systems (for example, Iconeus, AUTC, EchoFrame, or in-house setups based on ultrasound research platforms such as Verasonics).

What is ConfUSIus?¶

ConfUSIus is a Python package for handling, processing, and analyzing functional ultrasound imaging (fUSI) data. It provides tools for the entire fUSI analysis pipeline, from converting raw beamformed IQ data to processing hemodynamic signals and performing statistical analyses. It also ships a napari plugin for interactive data exploration.

Key Features¶

ConfUSIus provides a comprehensive toolkit designed specifically for fUSI data:

Typical Workflow¶

ConfUSIus supports the complete fUSI analysis pipeline, from raw data acquisition to statistical analysis and visualization:

 flowchart TB
    subgraph acquire["Data Acquisition"]
        A[fUSI system]
    end

    acquire --> convert

    subgraph convert["Format Conversion"]
        B["Source formats"]
        C[Xarray]
        B --> C
    end

    convert --> process

    subgraph process["Process Beamformed IQs"]
        D[Beamformed IQs]
        E[Power Doppler, velocity, custom measures]
        D --> E
    end

    process --> qc
    process --> visualization
    process --> registration

    subgraph qc["Quality Control"]
        qcmeasures[Global signal, DVARS, axial tissue velocity]
    end

    subgraph visualization["Visualization"]
        plotting[napari, Matplotlib]
    end

    subgraph registration["Registration"]
        motioncorr[Motion correction, template alignment]
    end

    qc --> signal
    visualization --> signal
    registration --> signal

    subgraph signal["Signal Processing"]
        extract[Signals extraction]
        denoising[Denoising]
        extract --> denoising
    end

    signal --> analyze

    analyze["Analysis & Visualization"]

Workflow Stages¶

1. Data Acquisition: Acquire beamformed IQ data from your ultrasound system (AUTC, EchoFrame, Iconeus, or custom setups).
2. Format Conversion: Convert proprietary formats to Xarray-compatible formats (typically Zarr for large datasets, or NIfTI for BIDS compliance).
3. Process Beamformed IQs: Apply clutter filtering and extract hemodynamic signals such as power Doppler, velocity, or custom measures from beamformed IQ data.

4. Quality Control, Visualization & Registration: These steps can be performed in parallel as needed:

   • Monitor data quality using metrics like global signal, DVARS, or axial tissue velocity.
   • Explore data interactively with napari or create static figures with Matplotlib.
   • Perform motion correction or align acquisitions to a template.

5. Signal Processing: Extract signals from specific brain regions and apply denoising and filtering.

6. Analysis: Perform statistical analyses or integrate with other Python scientific libraries.

When to Use ConfUSIus¶

ConfUSIus is designed for anyone working with fUSI data:

• Comprehensive fUSI toolkit: ConfUSIus covers the entire analysis pipeline in a single, actively maintained open-source package—from IQ processing and quality control to atlas integration, signal extraction, and connectivity analysis.
• Accessible at every skill level: Non-programmers can use the napari plugin for interactive data loading, time series inspection, and quality control. Python users can build fully custom pipelines using the scripting API.
• Python ecosystem integration: Works seamlessly with NumPy, Xarray, Dask, Nilearn, scikit-learn, and other scientific Python libraries.
• Standardized workflows: Follow fUSI-BIDS conventions for reproducible, shareable research.
• Scalable to large datasets: Process large beamformed IQ datasets out-of-core using Dask and Zarr without running out of memory.

Before You Begin¶

ConfUSIus is built on several key technologies:

• Xarray: Labeled multi-dimensional arrays with metadata.
• Zarr: Chunked, compressed array storage for large datasets.
• Dask: Parallel computing and out-of-core processing.

If you're new to these tools, check out the Working with Xarray section to get familiar with the core concepts. You may also want to review the Input/Output Guide to understand how ConfUSIus handles data formats.

Next Steps¶

Ready to get started?

1. Install ConfUSIus: Set up your environment and install the package.
2. I/O Guide: Learn how to load and convert your fUSI data.
3. Graphical Interface: Explore your data interactively with the napari plugin—no scripting required.
4. Examples: See complete workflows for common tasks.
5. API Reference: Explore detailed function documentation.

Still have questions? Check the GitHub issues or open a new one! You can also join the fUSI community Discord to ask questions and connect with other researchers using fUSI.

Getting Help¶

We host weekly drop-in hours on the fUSI community Discord usually every Thursday from 3pm to 4pm UTC. Join us in the drop-in-hours voice channel to:

• Get help with ConfUSIus usage and troubleshooting.
• Discuss new features and provide feedback.
• Connect with other fUSI researchers.
• Report bugs in an informal setting.

You can also use the help-desk text channel anytime for questions.

We post on Bluesky in advance to confirm each week's session.

Useful Python Resources for fUSI¶

While ConfUSIus offers many features to handle fUSI data, it obviously does not do everything. Below are some useful resources to read and packages to use alongside ConfUSIus.

• Xarray: ConfUSIus relies on Xarray for storing volumetric fUSI data. Learning how to use Xarray efficiently will get you a long way.
• Dask: Dask is a Python package for distributed parallel computing. Xarray supports Dask arrays as backend, and ConfUSIus relies on them notably for processing large beamformed IQ datasets. Xarray's user guide on parallel computing with Dask might also be a good read.
• Zarr: Zarr is a chunked, compressed array storage for large N-dimensional datasets. ConfUSIus relies on Zarr for storing beamformed IQ data, and large derived measures. Zarr's user guide on optimizing performance is a useful resource if you intend to work with very large beamformed IQ datasets.
• Brain Imaging Data Structure: ConfUSIus uses BIDS conventions when reading and writing JSON sidecars alongside NIfTI files. Even if you don't use NIfTI as your storage format, following BIDS conventions can help you organize and share your datasets later. You may also want to take a look at the fUSI-BIDS specification draft and at PyBIDS.
• Nilearn: Nilearn is a versatile package for analysis of brain volumes and surfaces. While it is mostly geared toward fMRI, many fUSI users have found it useful for analyzing fUSI data. ConfUSIus itself borrows some of Nilearn's features.
• SimpleITK: SimpleITK offers a simple wrapper API over ITK, the widely used image segmentation and image registration library. ConfUSIus builds on SimpleITK for image registration.
• BrainGlobe: BrainGlobe is a suite of Python-based software tools for computational neuroanatomy. Of particular interest is the BrainGlobe Atlas API, which provides a common interface to download and process brain atlases from multiple sources. ConfUSIus builds on the BrainGlobe Atlas API for atlas integration.
• Matplotlib: The obvious choice for creating static figures in Python.
• PyVista: While ConfUSIus uses napari for 3D rendering, PyVista also offers a simple API to make custom 3D visualizations.