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
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
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 Title
Boutify: Increasing the documentation and usability of AFNI through Boutiques
Contributors
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
apsearchwas used to create "helptext" for all AFNI command-line toolsparameteranddescriptionvalues from helptext2 - Curating AFNI tools
3 - Improve descriptors of these tools
4 - Proof-reading descriptions with AFNI experts
output-filesandgroupsproperties were added to the descriptors, as this was difficult or impossible to generate automatically, or even in some cases with human annotation5 - Updating documentation
pretty-printtooldocoptargument parser in Python, or regenerate the original boutiques descriptor.Future work includes improving each of these steps and the Nipype integration of Boutiques descriptors.
Project URLs