NiftyOne is a platform for bulk visualization of large-scale neuroimaging datasets, leveraging features of FiftyOne with popular neuroimaging python packages.

Installation

python -m venv niftyone
source niftyone/venv/activate

NiftyOne can be installed using pip:

pip install -U pip
pip install git+https://github.com/childmindresearch/niftyone.git

Usage

To get started, try using the boilerplate command:

niftyone <bids_directory> <output_directory> <analysis_level>

niftyone --help

Quick-start

1. Generate figures for each participant

   niftyone <bids_directory> <output_directory> participant
   

2. Collect participant figures into a compatible dataset

   niftyone <bids_directory> <output_directory> group
   

3. Launch FiftyOne app

   niftyone <bids_directory> <output_directory> launch
   

Contributing

Contributions to NiftyOne are welcome! Please refer to the Contributions page for information on how to contribute, report issues, or submit pull requests.

License

NiftyOne is distributed under the MIT license.

Support

If you encounter any issues or have questions, please open an issue on the issue tracker.

Installation

To install niftyone, you can use your installer of choice (e.g. pip, pipx, uv, etc). For example, to install the application with pip, use the following command:

pip install git+https://github.com/childmindresearch/niftyone

If installed properly, you should be able to run the following in your terminal:

niftyone -h

Features

Some features of NiftyOne include:

• Figure generation for QC
• Aggregation of QC metrics
• Shareable QC annotations

Figure Generation

NiftyOne can generate figures and videos for BIDS datasets for QC purposes using popular Python libraries, such as nibabel, numpy, etc. Possible outputs include:

General / anatomical

• Three view - a static image for a given volume in the three anatomical orientations (coronal, axial, sagittal)
• Slice video - a video slicing through a single orientation for a given volume
• Three view video - a video slicing through the 4th dimension (e.g. time) in the three anatomical orientations

Diffusion

• QSpace shells - visualization of diffusion gradients in Q-space
• DWI per shell - video visualizing diffusion volumes by gradient strength
• Signal per volume - 2-panel video, visualizing diffusion MRI volume with associated average signal per volume

Functional

• Carpet plot - Visualization of carpet plot for functional data
• Mean / std - Visualization of mean and standard deviations of functional data

Overlaying of multiple volumes is also possible (e.g. to visualize masks, registration, etc.)

Metrics

NiftyOne can also aggregate QC metrics associated with each participant.

For an example QC file, see the included QC metrics in the test dataset.

Usage

The follow section of the book contains information about hte various NiftyOne workflows, executing NiftyOne both on local machines and via containers. Additionally, there includes a sub-section on advanced NiftyOne usage.

Command line interface (CLI)

The following can also be seen by running niftyone -h in your terminal.

Below are all arguments of the NiftyOne CLI, separated by analysis level. In most cases, only the required arguments are needed.

usage: niftyone bids_dir output_dir analysis_level [options]

NiftyOne is a comphrensive tool designed to aid large-scale QC of BIDS datasets through
visualization and quantitative metrics.

positional arguments:
  bids_dir              Path to BIDS dataset
  output_dir            Path to output directory
  analysis_level        Analysis level

options:
  -h, --help            show this help message and exit
  --overwrite, -x       Overwrite previous results
  --verbose, -v         Verbose logging.

participant level options:
  --participant-label LABEL, --sub LABEL
                        Participant to analyze (default: all)
  --index PATH          Pre-computed bids2table index path (default: {bids_dir}/index.b2t)
  --qc-dir PATH         Path to pre-computed QC outputs
                        (default: {bids_dir}/derivatives/mriqc)
  --workers COUNT, -w COUNT
                        Number of worker processes. Setting to -1 runs as many processes as
                        there are cores available. (default: 1)

group level options:
  --ds-name DATASET     Name of NiftyOne dataset.

launch level options:
  --qc-key LABEL        Extra identifier for the QC session

For more information about the different analysis levels, see the workflows page.

Workflows

NiftyOne contains 3 primary analysis workflows.

Participant

The participant-level workflow can be the most time-consuming process, with image generation performed here.

Group

The group-level aggregates generated images for the platform. Additionally, if available, QC metrics are also aggregated during this workflow.

Launch

The launch-level workflow performs the simple task of launching the visualization platform. If successful, a local IP and forwarded port will be provided to connect to the platform on your local web browser.

Local

To use NiftyOne locally, first follow installation instructions. Once installed, NiftyOne can be initiated from the terminal.

1. Generating figures

We'll start by generating figures using the participant level workflow:

niftyone bids_dir output_dir participant --verbose

2. Aggregating data

Once figures are generated, we can aggregate figures (and QC metrics if available). For this example, we'll assume there are only figures. Additionally, we'll give the dataset a unique name - if one is not provided, it will assume this from the bids directory.

