	NEURON : Neuronal simulation environment.

		Developed by Upinder S. Bhalla,
		California Institute of Technology, 
			Written under Genesis/Xodus


1	INTRODUCTION.

This is Upi's Neuron simulation environment, developed to facilitate 
simulations of single neurons. It provides the following facilities :
*	Running simulations of neurons with a variety of electrophysiological
	manipulations.
*	Storage of simulated data, for later analysis eg. by the xfileview
	script (from orient_tut).
*	An interface to the neuron descriptor files, which concisely specify
	the geometry and electrical properties of neurons.
*	A means for editing the electrical and geometrical properties of
	neurons in the simulation.
*	A facility, still under development, for cutting and pasting neuronal
	components to redesign the simulated neuron.

This is meant to be a functional system, and not a prettified demo program.
The script files are pretty grim, and are not good for novices to tinker with.
Having made this Government Health Notice, I welcome enhancements and bugfixes
to neurokit. Please notify me of such changes, so I can incorporate them into
the release version.

At this point in the development of this utility, the recommended way of
designing new cells is to edit the cell parameter file in parallel with 
the simulations. Simple changes can be made using the editing functions
in the utility, but global changes are not easy to do in this way. When
the cell has evolved enough in the course of tinkering with it, the new
version can be easily saved and loaded back in.

The parameters used for the prototype elements in the library are defined
in the constants.g and protodefs.g files. At this point these cannot be
edited from within the utility. If you wish to define new prototype elements,
just create them in the Genesis /library element, like the other prototypes.
The currently defined prototype channels are derived from a number of
sources, primarily Hodgkin and Huxley, and Traub. New channels (ie, channel
parameters based on experiments) for the library will be most useful.

The cell reading utility only works for very simple channels. When 
dependencies on Ca concentration arise, the tidy formalism of the cell
parameter files cannot cope with the extra complication. In order to use
[Ca] dependencies, I suggest defining complete compartments in the library,
which have all these built in. Any suggestions about how to incorporate
[Ca] dependencies into paramter files will be welcomed.

2	A QUICK EXAMPLE

2.1	STARTING UP.
Type :

genesis NEURON

The credits will flash on the screen, and then it will say /library and
sit there for anywhere upto 5 minutes depending on your machine. (This is
when the library of prototype elements is being set up, you can trim
the library if you like to speed up this phase). 
	Then there will be a few obscure comments to the effect that some
widgets have no scripts attached to them. Ignore these. Eventually a title
bar with options :

quit  help  file  run cell  edit cell  edit compt  edit channel  multisim

will appear. Hit the 'help' button, and this file will be displayed. I suggest
that you proceed with these steps forthwith, and then you will be able to read
the instructions and try them out at the same time.
You can move around the file using the button commands indicated at the top of
the help window. Alternatively, the keys 'j' and 'k' move up and down the file
a line at a time, and 'f' and 'b' move a page forward and backwards. To go
to the top of the file, hit 'a', and 'z' to go to the end.

2.2	LOADING IN NEURON DESCRIPTIONS.

Hit the 'file' button. A menu with several options will appear. The default
parameter file should be ok to use, so hit 'Load from file'. This will
read the file specified by 'source_file_name' into the cell specified by
'Cell for IO'. The menu will then vanish in a puff of bytes, accompanied by
a few inane remarks in the simulation window which you can ignore.

2.3	RUNNING THE CELL

Hit 'run cell'. Three windows should appear : To the left, a hideously complex
menu with all sorts of options for running cells and saving them. On the top,
a picture of the cell itself. At the bottom right of the screen, there is a
graph which will contain the plots of intracellular potentials.

The 'Recording' button in the menu should be lit up. Using the LEFT mouse
button, click on a number of places on the cell displayed in the top window.
Each time, a representation of an electrode will appear, stuck into a
compartment. The MOUSE window in the top of the cell window indicates the
function of the 3 mouse buttons.

Hit the 'Iclamp' button on the main menu, and go to the cell and click
(again with the left mouse button) on the central compartment in the cell :
the soma. A black, two-tailed electrode will appear to represent current
injection.

Hit the 'run' button. The simulation will start off, with the cell turning
bright colors (hot representing high membrane potentials), and the graph
displaying plots of the potentials of the compartments you stuck the
recording electrodes into.

You can add and remove electrodes, both recording and stimulating, while
the simulation is in progress. 

2.4	EDITING CELL PROPERTIES

