def do_mvar_evaluation(X, morder, whit_max=3., whit_min=1., thr_cons=0.8):
'''
Fit MVAR model to data using scot and do some basic checks.
X: array (trials, channels, samples)
morder: the model order
Returns:
(is_white, consistency, is_stable)
'''
print('starting checks and MVAR fitting...')
# tsdata_to_var from MVGC requires sources x samples x trials
# X is of shape trials x sources x samples (which is what ScoT uses)
X_trans = X.transpose(1, 2, 0)
A, SIG, E = _tsdata_to_var(X_trans, morder)
del A, SIG
whi = False
dw, pval = dw_whiteness(X_trans, E)
if np.all(dw < whit_max) and np.all(dw > whit_min):
whi = True
cons = consistency(X_trans, E)
del dw, pval, E
from scot.var import VAR
mvar = VAR(morder)
mvar.fit(X) # scot func which requires shape trials x sources x samples
is_st = mvar.is_stable()
if cons < thr_cons or is_st is False or whi is False:
print('ERROR: Model order not ideal - check parameters !!')
return str(whi), cons, str(is_st)
def compute_order_extended(X,
m_max,
m_min=1,
m_step=1,
n_jobs=None,
verbose=True):
"""
Estimate VAR order with the Bayesian Information Criterion (BIC).
Parameters:
-----------
X : ndarray, shape (trials, n_channels, n_samples)
m_max : int
The maximum model order to test,
m_min : int
The minimum model order to test.
m_step : int
The step size for checking the model order interval
given by m_min and m_max.
n_jobs : None | int, optional
Number of jobs to run in parallel for various tasks (e.g. whiteness
testing). If set to None, joblib is not used at all. Note that the main
script must be guarded with `if __name__ == '__main__':` when using
parallelization.
verbose : bool
Plot results for other information criteria as well.
Returns:
--------
o_m : int
Estimated order using BIC2.
morders : np.array of shape ((m_max - m_min) / m_step, )
The model orders corresponding to the entries in the following results
arrays.
ics : np.array of shape (n_ics, (m_max - m_min) / m_step)
The information criteria for the different model orders.
[AIC1, BIC1, AIC2, BIC2, lnFPE, HQIC]]
stability : np.array of shape ((m_max - m_min) / m_step), )
Indicates if MVAR model describes stable process (covariance
stationary).
p_white_scot : np.array of shape ((m_max - m_min) / m_step), )
p-value that the residuals are white based on the Li-McLeod Portmanteau test
implemented in SCoT. Reject hypothesis of white residuals if p is smaller
than the critical p-value.
p_white_dw : np.array of shape ((m_max - m_min) / m_step), n_rois)
Uncorrected p-values that the residuals are white based on the Durbin-Watson
test as implemented by Barnett and Seth (2012). Reject hypothesis of white
residuals if all p's are smaller than the critical p-value.
dw : np.array of shape ((m_max - m_min) / m_step), n_rois)
The Durbin-Watson statistics.
consistency : np.array of shape ((m_max - m_min) / m_step), )
Results of the MVAR consistency estimation.
References:
-----------
[1] provides the equation:BIC(m) = 2*log[det(Σ)]+ 2*(p**2)*m*log(N*n*m)/(N*n*m),
Σ is the noise covariance matrix, p is the channels, N is the trials, n
is the n_samples, m is model order.
[1] Mingzhou Ding, Yonghong Chen (2008). "Granger Causality: Basic Theory and Application
to Neuroscience." Elsevier Science
[2] Nicoletta Nicolaou and Julius Georgiou (2013). “Autoregressive Model Order Estimation
Criteria for Monitoring Awareness during Anaesthesia.” IFIP Advances in Information and
Communication Technology 412
[3] Helmut Lütkepohl (2005). "New Introduction to Multiple Time Series Analysis."
1st ed. Berlin: Springer-Verlag Berlin Heidelberg.
URL: https://gist.github.com/dongqunxi/b23d1679b9bffa8e458c11f93bd8d6ff
"""
from scot.var import VAR
from scipy import linalg
N, p, n = X.shape
aic1 = []
bic1 = []
aic2 = []
bic2 = []
lnfpe = []
hqic = []
morders = []
stability = []
p_white_scot = []
p_white_dw = []
dw = []
consistency = []
# TODO: should this be n_total = N * n * p ???
# total number of data points: n_trials * n_samples
# Esther Florin (2010): N_total is number of time points contained in each time series
n_total = N * n
# check model order min/max/step input
if m_min >= m_max:
m_min = m_max - 1
if m_min < 1:
m_min = 1
if m_step < 1:
m_step = 1
if m_step >= m_max:
m_step = m_max
for m in range(m_min, m_max + 1, m_step):
morders.append(m)
mvar = VAR(m, n_jobs=n_jobs)
mvar.fit(X)
stable = mvar.is_stable()
stability.append(stable)
p_white_scot_ = mvar.test_whiteness(h=m,
repeats=100,
get_q=False,
random_state=None)
white_scot_ = p_white_scot_ >= 0.05
p_white_scot.append(p_white_scot_)
white_dw_, cons, dw_, pval = check_whiteness_and_consistency(
X.transpose(1, 2, 0),
mvar.residuals.transpose(1, 2, 0),
alpha=0.05)
dw.append(dw_)
p_white_dw.append(pval)
consistency.append(cons)
sigma = mvar.rescov
########################################################################
# from [1]
########################################################################
m_aic = 2 * np.log(linalg.det(sigma)) + 2 * (p**2) * m / n_total
m_bic = 2 * np.log(
linalg.det(sigma)) + 2 * (p**2) * m / n_total * np.log(n_total)
aic1.append(m_aic)
bic1.append(m_bic)
########################################################################
# from [2]
########################################################################
m_aic2 = np.log(linalg.det(sigma)) + 2 * (p**2) * m / n_total
m_bic2 = np.log(
linalg.det(sigma)) + (p**2) * m / n_total * np.log(n_total)
aic2.append(m_aic2)
bic2.append(m_bic2)
########################################################################
# from [3]
########################################################################
# Akaike's final prediction error
m_ln_fpe3 = np.log(linalg.det(sigma)) + p * np.log(
(n_total + m * p + 1) / (n_total - m * p - 1))
# Hannan-Quinn criterion
m_hqc3 = np.log(linalg.det(sigma)) + 2 * (p**2) * m / n_total * np.log(
np.log(n_total))
lnfpe.append(m_ln_fpe3)
hqic.append(m_hqc3)
if verbose:
results = 'Model order: ' + str(m).zfill(2)
results += ' AIC1: %.2f' % m_aic
results += ' BIC1: %.2f' % m_bic
results += ' AIC2: %.2f' % m_aic2
results += ' BIC2: %.2f' % m_bic2
results += ' lnFPE3: %.2f' % m_ln_fpe3
results += ' HQC3: %.2f' % m_hqc3
results += ' stable: %s' % str(stable)
results += ' white1: %s' % str(white_scot_)
results += ' white2: %s' % str(white_dw_)
results += ' DWmin: %.2f' % dw_.min()
results += ' DWmax: %.2f' % dw_.max()
results += ' consistency: %.4f' % cons
print(results)
morders = np.array(morders)
o_m = morders[np.argmin(bic2)]
if verbose:
print('>>> Optimal model order according to BIC2 = %d' % o_m)
ics = [aic1, bic1, aic2, bic2, lnfpe, hqic]
ics = np.asarray(ics)
stability = np.array(stability)
p_white_scot = np.array(p_white_scot)
p_white_dw = np.array(p_white_dw)
dw = np.array(dw)
consistency = np.array(consistency)
return o_m, morders, ics, stability, p_white_scot, p_white_dw, dw, consistency
def check_model_order(X, p, whit_min=1.5, whit_max=2.5, check_stability=True):
"""
Check whiteness, consistency, and stability for all model
orders k <= p.
Computationally intensive but for high model orders probably
faster than do_mvar_evaluation().
Parameters:
-----------
X : narray, shape (n_epochs, n_sources, n_times)
The data to estimate the model order for.
p : int
The maximum model order.
whit_min : float
Lower boundary for the Durbin-Watson test.
whit_max : float
Upper boundary for the Durbin-Watson test.
check_stability : bool
Check the stability condition. Time intensive since
it fits a second MVAR model from scot.var.VAR
Returns:
--------
A: array, coefficients of the specified model
SIG:array, recovariance of this model
E: array, noise covariance of this model
"""
assert p >= 1, "The model order must be greater or equal to 1."
from scot.var import VAR
X_orig = X.copy()
X = X.transpose(1, 2, 0)
n, m, N = X.shape
p1 = p + 1
q1n = p1 * n
I = np.eye(n)
XX = np.zeros((n, p1, m + p, N))
for k in range(p1):
XX[:, k, k:k + m, :] = X
AF = np.zeros((n, q1n))
AB = np.zeros((n, q1n))
k = 1
kn = k * n
M = N * (m - k)
kf = list(range(0, kn))
kb = list(range(q1n - kn, q1n))
XF = np.reshape(XX[:, 0:k, k:m, :], (kn, M), order='F')
XB = np.reshape(XX[:, 0:k, k - 1:m - 1, :], (kn, M), order='F')
CXF = np.linalg.cholesky(XF.dot(XF.T)).T
CXB = np.linalg.cholesky(XB.dot(XB.T)).T
AF[:, kf] = np.linalg.solve(CXF.T, I)
AB[:, kb] = np.linalg.solve(CXB.T, I)
del p1, XF, XB, CXF, CXB
while k <= p:
tempF = np.reshape(XX[:, 0:k, k:m, :], (kn, M), order='F')
af = AF[:, kf]
EF = af.dot(tempF)
del af, tempF
tempB = np.reshape(XX[:, 0:k, k - 1:m - 1, :], (kn, M), order='F')
ab = AB[:, kb]
EB = ab.dot(tempB)
del ab, tempB
CEF = np.linalg.cholesky(EF.dot(EF.T)).T
CEB = np.linalg.cholesky(EB.dot(EB.T)).T
R = np.dot(np.linalg.solve(CEF.T, EF.dot(EB.T)), np.linalg.inv(CEB))
del EB, CEF, CEB
RF = np.linalg.cholesky(I - R.dot(R.T)).T
RB = np.linalg.cholesky(I - (R.T).dot(R)).T
k = k + 1
kn = k * n
M = N * (m - k)
kf = np.arange(kn)
kb = list(range(q1n - kn, q1n))
AFPREV = AF[:, kf]
ABPREV = AB[:, kb]
AF[:, kf] = np.linalg.solve(RF.T, AFPREV - R.dot(ABPREV))
AB[:, kb] = np.linalg.solve(RB.T, ABPREV - R.T.dot(AFPREV))
del RF, RB, ABPREV
# check MVAR model properties
E = np.linalg.solve(AFPREV[:, :n], EF)
E = np.reshape(E, (n, m - k + 1, N), order='F')
if k > 1:
whi, cons, _, _ = check_whiteness_and_consistency(
X, E, whit_min, whit_max)
if check_stability:
mvar = VAR((k - 1))
mvar.fit(
X_orig
) # scot func which requires shape trials x sources x samples
is_st = mvar.is_stable()
output = 'morder %d:' % (k - 1)
output += ' white: %s' % str(whi)
output += '; consistency: %.4f' % cons
if check_stability:
output += '; stable: %s' % str(is_st)
print(output)
