Documentation on ihna.kozhukhov.imageanalysis
=============================================

1. OVERVIEW

In 2003 Dr. Valery Kalatsky suggested a novel paradigm for brain investigation by the method of
intrinsic-signal optical imaging technique. The essence of this technique is the following.
The primary visual cortex is stimulated by a drifting grating which orientation changes continuously
and periodically with a period equal to 1 minute. This means that the neural activity from a
partucular column will also make oscillations with this particular period. So does the intrinsic
signal. Hence, if we record the intrinsic signal and extract 1min-oscillations from it we will deal
with only that part of the signal that includes the response to the stimulus. The other more
powerful components of the intrinsic signal, especially those connected with breath rate and heart rate
will be excluded from an analysis.

For more detailed description of this method see the following paper:
Kalatsky V.A., Stryker P.S. New Paradigm for Optical Imaging: Temporally Encoded Maps of Intrinsic Signal.
Neuron. 2003. V. 38. N. 4. P. 529-545
This is your responsibility to cite this paper when you have done the research and used this package
for this purpose.

Dr. Valery Kalatsky supplied a program (called 'iman') that processes the data generated under continuous
stimulation paradigm. This program was extremely useful for making a scientific progress over 17 years.
However, at this moment important disadvantages in this program were found and this is clear that the
program shall be reconstructed.

In 2020 Dr. Sergei A. Kozhukhov reconstructed the IMAN and represented it in a way of C++
written Python module. The reconstructed version of the program have the following advantages comparing with
the original IMAN:

    (a) The program has been built under Linux v. 5.3 operating system while the original version of the
        program was built under older versions of Linux and failed to run in newer Linux'es.

    (b) A convenient feature of the program is possibility of its usage under Microsoft Windows. However,
        this is not true for the GUI interface.

    (c) When we treat about the IMAN program this was possible to make its builds under newer versions of
        any POSIX-compliant operating system (including Linux and Mac OS X) but such builds are not able
        to read the data recorded under the original data acquisition program developed by V. Kalatsky.
        This is not truth for the ihna.kozhukhov.imageanalysis package. This package may be build under any
        type of POSIX-compliant and Windows operating system and such build will read the original
        experiment records.

    (d) A convenient GUI interface is provided by the program. However, possibility to run the processing
        modules from the Python or iPython command line also exist. If you want to use this package from the
        Jupyter notebook, just do it.

    (e) While IMAN allowed to provide trace analysis for up to four pixels, the ihna.kozhukhov.imageanalysis
        provides trace analysis for a certain set of pixels define by the map ROI.

    (f) ihna.kozhukhov.imageanalysis provides an interactive tool to define a rectangular ROI and create
        complex ROI containing several simple rectangular ROIs. The program averages all traces recorded from
        all pixels belonging to the ROI.

    (g) The original IMAN saves traces as temporal dependencies of the signal on the frame number. It doesn't
        use frame arrival times. The ihna.kozhukhov.imageanalysis creates a temporal axis based on frame
        arrival times and such axis will be saved together with intinsic signal values at certain times.

However, the updated program has lost some of features that were treated to be deprecated. Especially,

    (a) The program doesn't work with episodic stimulation since such stimulation protocol has not been used
        for over 10 years.

    (b) The program doesn't open the data in so called 'old format', that is, the data recorded before 2003.

    (c) Green map analysis is also inavailable from the new version


1.2 WAYS TO USE THIS APPLICATION

USE IT AS AN ORDINARY USER if you want to get a convenient graphical user interface that allows you to interactively
manipulate with your experimental data. The GUI contains only limited functionality that will allow to to complete
current project successfully. However application of this package to any other tools will require either new
experimental data or USING IT AS AN EXPERT.

