Skip to content

Commit

Permalink
grammar fix (#2329)
Browse files Browse the repository at this point in the history
<!-- Please make sure your PR follows our [contribution
guidelines](https://github.com/arbor-sim/arbor/tree/master/doc/contrib)
and agree to the terms outlined in the [PR
procedure](https://github.com/arbor-sim/arbor/tree/master/doc/contrib/pr.rst).
-->

---------

Co-authored-by: Thorsten Hater <[email protected]>
  • Loading branch information
ErbB4 and thorstenhater authored Jul 31, 2024
1 parent e50f8b1 commit e23b9b8
Showing 1 changed file with 23 additions and 23 deletions.
46 changes: 23 additions & 23 deletions doc/fileformat/swc.rst
Original file line number Diff line number Diff line change
Expand Up @@ -12,15 +12,15 @@ Arbor supports reading morphologies described using the
`SWC <http://www.neuronland.org/NLMorphologyConverter/MorphologyFormats/SWC/Spec.html>`_ file format.

SWC files may contain comments, which are stored as metadata. And a blank line anywhere in the file is
interpreted as end of data.
interpreted as the end of data.

The description of the morphology is encoded as a list of samples with an id,
an `x,y,z` location in space, a radius, a tag and a parent id. Arbor parses these samples, performs some checks,
then generates a morphology according to one of three possible interpretations.
an `x,y,z` location in space, a radius, a tag, and a parent id. Arbor parses these samples, performs some checks,
and then generates a morphology according to one of three possible interpretations.

The SWC file format specifications does not describe how the file should be interpretted to reconstruct
a morphology from SWC samples. This has lead different simulators to interpret SWC files in different
ways, specifically the reconstruction of the soma. Arbor has its own an interpretation that
The SWC file format specifications do not describe how the file should be interpreted to reconstruct
a morphology from SWC samples. This has led different simulators to interpret SWC files in different
ways, specifically the reconstruction of the soma. Arbor has its own interpretation that
is powerful and simple to understand at the same time. However, we have also developed functions that will
interpret SWC files similarly to how the NEURON simulator would.

Expand All @@ -32,13 +32,13 @@ to validate an SWC file:
* Check that the parent id of a sample refers to an existing sample.

In addition, all interpretations agree that a *segment* is (in the common case) constructed between a sample and
its parent and inherits the tag of the sample; and if more than 1 sample have the same parent, the parent sample
its parent and inherits the tag of the sample; and if more than one sample has the same parent, the parent sample
is interpreted as a fork point in the morphology, and acts as the proximal point to a new branch for each of its
"child" samples. There a couple of exceptions to these rules which are listed below.

.. Note::

The SWC file format allows association of ``tags`` with parts of the
The SWC file format allows the association of ``tags`` with parts of the
morphology and reserves tag values 1-4 for soma, axon, basal dendrite, and
apical dendrite. In Arbor, these tags can be added to a
:class:`arbor.label_dict` using the :meth:`~arbor.label_dict.add_swc_tags` method.
Expand All @@ -53,8 +53,8 @@ described by a single sample. It constructs the soma from 2 or more samples, for
always constructed between a sample and its parent. This means that there are no gaps in the resulting morphology.

Arbor has no magic rules or transformations for the soma. It can be a single branch or multiple branches; segments
of a different tag can connect to its distal end, proximal end or anywhere in the middle. For example, to create a
morphology with a single segment soma; a single segment axon connected to one end of the soma; and a single segment
of a different tag can connect to its distal end, proximal end, or anywhere in the middle. For example, to create a
morphology with a single-segment soma, a single-segment axon connected to one end of the soma, and a single-segment
dendrite connected to the other end of the soma, the following swc file can be used:


Expand All @@ -63,7 +63,7 @@ dendrite connected to the other end of the soma, the following swc file can be u
:linenos:
Samples 1 and 2 will form the soma; samples 1 and 3 will form the axon, connected to the soma at the proximal end;
samples 2 and 4 will form the dendrite, connected to the soma at the distal end. The morphology will look something
samples 2 and 4 will form the dendrite, connected to the soma at the distal end. The morphology will look like something
like this:

.. figure:: ../gen-images/swc_morph.svg
Expand All @@ -75,9 +75,9 @@ like this:
NEURON interpretation
"""""""""""""""""""""
Arbor provides support for interpreting SWC inputs in the same way as NEURON,
to ease porting of cell models developed in NEURON to Arbor.
to ease the porting of cell models developed in NEURON to Arbor.

The NEURON interpretations is based on the observed output of NEURON's ``Import3d_SWC_read``
The NEURON interpretations are based on the observed output of NEURON's ``Import3d_SWC_read``
function, which is based on the `Neuromorpho approach <http://neuromorpho.org/SomaFormat.html>`_.
However, there are differences and undocumented interpretations of the soma and how dendrites,
axons and apical dendrites are attached to it that are not described explicitly by Neuromorpho.
Expand All @@ -96,7 +96,7 @@ axons and apical dendrites are attached to it that are not described explicitly

**Every sample must have the same SWC identifier (tag) as its parent, except for
samples whose parent is tagged as soma**:
This enforces that axons, dendrites and apical dendrites can only attach to the soma.
This enforces that axonal and dendritic segments can only attach to the soma.
Conversely, it isn't possible to attach an axon to a dendrite, for example.

**The first sample is tagged as soma**:
Expand All @@ -107,7 +107,7 @@ The `Neuromorpho guidelines <http://neuromorpho.org/SomaFormat.html>`_ regarding
interpretation of a spherical soma described with a single soma sample can be summarised:

* The soma is composed of two cylinders that have their proximal ends at the soma
center, extended first along the negative y-axis and then positive y-axis.
center, extended first along the negative y-axis and then the positive y-axis.

Following the Neuromorpho specification, NEURON constructs the soma from two cylinders,
joined at the soma center. It differs in two ways:
Expand All @@ -117,24 +117,24 @@ joined at the soma center. It differs in two ways:
``x=x0`` and the third at ``x=x0+r``, to form a single section.
* All dendrites, axons, and apical dendrites are attached to the center of the soma with "zero resistance wires".

**The axon, dendrite and apical sub-trees follow special rules for attachment to
**The axon, dendrite, and apical sub-trees follow special rules for attachment to
the soma**: By default, the sub-tree starts at the first sample with the
dendrite, axon or apical tag, and not at the parent location on the soma, and
a tag indicating a non-soma segment, and not at the parent location on the soma, and
the sub-tree is connected to its parent with a "zero resistance wire".
**Except** when the sub tree is defined by a single child sample. In which case
the sub-tree is composed of a single a segment from the parent location on the
soma to the child sample, with constant radius of the child.
**Except** when the sub-tree is defined by a single child sample. In which case
the sub-tree is composed of a single segment from the parent location on the
soma to the child sample, with a constant radius of the child.

Note that these special properties can lead to unintuitive behviour in some cases. Example
Note that these special properties can lead to unintuitive behaviour in some cases. Example

.. code-block::
# id, tag, x, y, z, radius, parent
1 1 0 0 0 6 -1
2 3 2 0 0 3 1
As we have one sample tagged ``1`` (soma), the soma is build by two cylinders
approximating a sphere. The dendrite is attached to the center, thus the
As we have one sample tagged ``1`` (soma), the soma is built by two cylinders
approximating a sphere. The dendrite is attached to the center, thus, the
morphology has *three* branches arranged in a 'T'-shape.

API
Expand Down

0 comments on commit e23b9b8

Please sign in to comment.