Package 'flexIC'

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)

---