USE IT AS AN EXPERT if you have a good knowledge of Python, NUMPY, Matplotlib, iPython, the Jupyter Notebook,
Scipy and Pandas. We also advice you to additionally install Anaconda - a Matlab-like interface that allows you to
work on Python-written code. After you studied the usage of this program as an expert, you can find new ways of
using this program, establish its interactions with another packages developed in another laboratories (BluePyOpt is
among them) and thus achieve more advances in science. The expert usage of this package will free you from studying
Matlab, R and/or SPSS, Just learn the packages mentioned above and of course this Documentation and Use it as an expert.

USE IT AS A GOD if are have strong background in Applied Mathematics and Computer Science and you know C++ very well.
When using as a god you don't need Python to be pre-installed. Anything what you need is to find C++ classes in the
cpp folder. Include all .cpp files within this folder to your project and use cpp as an include directory. Create your
own C++ application based on the classes provided. All necessary information can be found in docstrings to these
classes (In JetBrain CLion press Ctrl-Q for opening the documentation).


1.3. GENERAL CONCEPTS

A 32-BIT OPERATING SYSTEM
A type of operating system that uses 32 bits (4 bytes) to store memory addresses. This requires less
operating memory than the 64-bit operating system but it doesn't support the operating memory higher than 4 GB.
Both Windows and Linux can be 32-bit
Right-click on 'My Computer' and select 'Properties' to check whether your operating system is 32-bit.

A 64-BIT OPERATING SYSTEM
A type of operating system that uses 64 bits (8 bytes) to store memory adresses. This type supports operating memories
higher than 4 GB but requires more operating memory to be installed.Both Windows and Linux can be 64-bit.
Right-click on 'My Computer' and select 'Properties' to check whether your operating system is 64-bit.

AMPLITUDE MAP
A map that tells you how the population located at a particular point on the map is selective to the presented visual
stimulus

AVERAGED MAP
The result of processing all FRAMES within the record that contains information about how each neural population
recorded is responsible for a certain stimulus. The AMPLITUDE MAP and the PHASE MAP are particular cases of the
AVERAGED MAPS

A BUILD
A version of this package that can be used only for a certain platform. For example, builds for 64-bit Windows
can be launched under 64-bit Windows only and will failed to be run under Linux or 32-bit Windows. Also, you can't run
build for 64-bit Linux on 32-bit Linux and any type of Windows. Mac OS X operating system will run only builds for
Mac OS X.
Use a build suitable for your platform. If you don't have such a build, download the SOURCES and BUILD them to generate
a new build suitable for you.

TO BUILD
To geenerate a new build for a platform you are currently working on from the SOURCES. The building process requires
the COMPILER to be preinstalled.

COMPILER
A special application that builds the package from its sources. If no compiler is installed you can still use one of
existent builds of the program but you can't create your own builds. Since the compiler has been installed successfully,
you are not requires to run this. Just run the setup.py script that in turn will run an appropriate compiler.
If you are working under Windows you need to install and to use Microsoft Visual Studio. However, if you are working
under Linux or Mac OS X you need to install and use g++.

COMPLEX MAP
A 2D matrix containing complex number which modulus will give an amplitude maps and which argument will give the
phase map.

COMPLEX ROI
A ROI that can be consists of several simple or comples ROIs and contains all pixels that are contained by at least one
of these ROIs.

TO COMPRESS
To transform the data into their compressed state.

COMPRESSED STATE
State of the data when they contain all information recorded during the experiment occupying little volume on the
hard drive. You can't process the data stored in the compressed state and you need to DECOMPRESS it first.

TO DECOMPRESS
To transform the data into their decompressed state.

DECOMPRESSED STATE
State of the data when they they are ready for any kind of processing (including frame view, trace analysis and
building averaged amplitude and phase maps). The data in the decompressed state stores too long volume and you
probably need to

ELECTRONIC LAB JOURNAL
A special space where you can make notes about stimulation pecularities, animal state, substances induced etc.

