1. fMRI in small animals Focus on documentation Joseph B. Mandeville Athinoula 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

2. 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

3. 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

4. Example: our problem & approach Issue: 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

5. A brief overview of “jip” tools Resources: 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

6. Hurdles to distribution Web site for distribution* Web site for user feedback* * Thanks NITRC Licenses (copyright, …) Open-source issues (copyright, provenance,...) Documentation

7. Documentation: past attempts I 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.

8. 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

9. 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

10. 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 has a 3-line description * * think matlab tool-tips “Level-1” help is how to get help.

11. 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

12. Non-GUI documentation The 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.

13. 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 line 2) GLM control file 3) Stimulus files (per run) 4) Table files (per run) 5) Program output 6) 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

14. Conclusions Documentation is important but often overlooked or misunderstood “Users R us” The best users are developers Open-source is always best