[JOSS Review] Functionality documentation and non-GUI use

[billbrod]

The documentation currently does not include documentation of the code for fRAT, focusing on a (very thorough!) tutorial for how to use it. My guess is you plan to only encourage / support use through the GUI, is that correct? In that case, I think documentation of the underlying functions is not necessary, but I do think you should provide more documentation of the different options in the GUI (see the BET user guide for an example from FSL). Some of this information is included in the tutorial, but it should be pulled out into its own page. For example, under Parsing, what are the possible critical parameter values (and actually, why is this a free text field, rather than a checklist? if I'm understanding it correctly). What is SENSE and is it an alternative or complementary to Multiband? Or, under Analysis -> Outlier detection, what does checking Noise cutoff do? Or Gaussian outlier (GauO) detection? It doesn't need to be exhaustive (for example, the various file name and most of the plotting fields are pretty self-explanatory), but the critical ones should be documented (and that can often be a one-line explanation with a reference or link for existing methods).

https://github.com/openjournals/joss-reviews/issues/5200

[elliohow]

My guess is you plan to only encourage / support use through the GUI, is that correct?

Yes currently I only support use of fRAT through the GUI currently.

but I do think you should provide more documentation of the different options in the GUI (see the BET user guide for an example from FSL). Some of this information is included in the tutorial, but it should be pulled out into its own page. For example, under Parsing, what are the possible critical parameter values (and actually, why is this a free text field, rather than a checklist? if I'm understanding it correctly). What is SENSE and is it an alternative or complementary to Multiband? Or, under Analysis -> Outlier detection, what does checking Noise cutoff do? Or Gaussian outlier (GauO) detection? It doesn't need to be exhaustive (for example, the various file name and most of the plotting fields are pretty self-explanatory), but the critical ones should be documented (and that can often be a one-line explanation with a reference or link for existing methods).

There are tooltips that explain the function of the parameter settings when you hover over them in the GUI, but I definitely plan to expand on these in the future in the documentation. Is it sufficient for now to add this to the future additions page on the documentation and expand on what is currently there in the future?

[billbrod]

Yes currently I only support use of fRAT through the GUI currently.

Sounds good.

There are tooltips that explain the function of the parameter settings when you hover over them in the GUI, but I definitely plan to expand on these in the future in the documentation. Is it sufficient for now to add this to the future additions page on the documentation and expand on what is currently there in the future?

Oh I missed the hovering. In that case, yes, with two small steps:

• put something in your docs about how hovering over the name of the option gives additional info (not the entry field, which is why I missed it).
• put some information about SENSE and Multiband into the docs, with a link or reference, since they are important. Multiband I've heard of, but it's not clear to me what it means here (I tend to think of it in the context of acquisition, not analysis, but that might be me), and I've never heard of SENSE.

[elliohow]

I've expanded on what the critical parameters setting is in the ROI tutorial, ill add the note about the tooltips too:

Next, enter the Parsing page found under the “Settings” panel in the GUI. The critical parameters setting indicates what the independent variables of the experiment are and will be used when labelling plots and creating the parameter csv file, whereas the critical parameters abbreviation setting indicates how these variables are represented in the filenames of the scans (if at all). For example, the critical parameters option may contain “Multiband, SENSE”, whereas the “critical parameters abbreviation” option will instead contain “mb, s”. In this case, the file name P1_MB3_S2_matchBW.nii will represent that Multiband 3 and SENSE 2 were used.

Note

The critical parameter settings are used to supply the names and file name abbreviations of the independent variables, therefore fRAT supports the use of any parameters (and any number of them).

If critical parameters is left blank, the ROI analysis will combine all datasets, regardless of the independent variable used for each file. This can be useful for calculating tSNR across the entire dataset, if the independent variable does not affect tSNR.

To prevent confusion, I could remove Multiband and SENSE from those fields altogether. They are only there because im using fRAT to investigate how different acquisition parameters effect data quality metrics (specifically looking at multiband and SENSE) and how this changes for each region of the brain, but that field could contain anything.

[billbrod]

Yes that's much clearer. I'd still pull some of this info out to a different part of the docs as well, so it's easy to refer to. Or at least make it clear that everyone should go through the tutorial. My default assumption would be that I don't need to look through it if I understand how ROI analysis works, but the tutorial also includes key information about the tool works. That is, I originally thought the tutorial was only introducing the scientific concepts, but it is also introducing technical ones. So changing the wording on the docs index to say "To learn how to use fRAT, see this tutorial", instead of "To learn how to run an ROI analysis, follow this tutorial" would clarify that.

[elliohow]

So changing the wording on the docs index to say "To learn how to use fRAT, see this tutorial", instead of "To learn how to run an ROI analysis, follow this tutorial" would clarify that.

Good point, I've updated the documentation with your recommended wording.

[billbrod]

Excellent, this looks good to me then!