FILE TRAIN
A sequence of files that can store a single record. During the experiment the whole record is splitted into several
parts and each of the part is stored in a separate file. All files within the train are required for the data to be
opened. All of them shall exist in a stand alone folder and their names shall be the same as given at the record.

A FRAME
An image of the cortex made during a particular time. The FILE TRAIN contains temporal sequence of the frames recorded
an consequtive times.

G++
A C++ compiler working on Linux. This is the only compiler you can use to create a build for Linux or Mac OS X.

GUI SHELL
A stand-alone Python application that allows to interactive use of some of the functions available in the program

INSTALLATION
The process of copying program executable and python files from the installation folder to the system folder.

ISOLINE
An low-frequency aperiodic changes in the intrinsic signal that declines the accuracy of your research. These changes
shall be removed from the source intrinsic signal during the map averaging the traces extraction.

MANIFEST
The file that stores the ELECTRONIC LAB JOURNAL and all files associated with a particular record.

MICROSOFT VISUAL STUDIO
A C++ compiler working on MS Windows. This is the only compiler you can use to create a build for Windows.

MODULES
A more complicated interface of this package that provides an access to the functions that are inaccessible from the
GUI tool.

PLATFORM
A combination of the operating system and a Python 3 interpreter run under this particular operating system.

PHASE MAP
A map that tells you a feature that a particular neural population is tuned for depending on its location.

PYTHON
A programming language that is very useful for writing a scientific software.

PYTHON 3
The newest version of the Python programming language. This version has not forward and backward compatibility with
the odler version called Python 2, so, all packages written in Python 2 will not run under Python 3 and vice versa.

PYTHON INTERPRETER
A special program that is required to run the software written in the Python programming language. You can't use
this package without Python interpreter, however, since the interpreter is installed successfully, you are not
required to run this alone. Just click on the GUI application, this will start the Python interpeter and loads
the package into it.

PYTHON 3 INTERPRETER
A special program that is required to the software written in the Python 3 programming language. Especially,
this package is required Python to be installed on your PC.

REGION OF INTEREST (ROI)
A part of the maps which data you will use for the following analysis and calculating statistics. Because the instinsic
signal is spatially noisy, you can't read the signal recorded from a particular point directly but you shall select
an arbitrary piece of the maps and average the data across all pixels belonging to this piece.

SIMPLE ROI
A ROI that has a rectangular form.

SOURCE FILES
A version of this package that can be used to generate a particular build for a platform you are currently working on.
If you have source files, you can't run and use them directly, you need first, to make a particular build and then
to use a build you are currently made.

SYNCHRONIZATION
Establishing the relationship between a frame and a particular stimulus value. The synchronization process includes:
    (1) Reading the signal from the synchronization channel
    (2) Defining the analysis initial and final frame
    (3) Construction of the reference signal scalar-prodict of the frame sequence to the reference signal will get
    AVERAGED MAPS

SYNCHRONIZATION CHANNEL
A channel that accepts a signal from the stimulation computer. Such a signal is extremely useful for the synchronization
process!

A TRACE
A temporal-dependent intrinsic signal recorded from a particular pixel of the cortex

VESSEL MAP
An unprocessed photograph of the visual cortex that you can use to see where are vessels, dura, neural tissue etc.

WORKING FOLDER
The folder containing all the data related to a particular project.


3. INSTALLATION

3.1. INSTALLATION WAYS

This tool has been written both on Python and on C++. This means that it contains a platform-independent code that
shall be loaded into the Python interpreter and executed by means of the Python interpreter and a platform-independent
code that can't be executed directly and shall be transformed into CPU instructions by the process called 'building'.
This means that the first process of using this tool is to build this for your platform.

The building if the process of generation of new build of this tool. Another way to use it is to download some build
for your platform that has already been made. We consider both ways.

3.2. BUILDING THE PACKAGE FROM SOURCES

3.2.1 DOWNLOADING THE SOURCES

The package can be downloaded from the following link:

https://github.com/serik1987/ihna_kozhuhov_image_analysis

