[Neuroimaging] Looking for advice regarding releasing some analysis software

Thu Jun 16 11:39:06 EDT 2016

On Thu, Jun 16, 2016 at 8:01 AM, Yaroslav Halchenko <lists at onerussian.com>
wrote:

> 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).
>
>
One more idea for publicizing is the nipy.org website. As long as you think
that you would like to abide by the code of conduct (
http://nipy.org/conduct.html), you can add your software to the front page
of the website. You can also write some blog posts to demonstrate the use
of the software, or to describe the software. Details for contributing are
here:  http://nipy.org/contribute.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
> _______________________________________________
> Neuroimaging mailing list
> Neuroimaging at python.org
> https://mail.python.org/mailman/listinfo/neuroimaging
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/neuroimaging/attachments/20160616/b106f0f3/attachment-0001.html>