Model module

Module that defines PCM Model classes and NoiseModel classes

Model Classes

class model.Model(name)

Abstract PCM Model Class

Parameters:

name ([str]) – Name of the the model

est_theta0(G_hat)

Estimate initial guess for parameters

get_prior(theta, param_type=None)

Independent Gaussian prior on parameters :param theta: Vector of model parameters :type theta: np.array :param param_type: Indx into type of parameter: 0-M.n_param (model), M.n_param: Scale + Noise. :type param_type: ndarray

Returns:

  • prior (float) – log-prior probability (up to a constant)

  • dprior (np.array) – derivative of log-prior probability in respect to theta

  • ddprior (np.array) – second derivative of log-prior probability in respect to theta

get_theta0(G_hat)

Return initial guess for parameters :param G_hat: Crossvalidated estimate of G :type G_hat: np.array

Returns:

theta0 (np.array) – Initial guess for parameters (model.theta0 if given)

predict(theta)

Prediction function: Needs to be implemented

class model.FixedModel(name, G)

Fixed PCM with a rigid predicted G matrix and no parameters

Parameters:

  • name (string) – name of the particular model for indentification

  • G (numpy.ndarray) – 2-dimensional array giving the predicted second moment

predict(theta=None)

Calculation of G

Returns:

  • G (np.ndarray) – 2-dimensional (K,K) array of predicted second moment

  • dG_dTheta (None)

class model.ComponentModel(name, Gc)

Component model class G = sum (exp(theta_i) * Gc_i)

Parameters:

  • name (string) – name of the particular model for indentification

  • Gc (numpy.ndarray) – 3-dimensional array with compoments of G

est_theta0(G_hat)

Sets theta0 based on the crossvalidated second-moment

Parameters:

G_hat (numpy.ndarray) – Crossvalidated estimate of G

predict(theta)

Calculation of G

Parameters:

theta (numpy.ndarray) – Vector of model parameters

Returns:

  • G (np.ndarray) – 2-dimensional (K,K) array of predicted second moment

  • dG_dTheta (np.ndarray) – 3-d (n_param,K,K) array of partial matrix derivatives of G in respect to theta

class model.FeatureModel(name, Ac)

Feature model: A = sum (theta_i * Ac_i) G = A*A’

Parameters:

  • name (string) – name of the particular model for indentification

  • Ac (numpy.ndarray) – 3-dimensional array with components of A

est_theta0(G_hat)

Estimate initial guess for parameters

predict(theta)

Calculation of G

Parameters:

theta (np.ndarray) – Vector of model parameters

Returns:

  • G (np.ndarray) – 2-dimensional (K,K) array of predicted second moment

  • dG_dTheta (np.ndarray) – 3-d (n_param,K,K) array of partial matrix derivatives of G in respect to theta

class model.CorrelationModel(name, within_cov=None, num_items=1, corr=None, cond_effect=False)

Correlation model class for a fixed or flexible correlation model it models the correlation between different items across 2 experimental conditions. Using this paramaterization: var(x) = exp(theta_x)

var(y) = exp(theta_y)

cov(x,y) = sqrt(var(x)*var(y))* r

r = (exp(2*theta_z)-1)/(exp(2*theta_z)+1); % Fisher inverse

Parameters:

  • name (string) – name of the particular model for identification

  • within_cov (numpy.ndarray or None) – how to model within condition cov-variance between items (default None = identity )

  • num_items (int) – Number of items within each condition

  • corr (float or None) – If None, the correlation is a free parameter to be estimated, otherwise it is fixed to the given value

  • cond_effect (bool) – If True, the model includes a condition effect as a random effect. Default False.

est_theta0(G_hat)

gets theta0 based on the crossvalidated second-moment

Parameters:

G_hat (numpy.ndarray) – Crossvalidated estimate of G

get_correlation(theta)

Returns the correlations from a set of fitted parameters

Parameters:

theta (numpy.ndarray) – n_param x n_subj matrix of model parameters

