Acknowledgement
neurALC Version 1.0.x was developed during july - october 2005 in the group of Prof.
Dr. E. Fernandez at the institute of bioengineering of the university Miguel Hernandez, Alicante (Spain). The update to version 1.5.x was done during summer 2006 by the same team. We like to thank everyone who contributed to the making of neurALC.

Conventions Within This Manual
⋅ References in general or to components of the GUI, commands or other functions of neurALC are set using a typewriter face.
⋅ Textual description of menus or command structures uses >-symbols to illustrate a hierarchical implementation.

The Name...
Well, the program, or better its name come a long way. For a small group of people the software is also known as the program formerly called "WAND", "PROBE", or "Genie". These names were dismissed after we discovered that for example the Wide Area Network Daemon was simply there first, and well, there are a few trademarks on editable lubricants, etc. which use some of the names we thought of in the beginning - in short: neurALC is composed from two syllables - neur derived from the consideration that the program works with neuronal data, and ALC, which is the abbreviation used in international aviation for the Alicante airport.

Linux
The binary installer for Linux on x86 processor comes as a gnu-zipped tar archive. After download from sourceforge and dearchiving neuralc.tgz, run the install-neuralc.sh shell script from within bash. Prerequisites for using this binary are an installation of Trolltech's Qt framework version 3.x (KDE version 3 comes with libraries), the QWT version 0.4.2, QWT3D version 0.2.6 and the FFTW library package. To use the database functionality an additional installation of MySQL (version 3 or higher) is needed. Depending on the Linux-distribution you use, different ways of installing MySQL on your system exist. Refer to http://www.mysql.com for additional information.

MacOSX
The MacOSX installer-package requires MacOSX 10.3 or higher. The binary installer package includes the program and all required libraries (Qt 3.3.4 incl. support for MySQL, qwt 0.42, qwt3d 0.25, fftw3) for MacOSX. Depending on the processor (PowerPC or Intel Core/Xeon) inside the Mac you're using, you should download the file neuralc1.0-installer_"YourCPU".zip, dearchive and double click the icon to install (the PowerPC-binary will work on both CPU-platforms, but for maximal speed on your Intel-Mac please install the corresponding package). To use the database functionality an additional installation of MySQL (version 3 or higher) is needed. Visit http://www.mysql.com and download the MySQL-installer package for MacOSX of your choice.

Windows
The binary installer for Microsoft Windows is based on NSIS and installs the program, example files, manual, sources and all required libraries. Download neurALC-win32.exe from sourceforge, unzip it and click on the installer icon. The program is installed in its own directory in C:\Programs\neurALC and registered as entry within the Windows START-button menu. All required libraries are installed in the windows system directory. To use the database functionality an additional installation of MySQL (version 3 or higher) is needed. Visit http://www.mysql.com and download the MySQL-installer package for Windows of your choice.

Compilation
The program is written in C++. To compile under your flavor of MacOSX, *nix or Windows, first download and install the required libraries QWT, QWT3D and FFTW, as well as MySQL. Then download the neurALC source code-archive. Extract all files to a single directory, open a shell, change to the directory and type qmake, then make. That should be all you need to do. Under MacOSX and *nix gcc is used; to use the provided .pro-file under Windows, an installation of the mingw-package with such functionality, is recommended. If you run at this stage in to an error, generate a project file using Trolltech's qmake or change the supplied neuralc.pro according to your Qt installation and C++ compiler requirements.
As of this writing the non-commercial version of the Qt 3.2 framework for Windows is available only as a CD-Rom add-on of the book Blanchette, Summerfield: "C++ GUI programming with Qt3", ISBN 0131240722 (which offers in general a very nice introduction to Qt programming). To download the QPL/GPL version for other platforms visit the Trolltech web page.

Usage&Functionality
The neurALC GUI
Double click the program icon (shown on the right) to run neurALC. After the program start, open a data file with a neuronal recording in NEV-format (at the moment neurALC can only open recording files in the Neuronal Event Format Version 2). neurALC's user interface is designed in five (at least we think) logical sections. The main graphical user interface represents the hub to all available visualizations and program parameter. It provides access via four tabs:

