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, lengthK
The eigenvalues of the DPSS tapers
sides : str
Whether to compute weights on a onesided or twosided 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 lengthL)
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 autoregressive 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 timepoints (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/qbio/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=<builtin method random_sample of mtrand.RandomState object>)¶ Make an antisymmetric random 2d 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 2tuple of ints, returns a 2d 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 >>> np.set_printoptions(precision=4) # 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(n1) + a2*u(n2) + … + 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 wellestimated 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 overrides the sigma parameter). Default: None
Returns: u : ndarray
the AR sequence
v : ndarray
the unitvariance 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 constantcoefficient 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^{*}(tk) } = E{ x(t+k)x^{*}(t) } k in {0, 1, …, nlags1}
(* := conjugate transpose)
Note: this is related to the other commonly used definition for vector autocovariance
\[\]R_{xx}^{(2)}(k) = E{ x(tk)x^{*}(t) } = R_{xx}(k) = R_{xx}^{*}(k)
Parameters: x : ndarray (nc, N)
nlags : int, optional
compute lags for k in {0, …, nlags1}
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 autoregressive model estimation, this matrix will contain in $Sigma_{i,j}$ the residual variance in estimating timeseries $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 timepoints.
M Ding and Y Chen and S Bressler (2006) Granger Causality: Basic Theory and Application to Neuroscience. http://arxiv.org/abs/qbio/0608035v1

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 modulu 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 modulu 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 zeromean)
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^{*}(tk) } = E{ x(t+k)y^{*}(t) } k \in {0, 1, ..., nlags1}\](* := conjugate transpose)
Note: This is related to the other commonly used definition for vector crosscovariance
\[R_{xy}^{(2)}(k) = E{ x(tk)y^{*}(t) } = R_{xy}^(k) = R_{yx}^{*}(k)\]Parameters: x, y : ndarray (nc, N)
nlags : int, optional
compute lags for k in {0, …, nlags1}
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
 dB(x) = 10log10(x) (if power==True)
 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 Ftest 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).
 s : ndarray
 The sequence(s) to test. If s.ndim > 1, then test sequences in the last axis in parallel
 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.
 p : float
 The confidence threshold: under the null hypothesis of a locally white spectrum, there is a threshold such that there is a (1p)% 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..n1].
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 3d 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 ndimensional array.
See diag_indices() for full details.
Parameters: arr : array, at least 2d

nitime.utils.
dpss_windows
(N, NW, Kmax, interp_from=None, interp_kind='linear')¶ Returns the Discrete Prolate Spheroidal Sequences of orders [0,Kmax1] for a given frequencyspacing 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 Kmax1)
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]
 K : int
 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 Ndimensional 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 inplace, 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 2dimensional.
Array whose diagonal is to be filled, it gets modified inplace.
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 4d 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 timeseries of events.
Parameters: events : 1d int array
Integers denoting different kinds of events, occurring at the time corresponding to the bin represented by each slot in the array. In timebins 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 postitive 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 timeunits 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(ti) = 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:5183

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 jackknifing 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 logsdf estimated through jackknifing 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 onesided or twosided spectra
adpative : bool, optional
Compute the adaptive weighting for each jackknife pseudovalue
Returns: var : The estimate for logsdf variance
Notes
The jackknifed mean estimate is distributed about the true mean as a Student’s tdistribution with (K1) 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 (PrenticeHall, Englewood Cliffs, NJ), 1, pp 58113.

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 nonzero 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 ntuple 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
>>> np.set_printoptions(precision=4) # for doctesting >>> 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
squareroot of magnitudesquare 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 : arraylike
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{N1}{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:5183

nitime.utils.
structured_rand_arr
(size, sample_func=<builtin method random_sample of mtrand.RandomState object>, ltfac=None, utfac=None, fill_diag=None)¶ Make a structured random 2d 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 2tuple of ints, returns a 2d 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 >>> np.set_printoptions(precision=4) # 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=<builtin method random_sample of mtrand.RandomState object>, fill_diag=None)¶ Make a symmetric random 2d 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 2tuple of ints, returns a 2d 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 >>> np.set_printoptions(precision=4) # 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
>>> np.set_printoptions(precision=4) # For doctesting >>> 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=1e08)¶ 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 lowertriangle 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
Commpute 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 lowertriangle 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 uppertriangle 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
Commpute 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 lowertriangle 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 timeseries with zeros on either side, depending on its length
Parameters: time_series : nd array
Timeseries 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 zscore 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