Spiking features¶

SpikingFeatures contains a set of features relevant for models of single neurons that receive an external stimulus and responds by eliciting a series of action potentials, also called spikes. Many of these features require the start time and end time of the stimulus, which must be returned as info["stimulus_start"] and info["stimulus_start"] in the model function. info is then used as an additional input argument in the calculation of each feature. SpikingFeatures implements a preprocess() method, which locates spikes in the model output.

The features included in the SpikingFeatures are briefly defined below. This set of features was taken from the previous work of Druckmann et al., 2007, with the addition of the number of action potentials during the stimulus period. We refer to the original publication for more detailed definitions.

nr_spikes – Number of action potentials (during stimulus period).

spike_rate – Action potential firing rate (number of action potentials divided by stimulus duration).

time_before_first_spike – Time from stimulus onset to first elicited action potential.

accommodation_index – Accommodation index (normalized average difference in length of two consecutive interspike intervals).

average_AP_overshoot – Average action potential peak voltage.

average_AHP_depth – Average afterhyperpolarization depth (average minimum voltage between action potentials).

average_AP_width – Average action potential width taken at midpoint between the onset and peak of the action potential.

A set of standard spiking features is already included in SpikingFeatures, but the user may want to add custom features. The preprocess() method changes the input given to the feature functions, and as such each spiking feature function has the following input arguments:

The time array returned by the model simulation.

An Spikes object (spikes) which contain the spikes found in the model output.

An info dictionary with info["stimulus_start"] and info["stimulus_end"] set.

The Spikes object is a preprocessed version of the model output, used as a container for Spike objects. In turn, each Spike object contain information of a single spike. This information includes a brief voltage trace represented by a time and a voltage (V) array that only includes the selected spike. The information in Spikes is used to calculate each feature. As an example, let us assume we want to create a feature that is the time at which the first spike in the voltage trace ends. Such a feature can be defined as follows:

def first_spike_end_time(time, spikes, info):
    # Calculate the feature from the spikes object
    spike = spikes[0]              # Get the first spike
    values_feature = spike.t[-1]   # The last time point in the spike

    return None, values_feature

This feature may now be used as a feature function in the list given to the new_features argument.

From the set of both built-in and user defined features, we may select subsets of features that we want to use in the analysis of a model. Let us say we are interested in how the model performs in terms of the three features: nr_spikes, average_AHP_depth and first_spike_end_time. A spiking features object that calculates these features is created by:

features_to_run = ["nr_spikes",
                   "average_AHP_depth",
                   "first_spike_end_time"]

features = un.SpikingFeatures(new_features=[first_spike_end_time],
                              features_to_run=features_to_run)

API Reference¶

class uncertainpy.features.SpikingFeatures(new_features=None, features_to_run=u'all', interpolate=None, threshold=-30, end_threshold=-10, extended_spikes=False, trim=True, normalize=False, min_amplitude=0, min_duration=0, labels={}, strict=True, logger_level=u'info')[source]¶

Spiking features of a model result, works with single neuron models and voltage traces.

