Usage
=====

Please first read the compilation and installation instruction that can be found 
in the INSTALL file.

To run Neurofitter first create a settings XML file (e.g. settings.xml), 
containing all the settings you need to give to Neurofitter (information about
these parameters can be found in the file doc/XMLSettings.doc). 
Next run Neurofitter with the command "Neurofitter settings.xml" in the 
directory containing the executable.

More information
================

At the moment we are still writing documentation files for Neurofitter. If you want extended 
information please email us at werner@tnb.ua.ac.be. We will be very happy to help you.

References
==========

This work is based on the paper:

Achard P, De Schutter E. (2006) Complex parameter landscape for a complex neuron model. PLoS Comput Biol 2:e94


General Algorithm
=================

The user adapts the model so that it can interact with Neurofitter
The user adapts the experimental data to the appropriate format
The user generates a settings.xml file
The user executes "Neurofitter settings.xml"

Neurofitter starts the optimization algorithm

Optimization algorithm gives a first set of model parameters that have to be evaluated

For every "run" parameter (e.g. injection strength)
	Neurofitter will write a file in the model directory containing the model parameters
	Neurofitter writes also the "run" parameter (e.g. injection strength) in the file
	Neurofitter writes in the file the location of where it expects the simulator to write the output data 
	Neurofitter will run the simulator

	The external simulator reads the file written by Neurofitter
	The external simulator reads the model parameters
	The external simulator reads the run parameter
	The external simulator runs the model
	The external simulator writes out the recorded data

	Neurofitter reads the recorded data 
	Neurofitter cuts out the relevant time periods in the data and generates a V dVdt matrix
	Neurofitter calculates the error function for this run
End For

Neurofitter calculates the weighted sum of all the different runs and periods
Neurofitter writes out the error value of the parameters in the Neurofitter output file
Neurofitter gives back the error value of the model parameter set to the optimization algorithm

The optimization algorithm searches for a new parameter set to evaluate 
^
|......

Repeated until the optimization algorithm reaches a termination criterium


Simulator interface
===================

Neurofitter acts as an interface between model simulation software and optimization algorithms. To let Neurofitter
fit your model, you will probably have to adapt your model simulation code. The software is not really dependent
on the kind of simulator you use. So you can use Neuron, Genesis, ....

During the optimization Neurofitter will have to run the model a lot of times with different parameters, this means 
that your model has to get these parameters.
At every evaluation Neurofitter will write a file at the location you specify in the settings.xml file with the 
tag <ParameterFile>.
This file will contain three lines containing the following information:
- model output filename
- "run" parameters
- "model" parameters

The model output filename contains the location where the model should write it's output. 
The "run" parameters are 
The "model" parameters will contain the parameter value that are being fitted like e.g. the channel conductance.
So your model has to read these parameters and 

The best way to get an example of the file described above, is by creating an settings.xml file for Neurofitter
and to run it using this settings file. This will generate the example file in the location you specified in the
settings.xml file.



Settings.xml file
=================
All the settings of Neurofitter can be set in an xml file. You give the name of this file as argument to the binary
of Neurofitter.

More information about the exact format can be found in the "doc" directory


Data Format
============

