CellViewer Tutorial

Note that there is a set of step-by-step examples of using CellViewer included in the CCB MIEN User's Guide. It is more general and up to date than the Dataviewer section of that document, and may be helpful.

While reading this tutorial, you probably want to refer to the manual, which describes how to navigate in CellViewer (CV), and how to use the menus and preferences. If you do not have a working mien install yet, you will need to look at the install instructions, and if you are running an older version of mien, update it. If you have trouble opening a terminal, starting the apps, or loading files, see the quickstart.

This tutorial uses the same conventions as other MIEN tutorials. In particular, selection of CV menu options will be written like this CV->File->Load, meaning "In the CV window, open the File menu, and click on the Load option".

Many of the most useful editing functions of CV are implemented in extension blocks. Consequently, what you can do with CV depends on which extensions you have installed. If you have extensions, check for documentation and tutorials particular to those extensions. This document only shows operations that are available using the core MIEN package with no extensions.

The first section of the tutorial only describes viewing some anatomical data. A second tutorial shows some editing functions.

Viewing Anatomy Data

Start CV and Import Data

Open a terminal, and use the command:

This will open CV and download an anatomical data file. It may take some time depending on your web connection speed.

You can also download the file first, with curl, wget, or a web browser, open CV using mien -a cell, and open the data file by using CV->File->Load or by dragging the file into the CV window from a GUI file manager.

If you used the command to automatically open the file from the url, you may want to save a local copy, in case you want to restart the tutorial later. Select CV->File->Save As. In the subsequent dialog, leave Format set to guess from filename, and enter the file name ten3anat.nmpml. Nmpml files are a dialect of XML. If you like, you can look at this file in your favorite XML editor (be warned, though: it is quite long).

CV will open the data file and display an image. You are now looking at the plan view of a cricket sensory interneuron, and some fiducial lines. The lines show the outline of the ganglion that this cell is contained in. They would be useful for comparing this cell to other anatomical data from a cricket terminal abdominal ganglion. We aren't going to do that, so we will get rid of the line plots in just a moment. First, let's get a feel for the 3D shape of the ganglion, and the extent and location of this neuron within it.

Navigating in the Scene

Press "2" to look at a side view of the ganglion. Now press "3" to look at it end-on. Press "1" to get back to plan view (this is the view you would see by looking in the microscope at the slide this data set was digitized from). Press "a" or "d" and hold the key down to orbit your view around the data set. You can also use "s" or "w" to orbit around the other axis. When you are done, press "1" again.

Now, lets hide the fiducial lines. Select CV->Display->Filter. In the dialog that appears, click "Cells", now hold down Shift and click "Spheres" to select both. Once you have "Cells" and "Spheres" selected, click OK. The screen will go black for a second, and then CV will redraw the scene, but with the lines removed. The filter element "lines" wasn't included, so the lines are hidden. "Cells", obviously, refers to cell morphology data, and this was selected, so the cell is still visible. "Spheres" are another type of fiducial marker: 3D points with associated diameters. In this data set there are a few spheres, which were used to mark the location of some synaptic varicosities on the small branches of the axon. They are hard to see at this scale, but we will zoom in and look at them in a moment.

The dendrites of this cell are quite detailed, but hard to see at this scale. Let's zoom in and look at them. First, right-click in the center of one of the dendritic branches. This will center the point you clicked on in the view. Now, press "=" several times to zoom in. You can zoom back out with "-", or all the way back to the default view with "1".

The CV manual lists all the available view navigation functions for CV. Check out the keybindings described there, and navigate around the scene as much as you like.

Selection

Even when zoomed in, identifying individual processes in the fuzz of dendrites can be difficult. Suppose you are interested in the path of dendrite branches leading to a particular point? CV can make connections in the dendritic tree easier to see using selection. Try holding down Shift, and left-clicking on a dendrite tip. CV will print some information about the point you clicked nearest to. New select CV->Selection->Select Proximal. CV will select, and visually highlight, the set of sections connecting the tip you clicked on to the cell body.

