Coverage for /var/srv/projects/api.amasfac.comuna18.com/tmp/venv/lib/python3.9/site-packages/numpy/lib/type_check.py: 27%
132 statements
« prev ^ index » next coverage.py v6.4.4, created at 2023-07-17 14:22 -0600
1"""Automatically adapted for numpy Sep 19, 2005 by convertcode.py
3"""
4import functools
5import warnings
7__all__ = ['iscomplexobj', 'isrealobj', 'imag', 'iscomplex',
8 'isreal', 'nan_to_num', 'real', 'real_if_close',
9 'typename', 'asfarray', 'mintypecode',
10 'common_type']
12import numpy.core.numeric as _nx
13from numpy.core.numeric import asarray, asanyarray, isnan, zeros
14from numpy.core.overrides import set_module
15from numpy.core import overrides
16from .ufunclike import isneginf, isposinf
19array_function_dispatch = functools.partial(
20 overrides.array_function_dispatch, module='numpy')
23_typecodes_by_elsize = 'GDFgdfQqLlIiHhBb?'
26@set_module('numpy')
27def mintypecode(typechars, typeset='GDFgdf', default='d'):
28 """
29 Return the character for the minimum-size type to which given types can
30 be safely cast.
32 The returned type character must represent the smallest size dtype such
33 that an array of the returned type can handle the data from an array of
34 all types in `typechars` (or if `typechars` is an array, then its
35 dtype.char).
37 Parameters
38 ----------
39 typechars : list of str or array_like
40 If a list of strings, each string should represent a dtype.
41 If array_like, the character representation of the array dtype is used.
42 typeset : str or list of str, optional
43 The set of characters that the returned character is chosen from.
44 The default set is 'GDFgdf'.
45 default : str, optional
46 The default character, this is returned if none of the characters in
47 `typechars` matches a character in `typeset`.
49 Returns
50 -------
51 typechar : str
52 The character representing the minimum-size type that was found.
54 See Also
55 --------
56 dtype, sctype2char, maximum_sctype
58 Examples
59 --------
60 >>> np.mintypecode(['d', 'f', 'S'])
61 'd'
62 >>> x = np.array([1.1, 2-3.j])
63 >>> np.mintypecode(x)
64 'D'
66 >>> np.mintypecode('abceh', default='G')
67 'G'
69 """
70 typecodes = ((isinstance(t, str) and t) or asarray(t).dtype.char
71 for t in typechars)
72 intersection = set(t for t in typecodes if t in typeset)
73 if not intersection:
74 return default
75 if 'F' in intersection and 'd' in intersection:
76 return 'D'
77 return min(intersection, key=_typecodes_by_elsize.index)
80def _asfarray_dispatcher(a, dtype=None):
81 return (a,)
84@array_function_dispatch(_asfarray_dispatcher)
85def asfarray(a, dtype=_nx.float_):
86 """
87 Return an array converted to a float type.
89 Parameters
90 ----------
91 a : array_like
92 The input array.
93 dtype : str or dtype object, optional
94 Float type code to coerce input array `a`. If `dtype` is one of the
95 'int' dtypes, it is replaced with float64.
97 Returns
98 -------
99 out : ndarray
100 The input `a` as a float ndarray.
102 Examples
103 --------
104 >>> np.asfarray([2, 3])
105 array([2., 3.])
106 >>> np.asfarray([2, 3], dtype='float')
107 array([2., 3.])
108 >>> np.asfarray([2, 3], dtype='int8')
109 array([2., 3.])
111 """
112 if not _nx.issubdtype(dtype, _nx.inexact):
113 dtype = _nx.float_
114 return asarray(a, dtype=dtype)
117def _real_dispatcher(val):
118 return (val,)
121@array_function_dispatch(_real_dispatcher)
122def real(val):
123 """
124 Return the real part of the complex argument.
126 Parameters
127 ----------
128 val : array_like
129 Input array.
131 Returns
132 -------
133 out : ndarray or scalar
134 The real component of the complex argument. If `val` is real, the type
135 of `val` is used for the output. If `val` has complex elements, the
136 returned type is float.
138 See Also
139 --------
140 real_if_close, imag, angle
142 Examples
143 --------
144 >>> a = np.array([1+2j, 3+4j, 5+6j])
145 >>> a.real
146 array([1., 3., 5.])
147 >>> a.real = 9
148 >>> a
149 array([9.+2.j, 9.+4.j, 9.+6.j])
150 >>> a.real = np.array([9, 8, 7])
151 >>> a
152 array([9.+2.j, 8.+4.j, 7.+6.j])
153 >>> np.real(1 + 1j)
154 1.0
156 """
157 try:
158 return val.real
159 except AttributeError:
160 return asanyarray(val).real
163def _imag_dispatcher(val):
164 return (val,)
167@array_function_dispatch(_imag_dispatcher)
168def imag(val):
169 """
170 Return the imaginary part of the complex argument.
172 Parameters
173 ----------
174 val : array_like
175 Input array.
177 Returns
178 -------
179 out : ndarray or scalar
180 The imaginary component of the complex argument. If `val` is real,
181 the type of `val` is used for the output. If `val` has complex
182 elements, the returned type is float.
184 See Also
185 --------
186 real, angle, real_if_close
188 Examples
189 --------
190 >>> a = np.array([1+2j, 3+4j, 5+6j])
191 >>> a.imag
192 array([2., 4., 6.])
193 >>> a.imag = np.array([8, 10, 12])
194 >>> a
195 array([1. +8.j, 3.+10.j, 5.+12.j])
196 >>> np.imag(1 + 1j)
197 1.0
199 """
200 try:
201 return val.imag
202 except AttributeError:
203 return asanyarray(val).imag
206def _is_type_dispatcher(x):
207 return (x,)
210@array_function_dispatch(_is_type_dispatcher)
211def iscomplex(x):
212 """
213 Returns a bool array, where True if input element is complex.
215 What is tested is whether the input has a non-zero imaginary part, not if
216 the input type is complex.
218 Parameters
219 ----------
220 x : array_like
221 Input array.
223 Returns
224 -------
225 out : ndarray of bools
226 Output array.
228 See Also
229 --------
230 isreal
231 iscomplexobj : Return True if x is a complex type or an array of complex
232 numbers.
234 Examples
235 --------
236 >>> np.iscomplex([1+1j, 1+0j, 4.5, 3, 2, 2j])
237 array([ True, False, False, False, False, True])
239 """
240 ax = asanyarray(x)
241 if issubclass(ax.dtype.type, _nx.complexfloating):
242 return ax.imag != 0
243 res = zeros(ax.shape, bool)
244 return res[()] # convert to scalar if needed
247@array_function_dispatch(_is_type_dispatcher)
248def isreal(x):
249 """
250 Returns a bool array, where True if input element is real.
252 If element has complex type with zero complex part, the return value
253 for that element is True.
255 Parameters
256 ----------
257 x : array_like
258 Input array.
260 Returns
261 -------
262 out : ndarray, bool
263 Boolean array of same shape as `x`.
265 Notes
266 -----
267 `isreal` may behave unexpectedly for string or object arrays (see examples)
269 See Also
270 --------
271 iscomplex
272 isrealobj : Return True if x is not a complex type.
274 Examples
275 --------
276 >>> a = np.array([1+1j, 1+0j, 4.5, 3, 2, 2j], dtype=complex)
277 >>> np.isreal(a)
278 array([False, True, True, True, True, False])
280 The function does not work on string arrays.
282 >>> a = np.array([2j, "a"], dtype="U")
283 >>> np.isreal(a) # Warns about non-elementwise comparison
284 False
286 Returns True for all elements in input array of ``dtype=object`` even if
287 any of the elements is complex.
289 >>> a = np.array([1, "2", 3+4j], dtype=object)
290 >>> np.isreal(a)
291 array([ True, True, True])
293 isreal should not be used with object arrays
295 >>> a = np.array([1+2j, 2+1j], dtype=object)
296 >>> np.isreal(a)
297 array([ True, True])
299 """
300 return imag(x) == 0
303@array_function_dispatch(_is_type_dispatcher)
304def iscomplexobj(x):
305 """
306 Check for a complex type or an array of complex numbers.
308 The type of the input is checked, not the value. Even if the input
309 has an imaginary part equal to zero, `iscomplexobj` evaluates to True.
311 Parameters
312 ----------
313 x : any
314 The input can be of any type and shape.
316 Returns
317 -------
318 iscomplexobj : bool
319 The return value, True if `x` is of a complex type or has at least
320 one complex element.
322 See Also
323 --------
324 isrealobj, iscomplex
326 Examples
327 --------
328 >>> np.iscomplexobj(1)
329 False
330 >>> np.iscomplexobj(1+0j)
331 True
332 >>> np.iscomplexobj([3, 1+0j, True])
333 True
335 """
336 try:
337 dtype = x.dtype
338 type_ = dtype.type
339 except AttributeError:
340 type_ = asarray(x).dtype.type
341 return issubclass(type_, _nx.complexfloating)
344@array_function_dispatch(_is_type_dispatcher)
345def isrealobj(x):
346 """
347 Return True if x is a not complex type or an array of complex numbers.
349 The type of the input is checked, not the value. So even if the input
350 has an imaginary part equal to zero, `isrealobj` evaluates to False
351 if the data type is complex.
353 Parameters
354 ----------
355 x : any
356 The input can be of any type and shape.
358 Returns
359 -------
360 y : bool
361 The return value, False if `x` is of a complex type.
363 See Also
364 --------
365 iscomplexobj, isreal
367 Notes
368 -----
369 The function is only meant for arrays with numerical values but it
370 accepts all other objects. Since it assumes array input, the return
371 value of other objects may be True.
373 >>> np.isrealobj('A string')
374 True
375 >>> np.isrealobj(False)
376 True
377 >>> np.isrealobj(None)
378 True
380 Examples
381 --------
382 >>> np.isrealobj(1)
383 True
384 >>> np.isrealobj(1+0j)
385 False
386 >>> np.isrealobj([3, 1+0j, True])
387 False
389 """
390 return not iscomplexobj(x)
392#-----------------------------------------------------------------------------
394def _getmaxmin(t):
395 from numpy.core import getlimits
396 f = getlimits.finfo(t)
397 return f.max, f.min
400def _nan_to_num_dispatcher(x, copy=None, nan=None, posinf=None, neginf=None):
401 return (x,)
404@array_function_dispatch(_nan_to_num_dispatcher)
405def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None):
406 """
407 Replace NaN with zero and infinity with large finite numbers (default
408 behaviour) or with the numbers defined by the user using the `nan`,
409 `posinf` and/or `neginf` keywords.
411 If `x` is inexact, NaN is replaced by zero or by the user defined value in
412 `nan` keyword, infinity is replaced by the largest finite floating point
413 values representable by ``x.dtype`` or by the user defined value in
414 `posinf` keyword and -infinity is replaced by the most negative finite
415 floating point values representable by ``x.dtype`` or by the user defined
416 value in `neginf` keyword.
418 For complex dtypes, the above is applied to each of the real and
419 imaginary components of `x` separately.
421 If `x` is not inexact, then no replacements are made.
423 Parameters
424 ----------
425 x : scalar or array_like
426 Input data.
427 copy : bool, optional
428 Whether to create a copy of `x` (True) or to replace values
429 in-place (False). The in-place operation only occurs if
430 casting to an array does not require a copy.
431 Default is True.
433 .. versionadded:: 1.13
434 nan : int, float, optional
435 Value to be used to fill NaN values. If no value is passed
436 then NaN values will be replaced with 0.0.
438 .. versionadded:: 1.17
439 posinf : int, float, optional
440 Value to be used to fill positive infinity values. If no value is
441 passed then positive infinity values will be replaced with a very
442 large number.
444 .. versionadded:: 1.17
445 neginf : int, float, optional
446 Value to be used to fill negative infinity values. If no value is
447 passed then negative infinity values will be replaced with a very
448 small (or negative) number.
450 .. versionadded:: 1.17
454 Returns
455 -------
456 out : ndarray
457 `x`, with the non-finite values replaced. If `copy` is False, this may
458 be `x` itself.
460 See Also
461 --------
462 isinf : Shows which elements are positive or negative infinity.
463 isneginf : Shows which elements are negative infinity.
464 isposinf : Shows which elements are positive infinity.
465 isnan : Shows which elements are Not a Number (NaN).
466 isfinite : Shows which elements are finite (not NaN, not infinity)
468 Notes
469 -----
470 NumPy uses the IEEE Standard for Binary Floating-Point for Arithmetic
471 (IEEE 754). This means that Not a Number is not equivalent to infinity.
473 Examples
474 --------
475 >>> np.nan_to_num(np.inf)
476 1.7976931348623157e+308
477 >>> np.nan_to_num(-np.inf)
478 -1.7976931348623157e+308
479 >>> np.nan_to_num(np.nan)
480 0.0
481 >>> x = np.array([np.inf, -np.inf, np.nan, -128, 128])
482 >>> np.nan_to_num(x)
483 array([ 1.79769313e+308, -1.79769313e+308, 0.00000000e+000, # may vary
484 -1.28000000e+002, 1.28000000e+002])
485 >>> np.nan_to_num(x, nan=-9999, posinf=33333333, neginf=33333333)
486 array([ 3.3333333e+07, 3.3333333e+07, -9.9990000e+03,
487 -1.2800000e+02, 1.2800000e+02])
488 >>> y = np.array([complex(np.inf, np.nan), np.nan, complex(np.nan, np.inf)])
489 array([ 1.79769313e+308, -1.79769313e+308, 0.00000000e+000, # may vary
490 -1.28000000e+002, 1.28000000e+002])
491 >>> np.nan_to_num(y)
492 array([ 1.79769313e+308 +0.00000000e+000j, # may vary
493 0.00000000e+000 +0.00000000e+000j,
494 0.00000000e+000 +1.79769313e+308j])
495 >>> np.nan_to_num(y, nan=111111, posinf=222222)
496 array([222222.+111111.j, 111111. +0.j, 111111.+222222.j])
497 """
498 x = _nx.array(x, subok=True, copy=copy)
499 xtype = x.dtype.type
501 isscalar = (x.ndim == 0)
503 if not issubclass(xtype, _nx.inexact):
504 return x[()] if isscalar else x
506 iscomplex = issubclass(xtype, _nx.complexfloating)
508 dest = (x.real, x.imag) if iscomplex else (x,)
509 maxf, minf = _getmaxmin(x.real.dtype)
510 if posinf is not None:
511 maxf = posinf
512 if neginf is not None:
513 minf = neginf
514 for d in dest:
515 idx_nan = isnan(d)
516 idx_posinf = isposinf(d)
517 idx_neginf = isneginf(d)
518 _nx.copyto(d, nan, where=idx_nan)
519 _nx.copyto(d, maxf, where=idx_posinf)
520 _nx.copyto(d, minf, where=idx_neginf)
521 return x[()] if isscalar else x
523#-----------------------------------------------------------------------------
525def _real_if_close_dispatcher(a, tol=None):
526 return (a,)
529@array_function_dispatch(_real_if_close_dispatcher)
530def real_if_close(a, tol=100):
531 """
532 If input is complex with all imaginary parts close to zero, return
533 real parts.
535 "Close to zero" is defined as `tol` * (machine epsilon of the type for
536 `a`).
538 Parameters
539 ----------
540 a : array_like
541 Input array.
542 tol : float
543 Tolerance in machine epsilons for the complex part of the elements
544 in the array.
546 Returns
547 -------
548 out : ndarray
549 If `a` is real, the type of `a` is used for the output. If `a`
550 has complex elements, the returned type is float.
552 See Also
553 --------
554 real, imag, angle
556 Notes
557 -----
558 Machine epsilon varies from machine to machine and between data types
559 but Python floats on most platforms have a machine epsilon equal to
560 2.2204460492503131e-16. You can use 'np.finfo(float).eps' to print
561 out the machine epsilon for floats.
563 Examples
564 --------
565 >>> np.finfo(float).eps
566 2.2204460492503131e-16 # may vary
568 >>> np.real_if_close([2.1 + 4e-14j, 5.2 + 3e-15j], tol=1000)
569 array([2.1, 5.2])
570 >>> np.real_if_close([2.1 + 4e-13j, 5.2 + 3e-15j], tol=1000)
571 array([2.1+4.e-13j, 5.2 + 3e-15j])
573 """
574 a = asanyarray(a)
575 if not issubclass(a.dtype.type, _nx.complexfloating):
576 return a
577 if tol > 1:
578 from numpy.core import getlimits
579 f = getlimits.finfo(a.dtype.type)
580 tol = f.eps * tol
581 if _nx.all(_nx.absolute(a.imag) < tol):
582 a = a.real
583 return a
586#-----------------------------------------------------------------------------
588_namefromtype = {'S1': 'character',
589 '?': 'bool',
590 'b': 'signed char',
591 'B': 'unsigned char',
592 'h': 'short',
593 'H': 'unsigned short',
594 'i': 'integer',
595 'I': 'unsigned integer',
596 'l': 'long integer',
597 'L': 'unsigned long integer',
598 'q': 'long long integer',
599 'Q': 'unsigned long long integer',
600 'f': 'single precision',
601 'd': 'double precision',
602 'g': 'long precision',
603 'F': 'complex single precision',
604 'D': 'complex double precision',
605 'G': 'complex long double precision',
606 'S': 'string',
607 'U': 'unicode',
608 'V': 'void',
609 'O': 'object'
610 }
612@set_module('numpy')
613def typename(char):
614 """
615 Return a description for the given data type code.
617 Parameters
618 ----------
619 char : str
620 Data type code.
622 Returns
623 -------
624 out : str
625 Description of the input data type code.
627 See Also
628 --------
629 dtype, typecodes
631 Examples
632 --------
633 >>> typechars = ['S1', '?', 'B', 'D', 'G', 'F', 'I', 'H', 'L', 'O', 'Q',
634 ... 'S', 'U', 'V', 'b', 'd', 'g', 'f', 'i', 'h', 'l', 'q']
635 >>> for typechar in typechars:
636 ... print(typechar, ' : ', np.typename(typechar))
637 ...
638 S1 : character
639 ? : bool
640 B : unsigned char
641 D : complex double precision
642 G : complex long double precision
643 F : complex single precision
644 I : unsigned integer
645 H : unsigned short
646 L : unsigned long integer
647 O : object
648 Q : unsigned long long integer
649 S : string
650 U : unicode
651 V : void
652 b : signed char
653 d : double precision
654 g : long precision
655 f : single precision
656 i : integer
657 h : short
658 l : long integer
659 q : long long integer
661 """
662 return _namefromtype[char]
664#-----------------------------------------------------------------------------
666#determine the "minimum common type" for a group of arrays.
667array_type = [[_nx.half, _nx.single, _nx.double, _nx.longdouble],
668 [None, _nx.csingle, _nx.cdouble, _nx.clongdouble]]
669array_precision = {_nx.half: 0,
670 _nx.single: 1,
671 _nx.double: 2,
672 _nx.longdouble: 3,
673 _nx.csingle: 1,
674 _nx.cdouble: 2,
675 _nx.clongdouble: 3}
678def _common_type_dispatcher(*arrays):
679 return arrays
682@array_function_dispatch(_common_type_dispatcher)
683def common_type(*arrays):
684 """
685 Return a scalar type which is common to the input arrays.
687 The return type will always be an inexact (i.e. floating point) scalar
688 type, even if all the arrays are integer arrays. If one of the inputs is
689 an integer array, the minimum precision type that is returned is a
690 64-bit floating point dtype.
692 All input arrays except int64 and uint64 can be safely cast to the
693 returned dtype without loss of information.
695 Parameters
696 ----------
697 array1, array2, ... : ndarrays
698 Input arrays.
700 Returns
701 -------
702 out : data type code
703 Data type code.
705 See Also
706 --------
707 dtype, mintypecode
709 Examples
710 --------
711 >>> np.common_type(np.arange(2, dtype=np.float32))
712 <class 'numpy.float32'>
713 >>> np.common_type(np.arange(2, dtype=np.float32), np.arange(2))
714 <class 'numpy.float64'>
715 >>> np.common_type(np.arange(4), np.array([45, 6.j]), np.array([45.0]))
716 <class 'numpy.complex128'>
718 """
719 is_complex = False
720 precision = 0
721 for a in arrays:
722 t = a.dtype.type
723 if iscomplexobj(a):
724 is_complex = True
725 if issubclass(t, _nx.integer):
726 p = 2 # array_precision[_nx.double]
727 else:
728 p = array_precision.get(t, None)
729 if p is None:
730 raise TypeError("can't get common type for non-numeric array")
731 precision = max(precision, p)
732 if is_complex:
733 return array_type[1][precision]
734 else:
735 return array_type[0][precision]