Parameters:	new_features ({None, callable, list of callables}) – The new features to add. The feature functions have the requirements stated in `reference_feature`. If None, no features are added. Default is None. features_to_run ({“all”, None, str, list of feature names}, optional) – Which features to calculate uncertainties for. If `"all"`, the uncertainties are calculated for all implemented and assigned features. If None, or an empty list `[]`, no features are calculated. If str, only that feature is calculated. If list of feature names, all the listed features are calculated. Default is `"all"`. new_utility_methods ({None, list}, optional) – A list of new utility methods. All methods in this class that is not in the list of utility methods, is considered to be a feature. Default is None. interpolate ({None, “all”, str, list of feature names}, optional) – Which features are irregular, meaning they have a varying number of time points between evaluations. An interpolation is performed on each irregular feature to create regular results. If `"all"`, all features are interpolated. If None, or an empty list, no features are interpolated. If str, only that feature is interpolated. If list of feature names, all listed features are interpolated. Default is None. threshold ({float, int, “auto”}, optional) – The threshold where the model result is considered to have a spike. If “auto” the threshold is set to the standard variation of the result. Default is -30. end_threshold ({int, float}, optional) – The end threshold for a spike relative to the threshold. Default is -10. extended_spikes (bool, optional) – If the found spikes should be extended further out than the threshold cuttoff. If True the spikes is considered to start and end where the derivative equals 0.5. Default is False. trim (bool, optional) – If the spikes should be trimmed back from the termination threshold, so each spike is equal the threshold at both ends. Default is True. normalize (bool, optional) – If the voltage traceshould be normalized before the spikes are found. If normalize is used threshold must be between [0, 1], and the end_threshold a similar relative value. Default is False. min_amplitude ({int, float}, optional) – Minimum height for what should be considered a spike. Default is 0. min_duration ({int, float}, optional) – Minimum duration for what should be considered a spike. Default is 0. labels (dictionary, optional) – A dictionary with key as the feature name and the value as a list of labels for each axis. The number of elements in the list corresponds to the dimension of the feature. Example: new_labels = {"0d_feature": ["x-axis"], "1d_feature": ["x-axis", "y-axis"], "2d_feature": ["x-axis", "y-axis", "z-axis"] } strict (bool, optional) – If True, missing `"stimulus_start"` and `"stimulus_end"` from info raises a ValueError. If False the simulation start time is used as `"stimulus_start"` and the simulation end time is used for `"stimulus_end"`. Default is True. logger_level ({“info”, “debug”, “warning”, “error”, “critical”, None}, optional) – Set the threshold for the logging level. Logging messages less severe than this level is ignored. If None, no logging is performed. Default logger level is “info”.
Variables:	spikes (Spikes) – A Spikes object that contain all spikes. threshold ({float, int}) – The threshold where the model result is considered to have a spike. end_threshold ({int, float}) – The end threshold for a spike relative to the threshold. extended_spikes (bool) – If the found spikes should be extended further out than the threshold cuttoff. trim (bool) – If the spikes should be trimmed back from the termination threshold, so each spike is equal the threshold at both ends. normalize (bool) – If the voltage traceshould be normalized before the spikes are found. If normalize is used threshold must be between [0, 1], and the end_threshold a similar relative value. min_amplitude ({int, float}) – Minimum height for what should be considered a spike. min_duration ({int, float}) – Minimum duration for what should be considered a spike. features_to_run (list) – Which features to calculate uncertainties for. interpolate (list) – A list of irregular features to be interpolated. utility_methods (list) – A list of all utility methods implemented. All methods in this class that is not in the list of utility methods is considered to be a feature. labels (dictionary) – Labels for the axes of each feature, used when plotting. strict (bool) – If missing info values should raise an error.
Raises:	`ImportError` – If scipy is not installed.

Notes

The implemented features are:

nr_spikes	time_before_first_spike
spike_rate	average_AP_overshoot
average_AHP_depth	average_AP_width
accommodation_index	average_duration

Most of the feature are from: Druckmann, S., Banitt, Y., Gidon, A. A., Schurmann, F., Markram, H., and Segev, I. (2007). A novel multiple objective optimization framework for constraining conductance- based neuron models by experimental data. Frontiers in Neuroscience 1, 7-18. doi:10. 3389/neuro.01.1.1.001.2007

See also

uncertainpy.features.Features.reference_feature: reference_feature showing the requirements of a feature function.
uncertainpy.features.Spikes: Class for finding spikes in the model result.

accommodation_index(time, spikes, info)[source]¶

The accommodation index.

The accommodation index is the average of the difference in length of two consecutive interspike intervals normalized by the summed duration of the two interspike intervals.

Parameters:

time ({None, numpy.nan, array_like}) – Time values of the model. If no time values it is None or numpy.nan.
spikes (Spikes) – Spikes found in the model result.
info (dictionary) – Not used in this feature.

Returns:

time (None)
accommodation_index ({float, None}) – The accommodation index. Returns None if there are less than two spikes in the model result.

Notes

The accommodation index is defined as:

\[A = \frac{1}{N-k-1} \sum_{i=k}^N \frac{\text{ISI}_i - \text{ISI}_{i-1}}{\text{ISI}_i + \text{ISI}_{i-1}},\]

