Coverage for /home/martinb/.local/share/virtualenvs/camcops/lib/python3.6/site-packages/numpy/lib/ufunclike.py : 49%

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
1"""
2Module of functions that are like ufuncs in acting on arrays and optionally
3storing results in an output array.
5"""
6__all__ = ['fix', 'isneginf', 'isposinf']
8import numpy.core.numeric as nx
9from numpy.core.overrides import (
10 array_function_dispatch, ARRAY_FUNCTION_ENABLED,
11)
12import warnings
13import functools
16def _deprecate_out_named_y(f):
17 """
18 Allow the out argument to be passed as the name `y` (deprecated)
20 In future, this decorator should be removed.
21 """
22 @functools.wraps(f)
23 def func(x, out=None, **kwargs):
24 if 'y' in kwargs:
25 if 'out' in kwargs:
26 raise TypeError(
27 "{} got multiple values for argument 'out'/'y'"
28 .format(f.__name__)
29 )
30 out = kwargs.pop('y')
31 # NumPy 1.13.0, 2017-04-26
32 warnings.warn(
33 "The name of the out argument to {} has changed from `y` to "
34 "`out`, to match other ufuncs.".format(f.__name__),
35 DeprecationWarning, stacklevel=3)
36 return f(x, out=out, **kwargs)
38 return func
41def _fix_out_named_y(f):
42 """
43 Allow the out argument to be passed as the name `y` (deprecated)
45 This decorator should only be used if _deprecate_out_named_y is used on
46 a corresponding dispatcher function.
47 """
48 @functools.wraps(f)
49 def func(x, out=None, **kwargs):
50 if 'y' in kwargs:
51 # we already did error checking in _deprecate_out_named_y
52 out = kwargs.pop('y')
53 return f(x, out=out, **kwargs)
55 return func
58def _fix_and_maybe_deprecate_out_named_y(f):
59 """
60 Use the appropriate decorator, depending upon if dispatching is being used.
61 """
62 if ARRAY_FUNCTION_ENABLED:
63 return _fix_out_named_y(f)
64 else:
65 return _deprecate_out_named_y(f)
68@_deprecate_out_named_y
69def _dispatcher(x, out=None):
70 return (x, out)
73@array_function_dispatch(_dispatcher, verify=False, module='numpy')
74@_fix_and_maybe_deprecate_out_named_y
75def fix(x, out=None):
76 """
77 Round to nearest integer towards zero.
79 Round an array of floats element-wise to nearest integer towards zero.
80 The rounded values are returned as floats.
82 Parameters
83 ----------
84 x : array_like
85 An array of floats to be rounded
86 out : ndarray, optional
87 A location into which the result is stored. If provided, it must have
88 a shape that the input broadcasts to. If not provided or None, a
89 freshly-allocated array is returned.
91 Returns
92 -------
93 out : ndarray of floats
94 A float array with the same dimensions as the input.
95 If second argument is not supplied then a float array is returned
96 with the rounded values.
98 If a second argument is supplied the result is stored there.
99 The return value `out` is then a reference to that array.
101 See Also
102 --------
103 trunc, floor, ceil
104 around : Round to given number of decimals
106 Examples
107 --------
108 >>> np.fix(3.14)
109 3.0
110 >>> np.fix(3)
111 3.0
112 >>> np.fix([2.1, 2.9, -2.1, -2.9])
113 array([ 2., 2., -2., -2.])
115 """
116 # promote back to an array if flattened
117 res = nx.asanyarray(nx.ceil(x, out=out))
118 res = nx.floor(x, out=res, where=nx.greater_equal(x, 0))
120 # when no out argument is passed and no subclasses are involved, flatten
121 # scalars
122 if out is None and type(res) is nx.ndarray:
123 res = res[()]
124 return res
127@array_function_dispatch(_dispatcher, verify=False, module='numpy')
128@_fix_and_maybe_deprecate_out_named_y
129def isposinf(x, out=None):
130 """
131 Test element-wise for positive infinity, return result as bool array.
133 Parameters
134 ----------
135 x : array_like
136 The input array.
137 out : array_like, optional
138 A location into which the result is stored. If provided, it must have a
139 shape that the input broadcasts to. If not provided or None, a
140 freshly-allocated boolean array is returned.
142 Returns
143 -------
144 out : ndarray
145 A boolean array with the same dimensions as the input.
146 If second argument is not supplied then a boolean array is returned
147 with values True where the corresponding element of the input is
148 positive infinity and values False where the element of the input is
149 not positive infinity.
151 If a second argument is supplied the result is stored there. If the
152 type of that array is a numeric type the result is represented as zeros
153 and ones, if the type is boolean then as False and True.
154 The return value `out` is then a reference to that array.
156 See Also
157 --------
158 isinf, isneginf, isfinite, isnan
160 Notes
161 -----
162 NumPy uses the IEEE Standard for Binary Floating-Point for Arithmetic
163 (IEEE 754).
165 Errors result if the second argument is also supplied when x is a scalar
166 input, if first and second arguments have different shapes, or if the
167 first argument has complex values
169 Examples
170 --------
171 >>> np.isposinf(np.PINF)
172 True
173 >>> np.isposinf(np.inf)
174 True
175 >>> np.isposinf(np.NINF)
176 False
177 >>> np.isposinf([-np.inf, 0., np.inf])
178 array([False, False, True])
180 >>> x = np.array([-np.inf, 0., np.inf])
181 >>> y = np.array([2, 2, 2])
182 >>> np.isposinf(x, y)
183 array([0, 0, 1])
184 >>> y
185 array([0, 0, 1])
187 """
188 is_inf = nx.isinf(x)
189 try:
190 signbit = ~nx.signbit(x)
191 except TypeError as e:
192 raise TypeError('This operation is not supported for complex values '
193 'because it would be ambiguous.') from e
194 else:
195 return nx.logical_and(is_inf, signbit, out)
198@array_function_dispatch(_dispatcher, verify=False, module='numpy')
199@_fix_and_maybe_deprecate_out_named_y
200def isneginf(x, out=None):
201 """
202 Test element-wise for negative infinity, return result as bool array.
204 Parameters
205 ----------
206 x : array_like
207 The input array.
208 out : array_like, optional
209 A location into which the result is stored. If provided, it must have a
210 shape that the input broadcasts to. If not provided or None, a
211 freshly-allocated boolean array is returned.
213 Returns
214 -------
215 out : ndarray
216 A boolean array with the same dimensions as the input.
217 If second argument is not supplied then a numpy boolean array is
218 returned with values True where the corresponding element of the
219 input is negative infinity and values False where the element of
220 the input is not negative infinity.
222 If a second argument is supplied the result is stored there. If the
223 type of that array is a numeric type the result is represented as
224 zeros and ones, if the type is boolean then as False and True. The
225 return value `out` is then a reference to that array.
227 See Also
228 --------
229 isinf, isposinf, isnan, isfinite
231 Notes
232 -----
233 NumPy uses the IEEE Standard for Binary Floating-Point for Arithmetic
234 (IEEE 754).
236 Errors result if the second argument is also supplied when x is a scalar
237 input, if first and second arguments have different shapes, or if the
238 first argument has complex values.
240 Examples
241 --------
242 >>> np.isneginf(np.NINF)
243 True
244 >>> np.isneginf(np.inf)
245 False
246 >>> np.isneginf(np.PINF)
247 False
248 >>> np.isneginf([-np.inf, 0., np.inf])
249 array([ True, False, False])
251 >>> x = np.array([-np.inf, 0., np.inf])
252 >>> y = np.array([2, 2, 2])
253 >>> np.isneginf(x, y)
254 array([1, 0, 0])
255 >>> y
256 array([1, 0, 0])
258 """
259 is_inf = nx.isinf(x)
260 try:
261 signbit = nx.signbit(x)
262 except TypeError as e:
263 raise TypeError('This operation is not supported for complex values '
264 'because it would be ambiguous.') from e
265 else:
266 return nx.logical_and(is_inf, signbit, out)