pyNAVIS¶

pyNAVIS is an open-source cross-platform Python module for analyzing and processing spiking information obtained from neuromorphic auditory sensors. It is primarily focused to be used with a NAS, but can work with any other cochlea sensor.

For more information, head over to the Github repository.

Installing¶

pyNAVIS is distributed on PyPI and can be installed with pip:

pip install pyNAVIS

For more information, head over to the Installing section.

Getting started¶

Now that you have everything set up, you can create a new Python file and import the package:

from pyNAVIS import *

With this, you can now use all the functionalities that pyNAVIS provides. A more detailed guide with examples can be read here.

Software package¶

The Python code has been documented using docstrings, which is very convenient for users that want to either use the software or develop new features and functionalities.

To see all the information for the different Python modules, classes, methods and all the possible configuration options, read the pyNAVIS package section.

Contributing¶

If you would like to help improve pyNAVIS, please read our contributing guide.

License¶

This project is licensed under the GPL License - see the LICENSE.md file for details.

For further information and help, please contact me at jpdominguez@atc.us.es.

Cite this work¶

APA Dominguez-Morales, J. P., Gutierrez-Galan, D., Rios-Navarro, A., Duran-Lopez, L., Dominguez-Morales, M., & Jimenez-Fernandez, A. (2021). pyNAVIS: An open-source cross-platform software for spike-based neuromorphic audio information processing. Neurocomputing, 449, 172-175.

ISO 690 DOMINGUEZ-MORALES, Juan P., et al. pyNAVIS: An open-source cross-platform software for spike-based neuromorphic audio information processing. Neurocomputing, 2021, vol. 449, p. 172-175.

MLA Dominguez-Morales, Juan P., et al. “pyNAVIS: An open-source cross-platform software for spike-based neuromorphic audio information processing.” Neurocomputing 449 (2021): 172-175.

BibTeX @article{dominguez2021pynavis, title={pyNAVIS: An open-source cross-platform software for spike-based neuromorphic audio information processing}, author={Dominguez-Morales, Juan P and Gutierrez-Galan, D and Rios-Navarro, A and Duran-Lopez, L and Dominguez-Morales, M and Jimenez-Fernandez, A}, journal={Neurocomputing}, volume={449}, pages={172–175}, year={2021}, publisher={Elsevier} }

Installing¶

This section describes how to install and set up pyNAVIS.

First, some requirements need to be installed. If you already have a running Python3 environment, you can skip this step and move either to the User Installation or to the Developer Installation.

Requirements¶

pyNAVIS runs under Python3, so first you need to install and set up a Python3 environment.

For doing so, we recommend using Anaconda, which is a free and open-source distribution of the Python and R programming languages that aims to simplify package management and deployment. We recommend installing Anaconda 3.7, which can be downloaded from their website.

After installing Anaconda, let’s create a new Python environment, which is a directory that contains a specific collection of conda packages.

Note

Creating a Python environment is not necessary, but it is highly recommended. Environments act as a sand box where you can install and play around without spoiling the base Python installation.

For creating a Python environment, open a terminal (or the Anaconda Prompt if you are using Windows) and run:

conda create -n pyNAVIS_env python=3.7

Where pyNAVIS_env is the name of the environment and can be changed to your liking. After that, activate your environment by doing:

conda activate pyNAVIS_env

Note

Spyder, which is a well-known Python IDE is installed together with Anaconda.

After that, head over to the User Installation or to the Developer Installation instructions.

User installation¶

To install pyNAVIS, run the following line in the terminal:

pip install pyNAVIS

This will automatically install all the dependencies needed to use this package, which are numpy, scipy and matplotlib.

You can now start using pyNAVIS. Head over to the Getting Started section to introduce you to its functionalities and how to use it. Some other useful commands can be seen in the following note:

Note

To update pyNAVIS to the latest version, use the following command:

pip install --upgrade pyNAVIS

To install a specific version of pyNAVIS use the following command:

pip install pyNAVIS==version

To upgrade an already installed pyNAVIS package to the latest from PyPi use the following command:

pip install --upgrade pyNAVIS

To uninstall pyNAVIS use the following command:

pip uninstall pyNAVIS

Developer installation¶

Clone or download the repository. After that, head to:

cd /path/to/project/src

And run the following line from your terminal to install all the dependencies:

pip install -r requirements.txt

Note

Now you have everything set up to code. Take a look at the main.py file and the examples under the /examples folder to familiarize with pyNAVIS. Also, don’t forget to take a look at the pyNAVIS package section, which has all the information about classes and methods.

Warning

If you want to add new functionalities to pyNAVIS, please visit the Contributing section.

General information¶

In this section some general information regarding pyNAVIS and other aspects related to it can be found.

Glossary¶