Returns:

correlations (numpy.ndarray) – Correlation value

get_fSNR(theta, n_part=1, separate=False)

Returns the fSNR from a set of fitted parameters

Parameters:

  • theta (numpy.ndarray) – n_param x n_subj matrix of model parameters

  • n_part (int) – Number of partitions (blocks) in the data. Default 1.

  • separate (bool) – If True, returns fSNR for the two conditions separately, otherwise returns the geometric mean of the fSNR values

Returns:

fSNR (numpy.ndarray) – fSNR value

predict(theta)

Calculation of G for a correlation model

Parameters:

theta (numpy.ndarray) – Vector of model parameters

Returns:

  • G (np.ndarray) – 2-dimensional (K,K) array of predicted second moment

  • dG_dTheta (np.ndarray) – 3-d (n_param,K,K) array of partial matrix derivatives of G in respect to theta

class model.FreeModel(name, n_cond)

Free model class: Second moment matrix is G = A*A’, where A is a upper triangular matrix that is flexible

Parameters:

  • name (string) – name of the particular model for indentification

  • n_cond (int) – number of conditions for free model

est_theta0(G_hat)

Sets theta0 based on the crossvalidated second-moment

Parameters:

G_hat (numpy.ndarray) – Crossvalidated estimate of G

predict(theta)

Calculation of G

Parameters:

theta (numpy.ndarray) – Vector of model parameters

Returns:

  • G (np.ndarray) – 2-dimensional (K,K) array of predicted second moment

  • dG_dTheta (np.ndarray) – 3-d (n_param,K,K) array of partial matrix derivatives of G in respect to theta

Noise Model Classes

class model.NoiseModel

Abstract PCM Noise model class

class model.IndependentNoise

Simple Indepdennt noise model (i.i.d) the only parameter is the noise variance

derivative(theta, n=0)

Returns the derivative of S in respect to it’s own parameters

Parameters:

  • theta ([np.array]) – Array like of noiseparamters

  • n (int, optional) – Number of parameter to get derivate for. Defaults to 0.

Returns:

d (np-array) – derivative of S in respective to theta

get_theta0(Y, Z, X=None)

Makes an initial guess on noise paramters

Parameters:

  • Y ([np.array]) – Data

  • Z ([np.array]) – Random Effects matrix

  • X ([np.array], optional) – Fixed effects matrix.

Returns:

theta0 (np.array) – Initial guess for noise parameters

inverse(theta)

Returns S^{-1}

Parameters:

theta ([np.array]) – Array like of noiseparamters

Returns:

s (double) – Inverse of noise variance (scalar)

predict(theta)

Prediction function returns S - predicted noise covariance matrix

Parameters:

theta ([np.array]) – Array like of noiseparamters

Returns:

s (double) – Noise variance (for simplicity as a scalar)

class model.BlockPlusIndepNoise(part_vec)

This noise model uses correlated noise per partition (block) plus independent noise per observation For beta-values from an fMRI analysis, this is an adequate model

Parameters:

part_vec ([np.array]) – vector indicating the block membership for each observation

derivative(theta, n=0)

Returns the derivative of S in respect to it’s own parameters

Parameters:

  • theta (np.array) – Array like of noiseparamters

  • n (int, optional) – Number of parameter to get derivate for. Defaults to 0.

Returns:

d (np.array) – derivative of S in respective to theta

get_theta0(Y, Z, X=None)

Makes an initial guess on noise parameters :param Y: Data :type Y: [np.array] :param Z: Random Effects matrix :type Z: [np.array] :param X: Fixed effects matrix. :type X: [np.array], optional

inverse(theta)

Returns S^{-1}

Parameters:

theta (np.array) – Array like of noiseparamters

Returns:

iS (np.array) – Inverse of noise covariance

predict(theta)

Prediction function returns S - predicted noise covariance matrix

Parameters:

theta ([np.array]) – Array like of noiseparamters

Returns:

s (np.array) – Noise covariance matrix