=================
Neural structures
=================

The purpose of the :mod:`neuralstructures` component is to represent neural
structures, from the cell up to the level of the brain.

This component depends on :mod:`helmholtz.species` and :mod:`helmholtz.annotation`.

Brain regions
-------------

If all the data in your database will come from only a small number of brain
regions, it may be easiest to simply enter these by hand::

    >>> from helmholtz.neuralstructures.models import BrainRegion
    >>> h = BrainRegion(species=rat, english_name="hippocampus")
    >>> h.save()
    >>> ca1 = BrainRegion(species=rat, english_name="CA1", parent=h)
    >>> ca1.save()

Here we assume that ``rat`` has been created previously (see :doc:`species`).

If you wish a more exhaustive list of brain regions, you can use one of the
resources available on the web. Here we use the NeuroNames nomenclature for the
Swanson atlas, downloadable as a Microsoft Excel spreadsheet from http://braininfo.rprc.washington.edu/Nnont.aspx.
We use the Python ``xlrd`` package, available from http://pypi.python.org/pypi/xlrd/.

    >>> from helmholtz.neuralstructures.models import Atlas
    >>> swanson = Atlas(name="Swanson")
    >>> swanson.save()
    >>> import xlrd
    >>> book = xlrd.open_workbook('NN2007MouseandRatNomenclatures.xls')
    >>> data = book.sheet_by_name('Swanson')
    >>> for i in range(1, data.nrows):
    ...     name, abbrev = data.cell(i,0).value, data.cell(i,1).value
    ...     br = BrainRegion(species=rat, english_name=name,
    ...                      abbreviation=abbrev, atlas=swanson)
    ...     br.save()
    >>> BrainRegion.objects.count()
    800
    >>> BrainRegion.objects.filter(atlas="Swanson").count()
    798

Note that a count of all brain regions includes the two we created by hand above,
but we can filter by the atlas to get just the ones we read from the spreadsheet.
Now let's list the first five entries from the nomenclature::

    >>> BrainRegion.objects.filter(atlas="Swanson").all()[:5]
    [<BrainRegion: abducens nucleus>, <BrainRegion: accessory abducens nucleus>,
     <BrainRegion: accessory facial nucleus>, <BrainRegion: accessory olfactory bulb>,
     <BrainRegion: accessory olfactory bulb, glomerular layer>]
    
Here we've used only a subset of the information available in the spreadsheet. In
particular we have not used the information about the hierarchy of brain regions.
This is left as an exercise for the reader!


Cell types
----------
    
Cell types work in a similar way to brain regions::

    >>> from helmholtz.neuralstructures.models import CellType
    >>> pkj = CellType(english_name="Purkinje cell")
    >>> pkj.save()

    
Reference
---------

.. automodule:: helmholtz.neuralstructures.models

.. autoclass:: Atlas
   :members:

.. autoclass:: BrainRegion
   :members:

.. autoclass:: CellType
   :members:

.. autoclass:: Cell
   :members:
    