These selections can be used for more than visualization. If you had launched CV from a MIEN XML editor, you could send the selection you made back to the editor, and do something with the sections. We'll do that in the last part of the tutorial. For now, select CV->Selection-Clear Selection to to restore your view to normal (and your selection list to the empty list).

Synapses and Mechanisms

The model you are looking at includes some data besides morphology. It also has some synaptic inputs, ion channels, and passive electrical properties. If these properties are defined, CV can visualize them.

First, let's look at the distribution of an ion channel. Select CV->Extensions->Visualize->Show Mechanisms. A dialog appears listing the mechanisms. This model is rather simple, and defines constant passive properties throughout, so visualizing these won't be very interesting. Select Channel:paraNa. This is a parametric HH-like sodium channel, and is only present in and near the cell axon. Click OK.

You will see a region of the axon and proximal dendrite displayed in white, and the rest of the cell faded to dark blue (remember that this is an insect neuron, so it is rather typical that the electrogenic region of the axon begins some way away from the cell body). If there was a range of channel densities, this range would be displayed using pseudo-color. Since this is a simple model, the channel is either present (at a constant density) or not present, thus only two colors are displayed.

To get rid of the mechanism highlighting, you can select CV->Display->Replot.

Now, let's look at the synapses. Select CV->Extensions->Visualize->Show Synapses. A bunch of new Spheres will appear, larger in diameter than the ones used to mark varicosities. They are the same color as the cell, though, so they are not very easy to see. Let's fix that. Synapses, like other MIEN elements, can have meta-data attributes. Which ones they have will depend on the researchers that built a particular model. The synapses in this model have an attribute named "Direction", which reflects a putative tuning property of the sensory afferent cells providing the synapses (the details of the development of this particular model are previously published, but not relevant to this tutorial). In any case, CV can color the synapse markers using any numerical property, so let's use the "Direction" property, which is already set. Select Extensions->Visualize->Color Synapses. In the resulting dialog, leave Color using which attribute? set to "Direction", and set Color Scale Type to bgcyr. Click OK.

The synapses should look nicer now, and you can also see that there is some sort of spatial grouping to this "Direction" attribute.

If you haven't already saved a local copy of this file, and you want to look at the next tutorial, save a copy before you exit CV.

Using a CV Selection in Model Editing

Open the XML Editor and a Linked CV

Rather than opening CV directly, this time we are going to open the XML Editor first, and launch CV as a helper application. Assuming that you saved a copy of "ten3anat.nmpml", open a terminal, switch to the directory where you saved that file, and use the command:

The XML editor will open, displaying the element tree for the document in the left-hand panel (on some versions of Linux, you may need to resize the left-hand panel by hand to see anything).

Select XML->Extensions->Show Cell Viewer to launch CV from the XML editor. CV should open with the same initial view as in the last tutorial.

Remove the Fiducials

Last time around, we used CV's display filter to hide the fiducial lines in this data set, but this time we will remove the elements entirely.

The tree view (left-hand panel) in the XML editor supports typical extended selection. You can use Shift-click and CTRL-click (or CMD-click on Mac) to select multiple elements. You can also select one element with a click, and use Shift-down-arrow to add the element below it to the selection. Select all 7 of the elements called "Fiducial" at the first level of the document tree. Once they are selected, right click on them. This brings up a context menu. Select Delete in the context menu. In the confirmation dialog, say "Yes" to "Really delete?" and click OK. Note that the elements are removed from the document tree, and they vanish from the CV display.

Transferring Selections Between GUIs

The CV that you launched from the XML Editor is slightly different than a stand-alone CV. The navigation interface is the same, but a few menu options are different. Most of the entries in the CV->File menu are missing, because the linked CV assumes you will do file operations such as loading and saving from the parent XML Editor. Also, the CV->Selection menu has two new options: Export Selection and Import Selection. These options allow you to transfer lists of selected elements between the parent Editor and the CV.

