Neurolucida to NEURON best practices?

Managing anatomically complex model cells with the CellBuilder. Importing morphometric data with NEURON's Import3D tool or Robert Cannon's CVAPP. Where to find detailed morphometric data.
bsuter
Posts: 42
Joined: Fri May 28, 2010 9:04 am

Neurolucida to NEURON best practices?

Post by bsuter »

I've completed a detailed reconstruction of a neuron using Neurolucida software. What are current best practices / instructions / gotchas for bringing this morphology into NEURON for simulations?

The soma was reconstructed using NL's "contour" mode, i.e. as a sequence of closed polygons, each at a single z-level. As this was not a tracing, I was not able to apply the "cell body" type. Is this a good way to proceed? I read in older posts here that Import3D looks for a "cell body" label in NL files. I'm happy to redo differently.

In NL I labeled the traces as either "axon", "apical dendrite", or "dendrite". Should this generally transfer into NEURON?

How does NEURON know that a given branch connects to the soma - are any particular NL tracing techniques required (e.g. begin each root branch inside the soma volume)?

What NL export format is best for use with Import3D?

I attempted to import my reconstruction into NEURON by exporting from NL to .ASC, then selecting said .ASC file in the Import3D tool. This resulted in a number of error messages at the console. The morphology was displayed by Import3D. However, when I tried to send this to the CellBuilder, no shape displayed. I plan to read the error messages carefully and try to debug what's wrong, but figured it would be useful to first make sure that I'm following current best practices for the overall procedure.

Related: what is the best way to convert from NL to a .swc file? I realize this is not directly a NEURON question, but figure someone here may know the answer.

Thank you,
Ben.
ted
Site Admin
Posts: 6287
Joined: Wed May 18, 2005 4:50 pm
Location: Yale University School of Medicine
Contact:

Re: Neurolucida to NEURON best practices?

Post by ted »

bsuter wrote:I've completed a detailed reconstruction of a neuron using Neurolucida software. What are current best practices / instructions / gotchas for bringing this morphology into NEURON for simulations?
Use the Import3D tool to process a NeuroLucida ascii format file. It may work without complaint, issue warnings or comments, issue error messages, or fail dramatically. Warnings and comments require informed consideration and judgement, as do error messages. Some are just notifications that an orphan section was connected to the nearest branch point; it's up to the user to decide if that's OK or if some other action needs to be taken. Sometime it is helpful to use the tool's "Select point" feature--click on that radio button, then either click on some part of the shape plot or enter a number into the adjacent numerical field, and finally use the spinner's up & down arrows to walk through the data (you may need to zoom in on the shape plot for better visualization).
The soma was reconstructed using NL's "contour" mode, i.e. as a sequence of closed polygons, each at a single z-level. As this was not a tracing, I was not able to apply the "cell body" type. Is this a good way to proceed? I read in older posts here that Import3D looks for a "cell body" label in NL files. I'm happy to redo differently.
A z stack of outlines should work. If it doesn't, maybe you do need to apply such a label.
In NL I labeled the traces as either "axon", "apical dendrite", or "dendrite". Should this generally transfer into NEURON?
It will probably create corresponding subsets (SectionLists). Try it and find out.
How does NEURON know that a given branch connects to the soma
If the data format doesn't provide a specific markup or other notation (e.g. the numerical index of the parent data point) to indicate that something is attached to the soma, then presumably Import3D must decide on the basis of proximity.
are any particular NL tracing techniques required (e.g. begin each root branch inside the soma volume)?
AFAIK that's not necessary or advisable.
What NL export format is best for use with Import3D?
It can handle version 1 and 3 ASCII (text) files.
what is the best way to convert from NL to a .swc file?
You might check NeuroMorpho.org to see if they have made such a tool available.
bsuter
Posts: 42
Joined: Fri May 28, 2010 9:04 am

Re: Neurolucida to NEURON best practices?

Post by bsuter »

Hi Ted,
I'm still trying to get this (Neurolucida to NEURON) to work, but not much luck yet. I'll go back and try to debug from a very simple NL model. I've been using Import3D with a v3 NL .asc file. Most of the "problem points" seem to be at the soma, and in particular where each z-level contour closes (i.e. where start point connects to end point). The errors I see:

