# utils

## Module: `utils`

Miscellaneous utilities for time series analysis.

## Functions

nitime.utils.adaptive_weights(yk, eigvals, sides='onesided', max_iter=150)

  Perform an iterative procedure to find the optimal weights for K direct spectral estimators of DPSS tapered signals.

  Parameters:

    yk : ndarray (K, N)

    > The K DFTs of the tapered sequences

    eigvals : ndarray, length-K

    > The eigenvalues of the DPSS tapers

    sides : str

    > Whether to compute weights on a one-sided or two-sided spectrum

    max_iter : int

    > Maximum number of iterations for weight computation

  Returns:

    weights, nu :

    > The weights (array like sdfs), and the “equivalent degrees of freedom” (array length-L)

  Notes

  The weights to use for making the multitaper estimate, such that \(S_{mt} = \sum_{k} |w_k|^2S_k^{mt} / \sum_{k} |w_k|^2\)

  If there are less than 3 tapers, then the adaptive weights are not found. The square root of the eigenvalues are returned as weights, and the degrees of freedom are 2*K

nitime.utils.akaike_information_criterion(ecov, p, m, Ntotal, corrected=False)

  A measure of the goodness of fit of an auto-regressive model based on the model order and the error covariance.

  Parameters:

    ecov : float array

    > The error covariance of the system

    p :

    > the number of channels

    m : int

    > the model order

    Ntotal :

    > the number of total time-points (across channels)

    corrected : boolean (optional)

    > Whether to correct for small sample size

  Returns:

    AIC : float

    > The value of the AIC

  Notes

  This is an implementation of equation (50) in Ding et al. (2006):

  M Ding and Y Chen and S Bressler (2006) Granger Causality: Basic Theory and Application to Neuroscience. http://arxiv.org/abs/q-bio/0608035v1

  Correction for small sample size is taken from: http://en.wikipedia.org/wiki/Akaike_information_criterion.

nitime.utils.antisymm_rand_arr(size, sample_func=<bound method RandomState.random of RandomState(MT19937)>)

  Make an anti-symmetric random 2-d array of shape (size,size).

  Parameters:

    n : int

    > Size of the output array.

    sample_func : function, optional.

    > Must be a function which when called with a 2-tuple of ints, returns a 2-d array of that shape. By default, np.random.random is used, but any other sampling function can be used as long as matches this API.

  Examples

      >>> np.random.seed(0)  # for doctesting
      >>> antisymm_rand_arr(4)
      array([[ 0.    ,  0.7152,  0.6028,  0.5449],
             [-0.7152,  0.    ,  0.4376,  0.8918],
             [-0.6028, -0.4376,  0.    ,  0.5289],
             [-0.5449, -0.8918, -0.5289,  0.    ]])

nitime.utils.ar_generator(N=512, sigma=1.0, coefs=None, drop_transients=0, v=None)

  This generates a signal u(n) = a1*u(n-1) + a2*u(n-2) + … + v(n) where v(n) is a stationary stochastic process with zero mean and variance = sigma. XXX: confusing variance notation

  Parameters:

    N : float

    > The number of points in the AR process generated. Default: 512

    sigma : float

    > The variance of the noise in the AR process. Default: 1

    coefs : list or array of floats

    > The AR model coefficients. Default: [2.7607, -3.8106, 2.6535, -0.9238], which is a sequence shown to be well-estimated by an order 8 AR system.

    drop_transients : float

    > How many samples to drop from the beginning of the sequence (the transient phases of the process), so that the process can be considered stationary.

    v : float array

    > Optionally, input a specific sequence of noise samples (this over-rides the sigma parameter). Default: None

  Returns:

    u : ndarray

    > the AR sequence

    v : ndarray

    > the unit-variance innovations sequence

    coefs : ndarray

    > feedback coefficients from k=1,len(coefs)

    The form of the feedback coefficients is a little different than :

    the normal linear constant-coefficient difference equation. Therefore :

    the transfer function implemented in this method is :

    H(z) = sigma**0.5 / ( 1 - sum_k coefs(k)z**(-k) ) 1 <= k <= P :

  Examples

      >>> import nitime.algorithms as alg
      >>> ar_seq, nz, alpha = ar_generator()
      >>> fgrid, hz = alg.freq_response(1.0, a=np.r_[1, -alpha])
      >>> sdf_ar = (hz * hz.conj()).real

nitime.utils.autocorr(x, **kwargs)

  Returns the autocorrelation of signal s at all lags.

  Parameters:

    x : ndarray

    axis : time axis

    all_lags : {True/False}

    > whether to return all nonzero lags, or to clip the length of r_xy to be the length of x and y. If False, then the zero lag correlation is at index 0. Otherwise, it is found at (len(x) + len(y) - 1)/2

  Notes

  Adheres to the definition

  \[\]

  R_{xx}[k]=E{X[n+k]X^{*}[n]}

  where X is a discrete, stationary (ergodic) random process