Hit 'edit cell'. A variety of windows open up. Except for the Parameter 
Window, all have a 'Mouse' window on top which tells you what the mouse
buttons do.

 ------------------------	---------------------------------
 |			|	|				|
 |    Library Window	|	|	Compartment window
 |			|	|				|
 ------------------------	---------------------------------

 ------------------------	---------------------------------
 |			|	|				|
 |      Cell Window	|	|	Parameter window
 |			|	|				|
 ------------------------	---------------------------------

The library window has a list of the available prototype elements defined
in the protodefs file. One can click-to-select as indicated by the Mouse
window for the library. The currently selected element is hilit in red.

The Compartment window has a representation of the currently selected 
compartment, and the ion channels associated with it. The currently selected
channel is outlined in red.

The Cell window has a representation of the current cell. The currently
selected compartment turns red.

2.4.1 Selecting compartments.
Hit the cut-n-paste toggle on the bottom of the cell window. It should now
say 'edit shape'. Using the left mouse button, (Select, as indicated in the
mouse window) click on various compartments. They turn red, and the compartment
window  now represents the selected compartment. The parameter window
displays the properties of the selected compartment.

2.4.2 Selecting Channels.
Go to the compartment window and again change the 'cut-n-paste' toggle to
'select'. Now click on the channel you are interested in and it should be
hilit, and a brief list of channel properties will appear in the Parameter
window.

2.4.3 Editing parameters. 
Go to the 'Length' dialog in the parameter window. This represents the length
(in microns) of the selected compartment. Change it. The length of the
compartment in the cell window should change accordingly. Similarly, the
other parameters of the selected compartment and its channels can be
altered. 
	Another way to change the geometry of a compartment is to go to the
cell window, and use the 'stretch' and 'rotate' buttons on the mouse. These
options work in the 3 orthographic projections : z2d, x2d, y2d. Select 
z2d (Looking down from the z axis) by hitting ctrl-z in the cell window.
Now you can do the stretch and rotate operations in the xy plane. Similarly
you can change to the xz plane by hitting ctrl-y. A list of the control
command options for the draw windows is given in section 3.2 below.
	You can stretch and rotate several compartments at once by clicking
the 'select one compartment' toggle in the cell window so that it says
'select sub tree'. Now if you try the select, stretch and rotate options
you will see that they operate on all sub-branches of the element you
clicked on.

2.4.5 Cut and paste.
Set the toggles on the cell window to 'select one compartment' and
'cut_n_paste'. Copy a compartment from the cell into the library by
clicking the right button on the desired compartment. The library will
now have a new item in it, a duplicate of the compartment you just copied.
Select the compartment in the library by clicking on it using the left mouse
button. The name of the compartment appears in the 'sel' dialog in the library
window. If you were to try to paste this to the cell, it would complain that
the element already exists. There are two ways to get around this.
	One is to rename the element in the library, by typing something
else into the sel dialog. So, change the name of the element to 'newone'.
Now do the paste. 
	The other method is to flip the 'Use sel name when pasting' toggle
to 'Do Rall renaming'. This activates automatic renaming of elements 
following the Rall scheme, every time they are copied. This allows you
to copy compartments without having to manually rename them every time.
Paste a couple of compartments on to see how this works. Check out the
new names by going back to 'edit shape' mode in the cell widget and selecting
the new compartments.
	Cut and paste also works, in a similar manner, in the compartment
window. Again, you can't overwrite existing elements.

2.5	EDITING COMPARTMENT PROPERTIES

This is essentially identical to the process of editing cell properties,
except that the parameters displayed are specific to the compartment
selected and are more detailed.

2.6	EDITING CHANNEL PROPERTIES

This is still being worked on. The parameter window still has to be defined.

2.7	SAVING AN EDITED FILE

Hit the 'file' button on the title bar. This pops up the file menu. The
name of the file that your edited cell is going to be written to is in
the 'Save to file' dialog. As soon as you hit return, the file is written.
You could also change the 'Your Name' field so that the saved file has your
name as the author. Now go back and look at the new file and see how
your changes are reflected in the parameters of the cell.

2.8	RUNNING MULTIPLE MODELS SIMULTANEOUSLY : MULTISIM
Not yet operational.

2.9	EXITING

Hit the 'quit' button. A menu will pop up asking if you are serious. If you
are, kaboom.



3	INFORMATION ABOUT THE 'run cell' ENVIRONENT

3.1	SIMULATION CONTROL WINDOW
The menu window 'CELL RUN CONTROL PANEL' provides a number of dialogs
(the yellow areas where you can enter values) and buttons (The red areas).
3.1.1
The top couple of lines are for controlling the running of a simulation.
'stop' stops a simulation in progress, 'reset' puts the cell back into resting
potential, 'run' causes a simulation to run, and 'run paradigm' runs the
current specified paradigm file, which enables you to set up a complex
sequence of manipulations to be performed during a simulation.
The 'nstep' and 'runtime' dialogs are linked, and specify how long the 
simulation is to go, in simulation steps and simulated time respectively.

