.. _tutorialsinglecell: A simple single-cell model ========================== Building and testing detailed models of individual cells, then optimizing their parameters is usually the first step in building models with multi-compartment cells. Arbor supports a *single-cell model* workflow for this purpose, which is a good way to introduce Arbor's cell modelling concepts and approach. .. Note:: **Concepts covered in this example:** 0. The Arbor library and units. 1. Intro to morphologies. 2. Intro to region and locset expressions. 3. Intro to decors and cell decorations. 4. Building a :class:`arbor.cable_cell` object. 5. Building a :class:`arbor.single_cell_model` object. 6. Running a simulation and visualising the results. .. _tutorialsinglecell-cell: Setup and introduction to units ------------------------------- We begin by importing the Arbor library and its unit support. .. literalinclude:: ../../python/example/single_cell_model.py :language: python :lines: 4-5 As we will refer to both quite often, we assign aliases ``A`` and ``U``, to minimize typing. Over the course of this introduction, you will notice that most of Arbor's user interface is making use of units. This requires a bit of typing, but makes the physical quantities obvious and allows for easy conversion of models. You can use any sensible unit for a given dimension and Arbor will convert as needed, e.g., you can write ``5 * U.mm`` instead of ``5000 * U.um``. Handing a mismatching dimension to a method will cause a runtime error, so in the example above, ``5 * U.mV`` will be rejected. The cell -------- The most trivial representation of a cell in Arbor is to model the entire cell as a single cylinder. The following example shows the steps required to construct a model of a cylindrical cell with a length of 6 μm and a radius of 3 μm; Hodgkin–Huxley dynamics and a current clamp stimulus, then run the model for 30 ms. The first step is to construct the cell. In Arbor, the abstract representation used to define a cell with branching cable morphology is a ``cable_cell``, which holds a description of the cell's morphology, named regions, and locations on the morphology, and descriptions of ion channels, synapses, threshold detectors, and electrical properties. We will go over these one by one. Our *cell* has a simple morphology comprising a single segment, which is why we use an explicit construction. Normally, one would read the morphology from file and Arbor handles most standard formats natively. .. literalinclude:: ../../python/example/single_cell_model.py :language: python :lines: 9-11 This constructs a :class:`arbor.segment_tree` (see also :ref:`segment tree`) containing a single segment. You can skip the rest of this paragraph on first reading, it explains the details of constructing a morphology from scratch. The segment tree is the representation used to construct the morphology of a cell. A segment is a tapered cone with a tag; the tag can be used to classify the type of the segment (for example soma, dendrite , etc). To create a segment tree representing our single-cylinder cell, we need to add one segment to our ``tree`` object. We use the :meth:`arbor.segment_tree.append` method, which takes 4 arguments: the parent segment which does not exist for the first segment, so we use :class:`arbor.mnpos`; the proximal :class:`arbor.mpoint` (location and radius) of the segment; the distal :class:`arbor.mpoint` of the segment; and the tag. .. literalinclude:: ../../python/example/single_cell_model.py :language: python :lines: 13-14 Next, we create a dictionary of labels (:class:`arbor.label_dict`) to assign properties to. This is a handy tool to connect part of your morphology to semantically meaningful names. Labels give names to :term:`regions` and :term:`location` described using a DSL based on s-expressions. Labels from the dictionary can then be used to facilitate adding synapses, dynamics, stimuli, and probes to the cell. We add two labels: * ``soma`` defines a *region* with ``(tag 1)``. Note that this corresponds to the ``tag`` parameter that was used to define the single segment in step (1). * ``midpoint`` defines a *location* at ``(location 0 0.5)``, which is the midpoint ``0.5`` of branch ``0``, which corresponds to the midpoint of the soma on the morphology defined in step (1). .. literalinclude:: ../../python/example/single_cell_model.py :language: python :lines: 16-23 The final piece constructs a :class:`arbor.decor` describing the distribution and placement of dynamics and properties on a cell. The cell's default properties can be modified, and we can use :meth:`arbor.decor.paint` and :meth:`arbor.decor.place` to further customise it in the following way: * :meth:`arbor.decor.set_property` is used to set some default properties on the entire cell. In the above example we set the initial membrane potential to -40 mV. * :meth:`arbor.decor.paint` is used to set properties or add dynamics to a region of the cell. We call this method 'painting' to convey that we are working on sections of a cell, as opposed to precise locations: for example, we might want to *paint* a density ion channel on all dendrites, and then *place* a synapse at the tip of the axon. In the above example we paint HH dynamics on the region we previously named ``"soma"`` in our label dictionary. * :meth:`arbor.decor.place` is used to add objects on a precise :class:`arbor.location` on a cell. Examples of objects that are *placed* are synapses, threshold detectors, current stimuli, and probes. In the above example, we place a current stimulus :class:`arbor.iclamp` with a duration of 2 ms and a current of 0.8 nA, starting at 10 ms on the location we previously labelled ``"midpoint"``. We also place a :class:`arbor.threshold_detector` with a threshold of -10 mV on the same location. .. literalinclude:: ../../python/example/single_cell_model.py :language: python :lines: 25-26 The three ingredients -- morphology, labels, and decor -- are joined into a cable cell. The single-cell model --------------------- Once the cell description has been built, the next step is to build and run the simulation. Arbor provides an interface for constructing single-cell models with the :class:`arbor.single_cell_model` helper that creates a model from a cell description, with an interface for recording outputs and running the simulation. .. literalinclude:: ../../python/example/single_cell_model.py :language: python :lines: 28-29 The single-cell model has 4 main functions: 1. It holds the **global properties** of the model 2. It registers **probes** on specific locations on the cell to measure the voltage. 3. It **runs** the simulation. 4. It collects **spikes** from threshold detectors and voltage **traces** from registered probes. Right now, we'll only set a probe. The model is complete without, but to see the results, we need to extract some data. .. literalinclude:: ../../python/example/single_cell_model.py :language: python :lines: 31-32 Note, that the probe is given a location from the label dictionary ``midpoint``, the value to record ``voltage``, the sampling frequency, and finally a tag by which we can reference later here ``Um``. Now, we can start the actual simulation: .. literalinclude:: ../../python/example/single_cell_model.py :language: python :lines: 34-35 The results ----------- Our cell and model have been defined and we have run our simulation. Now we can look at the resulting spikes and membrane potential. .. literalinclude:: ../../python/example/single_cell_model.py :language: python :lines: 37-40 To print the spike times, we use :meth:`arbor.single_cell_model.spikes`. A single spike should be generated at around the same time the stimulus we provided in step (3) gets activated (10ms). And, finally, we plot the membrane potential .. literalinclude:: ../../python/example/single_cell_model.py :language: python :lines: 6-7,42-48 We should be seeing something like this: .. figure:: single_cell_model_result.svg :width: 400 :align: center A plot of the potential over time for the voltage probe was added in step (6). The full code ------------- You can find the source code for this example in full at ``python/examples/single_cell_model.py`` which comes in at roughly 10 lines of Python to define and simulate a cell from scratch.