====== Auryn Binary Extract (aube) ======

This command line tool extracts spike information from [[spk|binary spike raster files]] and converts them in the more digestible [[ras]] format. Binary files provide a significant simulation speed advantage over the old [[ras]] file format, take less disk space and allow random access to temporal chunks of spike information. ''aube'' is capable of efficiently merging the multiple [[spk]] files generated by parallel simulations and exports only select temporal ranges from it. It can be efficiently incorporated into Linux command-line and pipe based work flow and works flawlessly with [[gnuplot]]. The tool included with Auryn releases (ver. >0.6.1) and can be found in the ''tools'' directory. For users doing their analysis in Python, the [[python tools]] offer an alternative to decoding spk files. These tools allow to directly import binary spiking data into Python without the detour via aube.
===== Compiling/Installing aube =====
''aube'' is [[manual:compileauryn|compiled]] automatically with the rest of Auryn and located in the tools directory. It can be installed to your systems default install location (e.g. ''/usr/local/bin'') with the help of ''make install''. Otherwise you will have to ensure yourself that ''aube'' is in the PATH for the following examples to work.



===== Usage examples =====

To see how this works let's consider an example. Let's first generate some spiking output using the Vogels Abbott benchmark network with conductance-based synapses (see [[examples:start]]).
To that end, we use example program ''examples/sim_coba_binmon.cpp'' which will be compiled with Auryn. You find it in your build directory under examples. In this directory, to run the code, just call:
<code>
./sim_coba_binmon --dir /tmp
</code>
This code will run the using a single process.

==== Extracting spikes from a single spk file. ====

The above example has written the file ''/tmp/coba.0.e.spk'' to your disk. Now you want to extract all spikes from this file and write them to stdout. All you need to do is to call aube:
<code>
aube --input /tmp/coba.0.e.spk
</code>
or, alternatively, in short
<code>
aube -i /tmp/coba.0.e.spk
</code>


If you want to write the output to a file instead you can call:
<code>
aube --input /tmp/coba.0.e.spk > output.ras
</code>


==== Merging spk files from parallel simulations ====

In many cases you will run parallel simulations with Auryn.
For the above example that is equivalent to the call:
<code>
mpirun -n 2 sim_coba_binmon --dir /tmp
</code>
This will run the Vogels Abbott benchmark using two parallel processes. Because each process writes only the spikes of the neurons it simulates (neurons are distributed across processes), you end up with multiple files ''/tmp/coba.*.e.spk''. After the simulation, however, you would like to merge these spikes to analyze all spikes. 

Just call aube on all the input files:
<code>
aube --input /tmp/coba.*.e.spk
</code>

==== Extracting only a limited temporal range from the files ====

Most of the time you don't want all the spikes, but only a certain interval. Say, you would like to extract spikes from 7s to 10s to the file ''output.ras''. Then the aube call for you is:
<code>
aube --inputs /tmp/coba.*.e.spk --from 7 --to 10 --output output.ras
</code>

Alternatively you can use a shorter notation which achieves the same:
<code>
aube -i /tmp/coba.*.e.spk -f 7 -t 10 > output.ras
</code>


==== Using aube inside "pipes" (for instance in gnuplot) ====

You can use ''aube'' in pipes which for instance allows you calling it from without [[gnuplot]]. To plot the last 1s of spikes from a simulation from within gnuplot run:
<code>
plot '< aube --inputs /tmp/coba.*.e.spk --last 1' with dots
</code>


==== Additional command line options ====

For help try
<code>
aube --help
</code>