"Official" way to use third-party tools? #253

Since ICA-AROMA seems to be a binary and part of FSL, you do not really have to integrate (i.e. add to MATLAB path). However, you should use checkrequirement of the corresponding module to ensure ICA-AROMA is installed.

rWLS and WDS, on the other hand, requires handling from within MATLAB (add to MATLAB path); therefore, they should be integrated via the toolbox framework (each toolbox separately):

1. You need to write interface (Class.m). See the toolboxes folder for inspiration.
2. The corresponding module should check, load, and unload the toolbox. See aamod_tdt_decode (lines 28-29, 188, 191) as an example.
3. Your (site-specific) parameterset should contain a corresponding toolbox entry. See aap_parameters_defaults_UoS.xml (lines 21-57)

Counter-offer: I PR my code as-is and you modify it to conform to the new interface. That would really help us out on this.

I suspect this would take you about a half hour. It would take me a month.

You think a bit too highly of me :), and I am afraid I will not have time for that. I also do not think it is a sustainable development model.

The question is whether you consider the toolbox framework a good solution. If yes, then it may be worth your time to invest now. If not, you may need to propose an alternative solution.

The main difficulty is I can find no documentation on writing an aa class interface. Is there any? Perhaps I am looking in the wrong place.

Since you have made the toolbox framework a prerequisite for aa development, you are obligated to provide such documentation.
For example, when I rewrote the testing utility, I provided an extensively commented example script (aatest_ds000114_TEMPLATE) that explains in detail how to write a testscript when a developer contributes new code. In contrast, there is no such example of a documented toolbox interface. What is required? What is optional? What do the options mean? How are they used? Where are they used? When are they used? There is no explanation whatsoever .In fact, I can't find even one comment in any of the examples in aa_tools/toolboxes..

The alternative is spending a month stepping though the toolbox code trying to figure out what it's supposed to do. I also do not think this is a sustainable development model.

You are absolutely right! We need proper documentation, and not only for the toolbox framework.
And I wish I had that that extra bandwidth you had for writing that extensive documentation (something similar should also go to the website, as well). However, I am not a professional developer, and I am not paid for the development of aa; therefor I feel "obligated" is a bit strong expectation. On the other hand, I do feel somewhat obligation to other fellow developers (that is you, mostly), if I expect them to build upon what I did; but I am not sure whether I am always be able to fulfil it. This is one of the main issues of the extracurricular/ open-source development.
When I took over aa, I had even less documentation, so I am used to "spending a month stepping though the code trying to figure out what it's supposed to do." And often I did not have access to the original developer(s), or even they did not know. :) And it is not a sustainable development model, either, indeed, but what could I do? So forgive me, if I am used to that. I thought those three short notes will be enough to go ahead, but I understand that they are not as extensive as your documentation.

This discussion goes beyond the current issue, and I am not even sure whether there is any answer for that apart from dedicated funding for open-source development. More importantly, I certainly do not have the bandwidth to provide documentation for everything I ever did with aa. Maybe if I had a different job. :)

You asked me about the "official" way to use third-party tools, and my "two cent" is the toolbox interface - even though it is still under construction (esp. in terms of documentation). Apart from (or before) that, there is/was nothing, which I strongly oppose. To provide an answer to your issue, at least, you either hold your PR until the toolbox interface is properly documented so that you feel confident implementing it, or you submit your PR now and extend it later. However, I would like to avoid "officially" encouraging different practices.

I don't disagree with anything you wrote, but it still leaves me with no solution. Our lab just finished a study that uses my new code, we can't submit our paper until my PR goes in, and my PR can't go in until rWLS and WDS get a class interface.

I'll run this past the boss and see what he wants to do.

There are multiple solutions:

1. You can cite your repository.
2. You can create a new branch in the main repository and merge your PR into it. Later, it can be merged into the master branch.

I have added some documentation for the toolbox framework to the website and updated the core concepts accordingly.

The same documentation will also be added to the toolboxes to keep it close to the code.

Please, take a look and let me know whether you find it instructive enough.

N.B.: It will also require a corresponding PR from me to work. I will submit it soon.

Thanks much. I'll have a look...

Matlab appears to require an extraparameters field appear in each toolbox entry, otherwise aa_init crashes on this:

if isfield(aap.directory_conventions,'toolbox') && isstruct(aap.directory_conventions.toolbox)
    for TBX = aap.directory_conventions.toolbox
        if strcmp(TBX.name,'spm'), continue; end
        aas_cache_put(aap,TBX.name,aas_inittoolbox(aap,TBX.name));
    end
end

Is there something you would recommend to replace doKeepInPath?

I find it odd, however, you can keep the fied empty, as well:

    <extraparameters></extraparameters>

It is also possible that this bug has been fixed by #255 only.