Neuromorphic sensor: specialized sensory processing functions implemented by either analog or digital electronic circuits that are inspired by biological systems.
Address-Event Representation (AER): the AER Protocol is an asynchronous handshaking protocol used to transmit signals between neuromorphic systems. Please, refer to Sivilotti, M. A. (1991). Wiring considerations in analog VLSI systems, with application to field-programmable networks for more information.
Action potential: also called spike. It is the brief reversal of electric polarization of the membrane of a neuron.
Neuromorphic cochlea: it’s a neuromorphic sensor which mimicks the way in which the inner ear works.
Neuromorphic Auditory Sensor: also called NAS. A digital implementation (FPGA) of a neuromorphic cochlea with a cascade topology designed by Jimenez-Fernandez in 2016.
Channel: a specific frequency band of the neuromorphic cochlea. Depending on the cochlea, each channel could consists of two spike streams (or addresses), encoding the positive (ON) and the negative (OFF) part of the signal.
MEvents: megaevents, millions of events, 10^6 events. Commonly used as a unit of measurement for the number of spikes generated.
Spikegram: also called raster plot, cochleagram or cochleogram. A plot where the X axis represents time and the Y axis is the AER address assigned to the spike generated.
Sonogram: plot that represents the spike rate of the cochlea in a color map, where X axis is time, Y axis is the cochlea channel, and the color is the relative spike rate of the channel for a particular time period.
Phase-lock: Phase-locking is known as matching amplitude times to a certain phase of another waveform. In the case of auditory neurons, this means firing an action potential at a certain phase of a stimulus sound being delivered. It has been seen that when being played a pure tone, auditory nerve fibers will fire at the same frequency as the tone. Volley theory suggests that groups of auditory neurons use phase-locking to represent subharmonic frequencies of one harmonic sound. When phase-locking, ON and OFF spike streams are merged into a single stream, where a spike is generated only when the signal changes from ON to OFF or vice versa.

NAVIS and pyNAVIS¶

pyNAVIS stands for python-based Neuromorphic Auditory Visualizer (NAVIS). NAVIS is a GUI-based software tool for neuromorphic researchers to analyze spiking information obtained from a neuromorphic cochlea.

NAVIS was also developed by us, and it is the foundation of what pyNAVIS currently is. It was published in Neurocomputing journal as an Original Software Publication.

It was built on Windows Presentation Foundation (WPF), which allows an interactive GUI for fast analysis of a recorded file from a neuromorphic cochlea. As a counterpart, NAVIS is only available for Windows OS users due to its ac{GUI} framework dependency.

For this purpose, and based on many requests from different users and research groups with which the authors have collaborated, we developed pyNAVIS, a python version of that tool with many other functionalities added.

If you move from NAVIS to pyNAVIS, you will find the same whole set of functionalities. Moreover, some new useful functionalities suggested by neuromorpihc researchers in different research interships, international conferences and workshops (CapoCaccia Neuromorphic Workshop and Telluride Neuromorphic Cognition Engineering Workshop) that we’ve been to have already been implemented.

pyNAVIS does not have any GUI, which makes it lighter and faster. It is also very useful not only for being used as a standalone software package, but also to be imported within a bigger project and benefit from its functionalities. Due to the lack of an user interface, adding new functionalities to it is easier and faster than in NAVIS.

The following table summarizes the comparison between the main functionalities that NAVIS and pyNAVIS have:

Functionality		NAVIS	pyNAVIS
Loaders	- Load AEDAT
	- Load CSV
	- Load ZynqGrabber (iCub)
Plots	- Spikegram
	- Sonogram
	- Histogram
	- Average activity
	- Difference between L/R
Savers	- Save to AEDAT
	- Save to CSV
	- Save to TXT
Splitters	- Manual Splitter
	- Automatic Splitter
	- Segmenter
Generators	- Random addresses
	- Shift
	- Sweep
Dataset generation	- Phaselock dataset
	- Sonogram dataset
	- Histogram dataset
Other functionalities	- Mono to stereo
	- Stereo to mono
	- Phaselock
	- Extract channels activity
	- Check input file

Apart from that, it is also important to mention a few aspects:

pyNAVIS is cross platform, while NAVIS only works in Windows.
pyNAVIS can be easily integrated with other tools. Just by importing the pyNAVIS library in your script you can start using any of its functionalities. NAVIS cannot be integrated with other projects unless you dig deep in the code and merge it with another WPF application.
pyNAVIS does not have a GUI, while NAVIS does.
It is way easier to implement new functionalities in pyNAVIS than in NAVIS. Developers only need the basics of Python for that. In NAVIS, developers would need expertise on C#, LINQ and WPF and integrate the new function in the GUI.
Although we will continue updating NAVIS and adding new functionalities to it, users are moving towards using pyNAVIS as the reference software for neuromorphic audio processing and analysis.

Dataset generators¶

pyNAVIS incorporates different tools for generating datasets from a set of input files. All of them are included in the DatasetGenerators class.

Currently, three dataset generators are implemented:

Sonogram dataset generator: this function receives the path of a folder containing a set of AEDAT files and generates a new folder with their sonograms (in PNG format). This image dataset could be useful for training and testing CNNs or other deep learning algorithms on recognition tasks. This approach was previously used in Dominguez-Morales, Juan P., et al. “Deep neural networks for the recognition and classification of heart murmurs using neuromorphic auditory sensors.” IEEE transactions on biomedical circuits and systems 12.1 (2017): 24-34.
Histogram dataset generator: this function receives the path of a folder containing a set of AEDAT files and generates a new folder with their histograms in CSV format. This way, each CSV file consits of N rows, where N is the number of channels of the neuromorphic cochlea used to record the original files. These rows represent the number of spikes generated for that specific channel. Therefore, the histogram represents the frequency response of the cochlea for an input file. This could be useful for different scenarios and experiments. As an example, these values could be used as weights for the projections between the first and the second layer of an SNN in neuromorphic audio recognitions tasks. A similar approach was used in Dominguez-Morales, Juan Pedro, et al. “Multilayer spiking neural network for audio samples classification using SpiNNaker.” International conference on artificial neural networks. Springer, Cham, 2016..
Phaselock dataset generator: this function receives the path of a folder containing a set of AEDAT files and generates a new folder with the same files after phase-locking them. When phase-locking, ON and OFF spike streams are merged into a single stream, where a spike is generated only when the signal changes from ON to OFF or vice versa. More information regarding this procedure can be read in the Glossary. The output dataset consists of AEDAT files (one per input file) with less spikes than the original ones, and can be used for further processing, SNN training and many other tasks.