niftyone bids_dir output_dir group --ds-name example --verbose

Launching applicaiton

Finally, we can launch our application with the dataset by including the dataset name we used in the previous step.

niftyone bids_dir output_dir launch --ds-name example

If successfully launched, a message should appear in the terminal:

App launched. Point your web browser to http://localhost:5151

To exit, close the App or press ctrl + c

Enter the address in your web browser of choice to launch the application.

Container

Using NiftyOne via a container (e.g. Docker, Singularity), is similar to using NiftyOne locally. There are a few additional flags required.

NiftyOne uses a hidden .fiftyone directory stored in the home directory (e.g. /home/user/.fiftyone) This directory needs to be writable and mounted with the appropriate container flag.

Docker

First download the container, replacing <TAG> in the following command with the version to be pulled:

docker pull ghcr.io/childmindresearch/niftyone:<TAG>

To use NiftyOne with Docker, the host network also needs to be made available to be able to pass the launched application. Rather than executing each workflow with individual Docker commands, it is recommended to shell into the container and call each command:

docker run -it \
  -v "/home/user/.fiftyone:/.fiftyone:rw" \
  --network host \
  childmindresearch/niftyone:<TAG>

Once you are shelled into the container, you can follow the same instructions as if you are running NiftyOne locally.

Advanced

The following pages provide advanced usage instructions. These include things like running NiftyOne remotely, sharing QC results, etc.

Remote

NiftyOne can also be launched remotely (e.g. on a cluster). To use NiftyOne remotely, first follow either the local or container usage instructions with your remote server instructions (e.g. compute node if required). Once NiftyOne is launched, a (multi-layered) port forward will need to be set up from your local machine to the remote server:

Single-layer port forwarding

The follow provides an example of a single-layer port forward:

HOST=hostname # Name of the remote server (not the full address)
PORT=5151 # Assume port 5151 is available, change this as needed

ssh -L ${PORT}:localhost:${PORT} ${USER}@remote.server.com

From here, point the web browser on the local machine (e.g. your computer) to localhost:${PORT}.

Multi-layered port forwarding

The follow provides an example of a two-layer port forward (chain the command as needed for more layers):

HOST=hostname # Name of the remote server (not the full address)
PORT=5151 # Assume port 5151 is available, change this as needed

ssh -L ${PORT}:localhost:${PORT} ${USER}@remote.server.com ssh -L ${PORT}:localhost:${PORT} -N $HOST

From here, point the web browser on the local machine (e.g. your computer) to localhost:${PORT} as before.

Sharing QC annotations

NiftyOne enables users to interactively create QC annotations as tags within the application.

Annotations are saved to a JSON file when the application is closed, allowing QC annotations to be easily shared with others. The JSON file can be found in the output directory at output_dir/QC/<dataset_name>_tags.json.

Examples

This page provides example configurations to assist with figure generation. These examples are designed for use with the participant workflow. Additional figures can be generated by modifying configurations as needed.

Anatomical

The configuration below generates two views for anatomical T1-weighted (T1w) images.

queries:
  t1w: &t1w datatype == 'anat' & suffix == 'T1w' & ext == '.nii.gz'

figures:
  anat:
    queries:
      - *t1w
    views:
      three_view:
        figure: anatThreeView
      slice_video:
        axis: 2

Diffusion

The configuration below generates views for diffusion weighted (DWI) images in the same space as T1w images (for overlays). It also assumes there are 3D non-diffusion weighted (B0) images.

queries:
  dwi: &dwi datatype == 'dwi' & space == 'T1w' & res == 'dwi' & desc == 'preproc' & suffix == 'dwi' & ext == 'nii.gz'
  dwi_mask: &dwi_mask datatype == 'dwi' & space == 'T1w' & res == 'dwi' & desc == 'preproc' & suffix == 'mask' & ext == 'nii.gz'
  b0: &b0 datatype == 'dwi' & space == 'T1w' & desc == 'avg' & suffix == 'b0' & ext == 'nii.gz'
  t1w: &t1w datatype == 'anat' & run == 1 & suffix == 'T1w' & ext == 'nii.gz'
join_entities:
  default: &default ["sub", "ses", "run"]

figures:
  dwi:
    queries:
      - *dwi
    views:
      three_view_video:

  dwi_mask:
    queries:
      - *dwi
      - *dwi_mask
    join_entities: *default
    views:
      three_view_video:
        figure: "mask"

  registration:
    queries:
      - *b0
      - *t1w
    join_entities: ["sub", "ses"]
    views:
      three_view:
        overlay_cmap: "hot"
        figure: "registration"

Contributing

If you are looking to contribute, we recommend cloning the repository locally:

