Calculate the RDM

neurora.rdm_cal module

a module for calculating the RDM based on multimode neural data

neurora.rdm_cal.bhvRDM(bhv_data, sub_opt=1, method='correlation', abs=False)

Calculate the Representational Dissimilarity Matrix(Matrices) - RDM(s) for behavioral data

Parameters

  • bhv_data (array) – The behavioral data. The shape of bhv_data must be [n_cons, n_subs, n_trials]. n_cons, n_subs & n_trials represent the number of conidtions, the number of subjects & the number of trials, respectively.

  • sub_opt (int 0 or 1. Default is 1.) – Return the results for each subject or after averaging. If sub_opt=1, calculate the results of each subject (using the absolute distance). If sub_opt=0, calculate the results averaging the trials and taking the subjects as the features.

  • method (string 'correlation' or 'euclidean'. Default is 'correlation'.) – The method to calculate the dissimilarities. If method=’correlation’, the dissimilarity is calculated by Pearson Correlation. If method=’euclidean’, the dissimilarity is calculated by Euclidean Distance, the results will be normalized.

  • abs (boolean True or False. Default is True.) – Calculate the absolute value of Pearson r or not. Only works when method=’correlation’.

Returns

RDM(s) – The behavioral RDM. If sub_opt=1, return n_subs RDMs. The shape is [n_subs, n_cons, n_cons]. If sub_opt=0, return only one RDM. The shape is [n_cons, n_cons].

Return type

array

Notes

This function can also be used to calculate the RDM for computational simulation data.

For example, users can extract the activations for a certain layer i which includes Nn nodes in a deep convolutional neural network (DCNN) corresponding to Ni images. Thus, the input could be a [Ni, 1, Nn] matrix M. Using “bhvRDM(M, sub_opt=0)”, users can obtain the DCNN RDM for layer i.

neurora.rdm_cal.eegRDM(EEG_data, sub_opt=1, chl_opt=0, time_opt=0, time_win=5, time_step=5, method='correlation', abs=False)

Calculate the Representational Dissimilarity Matrix(Matrices) - RDM(s) based on EEG-like data

Parameters

  • EEG_data (array) – The EEG/MEG/fNIRS data. The shape of EEGdata must be [n_cons, n_subs, n_trials, n_chls, n_ts]. n_cons, n_subs, n_trials, n_chls & n_ts represent the number of conidtions, the number of subjects, the number of trials, the number of channels & the number of time-points, respectively.

  • sub_opt (int 0 or 1. Default is 1.) – Return the subject-result or average-result. If sub_opt=0, return the average result. If sub_opt=1, return the results of each subject.

  • chl_opt (int 0 or 1. Default is 0.) – Calculate the RDM for each channel or not. If chl_opt=0, calculate the RDM based on all channels’data. If chl_opt=1, calculate the RDMs based on each channel’s data respectively.

  • time_opt (int 0 or 1. Default is 0.) – Calculate the RDM for each time-point or not If time_opt=0, calculate the RDM based on whole time-points’ data. If time_opt=1, calculate the RDMs based on each time-points respectively.

  • time_win (int. Default is 5.) – Set a time-window for calculating the RDM for different time-points. Only when time_opt=1, time_win works. If time_win=5, that means each calculation process based on 5 time-points.

  • time_step (int. Default is 5.) – The time step size for each time of calculating. Only when time_opt=1, time_step works.

  • method (string 'correlation' or 'euclidean'. Default is 'correlation'.) – The method to calculate the dissimilarities. If method=’correlation’, the dissimilarity is calculated by Pearson Correlation. If method=’euclidean’, the dissimilarity is calculated by Euclidean Distance, the results will be normalized.

  • abs (boolean True or False. Default is True.) – Calculate the absolute value of Pearson r or not.

Returns

RDM(s) – The EEG/MEG/fNIR/other EEG-like RDM. If sub_opt=0 & chl_opt=0 & time_opt=0, return only one RDM.

The shape is [n_cons, n_cons].

If sub_opt=0 & chl_opt=0 & time_opt=1, return int((n_ts-time_win)/time_step)+1 RDM.

The shape is [int((n_ts-time_win)/time_step)+1, n_cons, n_cons].

If sub_opt=0 & chl_opt=1 & time_opt=0, return n_chls RDM.

The shape is [n_chls, n_cons, n_cons].

If sub_opt=0 & chl_opt=1 & time_opt=1, return n_chls*(int((n_ts-time_win)/time_step)+1) RDM.

The shape is [n_chls, int((n_ts-time_win)/time_step)+1, n_cons, n_cons].

If sub_opt=1 & chl_opt=0 & time_opt=0, return n_subs RDM.

The shape is [n_subs, n_cons, n_cons].

If sub_opt=1 & chl_opt=0 & time_opt=1, return n_subs*(int((n_ts-time_win)/time_step)+1) RDM.

The shape is [n_subs, int((n_ts-time_win)/time_step)+1, n_cons, n_cons].

If sub_opt=1 & chl_opt=1 & time_opt=0, return n_subs*n_chls RDM.

The shape is [n_subs, n_chls, n_cons, n_cons].

If sub_opt=1 & chl_opt=1 & time_opt=1, return n_subs*n_chls*(int((n_ts-time_win)/time_step)+1) RDM.

The shape is [n_subs, n_chls, int((n_ts-time_win)/time_step)+1, n_cons, n_cons].

Return type

array

Notes

Sometimes, the numbers of trials under different conditions are not same. In NeuroRA, we recommend users to average the trials under a same condition firstly in this situation. Thus, the shape of input (EEG_data) should be [n_cons, n_subs, 1, n_chls, n_ts].

