Importing SWC files and best practices

[JBall]

Hello everyone,

I'm working on converting some NML files created in Webknossos into a format that I can import into NEURON. I did not find any ready-made solutions that seemed to give me what I need, so I'm working on my own solution. My starting approach has been to try to convert to SWC format and use the approach detailed here: https://nrn.readthedocs.io/en/latest/gu ... d-tutorial

First of all, I should say that if there's a more straightforward way to import the structures into NEURON, I'd be happy to be pointed in the right direction.

But for now, I've been first experimenting with some simple dummy data to make sure I understand how import works, and I have a couple of easy questions. First, most of the time, I get the error window below, even if import seems to work (though there's no output to the terminal). I downloaded a SWC file from Neuromorpho.org and got the same error, so I wanted to ask whether this is something I should be concerned about or whether it may just be a quirk of parsing SWC files.

Error message:



Second, I'd like to request a sanity check on my preliminary results. I noticed gaps in the "Show Diam" view, and I wanted to find out if something is wrong with the file specification, or if this is a normal result.

The SWC data:

Code: Select all

1 1 16.73500 11.93100 1.70300 1.0000 -1
2 3 16.31700 10.24200 1.68400 0.45222 1
3 3 17.12900 13.28800 1.68900 0.57844 1
4 3 17.48100 14.09500 1.65400 0.45323 3
5 3 17.67800 14.96200 1.63800 0.35511 4
6 3 16.00800 9.69100 1.65600 0.4826 2
7 3 15.44900 8.52900 1.64900 0.57844 6
8 3 15.05100 7.68400 1.65300 0.45323 7

The result:


And in general, I'm trying to understand best practices for importing 3D morphology into NEURON. I've searched the forum and documents, but I'm still a little unsure about whether it's better to "over-specify" the morphology or stick to a simpler representation (does/can NEURON interpolate between nodes?). I'm making these skeletons myself, so I have flexibility over how coarse or fine they can be. It's also a little unclear to me how or whether I should be specifying the soma as a single point or a string of centroids with varying diameters--and if the latter, how to properly import that data.

Thanks in advance for your help, and I'm happy to continue to read if I'm pointed in the right direction.

[ted]

I'm working on converting some NML files created in Webknossos into a format that I can import into NEURON. I did not find any ready-made solutions that seemed to give me what I need

Have you considered https://github.com/nathantspencer/webknossos_toolkit ? Hard to know the quality and actual utility of any of these things, but this particular repo includes nml2swc and some "swc_tools" that may be useful e.g. swc2hoc. I don't know the author or anything about his programs.

NEURON's Import3d GUI tool works well, and when it generates real comments/warnings/error messages, those are generally informative and helpful. Too bad it's generating a popup window that warns even if there are no errors.

I'm not a big fan of "automated conversion" of morphometric data to Python or hoc code. A lot of the people who do that seem to come from the physical sciences or math, simply don't know what they don't know about cellular neuroanatomy or quantitative morphometry, and aren't collaborating with anyone who has expertise in these areas. Ditto for too many of those who will review and/or read whatever papers come out of their work. You have to wonder about big interdisciplinary computational studies on topics that really matter, like . . .

I've been first experimenting with some simple dummy data to make sure I understand how import works

Excellent.

