==========
Recordings
==========

The purpose of the :mod:`recordings` component is to group recorded signals that
are related (e.g. obtained from the same cell). We consider that each experiment consists
of one or more "recording blocks", each of which corresponds to one "recording
configuration". For example, for intracellular recordings with a glass electrode,
a recording block generally corresponds to one cell, i.e. one position of the
electrode. If the electrode is moved, this creates a new recording block. If the
amplifier or filter settings are changed, or the intra-electrode solution is
changed, this also creates a new recording block. For imaging data, a recording
block would correspond to one configuration (focal depth, etc.) of the microscope.

For a given recording configuration, the experimental preparation is generally
stimulated in some way and the response recorded. Each of these recordings we
call a "protocol recording" (a recording of the response to a given stimulation
protocol), so that a "recording block" contains one or more "protocol recordings".

This component depends on :mod:`experiment`, :mod:`stimulation` and :mod:`location`.

Recording blocks
----------------

A :class:`RecordingBlock` object is defined by a label and by the experiment to
which it belongs. Optionally you can also specify the start and end time of the
recording::

    >>> from helmholtz.recording.models import RecordingBlock
    >>> from datetime import datetime
    >>> block = RecordingBlock(experiment=expt, label="cellA", start=datetime(2010, 7, 18, 9, 18), end=datetime(2010, 7, 18, 11, 22))
    >>> block.save()

We assume the object ``expt`` was created previously, see :doc:`experiments`.
Now we need to specify the recording configuration, which holds information
about the recording device, the device configuration, and the device position::

    >>> from helmholtz.recording.models import RecordingConfiguration
    >>> rec_conf = RecordingConfiguration(block=block, device=pelectrode,
    ...                                   configuration=electrode_conf,
    ...                                   position=cellA_position)
    >>> rec_conf.save()
    
where we assume ``pelectrode`` (a :class:`helmholtz.electrophysiology.PatchElectrode` object),
``electrode_conf`` (a :class:`helmholtz.electrophysiology.PatchElectrodeConfiguration` object)
and ``cellA_position`` (a :class:`helmholtz.location.Position` object) have been
created earlier (see :doc:`electrophysiology` and :doc:`location`).

If recording with multiple devices at the same time, a separate :class:`RecordingConfiguration`
must be created for each, and all associated with the same :class:`RecordingBlock`.

Individual recordings in response to a particular stimulation protocol
----------------------------------------------------------------------

Suppose we apply two different stimulation protocols, ``stim1`` and ``stim2``,
created previously (see :doc:`stimulation`). To associate the recordings obtained
in response to each of these protocols with a :class:`RecordingBlock` object, we
create a :class:`ProtocolRecording` object for each::

    >>> from helmholtz.recording.models import ProtocolRecording
    >>> rec1 = ProtocolRecording(block=block, label="rec1", stimulus=stim1)
    >>> rec1.save()
    >>> rec2 = ProtocolRecording(block=block, label="rec2", stimulus=stim2)
    >>> rec2.save()

To see how the actual recorded signals are linked to the :class:`ProtocolRecording`
object, see :doc:`signals`.

Reference
---------

.. automodule:: helmholtz.recording.models

.. autoclass:: RecordingBlock
   :members:

.. autoclass:: RecordingConfiguration
   :members:
   
.. autoclass:: ProtocolRecording
   :members:
