API

thorns

Spike analysis software.

thorns.accumulate(spike_trains, ignore=None, keep=None)

Concatenate spike trains with the same meta data. Trains will be sorted by the metadata.

thorns.correlation_index(spike_trains, coincidence_window=5e-05, normalize=True)

Compute correlation index from spike_trains as described in [Joris2006].

References

[Joris2006]

Joris, P. X., Louage, D. H., Cardoen, L., & van der Heijden, M. (2006). Correlation index: a new metric to quantify temporal coding. Hearing research, 216, 19-30.

thorns.entrainment(spike_trains, freq, bin_size=0.001)

Calculate entrainment of spike_trains in response to periodic stimulus (freq Hz).

thorns.firing_rate(spike_trains)

Calculates average firing rate of neurons.

thorns.fold(spike_trains, period)

Fold spike_trains by period.

thorns.gcf()

Equivalent of plt.gcf()

thorns.get_duration(spike_trains)

Return the common duration of spike_trains.

thorns.isih(spike_trains, bin_size, **kwargs)

Calculate inter-spike interval histogram (ISIH).

Returns:

array_like

Histogram values.

array_like

Bin edges.

thorns.make_trains(data, **kwargs)

Create spike trains from various data formats.

thorns.period_histogram(spike_trains, freq, nbins=64, **kwargs)

Calculate period histogram of spike_trains to the periodic stimulus (ferq Hz).

Returns:

ndarray

Histogram values.

ndarray

Bin edges.

thorns.plot_isih(spike_trains, bin_size, ax=None, drawstyle='steps-post', density=True, **kwargs)

Plot inter-spike interval histogram.

thorns.plot_neurogram(spike_trains, fs, ax=None, **kwargs)

Visualize spike_trains by converting them to bit map and plot using plt.imshow(). Set fs reasonably in order to avoid aliasing effects.

For smaller number of spike trains, it’s usually better to use plot_raster.

thorns.plot_period_histogram(spike_trains, freq, nbins=64, shift=0, ax=None, style='', density=False, drawstyle='steps-post', **kwargs)

Plot period histogram of the given spike trains.

Parameters:

spike_trains : spike_trains

Spike trains for plotting.

freq : float

Stimulus frequency.

nbins : int

Number of bins for the histogram.

shift : float

Defines how much should the phase be shifted in the plot.

ax : plt.Ax, optional

Matplotlib Ax to plot on.

style : str, optional

Plotting style (See matplotlib plotting styles).

density : bool, optional

If False, the result will contain the number of samples in each bin. If True, the result is the value of the probability density function at the bin, normalized such that the integral over the range is 1. (See np.histogram() for reference)

drawstyle : {‘default’, ‘steps’, ‘steps-pre’, ‘steps-mid’, ‘steps-post’}

Set the drawstyle of the plot.

Returns:

plt.Axis

Matplotlib axis containing the plot.

thorns.plot_psth(spike_trains, bin_size, ax=None, drawstyle='steps-post', **kwargs)

Plots PSTH of spike_trains.

thorns.plot_raster(spike_trains, ax=None, style='k.', **kwargs)

Plot raster plot.

thorns.plot_sac(spike_trains, coincidence_window=5e-05, analysis_window=0.005, normalize=True, ax=None, style='k-', **kwargs)

Plot shuffled autocorrelogram (SAC) (Joris 2006)

thorns.plot_signal(signal, fs=None, ax=None, style='', **kwargs)

Plot time signal.

Parameters:

signal : array_like

Time signal.

fs : float, optional

Sampling freuency of the signal.

ax : plt.Axis, optional

Axis to plot onto.

style : str, optional

Plotting style string.

Returns:

plt.Axis

Matplotlib Axis with the plot.

thorns.psth(spike_trains, bin_size, normalize=True, **kwargs)

Calculate peristimulus time histogram (PSTH).

Returns:

array_like

Histogram values.

array_like

Bin edges.

thorns.select_trains(spike_trains, **kwargs)

Select trains from spike_trains where kwargs are equal to the metadata.

thorns.show()

Equivalent of plt.show()

thorns.shuffled_autocorrelogram(spike_trains, coincidence_window=5e-05, analysis_window=0.005, normalize=True)

Calculate shuffled autocorrelogram (SAC) of spike_trains as described in [Joris2006].