nitime.utils.autocov(x, **kwargs)

  Returns the autocovariance of signal s at all lags.

  Parameters:

    x : ndarray

    axis : time axis

    all_lags : {True/False}

    > whether to return all nonzero lags, or to clip the length of r_xy to be the length of x and y. If False, then the zero lag correlation is at index 0. Otherwise, it is found at (len(x) + len(y) - 1)/2

  Returns:

    cxx : ndarray

    > The autocovariance function

  Notes

  Adheres to the definition

  \[\]

  C_{xx}[k]=E{(X[n+k]-E{X})(X[n]-E{X})^{*}}

  where X is a discrete, stationary (ergodic) random process

nitime.utils.autocov_vector(x, nlags=None)

  This method computes the following function

  \[\]

  R_{xx}(k) = E{ x(t)x^{*}(t-k) } = E{ x(t+k)x^{*}(t) } k in {0, 1, …, nlags-1}

  (* := conjugate transpose)

  Note: this is related to the other commonly used definition for vector autocovariance

  \[\]

  R_{xx}^{(2)}(k) = E{ x(t-k)x^{*}(t) } = R_{xx}(-k) = R_{xx}^{*}(k)

  Parameters:

    x : ndarray (nc, N)

    nlags : int, optional

    > compute lags for k in {0, …, nlags-1}

  Returns:

    rxx : ndarray (nc, nc, nlags)

nitime.utils.bayesian_information_criterion(ecov, p, m, Ntotal)
  The Bayesian Information Criterion, also known as the Schwarz criterion

    is a measure of goodness of fit of a statistical model, based on the number of model parameters and the likelihood of the model

  Parameters:

    ecov : float array

    > The error covariance of the system

    p : int

    > the system size (how many variables).

    m : int

    > the model order.

    corrected : boolean (optional)

    > Whether to correct for small sample size

  Returns:

    BIC : float

    > The value of the BIC

    a :

    > the resulting autocovariance vector

  Notes

  This is an implementation of equation (51) in Ding et al. (2006):

  \[\]

  BIC(m) = 2 log(|\Sigma|) + frac{2p^2 m log(N_{total})}{N_{total}},

  where $Sigma$ is the noise covariance matrix. In auto-regressive model estimation, this matrix will contain in $Sigma_{i,j}$ the residual variance in estimating time-series $i$ from $j$, $p$ is the dimensionality of the data, $m$ is the number of parameters in the model and $N_{total}$ is the number of time-points.

  M Ding and Y Chen and S Bressler (2006) Granger Causality: Basic Theory and Application to Neuroscience. http://arxiv.org/abs/q-bio/0608035v1

  See http://en.wikipedia.org/wiki/Schwarz_criterion

nitime.utils.circle_to_hz(omega, Fsamp)

  For a frequency grid spaced on the unit circle of an imaginary plane, return the corresponding frequency grid in Hz.

nitime.utils.circularize(x, bottom=0, top=6.283185307179586, deg=False)

  Maps the input into the continuous interval (bottom, top) where bottom defaults to 0 and top defaults to 2*pi

  Parameters:

    x : ndarray - the input array

    bottom : float, optional (defaults to 0).

    > If you want to set the bottom of the interval into which you modulo to something else than 0.

    top : float, optional (defaults to 2*pi).

    > If you want to set the top of the interval into which you modulo to something else than 2*pi

  Returns:

    The input array, mapped into the interval (bottom,top) :

nitime.utils.crosscorr(x, y, **kwargs)

  Returns the crosscorrelation sequence between two ndarrays. This is performed by calling fftconvolve on x, y[::-1]

  Parameters:

    x : ndarray

    y : ndarray

    axis : time axis

    all_lags : {True/False}

    > whether to return all nonzero lags, or to clip the length of r_xy to be the length of x and y. If False, then the zero lag correlation is at index 0. Otherwise, it is found at (len(x) + len(y) - 1)/2

  Returns:

    rxy : ndarray

    > The crosscorrelation function

  Notes

  cross correlation is defined as

  \[\]

  R_{xy}[k]=E{X[n+k]Y^{*}[n]}

  where X and Y are discrete, stationary (ergodic) random processes