Press the button "Clone or download" and then choose the option "Download ZIP". You will download an archive that
contains a single folder. Unpack this folder to any destination folder. This folder is called 'installation folder'.
You can put the installation folder on your desktop or in the Downloads folder. This doesn't matter because you don't
need in this folder and its content after successfull build and installation and you will simply delete this. In any
way this tool shall be placed and will be placed to the same drive as you installed Python.

The next building process will occur in the command line. In Linux, right-click on the installation folder and choose
'Open in Terminal'. In Windows the process is more complicated:

    (1) Open the Windows menu and in the Search string type 'cmd'. You will see an icon corresponding to the CMD
        application
    (2) Right-click on the icon and choose "Run as a system administrator"
    (3) You will see the black window where you shall install the program.
    (4) In this window type 'cd' (withot quotes) and press space. Drag you installation folder to the CMD window and
        press Enter.

3.2.2. CHECKING FOR PYTHON

The following step is to ensure that the Python is installed correctly. Python is an interpreter that is responsible for
interaction between this tool and the operating system. Without Python you can't use this tool. To check the Python
installation version type the following command:

python --version

If you see that the command is not found. One of the following problems happened:

    (a) You did not install Python 3. Please, download and install this! In Linux Ubuntu, you shall simply run the
        following string:

sudo apt install python3

        For Windows a simple graphical interface is provided. Just use Google or Yandex to find Python 3, download and
        run it.

    (b) You have installed Python 3 but the Windows doesn't see this. Read the following instructions on how to fix
        this problem:

https://docs.python.org/3.8/using/windows.html#configuring-python

If this command is executed successfully but has written something like:
Python 2.7.17

This means that your operating system uses the old version of the Python and you need to tell it to use new version.
In Linux you can use it by running the following command:

sudo ln -s /usr/bin/python3 /usr/bin/python
sudo ln -s /usr/bin/pip3 /usr/bin/pip

In Windows you shall check the following instructions on how to fix this problem:

https://docs.python.org/3.8/using/windows.html#configuring-python

If you see the following line:
Python 3.6.9
(two last numbers doesn't matter, the only important thing is they shall be preceeded by the number '3' that tells you
that you are currently using Python 3, not Python 2)

you can continue the building process.

3.2.3. CHECKING FOR THE COMPILER

The compiler is a special program that transforms platform-independent sources that are unable to use into platform
dependent build that may be used under the specific build. The compiler is needed for you during the installation
process. After you installed the program successfully, you can removes your compiler if you don't use it (for instance,
if you don't write program on C/C++). Compiler is needed to build and install this package but it doesn't need to run
it.

In Linux you shall use g++. Install it by the following command:

sudo apt install g++

In Windows you shall download and install Microsoft Visual Studio. This package will not be build on another Windows
compilers (such as Borland C++ Builder).

3.2.4. CREATING THE BUILD OF THE PROGRAM

Run the following command to create the build:

python setup.py build

This program will generate new build for your platform and put it into the 'build' folder.

3.2.5. INSTALLING THE PROGRAM

Type the following instruction to do this:

python setup.py install

In Linux you shall use another command:

sudo python setup.py install

3.2.6. TROUBLE SOLUTION

    (a) The installer says 'please, use the python3'
        In all commands above you shall replace 'python' by 'python3 and 'pip' by 'pip3'. An alternative way in Linux
        is to use the following command to fix:

