Ball-and-stick morphology not plotting correctly

[wvangeit]

I have the following swc morphology:
1 1 0.0 -10.0 0.0 20.0 -1
2 1 0.0 0.0 0.0 20.0 1
3 1 0.0 10.0 0.0 20.0 2
4 3 0.0 10.0 0.0 2.0 3
5 3 0.0 100.0 0.0 2.0 4

When I plot this with:
import matplotlib.pyplot as plt

import neurom
import neurom.viewer
neurom.viewer.draw(neurom.load_neuron('ballandstick.swc'))

plt.show()

I get:

It seems the diameter of the soma is not plotted correctly ? (Or is there maybe an option to enable plotting the diameter of the soma ?)

[wvangeit]

ballandstick.swc.zip

[mgeplf]

It seems that the default soma plotting draws an 'outline' of the three points, so that's why you get the line.

You can try neurom.viewer.draw(neurom.load_neuron('ballandstick.swc', outline=False))
Which will draw a circle, but it will look wrong since the radius is calculated as the average distance to the center ((10 + (-10))/2, 0, 0), which won't be 10, since one of the coordinates is (0, 0, 0) itself.

How the points of the soma are interpreted has been discussed before, and it looks like there needs to be figured out as per #530.

[mgeplf]

Regardless of the above, the documentation needs to be cleared up so it's easier to find these properties.

[wvangeit]

You there is something very wrong with the soma plotting, it seems the radius of the soma is completely ignored ? (I hope this is only the case for plotting, and not the internal representation of the soma ?)

I corrected the position of the soma by moving the 0,0,0 position to the first line:
1 1 0.0 0.0 0.0 10.0 -1
2 1 0.0 -10.0 0.0 10.0 1
3 1 0.0 10.0 0.0 10.0 2
4 3 0.0 10.0 0.0 2.0 3
5 3 0.0 100.0 0.0 2.0 4

(As i mentioned the radius is completely ignored though)

I think the cleanest way out of this would be to add an option to allow the soma to be plotted like any other section, as a set of cylinders.
And for plotting the sphere, I would just calculate the total surface area of the cylinders and put calculate a radius that generates a sphere with the same surface area.

[lidakanari]

@wvangeit unfortunately you are right Werner. The radius of the soma is completely ignored in principle. The actual radius is computed assuming that the points of the soma belong to the contour. This computation gives a radius that is used for the plotting of the sphere.

[wvangeit]

@lidakanari But is this only used for plotting, or also in the internal representation in NeuroM (to calculate total surface areas etc)

[lidakanari]

@wvangeit This is independent of the plotting. It is used in the internal representation of the soma.

[mgeplf]

After discussion and investigation w/ @wvangeit, it seems like the best course of action is:

1. Assume that SWC, when multiple points are specified, is a series of connected cylinders, with point locations at each x, y, z, and with radius defined by r
2. If there is a single point, assume it's a sphere with radius r, at x, y, z
3. If the point count is 3, see if it follows the pattern in http://neuromorpho.org/SomaFormat.html, and then interpret as 2 stacked cylinders with the point between them as 0, 0, 0
4. Raise a message if the parent ordering ordering isn't linear (NEURON drops these points, so we want to make people aware of that.

Finally, the area of the soma will be calculated as the area of the cylinders (without the end caps), and radius will be that of the equivalent sphere with that area.

[lidakanari]

We have made this change back and forth a few times in the past. I am a bit skeptical about this proposal...

Is it compatible with the computations here: "An equivalent radius (rs) is computed as the average distance of each point of the single contour from this center. " from the http://neuromorpho.org/SomaFormat.html ? I've discussed this issue with Giorgio and Rembrandt and they both proposed the computation to be performed as described here as opposed to the cylinders approach. Of course this depends on the file format issues that are not yet resolved as @mgeplf pointed out.

I am afraid that this change might not be compatible with the contour definition in the ascii files from the lab. In most cases the diameters are set to zero or a random value. When the data are converted (into csv or h5) the diameters values that are propagated in the new formats do not correspond to the actual diameters of the soma.

[wvangeit]

But isn't that just a format problem ? I agree that you can throw away the radii in the ASC format (and the SomaFormat quote also refers to how to get the radius from the ASC file, not from SWC).
But for SWC other tools like Neuron do take the SWC radii into account.

[lidakanari]

Yes, it is obviously a file format problem. I have a proposal:

Case1: If the soma is a contour I would avoid changing the computation to assume cylinders according to the contour as this is a "special case"

Special case: Certain original files represent the soma by both a single contour and a series of cylinders. In these cases, the contour information is discarded and the cylinder representation is preserved unchanged (Figure 5). 

Case2: As Mike says (I think it is already like this)
Case3: If the soma is a three point ensure it is of the expected format:

According to the definition from the same link, the swc "correct" format should be:
1 xs ys zs rs -1
2 1 xs (ys-rs) zs rs 1
3 1 xs (ys+rs) zs rs 1

So in order to avoid confusion I would propose to check if:

1. P1.r == P2.r == P3.r
2. P2.y - P1.y == - P1.r
3. P3.y - P1.y == P1.r
   If those conditions are met then we can safely say that the swc format is the expected one and therefore we can proceed to treat the soma as "cylinders".

[wvangeit]

But so just to be sure: Case1 doesn't exist in SWC.

And yes, for the rest, it's basically what Brian is doing: https://github.com/brian-team/brian2/blob/master/brian2/spatialneuron/morphology.py#L1040

[lidakanari]

It does in practice... However the conversion into this case from ascii or other formats is obscure and depends on the converter so it is not reliable.

[mgeplf]

I agree w/ @wvangeit, except I would treat the 3 point case as the 'normal' case, unless it follows the 'neuromorpho' style, at which point it would be loaded neuromorpho style.

[lidakanari]

Sure, about case 3 I think we all agree.

I don't understand the disagreement... If case1 doesn't exist why should we change how we currently treat it? I have data in this format for which I don't assume cylinders btw.

[mgeplf]

Currently the SWC reader is treating the points as a contour, but in NEURON, it's treated as any other compartment style set of cylinders. The idea would be to switch over to that representation, since the standard (http://www.neuronland.org/NLMorphologyConverter/MorphologyFormats/SWC/Spec.html), doesn't explicitly say they should be contours, and thus implicitly suggests they should be interpreted the same as the neurites (ie: cylinders.)

[mgeplf]

So, to recap the discussion on Friday:

1. SWC doesn't do contours by default, although some software may output (we should track down these packages, and try and not use them - may need an option for the loader to specify these special cases)
2. When contours are needed, use the h5 format, now that @lidakanari has access to a script that does the neurolucida conver to h5 more 'correctly'
3. In the future, we may need to parse SWC+, but not now.

Does that sound right?

[lidakanari]

@mgeplf Agreed! I'd like to add that if anyone needs to produce SWC with a soma in contour format it will be better to produce an SWC+ following the conventions for the "contour soma" type. This way we can avoid misunderstandings and interpret the data correctly.

[asanin-epfl]

In favor of #915