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
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 toNone
(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 toNone
(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 toNone
(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.