The Population-Tab
As default after start-up, neurALC's Population-tab becomes selected/active. It is subdivided in an information and a visualization part. Information regarding the number of electrodes (active channels), date (creation date), number of recorded neuronal spikes (spikes), sample rate (in Hz), and the sorting status of units- (units:sorted/unsorted) or TRC (classes:sorted/unsorted) for the opened experimental file is provided (as far as it is filed within the file). Additionally an existing comment with up to 256 characters is displayed and can be edited or created via the provided text entry field.
The lower part of the tab is used to visualize the current data set or analysis result - on the level population or experiments. That implies that the result of any selected calculation or visualization will use all data - the recorded "population' - 'provided by the opened experimental data file. The slider widget at the button of the window allows, if applicable, to interactively adjust specific visualization or analysis parameter.

The Electrodes-Tab
Selecting the Electrodes-tab allows the user to access, analyze and visualize the information provided in the actual opened experimental file on electrode-, (if previously sorted and comprised in the NEV-file) neuronal unit- , and , if this analysis was performed, temporal response class (TRC)-level. Like for the Population-tab, the graphical user interface is subdivided in 2 parts: one which provides access to the single electrodes (Channel), neuronal units (Unit; only accessible if this information is contained in the actual opened experimental file), and temporal response class information (Class; only accessible if previously calculated and assigned).
The lower, second part of the Electrodes-tab serves as display for the visualization of the data or analysis results part. The slider widget at the button of the window allows, if applicable, to interactively adjust specific visualization or analysis parameter.

The 3D-Tab
neurALC offers a few visualization in three dimensions. The Option-pop-up menu in the upper part of this tab allows to select one of the provided visualization. Clicking the Home-button resets the view of the actual 3D-visualization in the lower part of the window. Using the mouse it is possible to rotate, zoom, or navigate otherwise within the three-dimensional visualization. Appendix-8.1 includes a table with neurALC's keyboard short cuts and a description of the possible mouse-based navigation. The slider widget at the button of the window allows, if applicable, to interactively adjust specific visualization or analysis parameter.

The Options-Tab
This tab provides access to all analysis and visualization parameter. The adjustable parameter are arranged in 7 different, tabbed views related to: the Trigger information within the opened experimental data file, Binning - ISI (inter spike interval) - Frequency, Correlation, Delay, Classification, Selection, and "el Ultimo". Any tuning in one of the options is applied to all related, further calculations or visualization during the actual program session.

The Trigger-tab allows to select and adjust the stimulus related time code ("trigger" information) which is filed within the actual opened experimental data file (or used for the "automatic" analysis of a directory of files). The NEV2-format definition allows to store 2 different data types with this information: "analog" and "digital" data packets. Up to 5 differently tagged analog (Analog 1, Analog 2, etc.), and one digital packet identifier (tagged as Digital) can be stored within the files. Both types can be selected, used as base for visualization, or their time stamp information edited from within this window.
Use the Start-pop-up menu to select the packet-label which marks the beginning of a stimulus. If the same analog or digital data packet is used to mark start and end of a stimulation, adjust the increment between successive stimulations via the text entry field in the same line. If a different data packet is used to mark the end of the stimulation, choose the corresponding data packet-label from the End-pop-pup.
Information of the number of the selected trigger events is provided: the sample rate at which these information was acquired during the experiment, and the list of the timestamps of the selected trigger packet/s (timestamps are displayed with their sample number saved during the acquisition of the actual opened experiment). Up to 32756 different of these timestamps can be directly edited from within this tab by clicking the the Edit Trigger-button.

Binning, ISI, Frequency
Binning, inter spike interval (ISI), and frequency related parameter can be accessed from this window. Use the provided widget to adjust the bin size to meet the requirements needed.
Adjust the range within the inter spike intervals are extracted and displayed from the actual opened file using the Minor- and Major-widget in the window part marked as
The frequency range for instant firing rate calculations can be adjusted with the corresponding widgets.

Correlation
This window allows the definition of all parameter for correlation-related calculations. Use the Window-text field to adjust the symmetrical time window in which the correlation function is determined. Set from the Channel-pop-up the reference electrode and, if existing, the reference neuronal unit or temporal response class for the cross-correlation calculation. Choosing All from the Channel-pop-up means that the correlation of the selected electrodes is calculated against the population activity (cumulative activity of all recorded events exclusive the electrode/unit for which the correlation function is determined.)

Delay
Adjust the time lag (Delay) and Dimension number which are used for delay embeddings. These parameter influence the phase space reconstruction of the opened or selected experimental data set. The method is taken from the TISEAN package and used in a few analysis functions of neurALC.

