Inference module

Inference module for PCM toolbox with main functionality for model fitting and evaluation. @author: jdiedrichsen

inference.fit_model_group(Data, M, fixed_effect='block', fit_scale=False, scale_prior=1000.0, noise_cov=None, algorithm=None, optim_param={}, theta0=None, verbose=True, return_second_deriv=False)

Fits PCM models(s) to a group of subjects

The model parameters are (by default) shared across subjects. Scale and noise parameters are individual for each subject. Some model parameters can also be made individual by setting M.common_param

Parameters:
  • Data (list of pcm.Datasets) – List data set has partition and condition descriptors

  • M (pcm.Model or list of pcm.Models) – Models to be fitted on the data sets. Optional field M.common_param indicates which model parameters are common to the group (True) and which ones are fit individually (False)

  • effect (fixed) – None, ‘block’, or nd-array / list of nd-arrays. Default (‘block’) add an intercept for each partition

  • fit_scale (bool) – Fit a additional scale parameter for each subject? Default is set to False.

  • scale_prior (float) – Prior variance for log-normal prior on scale parameter

  • algorithm (string) – Either ‘newton’ or ‘minimize’ - provides over-write for model specific algorithms

  • noise_cov – None (i.i.d), ‘block’, or optional specific covariance structure of the noise

  • optim_param (dict) – Additional paramters to be passed to the optimizer

  • theta0 (list of np.arrays) – List of starting values (same format as return argument theta)

  • verbose (bool) – Provide printout of progress? Default: True

Returns:
  • T (pandas.dataframe) – Dataframe with the fields: SN: Subject number likelihood: log-likelihood scale: Scale parameter (if fitscale = 1)-exp(theta_s) noise: Noise parameter- exp(theta_eps) iterations: Number of interations for model fit time: Elapsed time in sec

  • theta (list of np.arrays) – List of estimated model parameters each one is a vector with #num_commonparams + #num_singleparams x #numSubj elements

  • G_pred (list of np.arrays) – List of estimated G-matrices under the model

inference.fit_model_group_crossval(Data, M, fixed_effect='block', fit_scale=False, scale_prior=1000.0, noise_cov=None, algorithm=None, optim_param={}, theta0=None, verbose=True)