3.1.2
They are related, of course, by the duration of the simulation clock 'clock'
under the 'TIMING' category. The 'current_time' keeps track of where the
simulation is at the moment, and the 'refresh_factor' specifies the number
of steps that the simulation should go between graphics refreshes. The latter
should be kept large specially if you have a slow display, otherwise the
graphics will hold up the simulation.

3.1.3
'ELECTROPHYSIOLOGY' contains a number of things you can do to torment your
neuron. Any of these can be done before or while the simulation is run.
	You have already stuck recording and current injection electrodes
into the neuron. You can change the injection of the last (and future)
injection electrodes by setting the 'inject' dialog.
	The 'Vclamp' option does voltage clamping. At this point there is
no easy way to display the current being used to do the clamping.
	The 'Syn act' option sets the synaptic activation on a particular
compartment. It is equivalent to squirting some transmitter (selected by the
mouse button) onto the selected compartment. This stuff will hang around till
you repeat the click. Many channels have long time constants - the delay in
effects you see is not due to the transmitter hanging around. The amount
of transmitter is set by the 'Amount of synaptic activation' dialog.
	The 'Syn spike' option enables you to deliver a single pre-synaptic 
impulse to the synapse. Strength determined by the 'Weight of spike' dialog.
	The 'Syn rand' options delivers random presynaptic input, at an
average rate set by the 'Spike rate for rand' dialog.

3.1.4
The 'FILE IO' commands are just that. They set the options for saving
simulation data. The 'filepath' is the name of the directory to which
the output will be sent. The 'file_index' is a suffix added to the files
created by this particular run (useful when running a simulation series).
The run-info toggle decides whether or not a file containing some info about
the simulation (name of other files, time, notes) will be written. This file
is named according to the 'info_file' dialog.
Similarly, you can choose whether or not to save the data from each of the
recording electrodes you stuck into the cell. The destination file is
specified by the 'plot_file' dialog.
Finally, you can save any desired field (dialog 'field') in any compartment(s)
(dialog 'field_path') of the neuron. The 'field_path' is the wildcard path
of the desired compartments. By default, Vm (the membrane potential) of 
every compartment in the cell will be saved. The destination file is specified
in the 'field_file' dialog.

3.1.5
Running paradigm files.
A typical paradigm file is in paradigm.g. This is simply a script file,
which tweaks the cell parameters and sets the 'FILE IO' and other controls
to generate output for a series of simulations. Since a script file is being
used, just about anything you can code can be done in the paradigm.


3.2	CELL WINDOW
The top window is of the class 'Draw Widget', which is mentioned at length in
the documentation. This displays the selected cell geometry in 3d, and
also the membrane potential according to a hot colorscale where blue (cold) is
low potential (hyperpolarized) and yellow (hot) is depolarised.
3.2.1
You can do the following things in the draw widget, by
pressing the control key and a letter key as follows :
PAN COMMANDS	ctrl-j, ctrl-k, ctrl-h, ctrl-l  - up, down, left and right.
ZOOM COMMANDS	ctrl-i, ctrl-o			- in and out.
ROTATE COMMANDS	ctrl-q, ctrl-a, ctrl-<, ctrl->	- up, down, left and right.
						  (The side nearest you)
TRANSFORMATIONS	ctrl-x, ctrl-y, ctrl-z, ctrl-w	- Look along the x,y,z axes.
						  w selects 3d mode.
PRINT		ctrl-p				- If you have a postscript							  laser printer.
3.2.2
You can also perform a number of mouse point-and-click operations, specified
by the green 'MOUSE' window with red buttons (to represent mouse buttons) in
the top right hand corner of the cell window. The 'MOUSE' window changes
according to the currently selected electrophysiology option.
			

3.3 	GRAPH WINDOW
The graph window displays plots of membrane potential at the selected recording
electrode sites. By default, the traces are offset by 100 mV.

3.3.1 SCALING GRAPHS.
You can alter scales by hitting the 'scale' button at the top left.
It opens a menu with some obvious dialogs. The arrow keys scale the axis
named by 'field', in assorted and easily figured out ways. The selected
field may be changed by clicking on the 'field' button. The dialogs can also
be operated directly in the usual fashion. The new values will be assigned
to the graph when the APPLY or APPLY_AND_VANISH buttons are hit.

3.3.2 OVERLAYING PLOTS
The 'overlay' toggle does what it says, overlaying (or not) traces from
successive simulations.