Classification
neurALC offers the option to classify within single or multiple experiments registered spikes according to their temporal response in the PSTH. The accessible parameter for this processing can be adjusted from this part of the Options-tab. Specify the eigenvector calculation using the pop-up-widget provided.
For the clustering process of the data some parameter can be adjusted via the widgets in this panel. The classification process can additionally applied to all experimental files in a directory defined. In this case the actual defined parameter set in this and the other sub-windows of the Options-tab (e.g. the bin size, number of selected electrodes, etc.) is used for the classification of the directory data.

Selection
A set of electrodes from the actual opened experiment can be selected. The data set represented by this selection is then used for all further analysis or visualization methods. The main part of the window is occupied by a 10x10 electrode matrix.
When an experimental data file is opened, the activity recorded on each electrode is color coded: darker button backgrounds mean high activity; lighter grey backgrounds lower or no activity. If the mouse cursor is shortly paused over one of the electrode buttons, a tool tip with the actual number of recorded events during this experiment on this electrode is shown. If the All-checkbox on the right becomes activated, all electrodes will be selected. The Invert Selection-button inverts the actual selection. Activating the Cumulative activity-checkbox will enable the calculation of the cumulative activity on all electrodes and, if appropriate, include it to data analysis and/or exported files.

"El Ultimo"
This part of the Options-tab incorporates, as the name already indicates, access to function and/or parameter which do not really fit to any of the other option, or were implemented "last minute" to the program. This does not mean that this function were not comprehensively tested *well, as far as time permitted*- mainly the provided functionality is not fully implemented. For the first release of neurALC the shuffling function offers just one way of doing it, and might be subject to further extension in the future. Likewise the function to extract the timestamps of a designated firing sequence of neuronal electrodes, units or temporal response classes - the extraction works, but detection of existing fire pattern is not implemented so far. For the moment we have developed a small and simple external program to determine such fire patterns - if you interested in using this program and to collaborate, feel free to contact us.

The neuralc-menu
This menu provides access to the About neurALC-information and allows to quit the program.

The File-menu
From this menu experimental data files in NEV2-format can be opened and analyzed in neurALC (FileOpen File). Any opened files can be saved to a new file in NEV2-format (FileSave to NEV2). If the post-stimulus time data of the opened experiment were classified into TRCs, the result can be save using the FileSave classes (ASCII)-entry from the menu. Calculation results can be saved to files in ASCII-format using the FileSave Results (ASCII) command. If MySQL was installed on the system in use, and successfully detected by neurALC, the results of the actual displayed analysis can be transferred and stored in the database using the FileExport to database...-command. Choose the FileClose-command to close the actual opened and analyzed experimental recording. Additionally a directory which includes a set of experimental recordings can be specified and the recorded responses can be classified over all experiments according to their response characteristics in the post-stimulus time histogram (PSTH). The Classify directory...-command provides this functionality.
Via the Import trigger- and Export trigger-command it's possible to import an external file which includes "trigger" information about the applied stimulation, respectively to save this "trigger" information of the currently opened experiment to a file. neurALC possesses a program-internal editor for the trigger information - this editor is restricted in the size of the trigger information it can handle and does not offer highly sophisticated manipulation functions. Saving the trigger information allows to extract information from this data by using scripting or programming languages, or external text editor.
Finally the File-menu provides printing functionality - any graph calculated and displayed by neurALC can be printed via File>Print-command.

The Analysis-menu
Selecting any command from this menu applies the chosen analysis to the data set visible in the selected tab: if the Population-tab is active, the analysis is carried out on population level; if the Electrode-tab is active, the calculation is carried out on and visualized for the selected electrode or neuronal unit.

The Contraptions-menu
This menu provides access to a variety of functions with different purpose: use the Contraptions>Save configuration-command to save the actual
parameter defined in the Options-tab to the configuration file neuralc.conf. This file is located inside the folder in which the neurALC was installed and read at program startup.
The Contraptions>Select 3D color map-command allows to load and use a user-defined color map for the visualizations in the 3D-tab.
The Contraptions>Connect to database-command allows to connect to a MySQL-server to transfer and store experimental data files and results. Selecting the command opens a window in which the required information for the connection can be determined. Use the text entry fields to define the name of the existing database, the host name on which the MySQL-server is running, the user name and password, and the port on which the database server allows connections. If neurALC successfully connects to a MySQL database, the Contraptions>Open DB-GUI-command can be used to open the provided graphical database user interface.

The Help-menu
The help menu in the menu bar can be used to open neurALC's online help (which presumably works, because you can read this...).