Fits PCM model(sto N-1 subjects and evaluates the likelihood on the Nth subject.

Only the common model parameters are shared across subjects.The scale and noise parameters are still fitted to each subject. Some model parameters can also be made individual by setting M.common_param to False

Parameters:
  • Data (list of pcm.Datasets) – List data set has partition and condition descriptors

  • M (pcm.Model or list of pcm.Models) – Models to be fitted on the data sets. Optional field M.common_param indicates which model parameters are common to the group (True) and which ones are fit individually (False)

  • effect (fixed) – None, ‘block’, or nd-array. Default (‘block’) add an intercept for each partition

  • fit_scale (bool) – Fit a additional scale parameter for each subject? Default is set to False.

  • scale_prior (float) – Prior variance for log-normal prior on scale parameter

  • algorithm (string) – Either ‘newton’ or ‘minimize’ - provides over-write for model specific algorithms

  • noise_cov – None (i.i.d), ‘block’, or optional specific covariance structure of the noise

  • optim_param (dict) – Additional paramters to be passed to the optimizer

  • theta0 (list of np.arrays) – List of starting values (same format as return argument theta)

  • verbose (bool) – Provide printout of progress? Default: True

Returns:
  • T (pandas.dataframe) – Dataframe with the fields: SN: Subject number likelihood: log-likelihood scale: Scale parameter (if fitscale = 1)-exp(theta_s) noise: Noise parameter- exp(theta_eps) iterations: Number of interations for model fit time: Elapsed time in sec

  • theta (list of np.arrays) – List of estimated model parameters - common group parameters come from the training data, individual parameters from the testing data

  • G_pred (list of np.arrays) – List of estimated G-matrices under the model

inference.fit_model_individ(Data, M, fixed_effect='block', fit_scale=False, scale_prior=1000.0, noise_cov=None, algorithm=None, optim_param={}, theta0=None, verbose=True, return_second_deriv=False)

Fits Models to a data set individually.

The model parameters are all individually fit.

Parameters:
  • Data (pcm.Dataset or list of pcm.Datasets) – List data set has partition and condition descriptors

  • M (pcm.Model or list of pcm.Models) – Models to be fitted on the data sets

  • effect (fixed) – None, ‘block’, or nd-array. Default (‘block’) adds an intercept for each partition

  • fit_scale (bool) – Fit a additional scale parameter for each subject? Default is set to False.

  • scale_prior (float) – Prior variance for log-normal prior on scale parameter

  • algorithm (string) – Either ‘newton’ or ‘minimize’ - provides over-write for model specific algorithms

  • noise_cov – None (i.i.d), ‘block’, or optional specific covariance structure of the noise

  • optim_param (dict) – Additional paramters to be passed to the optimizer

  • theta0 (list of np.arrays) – List of starting values (same format as return argument theta)

  • verbose (bool) – Provide printout of progress? Default: True

Returns:
  • T (pandas.dataframe) – Dataframe with the fields: SN: Subject number likelihood: log-likelihood scale: Scale parameter (if fitscale = 1)-exp(theta_s) noise: Noise parameter- exp(theta_eps) run: Run parameter (if run = ‘random’) iterations: Number of interations for model fit time: Elapsed time in sec

  • theta (list of np.arrays) – List of estimated model parameters, each a #params x #numSubj np.array

  • G_pred (list of np.arrays) – List of estimated G-matrices under the model

inference.get_scale0(G, G_hat)

” Get approximate (log-)scaling parameter between predicted G and estimated G_hat

Parameters:
  • G (numpy.ndarray0) – Predicted G matrix by the model

  • G_hat (numpy.ndarry0) – Directly estimated G from the data

Returns:

scale0 – log-scaling parameter

inference.group_to_individ_param(theta, M, n_subj)

Takes a vector of group parameters and rearranges them To make it conform to theta you would get back from a individual fit

Parameters:
  • theta (nd.array) – Vector of group parameters

  • M (pcm.Model) – PCM model

  • n_subj (int) – Number of subjects

Returns:

theta_indiv (ndarray) – n_params x n_subj Matrix of group parameters

inference.likelihood_group(theta, M, YY, Z, X=None, Noise=<PcmPy.model.IndependentNoise object>, n_channel=1, fit_scale=True, scale_prior=1000.0, return_deriv=0, return_individ=False)

Negative Log-Likelihood of group data and derivative in respect to the parameters

Parameters:
  • theta (np.array) – Vector of (log-)model parameters consisting of common model parameters (M.n_param or sum of M.common_param) + participant-specific parameters (interated by subject): individ model param (not in common_param), scale parameter,noise parameters

  • M (pcm.Model) – Model object

  • YY (List of np.arrays) – List of NxN Matrix of outer product of the activity data (Y*Y’)

  • Z (List of 2d-np.array) – NxQ Design matrix - relating the trials (N) to the random effects (Q)

  • X (List of np.array) – Fixed effects design matrix - will be accounted for by ReML

  • Noise (List of pcm.Noisemodel) – Pcm-noise model (default: IndependentNoise)

  • n_channel (List of int) – Number of channels

  • fit_scale (bool) – Fit a scaling parameter for the model (default is False)

  • scale_prior (float) – Prior variance for log-normal prior on scale parameter

  • return_deriv (int) – 0: Only return negative likelihood 1: Return first derivative 2: Return first and second derivative (default)

  • return_individ (bool) – return individual likelihoods instead of group likelihood

  • return_deriv – 0:None, 1:First, 2: second

Returns:
  • negloglike – Negative log-likelihood of the data under a model

  • dLdtheta (1d-np.array) – First derivative of negloglike in respect to the parameters

  • ddLdtheta2 (2d-np.array) – Second derivative of negloglike in respect to the parameters

inference.likelihood_individ(theta, M, YY, Z, X=None, Noise=<PcmPy.model.IndependentNoise object>, n_channel=1, fit_scale=False, scale_prior=1000.0, return_deriv=0)

Negative Log-Likelihood of the data and derivative in respect to the parameters

Parameters:
  • theta (np.array) – Vector of (log-)model parameters - these include model, signal, and noise parameters

  • M (PcmPy.model.Model) – Model object with predict function

  • YY (2d-np.array) – NxN Matrix of outer product of the activity data (Y*Y’)

  • Z (2d-np.array) – NxQ Design matrix - relating the trials (N) to the random effects (Q)

  • X (np.array) – Fixed effects design matrix - will be accounted for by ReML

  • Noise (pcm.Noisemodel) – Pcm-noise mode to model block-effects (default: IndepenentNoise)

  • n_channel (int) – Number of channels

  • fit_scale (bool) – Fit a scaling parameter for the model (default is False)

  • scale_prior (float) – Prior variance for log-normal prior on scale parameter

  • return_deriv (int) – 0: Only return negative loglikelihood 1: Return first derivative 2: Return first and second derivative (default)

Returns:
  • negloglike (double) – Negative log-likelihood of the data under a model

  • dLdtheta (1d-np.array) – First derivative of negloglike in respect to the fitted parameters

  • ddLdtheta2 (2d-np.array) – Second derivative of negloglike in respect to the fitted parameters

inference.sample_model_group(Data, M, fixed_effect='block', fit_scale=False, scale_prior=1000.0, noise_cov=None, sample_param={'burn_in': 100, 'n_samples': 10000}, theta0=None, verbose=True, proposal_sd=None)

Approximates the posterior of the parameters of a group model using MCMC sampling

The model parameters are (by default) shared across subjects. Scale and noise parameters are individual for each subject. Some model parameters can also be made individual by setting M.common_param

Parameters:
  • Data (list of pcm.Datasets) – List data set has partition and condition descriptors

  • M (pcm.Model) – Models to sampled

  • effect (fixed) – None, ‘block’, or nd-array / list of nd-arrays. Default (‘block’) add an intercept for each partition

  • fit_scale (bool) – Fit a additional scale parameter for each subject? Default is set to False.

  • scale_prior (float) – Prior variance for log-normal prior on scale parameter

  • noise_cov – None (i.i.d), ‘block’, or optional specific covariance structure of the noise

  • sample_param (dict) – Additional paramters to be passed to MCMC sampler

  • theta0 (np.array) – starting values

Returns:
  • theta (np.array) – Sampled parameters

  • l (np.array) – Log-likelihood corresponding to the sampled parameters

  • G_pred (list of np.arrays) – List of estimated G-matrices under the model

inference.set_up_fit(Data, fixed_effect='block', noise_cov=None)

Utility routine pre-calculates and sets design matrices, etc for the PCM fit

Parameters:
  • Data (pcm.dataset) – Contains activity data (measurement), and obs_descriptors partition and condition

  • fixed_effect – Can be None, ‘block’, or a design matrix. ‘block’ includes an intercept for each partition.

  • noise_cov – Can be None: (i.i.d noise), ‘block’: a common noise paramter or a List of noise covariances for the different partitions

Returns:
  • Z (np.array) – Design matrix for random effects

  • X (np.array) – Design matrix for fixed effects

  • YY (np.array) – Quadratic form of the data (Y Y’)

  • Noise (pcm.model.NoiseModel) – Noise model

  • G_hat (np.array) – Crossvalidated estimate of second moment of U

inference.set_up_fit_group(Data, fixed_effect='block', noise_cov=None)

Pre-calculates and sets design matrices, etc for the PCM fit for a full group

Parameters:
  • Data (list of pcm.dataset) – Contains activity data (measurement), and obs_descriptors partition and condition

  • fixed_effect – Can be None, ‘block’, or a design matrix. ‘block’ includes an intercept for each partition.

  • noise_cov – Can be None: (i.i.d noise), ‘block’: a common noise paramter or a List of noise covariances for the different partitions

Returns:
  • Z (np.array) – Design matrix for random effects

  • X (np.array) – Design matrix for fixed effects

  • YY (np.array) – Quadratic form of the data (Y Y’)

  • Noise (NoiseModel) – Noise model

  • G_hat (np.array) – Crossvalidated estimate of second moment of U