ivneuro.tracking

A module with functions for processing positions data based on xy coordinates.

Classes

EventPosition

Obtain the position of an event.

Functions

scale_centroids(centroids, x_dim, y_dim)

Scale centroids to match the real values in appropiate scale.

calculate_speed(X_values, Y_values, timestamps[, smooth])

Calculate scalar speed.

position_of_event(x_values, y_values, timestamps, events)

Estimate the most likely position at with an event occurs, or get all the positions where that event occurs.

distances_to_position(x_values, y_values, position)

Given a set of x and y positions, calculate the distance to a specific position at each row.

Module Contents

ivneuro.tracking.scale_centroids(centroids, x_dim, y_dim)

Scale centroids to match the real values in appropiate scale.

This function assumes that positions at lower and higher limits of each dimension have been recorded.

Parameters:

  • centroids (numpy.ndarray of shape (2 x n_timestamps)) – Values of X_centroid and Y_centroid to be scaled.

  • x_dim (float) – Value from end to end of X coordinate.

  • y_dim (float) – Value from end to end of Y coordinate.

Return type:

numpy.ndarray with scaled values.

Examples

Use scale_centroids function.

>>> # Create and array with x and y coordinates: centroids
>>> import ivneuro as ivn
>>> import numpy as np
>>> x = 10 * np.cos(np.linspace(0, 2*np.pi, 100)) + 10
>>> y = 20 * np.sin(np.linspace(0, 2*np.pi, 100)) + 20
>>> centroids = np.concatenate((x.reshape(100,1), y.reshape(100,1)), axis=1).T # Coordinates for an oval trajectory
>>> # Scale using scale_centroids function
>>> scaled_centroids = ivn.scale_centroids(centroids, 15, 30)
Difference between observed and provided x/y ratios: -0.012587232612482069 %
>>> print(scaled_centroids[:,:5]) # Print first 5 values of x and y
array([[15.        , 14.98489627, 14.9396459 , 14.8644311 , 14.75955473],
       [15.        , 15.95147856, 16.89912585, 17.83912603, 18.76769406]])

If ratios between observed and provided x and y values are too different, scale_centroids will through a warning message.

>>> # Scale with inverted x and y measures
>>> scaled_centroids = ivn.scale_centroids(centroids, 30, 15)
Warning: the observed and provided x/y ratios have a difference of above 10%, consider switching the order of X and Y dimensions or cleaning centroids data and scale again
Difference between observed and provided x/y ratios: -75.00314680815312 %
ivneuro.tracking.calculate_speed(X_values, Y_values, timestamps, smooth=0)

Calculate scalar speed.

Speed is calculated through the following steps: 1. Calculate dtime, dX=PosX[T-deltaT]-posX[T] and dY=PosY[T-deltaT]-posY[T]. 2. Smooth dX and dY using a Gaussian filter. Note: by applying the Gaussian filter to dX and dY instead of the speed avoids short movements or random noie of the camera to propagate to the speed calculus, leaving only changes in position caused by displacement. 3. Calculate scalar speed: sqrt(dX**2+dY**2) / dT.

Parameters:

  • X_values (NUMPY ARRAY) – Positions in X coordinate. Must have the same lenght than Y_values and timestamps

  • Y_values (NUMPY ARRAY) – Positions in Y coordinate. Must have the same lenght than X_values and timestamps

  • timestamps (NUMPY ARRAY) – Timestamps for every position. Must have the same lenght than X_values and Y_values

  • smooth (Float, optional) – Defines the window of time a 2 x smooth and the width of the Gaussian kernel as 1 x smooth, for the Gaussian filter. The default is 0, in which case the Gaussian filter is not appplied.

Returns:

speed – Values of scalar speed

Return type:

numpy.ndarray

Examples

Create x coordinates, y coordinates and timestamps. Calculate speed and print it.

>>> import ivneuro as ivn
>>> import numpy as np
>>> x = 10 * np.cos(np.linspace(0, 2*np.pi, 100)) + 10
>>> y = 20 * np.sin(np.linspace(0, 2*np.pi, 100)) + 20
>>> ts = np.linspace(0,20,100).round(1)
# Calculate speed with calculate_speed function and print the first 5 values
>>> speed=ivn.calculate_speed(x, y, ts)
>>> print(speed[:5])
[6.3431908  6.32404896 6.28590074 6.22901826 6.15381269]
ivneuro.tracking.position_of_event(x_values, y_values, timestamps, events, estimator=np.median)

Estimate the most likely position at with an event occurs, or get all the positions where that event occurs.

Parameters:

  • x_values (np.ndarray of shape (1 X n_timestamps)) – All positions in x axis. Must be of the same lenght than y_values and timestamps

  • y_values (np.ndarray of shape (1 X n_timestamps)) – All positions in y axis. Must be of the same lenght than x_values and timestamps

  • timestamps (np.ndarray of shape (1 X n_timestamps)) – All timestamps. Must be of the same lenght than x_values and y_values.

  • events (one dimensional numpy.array or list of floats) – Timestamps of the event.

  • estimator (function, optional) – Function to be used to estimate the most likely position of the event. The default is np.median.