sudo ln -s /usr/bin/python3 /usr/bin/python
sudo ln -s /usr/bin/pip3 /usr/bin/pip

        In Windows, you shall change the environmental variables or (if you don't know how to do this) remove all
        versions of Python and install the latest one given that this is Python 3.

    (b) The installer says that 'Permission denied' or 'Отказано в доступе':
        You try to perform operation in non-priviledged mode. The solution is to enter to the priviledged mode. If you
        are working under windows, close the CMD, read section 3.2.1 carefully and do it again. Note, that you shall
        run CMD as a System administrator (or: "Запустить от имени системного администратора"), otherwise the
        installation will not work.
        If you are working under Linux, put 'sudo' before the command you are currently trying to run. Don't forget to
        put space to separate your command from the 'sudo' word.

    (c) If the installer writes you that the NUMPY package has not been found or the compiler if failed to find
        numpy/ndarray.h, the problem is the same: you don't install the additional Python package. The following
        command will fix this problem:

pip install numpy

3.3. INSTALLATION THE PACKAGE THAT HAS ALREADY BEEN BUILT BY YOUR COLLEAGUE

If your colleague is successful in building this package and you have the same platform as him (i.e., the same
version of Python and the same operating system) You can download the installation folder from him.
In this case you shall follow the steps 3.2.1-3.2.2, 3.2.4-3.2.5 and skip the step 3.2.3. In the step 3.2.5, when you
write:

python setup.py build

the installation script will check whether the provided build is suitable for your platform. Such check doesn't require
the compiler to be installed on your PC. If this check is OK this command will be completed successful. However
if the existent build is not suitable for your PC, this command will try to create a new build and this process will
of course requires the compiler to be installed.

4. USING GUI

Unfortunately the GUI v. 1.0 doesn't work stable in Windows. Hence, to use GUI you shall switch into Linux or wait for
later versions.

4.1. RUNNING GUI

Create a folder where you will put your experimental data. We will refer to this folder as the 'working folder'.
Next, right-click on the folder and select "Open in Terminal". In the terminal write "iman" and press enter.

If you are not happy with the Terminal, make the following steps before the first run of the GUI.

    (1) Go to the properties of your file browser.
    (2) Find the section "Executable text files" (or Исполняемые текстовые файлы), select the option "Ask what to do"
        or, if this is absent, select the option "Always execute".
    (3) Create your working directory.
    (4) Open the folder containing your distributive (folder build, then, folder scripts), then copy iman into your
        working folder.

In this case, run of the GUI will be easy: just double-click to the iman file and select 'Run' if this is necessary.

4.2. WORKING THE ELECTRONIC LAB JOURNAL

After the program is run successfully, you will see the main window. This window allows you to put all necessary data
to the electronic lab journal as well as to select an appropriate action to do. The window contains three columns.
The first column contains all widgets related to particular animal. The second column contains the data related to
a particular record or 'case'. The last column contains all operations that may be performed with a particular case.
Please, note that not all operations are available in v. 1.0.

Now you shall add animal to the lab journal by pressing the button 'Add animal'. To delete an animal, please, press
the button 'Delete animal'. The animal filter will be available in future versions.

Next, fill the boxes below using records from your offline journal. After all information about particular animal will
be filled, press 'Save animal info' to write this information into your hard disk drive. These operations shall be made
for each cat.

The next stage of your job is to import cases. Importing cases can be organized in two ways. In first way, you make a
local copy of a particular case on your local hard disk and put information about this copy into the electronic lab
journal. This way requires too long time and volume of your local storage  may not be enough to store all data. The
second way is to make a symbolic link to your data and add information about this link to the electronic lab journal.
Symbolic links doesn't require time to create and you don't need to wait for a long time. However, they can't work
without the external storage plugged in. If the storage is not plugged in, such a symbolic link is treated to be broken
and you can't use it until you plug your external storage again.

To import list of the cases you shall press the button 'Import cases' located at the middle panel of the main window.
Next, choose a particular way to import the data and press OK. In the following window you shall select the data
related to a particular animal. The following remarks are related to such a file selection.

    (1) The experimental setup doesn't store all record in a stand-alone file but rather uses a set of separate files
        called "the file train". An example of the train: T_1CK.0A00, T_1CK.0A01, ... You are not required to select
        all files related to a particular train. Just select any of them and the tool will find all other files and
        will import all files related to a particular train.

    (2) Multiple file selecting is available. You don't have to import each record separately. A good way is to enter
        the folder containing all records related to a particular animal, press Ctrl-A to select all records and then
        press OK.

    (3) If your multiple selection contains files that don't relate to any record, its OK. The import routine will
        notify you about them and will not import them.

    (4) You can't import the same record twice.

The next window will show you all file trains found by the tool. Status of the trains is at the right of their name.
Orange status means that the import is still in progress. Red status means that the import is not possible. And green
status implies that the train has already been imported. Press OK to import all found data.

All imported cases are mentioned in the 'Cases' list box. If you specify the case short name, such a name will be shown
in the box. However, if you don't specify this name, the list box will show you the train head file. If you don't see
the other files in the train, it doesn't mean that the tool forgot about them. The tool remembers all files related to
a particular train.

If some case is imported by error, you can delete it by pressing the button 'Delete case'. The 'Case filter' options
will be available in future versions.

Enter the information about each case from your paper lab journal and press 'Save the 'Save case info' button to save
this information. After you do these function, the data processing operations will be available at the right of the
case information.

4.3. READING THE FILE HEADER

To read the general information about the record written in the file header, please, click the button
'Open data manager' at the right of the 'Native data' string. Native data manager will be opened and the information
from the file header is available on the left column. The information is splitted into several pages.

General properties      general features of the record such as total number of frames, the file size etc.
Compression properties  represents features related to the file compression. This section is absent when you deal with
                        the native data.
Experimental setup      All properties of the data acquisition process
Stimulation             General properties of the visual stimulus.
Data                    Write you the total data size.

Next, use the button at the right of the window in order to do necessary operations with native data.

4.4. FRAME VIEW

In order to see a single frame unprocessed, press the 'Frame view' button. You will see a frame viewer. The frame image
is represented at the left of the window and the frame-related information is at the right of the window. If the data
are not compressed (see section 4.5 for more information), you can navigate across frames using the navigation panel:

    '<<'            will move you to the first frame
    '<'             will move you to the previous frame
    'Frame # ...'   will move you to an arbitrary frame which number you shall enter.
    '>'             will move you to the next frame
    '>>'            will move you to the last frame

This is also possible to save the frame image to one of the following formats:

'npy'   the NUMPY format that is suitable for frame insertion into the Jupyter Notebook
'mat'   if you wan't to use MATLAB to process the data
'png'   if you want to insert the frame into Power Point.

4.5. COMPRESSION AND DECOMPRESSION

The data is presented in two states: compressed and decompressed. The compressed data require little volume to store
but they are useless for the following processing. In order to make the data available for the further usage you need
to decompress them.

Again, if you have already processed the data and you storage is not enough to write more data, the can compress the
useless data.

There is not data loss during the compression. This means that is you compress the data and then decompress them
two resultant files will be absolutely identical.

You can check whether the data are compressed or decompressed. If the data are compressed you will see an orange word
'Compressed' at the right of the 'Native data' caption. If the data are decompressed you will see the 'Decompressed'
word. To compress or decompress the data press 'Open manager' button immediately below this record. Next, press
'Compress' or 'Decompress' depending on whet you are going to do. You can select the following option:

Don't decompress is native data exist   If both native and compressed data are presented in your working folder the
Don't compress if native data exist     tool will not waste your to to compress the data that have already been
                                        compressed or to decompress the data that have already been decompressed

Delete compressed files after decompression     After your files have been compressed or decompressed, the input file
Delete decompressed files after compression     will be deleted. If you created symbolic links during the compression
                                                or decompression, the symbolic link will be deleted, not file at the
                                                storage.

Next, press OK and wait until the process will be completed.

The compression / decompression result will always store on your local storage. Bear it in mind. If the

Both compressed and decompressed files can be deleted manually without any affect of the program work.

4.6. MANAGING ROI

The original data contains the data on the light reflected from set of objects: neural tissue, vessels, dura, bones etc.
If you want to specify what object you are interested in you shall specify a region on the map which data shall be
averaged. Such region is called 'the Region of Interest' or ROI. To specify a certain ROI press the button
'Open Manager' on the ROI section.

4.6.1. IMPORT ROI

If you have already defined ROI and save it in XML files created using ihna.kozhukhov.imaging package you can import
such files by pressing the button 'Import ROI'. Select the file where your ROI has been saved, press OK, enter the ROI's
name and press OK again.

4.6.2. DELETE ROI

Just press the button 'Delete ROI'.

4.6.3. DEFINE SIMPLE ROI

Press the button 'Define simple ROI'. Then, enter the ROI name. Now you shall draw the ROI borders. Select what border
you want to define using radio button on the right of the window. Next, click on that pixel of the map where you can
add your new ROI.  After this task will be completed for all ROIs press OK to save your new ROI.

4.6.3. DEFINE COMPLEX ROI

Simple ROI contains all pixels that lies within the rectangle which left, right, top and bottom border shall be given
by you. Complex ROI consists of several simple ROIs and contains all pixels that belong to at least one simple ROI.
To define complex ROI you shall click the button 'Define complex ROI', select all simple ROIs that belong to the complex
ROI and press OK.

4.6.4. MANUAL ROI DEFINITION

This option is suitable for you when you have exact coordinates of left, right, top and bottom borders of the ROI.
Press the button 'Define ROI manually', fill the form that you will see and press OK.

4.6.5. EXPORTING ROI TO TXT

All ROIs were saved to the manifest (xml) files, all their coordinates are accessible through the program API
(see section 5). However, you can additionally save them to the TXT format (this is not necessary for your research).
To export ROI as txt press the button 'Export to TXT' and enter the ROI coordinates.

4.6.6. SHOW ROI ON MAP

If you are not sure whether you (or your colleague) selected ROI in right way, you can press the button
'Show ROI on map' to seel how the part of the ROI belonging to the map looks like.

4.7. TRACE ANALYSIS

Trace analysis allows to extract temporal dependency of a signal belonging to some ROI, average this across all pixels
within the ROI and plot its spectrum. In order to do trace analysis press the button 'Open manager' in the section
'Native data' and press the button 'Trace analysis'.

4.7.1. ADJUSTMENT OF SYNCHRONIZATION PARAMETERS

Synchronization is a process of connecting records from the CCD camera to the stimulus signal. Synchronization also
defines what frames will be included into the analysis based on stimulus information. You can select one of four
synchronization types:

'No Synchronization'    is based on assumption that no stimulus is presented when recording the activity from the
                        visual cortex. The analysis range contains all frames by default. However, if you want to
                        start the analysis from a particular frame you can select the checkbox 'Start analysis from
                        frame #' and enter an appropriate frame number. If you want to finish the analysis at a
                        particular frame you can select the checkbox 'Finish analysis at frame #' and enter the frame
                        you want to use for the analysis finish.

'Quasi-stimulus synchronization' is based on assumption that the stimulus contains exactly integer number of frame
                                 and the stimulation cycle starts from the very first frame. You can select how many
                                 frames is contained in a single stimulation cycle. The analysis range always contain
                                 the whole number of stimulus cycles. The default range is selected in such a way as to
                                 maximize the analysis range. However, you can specify number of cycle from which the
                                 analysis starts. Just check the box 'Start analysis from cycle #' and type the cycle
                                 number manually. Number of the last cycle of the analysis is defined similarly. Cycle
                                 numbers start from 1.

'Quasi-time synchronization'    is based on assumption that the stimulus period in milliseconds is given exactly and
                                the stimulation cycle starts from the very first frame. You can select how many
                                frames is contained in a single stimulation cycle. The analysis range always contain
                                the whole number of stimulus cycles. The default range is selected in such a way as to
                                maximize the analysis range. However, you can specify number of cycle from which the
                                analysis starts. Just check the box 'Start analysis from cycle #' and type the cycle
                                number manually. Number of the last cycle of the analysis is defined similarly. Cycle
                                numbers start from 1.

'External synchronization'      this is the most precise type of the stimulus synchronization which is suitable when
                                the experimental setup has recorded the signal not only from the CCD camera but also
                                from the stimulation computer. If this is true for your case, always use this type of
                                synchronization. You shall know what synchronization channel is used for the
                                stimulus input. If you don't know, this is not problem: try both ones. If you selected
                                the channel number incorrecty you will gen 'No signal' error. You can select how many
                                frames is contained in a single stimulation cycle. The analysis range always contain
                                the whole number of stimulus cycles. The default range is selected in such a way as to
                                maximize the analysis range. However, you can specify number of cycle from which the
                                analysis starts. Just check the box 'Start analysis from cycle #' and type the cycle
                                number manually. Number of the last cycle of the analysis is defined similarly. Cycle
                                numbers start from 1.

In the Synchronization box you also have to select harmonic - it shows how many parameter changing cycles is in the
single stimulus cycle. When you are interested in the orientation selectivity and the stimulus is drifting sine grating
the harmonic equals to 2.0 (i.e., two cycles or orientation shift correspond ti a single cycle of the stimulus). But
for direction-selective and retinotopy research the harmonic is always 1.0.

4.7.2. ISOLINE REMOVE

Isolines are slow non-periodic changes in the intrinsic signal that doesn't relate to the stimulation. Isolines are
constituent that always worse the results so it need to be remove. There are three ways to remove the isoline:

    (1) Don't do it. Select 'No isoline' for such a purpose.

    (2) Linear fit. This way is based on assumption that isoline is straight line.

    (3) Time average. The isoline if an averaged activity across 2n cycles where n is Average radius.

If you don't know which way to select try all of them and compare the results quality.

4.7.3. ANOTHER PARAMETER

In the 'Trace reading section' you can select what ROI shall be used for the analysis. Select any of ROIs that you
defined in Section 4.6. Additionally, if you are not sure that you will the parameter 'Select a synchronization channel'
correctly, put the checkbox at the left of the synchronization channel number to include the signal from this chanel
into the analysis.

When you adjusted synchronization, isolines and trace reading properties, press OK to start the process of trace
reading. Wait for a bit until the process is finished.

4.7.4. PRELIMINARY TRACE VIEW

In the preliminary trace view, you will check the correctness of the parameters selected and select new parameters of
the further processing. You will see the following graphs.

(1) Time arrival differences will notify you about errors in defining the temporal characteristics of the signal

(2) The reference signal will show you how your trace activity is related to the visual stimulus.

(3) If you included synchronization channels into analysis you can see signals from these channels as well. The
    synchronization signal reflects how the stimulus  parameter depends on time.

(4) You can see stimulus traces before the isoline remove, traces connected to isolines and stimulus traces after
    the isoline remove.

(5) Spectrums for all but one mentioned characteristics are at the right of the window.

Graphs at the bottom show you final results and different graphs reflect different averaged strategy. The very bottom
of the window contain options that you can use to select an appropriate average strategy. Select the strategy and press
OK.

4.7.5. FINAL TRACE VIEW

On the last window you can see averaged traces and their spectrums and save the traces into some of the formats
appropriate for you or to all of them. 'Add to manifest' option will add your traces to the electronic lab journal.
All traces will be saved to a folder containing information about the animal. The following formats are available:

'NPZ'   suitable for using this tool for working with processed traces as well as for the Jupyter Notebook
'MAT'   Suitable for MATLAB
'PNG'   Suitable for appending the traces to the Power Point

Additionally you shall give the prefix and postfix - some name the will be applied to the traces full name in order to
distinguish these traces from another ones.

5. LOOKING FOR MORE INFORMATION

To look for more information please, look for GIT wiki.