Knockoff S-Matrix Generation API Reference

MAC-Minimizing Knockoffs

knockpy.mac.calc_min_group_eigenvalue(Sigma, groups, tol=1e-05, verbose=False)[source]

Calculates the minimum “group” eigenvalue of a covariance matrix Sigma: see Dai and Barber 2016. This is useful for constructing equicorrelated (group) knockoffs.

knockpy.mac.solve_SDP(Sigma, verbose=False, num_iter=10, tol=1e-05)[source]

Solves ungrouped SDP to create S-matrix for MAC-minimizing knockoffs.

Parameters
Sigmanp.ndarray

(p, p)-shaped covariance matrix of X

verbosebool

If True, prints updates during optimization.

num_iterint

Number of iterations in a final binary search to account for numerical errors and ensure 2Sigma - S is PSD.

tolfloat

Minimum permissible eigenvalue of 2Sigma - S and S.

Returns
Snp.ndarray

(p, p)-shaped diagonal S-matrix used to generate knockoffs

knockpy.mac.solve_equicorrelated(Sigma, groups, tol=1e-05, verbose=False, num_iter=10)[source]

Calculates the block diagonal matrix S using the equicorrelated method described by Dai and Barber 2016.

Parameters
Sigmanp.ndarray

(p, p)-shaped covariance matrix of X

groupsnp.ndarray

For group knockoffs, a p-length array of integers from 1 to num_groups such that groups[j] == i indicates that variable j is a member of group i. Defaults to None (regular knockoffs).

tolfloat

Minimum permissible eigenvalue of 2Sigma - S and S.

Returns
Snp.ndarray

(p, p)-shaped (block) diagonal matrix used to generate knockoffs

knockpy.mac.solve_group_SDP(Sigma, groups=None, verbose=False, objective='abs', norm_type=2, num_iter=10, tol=1e-05, **kwargs)[source]

Solves the MAC-minimizng SDP formulation for group knockoffs: extends Barer and Candes 2015/ Candes et al 2018.

Sigmanp.ndarray

(p, p)-shaped covariance matrix of X

groupsnp.ndarray

For group knockoffs, a p-length array of integers from 1 to num_groups such that groups[j] == i indicates that variable j is a member of group i. Defaults to None (regular knockoffs).

verbosebool

If True, prints updates during optimization.

objectivestr

How to optimize the S matrix for group knockoffs. There are several options: - ‘abs’: minimize sum(abs(Sigma - S)) - ‘pnorm’: minimize Lp-th matrix norm. - ‘norm’: minimize different type of matrix norm (see norm_type below).

norm_typestr or int
  • When objective == ‘pnorm’, a float specifying which Lp-th matrix norm

to use. Can be any float >= 1. - When objective == ‘norm’, can be ‘fro’, ‘nuc’, np.inf, or 1.

num_iterint

Number of iterations in a final binary search to account for numerical errors and ensure 2Sigma - S is PSD.

tolfloat

Minimum permissible eigenvalue of 2Sigma - S and S.

kwargsdict

Keyword arguments to pass to the cvxpy.Problem.solve() method.

Returns
Snp.ndarray

(p, p)-shaped (block) diagonal matrix used to generate knockoffs

Minimum Reconstructability Knockoffs

Methods for minimum-reconstructability knockoffs.

knockpy.mrc.mmi_loss(Sigma, S, smoothing=0)[source]

Computes the log determinant of the feature-knockoff covariance matrix, which is inversely related to the mutual information between X and XK.

Parameters
Sigmanp.ndarray

(p, p)-shaped covariance matrix of X

Snp.ndarray

(p, p)-shaped S-matrix used to generate knockoffs

smoothingfloat

Add smoothing to all eigenvalues of the feature-knockoff precision matrix before taking the log determinant to avoid numerical instability. Defaults to 0.

Returns
lossfloat

The MMI loss for Sigma and S.

knockpy.mrc.mvr_loss(Sigma, S, smoothing=0)[source]

Computes minimum variance-based reconstructability loss for knockoffs, e.g., the trace of the feature-knockoff precision matrix.

Parameters
Sigmanp.ndarray

(p, p)-shaped covariance matrix of X

Snp.ndarray

(p, p)-shaped S-matrix used to generate knockoffs

smoothingfloat

