noctiluca.analysis

noctiluca.analysis.p2

Calculating two-point functions, like MSD & ACF

Note that all of these (MSD, ACF, VACF, …) contain the same information. See also the python package bayesmsd.

noctiluca.analysis.p2.P2traj(traj, TA=True, recalculate=False, function=None, preproc=None, postproc=None, writeto='P2')

Calculate a two-point function for a single trajectory

The results are stored in the traj.meta[writeto]. By default, if this field exists already, the function aborts. To recalculate and overwrite, set recalculate = True.

Parameters:

  • traj (Trajectory) – the trajectory for which to calculate the MSD

  • TA (bool, optional) – whether to time average

  • recalculate (bool) – set to True to ensure that the calculation is actually performed

  • function ({'SD', 'D', 'SP'} or callable) – the function to evaluate. Should be fun(traj[m], traj[n]) --> float, where m >= n, and it should be vectorized (i.e. work on numpy arrays and return the corresponding arrays).

  • preproc (callable or None) – will be applied to the trajectory before processing. Example: lambda traj: traj.diff() gives the increment trajectory

  • postproc (callable or None) – will be applied to the final result, i.e. should take a (T,) array and return such. Relevant when accessing this function through P2dataset, since in that case this postproc is applied _before_ averaging. Use case: normalizing correlation functions

  • writeto (hashable or None) – where to store the output of the calculation in the traj.meta dict. Set to None to return the output dict instead of storing it. Defaults to 'P2'.

Returns:

dict, optional – A dict with keys 'data', 'N' giving the averaged data and the count of valid data points for each lag time. This is usually written into the traj.meta dict, but returned if writeto is None.

See also

P2dataset, MSD

Notes

Explicitly, the recalculate parameter is equivalent to

>>> del traj.meta[writeto]
noctiluca.analysis.p2.P2dataset(dataset, givevar=False, giveN=False, average_in_logspace=False, show_progress=False, **kwargs)

Ensemble average two-point functions

Parameters:

  • dataset (TaggedSet) – a list of Trajectory

  • givevar (bool, optional) – whether to also return the variance around the mean

  • giveN (bool, optional) – whether to return the sample size for each MSD data point

  • average_in_logspace (bool, optional) – set to True to replace the arithmetic with a geometric mean.

  • show_progress (bool, optional) – show a progress bar (tqdm)

  • kwargs (keyword arguments) – are all forwarded to forwarded to P2traj, see that docstring.

Returns:

  • eP2 (np.ndarray) – the calculated ensemble mean

  • var (np.ndarray, optional) – variance around the mean

  • N (np.ndarray, optional) – number of data points going into each estimate

See also

P2traj, MSD, ACF

Notes

This function is parallel-aware (ordered)

noctiluca.analysis.p2.P2(*args, **kwargs)

Shortcut function to calculate P2s.

Will select either P2traj or P2dataset, depending on the type of the first argument. Everything is then forwarded to that function.

This is mostly just a template for the following functions MSD, ACF, …

See also

P2traj, P2dataset

Notes

parallel-aware (ordered)

noctiluca.analysis.p2.SD(xm, xn)
noctiluca.analysis.p2.SP(xm, xn)
noctiluca.analysis.p2.normalize(data)
noctiluca.analysis.p2.diff(traj)
noctiluca.analysis.p2.MSD(*args, **kwargs)

Calculate MSD for a Trajectory or dataset.

This is an implementation of P2. See P2traj and P2dataset for detailed description of parameters, here we will just list the most interesting / relevant ones

Parameters:

  • in (Trajectory or TaggedSet of Trajectory) – the first argument is the input data, either a single Trajectory, or a dataset that will be ensemble averaged over

  • TA (bool, optional) – whether to time average on (each) single trajectory

  • recalculate (bool, optional) – set to True to ensure that the calculation is actually performed. Otherwise, this function might just return precalculated values from traj.meta['MSD'].

  • giveN (bool, optional) – only applicable when in is a dataset. Whether to also return the sample size for each MSD data point.

