=======
Species
=======

The purpose of the :mod:`species` component is to store lists of animal species and strains.
The species model is currently built on the `Catalogue of Life`_, although you are not obliged to use data from that catalogue: if you
only need a small number of species, it is probably easier to just enter them directly.

Note that if you use the Catalogue of Life data, and your database is publicly available on the web, you need to obtain permission
from the Species 2000 Secretariat, and to give precise credits:
see http://www.catalogueoflife.org/annual-checklist/2010/info/copyright.

The strain model is rather generic. In future we may extend it to support databases such as the `International Mouse Strain Resource`_.

Adding a single species to the database
---------------------------------------

::

  >>> from helmholtz.species.models import Species
  >>> rat = Species(scientific_name="Rattus norvegicus",
  ...               english_name="Norway rat",
  ...               id=180363,
  ...               lsid="urn:lsid:catalogueoflife.org:taxon:d84c04d4-29c1-102b-9a4a-00304854f820:ac2010",
  ...               url="http://www.itis.gov/servlet/SingleRpt/SingleRpt?search_topic=TSN&search_value=180363")
  >>> rat.save()


Populating the species database from the Catalogue of Life
----------------------------------------------------------

.. NOTE [Thierry: how to download the .csv files?]

::

  $ python manage.py populate_species


Adding a strain to the database
-------------------------------

::

  >>> from helmholtz.species.models import Species, Strain
  >>> norveg = Species.objects.get(english_name="Norway rat")
  >>> wistar = Strain(name="Wistar", species=norveg)
  >>> wistar.save()


Reference
---------

.. automodule:: helmholtz.species.models

.. autoclass:: Species

    .. attribute:: id
    
        if using the Catalog of Life, the Catalog of Life unique identifier, otherwise any unique integer: autogenerated if not supplied.
    
    .. attribute:: scientific_name
        
        e.g. "Rattus norvegicus"
    
    .. attribute:: english_name
    
        e.g. "Norway rat"
    
    .. attribute:: codename
    
        ???
    
    .. attribute:: lsid
    
        the `Life Science Identifier`_ for this species.
    
    .. attribute:: url
    
        the URL of a resource giving more detail on this species
    
.. autoclass:: Strain
    
    .. attribute:: name
    
        e.g. "Wistar", "domestic shorthair", "129/Sv"
    
    .. attribute:: species
    
        a :class:`Species` instance
    
    .. attribute:: genotype
    
        currently a free-form field, which could be used for indicating information about hybrids, for example.
    
    .. attribute:: notes
    
        anything which doesn't fit in any other field. (May be removed in future, since :class:`helmholtz.annotations.Annotation` can be used instead and is more flexible).


.. _`Catalogue of Life`: http://www.catalogueoflife.org/
.. _`International Mouse Strain Resource`: http://www.findmice.org/
.. _`Life Science Identifier`: http://en.wikipedia.org/wiki/LSID