Module Documentation

Documentation for every module and function found in TrajPy.

TrajPy

class trajpy.trajpy.Trajectory(trajectory: ndarray = array([[0., 0.]]), box_length: int = None, **params)

Bases: object

This is the main class object in trajpy. It can be initialized as a dummy object for calling its functions or you can initialize it with a trajectory array or csv file.

__init__(trajectory: ndarray = array([[0., 0.]]), box_length: int = None, **params) → None

Initialization function that can be left blank for using staticmethods. It can be initialized with an array with shape (N, dim) where dim is the number of spatial dimensions plus the time component. The first column must be the time, followed by the x- and y-axis. It also accepts tuples (t, x, y) or csv files.

The trajectory will be split between the temporal component self._t and the spatial axis self._r.

Parameters:

• trajectory – 2D trajectory as a function of time (t, x, y)

• params – use params for passing parameters into np.genfromtxt()

static anisotropy_(eigenvalues: ndarray) → float

Calculates the trajectory anisotropy using the eigenvalues of the gyration radius tensor.

\[a^2 = 1 - 3 \frac{\lambda_1\lambda_2 + \lambda_2 \lambda_3 + \lambda_3\lambda_1 }{(\lambda_1+\lambda_2+\lambda_3)^2}\]

static anomalous_exponent_(msd: ndarray, time_lag: ndarray) → float

Calculates the diffusion anomalous exponent

\[\beta = \frac{ \partial \log{ \left( \langle x^2 \rangle \right)} }{ \partial (\log{(t)}) }\]

Parameters:

• msd – mean square displacement

• time_lag – time interval

Returns:

diffusion nomalous exponent

static asymmetry_(eigenvalues: ndarray) → float

Takes the eigenvalues of the gyration radius tensor to estimate the asymmetry between axis.

\[a = - \log{ \left(1 - \frac{ ( \lambda_1 - \lambda_2)^2}{2 ( \lambda_1 + \lambda_2)^2} \right)}\]

Parameters:

eigenvalues – eigenvalues of the gyration radius tensor

Returns:

asymmetry coefficient

compute_features() → str

Compute every feature for the trajectory saved in self._r.

Return features:

return the values of the features as a string.

static confinement_probability_(r0: int, D: float, t: float, N: int = 100) → float

new Estimate the probability of Brownian particle with diffusivity \(D\) being trapped in the interval \([-r0, +r0]\) after a period of time t.

\[P(r, D, t) = \int_{-r_0}^{r_0} p(r, D, t) \mathrm{d}r\]

Parameters:

• r – position

• D – diffusivity

• t – time length

Return probability:

probability of the particle being confined

static efficiency_(trajectory: ndarray) → float

Calculates the efficiency of the movement, a measure that is related to the straightness.

\[E = \frac{|\mathbf{x}_{N-1} - \mathbf{x}_{0}|^2 } { (N-1) \sum_{i=1}^{N-1} |\mathbf{x}_{i} - \mathbf{x}_{i-1}|^2 }\]

Return efficiency:

trajectory efficiency.

static fractal_dimension_(trajectory: ndarray) → Tuple[float, float]

Estimates the fractal dimension of the trajectory

\[\frac{\log{(N)} }{ \log{(dNL^{-1})}}\]

Return fractal_dimension:

returns the fractal dimension

static frequency_spectrum_(position: ndarray, time: ndarray) → Dict[str, ndarray | float]

Computes the frequency spectrum for each spatial coordinate by using the Fast Fourier Transform algorithm param position: spatial coordinates param time: time return frequency_spectrum: returns a dictionary containing the dominant amplitude and the associated frequency along with the frequency spectrum and their amplituded

static gaussianity_(trajectory: ndarray) → float

measure of how close to a gaussian distribution is the trajectory.

\[g(n) = \frac{ \langle r_n^4 \rangle }{2 \langle r_n^2 \rangle^2}\]

Return gaussianity:

measure of similarity to a gaussian function

static green_kubo_(velocity: ndarray, t: ndarray, vacf: ndarray) → float

Computes the generalised Green-Kubo’s diffusion constant :return diffusivity: diffusion constant obtained by the Green-Kubo relation

static gyration_radius_(trajectory: ndarray) → Dict[str, ndarray | float]

Calculates the gyration radius tensor of the trajectory

\[R_{mn} = \frac{1}{2N^2} \sum_{i=1}^N \sum_{j=1}^N \left( r_{m}^{(i)} - r_{m}^{(j)} \right)\left( r_{n}^{(i)} - r_{n}^{(j)} \right)\, ,\]

where \(N\) is the number of segments of the trajectory, \(\mathbf{r}_i\) is the \(i\)-th position vector along the trajectory, \(m\) and \(n\) assume the values of the corresponding coordinates along the directions \(x, y, z\).

Return gyration_radius:

gyration_radius dictionary containing the tensor, eigenvalues in descending order

and the corresponding eigenvectors by column

static kurtosis_(trajectory: ndarray, eigenvector: ndarray) → float

We obtain the kurtosis by projecting each position of the trajectory along the main principal eigenvector of the radius of gyration tensor

\(r_i^p = \mathbf{r} \cdot \hat{e}_1\) and then calculating the quartic moment

\[K = \frac{1}{N} \sum_{i=1}^N \frac{ \left(r_i^p - \langle r^p \rangle \right)^4}{\sigma_{r^p}^4} \, ,\]

where \(\langle r^p \rangle\) is the mean position of the projected trajectory and \(\sigma_{r^p}^2\) is the variance. The kurtosis measures the peakiness of the distribution of points in the trajectory.

Return kurtosis:

K