oc>myfile.asc line 17: don't know section type: [2,111](216.19, -824.21, -85.00) 0.01
(and many more of these, I believe these are the soma contours)

Nearest branch point is coincident in xy plane.
Make a physical connection with diam of the MOVETO
17: [2,111](216.19, -824.21, -85.00) 0.01 branch at line 16 is 1e+09 away

Cannot figure out which is the parent
No coincident (even in xy plane) branch point.
29: [2,111](215.61, -827.97, -87.87) 0.01 branch at line 16 is 1e+09 away
48: [2,111](215.34, -828.55, -90.73) 0.01 branch at line 16 is 1e+09 away
(and more of these, one each for every soma contour, where the polygon closes)

While I can see the shape in Import3D, exporting to CellBuilder results in errors, so it does seem like I need to resolve the problem points before being able to proceed.

oc>nrniv: Arg out of range in user function
near line 5
{setlistname(hoc_ac_)}
^
List[27].object(0 )
Import3d_GUI[0].cbexport1(List[21] )
Import3d_GUI[0].cbexport( )

I am looking for the path of least resistance - i.e. I am happy to reconstruct the soma (and dendrite roots) in whatever way is optimal for import to NEURON, in order to avoid such issues.

Thanks,
Ben.
ted
Site Admin
Posts: 6287
Joined: Wed May 18, 2005 4:50 pm
Location: Yale University School of Medicine
Contact:

Re: Neurolucida to NEURON best practices?

Post by ted »

Why don't you email the file to me--ted dot carnevale at yale dot edu--so I can take a look at it. By the way, what version of NEURON are you using, in case it turns out that the problem has been solved in a more recent version or even perhaps in the most recent development code?
bsuter
Posts: 42
Joined: Fri May 28, 2010 9:04 am

Re: Neurolucida to NEURON best practices?

Post by bsuter »

(Ted, while I was composing this message, you replied to the thread)

Update: Within Neurolucida, I modified the reconstruction such that the soma contours were marked as "Cell Body". While this does not change the geometry of the soma in the reconstruction, it seems to have provided enough identification to allow NEURON's Import3D to correctly recognize the soma and connect the dendrites and axon to the soma.

For other NL users: When a contour is selected, the usual dropdown options for labeling section types (e.g. axon, apical dendrite, dendrite, cell body) is not available. Instead, one must select each contour, right-click and choose the "Set to Cell Body" option. I repeated this for every contour of the soma, re-exported to .asc, and then opened this in Import3D without any errors reported.

I'm curious, though, to understand how the soma is represented from NEURON's point of view: My soma reconstruction in NL consists of 19 contours, each in a single z-plane. The generated .hoc for the 3D geometry specification creates 19 sections (soma[0] to soma[18]). Looking at the pt3dadd() calls for these sections, I see the that all points in a single section are at a single z-value, with x, y, and d varying. The z-values do not increase monotonically with increasing soma section index, and looking at the topol() function I see that soma sections 1-18 are each connected to the center of soma[0]. Conceptually I'm having difficulties picturing what the resulting topology/geometry is, and what implications this has for the simulation?

Thanks,
Ben.
ted
Site Admin
Posts: 6287
Joined: Wed May 18, 2005 4:50 pm
Location: Yale University School of Medicine
Contact:

Re: Neurolucida to NEURON best practices?

Post by ted »

bsuter wrote:My soma reconstruction in NL consists of 19 contours, each in a single z-plane. The generated .hoc for the 3D geometry specification creates 19 sections (soma[0] to soma[18]). Looking at the pt3dadd() calls for these sections, I see the that all points in a single section are at a single z-value, with x, y, and d varying. The z-values do not increase monotonically with increasing soma section index, and looking at the topol() function I see that soma sections 1-18 are each connected to the center of soma[0].
This sounds more than a bit bizarre to me. I'll have to see it to understand it. Can you send me both versions of your Neurolucida file?
what implications this has for the simulation?
No good ones.
bsuter
Posts: 42
Joined: Fri May 28, 2010 9:04 am

Re: Neurolucida to NEURON best practices?

Post by bsuter »

