.. currentmodule:: brian

Electrophysiology: models
=========================
The electrophysiology library contains a number of models of electrodes,
amplifiers and recording protocols to simulate intracellular electrophysiological
recordings.
To import the electrophysiology library::

  from brian.library.electrophysiology import *

There is a series of example scripts in the examples/electrophysiology folder.

Electrodes
----------
Electrodes are defined as resistor/capacitor (RC) circuits, or multiple
RC circuits in series. Define a simple RC electrode with resistance Re
and capacitance Ce (possibly 0 pF) as follows::

  el=electrode(Re,Ce)

The ``electrode`` function returns an :class:`Equations` object containing the
electrode model, where
the electrode potential is ``v_el`` (the recording), the membrane potential is ``vm``, the electrode current
entering the membrane is ``i_inj`` and command current is ``i_cmd``.
These names can be overriden using the corresponding keywords. For example, a membrane
equation with a .5 nA current injected through an electrode is defined as follows::

  eqs=Equations('dv/dt=(-gl*v+i_inj)/Cm : volt')+electrode(50*Mohm,10*pF,vm='v',i_cmd=.5*nA)

Specify ``i_cmd=None`` if the electrode is only used to record (no current injection). More complex
electrodes can be defined by passing lists of resistances and capacitances, e.g.::

  el=electrode([50*Mohm,20*Mohm],[5*pF,3*pF])

Amplifiers
----------
Current-clamp amplifier
^^^^^^^^^^^^^^^^^^^^^^^
A current-clamp amplifier injects a current through an intracellular electrode
and records the membrane potential. Two standard circuits are included to compensate
for the electrode voltage: bridge compensation and capacitance neutralization
(see e.g. the `Axon guide <http://www.moleculardevices.com/pages/instruments/axon_guide.html>`__).
The following command::

  amp=current_clamp(Re=80*Mohm,Ce=10*pF)

defines a current-clamp amplifier with an electrode modelled as a RC circuit. The function
returns an :class:`Equations` object, where
the recording potential is ``v_rec``, the membrane potential is ``vm``, the electrode current
entering the membrane is ``i_inj`` and command current is ``i_cmd``.
These names can be overriden using the corresponding keywords.
For implementation reasons, the amplifier always includes an electrode.
Optionally, bridge compensation, can be used with the ``bridge`` keyword and capacitance
neutralization with the ``capa_comp`` keyword. For example, the following instruction defines
a partially compensated recording::

  amp=current_clamp(Re=80*Mohm,Ce=10*pF,bridge=78*Mohm,capa_comp=8*pF)

The capacitance neutralization is a feedback circuit, so that it becomes unstable if
the feedback capacitance is larger than the actual capacitance of the electrode.
The bridge compensation is an input-dependent voltage offset (``bridge*i_cmd``), and
thus is always stable (unless an additional feedback, such as dynamic clamp, is provided).
Note that the bridge and capacitance neutralization parameters can be variable names, e.g.::

  amp=current_clamp(Re=80*Mohm,Ce=10*pF,bridge='Rbridge',capa_comp=8*pF)

and then the bridge compensation can be changed dynamically during the simulation.

Voltage-clamp amplifier
^^^^^^^^^^^^^^^^^^^^^^^
The library includes a single-electrode voltage-clamp amplifier, which
clamps the potential at a given value and records the current going through
the electrode.
The following command::

  amp=voltage_clamp(Re=20*Mohm)

defines a voltage-clamp amplifier with an electrode modelled as a pure
resistance.
The function
returns an :class:`Equations` object, where
the recording current is ``i_rec``, the membrane potential is ``vm``, the electrode current
entering the membrane is ``i_inj`` and command voltage is ``v_cmd``
(note that ``i_rec`` = - ``i_inj``).
These names can be overriden using the corresponding keywords.
For implementation reasons, the amplifier always includes an electrode.
Electrode capacitance is not included, meaning that
the capacitance neutralization circuit is always set at the maximum value.
The quality of the clamp is limited by the electrode or ''series'' resistance,
which can be compensated in a similar way as bridge compensation in current-clamp
recordings. Series resistance compensation consists in adding a current-dependent
voltage offset to the voltage command. Because of the feedback, that compensation needs
to be slightly delayed (with a low-pass circuit). The following example defines a
voltage-clamp amplifier with half-compensated series resistance and compensation delay
1 ms::

  amp=voltage_clamp(Re=20*Mohm,Rs=10*Mohm,tau_u=1*ms)

