function ds_sa = cosmo_target_dsm_corr_measure(ds, varargin)
% measure correlation with target dissimilarity matrix
%
% ds_sa = cosmo_target_dsm_corr_measure(dataset, args)
%
% Inputs:
% ds dataset struct with field .samples PxQ for P samples and
% Q features
% args struct with fields:
% .target_dsm (optional) Either:
% - target dissimilarity matrix of size PxP. It should
% have zeros on the diagonal and be symmetric.
% - target dissimilarity vector of size Nx1, with
% N=P*(P-1)/2 the number of pairs of samples in ds.
% This option is mutually exclusive with the 'glm_dsm'
% option
% .metric (optional) distance metric used in pdist to compute
% pair-wise distances between samples in ds. It accepts
% any metric supported by pdist (default: 'correlation')
% .type (optional) type of correlation between target_dsm and
% ds, one of 'Pearson' (default), 'Spearman', or
% 'Kendall'. If the 'regress_dsm' option is used, then the
% specified correlation type is used for the partial
% correlaton computation, and a Pearson correlation
% is returned on the residuals (that is, the
% remaining dissimilarities after controlling for those
% in regress_dsm).
% .regress_dsm (optional) target dissimilarity matrix or vector (as
% .target_dsm), or a cell with matrices or vectors, that
% should be regressed out. If this option is provided then
% the output is the partial (Pearson) correlation between
% the pairwise distances between samples in ds and
% target_dsm, after controlling for the effect of the
% matrix (or matrices) in regress_dsm. (Using this option
% yields similar behaviour as the Matlab function
% 'partial_corr').
% When using this option, the 'type' option cannot be
% set to 'Kendall'.
% .glm_dsm (optional) cell with model dissimilarity matrices or
% vectors (as .target_dsm) for using a general linear
% model to get regression coefficients for each element in
% .glm_dsm. Both the input data and the dissimilarity
% matrices are z-scored before estimating the regression
% coefficients.
% This option is required when 'target_dsm' is not
% provided; it cannot cannot used together with the
% 'target_dsm' or 'regress_dsm' options.
% When using this option, the 'type' option cannot be
% set to 'Spearman' or 'Kendall'.
% For this option, the output has as many rows (samples)
% as there are elements (dissimilarity matrices) in
% .glm_dsm.
% .center_data If set to true, then the mean of each feature (column in
% ds.samples) is subtracted from each column prior to
% computing the pairwise distances for all samples in ds.
% This is generally recommended but is not the default in
% order to avoid breaking behavaiour from earlier
% versions. For a rationale why this is recommendable, see
% the Diedrichsen & Kriegeskorte article (below in
% references)
% Default: false
%
% Output:
% ds_sa Dataset struct with fields:
% .samples Scalar correlation value between the pair-wise
% distances of the samples in ds and target_dsm; or
% (when 'glm_dsms' is supplied) a column vector with
% normalized beta coefficients. These values
% are untransformed (e.g. there is no Fisher transform).
% .sa Struct with field:
% .labels {'rho'}; or (when 'glm_dsm' is supplied) a cell
% {'beta1','beta2',...}.
%
% Examples:
% % generate synthetic dataset with 6 classes (conditions),
% % one sample per class
% ds=cosmo_synthetic_dataset('ntargets',6,'nchunks',1);
% %
% % create target dissimilarity matrix to test whether
% % - class 1 and 2 are similar (and different from classes 3-6)
% % - class 3 and 4 are similar (and different from classes 1,2,5,6)
% % - class 5 and 6 are similar (and different from classes 1-4)
% target_dsm=1-kron(eye(3),ones(2));
% %
% % show the target dissimilarity matrix
% cosmo_disp(target_dsm);
% %|| [ 0 0 1 1 1 1
% %|| 0 0 1 1 1 1
% %|| 1 1 0 0 1 1
% %|| 1 1 0 0 1 1
% %|| 1 1 1 1 0 0
% %|| 1 1 1 1 0 0 ]
% %
% % compute similarity between pairw-wise similarity of the
% % patterns in the dataset and the target dissimilarity matrix
% dcm_ds=cosmo_target_dsm_corr_measure(ds,'target_dsm',target_dsm);
% %
% % Pearson correlation is about 0.56
% cosmo_disp(dcm_ds)
% %|| .samples
% %|| [ 0.562 ]
% %|| .sa
% %|| .labels
% %|| { 'rho' }
% %|| .metric
% %|| { 'correlation' }
% %|| .type
% %|| { 'Pearson' }
% %
% % do not consider classses 3 and 5
% target_dsm([3,5],:)=NaN;
% target_dsm(:,[3,5])=NaN;
% target_dsm(3,3)=0;
% target_dsm(5,5)=0;
% %
% % show the updated target dissimilarity matrix
% cosmo_disp(target_dsm);
% %|| [ 0 0 NaN 1 NaN 1
% %|| 0 0 NaN 1 NaN 1
% %|| NaN NaN 0 NaN NaN NaN
% %|| 1 1 NaN 0 NaN 1
% %|| NaN NaN NaN NaN 0 NaN
% %|| 1 1 NaN 1 NaN 0 ]
% %
% % compute similarity between pairw-wise similarity of the
% % patterns in the dataset and the target dissimilarity matrix
% dcm_ds=cosmo_target_dsm_corr_measure(ds,'target_dsm',target_dsm);
% %
% % Correlation is different because classes 3 and 5 were left out
% cosmo_disp(dcm_ds)
% %|| .samples
% %|| [ 0.705 ]
% %|| .sa
% %|| .labels
% %|| { 'rho' }
% %|| .metric
% %|| { 'correlation' }
% %|| .type
% %|| { 'Pearson' }
%
%
%
% Notes:
% - for group analysis, correlations can be fisher-transformed
% through:
% dcm_ds.samples=atanh(dcm_ds.samples)
% - it is recommended to set the 'center_data' to true when using
% the default 'correlation' metric, as this removes a main effect
% common to all samples; but note that this option is disabled by
% default due to historical reasons.
% - elements in the *_dsm dissimilarity matrices can have NaNs, in which
% case their value, as well as the corresponding location in the
% dataset's samples, are ignored. Masking is done prior to z-score
% normalization.
%
% Reference:
% - Diedrichsen, J., & Kriegeskorte, N. (2017). Representational
% models: A common framework for understanding encoding,
% pattern-component, and representational-similarity analysis.
% PLoS computational biology, 13(4), e1005508.
%
%
% # For CoSMoMVPA's copyright information and license terms, #
% # see the COPYING file distributed with CoSMoMVPA. #