where ISI is the interspike interval, N the number of spikes, and k is defined as:

\[k = \min \left\{4, \frac{\text{Number of ISIs}}{5}\right\}.\]

add_features(new_features, labels={})¶

Add new features.

Parameters:

new_features ({callable, list of callables}) – The new features to add. The feature functions have the requirements stated in reference_feature.
labels (dictionary, optional) – A dictionary with the labels for the new features. The keys are the feature function names and the values are a list of labels for each axis. The number of elements in the list corresponds to the dimension of the feature. Example:
```
new_labels = {"0d_feature": ["x-axis"],
              "1d_feature": ["x-axis", "y-axis"],
              "2d_feature": ["x-axis", "y-axis", "z-axis"]
             }
```

Raises:

TypeError – Raises a TypeError if new_features is not callable or list of callables.

Notes

The features added are not added to features_to_run. features_to_run must be set manually afterwards.

See also

uncertainpy.features.Features.reference_feature(): reference_feature showing the requirements of a feature function.

average_AHP_depth(time, spikes, info)[source]¶

The average action potential depth.

The minimum of the model result between two consecutive spikes (action potentials).

Parameters:

time ({None, numpy.nan, array_like}) – Time values of the model. If no time values it is None or numpy.nan.
spikes (Spikes) – Spikes found in the model result.
info (dictionary) – Not used in this feature.

Returns:

time (None)
average_AHP_depth ({float, None}) – The average action potential depth. Returns None if there are no spikes in the model result.

average_AP_overshoot(time, spikes, info)[source]¶

The average action potential overshoot,

The average of the absolute peak voltage values of all spikes (action potentials).

Parameters:

time ({None, numpy.nan, array_like}) – Time values of the model. If no time values it is None or numpy.nan.
spikes (Spikes) – Spikes found in the model result.
info (dictionary) – Not used in this feature.

Returns:

time (None)
average_AP_overshoot ({float, None}) – The average action potential overshoot. Returns None if there are no spikes in the model result.

average_AP_width(time, spikes, info)[source]¶

The average action potential width.

The average of the width of every spike (action potential) at the midpoint between the start and maximum of each spike.

Parameters:

time ({None, numpy.nan, array_like}) – Time values of the model. If no time values it is None or numpy.nan.
spikes (Spikes) – Spikes found in the model result.
info (dictionary) – Not used in this feature.

Returns:

time (None)
average_AP_width ({float, None}) – The average action potential width. Returns None if there are no spikes in the model result.

average_duration(time, spikes, info)[source]¶

The average duration of an action potential, from the action potential onset to action potential termination.

Parameters:

time ({None, numpy.nan, array_like}) – Time values of the model. If no time values it is None or numpy.nan.
spikes (Spikes) – Spikes found in the model result.
info (dictionary) – Not used in this feature.

Returns:

time (None)
average_AP_width ({float, None}) – The average action potential width. Returns None if there are no spikes in the model result.

calculate_all_features(*model_results)¶

Calculate all implemented features.

Parameters:	*model_results – Variable length argument list. Is the values that `model.run()` returns. By default it contains time and values, and then any number of optional info values.
Returns:	results – A dictionary where the keys are the feature names and the values are a dictionary with the time values time and feature results on values, on the form `{"time": t, "values": U}`.
Return type:	dictionary
Raises:	`TypeError` – If feature_name is a utility method.

Notes

Checks that the feature returns two values.

See also

uncertainpy.features.Features.calculate_feature(): Method for calculating a single feature.

calculate_feature(feature_name, *preprocess_results)¶

Calculate feature with feature_name.

Parameters:

feature_name (str) – Name of feature to calculate.
*preprocess_results – The values returned by preprocess. These values are sent as input arguments to each feature. By default preprocess returns the values that model.run() returns, which contains time and values, and then any number of optional info values. The implemented features require that info is a single dictionary with the information stored as key-value pairs. Certain features require specific keys to be present.

Returns:

time ({None, numpy.nan, array_like}) – Time values, or equivalent, of the feature, if no time values returns None or numpy.nan.
values (array_like) – The feature results, values must either be regular (have the same number of points for different paramaters) or be able to be interpolated.