Returns:

ndarray

Histogram values.

ndarray

Bin edges.

References

[Joris2006]

Joris, P. X., Louage, D. H., Cardoen, L., & van der Heijden, M. (2006). Correlation index: a new metric to quantify temporal coding. Hearing research, 216, 19-30.

thorns.spike_count(spike_trains)

Count all spikes in spike_trains.

thorns.trains_to_array(spike_trains, fs)

Convert spike_trains to 2D array (signals) with samlping frequency fs.

thorns.trim(spike_trains, start=0, stop=None)

Trim the spike trains.

Remove all spikes outside of the (start, stop) range.

thorns.vector_strength(spike_trains, freq)

Calculate vector strength of spike_trains in response to periodic stimulus (freq Hz).

thorns.waves

DSP related functions.

thorns.waves.align(a, fs_a, b, fs_b)

Align two signals, a and b, so that they have the same sampling frequency (resample to lower fs) and length (trim longer signal).

thorns.waves.amplitude_modulated_tone(fs, fm, fc, m, duration, pad=0, ramp=0.0025, dbspl=None)

Generate amplitude modulated tone.

Parameters:

fs : float

Sampling frequency in Hz.

fm : float

Modulation frequency in Hz.

fc : float

Carrier frequency in Hz.

m : float

Modulation depth <0-1>.

duration : float

Tone duration in seconds.

pad : float, optional

Duration of the pad in seconds (default is 0)

ramp : float, optional

Duration of the ramp in seconds (default is 2.5 ms)

dbspl : float, optional

Amplitude of the tone in dB SPL. If None (default), no scaling.

Returns:

array_like

AM signal.

thorns.waves.electrical_amplitudes(durations, polarity, ratio=None)

Calculate amplitudes for each “phase” of signle electrical pulse in cochlear implant.

The resulting pulses are charged ballanced. The function supports mono-, bi- and tri-phasic pulses.

Parameters:

durations : array_like

List of phase durations in the pulse.

polarity : {-1, 1, ‘c’ ‘cathodic’, ‘a’, ‘anodic’}

Polarity of the first phase. -1, ‘c’ and ‘cathodic’ are equivalent. As well as 1, ‘a’ and ‘anodic’.

ratio : float

Only valid for triphasic pulses. It is equal to the charge ratio between the first and second phase.

Returns:

tuple

Amplitudes of phases corresponding to durations.

thorns.waves.electrical_pulse(fs, amplitudes, durations, gap=0, pad=0, charge=None)

Generate electrical pulse.

Parameters:

fs : scalar

Sampling frequency of the output.

amplitudes : array_like

A list of amplitudes in Ampere of each phase of the output pulse.

durations : array_like

A list of desired durations of each phase of the output pulse in seconds. Must have the same number of elements as amplitudes.

gap : scalar

Desired duration of the gaps between phases of the output pulse.

pad : scalar

Desired duration of the zero signal appended at the end of the pulse.

charge : None, scalar, optional

If scalar, then it is equal to the absolute charge of the output pulse. Amplitudes of the phases will be re-scaled, but will preserve their ratios to one other.

Returns:

array_like

Output signal (a pulse).

thorns.waves.fft_filter(signal, fs, band)

Filter signal using a FFT filter.

Parameters:

signal : array_like

Input signal.

fs : float

Sampling frequency of the input signal.

band : tuple

Tuple with lower and upler cut of frequencies: (lo, hi).

Returns:

array_like

Filtered signal.

thorns.waves.plot_signal(signal, fs=None, ax=None, style='', **kwargs)

Plot time signal.

Parameters:

signal : array_like

Time signal.

fs : float, optional

Sampling freuency of the signal.

ax : plt.Axis, optional

Axis to plot onto.

style : str, optional

Plotting style string.

Returns:

plt.Axis

Matplotlib Axis with the plot.

thorns.waves.ramped_tone(fs, freq, duration, pad=0, pre=0, ramp=0.0025, dbspl=None)

Generate ramped tone singal.

Parameters:

fs : float

Sampling frequency in Hz.

freq : float

Frequency of the tone in Hz.

duration : float

Duration of the tone in seconds.

pad : float, optional

Duration of the pad in seconds (default is 0). Pad will be appended at the end of the signal.

pre : float, optional

