Project Report: AFNI in Boutiques (& nipype)

[gkiar]

Project Title

Boutify: Increasing the documentation and usability of AFNI through Boutiques

Contributors

Name	Position	Institute
Anisha Keshavan	Postdoctoral Fellow	University of Washington eScience Institute
Ross Markello	PhD Student	Montreal Neurological Institute
Greg Kiar	PhD Student	Montreal Neurological Institute
Chris Markiewicz	Software Developer	Stanford University
Satra Ghosh	Principal Research Scientist	MIT
Peter Molfese	Scientist	NIMH-SFIM
John Lee	Neuroimaging data scientist	NIMH-DSST
Dylan Nielson	Neuroimaging data scientist	NIMH-DSST

Project Summary

The goal of this project was to increase the portability and useability of the AFNI software package. This consisted of several key components, including: 1) parsing existing documentation, 2) manually annotating and curating AFNI tools to develop an understanding of their function, 3) generating executable descriptors of these tools, 4) proof-reading these descriptions with AFNI experts, and 5) then integrating these descriptions back into the tools themselves to improve their documentation, and execution platforms to simplify the adoption of AFNI.

Project Significance

This project lowers the barrier for using AFNI tools and integrating them with scientific workflows. This process increases the consistency of documentation for AFNI, and will lead to increases in functionality for both Boutiques, a tool for creating executable tool descriptions, and Nipype, a framework for creating scientific workflows in Python. This project will take advantage of gamification and human proof-readers to help with the creation of tool descriptions. While many pieces of this project are still in progress, ultimately the pieces will lead to easier adoption of AFNI interfaces and the harmonization of Boutiques and Nipype standards.

Progress Report

1 - Parsing existing documentation

• AFNI's apsearch was used to create "helptext" for all AFNI command-line tools
• Python utility was written to:
  • generate estimates of parameter and description values from helptext
  • create minimal Boutiques descriptors from these descriptions

2 - Curating AFNI tools

• Inspired by Braindr and Appstract, an app was created to annotate help-text guesses
• This app will be used to:
  • pick-up missing parameters,
  • restrict helptext to contain useful descriptions for a given parameter
  • annotate other properties of parameters, such as dataset type

3 - Improve descriptors of these tools

• While this step has not yet taken place (dependent on 2), it will use the updated descriptions for parameters to generage better estimates of Boutiques descriptors

4 - Proof-reading descriptions with AFNI experts

• Once minimal descriptors have been created, with AFNI experts the tools were rated several properties
• Descriptors were stepped-through manually with expert AFNI developers and users, and modified according to descriptions and features that the help-text didn't capture
• In particular, the output-files and groups properties were added to the descriptors, as this was difficult or impossible to generate automatically, or even in some cases with human annotation
• This process has been done for 3 or 4 AFNI tools.
• This process has uncovered several limitations of the Boutiques specification, and issues have been open to reflect the desired improvements.

5 - Updating documentation

• Once descriptors have been written, they can be used to generate fresh help-text with an under-development Boutiques pretty-print tool
• This tool can be used to generate help text that will be able to be either plugged into a docopt argument parser in Python, or regenerate the original boutiques descriptor.
• This standard for text annotation of tools will enable descriptors to be written for free for all future AFNI tools which adopt this method for documentation.

Future work includes improving each of these steps and the Nipype integration of Boutiques descriptors.

Project URLs

Component	URL
Boutiques	https://boutiques.github.io
AFNI help text parser	https://github.com/boutiques/afni-integration
Boutify web app	https://boutify-afni.firebaseapp.com
First pass at AFNI descriptors	https://github.com/afni/afni_boutiques
AFNI tool descriptor ratings	Google Doc
Pretty print tool development branch	https://github.com/gkiar/boutiques/tree/pretty-print
Nipype + Boutiques discussions	https://github.com/boutiques/boutiques/issues/