Getting started¶

After installing pyNAVIS with

pip install pyNAVIS

You can start using it by creating a new Python file and importing the package:

from pyNAVIS import *

With that, you will be able to use all the provided functionalities, which are specified in the pyNAVIS package section.

Either if you installed the developer version of if you, as an user, want to get introduced with a set of code examples, you can find them in the /src/examples folder of the Github repository after downloading or cloning it. These examples will show you how to use most of pyNAVIS functionalities. In /src/ you will find a main.py file that can be used to run those examples.

You can take a closer look at some of these main functionalities in the Examples section.

Examples¶

The /src/examples folder of the Github repository contains useful examples to start with, which can be launched from /src/main.py.

Some of these examples are explained in this section, so that users don’t have to download or clone the whole repository.

Load file¶

1. Load AEDAT and CSV files¶

To load a file, the Loaders class needs to be used. Currently, only AEDAT (.aedat) and Comma-Separated Values (.csv) files are supported.

For AEDAT files, use the loadAEDAT() function by following this example:

from pyNAVIS import *
settings = MainSettings(num_channels=16, mono_stereo=1, on_off_both=1, address_size=2, ts_tick=0.2, bin_size=10000)
spikes_info = Loaders.loadAEDAT('path/to/file/name.aedat', settings)

In this case, a file called name.aedat, which is located in path/to/file/ is loaded and stored into a SpikesFile variable named spikes_info. For that, some configuration parameters need to be chosen for that specific file. As it is shown in the code, this file consists of stereo (mono_stereo=1) information from 16 channels (num_channels=16), in which each channel has two addresses (for the positive and negative part of the signal; on_off_both=1). Also, in this AEDAT file, addresses are stored using 2 bytes (address_size=2) and each timestamp value has to be multiplied by 0.2 (ts_tick=0.2) to match real time.

Note

For the loadAERDAT function, the only parameter that is completely necessary is address_size.

On the other hand, to load a CSV file, follow the next example:

from pyNAVIS import *
spikes_info = Loaders.loadCSV('path/to/file/name.aedat')

Where no settings need to be specified.

2. Adapt and check SpikesFiles¶

Adapting a SpikesFile performs two different operations:

First, the timestamps are multiplied by the ts_tick parameter of the MainSettings.
Then, if reset_timestamp is set to True, the smallest timestamp in the file is subtracted to each of the other timestamps values.

Using the previous example, follow this lines of code to adapt the timestamps of a SpikesFile:

from pyNAVIS import *
settings = MainSettings(num_channels=16, mono_stereo=1, on_off_both=1, address_size=2, ts_tick=0.2, bin_size=10000)
spikes_info = Loaders.loadAEDAT('path/to/file/name.aedat', settings)
spikes_file_adapted = Functions.adapt_SpikesFile(spikes_info, settings)

This function returns a new SpikesFile with the same information as the one used as input, but with the timestamps adapted.

Then, the check_SpikesFile() function can be used to check if the SpikesFile is correct. This function will:

Check if all the timestamps of the SpikesFile are greater or equal than 0.
Check if all the timestamps of the SpikesFile are ordered correctly.
Check if all the addresses of the SpikesFile are between 0 and the maximum number of possible addresses, which depends on the settings.

from pyNAVIS import *
settings = MainSettings(num_channels=16, mono_stereo=1, on_off_both=1, address_size=2, ts_tick=0.2, bin_size=10000)
spikes_info = Loaders.loadAEDAT('path/to/file/name.aedat', settings)
spikes_file_adapted = Functions.adapt_SpikesFile(spikes_info, settings)
Functions.check_SpikesFile(stereo_file, settings)

Note

Both the adapt_SpikesFile() and the check_SpikesFile() functions are completely optional.

3. Plot information¶

To plot the spikegram (also known as cochleogram or raster plot), sonogram, histogram, average activity and the difference between left and right cochlea, follow the next example:

from pyNAVIS import *
settings = MainSettings(num_channels=16, mono_stereo=1, on_off_both=1, address_size=2, ts_tick=0.2, bin_size=10000)
spikes_info = Loaders.loadAEDAT('path/to/file/name.aedat', settings)
spikes_file_adapted = Functions.adapt_SpikesFile(spikes_info, settings)
Plots.spikegram(spikes_file_adapted, settings)
Plots.sonogram(spikes_file_adapted, settings)
Plots.histogram(spikes_file_adapted, settings)
Plots.average_activity(spikes_file_adapted, settings)
Plots.difference_between_LR(spikes_file_adapted, settings)

Note