nitime.utils.crosscov(x, y, axis=-1, all_lags=False, debias=True, normalize=True)

  Returns the crosscovariance sequence between two ndarrays. This is performed by calling fftconvolve on x, y[::-1]

  Parameters:

    x : ndarray

    y : ndarray

    axis : time axis

    all_lags : {True/False}

    > whether to return all nonzero lags, or to clip the length of s_xy to be the length of x and y. If False, then the zero lag covariance is at index 0. Otherwise, it is found at (len(x) + len(y) - 1)/2

    debias : {True/False}

    > Always removes an estimate of the mean along the axis, unless told not to (eg X and Y are known zero-mean)

  Returns:

    cxy : ndarray

    > The crosscovariance function

  Notes

  cross covariance of processes x and y is defined as

  \[\]

  C_{xy}[k]=E{(X(n+k)-E{X})(Y(n)-E{Y})^{*}}

  where X and Y are discrete, stationary (or ergodic) random processes

  Also note that this routine is the workhorse for all auto/cross/cov/corr functions.

nitime.utils.crosscov_vector(x, y, nlags=None)

  This method computes the following function

  \[R_{xy}(k) = E{ x(t)y^{*}(t-k) } = E{ x(t+k)y^{*}(t) } k \in {0, 1, ..., nlags-1}\]

  (* := conjugate transpose)

  Note: This is related to the other commonly used definition for vector crosscovariance

  \[R_{xy}^{(2)}(k) = E{ x(t-k)y^{*}(t) } = R_{xy}^(-k) = R_{yx}^{*}(k)\]
  Parameters:

    x, y : ndarray (nc, N)

    nlags : int, optional

    > compute lags for k in {0, …, nlags-1}

  Returns:

    rxy : ndarray (nc, nc, nlags)

nitime.utils.dB(x, power=True)

  Convert the values in x to decibels. If the values in x are in ‘power’-like units, then set the power flag accordingly

  1. dB(x) = 10log10(x) (if power==True)

  2. dB(x) = 10log10(|x|^2) = 20log10(|x|) (if power==False)

nitime.utils.detect_lines(s, tapers, p=None, **taper_kws)

  Detect the presence of line spectra in s using the F-test described in “Spectrum estimation and harmonic analysis” (Thompson 81). Strategies for detecting harmonics in low SNR include increasing the number of FFT points (NFFT keyword arg) and/or increasing the stability of the spectral estimate by using more tapers (higher NW parameter).

  sndarray

    The sequence(s) to test. If s.ndim > 1, then test sequences in the last axis in parallel

  tapersndarray or container

    Either the precomputed DPSS tapers, or the pair of parameters (NW, K) needed to compute K tapers of length n_pts.

  pfloat

    The confidence threshold: under the null hypothesis of a locally white spectrum, there is a threshold such that there is a (1-p)% chance of a line amplitude being larger than that threshold. Only detect lines with amplitude greater than this threshold. The default is 1/NFFT, to control for false positives.

  taper_kws

    Options for the tapered_spectra method, if no DPSS are provided.

  Returns:

    (freq, beta) : sequence

    > The frequencies (normalized in [0, .5]) and coefficients of the complex exponentials detected in the spectrum. A pair is returned for each sequence tested.

    > One can reconstruct the line components as such:

    > sn = 2*(beta[:,None]*np.exp(i*2*np.pi*np.arange(N)*freq[:,None])).real sn = sn.sum(axis=0)

nitime.utils.diag_indices(n, ndim=2)

  Return the indices to access the main diagonal of an array.

  This returns a tuple of indices that can be used to access the main diagonal of an array with ndim (>=2) dimensions and shape (n,n,…,n). For ndim=2 this is the usual diagonal, for ndim>2 this is the set of indices to access A[i,i,…,i] for i=[0..n-1].

  Parameters:

    n : int

    > The size, along each dimension, of the arrays for which the returned indices can be used.

    ndim : int, optional

    > The number of dimensions

  See also

  `-`, `array.`

  Examples

  Create a set of indices to access the diagonal of a (4,4) array: >>> di = diag_indices(4)

      >>> a = np.array([[1,2,3,4],[5,6,7,8],[9,10,11,12],[13,14,15,16]])
      >>> a
      array([[ 1,  2,  3,  4],
             [ 5,  6,  7,  8],
             [ 9, 10, 11, 12],
             [13, 14, 15, 16]])
      >>> a[di] = 100
      >>> a
      array([[100,   2,   3,   4],
             [  5, 100,   7,   8],
             [  9,  10, 100,  12],
             [ 13,  14,  15, 100]])

  Now, we create indices to manipulate a 3-d array: >>> d3 = diag_indices(2,3)

  And use it to set the diagonal of a zeros array to 1: >>> a = np.zeros((2,2,2),int) >>> a[d3] = 1 >>> a array([[[1, 0],

  > [0, 0]],

  <BLANKLINE>
    [[0, 0],

      [0, 1]]])