neurora.rdm_cal.eegRDM_bydecoding(EEG_data, sub_opt=1, time_win=5, time_step=5, navg=5, time_opt='average', nfolds=5, nrepeats=2, normalization=False)

Calculate the Representational Dissimilarity Matrix(Matrices) - RDM(s) using classification-based neural decoding based on EEG-like data

Parameters

  • EEG_data (array) – The EEG/MEG/fNIRS data. The shape of EEGdata must be [n_cons, n_subs, n_trials, n_chls, n_ts]. n_cons, n_subs, n_trials, n_chls & n_ts represent the number of conidtions, the number of subjects, the number of trials, the number of channels & the number of time-points, respectively.

  • sub_opt (int 0 or 1. Default is 1.) – Return the subject-result or average-result. If sub_opt=0, return the average result. If sub_opt=1, return the results of each subject.

  • time_win (int. Default is 5.) – Set a time-window for calculating the RDM for different time-points. Only when time_opt=1, time_win works. If time_win=5, that means each calculation process based on 5 time-points.

  • time_step (int. Default is 5.) – The time step size for each time of calculating. Only when time_opt=1, time_step works.

  • navg (int. Default is 5.) – The number of trials used to average.

  • time_opt (string "average" or "features". Default is "average".) – Average the time-points or regard the time points as features for classification If time_opt=”average”, the time-points in a certain time-window will be averaged. If time_opt=”features”, the time-points in a certain time-window will be used as features for classification.

  • nfolds (int. Default is 5.) – The number of folds. k should be at least 2.

  • nrepeats (int. Default is 2.) – The times for iteration.

  • normalization (boolean True or False. Default is False.) – Normalize the data or not.

Returns

RDM(s) – The EEG/MEG/fNIR/other EEG-like RDM. If sub_opt=0, return int((n_ts-time_win)/time_step)+1 RDMs.

The shape is [int((n_ts-time_win)/time_step)+1, n_cons, n_cons].

If sub_opt=1, return n_subs*int((n_ts-time_win)/time_step)+1 RDM.

The shape is [n_subs, int((n_ts-time_win)/time_step)+1, n_cons, n_cons].

Return type

array

Notes

Sometimes, the numbers of trials under different conditions are not same. In NeuroRA, we recommend users to sample randomly from the trials under each conditions to keep the numbers of trials under different conditions same, and you can iterate multiple times.

neurora.rdm_cal.fmriRDM(fmri_data, ksize=[3, 3, 3], strides=[1, 1, 1], sub_opt=1, method='correlation', abs=False)

Calculate the Representational Dissimilarity Matrices (RDMs) based on fMRI data (searchlight)

Parameters

  • fmri_data (array) – The fmri data. The shape of fmri_data must be [n_cons, n_subs, nx, ny, nz]. n_cons, nx, ny, nz represent the number of conditions, the number of subs & the size of fMRI-img, respectively.

  • ksize (array or list [kx, ky, kz]. Default is [3, 3, 3].) – The size of the calculation unit for searchlight. kx, ky, kz represent the number of voxels along the x, y, z axis. kx, ky, kz should be odd.

  • strides (array or list [sx, sy, sz]. Default is [1, 1, 1].) – The strides for calculating along the x, y, z axis.

  • sub_opt (int 0 or 1. Default is 1.) – Return the subject-result or average-result. If sub_opt=0, return the average result. If sub_opt=1, return the results of each subject.

  • method (string 'correlation' or 'euclidean'. Default is 'correlation'.) – The method to calculate the dissimilarities. If method=’correlation’, the dissimilarity is calculated by Pearson Correlation. If method=’euclidean’, the dissimilarity is calculated by Euclidean Distance, the results will be normalized.

  • abs (boolean True or False. Default is True.) – Calculate the absolute value of Pearson r or not.

Returns

RDM – The fMRI-Searchlight RDM. If sub_opt=0, the shape of RDMs is [n_x, n_y, n_z, n_cons, n_cons]. If sub_opt=1, the shape of RDMs is [n_subs, n_x, n_y, n_cons, n_cons] n_subs, n_x, n_y, n_z represent the number of subjects & the number of calculation units for searchlight along the x, y, z axis.

Return type

array

neurora.rdm_cal.fmriRDM_roi(fmri_data, mask_data, sub_opt=1, method='correlation', abs=False)

Calculate the Representational Dissimilarity Matrix - RDM(s) based on fMRI data (for ROI)

Parameters

  • fmri_data (array) – The fmri data. The shape of fmri_data must be [n_cons, n_subs, nx, ny, nz]. n_cons, nx, ny, nz represent the number of conditions, the number of subs & the size of fMRI-img, respectively.

  • mask_data (array [nx, ny, nz].) – The mask data for region of interest (ROI) The size of the fMRI-img. nx, ny, nz represent the number of voxels along the x, y, z axis.

  • sub_opt (int 0 or 1. Default is 1.) – Return the subject-result or average-result. If sub_opt=0, return the average result. If sub_opt=1, return the results of each subject.

  • method (string 'correlation' or 'euclidean'. Default is 'correlation'.) – The method to calculate the dissimilarities. If method=’correlation’, the dissimilarity is calculated by Pearson Correlation. If method=’euclidean’, the dissimilarity is calculated by Euclidean Distance, the results will be normalized.

  • abs (boolean True or False. Default is True.) – Calculate the absolute value of Pearson r or not.

Returns

RDM – The fMRI-ROI RDM. If sub_opt=0, the shape of RDM is [n_cons, n_cons]. If sub_opt=1, the shape of RDM is [n_subs, n_cons, n_cons].

Return type

array

Notes

The sizes (nx, ny, nz) of fmri_data and mask_data should be same.