ted wrote:
bsuter wrote:My soma reconstruction in NL consists of 19 contours, each in a single z-plane. The generated .hoc for the 3D geometry specification creates 19 sections (soma[0] to soma[18]). Looking at the pt3dadd() calls for these sections, I see the that all points in a single section are at a single z-value, with x, y, and d varying. The z-values do not increase monotonically with increasing soma section index, and looking at the topol() function I see that soma sections 1-18 are each connected to the center of soma[0].
This sounds more than a bit bizarre to me. I'll have to see it to understand it. Can you send me both versions of your Neurolucida file?
Thanks - I sent it to you via email.
ted
Site Admin
Posts: 6287
Joined: Wed May 18, 2005 4:50 pm
Location: Yale University School of Medicine
Contact:

Re: Neurolucida to NEURON best practices?

Post by ted »

Well, you already fixed one problem by doing the following:
Update: Within Neurolucida, I modified the reconstruction such that the soma contours were marked as "Cell Body". While this does not change the geometry of the soma in the reconstruction, it seems to have provided enough identification to allow NEURON's Import3D to correctly recognize the soma and connect the dendrites and axon to the soma.
although from the .DAT files (and at least one other thread on this Forum) I believe you marked the contours "CellBody" without any space between Cell and Body. I wonder if "soma" or "Soma" would have done as well?

I believe the remaining problem is that your revised .asc file shows the stack of soma outlines as being scrambled, that is the first soma outline is at z = -104.1, the second at -113.65, the third at -98.37 etc.. As I understand it, Import3D needs the stack to be arranged with monotonically increasing (or decreasing) z coordinate, so that reordering them correctly will allow Import3D to create a single soma section with a 3D shape somewhat like a large potato or gourd, and all dendritic trees that arise from the soma will be connected to the midpoint of this section.
bsuter
Posts: 42
Joined: Fri May 28, 2010 9:04 am

Re: Neurolucida to NEURON best practices?

Post by bsuter »

ted wrote:Well, you already fixed one problem by doing the following:
Update: Within Neurolucida, I modified the reconstruction such that the soma contours were marked as "Cell Body". While this does not change the geometry of the soma in the reconstruction, it seems to have provided enough identification to allow NEURON's Import3D to correctly recognize the soma and connect the dendrites and axon to the soma.
although from the .DAT files (and at least one other thread on this Forum) I believe you marked the contours "CellBody" without any space between Cell and Body. I wonder if "soma" or "Soma" would have done as well?
In Neurolucida there are four options while in tracing mode: Axon, Apical Dendrite, Dendrite, Cell Body. These are options in a dropdown UI element, and I don't know how NL translates this program state to an encoding in the data files (i.e. CellBody, Cell Body, etc). By the way, initially the soma contours were labeled "Soma 1", and contour labels can be user-defined. As you wrote, identifying each soma contour in NL using the "Cell Body" option solved the problem of importing from ASC into NEURON without (reported) errors.

Can you tell me which codes in the .ASC files are interpreted as section types by Import3D? I see only numeric values in the .ASC file.
I believe the remaining problem is that your revised .asc file shows the stack of soma outlines as being scrambled, that is the first soma outline is at z = -104.1, the second at -113.65, the third at -98.37 etc.. As I understand it, Import3D needs the stack to be arranged with monotonically increasing (or decreasing) z coordinate, so that reordering them correctly will allow Import3D to create a single soma section with a 3D shape somewhat like a large potato or gourd, and all dendritic trees that arise from the soma will be connected to the midpoint of this section.
Thanks, I see how this could explain the remaining problems. I'm quite sure that I reconstructed the soma contours monotonically starting from the most superficial z-level in NL. I know that I intended to do it that way, but I can't exclude plain user error on my part in actually executing this. Best I can do is to try it again monotonically and see if anything changes. I do have a couple of hunches, though:
1. NL's .asc export is buggy. I've tried round-tripping the ASC files in NL: Export tracing from NL to .asc, then immediately open that same .asc file in NL. This results in NL error messages about the file syntax. In and of itself, this is problematic, but I don't know whether it relates to my current issue. As I've noted, the .asc headers seem to indicate version 3, but the NL export menu says version 2. Whatever the details, I'll take this up with NL support directly.
2. The contours may initially be well-ordered, and get scrambled prior to/during export. While I believe that I constructed the soma contours monotonically, there's a very good chance that when I later converted each contour to a "Cell Body" type, I applied this conversion in a different order (i.e. that I did not select each contour monotonically in z). Could it be that NL re-orders these segments each time their label changes? I consider it possible, if odd.

