fMRI in small animalsFocus on documentation

Joseph B. MandevilleAthinoula A. Martinos Center for Biomedical Imaging

Charlestown, MA, USA

Mass. General Hospital/Harvard Medical School

Thanks & support

R03-EB8134 (NIBIB)Automated Alignment of MRI Rodent Brain to Sterotaxic Atlases

R01-EB001782 (NIBIB)IRON fMRI: Improving Sensitivity & Spatial Localization

Genesis of a software app.

• Identify an unmet need (e.g., data analysis)

• Assemble a team of scientists, programmers,

and consultants

• Develop the application in coordination with

user input

• Conference with users to develop–Work flow–Interface–Data formats, …

… just kidding

Real life

• Encounter road blocks doing research– desire different methodologies– get tired of inefficiencies, …

• Work alone in isolation– (in a dark corner, basement, ….)

• The new software attracts users

• A new phase begins: “development & support”– developers & users embrace … but harbor deep resentments and mutual loathing

– watch publications & funding dwindle

Example: our problem & approachIssue: We do a lot of rodent imaging; particularly fMRI.

Many human neuro-imaging tools don’t work well for rodents• different resolutions, orientations, anatomy, …

Solution:• develop anatomical templates• use standardized coordinate systems based upon histology• facilitate atlas/MRI communication

Illustrations of the problem: n=9, no anatomical reference

Marota et al., NeuroImage 2000

n=1, pile-of-heads format

Keilholtz et al., Magn Reson Med 2006

A brief overview of “jip” toolsResources:

• Allen Mouse Brain Atlas (.nii) + fake MRI mice• Mouse BIRN T2 template (LONI) aligned to ABA• Rat MRI templates aligned to Paxinos-Watson space

Software:• Visualization (NIFTI viewer with GLM analysis)• Registration (visualization + alignment)• Overlays & wire frames (atlas/MRI communication)• Batch/interactive communication• open source c code

Hurdles to distribution

• Web site for distribution *

• Web site for user feedback *

* Thanks NITRC

• Licenses (copyright, …)

• Open-source issues (copyright, provenance, ...)

• Documentation

Documentation: past attemptsI once wrote a manual… extensive… linked PDF… with pictures.Nobody read it.

Oh well, just n=1. So I wrote a new manual for a different program.Same result.

N=2, Manuals don’t substitute for online documentation.

What makes a user happy?( These are largely guesses on my part )

1. Understanding the advantages & limitations before downloading & using tools• What features are “tailored” for their application.• How/when do they join/leave your analysis stream

2. Batch/interactive communication• Visualize registration, but apply in batch mode.• Visualize time series analysis, but apply in batch mode.

3. Documentation• interactive and multi-level• Few people want to read your (my) manual, except to

answer specific questions unrelated to basic functions

Approach to Documentation

• Valid reasons for “Off-line” documentation (e.g., PDF)

– Overview of tools for prospective users

– Introductory tutorial for new users

– Resources (e.g., templates, atlases)

– Algorithms, details of file formats, …

Key lesson from experience:

What users want is “enough” information, when they want it.

• What happens online, stays online.

– Docs should be feature-based; not just a docu-dump

– For non-GUI apps, “program -h” usually isn’t sufficient

GUI documentation: brief

“Level-2” help is a very general overview of interaction:• Arrows, buttons, display modes, graphs, overlays & wire frames, activation color bars

• about 1 page

Every tool selection hasa 3-line description *

* think matlab tool-tips

“Level-1” help is how to get help.

GUI documentation: expansive

Most feature-based documentation is obtained by followed by “click on something” ?

About 1 page per selection

Colorbar documentation:• setting ranges• choosing +/- tails• color scales• paging through maps

Non-GUI documentationThe unix/Linux standard:

Unix%: glm -h

Syntax: executable [file name] [optional arguments]Optional arguments:-p to convert to percent change for S-n files-d [divisor] to divide output by divisor for S-n files-v for verbose output-s for small memory allocation

The problem here: [file name] has a host of options and refers to additional files (data files, stimulus files, table files); there needs to be many pages of help.

My approach to non-GUI apps

Revive old method for documentation that users actually liked!

Menu-driven help file

!0 0 0{{{{ Main Menu }}}}

1) input options from command line2) GLM control file3) Stimulus files (per run)4) Table files (per run)5) Program output6) Interface with display program

!1 0 0{{{{ Input Options }}}}

Syntax: executable [file name] [optional arguments]Optional arguments:-p to convert to percent change for S-n files-d [divisor] to divide output by divisor for S-n files-v for verbose output-s for small memory allocation

Conclusions

• Documentation is important but often overlooked or misunderstood

• “Users R us”

• The best users are developers

• Open-source is always best