[Neuroimaging] Looking for advice regarding releasing some analysis software

[Yaroslav Halchenko]

Great question(s) and answers so far!  a bit more to the plate:

On Thu, 16 Jun 2016, Ariel Rokem wrote:
> > For the last few years my lab has been doing time delay analysis on fMRI
> > and concurrent fMRI/NIRS data, and I’ve written a number of python tools
> > for performing the analysis, and they’ve been refined for several years at
> > this point, and I think they could be generally useful to people, so I’m
> > looking to release the software.  I’m fairly new at this, and I’ve found a
> > bunch of recommendations on how to do this, some of which are
> > contradictory.  I’d appreciate any help I could get on this.

> > What I’ve done so far:
> > 1) Chosen a license (Apache 2, based on a lot of reading and some
> > conversations)
> > 2) Put the core programs up on github (
> > https://github.com/bbfrederick/delaytools)
> > 3) Tried to put together rudimentary documentation and installation
> > directions.

> > As things exist now, if you install the prerequisites, download the code,
> > and add the main directory to your path, you should be able to run the
> > tools, which is a fine start, but there seems to be a lot more to
> > installation than that (automatically installing dependancies and all that)
> > that I’m unable to figure out. I’d appreciate any feedback on this.  I’m a
> > little mystified by the vagaries of constructing a setup.py file, and what
> > constitutes a ‘package’ and a ‘module’.


> You might find this template project useful:
> https://github.com/uwescience/shablona
> It has examples for some of these things (including testing and
> documentation)


I cannot stress enough on necessity to test scientific code. So I would

1. move actual functionality from bin/* scripts under delaytools/
modules, and just import/invoke them within the bin/scripts


2. now, that you have that functionality straight in the module, you
could test it 'easier', so provide delaytools/tests/ and start working
on them.



> > Some of the questions I have:
> > 1) In addition to the main program, I have scads of command line utilities
> > that make preparing and interpreting the data easier - do I just put them
> > all in the top level directory, or in a bin directory?


> You can put these in a bin directory and install them using the `scripts`
> kwarg to the `setup` function. Shablona doesn't have that, but here's how
> it happens on Dipy: https://github.com/nipy/dipy/blob/master/setup.py#L216

depending on 'philosophy' to follow (trust setuptools or not ;) ),
you could even generate those scripts automagically by setuptools, so
they would be appropriately generated even on Windows.  See e.g.

https://github.com/duecredit/duecredit/blob/master/setup.py#L96


I then usually do 'pip install -e .' (within virtualenv) so those entry
point scripts get generated, and available within virtualenv while
referring to actual development copy of the code.


Also please take example from dipy and others to use consistent prefix
for your commands (e.g. dt_ ?) so users could easily find/complete them
in their shell  and/or provide the "gateway" script (delaytools)
which would execute/pass options to corresponding script/module.
Similar to how git, git-annex, cmtk, datalad, ... are doing ;)

> > 2) The dependancies for the majority of the tools are very simple (numpy,
> > scipy, scikits-learn, matplotlib, nibabel), but there’s a kind of useful
> > gui tool that requires pyqt4 and pyqtgraph - pyqt does not seem to be
> > installable with pip, so I’m not sure how to handle that (installing it all
> > with anaconda is easy though). How should I handle this?


> I would handle that as an optional dependency, that only gets imported when
> it's needed. Another Dipy story: we use VTK in some visualizations, but
> this is an optional dependency. As of recently, we try to raise an
> informative error when the import is triggered in the absence of VTK.
> Something like:"you are trying to use a feature that requires pyqt and
> pyqtgraph, for instructions on installing these see https://
> <https://github.com/bbfrederick/delaytools>bbfrederick
> <https://github.com/bbfrederick/delaytools>.github.io/delaytools
> <https://github.com/bbfrederick/delaytools>/documentation/installtion/optional/install.html"
> would be helpful, I think.

I would also recommend to use 'extras_require' for setup call, so you
could create one 'gui' where you would list those which you could
install via pip, then if someone does

pip install delaytools[gui]

it would install core dependencies and those needed for GUI.

Needless to say that having a Debian package would probably make
installation really easy on any debian-based (and may be soon windows
;-)) platform.

> 3) What’s the best way to publicize this?  This won’t be useful if nobody
> > can find it.

> Announcing your releases to this list (and other lists where potential
> users hang out) is a good idea. Presenting it at conferences also helps
> spread the word. Another idea: you can write a paper about your software,
> so that people can make reference to your software when using it (see
> recent conversation about that here:
> https://mail.python.org/pipermail/neuroimaging/2016-April/000875.html).

> I hope that all helps and I am sure others will chime in with their
> ideas/opinions,

when you are ready, I would be happy to (re)tweet  and publicize
otherwise.  Also would be nice if

- for those references you listed in README.md you make hyperlinks, so
people could immediately go to them

- some specific examples/pipelines demonstrated specific uses of the tools

- I would encourage to provide  duecredit entries pointing to
  corresponding publications which you want to have cited when
  particular method is used, and/or pointing to good uses of them (IIRC
  'edu' tag for those in duecredit entries).

  shablona already has some examples, or have a look e.g. at pymvpa:

  https://github.com/PyMVPA/PyMVPA/blob/6a9d4060ad863f99170801854c272b61af51f015/mvpa2/__init__.py#L178
  https://github.com/PyMVPA/PyMVPA/blob/master/mvpa2/algorithms/hyperalignment.py#L170
  https://github.com/PyMVPA/PyMVPA/blob/master/mvpa2/algorithms/searchlight_hyperalignment.py#L52



-- 
Yaroslav O. Halchenko
Center for Open Neuroscience     http://centerforopenneuroscience.org
Dartmouth College, 419 Moore Hall, Hinman Box 6207, Hanover, NH 03755
Phone: +1 (603) 646-9834                       Fax: +1 (603) 646-1419
WWW:   http://www.linkedin.com/in/yarik