I'll see what I can do to test some of these possibilities.

I am reconstructing this neuron specifically for use in a NEURON model. I'm happy to do this in whatever way you or others recommend. My understanding from reading the forum was that reconstructing in Neurolucida for purposes of import into NEURON is reasonably common place. I'm looking for whatever way works / is recommended / is expected by the Import3D NL filter, even if that means redoing the reconstruction.

Thank you for your help with this, it is much appreciated!

Ben.
ted
Site Admin
Posts: 6287
Joined: Wed May 18, 2005 4:50 pm
Location: Yale University School of Medicine
Contact:

Re: Neurolucida to NEURON best practices?

Post by ted »

In my own dealings with NeuroLucida support (last time at least 3 years ago) they have always been very open, responsive, and effective. Please keep me apprised of what you learn. Many people are using NeuroLucida-generated data with NEURON, so it is important for the issues that have been raised here to be resolved, and for this discussion thread to result in a clear and concise statement of the best way for users to proceed.
bsuter
Posts: 42
Joined: Fri May 28, 2010 9:04 am

Re: Neurolucida to NEURON best practices?

Post by bsuter »

I believe we've identified sources of some, maybe all, the problems I've encountered. I've succeeded in generating a .hoc file containing the morphology reconstructed in Neurolucida, with minor differences. Some errors remain during the conversion process, but I believe they can be ignored. I believe there are some bugs and hope we can continue to address these. However, I think at this point it is worth describing the process that seems to work sufficiently well. This was tested in Neurolucida v9.14 (on 2P image stacks) and NEURON 7.1:

How to reconstruct a neuron in Neurolucida and generate a HOC file containing its morphology:
In Neurolucida:
1. Begin the reconstruction in "contour mode" and reconstruct the soma as a series of closed loop contours. I created a closed loop at successive z-levels. It is important to proceed monotonically in z, e.g. start superficial and proceed steadily deeper. Save the reconstruction so you can return to this point if the next steps fail.
2. Switch to selection mode. Right-click and choose "Select contours only". Drag the selection cursor to select all the contours at once. Right-click on a contour (between points) and choose "Set to Cell Body".
3. Switch to manual neuron tracing mode. Trace the remaining processes, taking care to select the appropriate type (dendrite, apical dendrite, axon). I chose to begin each process just within the boundary of the soma volume - I believe the important thing is to start close to the soma (whether inside or outside is not critical).
4. Save the reconstruction in the standard Neurolucida format, e.g. as a .dat file. This is useful if you need to return to make any modifications.
5. Save as an MBF ASCII file, with the .asc extension. This is a text file format that can be read by NEURON. Note: Do NOT use the "export tracing" menu command, instead you should choose "Save as" and select the .asc format there.
In NEURON:
6. Start the NEURON gui, then Tools->Miscellaneous->Import3D.
7. Choose a file, namely the .asc file generated in step 5.
8. You may see an error dialog that says "file translation problems. See the messages on the terminal." Continue / close this message dialog.
9. Inspect the messages at the terminal. You will likely see some lines showing Principle values and Principle axes data - this reflects NEURON's process of converting the soma contours from Neurolucida into the standard NEURON geometry type. Below this you will likely see a list of problems. In my experience, there is one such problem reported for every root process (e.g. the axon, apical dendrite and any basal dendrites), indicating that the root of a process is outside the bounding box of the soma. The messages also indicate that a "logical connection to center of nearest soma" is made. This means that the electrical connectivity (the topology) is established from soma to process, even though there is some geometrical gap. If you see any other problems reported, there may be issues with the reconstruction that were not automatically fixed, i.e. you may need to investigate the problems further. In my case there was an additional dialog window titled "Possible root branch errors". It lists the same "problems" as were shown on the terminal, with checkboxes next to each. Do NOT check any of these - I believe the statements at the terminal confirm that these connections were automatically fixed. Furthermore, in my case as soon as I checked any one of these checkboxes an error occurred and NEURON needed to be restarted. Close this "possible root branch errors" window.
10. The Import3D gui should show you the shape of your imported reconstruction. Optionally, deselect "Show Points" and zoom in/rotate to visually inspect the soma shape. Note that some of the root processes may look like they are hanging disconnected from the soma - geometrically this may be so, but topologically they should be properly connected per the points discussed in #9 above.
11. In Import3D, select "Export" then "CellBuilder". A CellBuild[0] windows should appear. Select the "Management" tab. Select the "Export" button. Deselect the "Membrane" option but keep "Topology", "Subsets", "Geometry" selected. Then click "Export to file" and save as appropriate. The resulting .hoc file contains the morphology of your reconstruction. If you wish, you can of course use the CellBuilder to add passive or active membrane properties for e.g. testing purposes.
12. At this point, I recommend closing NEURON, restarting and then loading the .hoc file via File->load hoc. You can then type