The ``tau_u`` keyword is optional and defaults to 1 ms.

Acquisition board
^^^^^^^^^^^^^^^^^
An acquisition board samples a recording
and sends a command (e.g. injected current)
at regular times. It is defined as a
:class:`NeuronGroup`.
Use::

  board=AcquisitionBoard(P=neuron,V='V',I='I',clock)
 
where ``P`` = neuron group (possibly containing amplifier and electrode),
``V`` = potential variable name,
``I`` = current variable name,
``clock`` = acquisition clock. The recording variable is then stored in
``board.record`` and a command is sent with the instruction ``board.command=I``.

Discontinuous current clamp
^^^^^^^^^^^^^^^^^^^^^^^^^^^
The discontinuous current clamp (DCC) consists in alternatively injecting current
and measuring the potential, in order to measure the potential when the voltage
across the electrode has vanished. The sampling clock is mainly determined by the
electrode time constant (the sampling period should be two orders of magnitude larger
than the electrode time constant).
It is defined and used in the same way as an acquisition board (above)::

  board=DCC(P=neuron,V='V',I='I',frequency=2*kHz)

where ``frequency`` is the sampling frequency. The duty cycle is 1/3
(meaning current is injected during 1/3 of each sampling step).

Discontinuous voltage clamp
^^^^^^^^^^^^^^^^^^^^^^^^^^^
The discontinuous voltage clamp or single-electrode voltage clamp (SEVC) is
an implementation of the voltage clamp using a feedback current with a DCC
amplifier. It is defined as the DCC::

  board=SEVC(P=neuron,V='V',I='I',frequency=2*kHz,gain=10*nS)

except that a gain parameter is included. The SEVC injects a negative
feedback current I=gain*(Vcommand-V). The quality of the clamp improves with
higher gains, but there is a maximum value above which the system is unstable,
because of the finite temporal resolution.
The recorded current is stored in ``board.record`` and the command voltage is sent
with the instruction ``board.command=-20*mV``.
With this implementation of the SEVC, the membrane is never perfectly clamped.
A better clamp is obtained by adding an integral controller with the keyword
``gain2=10*nS/ms``. The additional current J(t) is governed by the differential
equation dJ/dt=gain2*(Vcommand-V), so that it ensures perfect clamping in the
stationary state.
However, this controller does not improve the settling time of the clamp, but
only the final voltage value.

Active Electrode Compensation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The electrophysiology library includes the Active Electrode Compensation (AEC) technique
described in Brette et al (2008),
`High-resolution intracellular recordings using a real-time computational model of the electrode
<http://www.di.ens.fr/~brette/papers/Brette2008Neuron.html>`__,
Neuron 59(3):379-91.

It can be applied offline, or online, using the models of experimental setup
described above.
(for dynamic-clamp or voltage-clamp recordings, the electrode compensation must be
done online). An AEC board is initialized in the same way as an acquisition board::

  board=AEC(neuron,'V','I',clock)

where ``clock`` is the acquisition clock. The estimation phase typically looks like::

  board.start_injection()
  run(2*second)
  board.start_injection()
  run(100*ms)
  board.estimate()

where white noise is injected for 2 seconds (default amplitude .5 nA).
You can change the default amplitude and DC current as follows:
``board.start_injection(amp=.5*nA,DC=1*nA)``.
After estimation, the kernel is stored in ``board.Ke``.
The following options can be passed to the function ``estimate``:
``ksize`` (default 150 sampling steps), ``ktail`` (default 50 sampling steps)
and ``dendritic`` (default ``False``, use ``True`` is the recording is a thin
process, i.e., axon or dendrite).
Online compensation is then switched on with ``board.switch_on()``
and off with ``board.switch_off()``. For example, to inject a .5 nA current
pulse for 200 ms, use the following instructions::

  board.switch_on()
  board.command=.5*nA
  run(200*ms)
  board.command=0*nA
  run(150*ms)
  board.switch_off()

During the simulation, the variable ``board.record`` stores the compensated
potential.