nitime.utils.diag_indices_from(arr)

  Return the indices to access the main diagonal of an n-dimensional array.

  See diag_indices() for full details.

  Parameters:

    arr : array, at least 2-d

nitime.utils.dpss_windows(N, NW, Kmax, interp_from=None, interp_kind='linear')

  Returns the Discrete Prolate Spheroidal Sequences of orders [0,Kmax-1] for a given frequency-spacing multiple NW and sequence length N.

  Parameters:

    N : int

    > sequence length

    NW : float, unitless

    > standardized half bandwidth corresponding to 2NW = BW/f0 = BW*N*dt but with dt taken as 1

    Kmax : int

    > number of DPSS windows to return is Kmax (orders 0 through Kmax-1)

    interp_from : int (optional)

    > The dpss can be calculated using interpolation from a set of dpss with the same NW and Kmax, but shorter N. This is the length of this shorter set of dpss windows.

    interp_kind : str (optional)

    > This input variable is passed to scipy.interpolate.interp1d and specifies the kind of interpolation as a string (‘linear’, ‘nearest’, ‘zero’, ‘slinear’, ‘quadratic, ‘cubic’) or as an integer specifying the order of the spline interpolator to use.

  Returns:

    v, e : tuple,

    > v is an array of DPSS windows shaped (Kmax, N) e are the eigenvalues

  Notes

  Tridiagonal form of DPSS calculation from:

  Slepian, D. Prolate spheroidal wave functions, Fourier analysis, and uncertainty V: The discrete case. Bell System Technical Journal, Volume 57 (1978), 1371430

nitime.utils.expected_jk_variance(K)

  Compute the expected value of the jackknife variance estimate over K windows below. This expected value formula is based on the asymptotic expansion of the trigamma function derived in [Thompson_1994]

  ### Parameters

  Kint

    Number of tapers used in the multitaper method

  Returns:

    evar : float

    > Expected value of the jackknife variance estimator

nitime.utils.fftconvolve(in1, in2, mode='full', axis=None)

  Convolve two N-dimensional arrays using FFT. See convolve.

  This is a fix of scipy.signal.fftconvolve, adding an axis argument.

nitime.utils.fill_diagonal(a, val)

  Fill the main diagonal of the given array of any dimensionality.

  For an array with ndim > 2, the diagonal is the list of locations with indices a[i,i,…,i], all identical.

  This function modifies the input array in-place, it does not return a value.

  This functionality can be obtained via diag_indices(), but internally this version uses a much faster implementation that never constructs the indices and uses simple slicing.

  Parameters:

    a : array, at least 2-dimensional.

    > Array whose diagonal is to be filled, it gets modified in-place.

    val : scalar

    > Value to be written on the diagonal, its type must be compatible with that of the array a.

  See also

  `-`, `-`

  Examples

      >>> a = np.zeros((3,3),int)
      >>> fill_diagonal(a,5)
      >>> a
      array([[5, 0, 0],
             [0, 5, 0],
             [0, 0, 5]])

  The same function can operate on a 4-d array: >>> a = np.zeros((3,3,3,3),int) >>> fill_diagonal(a,4)

  We only show a few blocks for clarity: >>> a[0,0] array([[4, 0, 0],

  > [0, 0, 0], [0, 0, 0]])

      >>> a[1,1]
      array([[0, 0, 0],
             [0, 4, 0],
             [0, 0, 0]])
      >>> a[2,2]
      array([[0, 0, 0],
             [0, 0, 0],
             [0, 0, 4]])