Technical Prerequisites for the MySQL-functionality
To use neurALC's database functionality, an installation of MySQL version 3 or higher is needed. Please visit http://www.mysql.com and download the package of your choice. neurALC 1.0.0 was successfully tested with MySQL 3, 4 and 5. Additionally the Qt3 libraries on your system must offer MySQL-driver support (the supplied binary installers of neurALC for Apple's MacOSX and Microsoft Windows include the Qt3 libs compiled with the required support. Under Linux an update via the package manager of your distribution, or even a recompilation of the Qt3 C++ framework might be needed).
Install MySQL on your computer system - from our experience, depending on the operating system and the package of MySQL you choose, this might be the most problematic part. Before you try to use the database functionality provided by neurALC or dbALC, make sure that you check the correct function of the MySQL installation on your system. Refer for the MySQL information which comes with the package you downloaded, or the excellent online documentation.

If MySQL is successfully installed and running, add a user "neuralc" with the password "neuralc" to the database (refer to the MySQL documentation for information about adding a user and password). This is the database account which is used as default from within neurALC. In the next step a database with the required design and table type "InnoDB" must be created. The easiest option is to copy the files, provided with the neurALC distribution inside the folder neuralcDB, into MySQL's default folder for databases. The next time you startup MySQL these files are found and can be accessed.
Alternatively you can open the file DBcreation.txt in the editor or text processor of your choice, and use the documented command sequence from within MySQL to create the correct tables and keys - SQL command log for creating the neurALC database (content of the file DBcreation.txt):

CREATE DATABASE neuralcDB;
USE neuralcDB;
GRANT SELECT,INSERT,UPDATE,DELETE
ON neuralcDB.*
TO 'neuralc'@'localhost'
IDENTIFIED BY 'neuralc';
FLUSH PRIVILEGES;
CREATE TABLE experiment (file_name VARCHAR(256),
nev_file LONGBLOB,
comment VARCHAR(256),
creation_date DATE,
photo LONGBLOB,
stimulus_program LONGBLOB,
PRIMARY KEY(file_name(256)));
CREATE TABLE calculus (data_id ENUM(
'None',
'PopulRaster',
'PopulCount',
'PopulRate',
'PopulProb',
'PSTHRaster',
'PSTHCount',
'PSTHRate',
'PSTHProb',
'ISICount',
'ISIBinCount',
'ISIBinProb',
'IFRPopulation',
'IFRPsth',
'Autocorr',
'Crosscorr',
'Spectrum',
'Delay',
'Mutual',
'Recur',
'PSTH3D',
'SpecPopul3D',
'SpecPSTH3D'),
elect_id SMALLINT(3),
unit SMALLINT(3),
classified TINYINT(1) UNSIGNED,
boxes SMALLINT(4) UNSIGNED,
vecinity SMALLINT(4) UNSIGNED,
bin_step SMALLINT(4) UNSIGNED,
delay SMALLINT(4) UNSIGNED,
window FLOAT UNSIGNED,
overlap SMALLINT(4) UNSIGNED,
dimension SMALLINT(4) UNSIGNED,
minor_isi SMALLINT(5) UNSIGNED,
major_isi SMALLINT(5) UNSIGNED,
bin_data LONGBLOB NOT NULL,
unused SMALLINT(5),
experiment VARCHAR(256),
FOREIGN KEY (experiment(256)) REFERENCES experiment ON DELETE CASCADE,
PRIMARY KEY (experiment(256),data_id, elect_id, unit,classified, boxes,vecinity, bin_step,delay, window,
overlap,dimension,minor_isi,major_isi, unused));

Output
neurALC version 1.0.0 supports at the moment the following output formats:
⋅ All open neuronal data files can be saved in NEV2.x format, which allows to save TRC
classification and modified comments to these files.
⋅ Analysis results calculated for the selected electrode or neuronal "unit" data, can be exported and saved to an ASCII-file. Files written in ASCII-format by neurALC have the following, general structure: a header of several lines, followed by columns which hold the analysis results.
Each header line begins with a #. This header holds information about the experimental data file used for the analysis results and the related calculation parameter. The last line of the header holds the "variables" or labels or the following, tabulator-separated result columns.

"I have found a bug. What should I do?" - You can report all bugs (or possible fixes) through http://neuralc.sourceforge.net. Please include to the description the name of the operating system you are using, as well as the Qt-, QWT-, QWT3D-, and FFTW-versions.

