| Type: | Package |
| Title: | Flexible Rank-Preserving Correlation Engine |
| Version: | 0.1.4 |
| Description: | Implements a fast, flexible method for simulating continuous variables with specified rank correlations using the Iman–Conover transformation (Iman & Conover, 1982 <doi:10.1080/03610918208812265>) and back-ranking. Includes plotting tools and error-diagnostics. |
| License: | MIT + file LICENSE |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.2 |
| Imports: | ggplot2, MASS, stats |
| Suggests: | knitr, rmarkdown, mvtnorm, microbenchmark |
| VignetteBuilder: | knitr |
| NeedsCompilation: | no |
| Packaged: | 2025-06-26 15:47:25 UTC; w10105397 |
| Author: | Kevin Wells [aut, cre] |
| Maintainer: | Kevin Wells <kevin.e.wells@usm.edu> |
| Repository: | CRAN |
| Date/Publication: | 2025-06-26 16:00:02 UTC |
flexIC: Tunable Iman–Conover Rank-Correlation Imposition
Description
Applies a rank-based correlation structure to a numeric matrix using
a flexible, iterative variant of the Iman–Conover algorithm.
The method reorders each column of x based on the rank structure
of a multivariate normal draw whose correlation matrix matches target_r.
If eps is specified, the algorithm will iteratively draw candidates and
select the one with the closest match to the target Spearman structure.
The marginal distributions of x are preserved exactly.
Usage
flexIC(x, target_r, eps = "none", max_iter = 20)
Arguments
x |
Numeric matrix or data frame. Columns should be independent prior to transformation. |
target_r |
Target Spearman correlation matrix to impose. Must be square, symmetric, and positive-definite. |
eps |
Convergence tolerance (maximum absolute deviation allowed between achieved and target Spearman correlation).
If |
max_iter |
Maximum number of candidate draws to evaluate when |
Value
A numeric matrix with same dimensions as x, with transformed columns preserving marginal distributions
and approximately matching the specified rank correlation structure.
Examples
set.seed(1)
x <- cbind(rexp(100), rbinom(100, 5, 0.4))
R_target <- matrix(c(1, 0.6, 0.6, 1), 2)
out <- flexIC(x, R_target, eps = 0.02, max_iter = 50)
cor(out, method = "spearman")
One-Shot Iman–Conover Transformation
Description
Applies the classic Iman–Conover procedure to reorder the columns of a numeric matrix to approximately match a target rank correlation structure, while preserving marginals.
Usage
ic_exact(x, target_r)
Arguments
x |
A numeric matrix or data frame with independent columns (desired marginals). |
target_r |
A square, positive-definite correlation matrix to impose. |
Value
A numeric matrix with the same marginal distributions as x and
approximately matching the target Spearman correlation.
Examples
set.seed(123)
x <- matrix(rnorm(300), ncol = 3)
R_target <- matrix(c(1, 0.5, 0.3,
0.5, 1, 0.4,
0.3, 0.4, 1), 3)
out <- ic_exact(x, R_target)
cor(out, method = "spearman")
Facetted histograms of marginals before and after flexIC
Description
Facetted histograms of marginals before and after flexIC
Arguments
original |
Matrix or data frame of the original variables. |
flex_out |
Either the list returned by |
bins |
Number of histogram bins. |
after_lab |
Facet-strip label for the post-flexIC panel. |
Value
A ggplot object (returned invisibly).
Examples
set.seed(1)
x <- matrix(rnorm(300), ncol = 3)
target <- cor(x, method = "spearman")
fo <- flexIC(x, target, eps = 0.02, max_iter = 5)
plot_marginals_grid(x, fo, bins = 30)