Hide keyboard shortcuts

Hot-keys on this page

r m x p   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

1import numpy as np 

2 

3from pandas._libs import lib 

4 

5from pandas.core.dtypes.cast import maybe_downcast_to_dtype 

6from pandas.core.dtypes.common import ( 

7 ensure_object, 

8 is_datetime_or_timedelta_dtype, 

9 is_decimal, 

10 is_number, 

11 is_numeric_dtype, 

12 is_scalar, 

13) 

14from pandas.core.dtypes.generic import ABCIndexClass, ABCSeries 

15 

16import pandas as pd 

17 

18 

19def to_numeric(arg, errors="raise", downcast=None): 

20 """ 

21 Convert argument to a numeric type. 

22 

23 The default return dtype is `float64` or `int64` 

24 depending on the data supplied. Use the `downcast` parameter 

25 to obtain other dtypes. 

26 

27 Please note that precision loss may occur if really large numbers 

28 are passed in. Due to the internal limitations of `ndarray`, if 

29 numbers smaller than `-9223372036854775808` (np.iinfo(np.int64).min) 

30 or larger than `18446744073709551615` (np.iinfo(np.uint64).max) are 

31 passed in, it is very likely they will be converted to float so that 

32 they can stored in an `ndarray`. These warnings apply similarly to 

33 `Series` since it internally leverages `ndarray`. 

34 

35 Parameters 

36 ---------- 

37 arg : scalar, list, tuple, 1-d array, or Series 

38 errors : {'ignore', 'raise', 'coerce'}, default 'raise' 

39 - If 'raise', then invalid parsing will raise an exception. 

40 - If 'coerce', then invalid parsing will be set as NaN. 

41 - If 'ignore', then invalid parsing will return the input. 

42 downcast : {'integer', 'signed', 'unsigned', 'float'}, default None 

43 If not None, and if the data has been successfully cast to a 

44 numerical dtype (or if the data was numeric to begin with), 

45 downcast that resulting data to the smallest numerical dtype 

46 possible according to the following rules: 

47 

48 - 'integer' or 'signed': smallest signed int dtype (min.: np.int8) 

49 - 'unsigned': smallest unsigned int dtype (min.: np.uint8) 

50 - 'float': smallest float dtype (min.: np.float32) 

51 

52 As this behaviour is separate from the core conversion to 

53 numeric values, any errors raised during the downcasting 

54 will be surfaced regardless of the value of the 'errors' input. 

55 

56 In addition, downcasting will only occur if the size 

57 of the resulting data's dtype is strictly larger than 

58 the dtype it is to be cast to, so if none of the dtypes 

59 checked satisfy that specification, no downcasting will be 

60 performed on the data. 

61 

62 Returns 

63 ------- 

64 ret : numeric if parsing succeeded. 

65 Return type depends on input. Series if Series, otherwise ndarray. 

66 

67 See Also 

68 -------- 

69 DataFrame.astype : Cast argument to a specified dtype. 

70 to_datetime : Convert argument to datetime. 

71 to_timedelta : Convert argument to timedelta. 

72 numpy.ndarray.astype : Cast a numpy array to a specified type. 

73 convert_dtypes : Convert dtypes. 

74 

75 Examples 

76 -------- 

77 Take separate series and convert to numeric, coercing when told to 

78 

79 >>> s = pd.Series(['1.0', '2', -3]) 

80 >>> pd.to_numeric(s) 

81 0 1.0 

82 1 2.0 

83 2 -3.0 

84 dtype: float64 

85 >>> pd.to_numeric(s, downcast='float') 

86 0 1.0 

87 1 2.0 

88 2 -3.0 

89 dtype: float32 

90 >>> pd.to_numeric(s, downcast='signed') 

91 0 1 

92 1 2 

93 2 -3 

94 dtype: int8 

95 >>> s = pd.Series(['apple', '1.0', '2', -3]) 

96 >>> pd.to_numeric(s, errors='ignore') 

97 0 apple 

98 1 1.0 

99 2 2 

100 3 -3 

101 dtype: object 

102 >>> pd.to_numeric(s, errors='coerce') 

103 0 NaN 

104 1 1.0 

105 2 2.0 

106 3 -3.0 

107 dtype: float64 

108 """ 

109 if downcast not in (None, "integer", "signed", "unsigned", "float"): 

110 raise ValueError("invalid downcasting method provided") 

111 

112 if errors not in ("ignore", "raise", "coerce"): 

113 raise ValueError("invalid error value specified") 

114 

115 is_series = False 

116 is_index = False 

117 is_scalars = False 

118 

119 if isinstance(arg, ABCSeries): 

120 is_series = True 

121 values = arg.values 

122 elif isinstance(arg, ABCIndexClass): 

123 is_index = True 

124 values = arg.asi8 

125 if values is None: 

126 values = arg.values 

127 elif isinstance(arg, (list, tuple)): 

128 values = np.array(arg, dtype="O") 

129 elif is_scalar(arg): 

130 if is_decimal(arg): 

131 return float(arg) 

132 if is_number(arg): 

133 return arg 

134 is_scalars = True 

135 values = np.array([arg], dtype="O") 

136 elif getattr(arg, "ndim", 1) > 1: 

137 raise TypeError("arg must be a list, tuple, 1-d array, or Series") 

138 else: 

139 values = arg 

140 

141 if is_numeric_dtype(values): 

142 pass 

143 elif is_datetime_or_timedelta_dtype(values): 

144 values = values.astype(np.int64) 

145 else: 

146 values = ensure_object(values) 

147 coerce_numeric = errors not in ("ignore", "raise") 

148 try: 

149 values = lib.maybe_convert_numeric( 

150 values, set(), coerce_numeric=coerce_numeric 

151 ) 

152 except (ValueError, TypeError): 

153 if errors == "raise": 

154 raise 

155 

156 # attempt downcast only if the data has been successfully converted 

157 # to a numerical dtype and if a downcast method has been specified 

158 if downcast is not None and is_numeric_dtype(values): 

159 typecodes = None 

160 

161 if downcast in ("integer", "signed"): 

162 typecodes = np.typecodes["Integer"] 

163 elif downcast == "unsigned" and np.min(values) >= 0: 

164 typecodes = np.typecodes["UnsignedInteger"] 

165 elif downcast == "float": 

166 typecodes = np.typecodes["Float"] 

167 

168 # pandas support goes only to np.float32, 

169 # as float dtypes smaller than that are 

170 # extremely rare and not well supported 

171 float_32_char = np.dtype(np.float32).char 

172 float_32_ind = typecodes.index(float_32_char) 

173 typecodes = typecodes[float_32_ind:] 

174 

175 if typecodes is not None: 

176 # from smallest to largest 

177 for dtype in typecodes: 

178 if np.dtype(dtype).itemsize <= values.dtype.itemsize: 

179 values = maybe_downcast_to_dtype(values, dtype) 

180 

181 # successful conversion 

182 if values.dtype == dtype: 

183 break 

184 

185 if is_series: 

186 return pd.Series(values, index=arg.index, name=arg.name) 

187 elif is_index: 

188 # because we want to coerce to numeric if possible, 

189 # do not use _shallow_copy_with_infer 

190 return pd.Index(values, name=arg.name) 

191 elif is_scalars: 

192 return values[0] 

193 else: 

194 return values