Experimental and Model data should consist of a set of ASCII files. One ASCII file for every run (e.g. for every 
a ASCII file consisting of 1 column with the timestamps, and then 1 column containing the data (e.g. voltage) 
for every recording site in your model. 

The data that is generated by your model should match exactly the format of your experimental data. At this point
we don't have any support yet for variable time step model data. If you want to use this kind of model output, you
should write a script that interpolates the data, so that the data files have fixed time step.

Units
=====

Neurofitter is not aware of any units. This means that all the values that you give to it, are in the units that
you specify. You should be consistent when giving data values. If for example you give experimental data with time
stamps in millisecond you should also give the sampling rate in 1/milliseconds. Or if your voltage data is in
mV you also have to give the minimalV and maximalV for the V/dVdt matrix in mV.


Further Documentation
=====================

Very specific source code documentation can probably be found in the "doc" directory. 
This  documentation is automatically generated by Doxygen, for information on recreating
this information yourself, it is absent, please read the INSTALL file.


License
=======

The license is GPL. More information can be found in the LICENSE and AUTHORS file.


FAQ
===

Q: How do I compile Neurofitter ?
A: Compilation instructions can be found in the INSTALL file

Q: I get an error message ...
A: Maybe your problem will be solved after you read the Troubleshooting section

Q: I have found an extremely good optimization algorithm, can it be used with 
Neurofitter ?
A: Great ! Neurofitter has been developed so that it can be extended as easily as 
possible. The only thing you need to do is to create your own derived class of
FitterInterface which implements the algorithm. For further information please
contact us at neurofitter.sourceforge.net or www.tnb.ua.ac.be 

Q: Which kind of simulator software can be used with Neurofitter
A: Neurofitter contains premade interfaces to the Neuron and Genesis neuron simulator
software, called NeuronModelInterface and GenesisModelInterface. You can also use other
simulation software, as long as it can be started by using a shell command and if it
can read the model parameters from a file. The ExecutableModelInterface is made for this
kind of simulator software.

Q: I use variable timestep methods in my model, can I use it ?
A: Neurofitter, at this points, doesn't support variable timestep method's data. If you
want to use your model you will have to interpolate the output data.

Q: Can I use MPI with Neurofitter ?
A: Yes, you can ! Please refer to the doc/MPI.doc file

Troubleshooting
===============

******* Problem:
You get an error message like: "Error in Neurofitter: Not enough arguments"

Analysis:
You always have to give a parameter file name as argument to the Neurofitter executable.
Did you do this ?


******* Problem:
You get some "parser error" message

Analysis:
This is probably caused by the XML parser which reads the parameter XML file. Are you
sure the syntax of your parameter is correct ? If it is, maybe you have found a bug
in Neurofitter or Libxml.


******* Problem:
While running Neurofitter you see that the error values you get for the model are not
correct, uninitialized or just all zero.

Analysis:
Maybe there is something wrong with the interface between Neurofitter and the model 
simulation software. Maybe you could check if the output of the model is generated 
correctly or if no errors occur while running the model. You can specify in the 
parameters of Neurofitter that files should be generated with the stderr and stdout
of the command that runs the model. Maybe these contain some information ?
Also try to put the verboselevel at maximum so that you see all the information about
the matrices generated by Neurofitter


******** Problem:
It seems that Neurofitter "eats" all my memory

Analysis:
It could be that this caused by some parameters you set for Neurofitter. Don't use
e.g. too large dimensions for the V dVdt matrices. Another possibility is a memory 
leak in Neurofitter, maybe you could contact us at neurofitter.sourceforge.net or 
www.tnb.ua.ac.be

******** Problem:
Neurofitter generates a "Malloc allocation" error

Analysis:
Apparently you've run out of memory. There could be several reasons for this kind of
problem. One could be that your disk is almost full.
Another could be that your sampling rate in the settings.xml is not set to the correct
value. 
It could also be that your model and experimental have a very high sampling rate, which creates
problems for Neurofitter. This problem can only be solved by downsampling your data, or by using
smaller time periods of data. 
If you really are in a situation where you need to use very large data sets to fit your model
and Neurofitter gives this kind of error, please contact us, maybe we can come up with a 
solution to more efficiently save data in memory.

******** Problem:
While running Neurofitter using MPI you get an error like:
p4_error: semget failed for setnum: 0

Analysis:
The maximum number of allowed semaphores on the master node has been created. If this is caused by
you can solve this by running "cleanipcs", a script which should have been provided together with
MPICH

******** Problem:
Help ! I get an error message and I don't understand what it means :-(

Analysis:
Maybe you have found a bug in Neurofitter. You can always contact us at 
neurofitter.sourceforge.net or www.tnb.ua.ac.be