The difference between left and right cochlea can only be performed in stereo (mono_stereo=1) files.

Some examples of the different plots can be seen in the following image:

Convert from mono to stereo files and vice versa¶

From mono to stereo¶

To convert from a mono SpikesFile to a stereo SpikesFile, first load the mono file:

from pyNAVIS import *
settings = MainSettings(num_channels=16, mono_stereo=0, on_off_both=1, address_size=2, ts_tick=0.2, bin_size=10000)
mono_file = Loaders.loadAEDAT('path/to/file/name.aedat', settings)

Warning

Pay attention to the mono_stereo parameter, which was set to 0, meaning that the file that is loaded is mono.

Then execute the mono_to_stereo() function:

stereo_file = Functions.mono_to_stereo(mono_file, delay=0, settings=settings, return_save_both=0)

Where delay is the time delay between left and right information.

Note

When return_save_both is set to 0, the information will be returned as a SpikesFile. If it is set to 1, the information will be saved instead of being returned. If it is set to 2, the information will be returned and also saved.

If return_save_both is set to either 1 or 2, you also have to set the path where the file will be saved, and the output_format. Check the mono_to_stereo() function for more information.

To plot the output file, you can use the graphs presented in previous examples.

from pyNAVIS import *
settings = MainSettings(num_channels=16, mono_stereo=0, on_off_both=1, address_size=2, ts_tick=0.2, bin_size=10000)
mono_file = Loaders.loadAEDAT('path/to/file/name.aedat', settings)
stereo_file = Functions.mono_to_stereo(mono_file, delay=0, settings=settings, return_save_both=0)
settings.mono_stereo = 1
Plots.spikegram(stereo_file, settings)

Warning

To plot the information, mono_stereo has to be set to 1.

From stereo to mono¶

The same procedure, but using the stereo_to_mono(), can be applied to convert a stereo file to a mono file:

from pyNAVIS import *
settings = MainSettings(num_channels=16, mono_stereo=1, on_off_both=1, address_size=2, ts_tick=0.2, bin_size=10000)
stereo_file = Loaders.loadAEDAT('path/to/file/name.aedat', settings)
mono_file = Functions.stereo_to_mono(stereo_file, left_right=0, settings=settings, return_save_both=0)
settings.mono_stereo = 0
Plots.spikegram(mono_file, settings)

For more information regarding this function, see stereo_to_mono().

Generate new files with spiking information¶

pyNAVIS has three different functionalities to generate new custom artificial files with spiking information. These are described in the Generators class:

random_addrs()
shift()
sweep()

1. Random addresses¶

The random_addr() function lets you generate a new file with completely random spikes. The spike rate, the length of the file and the number of channels can be specified to customize the output file.

from pyNAVIS import *

f = 1000        # frequency of the spikes generated per channel.
n_ch = 64       # number of channels (or addresses)
l = 1000000     # microseconds

rand_spikes = Generators.random_addrs(freq=f, num_ch=n_ch, length=l, return_save_both=0)

The parameter return_save_both is set to 0, which means that, instead of saving the information to a file, it will return it in the sweep_spikes variable. Then, you can use that variable to plot the spikes. Here you can see an example of the code that you would need to add to the previous code:

import matplotlib.pyplo as plt

rand_settings = MainSettings(num_channels=64, mono_stereo=0, on_off_both=0, bin_size=20000)

Plots.spikegram(rand_spikes, rand_settings)
Plots.sonogram(rand_spikes, rand_settings)
Plots.histogram(rand_spikes, rand_settings)

plt.show()

This will generate the plots that can be seen in the next figure.

2. Shift¶

The shift() function generates a frequency shift from lower addresses to higher addresses. To use this function, you can follow the next example:

from pyNAVIS import *

f = 10          # number of spikes per channel.
n_ch = 64       # number of channels (or addresses)
l = 1000000     # microseconds

shift_spikes = Generators.shift(freq=f, num_ch=n_ch, length=l, return_save_both=0)

And plot the information with the same code that was used in previous examples.

Here you can see the spikegram of the shift that corresponds to the example:

3. Sweep¶

The sweep() is very similar to the shift() function, but instead of going from lower to higher addresses, it goes back again, doing a full cycle.

See the following example:

from pyNAVIS import *

f = 5           # number of spikes per channel and shift.
c = 5           # total number of cycles to perform
n_ch = 64       # number of channels (or addresses)
l = 1000000     # microseconds

sweep_spikes = Generators.sweep(freq=f, cycles=c, num_ch=n_ch, length=l, return_save_both=0)

And you can also plot the information following the example presented in the random_addrs() section.

Here you can see the spikegram of the sweep that corresponds to the example:

Manually split spiking information¶

With pyNAVIS you can both select a specific portion of time from a file and extract it, and also get the information from a set of addresses which can be specified by the user.

1. Extract a portion of the file¶

To do this, you should use the manual_splitter() function from the Splitters class.

Here you can find an example where a file is loaded and then a portion of it is extracted (from 0 to 100000 microseconds):

from pyNAVIS import *

init_timestamp = 0          # microseconds
end_timestamp  = 100000     # microseconds

settings = MainSettings(num_channels=16, mono_stereo=1, on_off_both=1, address_size=2, ts_tick=0.2, bin_size=10000)
spikes_info = Loaders.loadAEDAT('path/to/file/name.aedat', settings)
spikes_file_adapted = Functions.adapt_SpikesFile(spikes_info, settings)

