1""" 

2utilities: common utilities used throughout the code base 

3""" 

4 

5import logging 

6from typing import List, Optional 

7 

8from numpy import fill_diagonal, dot, eye, allclose, ndarray, zeros 

9 

10# set logging 

11logging.basicConfig(level=logging.INFO) 

12logger = logging.getLogger(__name__) 

13 

14 

15def _backend_warning(): 

16 """ 

17 Convenience function for issuing warnings for backend modules. 

18 """ 

19 logging.warning("All code in r_backends is merely a python wrapper over " 

20 "existing DOE packages in R. Code quality and validation " 

21 "supported by underlying R packages.") 

22 

23 

24def _check_int_input(var, input_name: str) -> int: 

25 """ 

26 _check_int_input 

27 

28 Convenience function to check if an input is an int (or a float coercable into an int without 

29 rounding). If the input is not of the expected types it will raise a helpful value error. 

30 

31 Parameters 

32 ---------- 

33 var 

34 the input variable to check 

35 input_name : str 

36 the name of the variable to include if an error is raised 

37 

38 Returns 

39 ------- 

40 int 

41 the input variable coerced into an int 

42 """ 

43 

44 if not isinstance(var, int) and ( 

45 not isinstance(var, float) or not var.is_integer()): 

46 raise ValueError("Input {} must be an integer.".format(input_name)) 

47 

48 return int(var) 

49 

50 

51def _check_str_input(var, input_name: str, valid_options: Optional[List[str]] = None) -> str: 

52 """ 

53 _check_str_input 

54 

55 Convenience function to check if an input is a string. If argument valid_options is given, this 

56 function will also check that var is a valid option from the valid_options specified. 

57 

58 Parameters 

59 ---------- 

60 var 

61 the input variable to check 

62 input_name : str 

63 the name of the variable to include if an error is raised 

64 valid_options: List[str], optional 

65 a list of valid options for var 

66 

67 Returns 

68 ------- 

69 str 

70 the input var after lowering ans stripping the string 

71 """ 

72 

73 if not isinstance(var, str): 

74 raise ValueError("Invalid input {0} for {1}. Input {1} must be a string.".format( 

75 var, input_name)) 

76 

77 var = var.strip().lower() 

78 

79 if valid_options is not None: 

80 valid_options = [option.strip().lower() for option in valid_options] 

81 if var not in valid_options: 

82 raise ValueError("Invalid input {0} for {1}. Input {1} must be one of the following " 

83 "options: {2}.".format(var, input_name, valid_options)) 

84 

85 return var 

86 

87 

88def _check_balanced(arr: ndarray, rtol: float = 1e-07, atol: float = 0.0) -> bool: 

89 """ 

90 

91 Parameters 

92 ---------- 

93 arr 

94 rtol 

95 atol 

96 

97 Returns 

98 ------- 

99 

100 """ 

101 col_sums = arr.sum(axis=0).astype(float) 

102 return allclose( 

103 col_sums, zeros(col_sums.shape[0], dtype=float), 

104 rtol=rtol, atol=atol 

105 ) 

106 

107 

108def _check_orthogonal(arr: ndarray, rtol: float = 1e-07, atol: float = 0.0) -> bool: 

109 """ 

110 

111 Parameters 

112 ---------- 

113 arr : np.ndarray 

114 an array to check for orthogonality 

115 rtol : 

116 atol 

117 

118 Returns 

119 ------- 

120 bool 

121 returns True if orthogonal withing specified tolerances, returns False if not orthogonal 

122 """ 

123 product = dot(arr.T, arr) 

124 fill_diagonal(product, 1.0) 

125 return allclose( 

126 product.astype(float), eye(arr.shape[1], dtype=float), 

127 rtol=rtol, atol=atol 

128 )