fMRwhy and Binder

[negatoscope]

This is an ongoing attempt to port the fMRwhy Toolbox as a tutorial in a Jupyter Notebook running Octave on Binder.

The repository can be launched following this link:

This Binder build installs fMRwhy along with its required dependencies (SPM12, bids-matlab, dicm2nii, TAPAS (PhysIO) and RainCloudPlots).

It also fetches one subject's data from from dataset ds002748 in OpenNeuro, including its anatomical and functional images and its dataset_description.json file.

Also, a custom fmrwhy_settings_template.m was created in the Home folder.

So far, when running fmrwhy_workflow_qc I've encountered a couple of issues which have been partially solved:

• Some scripts include a Matlab-only function called contains. Octave function strfind can be used instead. I found it in fmrwhy_bids_setupQcSubDirs.m, but it might be in other scripts as well.
• After replacing said function, fmrwhy_workflow_qc is able to succesfully create the options structure. Nevertheless, the anatomical and functional images aren't copied to the derivatives/fmrwhy-preproc/sub-01/ folder. I'm still not very familiar with toolbox, but I'm trying to backtrace the problem (I suspect the solution is simple). It shows the following error:

error: structure has no member 'folder'
error: called from
    fmrwhy_bids_setupQcSubDirs at line 46 column 26
    fmrwhy_workflow_qc at line 52 column 13

• If I manually copy/paste and gunzip the anat and func folder, it goes through and starts preprocessing (func-anat coregister, segment, reslice) but stops after 'Realign: Estimate' with another Matlab/Octave compatibility error:

warning: the 'array2table' function is not yet implemented in Octave

So, as a first step we could try and solve the copy/paste and gunzip issue and then continue debugging.

[jsheunis]

Awesome, thanks for writing this up @negatoscope!!

I think a sensible way forward is to create a new issue for the MATLAB to Octave conversion. Then in that issue we can track all such changes (such as the contains --> strfind) across the whole toolbox code base.

And then, I think the error: structure has no member 'folder' problem is also a MATLAB-Octave inconsistency. Looks like the Octave dir function does not output a folder field. We'll probably bump into a number if such inconsistencies going forward...

Regarding the array2table issue (and other ones), we could look into how SPM12 handles such tasks, since I think they would probably already have solved many MATLAB/Octave inconsistencies.

[negatoscope]

The semester is over for me, so I've put some time to this and I've made some progress.

Mainly, there are some functions that exist in Matlab but are not implemented yet in Octave. Here are some the changes applied across the fmrwhy_bids_preprocFunc.m and fmrwhy_bids_preprocMultRegr.m scripts so far:

1. contains --> strfind: Functionally similar.
2. array2table --> struct: Tables are not natively supported in Octave. Alternatives exist (dataframe, tablicious packages) but are hard to manage, and currently can't be written in a file. My (unelegant) workaround was to manually build structs, fusing the data in question with its corresponding column names. These names can't be read afterwards, so when loading the output file, the first row (names) must be handled with (the revelant code chunk I wrote deletes it).
3. writetable --> tdfwrite: Functionally similar. Needs custom script (can be found in the scripts folder).
4. tdfread --> dlmread: Functionally similar.
5. normc: Installed and loaded the miscellaneous package that includes it.

With this, fmrwhy_workflow_qc.m manages to go through the whole preprocessing pipeline and makes the multiple regressors needed for quality control. It even prints out some nice images in the command line (which doesn´t happen on Octave on my PC!):

You can see the entire current output by opening the "command_line" notebook. Next, I will try to figure out how to index the "ax" variable in script fmrwhy_util_createOverlayMontage.m.

PD: @jsheunis I know you suggested to start a new issue to track these changes, but I wasn´t sure how to do it without it being too similar with what I've already done with this issue. How should I proceed? Is there a template or anything to guide me? Feel free to delete this comment too if needed!

[jsheunis]

Thanks for the great update @negatoscope! Great to see that the pipeline is running almost in full! It's interesting to see the visual output, since I don't think theres an explicit call to display the image/figure axes. I'm guessing that right when the error occurs, the current axis is output to the command line? It's also interesting to see the long command line output in Octave, which differs from Matlab. That might need some work in future to align between different environments, but it's not a high priority at the moment.

Since this issue that we are working on currently is mainly about having the workflow run on Binder (with Octave) I think it will be good to track the Matlab-Octave conversion/compatibility aspects in a separate issue (or rather multiple issues) since then it will be easier to reference them individually. The GitHub search functionality of multiple issues will also make it easier to see that conversion of specific functions/modules are being addressed or have already been addressed. If for example in future we find similar bugs in other parts of the code, then contributors can more easily look up what has already been done. So i suggest we create a new issue per Matlab-Octave function that needs to be changed, and then the individual issues can be used to discuss the proposed changes as well as highlight all the different parts in the code base where the update will need to be made. Essentially this means creating a new issue per item in your numbered list. I can create a new tag called "MATLAB/Octave consistency" or something that we can then put on the issue, so they are easily recognisable.

Am I making sense?

[negatoscope]

Yes, it makes complete sense, thanks for the clarification! I shall proceed in that way then!