git clone https://github.com/childmindresearch/niftyone <local_directory>
cd <local_directory>    # Navigate to local copy of repository

Dependencies

niftyone relies on a number of internal (python) and external (system) dependencies in order to build a platform for bulk visualization of large-scale neuroimaging datasets. The primary external dependency is FFmpeg - installation instructions can be found on their website. Internal dependencies are listed in the pyproject.toml file of the repository, with specific development versions listed in the requirements.txt file - any version updates will also be reflected in this file.

Development environment setup

To setup the development environment, first ensure external dependencies are installed.

python -m venv <venv_directory>
source activate <venv_directory>/bin/activate

Internal dependencies can be installed using pip:

pip install -e .\[doc,dev,test\]

To ensure the installation was successful, try running the niftyone command:

niftyone -h

Code formatting

niftyone uses pre-commit, as well as a Github action workflow to check for and address formatting issues. These use the following:

• ruff - formatting and linting
• mypy - type checking
• language-formatters-pre-commit-hooks - pretty format YAML and TOML files
• pre-commit-hooks - fix string casing, format JSON files

To install the pre-commit configuration, run the following:

pre-commit install

Adding features / fixing bugs

To contribute a change to the code base, checkout a new branch from the main branch and then make your changes.

git checkout -b feature/your-feature-name main

Testing

While all new contributions will be tested, testing can also be done locally making use of the same dataset, ds000102, available as a sub-module in the testing directory. To download the sub-module:

git submodule update --init --recursive

Unit tests can be performed via pytest:

pytest --cov-report term-missing --cov src/ tests/ -s

niftyone tests/data/ds000102 /tmp/niftyone_test participant

Pull requests

Once you have made your changes and are ready to contribute, follow the steps to submit a pull request:

1. Push your changes back.

   git push -u origin feature/your-feature-name
   

2. Create a pull request to merge your branch into the main branch. Provide a clear description of your changes in the pull request message.

Guidelines

• Write clear and concise commit messages.
• Test your changes thoroughly before submitting a pull request
• If the pull request adds functionality, the documentation should also be updated.

It is okay to submit work-in-progress and seek feedback - you will likely be asked to make additional changes or asked clarification questions.

Review process

All pull requests will undergo a review process before being accepted. Reviewers may provide feedback or request changes to ensure the quality of the codebase.

Frequently Asked Questions (FAQ)

1. Where can NiftyOne be installed?

   NiftyOne can be installed both locally and on a remote serve. If NiftyOne is installed on a server, the output can be viewed from a local web browser after port forwarding.

2. I am getting the following error: /home/user/.../mongod: error while loading shared libraries.

   Try to reinstall mongo and / or re-creating the virtual environment NiftyOne is installed in.

3. I am getting the following error: OSError: You must have fiftyone>=0.22.1 installed in order to migrate from v0.22.1 to v0.21.6, but you are currently running fiftyone==0.21.6.

   Try re-installing fiftyone / niftyone.

4. I am getting an error about connection failure to port 5151.

   The port 5151 is likely already being used by another application - try incrementing the port number to 5152, 5153, etc.

Version

This document book provides details on the latest version of the tool. To reference previous versions, please refer to the appropriate tag in the Github repository - the pages of the book can be found in the docs/src/ directory.

module niftyone

Large-scale neuroimaging visualization using FiftyOne.

Global Variables

• figures
• metrics
• runner

module niftyone.analysis_levels

Analysis-level workflows.

module niftyone.analysis_levels.group

Group analysis-level.

Global Variables

• TAGS
• IMG_EXTENSIONS

function group

group(
    bids_dir: str | os.PathLike,
    out_dir: str | os.PathLike,
    ds_name: str | None = None,
    qc_key: str | None = None,
    overwrite: bool = False
) → None

Collects samples into a FiftyOne dataset and exports to the output directory.

module niftyone.analysis_levels.launch

Launch analysis-level.

function launch

launch(
    bids_dir: str | os.PathLike,
    out_dir: str | os.PathLike,
    ds_name: str | None = None,
    qc_key: str | None = None
) → None

Launch FiftyOne application to visualize a dataset.

module niftyone.analysis_levels.participant

Participant analysis-level.

function load_config

load_config(config: pathlib.Path | None) → dict[str, Any]

Load configuration file describing figures to be generated.

function participant

participant(
    bids_dir: pathlib.Path,
    out_dir: pathlib.Path,
    sub: str | None = None,
    index_path: pathlib.Path | None = None,
    qc_dir: pathlib.Path | None = None,
    config: pathlib.Path | None = None,
    workers: int = 1,
    overwrite: bool = False,
    verbose: bool = False
) → None

Generate visualization images.

