Specification¶
Formats:¶
MorphIO supports ASC (aka Neurolucida), H5 and SWC extensions
Soma formats:¶
(For more information, see: Soma Format) MorphIO recognizes several kinds of soma format. The soma type is determined according to the morphology type and the number of data points:
Undefined soma SOMA_UNDEFINED¶
MorphIO can read correctly a file without a soma. The latter will be of type “undefined”. Additionnaly, a soma made of 2 points will be of type “undefined” as well. Indeed a 2-points soma does not make any sense in any of the other soma formats.
Soma single point SOMA_SINGLE_POINT¶
If a soma is made of only one point it will be treated as a “single point soma” regardless of the morphology file format. The single point soma is represented as a sphere whose coordinate and radius are given by the soma point.
Morphology file dependent soma type:¶
SWC¶
SOMA_NEUROMORPHO_THREE_POINT_CYLINDERS¶
SWC files with a soma made of 3 points will have a soma of type 3-points soma. A 3-points soma is represented as a cylinder along the Y-axis. The first point describe the coordinate of the cylinder center. Its radius represent the length AND radius of the cylinder. X and Z coordinates of second and third points must be identical to those of first point. Y coordinate of second (resp. third) point represents the bottom (resp. top) of the cylinder. Thus, it must have the value Y-R (resp. Y+R) where Y is the Y coordinate of first point and R the radius.
SOMA_CYLINDERS¶
SWC files with more than 3 points are treated as a stack of consecutive conical frustums. Each point describes coordinates and radius of a disk. Each frustums is formed by 2 consecutive disks.
H5, ASC¶
ASC and H5 being the text and binary representation of the same format, they obey to the same specification.
SOMA_CONTOUR¶
A H5/ASC file with a soma of 3 points or more will have their soma represented as a soma contour. In ASC format, soma points are characterized by an S-expression starting with the tag “CellBody”. Even if it is almost never the case in practice, contours are meant to be in the XY plane.
- warning
MorphIO does not support ASC files with multiple CellBody tags 1.
Sub-cellular structures¶
SWC does not support any sub-cellular structures. H5 and ASC support some, please see the following for more details.
Spines¶
SWC and H5 do not support spines. ASC files containing files will be read correctly. However spines data are not handled by MorphIO and spine information will be lost when writing to disk. Unit test
Mitochondria¶
SWC and ASC do not support mitochondria. Mitochondria can be read and written to disk using the H5 format. See README.md for more details about the mitochondria API. Unit test
Custom annotations¶
Custom annotations are not supported 1.
Soma special cases¶
No somata¶
MorphIO supports reading and writing files without a soma. SWC files root sections will have a parent ID of -1. Unit test, Unit test
Multiple soma¶
Others¶
Section with only one child section¶
When a section has a single child section (aka unifurcation), the child section will be merged with its parent when reading or writing the file. Unit test, Unit test
Section ordering¶
In MorphIO each section is identified by an ID. By default, the section IDs will correspond to
the order of section appearance while performing a depth-first traversal on every neurites. The
neurite order is the order of appearance in the file. Alternatively, the NRN simulator way of
ordering section can be used by specifying the flag morphio::Option::NRN_ID
when opening
the file. In the NRN simulator, the soma which is considered as a section (contrary to MorphIO)
is placed first and then neurites are sorted according to their type.
The final order is the following:
Soma
Axon
Basal
Apical
Format specific specifications¶
SWC: The file format specification if available on http://www.neuronland.org. Here we will discuss, what does MorphIO support and does not.
SWC IDs ordering: there is no special constraint about the IDs as long as the parent ID of each points is defined. IDs don’t need to be consecutive nor sorted, and the soma does not need to be the first point.
Soma format is determined according to the number of soma points:
one point -> SOMA_SINGLE_POINT
two points -> SOMA_UNDEFINED
three points:
layout: one soma point with two children -> SOMA_NEUROMORPHO_THREE_POINT_CYLINDERS
else -> SOMA_CYLINDERS
more than three points -> SOMA_CYLINDERS
- 1(1,2)
If this feature seems crucial to you, feel free to create an issue on MorphIO issue tracker.