Workflow recommended citations

[alexsavio]

Hi,

With large workflows it is complicated to search through all references that you should cite by using one or another interface.
Do you think it would be useful to have a member in each interface that is a list of citations? So in the end you can call a function from workflow that builds the whole list of recommended references?

[satra]

@alexsavio - there is a package called duecredit that solves this. however, this would require effort to add these to each interface.

[alexsavio]

I understand there would be some effort. I am also afraid that this could bring some personal conflicts if we 'forget' a specific reference. I am available to do it, but I was wondering if you would find it a good contribution and, if yes, which approach would you like me to use.

[arokem]

From the peanut gallery: I recently integrated duecredit into our library
template project, and it was really not a lot of work (for a very small
package! uwescience/shablona#29). You drop in one
module into the library, and then add some annotations with the relevant
DOIs and just a bit of metadata to each one of the interfaces (admittedly,
that will be a bit more work on something as big as nipype...), and then
the rest should be taken care of by duecredit itself. CC: @yarikoptic and
@mvdoc can also help with guidance on the right approach.

I agree that you want to be as complete as possible, giving credit where
credit is due. On the other hand, I wouldn't worry about that too much. If
someone feels that your code isn't giving them due credit, they can put in
a PR to fix it.

On Mon, May 2, 2016 at 7:38 AM, Alexandre M. S. notifications@github.com
wrote:

I understand there would be some effort. I am also afraid that this could
bring some personal conflicts if we 'forget' a specific reference. I am
available to do it, but I was wondering if you would find it a good
contribution and, if yes, which approach would you like me to use.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub
#1464 (comment)

[satra]

@alexsavio - let's do it.

@arokem - i completely agree that this may be incentivizing for people to insert/fix their doi's when we don't get it right :)

among other extensions of this idea, would be to automate the writing of a methods/supplementary methods section for people using nipype workflows and/or provenance capture.

[alexsavio]

@satra. yes, this also came out when discussing with a colleague: having the methods paragraph written out of a workflow. We could add some markov chain to add some variance to the paragraphs. XD

[alexsavio]

Nice, I will be filling this spreadsheet with references and soon will make a first PR with the first ones:
https://docs.google.com/spreadsheets/d/1InqHP3ZQYlWBM7jUHH8mddnDHwmaPgd2n3PgcOrtUQk

[alexsavio]

Hi,

I added the credits to the spm interface as an example. I am not sure if I should add the references directly as a decorator to each nipype interface or keep a separate refs.py file in each interface folder. The latter is done here:
https://github.com/alexsavio/nipype/tree/enh/duecredit/nipype/interfaces/spm

What is in your opinion the best approach @satra @yarikoptic ?

[satra]

@alexsavio - for the interfaces, i think we should add the references as metadata to each interface references_ = []

and then in the base interface class decorate the run command and augment the help command to use these references.

[yarikoptic]

I guess for a 'duecredit' way

• citation of spm as a whole could be most appropriate by decoration of SPMCommand._run_interface, then running any spm command (I guess they all invoke this _run_interface) would result in a spm citation.
• as we discussed during lunch with @mvdoc, for subclasses where there is no explicit overloaded method(s) which could be decorated to make the use of those instances/methods explicit, we could "decorate" the class while extending @due.cite options with ability to specify which methods to decorate (run?), which then would create those methods in derived classes solely for citation tracking while delegating actual execution to superclass... I could implement that if we decide that it is the viable way to go
  But neither of those yet deals with enhancing docstrings for the classes, which I guess could be done (especially if decorating entire class), or we (in duecredit) may be could just pick up nipype's references_ if they are consistently defined and "tagged".

[alexsavio]

I pushed an interpretation of what @satra suggests. Might still need some fixes.

Please look at my changes in nipype/interfaces/base.py and nipype/interfaces/spm/base.py.

I am not using the duecredit decorators in this case. I guess, unless I implement a decorator to use duecredit, the duecredit decorators wouldn't allow me to use the references in the help function and also in the run.

[yarikoptic]

cool -- I have left few comments on alexsavio@cc341df#diff-9208df2bc74d92af5581c683cc78f91f

[alexsavio]

Hi @satra, it seems that the duecredit decorators allow you to declare references without having duecredit installed in the environment, i.e., it wouldn't raise an exception when it doesn't find the methods in the environment.
The features you ask would either require to add duecredit as a dependency or to ask the duecredit team to add more features.
IMO adding duecredit as a dependency is not a huge problem and would give a bit more flexibility to implement this. What do you think?