Code: Select all

topology()
at the terminal to see a schematic diagram of the sections and their connections. You likely will want to confirm that the soma is connected to all the expected main branches.
13. It is recommended that you check your model for any morphological problems. For example, if the diameter is too small at some point the electrical flow may effectively be blocked. The following code executed at the terminal is useful, but won't catch the case of a tiny (but non-zero) diameter:

Code: Select all

forall { for(x,0) { if (diam(x) <=0) print secname(), diam(x) } }
14. You should also check for any sections of zero length:

Code: Select all

forall { if (L<=0) print secname(), L }
15. Finally, I recommend adding passive membrane properties, an IClamp point process at the soma, injecting a current step, and measuring whether the resulting somatic change in membrane potential reaches all the distal processes by displaying a shape plot with the display range scaled appropriately. The Tools->Impedance menu provides a number of more sophisticated ways to analyze / inspect the reconstruction's electrical signal transfer.

Remaining issues:
A. I'd prefer if the default conversion of the soma contours resulted in a soma shape where the "0" end and the "1" end define a line roughly parallel to the y-axis. At present, in my case, the resulting line from "0" to "1" end of the soma is roughly parallel to the z-axis. I'd like to connect the apical dendrite at the narrow end of the "egg", the axon at the opposing blunt end of the "egg", and the basal dendrites in the middle. I don't think this is currently possible in my case, due to z-parallel orientation of the primary axis.
B. The "possible root branch errors" dialog window seems to be broken, and it seems to duplicate the errors shown in the terminal and conflict with them (the terminals says they were automatically fixed, the dialog says the user should select the ones to be fixed). Note that checking any of these results in errors at the terminal and breaks the ability to export to CellBuilder.
C. I'd prefer if Import3D printed info to the terminal indicating what type of file was recognized (i.e. "Neurolucida v3"), and also what types of elements were identified (e.g. "Contours: 1 soma; Tracings: 1 axon, 1 apical dendrite, 14 basal dendrites").
D. Turns out that the Neurolucida "Export tracing->ASC v2" command generates files whose header reads "version 3", but which are not "v3" files. Furthermore, these files are not the same as the ones generated by "Save as -> ASCII 2 .asc2". The latter are identified as "v3" by NEURON, the former as older versions. I'm waiting for some clarification from Neurolucida on these different formats and will report what I learn - for now, the key is to use "Save as->ASC".
E. For Neurolucida users: if you wish to reconstruct the soma as a tracing (i.e. sequence of tapered cylinder sections) instead of as contours, you may need to take the following approach: First reconstruct the soma as contours, the rest of the cell as tracings, as detailed above. Generate a .hoc file from this. Then start a new reconstruction, tell NL that you are tracing a "dendrite" in manual tracing mode, reconstruct just the soma in this way, then generate a soma.hoc file from this. Open soma.hoc, change "dend" to "soma", copy the geometry definition and then modify the initial, full .hoc file such as to replace the original "contour based" soma geometry with this simpler fragment. You will also need to update some of .hoc code at the end of the file since there will be just one soma section, rather than multiple (one for each contour). Why this roundabout technique? When I tried to trace a "Cell Body" in "manual tracing mode", it first seemed to work fine in Neurolucida, but in NeuroExplorer it was shown as if I had been defining points in a contour, and similarly in Import3D.

Your mileage may vary ...
ted
Site Admin
Posts: 6287
Joined: Wed May 18, 2005 4:50 pm
Location: Yale University School of Medicine
Contact:

