NEURON Programming Tutorial #2

Introduction

One of the last commands we added to our program in the last tutorial was:

load_proc("nrnmainmenu")
This command loads the functions in the standard run library which contains the nrnmainmenu() function. In this tutorial, we will explore the nrnmainmenu() function and others that are used in the graphical user interface.

The graphical user interface

NEURON's graphical user interface (GUI) is based on InterViews (developed by Silicon Graphics Inc. and Stanford University). This GUI allows NEURON to easily display and print graphs, create menus, buttons, and other GUI tools.

In this tutorial, we will build on the program that we started last time. To get started, start NEURON with your program from tutorial #1:

nrniv prog1.nrn -
In NEURON's GUI, many of the most useful functions have been placed into the standard run library (which we loaded with the load_proc() command). To start the GUI, enter the following at the oc> prompt:

nrnmainmenu()
This will open two windows on the screen: the Print & File Window Manager and the NEURON Main Panel.

Before getting into the specific functions in these panels, we need to explore some general concepts and features of NEURON's GUI. For our example, we will use the NEURON Main Panel.

The first three buttons in the NEURON Main Panel have next to them a field editor box with some numbers in them. Whenever you see this type of box, you can enter a new value by simply moving the mouse into the field editor box and start typing. A flashing vertical bar will appear when you start typing a signifies that you are editing the value in the field editor. After you have entered the new number (or expression), you need to tell NEURON to accept the number (or expression) you just entered. You can do this by either pressing the Enter key, by clicking on the button associated with the field editor or, if there is another button (called a check box) between the main button and the field editor box, you can click on that button. The check box is used to toggle between the default value and your changed value. Thus, if you change the value of celsius, a check mark will appear in the check box signifying that you have changed the value of this field editor. Then, by pressing the check box, you can toggle between the default value and the changed value.

The last four items in the NEURON Main Panel are menus. To bring up a menu, click and hold any mouse button down on the text of the menu button (e.g., the New Graph menu button). This will bring up a list of other items which you can select from by dragging the mouse pointer over the text of the menu item. Releasing the mouse button will select the menu item. Menus can be hierarchical--for example, the Point Processes menu contains two sub-menus, Managers and Viewers, from which you can select other menu items. If you click on a menu and it stays up, you can click in another part of the window to make it disappear.

This should be enough to get us started. We will describe other specialized functions in the user interface as we come across them.

The Print & File Window Manager