Duration of the pre-pad in seconds. This pad will be attached at the end of the siganl.

ramp : float, optional

Duration of the ramp in seconds (default is 2.5 ms)

dbspl : float, optional

Amplitude of the tone in dB SPL. If None (default), no scaling. Scaling is done before ramping and appending the pad.

Returns:

array_like

The output tone with optional padding.

thorns.waves.resample(signal, fs, new_fs)

Resample signal from fs to new_fs.

thorns.waves.rms(signal)

Calculate root mean squere of a signal.

thorns.waves.set_dbspl(signal, dbspl)

Scale the level of signal to the given dB_SPL.

thorns.waves.show()

Equivalent of plt.show()

thorns.waves.snr(signal, noise)

Calculate signal-to-noise ratio in dB given signal and noise.

thorns.waves.t(signal, fs)

Return time vector for signal with sampling frequency fs (Hz).

thorns.waves.trim(a, b)

Trim the longer vector, so that both have the same length.

thorns.util

Utilities.

thorns.util.cache(func, workdir=u'work')

Wrap a function and cache its output.

thorns.util.dumpdb(data, name=u'dump', workdir=u'work', kwargs=None)

Dump data in order to recall the most up-to-date records later.

Parameters:

data : pd.DataFrame

Data that will be appended to the database.

name : str, optional

Base name of the pickle file.

workdir : str, optional

Directory for the data.

kwargs : dict, optional

Additional parameters common for all data (MultiIndex will be extended).

thorns.util.find_zero(func, x1, x2, xtol=None, kwargs=None)

Find a zero crossing of a function using binary search.

Parameters:

func : function

Function must be increasing and have one zero crossing.

x1, x2 : float

Lower and upper range. Requirements (func(x1) < 0) and (func(x2) > 0).

xtol : float, optional

Range (x2-x1) at which the search stops. If not specified, then 1e-3-th of the difference between x2 and x1 will be taken.

kwargs : dict, optional

Extra keyword arguments for the function.

Returns:

float

Function argument x0 for which func(x0) ~ 0.

thorns.util.get_store(name=u'store', workdir=u'work')

Return a quick and dirty shelve based persisten dict-like store.

thorns.util.loaddb(name=u'dump', workdir=u'work', timestamp=False, load_all=False)

Recall dumped data discarding duplicated records.

Parameters:

name : str, optional

Base of the data filename.

workdir : str, optional

Directory where the data is stored.

timestamp : bool, optional

Add an extra column with timestamps to the index.

load_all : bool, optional

If True, data from all experiments will be loaded from the dumpdb file. The default is to load only the most recent data.

Returns:

pd.DataFrame

Data without duplicates.

thorns.util.map(func, space, backend=None, cache=None, workdir=u'work', dependencies=None, kwargs=None)

Apply func to every item of iterable and return a list of the results. This map supports multiple backends, e.g. ‘serial’, ‘multiprocessing’, ‘ipcluster’.

Parameters:

func : function

The function to be applied to the data.

space : (list of dicts) or (dict of lists)

Parameter space, where the keys of the dictonary(s) correspond to the keyward arguments of the function. In the case of a list of dicts, each entry of the list is applied to the function. In the case of a dict of lists, the parameter space is built by using all possible permutations of the list entries.

backend : {‘serial’, ‘ipcluster’, ‘multiprocessing’, ‘serial_isolated’}

Choose a backend for the map.

cache : bool or {‘yes’, ‘no’, ‘redo’}

If True, each result is loaded instead calculated again.

workdir : str, optional

Directory in which to store cache.

dependencies : list, optional

List of python files that will be imported on the remote site before executing the func.

kwargs : dict, optional

Extra parameters for the func.

Returns:

pd.DataFrame

Table with parameters (MultiIndex) and results.

thorns.io

Contains functions to read and write spike data in different formats.

thorns.io.read_brainwaref32(filename, stimparams=None)

Read the spike timings as exported from BrainWare.

BrainWare is software by Tucker-Davis Technologies.

Parameters:

filename : str

The branwaref32 file to import.

stimparams : dict

A dict with the parameter names used in the stimulation sequence. The key gives the parameter number as an integer while the value is the new name as a string.

Returns:

spike_trains

A DataFrame containing the spike timings in the thonrns spike_train format.