Re: Neurolucida to NEURON best practices?

Post by ted »

Outstanding. I have a few minor comments (one is that, for reasons we can get into later, it is advisable to save the CellBuilder to a ses file). I would like to see this post be incorporated as an article, with you listed as author*, into NEURON's WWW site where it will be more visible (besides, the WWW site lends itself more readily to revisions, additions, and linking to related materials). Also a post should be added to this Forum's "Hot tips" area with a link that points to the article on the WWW site.

*--this can involve as much or as little further effort on your part as you wish. If you're interested, contact me by email.
ted
Site Admin
Posts: 6287
Joined: Wed May 18, 2005 4:50 pm
Location: Yale University School of Medicine
Contact:

Re: Neurolucida to NEURON best practices?

Post by ted »

Further comments:

If the soma stack skips around, instead of proceeding in an orderly manner, it's probably quickest just to open a copy of the asc file with a text editor and use block copy & paste to rearrange the outlines in a monotonically increasing or decreasing sequence.

The most recent revision to Import3D was done to the development code in changeset 470,
back on Tuesday, 9/28/2010
http://www.neuron.yale.edu/hg/neuron/nr ... 1bff7325f7
That changeset's comments are:
"Import3D was not computing the bounding box for soma stacks and hence misleading messages were generated stating that that main branches were outside the soma bounding box."

Anyone who is using Import3D to deal with morphometry files that contain one or more stacks of soma outlines would be well advised to either get a more recent alpha installer (the only one available as of this date is for MSWin: http://www.neuron.yale.edu/ftp/neuron/v ... -setup.exe) or to download and compile the most recent development code (easy to do under UNIX/Linux/OS X, directions provided at http://www.neuron.yale.edu/neuron/download/getdevel).

In its present implementation, Import3D should be able to handle somas whose morphometric data were obtained in any of these three different ways:
1. as a sequence of x,y,z,diam measurements, i.e. like any other neurite.
2. by tracing an outline of the perimeter of the soma at one z level. In this case, Import3D's code identifies the principal axis of this "soma silhouette", then cuts the silhouette into 20 (as I recall) slices of equal thickness dL by a series of lines orthogonal to the principal axis. Each slice is then treated as if it were the side view of a very short cylinder (like a thick washer)--its surface area and volume are computed as PI*w*dL and PI*w*(dL/2)^2, where w is its width (measured orthogonal to the soma principal axis). The total somatic surface area and volume are computed by summing over all the slices. These are reasonably satisfactory approximations to the true area and volume as long as the actual shape of the soma does not deviate too far from having rotational symmetry about an axis. If there are two or more nonoverlapping soma outlines, each will be treated as defining a separate soma and cell.
3. by tracing soma outlines at multiple z levels. Import3D's code divides each outline into some number of equally spaced points, which are used to construct a triangular mesh approximation of the surface of the soma. Somatic surface area and volume are computed from this mesh. A stack of outlines that overlap is interpreted as defining a single soma; if there are two or more nonoverlapping stacks, each individual stack is treated as defining a separate soma and cell.
Sherif
Posts: 27
Joined: Thu Oct 13, 2005 4:32 pm

Re: Neurolucida to NEURON best practices?

Post by Sherif »

My question is relevant to this topic so I am posting my question here. We have been running into trouble viewing the soma of our 3D imported neuron created in Neurolucida into NEURON. Following the previous posts in this forum, we set all the soma contours to cell body as well as organizing them in monotonicaly increasing order. We have had success with other cells created the same way, yet one cell appears in many pieces but with no soma. The asc file has the soma information, but for some reason the soma disappears when the cell is imported to NEURON. We compared the asc file to other working files and could find no obvious discrepancies. Any ideas?
ted
Site Admin
Posts: 6287
Joined: Wed May 18, 2005 4:50 pm
Location: Yale University School of Medicine
Contact:

Re: Neurolucida to NEURON best practices?

Post by ted »

Sherif wrote:one cell appears in many pieces but with no soma. The asc file has the soma information, but for some reason the soma disappears when the cell is imported to NEURON.
If you zip up this particular NeuroLucida file, and also one that imports properly, and send them to me, we'll see what we can figure out.
Post Reply