nitime.utils.fir_design_matrix(events, len_hrf)

  Create a FIR event matrix from a time-series of events.

  Parameters:

    events : 1-d int array

    > Integers denoting different kinds of events, occurring at the time corresponding to the bin represented by each slot in the array. In time-bins in which no event occurred, a 0 should be entered. If negative event values are entered, they will be used as “negative” events, as in events that should be contrasted with the positive events (typically -1 and 1 can be used for a simple contrast of two conditions)

    len_hrf : int

    > The expected length of the HRF (in the same time-units as the events are represented (presumably TR). The size of the block dedicated in the fir_matrix to each type of event

  Returns:

    fir_matrix : matrix

    > The design matrix for FIR estimation

nitime.utils.generate_mar(a, cov, N)

  Generates a multivariate autoregressive dataset given the formula:

  X(t) + sum_{i=1}^{P} a(i)X(t-i) = E(t)

  Where E(t) is a vector of samples from possibly covarying noise processes.

  Parameters:

    a : ndarray (n_order, n_c, n_c)

    > An order n_order set of coefficient matrices, each shaped (n_c, n_c) for n_channel data

    cov : ndarray (n_c, n_c)

    > The innovations process covariance

    N : int

    > how many samples to generate

  Returns:

    mar, nz :

    mar and noise process shaped (n_c, N) :

nitime.utils.get_bounds(f, lb=0, ub=None)

  Find the indices of the lower and upper bounds within an array f

  Parameters:

    f, array :

    lb,ub, float :

  Returns:

    lb_idx, ub_idx: the indices into ‘f’ which correspond to values bounded :

    between ub and lb in that array :

nitime.utils.get_freqs(Fs, n)

  Returns the center frequencies of the frequency decomposition of a time series of length n, sampled at Fs Hz

nitime.utils.hanning_window_spectrum(N, Fs)

  Calculate the analytical spectrum of a Hanning window

  Parameters:

    N : int

    > The size of the window

    Fs : float

    > The sampling rate

  Returns:

    float array - the frequency bands, given N and FS :

    complex array: the power in the spectrum of the square window in the :

    frequency bands :

  Notes

  This is equation 28b in Harris (1978):

  \[W(\theta) = 0.5 D(\theta) + 0.25 (D(\theta - \frac{2\pi}{N}) + D(\theta + \frac{2\pi}{N}) ),\]

  where:

  \[D(\theta) = exp(j\frac{\theta}{2}) \frac{sin\frac{N\theta}{2}}{sin\frac{\theta}{2}}\]

  F.J. Harris (1978). On the use of windows for harmonic analysis with the discrete Fourier transform. Proceedings of the IEEE, 66:51-83

nitime.utils.intersect_coords(coords1, coords2)

  For two sets of coordinates, find the coordinates that are common to both, where the dimensionality is the coords1.shape[0]

nitime.utils.jackknifed_coh_variance(tx, ty, eigvals, adaptive=True)

  Returns the variance of the coherency between x and y, estimated through jack-knifing the tapered samples in {tx, ty}.

  Parameters:

    tx : ndarray, (K, L)

    > The K complex spectra of tapered timeseries x

    ty : ndarray, (K, L)

    > The K complex spectra of tapered timeseries y

    eigvals : ndarray (K,)

    > The eigenvalues associated with the K DPSS tapers

  Returns:

    jk_var : ndarray

    > The variance computed in the transformed domain (see normalize_coherence)

nitime.utils.jackknifed_sdf_variance(yk, eigvals, sides='onesided', adaptive=True)

  Returns the variance of the log-sdf estimated through jack-knifing a group of independent sdf estimates.

  Parameters:

    yk : ndarray (K, L)

    > The K DFTs of the tapered sequences

    eigvals : ndarray (K,)

    > The eigenvalues corresponding to the K DPSS tapers

    sides : str, optional

    > Compute the jackknife pseudovalues over as one-sided or two-sided spectra

    adaptive : bool, optional

    > Compute the adaptive weighting for each jackknife pseudovalue

  Returns:

    var : The estimate for log-sdf variance

  Notes

  The jackknifed mean estimate is distributed about the true mean as a Student’s t-distribution with (K-1) degrees of freedom, and standard error equal to sqrt(var). However, Thompson and Chave [1] point out that this variance better describes the sample mean.

  [1] Thomson D J, Chave A D (1991) Advances in Spectrum Analysis and Array Processing (Prentice-Hall, Englewood Cliffs, NJ), 1, pp 58-113.

nitime.utils.mask_indices(n, mask_func, k=0)

  Return the indices to access (n,n) arrays, given a masking function.

  Assume mask_func() is a function that, for a square array a of size (n,n) with a possible offset argument k, when called as mask_func(a,k) returns a new array with zeros in certain locations (functions like triu() or tril() do precisely this). Then this function returns the indices where the non-zero values would be located.

  Parameters:

    n : int

    > The returned indices will be valid to access arrays of shape (n,n).

    mask_func : callable

    > A function whose api is similar to that of numpy.tri{u,l}. That is, mask_func(x,k) returns a boolean array, shaped like x. k is an optional argument to the function.

    k : scalar

    > An optional argument which is passed through to mask_func(). Functions like tri{u,l} take a second argument that is interpreted as an offset.

  Returns:

    indices : an n-tuple of index arrays.

    > The indices corresponding to the locations where mask_func(ones((n,n)),k) is True.

  Examples

  These are the indices that would allow you to access the upper triangular part of any 3x3 array: >>> iu = mask_indices(3,np.triu)

  For example, if a is a 3x3 array: >>> a = np.arange(9).reshape(3,3) >>> a array([[0, 1, 2],

  > [3, 4, 5], [6, 7, 8]])

  Then: >>> a[iu] array([0, 1, 2, 4, 5, 8])

  An offset can be passed also to the masking function. This gets us the indices starting on the first diagonal right of the main one: >>> iu1 = mask_indices(3,np.triu,1)

  with which we now extract only three elements: >>> a[iu1] array([1, 2, 5])

nitime.utils.minmax_norm(arr, mode='direct', folding_edges=None)

  Minmax_norm an array to [0,1] range.

  By default, this simply rescales the input array to [0,1]. But it has a special ‘folding’ mode that allows for the normalization of an array with negative and positive values by mapping the negative values to their flipped sign

  Parameters:

    arr : 1d array

    mode : string, one of [‘direct’,’folding’]

    folding_edges : (float,float)

    > Only needed for folding mode, ignored in ‘direct’ mode.

  Examples

      >>> a = np.linspace(0.3,0.8,4)
      >>> minmax_norm(a)
      array([0.    , 0.3333, 0.6667, 1.    ])
      >>> b = np.concatenate([np.linspace(-0.7,-0.3,3),
      ...                             np.linspace(0.3,0.8,3)])
      >>> b
      array([-0.7 , -0.5 , -0.3 ,  0.3 ,  0.55,  0.8 ])
      >>> minmax_norm(b,'folding',[-0.3,0.3])
      array([0.8, 0.4, 0. , 0. , 0.5, 1. ])

nitime.utils.multi_intersect(input)

  A function for finding the intersection of several different arrays

  Parameters:

    input is a tuple of arrays, with all the different arrays :

  Returns:

    array - the intersection of the inputs :

  Notes

  Simply runs intersect1d iteratively on the inputs

nitime.utils.normal_coherence_to_unit(y, dof, out=None)

  The inverse transform of the above normalization

nitime.utils.normalize_coherence(x, dof, copy=True)

  The generally accepted choice to transform coherence measures into a more normal distribution

  Parameters:

    x : ndarray, real

    > square-root of magnitude-square coherence measures

    dof : int

    > number of degrees of freedom in the multitaper model

    copy : bool

    > Copy or return inplace modified x.

  Returns:

    y : ndarray, real

    > The transformed array.

nitime.utils.percent_change(ts, ax=-1)

  Returns the % signal change of each point of the times series along a given axis of the array time_series

  Parameters:

    ts : ndarray

    > an array of time series

    ax : int, optional (default to -1)

    > the axis of time_series along which to compute means and stdevs

  Returns:

    ndarray :

    > the renormalized time series array (in units of %)

  Examples

      >>> ts = np.arange(4*5).reshape(4,5)
      >>> ax = 0
      >>> percent_change(ts,ax)
      array([[-100.    ,  -88.2353,  -78.9474,  -71.4286,  -65.2174],
             [ -33.3333,  -29.4118,  -26.3158,  -23.8095,  -21.7391],
             [  33.3333,   29.4118,   26.3158,   23.8095,   21.7391],
             [ 100.    ,   88.2353,   78.9474,   71.4286,   65.2174]])
      >>> ax = 1
      >>> percent_change(ts,ax)
      array([[-100.    ,  -50.    ,    0.    ,   50.    ,  100.    ],
             [ -28.5714,  -14.2857,    0.    ,   14.2857,   28.5714],
             [ -16.6667,   -8.3333,    0.    ,    8.3333,   16.6667],
             [ -11.7647,   -5.8824,    0.    ,    5.8824,   11.7647]])

nitime.utils.remove_bias(x, axis)

  Subtracts an estimate of the mean from signal x at axis

nitime.utils.rescale_arr(arr, amin, amax)

  Rescale an array to a new range.

  Return a new array whose range of values is (amin,amax).

  Parameters:

    arr : array-like

    amin : float

    > new minimum value

    amax : float

    > new maximum value

  Examples

      >>> a = np.arange(5)

      >>> rescale_arr(a,3,6)
      array([3.  , 3.75, 4.5 , 5.25, 6.  ])

nitime.utils.square_window_spectrum(N, Fs)

  Calculate the analytical spectrum of a square window

  Parameters:

    N : int

    > the size of the window

    Fs : float

    > The sampling rate

  Returns:

    float array - the frequency bands, given N and FS :

    complex array: the power in the spectrum of the square window in the :

    frequency bands :

  Notes

  This is equation 21c in Harris (1978):

  \[W(\theta) = exp(-j \frac{N-1}{2} \theta) \frac{sin \frac{N\theta}{2}} {sin\frac{\theta}{2}}\]

  F.J. Harris (1978). On the use of windows for harmonic analysis with the discrete Fourier transform. Proceedings of the IEEE, 66:51-83

nitime.utils.structured_rand_arr(size, sample_func=<bound method RandomState.random of RandomState(MT19937)>, ltfac=None, utfac=None, fill_diag=None)

  Make a structured random 2-d array of shape (size,size).

  If no optional arguments are given, a symmetric array is returned.

  Parameters:

    size : int

    > Determines the shape of the output array: (size,size).

    sample_func : function, optional.

    > Must be a function which when called with a 2-tuple of ints, returns a 2-d array of that shape. By default, np.random.random is used, but any other sampling function can be used as long as matches this API.

    utfac : float, optional

    > Multiplicative factor for the upper triangular part of the matrix.

    ltfac : float, optional

    > Multiplicative factor for the lower triangular part of the matrix.

    fill_diag : float, optional

    > If given, use this value to fill in the diagonal. Otherwise the diagonal will contain random elements.

  Examples

      >>> np.random.seed(0)  # for doctesting
      >>> structured_rand_arr(4)
      array([[0.5488, 0.7152, 0.6028, 0.5449],
             [0.7152, 0.6459, 0.4376, 0.8918],
             [0.6028, 0.4376, 0.7917, 0.5289],
             [0.5449, 0.8918, 0.5289, 0.0871]])
      >>> structured_rand_arr(4,ltfac=-10,utfac=10,fill_diag=0.5)
      array([[ 0.5   ,  8.3262,  7.7816,  8.7001],
             [-8.3262,  0.5   ,  4.6148,  7.8053],
             [-7.7816, -4.6148,  0.5   ,  9.4467],
             [-8.7001, -7.8053, -9.4467,  0.5   ]])

nitime.utils.symm_rand_arr(size, sample_func=<bound method RandomState.random of RandomState(MT19937)>, fill_diag=None)

  Make a symmetric random 2-d array of shape (size,size).

  Parameters:

    n : int

    > Size of the output array.

    sample_func : function, optional.

    > Must be a function which when called with a 2-tuple of ints, returns a 2-d array of that shape. By default, np.random.random is used, but any other sampling function can be used as long as matches this API.

    fill_diag : float, optional

    > If given, use this value to fill in the diagonal. Useful for

  Examples

      >>> np.random.seed(0)  # for doctesting
      >>> symm_rand_arr(4)
      array([[0.5488, 0.7152, 0.6028, 0.5449],
             [0.7152, 0.6459, 0.4376, 0.8918],
             [0.6028, 0.4376, 0.7917, 0.5289],
             [0.5449, 0.8918, 0.5289, 0.0871]])
      >>> symm_rand_arr(4,fill_diag=4)
      array([[4.    , 0.8326, 0.7782, 0.87  ],
             [0.8326, 4.    , 0.4615, 0.7805],
             [0.7782, 0.4615, 4.    , 0.9447],
             [0.87  , 0.7805, 0.9447, 4.    ]])

nitime.utils.tapered_spectra(s, tapers, NFFT=None, low_bias=True)

  Compute the tapered spectra of the rows of s.

  Parameters:

    s : ndarray, (n_arr, n_pts)

    > An array whose rows are timeseries.

    tapers : ndarray or container

    > Either the precomputed DPSS tapers, or the pair of parameters (NW, K) needed to compute K tapers of length n_pts.

    NFFT : int

    > Number of FFT bins to compute

    low_bias : Boolean

    > If compute DPSS, automatically select tapers corresponding to > 90% energy concentration.

  Returns:

    t_spectra : ndarray, shaped (n_arr, K, NFFT)

    > The FFT of the tapered sequences in s. First dimension is squeezed out if n_arr is 1.

    eigvals : ndarray

    > The eigenvalues are also returned if DPSS are calculated here.

nitime.utils.threshold_arr(cmat, threshold=0.0, threshold2=None)

  Threshold values from the input array.

  Parameters:

    cmat : array

    threshold : float, optional.

    > First threshold.

    threshold2 : float, optional.

    > Second threshold.

  Returns:

    indices, values: a tuple with ndim+1 :

  Examples

      >>> a = np.linspace(0,0.2,5)
      >>> a
      array([0.  , 0.05, 0.1 , 0.15, 0.2 ])
      >>> threshold_arr(a,0.1)
      (array([3, 4]), array([0.15, 0.2 ]))

  With two thresholds: >>> threshold_arr(a,0.1,0.2) (array([0, 1]), array([0. , 0.05]))

nitime.utils.thresholded_arr(arr, threshold=0.0, threshold2=None, fill_val=nan)

  Threshold values from the input matrix and return a new matrix.

  Parameters:

    arr : array

    threshold : float

    > First threshold.

    threshold2 : float, optional.

    > Second threshold.

  Returns:

    An array shaped like the input, with the values outside the threshold :

    replaced with fill_val. :

nitime.utils.tridi_inverse_iteration(d, e, w, x0=None, rtol=1e-08)

  Perform an inverse iteration to find the eigenvector corresponding to the given eigenvalue in a symmetric tridiagonal system.

  Parameters:

    d : ndarray

    > main diagonal of the tridiagonal system

    e : ndarray

    > offdiagonal stored in e[:-1]

    w : float

    > eigenvalue of the eigenvector

    x0 : ndarray

    > initial point to start the iteration

    rtol : float

    > tolerance for the norm of the difference of iterates

  Returns:

    e : ndarray

    > The converged eigenvector

nitime.utils.tril_indices(n, k=0)

  Return the indices for the lower-triangle of an (n,n) array.

  Parameters:

    n : int

    > Sets the size of the arrays for which the returned indices will be valid.

    k : int, optional

    > Diagonal offset (see tril() for details).

  See also

  `-`, `for`, `-`

  Examples

  Compute two different sets of indices to access 4x4 arrays, one for the lower triangular part starting at the main diagonal, and one starting two diagonals further right:

      >>> il1 = tril_indices(4)
      >>> il2 = tril_indices(4,2)

  Here is how they can be used with a sample array: >>> a = np.array([[1,2,3,4],[5,6,7,8],[9,10,11,12],[13,14,15,16]]) >>> a array([[ 1, 2, 3, 4],

  > [ 5, 6, 7, 8], [ 9, 10, 11, 12], [13, 14, 15, 16]])

  Both for indexing: >>> a[il1] array([ 1, 5, 6, 9, 10, 11, 13, 14, 15, 16])

  And for assigning values: >>> a[il1] = -1 >>> a array([[-1, 2, 3, 4],

  > [-1, -1, 7, 8], [-1, -1, -1, 12], [-1, -1, -1, -1]])

  These cover almost the whole array (two diagonals right of the main one): >>> a[il2] = -10 >>> a array([[-10, -10, -10, 4],

  > [-10, -10, -10, -10], [-10, -10, -10, -10], [-10, -10, -10, -10]])

nitime.utils.tril_indices_from(arr, k=0)

  Return the indices for the lower-triangle of an (n,n) array.

  See tril_indices() for full details.

  Parameters:

    n : int

    > Sets the size of the arrays for which the returned indices will be valid.

    k : int, optional

    > Diagonal offset (see tril() for details).

nitime.utils.triu_indices(n, k=0)

  Return the indices for the upper-triangle of an (n,n) array.

  Parameters:

    n : int

    > Sets the size of the arrays for which the returned indices will be valid.

    k : int, optional

    > Diagonal offset (see triu() for details).

  See also

  `-`, `for`, `-`

  Examples

  Compute two different sets of indices to access 4x4 arrays, one for the upper triangular part starting at the main diagonal, and one starting two diagonals further right:

      >>> iu1 = triu_indices(4)
      >>> iu2 = triu_indices(4,2)

  Here is how they can be used with a sample array: >>> a = np.array([[1,2,3,4],[5,6,7,8],[9,10,11,12],[13,14,15,16]]) >>> a array([[ 1, 2, 3, 4],

  > [ 5, 6, 7, 8], [ 9, 10, 11, 12], [13, 14, 15, 16]])

  Both for indexing: >>> a[iu1] array([ 1, 2, 3, 4, 6, 7, 8, 11, 12, 16])

  And for assigning values: >>> a[iu1] = -1 >>> a array([[-1, -1, -1, -1],

  > [ 5, -1, -1, -1], [ 9, 10, -1, -1], [13, 14, 15, -1]])

  These cover almost the whole array (two diagonals right of the main one): >>> a[iu2] = -10 >>> a array([[ -1, -1, -10, -10],

  > [ 5, -1, -1, -10], [ 9, 10, -1, -1], [ 13, 14, 15, -1]])

nitime.utils.triu_indices_from(arr, k=0)

  Return the indices for the lower-triangle of an (n,n) array.

  See triu_indices() for full details.

  Parameters:

    n : int

    > Sets the size of the arrays for which the returned indices will be valid.

    k : int, optional

    > Diagonal offset (see triu() for details).

nitime.utils.unwrap_phases(a)

  Changes consecutive jumps larger than pi to their 2*pi complement.

nitime.utils.zero_pad(time_series, NFFT)

  Pad a time-series with zeros on either side, depending on its length

  Parameters:

    time_series : n-d array

    > Time-series data with time as the last dimension

    NFFT : int

    > The length to pad the data up to.

nitime.utils.zscore(time_series, axis=-1)

  Returns the z-score of each point of the time series along a given axis of the array time_series.

  Parameters:

    time_series : ndarray

    > an array of time series

    axis : int, optional

    > the axis of time_series along which to compute means and stdevs

    Returns :

    _______ :

    zt : ndarray

    > the renormalized time series array