Raises:

TypeError – If feature_name is a utility method.

See also

uncertainpy.models.Model.run(): The model run method

calculate_features(*model_results)¶

Calculate all features in features_to_run.

Parameters:	*model_results – Variable length argument list. Is the values that `model.run()` returns. By default it contains time and values, and then any number of optional info values.
Returns:	results – A dictionary where the keys are the feature names and the values are a dictionary with the time values time and feature results on values, on the form `{"time": time, "values": values}`.
Return type:	dictionary
Raises:	`TypeError` – If feature_name is a utility method.

Notes

Checks that the feature returns two values.

See also

uncertainpy.features.Features.calculate_feature(): Method for calculating a single feature.

calculate_spikes(time, values, threshold=-30, end_threshold=-10, extended_spikes=False, trim=True, normalize=False, min_amplitude=0, min_duration=0)¶

Calculating spikes of a model result, works with single neuron models and voltage traces.

Parameters:

time ({None, numpy.nan, array_like}) – Time values of the model. If no time values it is None or numpy.nan.
values (array_like) – Result of the model.
threshold ({float, int, “auto”}, optional) – The threshold where the model result is considered to have a spike. If “auto” the threshold is set to the standard variation of the result. Default is -30.
end_threshold ({int, float}, optional) – The end threshold for a spike relative to the threshold. Default is -10.
extended_spikes (bool, optional) – If the found spikes should be extended further out than the threshold cuttoff. If True the spikes is considered to start and end where the derivative equals 0.5. Default is False.
trim (bool, optional) – If the spikes should be trimmed back from the termination threshold, so each spike is equal the threshold at both ends. Default is True.
normalize (bool, optional) – If the voltage traceshould be normalized before the spikes are found. If normalize is used threshold must be between [0, 1], and the end_threshold a similar relative value. Default is False.
min_amplitude ({int, float}, optional) – Minimum height for what should be considered a spike. Default is 0.
min_duration ({int, float}, optional) – Minimum duration for what should be considered a spike. Default is 0.

Returns:

time ({None, numpy.nan, array_like}) – Time values of the model. If no time values it returns None or numpy.nan.
values (Spikes) – The spikes found in the model results.

See also

uncertainpy.features.Features.reference_feature(): reference_feature showing the requirements of a feature function.
uncertainpy.features.Spikes(): Class for finding spikes in the model result.

features_to_run¶

Which features to calculate uncertainties for.

Parameters:	new_features_to_run ({“all”, None, str, list of feature names}) – Which features to calculate uncertainties for. If `"all"`, the uncertainties are calculated for all implemented and assigned features. If None, or an empty list , no features are calculated. If str, only that feature is calculated. If list of feature names, all listed features are calculated. Default is `"all"`.
Returns:	A list of features to calculate uncertainties for.
Return type:	list

implemented_features()¶

Return a list of all callable methods in feature, that are not utility methods, does not starts with “_” and not a method of a general python object.

Returns:	A list of all callable methods in feature, that are not utility methods.
Return type:	list

interpolate¶

Features that require an interpolation.

Which features are interpolated, meaning they have a varying number of time points between evaluations. An interpolation is performed on each interpolated feature to create regular results.

Parameters:	new_interpolate ({None, “all”, str, list of feature names}) – If `"all"`, all features are interpolated. If None, or an empty list, no features are interpolated. If str, only that feature is interpolated. If list of feature names, all listed features are interpolated. Default is None.
Returns:	A list of irregular features to be interpolated.
Return type:	list

labels¶

Labels for the axes of each feature, used when plotting.

Parameters:	new_labels (dictionary) – A dictionary with key as the feature name and the value as a list of labels for each axis. The number of elements in the list corresponds to the dimension of the feature. Example: new_labels = {"0d_feature": ["x-axis"], "1d_feature": ["x-axis", "y-axis"], "2d_feature": ["x-axis", "y-axis", "z-axis"] }

nr_spikes(time, spikes, info)[source]¶

The number of spikes in the model result during the stimulus period.

Parameters:

