Coverage for src / cvx / risk / linalg / valid.py: 100%

1"""Matrix validation utilities for handling non-finite values. 

2 

3This module provides functions for validating and cleaning matrices that may 

4contain non-finite values (NaN or infinity). This is particularly useful when 

5working with financial data where missing values are common. 

6 

7Example: 

8 Extract the valid submatrix from a covariance matrix with missing data: 

9 

10 >>> import numpy as np 

11 >>> from cvx.risk.linalg import valid 

12 >>> # Create a covariance matrix with some NaN values on diagonal 

13 >>> cov = np.array([[np.nan, 0.5, 0.2], 

14 ... [0.5, 2.0, 0.3], 

15 ... [0.2, 0.3, np.nan]]) 

16 >>> # Get valid indicator and submatrix 

17 >>> v, submatrix = valid(cov) 

18 >>> v # Second row/column is valid 

19 array([False, True, False]) 

20 >>> submatrix 

21 array([[2.]]) 

22 

23""" 

24 

25# Copyright 2023 Stanford University Convex Optimization Group 

26# 

27# Licensed under the Apache License, Version 2.0 (the "License"); 

28# you may not use this file except in compliance with the License. 

29# You may obtain a copy of the License at 

30# 

31# http://www.apache.org/licenses/LICENSE-2.0 

32# 

33# Unless required by applicable law or agreed to in writing, software 

34# distributed under the License is distributed on an "AS IS" BASIS, 

35# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 

36# See the License for the specific language governing permissions and 

37# limitations under the License. 

38from __future__ import annotations 

39 

40import numpy as np 

41 

42 

43def valid(matrix: np.ndarray) -> tuple[np.ndarray, np.ndarray]: 

44 """Extract the valid subset of a matrix by removing rows/columns with non-finite values. 

45 

46 This function identifies rows and columns in a square matrix that contain 

47 non-finite values (NaN or infinity) on the diagonal and removes them, 

48 returning both the indicator vector and the resulting valid submatrix. 

49 

50 This is useful when working with covariance matrices where some assets 

51 may have missing or invalid data. 

52 

53 Args: 

54 matrix: A square n x n matrix to be validated. Typically a covariance 

55 or correlation matrix. 

56 

57 Returns: 

58 A tuple containing: 

59 - v: Boolean vector of shape (n,) indicating which rows/columns are 

60 valid (True for valid, False for invalid). 

61 - submatrix: The valid submatrix with invalid rows/columns removed. 

62 Shape is (k, k) where k is the number of True values in v. 

63 

64 Raises: 

65 AssertionError: If the input matrix is not square (n x n). 

66 

67 Example: 

68 Basic usage with a covariance matrix: 

69 

70 >>> import numpy as np 

71 >>> from cvx.risk.linalg import valid 

72 >>> # Create a 3x3 matrix with one invalid entry 

73 >>> cov = np.array([[1.0, 0.5, 0.2], 

74 ... [0.5, np.nan, 0.3], 

75 ... [0.2, 0.3, 1.0]]) 

76 >>> v, submatrix = valid(cov) 

77 >>> v 

78 array([ True, False, True]) 

79 >>> submatrix 

80 array([[1. , 0.2], 

81 [0.2, 1. ]]) 

82 

83 Handling a fully valid matrix: 

84 

85 >>> cov = np.array([[1.0, 0.5], [0.5, 1.0]]) 

86 >>> v, submatrix = valid(cov) 

87 >>> v 

88 array([ True, True]) 

89 >>> np.allclose(submatrix, cov) 

90 True 

91 

92 Note: 

93 The function checks only the diagonal elements for validity. It assumes 

94 that if the diagonal is finite, the entire row/column is valid. This is 

95 a common assumption for covariance matrices. 

96 

97 """ 

98 # make sure matrix is quadratic 

99 if matrix.shape[0] != matrix.shape[1]: 

100 raise AssertionError 

101 

102 v = np.isfinite(np.diag(matrix)) 

103 return v, matrix[:, v][v]