static msd_ensemble_averaged_(spatial_components: ndarray) → ndarray

calculates the ensemble-averaged mean squared displacement

\[\langle \mathbf{r}^2 \rangle (t) = \frac{1}{N-1} \sum_{n=1}^N |\mathbf{x}_{n}-\mathbf{x}_0|^2\]

where \(N\) is the number of trajectories, \(\mathbf{r}_n(t)\) is the position of the trajectory \(n\) at time \(t\).

Parameters:

spatial_components – array containing trajectory spatial coordinates

Return msd:

ensemble-averaged msd

static msd_ratio_(msd_ta: ndarray, n1: int, n2: int) → float

Ratio of the ensemble averaged mean squared displacements.

\[\langle r^2 \rangle_{\tau_1, \tau_2} = \frac{\langle r^2 \rangle_{\tau_1 }} {\langle r^2 \rangle_{\tau_2 }} - \frac{\tau_1}{\tau_2}\]

with

\[\tau_1 < \tau_2\]

Return msd_ratio:

static msd_time_averaged_(spatial_components: ndarray, tau: ndarray | int) → ndarray

calculates the time-averaged mean squared displacement

\[\langle \mathbf{r}_{\tau}^2 \rangle = \frac{1}{T-\tau} \sum_{t=1}^{N-\tau} |\mathbf{x}_{t+\tau} - \mathbf{x}_{\tau} |^2\]

where \(\tau\) is the time interval (time lag) between the two positions and :math:`T is total trajectory time length.

Parameters:

• spatial_components – array containing trajectory spatial coordinates

• tau – time lag, it can be a single value or an array

Return msd:

time-averaged MSD

static stationary_velocity_correlation_(velocity: ndarray, t: ndarray, taus: ndarray) → ndarray

Computes the stationary velocity autocorrelation function by time average .. math:

langle vec{v(t+tau)} vec{v(t)} rangle

Parameters:

• velocity – velocity array

• t – time array

• taus – single or array of non-negative integer values representing the time lag

Return time_averaged_corr_velocity:

velocity autocorrelation function output

static straightness_(trajectory: ndarray) → float

Estimates how much straight is the trajectory

\[S = \frac{|\mathbf{x}_{N-1} -\mathbf{x}_0 |} { \sum_{i=1}^{N-1} |\mathbf{x}_i - \mathbf{x}_{i-1}|}\]

Return straightness:

measure of linearity

static velocity_(position: ndarray, time: ndarray) → ndarray

Computes the velocity associated with the trajectory

static velocity_description_(velocity: ndarray) → Dict[str, ndarray | float | str]

Computes the main features of the velocity distribuition: mean, median, mode, variance, standard deviation, range, skewness and kurtosis

Parameters:

velocity – velocity array

return velocity_description: returns a dictionary where the values are bounded to a key of the same name

Trajectory Generator

trajpy.traj_generator.anomalous_diffusion(n_steps: int, n_samples: int, time_step: float, alpha: float) → Tuple[ndarray, ndarray]

Generates an ensemble of anomalous trajectories.

Parameters:

• n_steps – total number of steps

• n_samples – number of simulations

• time_step – time step

• alpha – anomalous exponent

Return x, y:

time, array containing N_sample trajectories with Nsteps

trajpy.traj_generator.confined_diffusion(radius: float, n_steps: int, n_samples: int, dx: float, y0: float, D: float, dt: float) → Tuple[ndarray, ndarray]

Generates trajectories under confinement.

Parameters:

• radius – confinement radius

• n_steps – number of displacements

• n_samples – number of trajectories

• dx – displacement

• y0 – initial position

• D – diffusion coefficient

• dt – time step

Return x, y:

time, array containing N_samples trajectories with N_steps

trajpy.traj_generator.normal_diffusion(n_steps: int, n_samples: int, dx: float, y0: float, D: float, dt: float) → Tuple[ndarray, ndarray]

Generates an ensemble of normal diffusion trajectories.

Parameters:

• n_steps – total steps

• n_samples – number of trajectories

• dx – maximum step length

• y0 – starting position

• D – diffusivity

• dt – time step

Return x, y:

time, array containing N_samples trajectories with N_steps

trajpy.traj_generator.normal_distribution(u: float, D: float, dt: float) → float

This is the steplength probability density function for normal diffusion.

Parameters:

• u – absolute distance travelled by the particle durint the time interval dt

• D – diffusivity

• dt – time interval

Return pdf:

probability density function

trajpy.traj_generator.save_to_file(y: ndarray, param: int | float | str, path: str) → None

Saves the trajectories to a file.

Parameters:

• y – trajectory array

• param – a parameter that characterizes the kind of trajectory

• path – path to the folder where the file will be saved

trajpy.traj_generator.superdiffusion(velocity: float, n_steps: int, n_samples: int, y0: float, dt: float) → Tuple[ndarray, ndarray]

Generates direct diffusion trajectories. Combine pairwise with normal diffusion components.

Parameters:

• velocity – constant velocity

• n_steps – number of time steps

• n_samples – number of trajectories

• y0 – initial position

• dt – time interval

Return x, y:

time, array containing N_samples trajectories with N_steps

trajpy.traj_generator.weierstrass_mandelbrot(t: float, n_displacements: int, alpha: float) → float

Calculates the weierstrass mandelbrot function

\[W(t) = \sum_{n=-\infty}^{\infty} \frac{\cos{(\phi_n )} - \cos{(\gamma^n t^* + \phi_n )} }{\gamma^{n\alpha/2}} \, .\]

Parameters:

• t – time step

• n_displacements – number of displacements

• alpha – anomalous exponent

Returns:

anomalous step