yupi.stats

This module contains a set of functions for statistical information extraction from a trajectory collection.

All the resources of this module should be imported directly from yupi.stats.

class KurtosisStat(trajs)

Estimate kurtosis as a function of time of the list of Trajectory objects, trajs. The average is perform over the ensemble of realizations.

Parameters:

trajs (list[Trajectory]) – Input list of trajectories.

property kurtosis: ndarray

Kurtosis at every time instant.

plot(show_ref=True, ax=None, show=True, ref_color='#a6ec98', **kwargs)

Plot kurtosis.

Parameters:

• show_ref (bool, optional) – If True, the reference value is shown. By default True.

• ax (Axes, optional) – Axes to plot on. If None, a new figure and axes are created.

• show (bool, optional) – If True, the plot is shown. By default True.

• ref_color (Any, optional) – Color of the fill between the upper and lower bound. By default LIGHT_GREEN.

• kwargs (Any)

Returns:

Axes of the plot.

Return type:

Axes

class KurtosisTimeAvgStat(trajs, lag)

Estimate the kurtosis for every Trajectory object stored in trajs.

Parameters:

• trajs (list[Trajectory]) – Input list of trajectories.

• lag (int) – Number of steps that multiplied by dt defines the lag time.

property kurtosis: ndarray

Array of kurtosis with shape (lag, N), where N is the number of trajectories.

property kurtosis_mean: ndarray

Overall mean of the kurtosis

property kurtosis_std: ndarray

Overall standard deviation of the kurtosis

class MsdStat(trajs)

Compute the square displacements for every Trajectory object stored in trajs as the square of the current position vector that has been subtracted the initial position.

Trajectories should have the same length.

Parameters:

trajs (list[Trajectory]) – Input list of trajectories.

property msd: ndarray

Calculate the mean square displacement for each trajectory.

Returns:

Array of mean square displacements with shape (lag, N), where N the number of trajectories.

Return type:

np.ndarray

property msd_mean: ndarray

Overall mean square displacement.

property msd_std: ndarray

Overall standard deviation of the mean square displacement.

class MsdTimeAvgStat(trajs, lag)

Estimate the mean square displacement for every Trajectory object stored in trajs as the average of the square of dispacement vectors as a function of the lag time.

This is a convenience estimator specially when trajectories do not have equal lengths.

Parameters:

• trajs (list[Trajectory]) – Input list of trajectories.

• lag (int) – Number of steps that multiplied by dt defines the lag time.

property msd: ndarray

Calculate the mean square displacement for each trajectory.

Returns:

Array of mean square displacements with shape (lag, N), where N the number of trajectories.

Return type:

np.ndarray

property msd_mean: ndarray

Overall mean square displacement.

property msd_std: ndarray

Overall standard deviation of the mean square displacement.

plot(fill_color='#f7c790', ax=None, show=True, **kwargs)

Plot the mean square displacement.

Parameters:

• fill_color (Any, optional) – Color of the fill between the mean and standard deviation. Default is LIGHT_ORANGE.

• ax (Axes, optional) – Axes to plot on. If None, a new figure and axes are created.

• show (bool, optional) – Whether to show the plot or not. Default is True.

• kwargs (Any)

Return type:

Axes

class PsdStat(trajs, lag, omega=False)

Estimate the power spectral density of a list of Trajectory object as the Fourier transform of its velocity autocorrelation function.

Parameters:

• trajs (list[Trajectory]) – Input list of trajectories.

• lag (int) – Number of steps that multiplied by dt defines the lag time.

• omega (bool) – If True, return the angular frequency instead of the frequency.

property psd: ndarray

Array of power spectral density with shape (lag, N), where N is the number of trajectories.

property psd_mean: ndarray

Overall mean of the power spectral density

property psd_std: ndarray

Overall standard deviation of the power spectral density

property frecuency: ndarray

Frequency vector of the power spectral density.

plot(show=True, ax=None, **kwargs)

Plot the Power Spectral Density.

Parameters:

• show (bool, optional) – If True, the plot is shown. By default True.

• ax (Axes | None)

• kwargs (Any)

Returns:

Axes of the plot.

Return type:

Axes

class SpeedStat(trajs, step=1)

Estimate speeds of the list of trajectories, trajs, by computing displacements according to a certain sample frequency given by step.

Parameters:

• trajs (list[Trajectory]) – Input list of trajectories.

• step (int) – Numer of sample points.

property speeds: ndarray

Get the speeds of the trajectories.

Returns:

Concatenated array of speeds.

Return type:

np.ndarray

plot(bins=None, show=True, ax=None, **kwargs)

Plot a histogram of the array of velocities v.

Parameters:

• v (np.ndarray) – Velocity array.

• show (bool, optional) – If True, the plot is shown. By default True.

• units (string, optional) – Velocity units. By default ‘m/s’.

• bins (int | None)

• ax (Axes | None)

• kwargs (Any)

Returns:

Axes of the plot.

Return type:

Axes

class TurningAngleStat(trajs, accumulate=False, degrees=False, centered=False, wrap=True)

Estimate all the turning angles that forms a set of trajectories.

Parameters:

• trajs (list[Trajectory]) – Input list of trajectories.

• accumulate (bool, optional) – If True, turning angles are measured with respect to an axis define by the initial velocity (i.e., angles between initial and current velocity). Otherwise, relative turning angles are computed (i.e., angles between succesive velocity vectors). By default False.

• degrees (bool, optional) – If True, angles are given in degrees. Otherwise, the units are radians. By default False.

• centered (bool, optional) – If True, angles are wrapped on the interval [-pi, pi]. Otherwise, the interval [0, 2*pi] is chosen. By default False.

• wrap (bool, optional) – If True, angles are wrapped in a certain interval (depending on centered param). By default True.

theta

Concatenated array of turning angles for a list of Trajectory objects.

Type:

np.ndarray

property theta: ndarray

Get the turning angles of the trajectories.

Returns:

List of turning angles for each trajectory.

Return type:

list[list[float]]

plot(bins=36, show=True, ax=None, **kwargs)

Plot a histogram of the array of angles ang.

Parameters:

• ang (np.ndarray) – Array of angles.

• bins (int) – Number of histogram bins.

• show (bool, optional) – If True, the plot is shown. By default True.

• ax (Axes, optional) – Axes to plot. By default None.

• kwargs (Any)

Returns:

Axes of the plot.

Return type:

PolarAxes

Raises:

ValueError – If the axes is not polar.

class VacfStat(trajs)

Compute the pair-wise dot product between initial and current velocity vectors for every Trajectory object stored in trajs.

Parameters:

trajs (list[Trajectory]) – Input list of trajectories.

property vacf: ndarray

Array of velocity dot products with shape (n, N), where n is the total number of time steps and N the number of trajectories.

property vacf_mean: ndarray

Overall mean of the velocity autocorrelation function

property vacf_std: ndarray

Overall standard deviation of the velocity autocorrelation function

class VacfTimeAvgStat(trajs, lag)

Estimate the velocity autocorrelation function for every Trajectory object stored in trajs as the average of the dot product between velocity vectors that are distant a certain lag time.

This is a convenience estimator specially when trajectories do not have equal lengths.

Parameters:

• trajs (list[Trajectory]) – Input list of trajectories.

• lag (int) – Number of steps that multiplied by dt defines the lag time.

property vacf: ndarray

Array of velocity autocorrelation function with shape (lag, N), where N is the number of trajectories.

property vacf_mean: ndarray

Overall mean of the velocity autocorrelation function

property vacf_std: ndarray

Overall standard deviation of the velocity autocorrelation function

plot(log_inset=True, ax=None, show=True, **kwargs)

Plot Velocity Autocorrelation Function.

Parameters:

• log_inset (bool, optional) – If True, a log-log inset is shown. By default True.

• ax (Axes, optional) – Axes to plot on. By default None.

• show (bool, optional) – If True, the plot is shown. By default True.

• kwargs (Any)

Returns:

Axes of the plot.

Return type:

Axes

collect(trajs, lag=None, concat=True, warnings=True, velocity=False, func=None, at=None)

Collect general function.

It can collect the data of each trajectory lagged by a given step or time (step if lag is int, time if lag is float). It can also collect the data of each trajectory at a given step or time (step if at is int, time if at is float). Both lag and at parameters can not be used at the same time.

Parameters:

• trajs (list[Trajectory]) – Group of trajectories.

• lag (int | float | None) – If int, the number of samples to lag. If float, the time to lag.

• concat (bool, optional) – If true each trajectory stracted data will be concatenated in a single array, by default True.

• warnings (bool, optional) – If true, warnings will be printed if a trajectory is shorter than the lag, by default True.

• velocity (bool, optional) – If true, the velocity will be returned (calculated using the lag if given), by default False.

• func (Callable[[Vector], Vector] | None) – Function to apply to each resulting vector, by default None.

• at (int | float | None) – If int, the index of the collected vector in the trajectory. If float, it is taken as time and the index is calculated using the trajectory’s dt.

Returns:

Collected data.

Return type:

np.ndarray

Raises:

ValueError – If lag and at are given at the same time.

collect_at_step(trajs, step, warnings=True, velocity=False, func=None)

Collects the positional data (or velocity) of each trajectory at a given step.

Parameters:

• trajs (list[Trajectory]) – List of trajectories.

• step (int) – Index of the collected vector of each trajectory.

• warnings (bool) – If True, warns if the trajectory is shorter than the step, by default True.

• velocity (bool) – If True, the velocity of the trajectory is used, by default False.

• func (Callable[[Vector], Vector] | None) – Function to apply to the collected vector of each trajectory. By default, the identity function.

Returns:

Array of collected data.

Return type:

np.ndarray

See also

collect_at_time, collect_step_lagged, collect_time_lagged, collect

collect_at_time(trajs, time, warnings=True, velocity=False, func=None)

Collects the positional data (or velocity) of each trajectory at a given time.

Parameters:

• trajs (list[Trajectory]) – List of trajectories.

• time (float) –

  Time of the collected vector of each trajectory.

  It is calculated using the trajectory’s dt.

• warnings (bool) – If True, warns if the trajectory is shorter than the time, by default True.

• velocity (bool) – If True, the velocity of the trajectory is used, by default False.

• func (Callable[[Vector], Vector] | None) – Function to apply to the collected vector of each trajectory. By default, the identity function.

Returns:

Array of collected data.

Return type:

np.ndarray

See also

collect_at_step, collect_step_lagged, collect_time_lagged, collect

collect_step_lagged(trajs, step, warnings=True, velocity=False, concat=True, func=None)

Collects the positional data (or velocity) of each trajectory lagged by a given step.

Parameters:

• trajs (list[Trajectory]) – List of trajectories.

• step (int) – Number of steps to lag.

• warnings (bool) – If True, warns if the trajectory is shorter than the step, by default True.

• velocity (bool) – If True, the velocity of the trajectory is used, by default False.

• concat (bool) – If True, the data is concatenated, by default True.

• func (Callable[[Vector], Vector] | None) – Function to apply to the collected vector of each trajectory. By default, the identity function.

Returns:

Array of collected data.

Return type:

np.ndarray

See also

collect_at_step, collect_at_step, collect_time_lagged, collect

collect_time_lagged(trajs, time, warnings=True, velocity=False, concat=True, func=None)

Collects the positional data (or velocity) of each trajectory lagged by a given time.

Parameters:

• trajs (list[Trajectory]) – List of trajectories.

• time (float) – Time to lag.

• warnings (bool) – If True, warns if the trajectory is shorter than the step, by default True.

• velocity (bool) – If True, the velocity of the trajectory is used, by default False.

• concat (bool) – If True, the data is concatenated, by default True.

• func (Callable[[Vector], Vector] | None) – Function to apply to the collected vector of each trajectory. By default, the identity function.

Returns:

Array of collected data.

Return type:

np.ndarray

See also

collect_at_step, collect_at_time, collect_step_lagged, collect

kurtosis_reference(trajs)

Get the sampled kurtosis for the case of len(trajs) trajectories whose position vectors are normally distributed.

Parameters:

trajs (list[Trajectory]) – Input trajectories.

Returns:

Value of kurtosis.

Return type:

float

turning_angles(traj, accumulate=False, degrees=False, centered=False, wrap=True)

Return the sequence of turning angles that forms the trajectory.

Parameters:

• traj (Trajectory) – Input trajectory.

• accumulate (bool, optional) – If True, turning angles are measured with respect to an axis defined by the initial velocity (i.e., angles between initial and current velocity). Otherwise, relative turning angles are computed (i.e., angles between succesive velocity vectors). By default False.

• degrees (bool, optional) – If True, angles are given in degrees. Otherwise, the units are radians. By default False.

• centered (bool, optional) – If True, angles are wrapped on the interval [-pi, pi]. Otherwise, the interval [0, 2*pi] is chosen. By default False.

• wrap (bool, optional) – If True, angles are wrapped in a certain interval (depending on centered param). By default True.

Returns:

Turning angles where each position in the array correspond to a given time instant.

Return type:

np.ndarray