"I have successfully compiled neurALC and build an installer on the Sony's PSP, Qtopia, whatever else system and/or platform for which so far no binary installation is available. Do you like to include it in the neurALC distributions tree?"-
YES! Contact us by email or through http://neuralc.sourceforge.net

"I have extended the import/output and/or analysis capabilities of neurALC. Do you like to include the changes to the neurALC source tree?"- YES! Contact us by email or through http://neuralc.sourceforge.net.

"Well, Trolltech just now released the marvelous, wowed, effulgent, *please insert your descriptive expression here* Qt4 - including even a free desktop edition for Microsoft Windows. How can you dare to offer a free program based on the ancient, hoary, paleolithic, *please insert your descriptive expression here* Qt3?"- We were and are aware of the release of Qt4 (and the resulting relief this has for example on the development of Qt-based programs under Microsoft Windows). neurALC is partly based on extensions to the Qt3 framework, namely the QTW and QTW3D libraries. When we started the development neither of these libraries was reported to work fully without problems with Qt4. Well, and we had an educational license of Qt3, so... but, as mentioned previously, this is GPL'ed sources - go ahead and... (please see following entry in this FAQ)

"I had some time during today's lunch break and ported the source code of neurALC to Trolltech's Qt4. Do you like to include the changes to the neurALC source tree?"- HOW GREAT! THANKS!! And: YES! Please contact us by email or through http://neuralc.sourceforge.net

"How to reference/quote/cite neurALC?" - If you publish results in an article or neurALC as data processor for any other kind of publication, please use a phrase similar to: "Temporal response classes were obtained from the analyzed multi-electrode recordings using the neurALC program" in the methods section, and include the following to your list of references: neurALC - a cross-platform, open source program for the analysis of extra-cellular neuronal multi-electrode recordings distributed under GPL (http://neuralc.sourceforge.net).

G. Celeux and G. Govaert, A Classification EM algorithm for clustering and two stochastic versions, Computational Statistics and Data Analysis, 14(3):315-332 (1992)

J.P. Eckmann, S. Oliffson Kamphorst and D. Ruelle, Recurrence plots of dynamical systems, Europhys. Lett. 4, 973 (1987)

FFTW3 - library system for Fourier and related calculations.

A.M. Fraser and H.L. Swinney, Independent coordinates for strange attractors
from mutual information, Phys. Rev. A 33, 1134 (1986)

KlustaKwik - a program for unsupervised classification of multi-dimensional con-
tinuous data (see KD Harris et al, Journal of Neurophysiology 84:401-414, 2000)

MySQL - an open source database.

NEV2lkit - a preprocessor for intra- and extra-cellular neuronal recordings distributed under GPL

NEV 2.0-format specifications - as of this writing the Neural Event Format specifi-
cations (version 2.0) are publicly available.

Qt - the cross-platform C++ framework from Trolltech.

QWT - library for the Qt framework which provides Qt widgets for technical appli-
cations.

QWT3D - library for the Qt framework which provides Qt widgets for three-dimensional plotting.

TISEAN - a software project for the analysis of time series with methods based
on the theory of nonlinear deterministic dynamical systems.

GNU Public License 2.0 (GPL) - the full text of the GPL is provided with neurALC or can be read online.

GNU Lesser General Public License Version 2.1 (LGPL)
The full text of the GNU LGPL is provided with neurALC or can be read online.

QWT License 1.0 - the Qwt library and included programs are provided under the terms of the GNU
LESSER GENERAL PUBLIC LICENSE (LGPL) with the following exceptions:
1. Widgets that are subclassed from Qwt widgets do not constitute a derivative work.
2. Static linking of applications and widgets to the Qwt library does not constitute a derivative work and does not require the author to provide source code for the application or widget, use the shared Qwt libraries, or link their applications or widgets against a user-supplied version of Qwt. If you link the application or widget to a modified version of Qwt, then the changes to Qwt must be provided under the terms of the LGPL in sections 1, 2, and 4.
3. You do not have to provide a copy of the Qwt license with programs that are linked to the Qwt library, nor do you have to identify the Qwt license in your program or documentation as required by section 6 of the LGPL. However, programs must still identify their use of Qwt: neurALC is based in part on the work of the Qwt project.

Creative Commons License - the neurALC manuals are distributed under a creative commons license (CCL2). The full text is provided with neurALC or can be read online.

last changes 20.08.2006