New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Project Report: AFNI in Boutiques (& nipype) #3

Open
gkiar opened this Issue Sep 14, 2018 · 0 comments

Comments

Projects
None yet
1 participant
@gkiar
Collaborator

gkiar commented Sep 14, 2018

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/

@gkiar gkiar changed the title from Project Report: AFNI in Boutiques to Project Report: AFNI in Boutiques (& nipype) Sep 14, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment