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 eps = "none", no convergence test is performed and the first draw is used (equivalent to classic Iman–Conover).

max_iter

Maximum number of candidate draws to evaluate when eps is numeric.

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 flexIC() or the transformed numeric matrix itself.

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)