Frequency Space Evolution of Pattern Forming Systems

These videos were rendered as part of the research for the paper "A Model for the Origin and Properties of Flicker-Induced Geometric Phosphenes". In this work, we showed how periodic stimulation (a uniform flickering light) could lead to emergence of geometric patterns in the brain's visual system. The videos below show the evolution of these patterns in the Fourier domain (spatial frequency space).

Magnitudes of Fourier Coefficients for evolution of Wilson-Cowen Pattern formation undergoing periodic stimulation. First : Stripe domain converges to a single orientation in frequency space, while Second : Hexagon forming domain converged to.. well, hexagons.

Videos from today

Python, Sphinx, and lambda functions

Some 80% of my code is generated by higher order functions or is declared as a lambda expression. Typically, this results in fewer total lines of code and good code reuse. The problem I am having is that these types of functions are not processed properly by the automatic documentation generator Sphinx.

This blog has a partial solution : directly assign values to __doc__ and __name__. This is, however, neither necessary nor sufficient to get the functionality we desire with Sphinx. You can document functions generated with higher order functions or lambda expressions like module variable by following them with a triple-quote string.

foo = lambda x:x
"""Identity function"""

Produces something like the following in the automatically generated documentation :

foo

Identity function

This is better, but not quite enough. We don't get the argument list, the some of the formatting is a bit odd. I'll let you know if I figure something out. At the moment I can't even figure out how to infer the argument list of a lambda function.

Update : the answer may have something to do with this :

It’s possible to override the signature for explicitly documented callable
objects (functions, methods, classes) with the regular syntax that will
override the signature gained from introspection:

.. autoclass:: Noodle(type)
 
   .. automethod:: eat(persona)

This is useful if the signature from the method is hidden by a decorator.

New in version 0.4.

Problem of the Day : Generating Sphinx documentation from Python doc-strings

Sphinx : a documentation generator for Python

Problem : Sphinx documentation is not clear (to me) on how to generate documentation from your Python doc-strings. At least, no obvious tutorial exists.

Possibly helpful links ( none of which actually solve this problem )

http://scienceoss.com/use-sphinx-for-documentation/

http://neuroimaging.scipy.org/site/doc/manual/html/devel/guidelines/sphinx_helpers.html

Steps so far :

First, I followed this tutorial to get Sphinx running and installed, and the basic example running. After this tutorial, you should have a working documentation directory that builds a minimal example of "index.rst" and "chapter1.rst"

Second, I tried adding ".. automodule:: numpy" to the top of the demo "chapter1.rst" file. I was pleasantly surprised to see this work, more or less. This inserted some basic numpy documentation into the minimal "chapter1.rst" file. I guess you'd probably have to have numpy installed and working for this to work.

Now what ? I think this means that I need to create a separate ".rst" file in the documentation source directory for every class, module, or source that I want to document.

I also need to figure out how to package my python code into an importable library so Sphinx can see it like numpy. From the Pyhon documentation : A module is a file containing Python definitions and statements. So, I guess each of my .py script files will need a to be turned into a module, and then a separate .rst file for each .py source file will need to be added to my documentation source directory.

All Python source files are automatically modules, with the name of the module as the name of the script file. Sphinx is somehow coupled to the iPython interpreter, I am told. If you can get your modules to be importable form iPython system-wide you'll be all set.

There should be some way to just tell the Sphinx autodoc "here is a python file, please automatically pull documentation out of it". As far as I can tell, there is not. Specifying absolute paths does not work.

This seems to work : add the directories containing your source files to the environment variable "PYTHONPATH". Then, at least the automodule feature will work if you pass it the name of your file ( without the name of extension ).

export PYTHONPATH="~/ahh":$PYTHONPATH

Turns out the the header stuff in the .rst file is necessary, otherwise Sphinx won't generate an entry for your module on the main index page. Also, "toctree" means "table of contents tree" ( I don't think this is explicitly stated in the Sphinx documentation ).

Ok, this is great. automodule seems to work. It looks like you need to manually create a new ".rst" file for every module you want to document, register them in the table of contents tree in "index.rst", then add an automodule command in these files and make sure your file/module is system-wide importable ( in PYTHONPATH ). This isn't exactly what I had in mind when I heard the workd "autodoc", but maybe I can write a script called "autoautodoc" that automates the .. automation ? of ? documentation ??

If you do something like this :

.. automodule:: foo

:members:

all the class files inside the module get displayed as well.

ok... thats nice. I guess I'll go write an auto-autodoc script now.

edit : here is my auto-autodoc scrip, which produces output which can be piped back to bash to perform requisite operations.

import re

files = '''orix
orix.matrix
orix.statistics
orix.device
orix.function
orix.plot
orix.sequence
orix.graph
orix.cpuutil
orix.logic
orix.gpufun 
orix.convolution
'''

print "cd ~/orix/doc"
print "rm *.rst orix.* mods.txt"

files = files.split('\n')

index = '''
Welcome to orix's documentation!
================================

Contents:

.. toctree::
   :numbered:
   :maxdepth: 2
   
'''

for f in files:
    fstring = f+'.rst'
    foo = r'\n'.join([f,''.join(['=']*len(f)),".. automodule:: %s"%f,"    :members:"])
    print 'touch %s'%fstring
    print 'echo -e "%s" >> %s'%(foo,fstring)
    print r'echo -e "%s\n" >> mods.txt'%fstring
    index = index + '   ' + fstring + '\n'

index = index + '''
  
Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
'''

index = r'\n'.join(index.split('\n'))
index = r'\`'.join(index.split('`'))
print 'echo -e "%s" >> index.rst'%index
print 'make clean'
print 'make latex'
print 'make html'
print 'cd _build/latex'
print 'make all-pdf'
print 'xpdf orix.pdf &'
print "cd ~/orix/doc"
print 'firefox ~/orix/doc/_build/html/index.html &'