[pymvpa] Handling of references

[Michael Hanke]

Hi,

On Tue, Oct 07, 2008 at 10:35:13AM +0200, Emanuele Olivetti wrote:
> Even though it is not about visualizing performance of classifiers,
> a related nice article about (statistical) comparison of classifiers
> (that you could be interested in) is this one:
> 
> http://jmlr.csail.mit.edu/papers/volume7/demsar06a/demsar06a.pdf
Thanks for the reference.

However, I usually do not find the time to read such paper the moment I
get the reference -- even worse I tend to forget to read them later on.
The only choice left for me is to query google for something I don't
exactly know what it is :(

Reading Emanuele's post, I thought to try to change that for the
MVPA-related literature (at least).

I have implemented a bibtex-like reference handling for the PyMVPA
manual. RsT and Sphinx do not handle it well, so I have written a python
script to convert the content of a bibtex file into RsT, while
automatically adding DOI and other URLs, a short summary if available,
keywords to be put into the manual index and proper link targets for
cross-references throughout the manual. From now on we can cite stuff
much like it would be done in LaTeX.

Emanuele's hint would look like this (and actually does look like it, as
I have added it to the bib file):

@Article{ Dem06,
        author = "Janez Demšar",
        title = "Statistical Comparisons of Classifiers over Multiple Data Sets",
        journal = "Journal of Machine Learning Research",
        volume = "7",
        year = "2006",
        issn = "1533-7928",
        pages = "1–30",
        publisher = "MIT Press",
        address = "Cambridge, MA, USA",
        url = "http://portal.acm.org/citation.cfm?id=1248548",
        pymvpa-summary = "This is a review of several benchmarks procedures."
}

The script understands to custom bibtex fields:

- 'pymvpa-summary' contains a terse summary of why this is interesting in
    the MVPA context.

- 'pymvpa-keywords' is a comma-separated list of keywords, that will
    appear in the manual index

Additionally, the script can also handle DOI strings and puts proper
URLs in the generated table.

A reference in the manual to this article looks like this:

  :ref:`Demšar (2006) <Dem06>`

which would set a link to the corresponding item in the reference list.
To make paper such as the above work, the whole thing assumes UTF8
encoding of the bib file -- which can easily be done with eg. kbibtex.

Here is what it looks like:

  http://www.pymvpa.org/references.html

Currently, the script uses python-bibtex to read the file. I did not
want to add that as a build-dep. so `make references` will generate the
references.txt offline, which is then shipped in the released tarball.

Hope you like it,


Michael

-- 
GPG key:  1024D/3144BE0F Michael Hanke
http://apsy.gse.uni-magdeburg.de/hanke
ICQ: 48230050