Returns:

  • msd (np.ndarray) – the calculated MSD. Note that msd[i] = MSD(iΔt), i.e. msd[0] = 0.

  • N (np.ndarray, optional) – the sample size for each point, see giveN.

See also

P2traj, P2dataset

Notes

parallel-aware (ordered)

noctiluca.analysis.p2.ACov(*args, **kwargs)

Calculate autocovariance for a Trajectory or dataset.

This is an implementation of P2. See P2traj and P2dataset for detailed description of parameters, here we will just list the most interesting / relevant ones

Parameters:

  • in (Trajectory or TaggedSet of Trajectory) – the first argument is the input data, either a single Trajectory, or a dataset that will be ensemble averaged over

  • TA (bool, optional) – whether to time average on (each) single trajectory

  • recalculate (bool, optional) – set to True to ensure that the calculation is actually performed. Otherwise, this function might just return precalculated values from traj.meta['ACov'].

  • giveN (bool, optional) – only applicable when in is a dataset. Whether to also return the sample size for each data point.

Returns:

  • acov (np.ndarray) – the calculated autocovariance

  • N (np.ndarray, optional) – the sample size for each point, see giveN

See also

MSD, P2traj, P2dataset

Notes

parallel-aware (ordered)

noctiluca.analysis.p2.ACorr(*args, **kwargs)

Calculate autocorrelation for a Trajectory or dataset.

This is an implementation of P2. See P2traj and P2dataset for detailed description of parameters, here we will just list the most interesting / relevant ones

Parameters:

  • in (Trajectory or TaggedSet of Trajectory) – the first argument is the input data, either a single Trajectory, or a dataset that will be ensemble averaged over

  • TA (bool, optional) – whether to time average on (each) single trajectory

  • recalculate (bool, optional) – set to True to ensure that the calculation is actually performed. Otherwise, this function might just return precalculated values from traj.meta['ACorr'].

  • giveN (bool, optional) – only applicable when in is a dataset. Whether to also return the sample size for each data point.

Returns:

  • acorr (np.ndarray) – the calculated autocorrelation

  • N (np.ndarray, optional) – the sample size for each point, see giveN

See also

MSD, P2traj, P2dataset

Notes

parallel-aware (ordered)

noctiluca.analysis.p2.VACov(*args, **kwargs)

Calculate velocity autocovariance for a Trajectory or dataset.

This is an implementation of P2. See P2traj and P2dataset for detailed description of parameters, here we will just list the most interesting / relevant ones

Parameters:

  • in (Trajectory or TaggedSet of Trajectory) – the first argument is the input data, either a single Trajectory, or a dataset that will be ensemble averaged over

  • TA (bool, optional) – whether to time average on (each) single trajectory

  • recalculate (bool, optional) – set to True to ensure that the calculation is actually performed. Otherwise, this function might just return precalculated values from traj.meta['VACov'].

  • giveN (bool, optional) – only applicable when in is a dataset. Whether to also return the sample size for each data point.

Returns:

  • vacov (np.ndarray) – the calculated velocity autocovariance

  • N (np.ndarray, optional) – the sample size for each point, see giveN

See also

MSD, P2traj, P2dataset

Notes

parallel-aware (ordered)

noctiluca.analysis.p2.VACorr(*args, **kwargs)

Calculate velocity autocorrelation for a Trajectory or dataset.

This is an implementation of P2. See P2traj and P2dataset for detailed description of parameters, here we will just list the most interesting / relevant ones

Parameters:

  • in (Trajectory or TaggedSet of Trajectory) – the first argument is the input data, either a single Trajectory, or a dataset that will be ensemble averaged over

  • TA (bool, optional) – whether to time average on (each) single trajectory

  • recalculate (bool, optional) – set to True to ensure that the calculation is actually performed. Otherwise, this function might just return precalculated values from traj.meta['VACorr'].

  • giveN (bool, optional) – only applicable when in is a dataset. Whether to also return the sample size for each data point.

Returns:

  • vacorr (np.ndarray) – the calculated velocity autocorrelation

  • N (np.ndarray, optional) – the sample size for each point, see giveN

See also

MSD, P2traj, P2dataset

Notes

parallel-aware (ordered)