fix_cor: Fixes an invalid target correlation.

View source: R/permute.R

fix_corR Documentation

Fixes an invalid target correlation.


Shrinks the target correlation using a uniform scaling factor so that the overall correlation matrix is positive semi-definite. The method is described in detail in Gerard (2020).


fix_cor(design_perm, target_cor, num_steps = 51)



A numeric design matrix whose rows are to be permuted (thus controlling the amount by which they are correlated with the surrogate variables). The rows index the samples and the columns index the variables. The intercept should not be included (though see Section "Unestimable Components").


A numeric matrix of target correlations between the variables in design_perm and the surrogate variables. The rows index the observed covariates and the columns index the surrogate variables. That is, target_cor[i, j] specifies the target correlation between the ith column of design_perm and the jth surrogate variable. The surrogate variables are estimated either using factor analysis or surrogate variable analysis (see the parameter use_sva). The number of columns in target_cor specifies the number of surrogate variables. Set target_cor to NULL to indicate that design_perm and the surrogate variables are independent.


The number of steps between 0 and 1 to take in the grid search for the shrinkage factor. The step-size would be 1 / (num_steps - 1).


Let W = cor(design_perm). Let R = target_cor. Then the overall correlation matrix is:

≤ft( \begin{array}{cc} W & R\\ R' & I_K \end{array} \right).

This function applies a multiplicative scaling factor to R until the above matrix is positive semi-definite. That is, it finds a between 0 and 1 such that

≤ft( \begin{array}{cc} W & aR\\ aR' & I_K \end{array} \right)

is positive semi-definite.


A matrix of correlations the same dimension as target_cor. Actually, the returned matrix is a * target_cor, where a was determined to make the overall correlation matrix positive semi-definite.


David Gerard


  • Gerard, D (2020). "Data-based RNA-seq simulations by binomial thinning." BMC Bioinformatics. 21(1), 206. doi: 10.1186/s12859-020-3450-9.


n <- 10
design_perm <- matrix(rep(c(0, 1), length.out = n))
target_cor <- matrix(seq(1, 0, length.out = 10), nrow = 1)
new_cor <- seqgendiff:::fix_cor(design_perm = design_perm, target_cor = target_cor)
new_cor / target_cor

## In the case of one observed covariate, the requirement is just that
## the sum of squared correlations is less than or equal to one.
sum(target_cor ^ 2)
sum(new_cor ^ 2)

seqgendiff documentation built on March 18, 2022, 5:21 p.m.