most of the time, I get the error window below . . . even if import seems to work (though there's no output to the terminal). I downloaded a SWC file from Neuromorpho.org and got the same error

You are right to be concerned. Every tool has a learning curve. Never use a new tool for serious work unless you know how to use it.

Here I must ask what version of NEURON you're using, and what SWC file you downloaded and from where.

Regarding the "simple dummy data" in your post--

First, did you develop this de novo, or is it an excerpt from a morphometric data file you picked up somewhere (and where would that be, but I repeat myself)?

Go ahead and use Import3d to read that file. True, the terminal shows no error messages. But does that mean all is well? Here are a couple of simple tests.

Click on Export / CellBuilder
In the CellBuilder click on the Continuous Create button.
Now at the oc> prompt enter the command
topology()
You should see something like this

Code: Select all

oc>topology()

|-|       soma(0-1)
  `|       dend[0](0-1)
    `|       dend[2](0-1)
  `|       dend[1](0-1)

i.e. the root section is soma, and it looks like the 0 ends of dend[0] and [1] are attached to soma's 1 end, and the 0 end of dend[2] is attached to dend[0]'s 1 end. Is that what you expected?

Next execute
forall psection()
Note that psection() reports that dend[0] and [1] are actually attached to soma's middle (0.5)--and if you look at the Import3d tool's canvas, you'll see the "nodes" (locations at which the morphometric data file specifies xyzdiam data), where the solid blue square corresponds to the root node (coords in the first line of swc data) and the hollow blue squares are the other nodes, and sure enough, the proximal end of
Also check the L and diam values. Are they what you expected?

WRT the gap in your shape plot--my guess is that you got this data from NeuroMorpho, and the nice people at NeuroMorpho have spiffed it up in a way that accounts for the strange appearance. Let me know if that's the case, and we can discuss this particular aspect further.

BTW, you can use the Import3d tool to walk through the morphometric data file (and highlight the corresponding node in the Import3d's canvas with a red dot) by clicking on the up or down arrow next to the "Select id" button.

whether it's better to "over-specify" the morphology or stick to a simpler representation

You're trying to decide whether to use the "stylized specification" (of L and diam) or the "3d specification" (using pt3dadd statements).[/quote]Depends on what you plan to do. If this raises proprietary issues, or requires a long discussion, it might be best to continue via email.

(does/can NEURON interpolate between nodes?)

Not sure what you mean by this question.

I'm making these skeletons myself, so I have flexibility over how coarse or fine they can be.

Good. You won't have to embed confusion-inducing things like one-point somas into your morphometric specification.

Do you need anatomical verisimilitude, or do you need to control the physical appearance of your model? Won't affect its intrinsic electrical behavior, probably would affect its utility in studies of extracellular stimulation, or "networks whose connections are based on proximity between pre- and postsynaptic branches."

It's also a little unclear to me how or whether I should be specifying the soma as a single point or a string of centroids with varying diameters

In most cases, the soma has negligible electrotonic extent (can be treated as isopotential). If you want to represent it as a cylinder, fine, use L and diam or pt3d syntax as you choose (latter is better for making pretty pictures when it comes time to publish). If shape is important (maybe you're interested in intracellular chemical signaling), then use pt3d syntax, which can accommodate a wide variety of shapes (best when radius of centroid curvature is bigger than centroid length, not ideal for surfaces with concavity or saddles).

[JBall]

Hi Ted, thanks for your reply and detailed answers.

I found that repo too, and I was getting started trying to design my own converter when I found it. nml2swc.py makes some assumptions about the NML format that appear to no longer hold for current Webknossos, and the results weren't useful for Import3D. It's possible that swc2hoc.py will take the resulting SWC file and create a useful .hoc specification file, but I'd feel a bit more comfortable writing my own code at this point so that I know what I'm working with. I also hope the result may be useful for others who would be interested in importing modern Webknossos skeletons for NEURON simulation.

WRT the gap in your shape plot--my guess is that you got this data from NeuroMorpho...

Not in this case, though I admit I looked over their shoulder at their SWC format, so I may have copied some of their problems. I started with a mouse retinal horizontal cell (https://neuromorpho.org/neuron_info.jsp ... retina2_n3), because I'm familiar with the cell type. The numbers are all of my own doing. It's the beginning of the annotation of an actual cell, but I only laid down a few points to get started and test.

i.e. the root section is soma, and it looks like the 0 ends of dend[0] and [1] are attached to soma's 1 end, and the 0 end of dend[2] is attached to dend[0]'s 1 end. Is that what you expected?

Note that psection() reports that dend[0] and [1] are actually attached to soma's middle (0.5)--and if you look at the Import3d tool's canvas, you'll see the "nodes" (locations at which the morphometric data file specifies xyzdiam data), where the solid blue square corresponds to the root node (coords in the first line of swc data) and the hollow blue squares are the other nodes, and sure enough, the proximal end of...

Mostly this is as expected, but I would have ideally modeled the soma as a cylinder with dend[0] and dend[1] connected at the opposite ends of the soma. I would personally find it most intuitive to model the soma as a single point with processes emanating from the apical and the basal ends as needed, but I'm open to other options provided that I understand how to code the SWC file and import it into NEURON.

You're trying to decide whether to use the "stylized specification" (of L and diam) or the "3d specification" (using pt3dadd statements).

You're right, but it's possible I don't fully appreciate the distinction (this speaks to my question about interpolation too). I can create skeletons with more points, but I need to specify the radius at each point during annotation, and more points will take more time. If it's necessary for faithful simulations, I can put in the time. But, my intuition tells me that a dendritic section that does not branch for ~2-3 um and does not significantly change diameter along this length could be represented as a single cylinder from point A to point B. I have been creating skeletons a little bit sparsely--just enough to capture branch points, significant changes in neurite size, and capture the general shape. So, not purely stylized, but also not a perfect representation of the morphology. Given this, it seems like the stylized representation may actually be preferable, would you agree? If so, is there an analogous path for importing/converting SWC or similar data into the stylized representation?

[ted]

Start with a clear concept of what you're trying to do. For your purpose, is it sufficient to represent neurites as right cylinders, or is it important that a neurite's diameter may vary, and its centroid diverge from a straight line, from one end to the other? This decision should be strictly on a scientific basis, not on technical details such as how to implement the morphometric data, or how those data will be translated into code suitable for executing simulations.

I would have ideally modeled the soma as a cylinder with dend[0] and dend[1] connected at the opposite ends of the soma.

Then do that, as long as it fits with your scientific purpose. It'll take two lines in the swc file.

I would personally find it most intuitive to model the soma as a single point

Sounds like you're veering into computational details. Don't confound specification of anatomy with details of how a physical system that is "continuous in space and time" will be approximated by a bag of equations that describe the variation of state variables over discrete points in time and space. Regarding spatial discretization, you might find it helpful to read chapter 5 in The NEURON Book. If you don't have that, read this https://www.neuron.yale.edu/ftp/ted/book/chap5.pdf.

Given this, it seems like the stylized representation may actually be preferable, would you agree?

I don't have a clear enough idea of what you're trying to do to have an informed opinion about this. If using model cells whose anatomies are based on Webknossos-generated NML files is of central importance, then you'll need to use Import3d or something else to handle the conversion.

But the discussion so far has been from the perspective of methodology, so is that it? there isn't an underlying scientific question?

[JBall]

Thanks Ted. A colleague has recordings from neurons of this type that show the presence of an unexpected receptor type. I decided to leverage available anatomical data to probe the effects of hypothetical receptor location and morphology on signal processing. Plus, like you said, pretty pictures.

I've managed to adjust the reconstructions and code to properly convert the NML files into a SWC format that imports into NEURON without errors. I had a misconception about soma representation: Although I was content with the soma being represented as a single point, I didn't realize that this was a bad situation for the SWC import function. So, I've adjusted the reconstructions to include a string of soma nodes to which I've attached dendritic and axonal compartments to either end. Purely passive simulations seem to be working as expected thus far.

From here my next step is to begin to Python-ize the code. I learned NEURON over a decade ago and I didn't pay attention to the Python implementation, so I have some catching up to do. The ball-and-stick tutorials make sense, but I'm now struggling a little to adapt the import of the 3D model specification into the _setup_morphology method, because the anatomically detailed model tutorials tend to focus upon exporting imported models using HOC and/or SES files. Are there any examples for this workflow that you would recommend?

[ted]

The Python tutorials illustrate a lot of useful things that can be done with code, and a particular approach to writing code that scales well as program complexity increases.

But the KISS principle has its own advantages. Writing less code automatically means writing fewer typos and user-created bugs that you have to diagnose and fix. If you only have a few morphologies to deal with, you don't need code that can process, unattended, a large number of morphology files--which puts far more trust in morphometric data than is warranted, given all the problems that can lurk in those files. Only a non-biologist would be comfortable doing such a thing. Might as well eat random roadkill without cooking it. Just use the Import3d tool to get the morphology into a CellBuilder, and then use that CellBuilder to

--create subsets that make anatomical sense (e.g. apical vs. basilar dendrites, somatic vs. axonal sections) or that are required by what is known or hypothesized about channel distributions

--specify the spatial discretization strategy. The d_lambda rule generally works well, but myelinated sections may require special treatment, which I can describe if you need it.

--specify basic biophysical properties, e.g. Ra is uniform in most model cells, dendritic A current density in some cell classes increases with distance from the soma, etc.

When you're done, save the CellBuilder to a ses file so you can return to it if you need to. Then export to a cell class. Sure, it's hoc, but Python can deal with that. Suppose foo.hoc defines the hoc cell class Foo. Then

h.load_file("foo.hoc")
cell = h.Foo()

and after that you can do whatever you want in Python.