The Print & File Window Manager window contains several different buttons, menus and two rectangles on the right side of the window. This window is special in NEURON and is treated differently than the others in the following way: The first button in the upper left corner of the window is the Dismiss button, and pressing this will cause the window, and all other NEURON windows, to be closed. The window has not exited--it has simply been iconified, and can be re-opened by deiconifying it (see the X Window System's man pages if you are not familiar with iconifying). Upon re-opening the Print & File Window Manager, all other NEURON windows are re-opened as well. Note: In all other windows, the Dismiss button will cause the window in which you pressed the Dismiss button to exit.

The Help button will start the help system. The help system is designed to allow you to explore NEURON's features by selecting the item you want information on. The information you request will then be displayed in the NEURON Help window. I highly recommend that you take some time explore NEURON with the help system. While in help mode, the cursor changes from an arrow to a question mark. To exit help mode, simply press the Help button in the Print & File Window Manager window.

The left most of the two red rectangles in the window represents the entire NEURON display--we will call this the Manager rectangle. Each smaller blue rectangle (with a number in it) represents one of NEURON's windows. The second red rectangle represents a sheet of paper--we will call this the Selection rectangle. It is used to print selected windows to a file or printer and to save selected windows in a session file. To select one of the windows to print or save, click with right mouse button in one of the smaller blue rectangles in the Manager rectangle, and you will see it appear in the Selection rectangle. To remove the window from the Selection rectangle, simply click with the right mouse button in the small numbered rectangle that you wish to remove. You may also want to move (left mouse button) or resize (middle mouse button) the windows in the Selection rectangle.

The Print button will print the currently selected windows (i.e., the ones in the Selection rectangle) to your PostScript[TM] printer. If you would like to change the printer that you will print to, you can select the Select Printer option in the Other menu. This will pop up a window in which you can enter the command to print your file to the new printer. You can also change the layout of the paper to Landscape from Portrait mode (or vice versa) by selecting the Land/Port option in the Other menu. If you would like to print the PostScript output to a file, then you can select the PostScript option under the Print to file menu.

We will come back to some of the other options in the Print & File Window Manager window later.

The NEURON Main Panel

The NEURON Main Panel is entry point into NEURON's graphical user interface. Many of the most useful features of the GUI are either directly or indirectly accessible from the NEURON Main Panel. Below we describe many of these features.

The first item in the panel is the Real Time counter. It displays the computation time (in seconds) and is useful to determine how long your simulation takes. The second item displays the temperature (in celsius) used in the simulation, and affects all temperature dependent variables such as the state variables in the Hodgkin-Huxley channel models. The third item allows you to globally change the Axial Resistivity in all of the cable sections (see the next tutorial for a description of how to create and connect multiple sections together).

The RunControl button opens up the RunControl panel from which you can run and control different simulations. See the next section for a description of the RunControl panel.

From the New Graph menu, you can create different types of plots including plotting variables vs. time or vs. space, or plotting variables in a phase plane. See below for information on plotting variables vs. time, and see the next tutorial for more information on plotting variables vs. both space and time.

This section is still under construction. Please see the help system for an explanation on how to use the other items in the NEURON Main Panel.

The Run Control Window

In the previous tutorial, we ran simulations using the run() function. If we needed to change one of the simulation control parameters (e.g., tstop), we had to do this by typing some code:

tstop = 10
which was rather tedious. The RunControl panel was created to allow easy access to NEURON's simulation control parameters, and to allow people to easily start and stop their simulations.

To start a simulation, press the Init & Run button in the RunControl panel. This will initialize all of the simulation parameters, and start the simulation. It is equivalent to the run() command we used in the previous tutorial. The Stop button will halt a simulation, but it can be resumed by using either the Continue til button to continue the simulation until t reaches the value in the Continue til field editor, or the Continue for button to continue the simulation for the number of milliseconds in the Continue for field editor. If you would like to continue the simulation for one time step, you can press the Single Step button.

The actual simulation time, t, is displayed in milliseconds, and at each time step, it is incremented by dt. The time the simulation normally terminates, Tstop, is also displayed in milliseconds.

Complex simulations can require a small dt for accurate results. If we are also generating graphs during the simulation run, this could slow the simulation down even further. To moderate this, we can set the number of times NEURON updates the graphs per millisecond in the Plots/ms field editor. Choosing a value for Plots/ms that is greater than 1/dt will change dt to accommodate the increased plot resolution.

Since we can now run the simulation using the Run Control Window buttons, we no longer need our rununtil() procedure and can remove it from our program.

Creating and using graphs

Graphs are an integral part of NEURON's user interface, and are designed to allow users to generate simulation results which can be directly incorporated into papers. With the Print button or Print to file menu in the Print & File Window Manager, you can save graphs in PostScript[TM] format.

From the New Graph menu in the NEURON Main Panel, you can select several different types of graphs. In this section, we will explore plotting different variables vs. time, and as examples, we will create two graphs, one plot of voltage vs. time and one plot of the different somatic currents vs. time.

There are several different axes available when plotting variables vs. time (Voltage axis, Current axis and State axis). Each of these require their own graph since the method used to solve the cable equations, developed by Mike Hines, calculates each of these variables at different times. For example, voltages are calculated at each time step, but currents are calculated at the half time step before voltage and the state variables are calculated at the half time step after the voltage. For more information on the numerical method used to solve these equations see (Hines, 1984).

To create our voltage vs. time graph, we can select a Voltage axis from the New Graph menu in the NEURON Main Panel. This opens a new graph window with voltage axes (-80 mV to +40 mV on the Y axis and 0 to tstop on the X axis), and by default, the voltage in the middle of the currently accessed section is selected to plot. In our program, the soma is the currently accessed section, so the default voltage graph will plot the desired function. Running the simulation (via the Init & Run button) will run the simulation and plot the voltage in the middle of the soma vs. time.

To create our currents vs. time graph, we can select a Current axis from the New Graph menu in the NEURON Main Panel. This opens a new graph window with current axes (-1 nA to +1 nA on the Y axis and 0 to tstop on the X axis). For current graphs, no variable is selected to plot by default, so we must choose what to plot from the graph menu.

Each graph has its own menu that can be accessed with the right mouse button. Plot what? in the graph menu will pop up a window that allows us to choose what current variable to plot. The variables can be either directly typed in if we know the exact name of the variable we want to plot, or they can be selected from the list of variables in the selection boxes.

We want to plot the somatic currents, so we need to select soma in the first selection box, and then select one of the currents from the second box. The available currents are ik, ina and il_hh. We can select a variable by either double clicking with the left mouse button on the variable name, or we can click once on the variable name and the press the Accept button. For our current graph, we want to plot all of the soma currents, so we need to select soma.ik(0.5), soma.ina(0.5) and soma.il_hh(0.5) from the Plot what? menu option.

This section is still under construction. Please see the help system for an explanation of how to use the other options in the graph menu and how to create other types of graphs.

Saving and retrieving sessions

After creating several graphs, you may want to save the windows you have created (i.e., graphs and panels) to a file so that you can recall them at a later time. NEURON allows you to save either all or selected windows to a session by selecting the Save selected or Save all option of the Session menu in the Print & File Window Manager. Save all will save the position and contents of all NEURON's windows. Save selected will save only those windows that are currently selected in the Selection rectangle in Print & File Window Manager. Either of these options will pop up a window in which you can enter the filename of your save session.

If we save our session to a file, we can either load the session each time we load our program by selecting the Retrieve option of the Session menu in the Print & File Window Manager, or we can have our program automatically load our session for us. To do this, we need to add the following to our program:

xopen("prog2.ses")
where prog2.ses is the name of the session we saved (Note: the name must be in quotes). The next time we start our program, the session with our graphs and menus will automatically be loaded into NEURON.

Here is our program so far:

load_proc("nrnmainmenu")

create soma
access soma

nseg = 1
diam = 100
L = 100

insert hh

objectvar stim

stim = new IClamp(0.5)

stim.del = 0
stim.dur = 0.1
stim.amp = 30

xopen("prog2.ses")

What's next

In the next tutorial we will explore how to build cells with more complex morphologies and how to create a new dynamic type of graph, a space plot.


Kevin E. Martin (martin@cs.unc.edu)