Correlation Coefficients

mrestimator.coefficients(data, method=None, steps=None, dt=1, dtunit='ms', knownmean=None, numboot=100, seed=5330, description=None, desc=None)[source]

Calculates the coefficients of correlation \(r_k\).

Parameters:
  • data (ndarray) – Input data, containing the time series of activity in the trial structure. If a one dimensional array is provieded instead, we assume a single trial and reshape the input.
  • method (str) – The estimation method to use, either ‘trialseparated’ ('ts') or ‘stationarymean’ ('sm'). 'ts' calculates the \(r_k\) for each trial separately and averages over trials. The resulting coefficients can be biased if the trials are too short. 'sm' assumes the mean activity and its variance to be constant across all trials. The mean activity is then calculated from the larger pool of data from all trials and the short-trial-bias might be compensated. If you are unsure, compare results from both methods. If they agree, trials should be long enough.
  • steps (array, optional) – Specify the steps \(k\) for which to compute coefficients \(r_k\). If an array of length two is provided, e.g. steps=(minstep, maxstep), all enclosed integer values will be used. Arrays larger than two are assumed to contain a manual choice of steps. Strides other than one are possible.
  • dt (float, optional) – The size of each step in dtunits. Default is 1.
  • dtunit (str, optional) – Units of step size. Default is ‘ms’.
  • description (str, optional) – Set the description of the CoefficientResult. By default all results of functions working with this set inherit its description (e.g. plot legends).
Other Parameters:
 
  • knownmean (float, optional) – If the (stationary) mean activity is known beforehand, it can be provided here. In this case, the provided value is used instead of approximating the expecation value of the activity using the mean.
  • numboot (int, optional) – Enable bootstrapping to generate numboot (resampled) series of trials from the provided one. This allows to approximate statistical errors, returned in stderrs. Default is numboot=100.
  • seed (int, None or ‘random’, optional) – If bootstrapping (numboot>0), a custom seed can be passed to the random number generator used for resampling. Per default, it is set to the same value every time coefficients() is called to return consistent results when repeating the analysis on the same data. Set to None to prevent (re)seeding. ‘random’ seeds using the wall clock time. For more details, see numpy.random.RandomState.
Returns:

CoefficientResult – The output is grouped and can be accessed using its attributes (listed below).
class mrestimator.CoefficientResult[source]

Result returned by coefficients(). Subclassed from namedtuple.

Attributes are set to None if the specified method or input data do not provide them. All attributes of type ndarray and lists are one-dimensional.

Variables:
  • coefficients (ndarray) – Contains the coefficients \(r_k\), has length numsteps. Access via .coefficients[step]
  • steps (ndarray) – Array of the \(k\) values matching coefficients.
  • dt (float) – The size of each step in dtunits. Default is 1.
  • dtunit (str) – Units of step size. Default is ‘ms’.
  • method (str or None) – The method that was used to calculate the coefficients
  • stderrs (ndarray or None) – Standard errors of the \(r_k\).
  • trialactivities (ndarray) – Mean activity of each trial in the provided data. To get the global mean activity, use np.mean(trialactivities). Has lenght numtrials
  • description (str) – Description (or name) of the data set, by default all results of functions working with this set inherit its description (e.g. plot legends).
  • numtrials (int,) – Number of trials that contributed.
  • numboot (int,) – Number of bootstrap replicas that were created.
  • numsteps (int,) – Number of steps in coefficients, steps and stderrs.
  • bootstrapcrs (list) – List containing the numboot CoefficientResult instances that were calculated from the resampled input data. The List is empty if bootstrapping was skipped (numboot=0).
  • trialcrs (list) – List of the CoefficientResult instances calculated from individual trials. Only has length numtrials if the trialseparated method was used, otherwise it is empty.

Note

At the time of writing, ndarray behaves a bit unexpected when creating arrays with objects that are sequence like (such as CoefficientResult and FitResult), even when specifying dtype=object. Numpy converts the objects into an ndimensional structure instead of creating the (probably desired) 1d-array. To work around the issue, use a list or manually create the array with dtype=object and add the entries after creation.

Example

import numpy as np
import matplotlib.pyplot as plt
import mrestimator as mre

# branching process with 15 trials
bp = mre.simulate_branching(m=0.995, a=10, numtrials=15)

# the bp returns data already in the right format
rk = mre.coefficients(bp, method='ts', dtunit='step')

# fit
ft = mre.fit(rk)

# plot coefficients and the autocorrelation fit
mre.OutputHandler([rk, ft])
plt.show()

# print the coefficients
print(rk.coefficients)

# get the documentation
print(help(rk))

# rk is inherited from namedtuple with all the bells and whistles
print(rk._fields)
../_images/example_fitres.png