manual_split_spikes = Splitters.manual_splitter(spikes_file_adapted, init=init_timestamp, end=end_timestamp, settings=settings, return_save_both=0)

Whose information can be saved into a file, plotted, or processed.

2. Extract a set of addresses from the file¶

You can also extract a user-defined set of addresses from a file.

To do this, you should use the extract_channels_activities() function from the Functions class.

See the following example:

from pyNAVIS import *

addresses_set = [0, 1, 2, 3]   # List of addresses to extract from the file. Can also be set with range(4).

settings = MainSettings(num_channels=16, mono_stereo=1, on_off_both=1, address_size=2, ts_tick=0.2, bin_size=10000)
spikes_info = Loaders.loadAEDAT('path/to/file/name.aedat', settings)
spikes_file_adapted = Functions.adapt_SpikesFile(spikes_info, settings)

addresses_info = Functions.extract_channels_activities(spikes_file_adapted, addresses=addresses_set)

If you want to plot addresses_info, the settings should be changed to support the number of addresses that this new variable has.

Phaselock¶

An interesting functionality that is supported in this software package is the phaselock operation.

The phaselock operation puts a spike in the output only when the spike train from a specific channel changes from ON (positive part of the signal) to OFF (negative part of the signal). This heavily reduces the number of spikes at the output.

Note

This functionality can only be used in files that have two addresses per channel (ON and OFF). The settings should also match this (on_off_both has to be equal to 1).

See the following example:

from pyNAVIS import *

settings = MainSettings(num_channels=64, mono_stereo=0, on_off_both=1, address_size=2, ts_tick=0.2, bin_size=10000)
spikes_info = Loaders.loadAEDAT('path/to/file/name.aedat', settings)
spikes_file_adapted = Functions.adapt_SpikesFile(spikes_info, settings)

phaselocked_file = Functions.phase_lock(spikes_file_adapted, settings)

Warning

If you want to plot the output, the settings should be changed before plotting, since the phaselock operation fuses ON and OFF addresses into only one (on_off_both should be set to 0).

Generate image datasets from spiking information¶

With this functionality you can generate a set of sonogram images from a folder where files are.

from pyNAVIS import *

input_folder            = 'path/to/input_folder'    # folder that contains the files with spikes
output_folder           = 'path/to/output_folder'   # folder where the sonograms will be saved
allow_subdirectories    = False                     # look into subdirectories within input_folder

settings = MainSettings(num_channels=64, mono_stereo=1, on_off_both=1, address_size=2, ts_tick=0.2, bin_size=20000)

DatasetGenerators.generate_sonogram_dataset(input_folder, output_folder, settings, allow_subdirectories=allow_subdirectories)

Note

Currently, this functionality only supports AEDAT (.aedat) files.

pyNAVIS package¶

In this section, you can find all the information regarding pyNAVIS’ parameters, functions, classes and modules. The following figure depicts the current software architecture of this package.

You can navigate through the different modules by using the sidebar menu.

pyNAVIS.dataset_gen¶

DatasetGenerators¶

pyNAVIS.functions¶

Functions¶

class pyNAVIS.functions.Functions[source]¶

Methods:

`ISI`(spikes_file[, verbose])	Generates an array with the inter-spike intervals of the input SpikesFile.
`adapt_timestamps`(spikes_file, settings)	Subtracts the smallest timestamp of the timestamps list to all of the timestamps contained in the list (in order to start from 0) It also adapts timestamps based on the tick frequency (ts_tick in the MainSettings).
`check_LocalizationFile`(localization_file, ...)	Checks if the spiking information contained in the LocalizationFile is correct and prints "The loaded LocalizationFile file has been checked and it's OK" if the file passes all the checks.
`check_SpikesFile`(spikes_file, settings)	Checks if the spiking information contained in the SpikesFile is correct and prints "The loaded SpikesFile file has been checked and it's OK" if the file passes all the checks.
`extract_channels_activities`(spikes_file, ...)	Extract information from a specific set of addresses from the SpikesFile.
`mono_to_stereo`(spikes_file, delay, settings)	Generates a stereo AEDAT SpikesFile from a mono SpikesFile with a specific delay between both.
`phase_lock`(spikes_file, settings[, posNeg_both])	Performs the phase lock operation over a SpikesFile.
`stereo_to_mono`(spikes_file, left_right, settings)	Generates a mono AEDAT SpikesFile from a stereo SpikesFile.

static ISI(spikes_file, verbose=False)[source]¶

Generates an array with the inter-spike intervals of the input SpikesFile.

Parameters

spikes_file (SpikesFile or string) – File or path to use.
settings (MainSettings) – Configuration parameters for the input file.
verbose (boolean, optional) – Set to True if you want the execution time of the function to be printed.

Returns

int[] – inter-spike interval array.

static adapt_timestamps(spikes_file, settings)[source]¶

Subtracts the smallest timestamp of the timestamps list to all of the timestamps contained in the list (in order to start from 0) It also adapts timestamps based on the tick frequency (ts_tick in the MainSettings).

Parameters

spikes_file –
settings (MainSettings) – Configuration parameters for the file to adapt.

Returns

adapted_timestamps – Adapted timestamps list.