First, let's import a selection. In the XML left panel, open the element "Cell:ten3" by clicking on the triangle (or plus sign on some platforms) that appears to the left of the name. You can also do this by selecting the name and then pressing right-arrow.

There are a lot of elements under Cell:ten3. The model contains more than 1000 sections. Dealing with them individually would be very time consuming and error prone. Fortunately, we can operate on groups of elements at the same time, and CV provides a nice interface for building these groups.

This model already has some saved groups, called NamedRegions. One of the first child elements of the Cell should be called NamedRegion:Active. Select this element, and right-click on it. In the context menu, choose Select Sections. You're view will move to the first section in the region (section[8]), and XML will print a message that it selected 7 sections. Make sure you don't click in the tree browser again, or you will change the selection (if you do that, go back to the NamedRegion and repeat the selection. Switch focus to the CV window. in CV, use CV->Selection->Import Selection. The axon region of the model will be highlighted. This shows the location of the sections included in the NamedRegion.

You can also select individual sections in the tree browser, or any set you want (using the extended selection keys), and import the manual selection into CV, but it is usually more useful to go in the other direction, so let's do that.

Create a Customized NamedRegion

Choose CV->Selection->Clear Selection to remove the selection in CV (but not in XML, yet). There are three main dendritic regions in this cell, including one in the upper right which looks triangular in plan view. Locate the large diagonal process leading to this dendritic region, and Shift-left-click on it in CV. Now use CV->Selection->Select Distal. CV will highlight the triangular region (You may notice that the start of your selection isn't at exactly the point you clicked. This is explained in the CV manual. You probably didn't click at a section boundary, so CV selected the section containing the point you clicked on. Don't worry about this for now).

Now use CV->Selection->Export Selection to send the selection back to XML (replacing the previous selection). Switch back to the XML window, again, don't left-click in the tree browser pane, or you will change the selection. Instead, right-click on one of the selected elements.

The context menu detects that you have multiple elements selected, and adjust the set of options you see accordingly. In addition, since you have a set of several elements that are all cell sections selected, you will see the additional option "Make Region". Choose this. In the resulting dialog, name your region "RightDendrite", and click OK.

This adds a new element to the cell. You will probably need to scroll down to the bottom of the tree view to see your new element: "NamedRegion:RightDendrite". You can open that element to see a list of references to the sections that you had selected. The region element will save this set of selections if you save the file, and can be used by other functions to make edits to specifically these sections.

Make a Reduced Complexity Model

Suppose would like to look at spike generation in the axon of this cell, without simulating all the dendrite compartments (it might also be interesting to see how removing the dendrite electrical load changes spike generation). It's pretty easy to remove parts of a model using CV's selection tools.

The axon sticks up toward the top of the screen in plan view (actually, this is only the start of the axon, the morphology of the whole axon of this projecting interneuron isn't part of this model). Let's select it.

In the CV window, select CV->Selection->Clear Selection. Now Shift-click on the axon, out beyond the bulk of the dendrites. Use CV->Selection->Select Proximal. (If you get errors at this point, or at any point after operating on a selection in the XML editor, make sure that you have cleared the selection in CV, and then try again). This will select the region between the section you clicked on and the cell body. If there are still some un-selected sections past the point you clicked on, use CV->Selection->Select Proximal to select them too. Multiple selection commands will add to your selected region, not replace it (which is why we have to use "Clear Selection" before starting a new selection).

Now the axon is selected, but what we want to operate on (by deleting it), is actually everything else but the axon. Use CV->Selection->Invert Selection, and all the dendrites will become selected. Now use CV->Selection->Export Selection. In the XML window, right-click and choose Delete, say yes to really delete, and click OK.

Now you have a very much reduced cable model of the axon, SIZ, and cell body of this cell. You can use XML->File->Save As to save this to a new file if you like. For example, you could save as a hoc file, and run some virtual experiments on the segment in Neuron (actually, you could construct the experiments in MIEN, and run them, using Neuron, from within MIEN also, but that is beyond the scope of this CV tutorial).