time ({None, numpy.nan, array_like}) – Time values of the model. If no time values it is None or numpy.nan.
spikes (Spikes) – Spikes found in the model result.
info (dictionary) – If strict=True, requires info["stimulus_start"] and info['stimulus_end'] set.

Returns:

time (None)
nr_spikes (int) – The number of spikes in the model result.

Raises:

ValueError – If strict is True and "stimulus_start" and "stimulus_end" are missing from info.
ValueError – If stimulus_start >= stimulus_end.

preprocess(time, values, info)¶

Calculating spikes from the model result.

Parameters:

time ({None, numpy.nan, array_like}) – Time values of the model. If no time values it is None or numpy.nan.
values (array_like) – Result of the model.
info (dictionary) – A dictionary with info[“stimulus_start”] and info[“stimulus_end”].

Returns:

time ({None, numpy.nan, array_like}) – Time values of the model. If no time values it returns None or numpy.nan.
values (Spikes) – The spikes found in the model results.
info (dictionary) – A dictionary with info[“stimulus_start”] and info[“stimulus_end”].

Notes

Also sets self.values = values, so features have access to self.values if necessary.

See also

uncertainpy.models.Model.run(): The model run method
uncertainpy.features.Spikes(): Class for finding spikes in the model result.

reference_feature(time, spikes, info)¶

An example of an GeneralSpikingFeature. The feature functions have the following requirements, and the input arguments must either be returned by Model.run or SpikingFeatures.preprocess.

Parameters:

time ({None, numpy.nan, array_like}) – Time values of the model. If no time values it is None or numpy.nan.
spikes (Spikes) – Spikes found in the model result.
info (dictionary) – A dictionary with info[“stimulus_start”] and info[“stimulus_end”] set.

Returns:

time ({None, numpy.nan, array_like}) – Time values, or equivalent, of the feature, if no time values return None or numpy.nan.
values (array_like) – The feature results, values. Returns None if there are no feature results and that evaluation are disregarded.

See also

uncertainpy.features.GeneralSpikingFeatures.preprocess(): The GeneralSpikingFeatures preprocess method.
uncertainpy.models.Model.run(): The model run method

spike_rate(time, spikes, info)[source]¶

The spike rate of the model result.

Number of spikes divided by the duration.

Parameters:

time ({None, numpy.nan, array_like}) – Time values of the model. If no time values it is None or numpy.nan.
spikes (Spikes) – Spikes found in the model result.
info (dictionary) – If strict=True, requires info["stimulus_start"] and info['stimulus_end'] set.

Returns:

time (None)
spike_rate (float) – The spike rate of the model result.

Raises:

ValueError – If strict is True and "stimulus_start" and "stimulus_end" are missing from info.
ValueError – If stimulus_start >= stimulus_end.

time_before_first_spike(time, spikes, info)[source]¶

The time from the stimulus start to the first spike occurs.

Parameters:

time ({None, numpy.nan, array_like}) – Time values of the model. If no time values it is None or numpy.nan.
spikes (Spikes) – Spikes found in the model result.
info (dictionary) – If strict=True, requires info["stimulus_start"] set.

Returns:

time (None)
time_before_first_spike ({float, None}) – The time from the stimulus start to the first spike occurs. Returns None if there are no spikes on the model result.

Raises:

ValueError – If strict is True and "stimulus_start" and "stimulus_end" are missing from info.

validate(feature_name, *feature_result)¶

Validate the results from calculate_feature.

This method ensures each returns time, values.

Parameters:	model_results – Any type of model results returned by `run`. feature_name (str) – Name of the feature, to create better error messages.
Raises:	`ValueError` – If the model result does not fit the requirements. `TypeError` – If the model result does not fit the requirements.

Notes

Tries to verify that at least, time and values are returned from run. model_result should follow the format: return time, values, info_1, info_2, .... Where:

time_feature : {None, numpy.nan, array_like}

Time values, or equivalent, of the feature, if no time values return None or numpy.nan.
values : {None, numpy.nan, array_like}

The feature results, values must either be regular (have the same number of points for different paramaters) or be able to be interpolated. If there are no feature results return None or numpy.nan instead of values and that evaluation are disregarded.