static check_LocalizationFile(localization_file, settings, localization_settings)[source]¶

Checks if the spiking information contained in the LocalizationFile is correct and prints “The loaded LocalizationFile file has been checked and it’s OK” if the file passes all the checks.

Parameters

localization_file (LocalizationFile) – File to check.
settings (MainSettings) – Configuration parameters for the file to check.
localization_settings (LocalizationSettings) – Configuration parameters of the localization model for the file to check.

Returns

None.

Raises

TimestampOrderError – If the LocalizationFile contains at least one timestamp which value is less than 0.
TimestampOrderError – If the LocalizationFile contains at least one timestamp that is lesser than its previous one.
ChannelValueError – If the LocalizationFile contains at least one address less than mso_start_channel or greater than mso_end_channel that you specified in the LocalizationSettings.
NeuronIDValueError – If the LocalizationFile contains at least one address less than 0 or greater than the mso_num_neurons_channel you specified in LocalizationSettings

Notes

If mso_start_channel is set to 33 and mso_end_channel is set to 36, there will be four possible channel values: [33, 36]

static check_SpikesFile(spikes_file, settings)[source]¶

Checks if the spiking information contained in the SpikesFile is correct and prints “The loaded SpikesFile file has been checked and it’s OK” if the file passes all the checks.

Parameters

spikes_file (SpikesFile) – File to check.
settings (MainSettings) – Configuration parameters for the file to check.

Returns

None.

Raises

TimestampOrderError – If the SpikesFile contains at least one timestamp which value is less than 0.
TimestampOrderError – If the SpikesFile contains at least one timestamp that is lesser than its previous one.
AddressValueError – If the SpikesFile contains at least one address less than 0 or greater than the num_channels that you specified in the MainSettings.

Notes

If mono_stereo is set to 1 (stereo) in the MainSettings, then addresses should be less than num_channels*2.

If on_off_both is set to 1 (both) in the MainSettings, then addresses should be less than num_channels*2.

If mono_stereo is set to 1 and on_off_both is set to 1 in the MainSettings, then addresses should be less than num_channels*2*2.

static extract_channels_activities(spikes_file, addresses, reset_addresses=True, verbose=False)[source]¶

Extract information from a specific set of addresses from the SpikesFile.

Parameters

spikes_file (SpikesFile) – File to use.
addresses (int[]) – List of addresses to extract.
reset_addresses (boolean, optional) – If set to true, addresses IDs will start from 0. If not, they will keep their original IDs.
verbose (boolean, optional) – Set to True if you want the execution time of the function to be printed.

Returns

SpikesFile – SpikesFile containing only the information from the addresses specified as input from spikes_file.

static mono_to_stereo(spikes_file, delay, settings, return_save_both=0, path=None, output_format='.aedat')[source]¶

Generates a stereo AEDAT SpikesFile from a mono SpikesFile with a specific delay between both.

Parameters

spikes_file (SpikesFile) – Input file.
delay (int) – Delay (microseconds) introduced between left and right spikes. Can be either negative or positive.
settings (MainSettings) – Configuration parameters for the input file.
return_save_both (int, optional) – Set it to 0 to return the SpikesFile, to 1 to save the SpikesFile in the output path, and to 2 to do both.
path (string, optional) – Path where the output file will be saved. Format should not be specified. Not needed if return_save_both is set to 0.
output_format (string, optional) – Output format of the file. Currently supports ‘.aedat’, ‘.csv’, “.txt” and “.txt_rel”. See the Savers class for more information.

Returns

SpikesFile – SpikesFile containing the shift. Returned only if return_save_both is either 0 or 2.

Raises

SettingsError – If the input file is a stereo SpikesFile (settings.mono_stereo is set to 1).

Note: The timestamp of the left event is used as reference. Thus, the timestamp of the right event will be ts_right = ts_left + delay.

static phase_lock(spikes_file, settings, posNeg_both=0)[source]¶

Performs the phase lock operation over a SpikesFile. This can only be performed to SpikeFiles with both ON and OFF addresses. The phaselock operation puts a spike in the output only when the spike train from a specific channel changes from ON (positive part of the signal) to OFF (negative part of the signal). This heavily reduces the number of spikes at the output.

Parameters

spikes_file (SpikesFile) – File used to perform the phase lock.
settings (MainSettings) – Configuration parameters of the input file.
posNeg_both (int, optional) – If set to 0, a spike is generated only when spike trains change from ON to OFF addresses. If set to 1, a spike is generated every time spike trains change from ON to OFF addresses or vice versa.

Returns

SpikesFile – Phase-locked SpikesFile.

Raises

SettingsError – If the on_off_both parameter is not set to 1 (both) in the MainSettings.

static stereo_to_mono(spikes_file, left_right, settings, return_save_both=0, path=None, output_format='.aedat')[source]¶

Generates a mono AEDAT SpikesFile from a stereo SpikesFile.

Parameters

spikes_file (SpikesFile) – Input file.
left_right (int) – Set to 0 if you want to extract the left part of the SpikesFile, or to 1 if you want the right part.
settings (MainSettings) – Configuration parameters for the input file.
return_save_both (int, optional) – Set it to 0 to return the SpikesFile, to 1 to save the SpikesFile in the output path, and to 2 to do both.
path (string, optional) – Path where the output file will be saved. Format should not be specified. Not needed if return_save_both is set to 0.
output_format (string, optional) – Output format of the file. Currently supports ‘.aedat’, ‘.csv’, “.txt” and “.txt_rel”. See the Savers class for more information.