Add smoothing to all eigenvalues of the feature-knockoff precision matrix before inverting to avoid numerical instability. Defaults to 0.

Returns
lossfloat

The MVR loss for Sigma and S.

knockpy.mrc.solve_ciknock(Sigma, tol=1e-05, num_iter=10)[source]

Computes S-matrix used to generate conditional independence knockoffs.

Parameters
Sigmanp.ndarray

(p, p)-shaped covariance matrix of X

tolfloat

Minimum permissible eigenvalue of 2Sigma - S and S.

num_iterint

The number of iterations in the binary search to ensure S is feasible.

Returns
Snp.ndarray

(p, p)-shaped (block) diagonal matrix used to generate knockoffs

Notes

When the S-matrix corresponding to conditional independence knockoffs is not feasible, this computes that S matrix and then does a binary search to find the maximum gamma such that gamma * S is feasible.

knockpy.mrc.solve_mmi(Sigma, tol=1e-05, verbose=False, num_iter=10, smoothing=0, converge_tol=0.0001)[source]

Computes S-matrix used to generate minimum mutual information knockoffs using coordinate descent.

Parameters
Sigmanp.ndarray

(p, p)-shaped covariance matrix of X

tolfloat

Minimum permissible eigenvalue of 2Sigma - S and S.

verbosebool

If True, prints updates during optimization.

num_iterint

The number of coordinate descent iterations. Defaults to 10.

smoothingfloat

Add smoothing to all eigenvalues of the feature-knockoff precision matrix before inverting to avoid numerical instability. Defaults to 0.

converge_tolfloat

A parameter specifying the criteria for convergence.

Returns
Snp.ndarray

(p, p)-shaped (block) diagonal matrix used to generate knockoffs

knockpy.mrc.solve_mvr(Sigma, tol=1e-05, verbose=False, num_iter=10, smoothing=0, rej_rate=0, converge_tol=1)[source]

Computes S-matrix used to generate minimum variance-based reconstructability knockoffs using coordinate descent.

Parameters
Sigmanp.ndarray

(p, p)-shaped covariance matrix of X

tolfloat

Minimum permissible eigenvalue of 2Sigma - S and S.

verbosebool

If True, prints updates during optimization.

num_iterint

The number of coordinate descent iterations. Defaults to 10.

smoothingfloat

Add smoothing to all eigenvalues of the feature-knockoff precision matrix before inverting to avoid numerical instability. Defaults to 0.

converge_tolfloat

A parameter specifying the criteria for convergence.

Returns
Snp.ndarray

(p, p)-shaped (block) diagonal matrix used to generate knockoffs

API Rerefence: knockpy.smatrix

knockpy.smatrix.compute_smatrix(Sigma, groups=None, method=None, solver='cd', max_block=1000, num_processes=1, **kwargs)[source]

Wraps a variety of S-matrix generation functions. For mvr, mmi, and sdp methods, this uses a block-diagonal approximation of Sigma if the dimension of Sigma exceeds max_block.

Parameters
Sigmanp.ndarray
``(p, p)``-shaped covariance matrix of X
groupsnp.ndarray

For group knockoffs, a p-length array of integers from 1 to num_groups such that groups[j] == i indicates that variable j is a member of group i. Defaults to None (regular knockoffs).

methodstr

Method for constructing S-matrix. One of mvr, mmi, sdp, equicorrelated, ci.

solverstr

Method for solving mrc knockoffs. One of ‘cd’ (coordinate descent) or ‘psgd’ (projected gradient descent). Coordinate descent is highly recommended.

max_blockint

The maximum size of a block in a block-diagonal approximation of Sigma.

num_processesint

Number of parallel process to use if Sigma is approximated as a block-diagonal matrix.

kwargsdict

kwargs to pass to one of the wrapped S-matrix solvers.

Returns
Snp.ndarray

(p, p)-shaped (block) diagonal matrix used to generate knockoffs

knockpy.smatrix.divide_computation(Sigma, max_block)[source]

Approximates a correlation matrix Sigma as a block-diagonal matrix using hierarchical clustering. Roughly follows the R knockoff package.

knockpy.smatrix.merge_groups(groups, max_block)[source]

Merges groups of variables together while ensuring all new groups have size less than max_block.

knockpy.smatrix.parse_method(method, groups, p)[source]

Decides which method to use to create the knockoff S matrix