Raises:

  • TypeError – If x_values, y_values or timestamps is not np.ndarray.

  • ValueError – If x_values lenght, y_values lenght and timestamps lenght are not the same.

Returns:

Most likely position (x, y) if estimator is not None, or all the positions of the event (np.array([x])), np.array([y]) if estimator is None.

Return type:

Tuple

Examples

Estimate the position of an event with the median.

>>> # Create x coordinates, y coordinates, centroids timestamps and event.
>>> import ivneuro as ivn
>>> import numpy as np
>>> x = 10 * np.cos(np.linspace(0, 2*np.pi, 100)) + 10
>>> y = 20 * np.sin(np.linspace(0, 2*np.pi, 100)) + 20
>>> ts = np.linspace(0,20,100).round(1)
>>> np.random.seed(24)
>>> event = np.random.choice(ts[(ts>10) & (ts<15)], size=5, replace = False) # Create an event by making a random choice from timestamps
>>> # Estimate the position with position_of_event, return the median
>>> ivn.position_of_event(x, y, ts, event)
(1.7632341857016716, 8.658802722744587)

Return the mean of the positions

>>> ivn.position_of_event(x, y, ts, event, estimator = np.mean)
(3.356415004157808, 7.336570446958302)

Return all the positions for x and y

>>> ivn.position_of_event(x, y, ts, event, estimator = None)
(array([5.        , 0.83891543, 8.57685162, 0.60307379, 1.76323419]),
 array([ 2.67949192, 11.98138929,  0.20357116, 13.15959713,  8.65880272]))
ivneuro.tracking.distances_to_position(x_values, y_values, position)

Given a set of x and y positions, calculate the distance to a specific position at each row.

Parameters:

  • x_values (np.ndarray of shape (1 X n_timestamps)) – X_centroid positions at each timestamp. Must be of the same lenght than y_values and timestamps

  • y_values (np.ndarray of shape (1 X n_timestamps))

  • position (tuple) – Position (x, y) to calculate distance.

Returns:

One dimensional array with distances to position at every point.

Return type:

np.ndarray

Examples

Calculate distances to a position.

>>> # Create x coordinates and y coordinates, create position of interest
>>> import ivneuro as ivn
>>> import numpy as np
>>> x = 10 * np.cos(np.linspace(0, 2*np.pi, 100)) + 10
>>> y = 20 * np.sin(np.linspace(0, 2*np.pi, 100)) + 20
>>> center = (10, 20) # Position of interest
>>> # Calculate distances
>>> distances = ivn.distances_to_position (x, y, center)
>>> print(distances[:5])
[10.         10.06015795 10.23756293 10.523536   10.90516361]
class ivneuro.tracking.EventPosition(x_values, y_values, timestamps, events, estimator=np.median)

Obtain the position of an event.

Parameters:

  • x_values (np.ndarray of shape (1 X n_timestamps)) – All positions in x axis. Must be of the same lenght than y_values and timestamps

  • y_values (np.ndarray of shape (1 X n_timestamps)) – All positions in y axis. Must be of the same lenght than x_values and timestamps

  • timestamps (np.ndarray of shape (1 X n_timestamps)) – All timestamps. Must be of the same lenght than x_values and y_values.

  • events (one dimensional numpy.array or list of floats) – Timestamps of the event.

  • estimator (function, optional) – Function to be used to estimate the most likely position of the event. The default is np.median.

Raises:

  • TypeError – If x_values, y_values or timestamps is not np.ndarray.

  • ValueError – If x_values lenght, y_values lenght and timestamps lenght are not the same.

  • ValueError – If estimator == None.

x_values

All positions in x axis.

Type:

np.ndarray

y_values

All positions in y axis.

Type:

np.ndarray

timestamps

All timestamps

Type:

np.ndarray

events

Timestamps of the event.

Type:

np.ndarray

estimator

The function used to estimate the most likelly position.

Type:

function

estimated_position

Most likely position (x, y).

Type:

tuple

position_std

Standar deviation for the positions of th event (std(x), std(y))

Type:

tuple

distances_to_event()

Calculate the distance to the event estimated position at each timestamp

Returns: np.ndarray

One dimensional array with distances.

set_distances_to_event()

Set distances_to_event attribute using distances_to_event function

Returns:

None

all_event_positions():

Get all the positions at wich the event occurrs.

Returns: tuple

All the positions of the event (np.array([x])), np.array([y]).

get_event_position_std():

Calculate the standar deviation for the event position at x and y axis.

Returns: tuple

Standar deviation in x and y (std(x), std(y))

plot():

plot the all the trajectory, positions where the event occurred and the event estimated position

Returns:

None

x_values
y_values
timestamps
events
estimator
estimated_position
position_std
__str__()
__repr__()
_position_of_event()
distances_to_event()
set_distances_to_event()
all_event_positions()
get_event_position_std()
plot()