FreeSurfer Simple Reporting

Abstract

pl-freesurfer_simplereport is a ChRIS ds plugin which generates reports off FreeSurfer generated annotation/segmentation volumes that exist in the input file space. These reports can be created in various formats (txt, csv, json, html, and pdf) and are saved in the output file space. The plugin can be run safely on an appropriate upstream directory space (i.e. outputs created by FreeSurfer) to generate reports off all mgz files that conform to a pattern *aparc*mgz.

Installation

pl-freesurfer_simplereport is a ChRIS plugin, meaning it can run from either within ChRIS or the command-line.

Local Usage

To get started with local command-line usage, use Apptainer (a.k.a. Singularity) to run pl-freesurfer_simplereport as a container:

singularity exec docker://fnndsc/pl-freesurfer_simplereport \
    freesurfer_simplereport [--args values...]              \
    input/ output/

To print its available options, run:

singularity exec docker://fnndsc/pl-freesurfer_simplereport \
    freesurfer_simplereport --help

Examples

freesurfer_simplereport requires two positional arguments: a directory containing input data, and a directory where to create output data. Typically, the input directory space should contain FreeSurfer annotation volume files (format mgz). The exact location of these files is unimportant as the plugin will recursively search for hits that satisfy the pattern **/*annot*mgz. For each hit, a report will be generated with a similar tree structure in the output file space. In the simplest case, no command line arguments are needed.

mkdir outgoing/
# Assume that the directory FreeSurfer-recon contains FreeSurfer generated
# contents.
singularity exec docker://fnndsc/pl-freesurfer_simplereport:latest  \
    freesurfer_simplereport                                         \
    FreeSurfer-recon/ outgoing/

Development

Instructions for developers.

Building

Build a local container image:

docker build -t localhost/fnndsc/pl-freesurfer_simplereport .

Get JSON Representation

Run chris_plugin_info to produce a JSON description of this plugin, which can be uploaded to a ChRIS Store.

docker run --rm localhost/fnndsc/pl-freesurfer_simplereport \
    chris_plugin_info > chris_plugin_info.json

Local Test Run

Mount the source code freesurfer_simplereport.py into a container to test changes without rebuild.

docker run --rm -it --userns=host -u $(id -u):$(id -g) \
    -v $PWD/freesurfer_simplereport.py:/usr/local/lib/python3.10/site-packages/freesurfer_simplereport.py:ro \
    -v $PWD/in:/incoming:ro -v $PWD/out:/outgoing:rw -w /outgoing \
    localhost/fnndsc/pl-freesurfer_simplereport freesurfer_simplereport /incoming /outgoing