Returns

SpikesFile – SpikesFile containing the shift. Returned only if return_save_both is either 0 or 2.

Raises

AttributeError – If the input file is a mono SpikesFile (settings.mono_stereo is set to 0).

pyNAVIS.generators¶

Generators¶

pyNAVIS.loaders¶

SpikesFile¶

class pyNAVIS.loaders.SpikesFile(addresses=[], timestamps=[])[source]¶

Class that contains all the addresses and timestamps of a file.

Variables

~SpikesFile.timestamps (int[]) – Timestamps of the file.
~SpikesFile.addresses (int[]) – Addresses of the file.

Note

Timestamps and addresses are matched, which means that timestamps[0] is the timestamp for the spike with address addresses[0].

Loaders¶

class pyNAVIS.loaders.Loaders[source]¶

Functionalities for loading spiking information from different formats.

Methods:

`loadAEDAT`(path, settings)	Loads an AEDAT (.aedat) file.
`loadAEDATLocalization`(path, settings, ...)	Loads an AEDAT (.aedat) file which contains events from both the NAS model and the SOC model (sound source localization).
`loadCSV`(path[, delimiter])	Loads a Comma-Separated Values (.csv) file.
`loadCSVLocalization`(path[, delimiter])	Loads a Comma-Separated Values (.csv) file which contains events from both the NAS model and the SOC model (sound source localization).
`loadZynqGrabberData`(path, settings, ...)	Loads a text (.txt) file with EAR events collected by the zynqGrabber.

static loadAEDAT(path, settings)[source]¶

Loads an AEDAT (.aedat) file.

Parameters

path (string) – Full path of the AEDAT file to be loaded, including name and extension.
settings (MainSettings) – Configuration parameters for the file to load.

Returns

SpikesFile – SpikesFile containing all the addresses and timestamps of the file.

static loadAEDATLocalization(path, settings, localization_settings)[source]¶

Loads an AEDAT (.aedat) file which contains events from both the NAS model and the SOC model (sound source localization).

Parameters

path (string) – Full path of the AEDAT file to be loaded, including name and extension.
settings (MainSettings) – Configuration parameters for the file to load.
localization_settings (LocalizationSettings) – Configuration parameters of the localization module for the file to load.

Returns

SpikesFile – SpikesFile containing all the addresses and timestamps of the file. LocalizationFile: LocalizationFile containing all the events from both the MSO and LSO models of the file.

Raises

SettingsError – If settings.address_size is different than 2 and 4.

static loadCSV(path, delimiter=',')[source]¶

Loads a Comma-Separated Values (.csv) file.

Parameters

path (string) – Full path of the CSV file to be loaded, including name and extension.
delimiter (char) – Delimiter to use in the CSV file.

Returns

SpikesFile – SpikesFile containing all the addresses and timestamps of the file.

Note

The CSV file should contain one line per event, and the information in each line should be: address, timestamp

static loadCSVLocalization(path, delimiter=',')[source]¶

Loads a Comma-Separated Values (.csv) file which contains events from both the NAS model and the SOC model (sound source localization).

Parameters

path (string) – Full path of the CSV file to be loaded, including name and extension.
delimiter (char) – Delimiter to use in the CSV file.

Returns

SpikesFile – SpikesFile containing all the addresses and timestamps of the file. LocalizationFile: LocalizationFile containing all the events from both the MSO and LSO models of the file.

Note

The CSV file should contain one line per event, and the information in each line should be: address, timestamp

The CSV format should be: address, timestamp, auditory_model, xso_type, neuron_id.

static loadZynqGrabberData(path, settings, localization_settings)[source]¶

Loads a text (.txt) file with EAR events collected by the zynqGrabber.

Parameters

path (string) – Full path of the CSV file to be loaded, including name and extension.
settings (MainSettings) – Configuration parameters for the file to load.
localization_settings (LocalizationSettings) – Configuration parameters of the localization module for the file to load.

Returns

spikes_file – SpikesFile containing all the addresses and timestamps of the file. localization_file: LocalizationFile containing all the events from both the MSO and LSO models of the file.

pyNAVIS.main_settings¶

MainSettings¶

pyNAVIS.plots¶

Plots¶

pyNAVIS.savers¶

Savers¶

class pyNAVIS.savers.Savers[source]¶

Methods:

`save_AEDAT`(spikes_file, path, settings[, ...])	Saves a SpikesFile into an AEDAT file.
`save_CSV`(spikes_file, path[, split, ...])	Saves a SpikesFile into a CSV file where each spike is represented in one line following the same patter: "address, timestamp".
`save_TXT`(spikes_file, path[, split, ...])	Saves a SpikesFile into two different TXT files, where addresses and timestamps are stored, respectively.
`save_TXT_relativeTS`(spikes_file, path[, ...])	Saves a SpikesFile into two different TXT files, where addresses and timestamps are stored, respectively.
`save_as_any`(spikes_file, path, output_format)	Saves a SpikesFile into any of the implemented Savers, depending on the output format selected.

static save_AEDAT(spikes_file, path, settings, verbose=False)[source]¶

Saves a SpikesFile into an AEDAT file.