module niftyone.cli

Command line interface (CLI) utilities.

class NiftyOneArgumentParser

NiftyOne CLI parser.

method NiftyOneArgumentParser.__init__

__init__() → None

method NiftyOneArgumentParser.parse_args

parse_args(args: collections.abc.Sequence[str] | None = None) → Namespace

Parse command-line arguments.

module niftyone.figures

Figure factories for creating visualizations.

Global Variables

• factory
• dwi
• func
• multi_view

module niftyone.figures.dwi

Factories associated with diffusion visualizations.

class QSpaceShells

Visualize diffusion gradients in Q-space.

class DwiPerShell

Visualize diffusion in ascending order of diffusion gradient strength.

class SignalPerVolume

Visualize average signal per volume.

module niftyone.figures.factory

Factory for creating different figures.

Global Variables

• view_registry

function register

register(name: str) → Callable

Register view be callable in figure generation pipeline.

function create_view

create_view(
    view: str,
    view_kwargs: dict[str, typing.Any] | None,
    join_entities: list[str],
    queries: list[str]
) → View

Create a registered view.

function create_views

create_views(config: dict[str, typing.Any]) → list['View']

Create selected views dynamically from config.

class View

Base class for a View.

method View.__init__

__init__(
    queries: list[str],
    join_entities: list[str] | None,
    view_kwargs: dict[str, typing.Any]
) → None

method View.create

create(
    records: list[pandas.core.series.Series],
    out_dir: pathlib.Path,
    overwrite: bool
) → None

Create and save figure from a list of relevant records.

module niftyone.figures.func

Factories associated with functional visualizations.

class CarpetPlot

Visualize carpet plots of functional data.

class MeanStd

Visualize mean and standard deviations of functional data.

module niftyone.figures.multi_view

Factories associated with multiple views.

class ThreeView

Visualize static image in three orientations (coronal, axial, sagittal).

class SliceVideo

Visualize along single chosen orientation of an image volume.

class ThreeViewVideo

Visualize image volume along three orientations (coronal, axial, sagittal).

module niftyone.metadata

Utilities for handling metadata associated with dataset or application.

Global Variables

• tags

module niftyone.metadata.bids

Utilties for handling BIDS dataset associated metadata.

function make_dataset_description

make_dataset_description(out_dir: pathlib.Path, overwrite: bool) → None

Create dataset_description.json for BIDS dataset.

module niftyone.metadata.tags

Utilities for handling NiftyOne tags.

Global Variables

• TAGS

class GroupTags

QC tags for individual data acquisitions.

Interfaces between FiftyOne datasets and pandas DataFrames, CSV, JSON.

method GroupTags.__init__

__init__(tags_dict: dict[str, typing.Any]) → None

method GroupTags.apply

apply(dataset: fiftyone.core.dataset.Dataset) → None

Apply tags to a given FiftyOne dataset, overwriting existing tags.

method GroupTags.equals

equals(other: 'GroupTags') → bool

Assert two groups of tabs are equal.

classmethod GroupTags.from_csv

from_csv(path: str | pathlib.Path) → GroupTags

Extract tags from csv.

classmethod GroupTags.from_dataset

from_dataset(dataset: fiftyone.core.dataset.Dataset) → GroupTags

Extract tags from a FiftyOne dataset.

classmethod GroupTags.from_df

from_df(df: pandas.core.frame.DataFrame) → GroupTags

Extract tags from datafame.

classmethod GroupTags.from_json

from_json(path: str | pathlib.Path) → GroupTags

Extract tags from json file.

method GroupTags.to_csv

to_csv(path: str | pathlib.Path) → None

Save tags to csv.

method GroupTags.to_df

to_df() → DataFrame

Convert tags from dict to pandas dataframe.

method GroupTags.to_json

to_json(path: str | pathlib.Path) → None

Save tags to json.

module niftyone.metrics

Utilities for handling QC metrics.

function create_niftyone_metrics_tsv

create_niftyone_metrics_tsv(
    record: pandas.core.series.Series,
    entities: bids2table.entities.BIDSEntities,
    out_dir: pathlib.Path,
    qc_dir: pathlib.Path,
    overwrite: bool = False
) → None

Filter for metrics associated with record (image).

module niftyone.runner

Handles coordination to generate figure and extract metrics via workflow Runner.

class Runner

Runner class to process participants dynamically.

method Runner.__init__

__init__(
    figure_views: list[niftyone.figures.factory.View],
    out_dir: pathlib.Path,
    qc_dir: pathlib.Path | None,
    overwrite: bool
) → None

method Runner.create_figures

create_figures() → None

Generate figures from dataset.

method Runner.update_metrics

update_metrics() → None

Generate / update QC metrics for dataset.