Parameters

spikes_file (SpikesFile) – File to save.
path (string) – Path where the output file will be saved, including name. Extension should not be specified.
settings (MainSettings) – Configuration parameters for the file to save.
verbose (boolean, optional) – Set to True if you want the execution time of the function to be printed.

Returns

None.

static save_CSV(spikes_file, path, split=False, separator=', ', verbose=False)[source]¶

Saves a SpikesFile into a CSV file where each spike is represented in one line following the same patter: “address, timestamp”.

Parameters

spikes_file (SpikesFile) – File to save.
path (string) – Path where the output file will be saved, including name. Extension should not be specified.
split (boolean, optional) – True for generating two files (addresses and timestamps), and False for generating one with all the information.
separator (string, optional) – which character to use as separator between addresses and timestamps when split = False
verbose (boolean, optional) – Set to True if you want the execution time of the function to be printed.

Returns

None.

static save_TXT(spikes_file, path, split=True, separator=', ', verbose=False)[source]¶

Saves a SpikesFile into two different TXT files, where addresses and timestamps are stored, respectively.

Parameters

spikes_file (SpikesFile) – File to save.
path (string) – Path where the output file will be saved, including name. Extension should not be specified.
split (boolean, optional) – True for generating two files (addresses and timestamps), and False for generating one with all the information.
separator (string, optional) – which character to use as separator between addresses and timestamps when split = False
verbose (boolean, optional) – Set to True if you want the execution time of the function to be printed.

Returns

None.

static save_TXT_relativeTS(spikes_file, path, split=True, separator=', ', verbose=False)[source]¶

Saves a SpikesFile into two different TXT files, where addresses and timestamps are stored, respectively. Timestamps are relative to the previous spike.

Parameters

spikes_file (SpikesFile) – File to save.
path (string) – Path where the output file will be saved, including name. Extension should not be specified.
split (boolean, optional) – True for generating two files (addresses and timestamps), and False for generating one with all the information.
separator (string, optional) – which character to use as separator between addresses and timestamps when split = False
verbose (boolean, optional) – Set to True if you want the execution time of the function to be printed.

Returns

None.

static save_as_any(spikes_file, path, output_format, settings=None)[source]¶

Saves a SpikesFile into any of the implemented Savers, depending on the output format selected.

Parameters

spikes_file (SpikesFile) – File to save.
path (string) – Path where the output file will be saved. Format should not be specified.
output_format (string) – Output format of the file. Currently supports ‘.aedat’, ‘.csv’, “.txt” and “.txt_rel”. See the Savers class for more information.
settings (MainSettings, optional) – Configuration parameters for the output file. Only needed when saving the output as an AEDAT file.

Returns

None.

Raises

SettingsError – if settings are not specified and output_format refers to AEDAT.

pyNAVIS.splitters¶

Splitters¶

pyNAVIS.utils¶

Utils¶

class pyNAVIS.utils.Utils[source]¶

Methods:

`execution_time`(executing_function, ...)	Calculate the time that a function takes to execute (in seconds).
`extract_addr_and_ts`(zipped_addr_ts)	Converts a list of [address, timestamp] tuples into a SpikesFile.
`getKey`(item)	Get timestamps.
`get_info`(spikes_file)	Prints the number of spikes and the number of microseconds of audio that the SpikesFile contains.
`order_timestamps`(spikes_file)	Order the spikes contained in a SpikesFile by timestamp.

static execution_time(executing_function, function_params)[source]¶

Calculate the time that a function takes to execute (in seconds).

Parameters

executing_function (function) – The name of the function whose execution time wants to be calculated.
function_params (list) – List of the parameters that want to be used in the executing_function.

Returns

float – Time that the function takes to execute.

static extract_addr_and_ts(zipped_addr_ts)[source]¶

Converts a list of [address, timestamp] tuples into a SpikesFile.

Parameters: aedat_addr_ts (list) – A list of [address, timestamp] tuples.
Returns: SpikesFile – A SpikesFile object with the addresses and timestamps obtained from zipped_addr_ts

static getKey(item)[source]¶

Get timestamps. Used to sort zipped list of [address, timestamp] tuples by timestamp.

Parameters: item (tuple) – [address, timestamp] tuple.
Returns: int – Timestamp.

static get_info(spikes_file)[source]¶

Prints the number of spikes and the number of microseconds of audio that the SpikesFile contains.

Parameters: spikes_file (SpikesFile) – File to get the information from.
Returns: None.

static order_timestamps(spikes_file)[source]¶

Order the spikes contained in a SpikesFile by timestamp.

Parameters: spikes_file (SpikesFile) – Input SpikesFile to order.
Returns: SpikesFile – Ordered SpikesFile.

Contributing¶

New functionalities or improvements to the existing project are welcome. To contribute to this project please follow these guidelines:

Search previous suggestions before making a new one, as yours may be a duplicate.
Fork the project.
Create a branch.
Commit your changes to improve the project.
Push this branch to your GitHub project.
Open a Pull Request.
Discuss, and optionally continue committing.
Wait untill the project owner merges or closes the Pull Request.

If it is a new feature request (e.g., a new functionality), post an issue to discuss this new feature before you start coding. If the project owner approves it, assign the issue to yourself and then do the steps above. Thank you for contributing to pyNAVIS!