Spaces:
Paused
Paused
| """ | |
| Create the numpy.core.multiarray namespace for backward compatibility. In v1.16 | |
| the multiarray and umath c-extension modules were merged into a single | |
| _multiarray_umath extension module. So we replicate the old namespace | |
| by importing from the extension module. | |
| """ | |
| import functools | |
| import warnings | |
| from . import overrides | |
| from . import _multiarray_umath | |
| from ._multiarray_umath import * # noqa: F403 | |
| # These imports are needed for backward compatibility, | |
| # do not change them. issue gh-15518 | |
| # _get_ndarray_c_version is semi-public, on purpose not added to __all__ | |
| from ._multiarray_umath import ( | |
| _fastCopyAndTranspose, _flagdict, _insert, _reconstruct, _vec_string, | |
| _ARRAY_API, _monotonicity, _get_ndarray_c_version, _set_madvise_hugepage, | |
| ) | |
| __all__ = [ | |
| '_ARRAY_API', 'ALLOW_THREADS', 'BUFSIZE', 'CLIP', 'DATETIMEUNITS', | |
| 'ITEM_HASOBJECT', 'ITEM_IS_POINTER', 'LIST_PICKLE', 'MAXDIMS', | |
| 'MAY_SHARE_BOUNDS', 'MAY_SHARE_EXACT', 'NEEDS_INIT', 'NEEDS_PYAPI', | |
| 'RAISE', 'USE_GETITEM', 'USE_SETITEM', 'WRAP', '_fastCopyAndTranspose', | |
| '_flagdict', '_insert', '_reconstruct', '_vec_string', '_monotonicity', | |
| 'add_docstring', 'arange', 'array', 'asarray', 'asanyarray', | |
| 'ascontiguousarray', 'asfortranarray', 'bincount', 'broadcast', | |
| 'busday_count', 'busday_offset', 'busdaycalendar', 'can_cast', | |
| 'compare_chararrays', 'concatenate', 'copyto', 'correlate', 'correlate2', | |
| 'count_nonzero', 'c_einsum', 'datetime_as_string', 'datetime_data', | |
| 'digitize', 'dot', 'dragon4_positional', 'dragon4_scientific', 'dtype', | |
| 'empty', 'empty_like', 'error', 'flagsobj', 'flatiter', 'format_longfloat', | |
| 'frombuffer', 'fromfile', 'fromiter', 'fromstring', 'inner', | |
| 'interp', 'interp_complex', 'is_busday', 'lexsort', | |
| 'matmul', 'may_share_memory', 'min_scalar_type', 'ndarray', 'nditer', | |
| 'nested_iters', 'normalize_axis_index', 'packbits', | |
| 'promote_types', 'putmask', 'ravel_multi_index', 'result_type', 'scalar', | |
| 'set_datetimeparse_function', 'set_legacy_print_mode', 'set_numeric_ops', | |
| 'set_string_function', 'set_typeDict', 'shares_memory', | |
| 'tracemalloc_domain', 'typeinfo', 'unpackbits', 'unravel_index', 'vdot', | |
| 'where', 'zeros'] | |
| # For backward compatibility, make sure pickle imports these functions from here | |
| _reconstruct.__module__ = 'numpy.core.multiarray' | |
| scalar.__module__ = 'numpy.core.multiarray' | |
| arange.__module__ = 'numpy' | |
| array.__module__ = 'numpy' | |
| asarray.__module__ = 'numpy' | |
| asanyarray.__module__ = 'numpy' | |
| ascontiguousarray.__module__ = 'numpy' | |
| asfortranarray.__module__ = 'numpy' | |
| datetime_data.__module__ = 'numpy' | |
| empty.__module__ = 'numpy' | |
| frombuffer.__module__ = 'numpy' | |
| fromfile.__module__ = 'numpy' | |
| fromiter.__module__ = 'numpy' | |
| frompyfunc.__module__ = 'numpy' | |
| fromstring.__module__ = 'numpy' | |
| geterrobj.__module__ = 'numpy' | |
| may_share_memory.__module__ = 'numpy' | |
| nested_iters.__module__ = 'numpy' | |
| promote_types.__module__ = 'numpy' | |
| set_numeric_ops.__module__ = 'numpy' | |
| seterrobj.__module__ = 'numpy' | |
| zeros.__module__ = 'numpy' | |
| # We can't verify dispatcher signatures because NumPy's C functions don't | |
| # support introspection. | |
| array_function_from_c_func_and_dispatcher = functools.partial( | |
| overrides.array_function_from_dispatcher, | |
| module='numpy', docs_from_dispatcher=True, verify=False) | |
| def empty_like(prototype, dtype=None, order=None, subok=None, shape=None): | |
| """ | |
| empty_like(prototype, dtype=None, order='K', subok=True, shape=None) | |
| Return a new array with the same shape and type as a given array. | |
| Parameters | |
| ---------- | |
| prototype : array_like | |
| The shape and data-type of `prototype` define these same attributes | |
| of the returned array. | |
| dtype : data-type, optional | |
| Overrides the data type of the result. | |
| .. versionadded:: 1.6.0 | |
| order : {'C', 'F', 'A', or 'K'}, optional | |
| Overrides the memory layout of the result. 'C' means C-order, | |
| 'F' means F-order, 'A' means 'F' if `prototype` is Fortran | |
| contiguous, 'C' otherwise. 'K' means match the layout of `prototype` | |
| as closely as possible. | |
| .. versionadded:: 1.6.0 | |
| subok : bool, optional. | |
| If True, then the newly created array will use the sub-class | |
| type of `prototype`, otherwise it will be a base-class array. Defaults | |
| to True. | |
| shape : int or sequence of ints, optional. | |
| Overrides the shape of the result. If order='K' and the number of | |
| dimensions is unchanged, will try to keep order, otherwise, | |
| order='C' is implied. | |
| .. versionadded:: 1.17.0 | |
| Returns | |
| ------- | |
| out : ndarray | |
| Array of uninitialized (arbitrary) data with the same | |
| shape and type as `prototype`. | |
| See Also | |
| -------- | |
| ones_like : Return an array of ones with shape and type of input. | |
| zeros_like : Return an array of zeros with shape and type of input. | |
| full_like : Return a new array with shape of input filled with value. | |
| empty : Return a new uninitialized array. | |
| Notes | |
| ----- | |
| This function does *not* initialize the returned array; to do that use | |
| `zeros_like` or `ones_like` instead. It may be marginally faster than | |
| the functions that do set the array values. | |
| Examples | |
| -------- | |
| >>> a = ([1,2,3], [4,5,6]) # a is array-like | |
| >>> np.empty_like(a) | |
| array([[-1073741821, -1073741821, 3], # uninitialized | |
| [ 0, 0, -1073741821]]) | |
| >>> a = np.array([[1., 2., 3.],[4.,5.,6.]]) | |
| >>> np.empty_like(a) | |
| array([[ -2.00000715e+000, 1.48219694e-323, -2.00000572e+000], # uninitialized | |
| [ 4.38791518e-305, -2.00000715e+000, 4.17269252e-309]]) | |
| """ | |
| return (prototype,) | |
| def concatenate(arrays, axis=None, out=None, *, dtype=None, casting=None): | |
| """ | |
| concatenate((a1, a2, ...), axis=0, out=None, dtype=None, casting="same_kind") | |
| Join a sequence of arrays along an existing axis. | |
| Parameters | |
| ---------- | |
| a1, a2, ... : sequence of array_like | |
| The arrays must have the same shape, except in the dimension | |
| corresponding to `axis` (the first, by default). | |
| axis : int, optional | |
| The axis along which the arrays will be joined. If axis is None, | |
| arrays are flattened before use. Default is 0. | |
| out : ndarray, optional | |
| If provided, the destination to place the result. The shape must be | |
| correct, matching that of what concatenate would have returned if no | |
| out argument were specified. | |
| dtype : str or dtype | |
| If provided, the destination array will have this dtype. Cannot be | |
| provided together with `out`. | |
| .. versionadded:: 1.20.0 | |
| casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional | |
| Controls what kind of data casting may occur. Defaults to 'same_kind'. | |
| .. versionadded:: 1.20.0 | |
| Returns | |
| ------- | |
| res : ndarray | |
| The concatenated array. | |
| See Also | |
| -------- | |
| ma.concatenate : Concatenate function that preserves input masks. | |
| array_split : Split an array into multiple sub-arrays of equal or | |
| near-equal size. | |
| split : Split array into a list of multiple sub-arrays of equal size. | |
| hsplit : Split array into multiple sub-arrays horizontally (column wise). | |
| vsplit : Split array into multiple sub-arrays vertically (row wise). | |
| dsplit : Split array into multiple sub-arrays along the 3rd axis (depth). | |
| stack : Stack a sequence of arrays along a new axis. | |
| block : Assemble arrays from blocks. | |
| hstack : Stack arrays in sequence horizontally (column wise). | |
| vstack : Stack arrays in sequence vertically (row wise). | |
| dstack : Stack arrays in sequence depth wise (along third dimension). | |
| column_stack : Stack 1-D arrays as columns into a 2-D array. | |
| Notes | |
| ----- | |
| When one or more of the arrays to be concatenated is a MaskedArray, | |
| this function will return a MaskedArray object instead of an ndarray, | |
| but the input masks are *not* preserved. In cases where a MaskedArray | |
| is expected as input, use the ma.concatenate function from the masked | |
| array module instead. | |
| Examples | |
| -------- | |
| >>> a = np.array([[1, 2], [3, 4]]) | |
| >>> b = np.array([[5, 6]]) | |
| >>> np.concatenate((a, b), axis=0) | |
| array([[1, 2], | |
| [3, 4], | |
| [5, 6]]) | |
| >>> np.concatenate((a, b.T), axis=1) | |
| array([[1, 2, 5], | |
| [3, 4, 6]]) | |
| >>> np.concatenate((a, b), axis=None) | |
| array([1, 2, 3, 4, 5, 6]) | |
| This function will not preserve masking of MaskedArray inputs. | |
| >>> a = np.ma.arange(3) | |
| >>> a[1] = np.ma.masked | |
| >>> b = np.arange(2, 5) | |
| >>> a | |
| masked_array(data=[0, --, 2], | |
| mask=[False, True, False], | |
| fill_value=999999) | |
| >>> b | |
| array([2, 3, 4]) | |
| >>> np.concatenate([a, b]) | |
| masked_array(data=[0, 1, 2, 2, 3, 4], | |
| mask=False, | |
| fill_value=999999) | |
| >>> np.ma.concatenate([a, b]) | |
| masked_array(data=[0, --, 2, 2, 3, 4], | |
| mask=[False, True, False, False, False, False], | |
| fill_value=999999) | |
| """ | |
| if out is not None: | |
| # optimize for the typical case where only arrays is provided | |
| arrays = list(arrays) | |
| arrays.append(out) | |
| return arrays | |
| def inner(a, b): | |
| """ | |
| inner(a, b) | |
| Inner product of two arrays. | |
| Ordinary inner product of vectors for 1-D arrays (without complex | |
| conjugation), in higher dimensions a sum product over the last axes. | |
| Parameters | |
| ---------- | |
| a, b : array_like | |
| If `a` and `b` are nonscalar, their last dimensions must match. | |
| Returns | |
| ------- | |
| out : ndarray | |
| If `a` and `b` are both | |
| scalars or both 1-D arrays then a scalar is returned; otherwise | |
| an array is returned. | |
| ``out.shape = (*a.shape[:-1], *b.shape[:-1])`` | |
| Raises | |
| ------ | |
| ValueError | |
| If both `a` and `b` are nonscalar and their last dimensions have | |
| different sizes. | |
| See Also | |
| -------- | |
| tensordot : Sum products over arbitrary axes. | |
| dot : Generalised matrix product, using second last dimension of `b`. | |
| einsum : Einstein summation convention. | |
| Notes | |
| ----- | |
| For vectors (1-D arrays) it computes the ordinary inner-product:: | |
| np.inner(a, b) = sum(a[:]*b[:]) | |
| More generally, if `ndim(a) = r > 0` and `ndim(b) = s > 0`:: | |
| np.inner(a, b) = np.tensordot(a, b, axes=(-1,-1)) | |
| or explicitly:: | |
| np.inner(a, b)[i0,...,ir-2,j0,...,js-2] | |
| = sum(a[i0,...,ir-2,:]*b[j0,...,js-2,:]) | |
| In addition `a` or `b` may be scalars, in which case:: | |
| np.inner(a,b) = a*b | |
| Examples | |
| -------- | |
| Ordinary inner product for vectors: | |
| >>> a = np.array([1,2,3]) | |
| >>> b = np.array([0,1,0]) | |
| >>> np.inner(a, b) | |
| 2 | |
| Some multidimensional examples: | |
| >>> a = np.arange(24).reshape((2,3,4)) | |
| >>> b = np.arange(4) | |
| >>> c = np.inner(a, b) | |
| >>> c.shape | |
| (2, 3) | |
| >>> c | |
| array([[ 14, 38, 62], | |
| [ 86, 110, 134]]) | |
| >>> a = np.arange(2).reshape((1,1,2)) | |
| >>> b = np.arange(6).reshape((3,2)) | |
| >>> c = np.inner(a, b) | |
| >>> c.shape | |
| (1, 1, 3) | |
| >>> c | |
| array([[[1, 3, 5]]]) | |
| An example where `b` is a scalar: | |
| >>> np.inner(np.eye(2), 7) | |
| array([[7., 0.], | |
| [0., 7.]]) | |
| """ | |
| return (a, b) | |
| def where(condition, x=None, y=None): | |
| """ | |
| where(condition, [x, y]) | |
| Return elements chosen from `x` or `y` depending on `condition`. | |
| .. note:: | |
| When only `condition` is provided, this function is a shorthand for | |
| ``np.asarray(condition).nonzero()``. Using `nonzero` directly should be | |
| preferred, as it behaves correctly for subclasses. The rest of this | |
| documentation covers only the case where all three arguments are | |
| provided. | |
| Parameters | |
| ---------- | |
| condition : array_like, bool | |
| Where True, yield `x`, otherwise yield `y`. | |
| x, y : array_like | |
| Values from which to choose. `x`, `y` and `condition` need to be | |
| broadcastable to some shape. | |
| Returns | |
| ------- | |
| out : ndarray | |
| An array with elements from `x` where `condition` is True, and elements | |
| from `y` elsewhere. | |
| See Also | |
| -------- | |
| choose | |
| nonzero : The function that is called when x and y are omitted | |
| Notes | |
| ----- | |
| If all the arrays are 1-D, `where` is equivalent to:: | |
| [xv if c else yv | |
| for c, xv, yv in zip(condition, x, y)] | |
| Examples | |
| -------- | |
| >>> a = np.arange(10) | |
| >>> a | |
| array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) | |
| >>> np.where(a < 5, a, 10*a) | |
| array([ 0, 1, 2, 3, 4, 50, 60, 70, 80, 90]) | |
| This can be used on multidimensional arrays too: | |
| >>> np.where([[True, False], [True, True]], | |
| ... [[1, 2], [3, 4]], | |
| ... [[9, 8], [7, 6]]) | |
| array([[1, 8], | |
| [3, 4]]) | |
| The shapes of x, y, and the condition are broadcast together: | |
| >>> x, y = np.ogrid[:3, :4] | |
| >>> np.where(x < y, x, 10 + y) # both x and 10+y are broadcast | |
| array([[10, 0, 0, 0], | |
| [10, 11, 1, 1], | |
| [10, 11, 12, 2]]) | |
| >>> a = np.array([[0, 1, 2], | |
| ... [0, 2, 4], | |
| ... [0, 3, 6]]) | |
| >>> np.where(a < 4, a, -1) # -1 is broadcast | |
| array([[ 0, 1, 2], | |
| [ 0, 2, -1], | |
| [ 0, 3, -1]]) | |
| """ | |
| return (condition, x, y) | |
| def lexsort(keys, axis=None): | |
| """ | |
| lexsort(keys, axis=-1) | |
| Perform an indirect stable sort using a sequence of keys. | |
| Given multiple sorting keys, which can be interpreted as columns in a | |
| spreadsheet, lexsort returns an array of integer indices that describes | |
| the sort order by multiple columns. The last key in the sequence is used | |
| for the primary sort order, the second-to-last key for the secondary sort | |
| order, and so on. The keys argument must be a sequence of objects that | |
| can be converted to arrays of the same shape. If a 2D array is provided | |
| for the keys argument, its rows are interpreted as the sorting keys and | |
| sorting is according to the last row, second last row etc. | |
| Parameters | |
| ---------- | |
| keys : (k, N) array or tuple containing k (N,)-shaped sequences | |
| The `k` different "columns" to be sorted. The last column (or row if | |
| `keys` is a 2D array) is the primary sort key. | |
| axis : int, optional | |
| Axis to be indirectly sorted. By default, sort over the last axis. | |
| Returns | |
| ------- | |
| indices : (N,) ndarray of ints | |
| Array of indices that sort the keys along the specified axis. | |
| See Also | |
| -------- | |
| argsort : Indirect sort. | |
| ndarray.sort : In-place sort. | |
| sort : Return a sorted copy of an array. | |
| Examples | |
| -------- | |
| Sort names: first by surname, then by name. | |
| >>> surnames = ('Hertz', 'Galilei', 'Hertz') | |
| >>> first_names = ('Heinrich', 'Galileo', 'Gustav') | |
| >>> ind = np.lexsort((first_names, surnames)) | |
| >>> ind | |
| array([1, 2, 0]) | |
| >>> [surnames[i] + ", " + first_names[i] for i in ind] | |
| ['Galilei, Galileo', 'Hertz, Gustav', 'Hertz, Heinrich'] | |
| Sort two columns of numbers: | |
| >>> a = [1,5,1,4,3,4,4] # First column | |
| >>> b = [9,4,0,4,0,2,1] # Second column | |
| >>> ind = np.lexsort((b,a)) # Sort by a, then by b | |
| >>> ind | |
| array([2, 0, 4, 6, 5, 3, 1]) | |
| >>> [(a[i],b[i]) for i in ind] | |
| [(1, 0), (1, 9), (3, 0), (4, 1), (4, 2), (4, 4), (5, 4)] | |
| Note that sorting is first according to the elements of ``a``. | |
| Secondary sorting is according to the elements of ``b``. | |
| A normal ``argsort`` would have yielded: | |
| >>> [(a[i],b[i]) for i in np.argsort(a)] | |
| [(1, 9), (1, 0), (3, 0), (4, 4), (4, 2), (4, 1), (5, 4)] | |
| Structured arrays are sorted lexically by ``argsort``: | |
| >>> x = np.array([(1,9), (5,4), (1,0), (4,4), (3,0), (4,2), (4,1)], | |
| ... dtype=np.dtype([('x', int), ('y', int)])) | |
| >>> np.argsort(x) # or np.argsort(x, order=('x', 'y')) | |
| array([2, 0, 4, 6, 5, 3, 1]) | |
| """ | |
| if isinstance(keys, tuple): | |
| return keys | |
| else: | |
| return (keys,) | |
| def can_cast(from_, to, casting=None): | |
| """ | |
| can_cast(from_, to, casting='safe') | |
| Returns True if cast between data types can occur according to the | |
| casting rule. If from is a scalar or array scalar, also returns | |
| True if the scalar value can be cast without overflow or truncation | |
| to an integer. | |
| Parameters | |
| ---------- | |
| from_ : dtype, dtype specifier, scalar, or array | |
| Data type, scalar, or array to cast from. | |
| to : dtype or dtype specifier | |
| Data type to cast to. | |
| casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional | |
| Controls what kind of data casting may occur. | |
| * 'no' means the data types should not be cast at all. | |
| * 'equiv' means only byte-order changes are allowed. | |
| * 'safe' means only casts which can preserve values are allowed. | |
| * 'same_kind' means only safe casts or casts within a kind, | |
| like float64 to float32, are allowed. | |
| * 'unsafe' means any data conversions may be done. | |
| Returns | |
| ------- | |
| out : bool | |
| True if cast can occur according to the casting rule. | |
| Notes | |
| ----- | |
| .. versionchanged:: 1.17.0 | |
| Casting between a simple data type and a structured one is possible only | |
| for "unsafe" casting. Casting to multiple fields is allowed, but | |
| casting from multiple fields is not. | |
| .. versionchanged:: 1.9.0 | |
| Casting from numeric to string types in 'safe' casting mode requires | |
| that the string dtype length is long enough to store the maximum | |
| integer/float value converted. | |
| See also | |
| -------- | |
| dtype, result_type | |
| Examples | |
| -------- | |
| Basic examples | |
| >>> np.can_cast(np.int32, np.int64) | |
| True | |
| >>> np.can_cast(np.float64, complex) | |
| True | |
| >>> np.can_cast(complex, float) | |
| False | |
| >>> np.can_cast('i8', 'f8') | |
| True | |
| >>> np.can_cast('i8', 'f4') | |
| False | |
| >>> np.can_cast('i4', 'S4') | |
| False | |
| Casting scalars | |
| >>> np.can_cast(100, 'i1') | |
| True | |
| >>> np.can_cast(150, 'i1') | |
| False | |
| >>> np.can_cast(150, 'u1') | |
| True | |
| >>> np.can_cast(3.5e100, np.float32) | |
| False | |
| >>> np.can_cast(1000.0, np.float32) | |
| True | |
| Array scalar checks the value, array does not | |
| >>> np.can_cast(np.array(1000.0), np.float32) | |
| True | |
| >>> np.can_cast(np.array([1000.0]), np.float32) | |
| False | |
| Using the casting rules | |
| >>> np.can_cast('i8', 'i8', 'no') | |
| True | |
| >>> np.can_cast('<i8', '>i8', 'no') | |
| False | |
| >>> np.can_cast('<i8', '>i8', 'equiv') | |
| True | |
| >>> np.can_cast('<i4', '>i8', 'equiv') | |
| False | |
| >>> np.can_cast('<i4', '>i8', 'safe') | |
| True | |
| >>> np.can_cast('<i8', '>i4', 'safe') | |
| False | |
| >>> np.can_cast('<i8', '>i4', 'same_kind') | |
| True | |
| >>> np.can_cast('<i8', '>u4', 'same_kind') | |
| False | |
| >>> np.can_cast('<i8', '>u4', 'unsafe') | |
| True | |
| """ | |
| return (from_,) | |
| def min_scalar_type(a): | |
| """ | |
| min_scalar_type(a) | |
| For scalar ``a``, returns the data type with the smallest size | |
| and smallest scalar kind which can hold its value. For non-scalar | |
| array ``a``, returns the vector's dtype unmodified. | |
| Floating point values are not demoted to integers, | |
| and complex values are not demoted to floats. | |
| Parameters | |
| ---------- | |
| a : scalar or array_like | |
| The value whose minimal data type is to be found. | |
| Returns | |
| ------- | |
| out : dtype | |
| The minimal data type. | |
| Notes | |
| ----- | |
| .. versionadded:: 1.6.0 | |
| See Also | |
| -------- | |
| result_type, promote_types, dtype, can_cast | |
| Examples | |
| -------- | |
| >>> np.min_scalar_type(10) | |
| dtype('uint8') | |
| >>> np.min_scalar_type(-260) | |
| dtype('int16') | |
| >>> np.min_scalar_type(3.1) | |
| dtype('float16') | |
| >>> np.min_scalar_type(1e50) | |
| dtype('float64') | |
| >>> np.min_scalar_type(np.arange(4,dtype='f8')) | |
| dtype('float64') | |
| """ | |
| return (a,) | |
| def result_type(*arrays_and_dtypes): | |
| """ | |
| result_type(*arrays_and_dtypes) | |
| Returns the type that results from applying the NumPy | |
| type promotion rules to the arguments. | |
| Type promotion in NumPy works similarly to the rules in languages | |
| like C++, with some slight differences. When both scalars and | |
| arrays are used, the array's type takes precedence and the actual value | |
| of the scalar is taken into account. | |
| For example, calculating 3*a, where a is an array of 32-bit floats, | |
| intuitively should result in a 32-bit float output. If the 3 is a | |
| 32-bit integer, the NumPy rules indicate it can't convert losslessly | |
| into a 32-bit float, so a 64-bit float should be the result type. | |
| By examining the value of the constant, '3', we see that it fits in | |
| an 8-bit integer, which can be cast losslessly into the 32-bit float. | |
| Parameters | |
| ---------- | |
| arrays_and_dtypes : list of arrays and dtypes | |
| The operands of some operation whose result type is needed. | |
| Returns | |
| ------- | |
| out : dtype | |
| The result type. | |
| See also | |
| -------- | |
| dtype, promote_types, min_scalar_type, can_cast | |
| Notes | |
| ----- | |
| .. versionadded:: 1.6.0 | |
| The specific algorithm used is as follows. | |
| Categories are determined by first checking which of boolean, | |
| integer (int/uint), or floating point (float/complex) the maximum | |
| kind of all the arrays and the scalars are. | |
| If there are only scalars or the maximum category of the scalars | |
| is higher than the maximum category of the arrays, | |
| the data types are combined with :func:`promote_types` | |
| to produce the return value. | |
| Otherwise, `min_scalar_type` is called on each array, and | |
| the resulting data types are all combined with :func:`promote_types` | |
| to produce the return value. | |
| The set of int values is not a subset of the uint values for types | |
| with the same number of bits, something not reflected in | |
| :func:`min_scalar_type`, but handled as a special case in `result_type`. | |
| Examples | |
| -------- | |
| >>> np.result_type(3, np.arange(7, dtype='i1')) | |
| dtype('int8') | |
| >>> np.result_type('i4', 'c8') | |
| dtype('complex128') | |
| >>> np.result_type(3.0, -2) | |
| dtype('float64') | |
| """ | |
| return arrays_and_dtypes | |
| def dot(a, b, out=None): | |
| """ | |
| dot(a, b, out=None) | |
| Dot product of two arrays. Specifically, | |
| - If both `a` and `b` are 1-D arrays, it is inner product of vectors | |
| (without complex conjugation). | |
| - If both `a` and `b` are 2-D arrays, it is matrix multiplication, | |
| but using :func:`matmul` or ``a @ b`` is preferred. | |
| - If either `a` or `b` is 0-D (scalar), it is equivalent to :func:`multiply` | |
| and using ``numpy.multiply(a, b)`` or ``a * b`` is preferred. | |
| - If `a` is an N-D array and `b` is a 1-D array, it is a sum product over | |
| the last axis of `a` and `b`. | |
| - If `a` is an N-D array and `b` is an M-D array (where ``M>=2``), it is a | |
| sum product over the last axis of `a` and the second-to-last axis of `b`:: | |
| dot(a, b)[i,j,k,m] = sum(a[i,j,:] * b[k,:,m]) | |
| Parameters | |
| ---------- | |
| a : array_like | |
| First argument. | |
| b : array_like | |
| Second argument. | |
| out : ndarray, optional | |
| Output argument. This must have the exact kind that would be returned | |
| if it was not used. In particular, it must have the right type, must be | |
| C-contiguous, and its dtype must be the dtype that would be returned | |
| for `dot(a,b)`. This is a performance feature. Therefore, if these | |
| conditions are not met, an exception is raised, instead of attempting | |
| to be flexible. | |
| Returns | |
| ------- | |
| output : ndarray | |
| Returns the dot product of `a` and `b`. If `a` and `b` are both | |
| scalars or both 1-D arrays then a scalar is returned; otherwise | |
| an array is returned. | |
| If `out` is given, then it is returned. | |
| Raises | |
| ------ | |
| ValueError | |
| If the last dimension of `a` is not the same size as | |
| the second-to-last dimension of `b`. | |
| See Also | |
| -------- | |
| vdot : Complex-conjugating dot product. | |
| tensordot : Sum products over arbitrary axes. | |
| einsum : Einstein summation convention. | |
| matmul : '@' operator as method with out parameter. | |
| linalg.multi_dot : Chained dot product. | |
| Examples | |
| -------- | |
| >>> np.dot(3, 4) | |
| 12 | |
| Neither argument is complex-conjugated: | |
| >>> np.dot([2j, 3j], [2j, 3j]) | |
| (-13+0j) | |
| For 2-D arrays it is the matrix product: | |
| >>> a = [[1, 0], [0, 1]] | |
| >>> b = [[4, 1], [2, 2]] | |
| >>> np.dot(a, b) | |
| array([[4, 1], | |
| [2, 2]]) | |
| >>> a = np.arange(3*4*5*6).reshape((3,4,5,6)) | |
| >>> b = np.arange(3*4*5*6)[::-1].reshape((5,4,6,3)) | |
| >>> np.dot(a, b)[2,3,2,1,2,2] | |
| 499128 | |
| >>> sum(a[2,3,2,:] * b[1,2,:,2]) | |
| 499128 | |
| """ | |
| return (a, b, out) | |
| def vdot(a, b): | |
| """ | |
| vdot(a, b) | |
| Return the dot product of two vectors. | |
| The vdot(`a`, `b`) function handles complex numbers differently than | |
| dot(`a`, `b`). If the first argument is complex the complex conjugate | |
| of the first argument is used for the calculation of the dot product. | |
| Note that `vdot` handles multidimensional arrays differently than `dot`: | |
| it does *not* perform a matrix product, but flattens input arguments | |
| to 1-D vectors first. Consequently, it should only be used for vectors. | |
| Parameters | |
| ---------- | |
| a : array_like | |
| If `a` is complex the complex conjugate is taken before calculation | |
| of the dot product. | |
| b : array_like | |
| Second argument to the dot product. | |
| Returns | |
| ------- | |
| output : ndarray | |
| Dot product of `a` and `b`. Can be an int, float, or | |
| complex depending on the types of `a` and `b`. | |
| See Also | |
| -------- | |
| dot : Return the dot product without using the complex conjugate of the | |
| first argument. | |
| Examples | |
| -------- | |
| >>> a = np.array([1+2j,3+4j]) | |
| >>> b = np.array([5+6j,7+8j]) | |
| >>> np.vdot(a, b) | |
| (70-8j) | |
| >>> np.vdot(b, a) | |
| (70+8j) | |
| Note that higher-dimensional arrays are flattened! | |
| >>> a = np.array([[1, 4], [5, 6]]) | |
| >>> b = np.array([[4, 1], [2, 2]]) | |
| >>> np.vdot(a, b) | |
| 30 | |
| >>> np.vdot(b, a) | |
| 30 | |
| >>> 1*4 + 4*1 + 5*2 + 6*2 | |
| 30 | |
| """ | |
| return (a, b) | |
| def bincount(x, weights=None, minlength=None): | |
| """ | |
| bincount(x, weights=None, minlength=0) | |
| Count number of occurrences of each value in array of non-negative ints. | |
| The number of bins (of size 1) is one larger than the largest value in | |
| `x`. If `minlength` is specified, there will be at least this number | |
| of bins in the output array (though it will be longer if necessary, | |
| depending on the contents of `x`). | |
| Each bin gives the number of occurrences of its index value in `x`. | |
| If `weights` is specified the input array is weighted by it, i.e. if a | |
| value ``n`` is found at position ``i``, ``out[n] += weight[i]`` instead | |
| of ``out[n] += 1``. | |
| Parameters | |
| ---------- | |
| x : array_like, 1 dimension, nonnegative ints | |
| Input array. | |
| weights : array_like, optional | |
| Weights, array of the same shape as `x`. | |
| minlength : int, optional | |
| A minimum number of bins for the output array. | |
| .. versionadded:: 1.6.0 | |
| Returns | |
| ------- | |
| out : ndarray of ints | |
| The result of binning the input array. | |
| The length of `out` is equal to ``np.amax(x)+1``. | |
| Raises | |
| ------ | |
| ValueError | |
| If the input is not 1-dimensional, or contains elements with negative | |
| values, or if `minlength` is negative. | |
| TypeError | |
| If the type of the input is float or complex. | |
| See Also | |
| -------- | |
| histogram, digitize, unique | |
| Examples | |
| -------- | |
| >>> np.bincount(np.arange(5)) | |
| array([1, 1, 1, 1, 1]) | |
| >>> np.bincount(np.array([0, 1, 1, 3, 2, 1, 7])) | |
| array([1, 3, 1, 1, 0, 0, 0, 1]) | |
| >>> x = np.array([0, 1, 1, 3, 2, 1, 7, 23]) | |
| >>> np.bincount(x).size == np.amax(x)+1 | |
| True | |
| The input array needs to be of integer dtype, otherwise a | |
| TypeError is raised: | |
| >>> np.bincount(np.arange(5, dtype=float)) | |
| Traceback (most recent call last): | |
| ... | |
| TypeError: Cannot cast array data from dtype('float64') to dtype('int64') | |
| according to the rule 'safe' | |
| A possible use of ``bincount`` is to perform sums over | |
| variable-size chunks of an array, using the ``weights`` keyword. | |
| >>> w = np.array([0.3, 0.5, 0.2, 0.7, 1., -0.6]) # weights | |
| >>> x = np.array([0, 1, 1, 2, 2, 2]) | |
| >>> np.bincount(x, weights=w) | |
| array([ 0.3, 0.7, 1.1]) | |
| """ | |
| return (x, weights) | |
| def ravel_multi_index(multi_index, dims, mode=None, order=None): | |
| """ | |
| ravel_multi_index(multi_index, dims, mode='raise', order='C') | |
| Converts a tuple of index arrays into an array of flat | |
| indices, applying boundary modes to the multi-index. | |
| Parameters | |
| ---------- | |
| multi_index : tuple of array_like | |
| A tuple of integer arrays, one array for each dimension. | |
| dims : tuple of ints | |
| The shape of array into which the indices from ``multi_index`` apply. | |
| mode : {'raise', 'wrap', 'clip'}, optional | |
| Specifies how out-of-bounds indices are handled. Can specify | |
| either one mode or a tuple of modes, one mode per index. | |
| * 'raise' -- raise an error (default) | |
| * 'wrap' -- wrap around | |
| * 'clip' -- clip to the range | |
| In 'clip' mode, a negative index which would normally | |
| wrap will clip to 0 instead. | |
| order : {'C', 'F'}, optional | |
| Determines whether the multi-index should be viewed as | |
| indexing in row-major (C-style) or column-major | |
| (Fortran-style) order. | |
| Returns | |
| ------- | |
| raveled_indices : ndarray | |
| An array of indices into the flattened version of an array | |
| of dimensions ``dims``. | |
| See Also | |
| -------- | |
| unravel_index | |
| Notes | |
| ----- | |
| .. versionadded:: 1.6.0 | |
| Examples | |
| -------- | |
| >>> arr = np.array([[3,6,6],[4,5,1]]) | |
| >>> np.ravel_multi_index(arr, (7,6)) | |
| array([22, 41, 37]) | |
| >>> np.ravel_multi_index(arr, (7,6), order='F') | |
| array([31, 41, 13]) | |
| >>> np.ravel_multi_index(arr, (4,6), mode='clip') | |
| array([22, 23, 19]) | |
| >>> np.ravel_multi_index(arr, (4,4), mode=('clip','wrap')) | |
| array([12, 13, 13]) | |
| >>> np.ravel_multi_index((3,1,4,1), (6,7,8,9)) | |
| 1621 | |
| """ | |
| return multi_index | |
| def unravel_index(indices, shape=None, order=None): | |
| """ | |
| unravel_index(indices, shape, order='C') | |
| Converts a flat index or array of flat indices into a tuple | |
| of coordinate arrays. | |
| Parameters | |
| ---------- | |
| indices : array_like | |
| An integer array whose elements are indices into the flattened | |
| version of an array of dimensions ``shape``. Before version 1.6.0, | |
| this function accepted just one index value. | |
| shape : tuple of ints | |
| The shape of the array to use for unraveling ``indices``. | |
| .. versionchanged:: 1.16.0 | |
| Renamed from ``dims`` to ``shape``. | |
| order : {'C', 'F'}, optional | |
| Determines whether the indices should be viewed as indexing in | |
| row-major (C-style) or column-major (Fortran-style) order. | |
| .. versionadded:: 1.6.0 | |
| Returns | |
| ------- | |
| unraveled_coords : tuple of ndarray | |
| Each array in the tuple has the same shape as the ``indices`` | |
| array. | |
| See Also | |
| -------- | |
| ravel_multi_index | |
| Examples | |
| -------- | |
| >>> np.unravel_index([22, 41, 37], (7,6)) | |
| (array([3, 6, 6]), array([4, 5, 1])) | |
| >>> np.unravel_index([31, 41, 13], (7,6), order='F') | |
| (array([3, 6, 6]), array([4, 5, 1])) | |
| >>> np.unravel_index(1621, (6,7,8,9)) | |
| (3, 1, 4, 1) | |
| """ | |
| return (indices,) | |
| def copyto(dst, src, casting=None, where=None): | |
| """ | |
| copyto(dst, src, casting='same_kind', where=True) | |
| Copies values from one array to another, broadcasting as necessary. | |
| Raises a TypeError if the `casting` rule is violated, and if | |
| `where` is provided, it selects which elements to copy. | |
| .. versionadded:: 1.7.0 | |
| Parameters | |
| ---------- | |
| dst : ndarray | |
| The array into which values are copied. | |
| src : array_like | |
| The array from which values are copied. | |
| casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional | |
| Controls what kind of data casting may occur when copying. | |
| * 'no' means the data types should not be cast at all. | |
| * 'equiv' means only byte-order changes are allowed. | |
| * 'safe' means only casts which can preserve values are allowed. | |
| * 'same_kind' means only safe casts or casts within a kind, | |
| like float64 to float32, are allowed. | |
| * 'unsafe' means any data conversions may be done. | |
| where : array_like of bool, optional | |
| A boolean array which is broadcasted to match the dimensions | |
| of `dst`, and selects elements to copy from `src` to `dst` | |
| wherever it contains the value True. | |
| """ | |
| return (dst, src, where) | |
| def putmask(a, mask, values): | |
| """ | |
| putmask(a, mask, values) | |
| Changes elements of an array based on conditional and input values. | |
| Sets ``a.flat[n] = values[n]`` for each n where ``mask.flat[n]==True``. | |
| If `values` is not the same size as `a` and `mask` then it will repeat. | |
| This gives behavior different from ``a[mask] = values``. | |
| Parameters | |
| ---------- | |
| a : ndarray | |
| Target array. | |
| mask : array_like | |
| Boolean mask array. It has to be the same shape as `a`. | |
| values : array_like | |
| Values to put into `a` where `mask` is True. If `values` is smaller | |
| than `a` it will be repeated. | |
| See Also | |
| -------- | |
| place, put, take, copyto | |
| Examples | |
| -------- | |
| >>> x = np.arange(6).reshape(2, 3) | |
| >>> np.putmask(x, x>2, x**2) | |
| >>> x | |
| array([[ 0, 1, 2], | |
| [ 9, 16, 25]]) | |
| If `values` is smaller than `a` it is repeated: | |
| >>> x = np.arange(5) | |
| >>> np.putmask(x, x>1, [-33, -44]) | |
| >>> x | |
| array([ 0, 1, -33, -44, -33]) | |
| """ | |
| return (a, mask, values) | |
| def packbits(a, axis=None, bitorder='big'): | |
| """ | |
| packbits(a, axis=None, bitorder='big') | |
| Packs the elements of a binary-valued array into bits in a uint8 array. | |
| The result is padded to full bytes by inserting zero bits at the end. | |
| Parameters | |
| ---------- | |
| a : array_like | |
| An array of integers or booleans whose elements should be packed to | |
| bits. | |
| axis : int, optional | |
| The dimension over which bit-packing is done. | |
| ``None`` implies packing the flattened array. | |
| bitorder : {'big', 'little'}, optional | |
| The order of the input bits. 'big' will mimic bin(val), | |
| ``[0, 0, 0, 0, 0, 0, 1, 1] => 3 = 0b00000011``, 'little' will | |
| reverse the order so ``[1, 1, 0, 0, 0, 0, 0, 0] => 3``. | |
| Defaults to 'big'. | |
| .. versionadded:: 1.17.0 | |
| Returns | |
| ------- | |
| packed : ndarray | |
| Array of type uint8 whose elements represent bits corresponding to the | |
| logical (0 or nonzero) value of the input elements. The shape of | |
| `packed` has the same number of dimensions as the input (unless `axis` | |
| is None, in which case the output is 1-D). | |
| See Also | |
| -------- | |
| unpackbits: Unpacks elements of a uint8 array into a binary-valued output | |
| array. | |
| Examples | |
| -------- | |
| >>> a = np.array([[[1,0,1], | |
| ... [0,1,0]], | |
| ... [[1,1,0], | |
| ... [0,0,1]]]) | |
| >>> b = np.packbits(a, axis=-1) | |
| >>> b | |
| array([[[160], | |
| [ 64]], | |
| [[192], | |
| [ 32]]], dtype=uint8) | |
| Note that in binary 160 = 1010 0000, 64 = 0100 0000, 192 = 1100 0000, | |
| and 32 = 0010 0000. | |
| """ | |
| return (a,) | |
| def unpackbits(a, axis=None, count=None, bitorder='big'): | |
| """ | |
| unpackbits(a, axis=None, count=None, bitorder='big') | |
| Unpacks elements of a uint8 array into a binary-valued output array. | |
| Each element of `a` represents a bit-field that should be unpacked | |
| into a binary-valued output array. The shape of the output array is | |
| either 1-D (if `axis` is ``None``) or the same shape as the input | |
| array with unpacking done along the axis specified. | |
| Parameters | |
| ---------- | |
| a : ndarray, uint8 type | |
| Input array. | |
| axis : int, optional | |
| The dimension over which bit-unpacking is done. | |
| ``None`` implies unpacking the flattened array. | |
| count : int or None, optional | |
| The number of elements to unpack along `axis`, provided as a way | |
| of undoing the effect of packing a size that is not a multiple | |
| of eight. A non-negative number means to only unpack `count` | |
| bits. A negative number means to trim off that many bits from | |
| the end. ``None`` means to unpack the entire array (the | |
| default). Counts larger than the available number of bits will | |
| add zero padding to the output. Negative counts must not | |
| exceed the available number of bits. | |
| .. versionadded:: 1.17.0 | |
| bitorder : {'big', 'little'}, optional | |
| The order of the returned bits. 'big' will mimic bin(val), | |
| ``3 = 0b00000011 => [0, 0, 0, 0, 0, 0, 1, 1]``, 'little' will reverse | |
| the order to ``[1, 1, 0, 0, 0, 0, 0, 0]``. | |
| Defaults to 'big'. | |
| .. versionadded:: 1.17.0 | |
| Returns | |
| ------- | |
| unpacked : ndarray, uint8 type | |
| The elements are binary-valued (0 or 1). | |
| See Also | |
| -------- | |
| packbits : Packs the elements of a binary-valued array into bits in | |
| a uint8 array. | |
| Examples | |
| -------- | |
| >>> a = np.array([[2], [7], [23]], dtype=np.uint8) | |
| >>> a | |
| array([[ 2], | |
| [ 7], | |
| [23]], dtype=uint8) | |
| >>> b = np.unpackbits(a, axis=1) | |
| >>> b | |
| array([[0, 0, 0, 0, 0, 0, 1, 0], | |
| [0, 0, 0, 0, 0, 1, 1, 1], | |
| [0, 0, 0, 1, 0, 1, 1, 1]], dtype=uint8) | |
| >>> c = np.unpackbits(a, axis=1, count=-3) | |
| >>> c | |
| array([[0, 0, 0, 0, 0], | |
| [0, 0, 0, 0, 0], | |
| [0, 0, 0, 1, 0]], dtype=uint8) | |
| >>> p = np.packbits(b, axis=0) | |
| >>> np.unpackbits(p, axis=0) | |
| array([[0, 0, 0, 0, 0, 0, 1, 0], | |
| [0, 0, 0, 0, 0, 1, 1, 1], | |
| [0, 0, 0, 1, 0, 1, 1, 1], | |
| [0, 0, 0, 0, 0, 0, 0, 0], | |
| [0, 0, 0, 0, 0, 0, 0, 0], | |
| [0, 0, 0, 0, 0, 0, 0, 0], | |
| [0, 0, 0, 0, 0, 0, 0, 0], | |
| [0, 0, 0, 0, 0, 0, 0, 0]], dtype=uint8) | |
| >>> np.array_equal(b, np.unpackbits(p, axis=0, count=b.shape[0])) | |
| True | |
| """ | |
| return (a,) | |
| def shares_memory(a, b, max_work=None): | |
| """ | |
| shares_memory(a, b, max_work=None) | |
| Determine if two arrays share memory. | |
| .. warning:: | |
| This function can be exponentially slow for some inputs, unless | |
| `max_work` is set to a finite number or ``MAY_SHARE_BOUNDS``. | |
| If in doubt, use `numpy.may_share_memory` instead. | |
| Parameters | |
| ---------- | |
| a, b : ndarray | |
| Input arrays | |
| max_work : int, optional | |
| Effort to spend on solving the overlap problem (maximum number | |
| of candidate solutions to consider). The following special | |
| values are recognized: | |
| max_work=MAY_SHARE_EXACT (default) | |
| The problem is solved exactly. In this case, the function returns | |
| True only if there is an element shared between the arrays. Finding | |
| the exact solution may take extremely long in some cases. | |
| max_work=MAY_SHARE_BOUNDS | |
| Only the memory bounds of a and b are checked. | |
| Raises | |
| ------ | |
| numpy.TooHardError | |
| Exceeded max_work. | |
| Returns | |
| ------- | |
| out : bool | |
| See Also | |
| -------- | |
| may_share_memory | |
| Examples | |
| -------- | |
| >>> x = np.array([1, 2, 3, 4]) | |
| >>> np.shares_memory(x, np.array([5, 6, 7])) | |
| False | |
| >>> np.shares_memory(x[::2], x) | |
| True | |
| >>> np.shares_memory(x[::2], x[1::2]) | |
| False | |
| Checking whether two arrays share memory is NP-complete, and | |
| runtime may increase exponentially in the number of | |
| dimensions. Hence, `max_work` should generally be set to a finite | |
| number, as it is possible to construct examples that take | |
| extremely long to run: | |
| >>> from numpy.lib.stride_tricks import as_strided | |
| >>> x = np.zeros([192163377], dtype=np.int8) | |
| >>> x1 = as_strided(x, strides=(36674, 61119, 85569), shape=(1049, 1049, 1049)) | |
| >>> x2 = as_strided(x[64023025:], strides=(12223, 12224, 1), shape=(1049, 1049, 1)) | |
| >>> np.shares_memory(x1, x2, max_work=1000) | |
| Traceback (most recent call last): | |
| ... | |
| numpy.TooHardError: Exceeded max_work | |
| Running ``np.shares_memory(x1, x2)`` without `max_work` set takes | |
| around 1 minute for this case. It is possible to find problems | |
| that take still significantly longer. | |
| """ | |
| return (a, b) | |
| def may_share_memory(a, b, max_work=None): | |
| """ | |
| may_share_memory(a, b, max_work=None) | |
| Determine if two arrays might share memory | |
| A return of True does not necessarily mean that the two arrays | |
| share any element. It just means that they *might*. | |
| Only the memory bounds of a and b are checked by default. | |
| Parameters | |
| ---------- | |
| a, b : ndarray | |
| Input arrays | |
| max_work : int, optional | |
| Effort to spend on solving the overlap problem. See | |
| `shares_memory` for details. Default for ``may_share_memory`` | |
| is to do a bounds check. | |
| Returns | |
| ------- | |
| out : bool | |
| See Also | |
| -------- | |
| shares_memory | |
| Examples | |
| -------- | |
| >>> np.may_share_memory(np.array([1,2]), np.array([5,8,9])) | |
| False | |
| >>> x = np.zeros([3, 4]) | |
| >>> np.may_share_memory(x[:,0], x[:,1]) | |
| True | |
| """ | |
| return (a, b) | |
| def is_busday(dates, weekmask=None, holidays=None, busdaycal=None, out=None): | |
| """ | |
| is_busday(dates, weekmask='1111100', holidays=None, busdaycal=None, out=None) | |
| Calculates which of the given dates are valid days, and which are not. | |
| .. versionadded:: 1.7.0 | |
| Parameters | |
| ---------- | |
| dates : array_like of datetime64[D] | |
| The array of dates to process. | |
| weekmask : str or array_like of bool, optional | |
| A seven-element array indicating which of Monday through Sunday are | |
| valid days. May be specified as a length-seven list or array, like | |
| [1,1,1,1,1,0,0]; a length-seven string, like '1111100'; or a string | |
| like "Mon Tue Wed Thu Fri", made up of 3-character abbreviations for | |
| weekdays, optionally separated by white space. Valid abbreviations | |
| are: Mon Tue Wed Thu Fri Sat Sun | |
| holidays : array_like of datetime64[D], optional | |
| An array of dates to consider as invalid dates. They may be | |
| specified in any order, and NaT (not-a-time) dates are ignored. | |
| This list is saved in a normalized form that is suited for | |
| fast calculations of valid days. | |
| busdaycal : busdaycalendar, optional | |
| A `busdaycalendar` object which specifies the valid days. If this | |
| parameter is provided, neither weekmask nor holidays may be | |
| provided. | |
| out : array of bool, optional | |
| If provided, this array is filled with the result. | |
| Returns | |
| ------- | |
| out : array of bool | |
| An array with the same shape as ``dates``, containing True for | |
| each valid day, and False for each invalid day. | |
| See Also | |
| -------- | |
| busdaycalendar : An object that specifies a custom set of valid days. | |
| busday_offset : Applies an offset counted in valid days. | |
| busday_count : Counts how many valid days are in a half-open date range. | |
| Examples | |
| -------- | |
| >>> # The weekdays are Friday, Saturday, and Monday | |
| ... np.is_busday(['2011-07-01', '2011-07-02', '2011-07-18'], | |
| ... holidays=['2011-07-01', '2011-07-04', '2011-07-17']) | |
| array([False, False, True]) | |
| """ | |
| return (dates, weekmask, holidays, out) | |
| def busday_offset(dates, offsets, roll=None, weekmask=None, holidays=None, | |
| busdaycal=None, out=None): | |
| """ | |
| busday_offset(dates, offsets, roll='raise', weekmask='1111100', holidays=None, busdaycal=None, out=None) | |
| First adjusts the date to fall on a valid day according to | |
| the ``roll`` rule, then applies offsets to the given dates | |
| counted in valid days. | |
| .. versionadded:: 1.7.0 | |
| Parameters | |
| ---------- | |
| dates : array_like of datetime64[D] | |
| The array of dates to process. | |
| offsets : array_like of int | |
| The array of offsets, which is broadcast with ``dates``. | |
| roll : {'raise', 'nat', 'forward', 'following', 'backward', 'preceding', 'modifiedfollowing', 'modifiedpreceding'}, optional | |
| How to treat dates that do not fall on a valid day. The default | |
| is 'raise'. | |
| * 'raise' means to raise an exception for an invalid day. | |
| * 'nat' means to return a NaT (not-a-time) for an invalid day. | |
| * 'forward' and 'following' mean to take the first valid day | |
| later in time. | |
| * 'backward' and 'preceding' mean to take the first valid day | |
| earlier in time. | |
| * 'modifiedfollowing' means to take the first valid day | |
| later in time unless it is across a Month boundary, in which | |
| case to take the first valid day earlier in time. | |
| * 'modifiedpreceding' means to take the first valid day | |
| earlier in time unless it is across a Month boundary, in which | |
| case to take the first valid day later in time. | |
| weekmask : str or array_like of bool, optional | |
| A seven-element array indicating which of Monday through Sunday are | |
| valid days. May be specified as a length-seven list or array, like | |
| [1,1,1,1,1,0,0]; a length-seven string, like '1111100'; or a string | |
| like "Mon Tue Wed Thu Fri", made up of 3-character abbreviations for | |
| weekdays, optionally separated by white space. Valid abbreviations | |
| are: Mon Tue Wed Thu Fri Sat Sun | |
| holidays : array_like of datetime64[D], optional | |
| An array of dates to consider as invalid dates. They may be | |
| specified in any order, and NaT (not-a-time) dates are ignored. | |
| This list is saved in a normalized form that is suited for | |
| fast calculations of valid days. | |
| busdaycal : busdaycalendar, optional | |
| A `busdaycalendar` object which specifies the valid days. If this | |
| parameter is provided, neither weekmask nor holidays may be | |
| provided. | |
| out : array of datetime64[D], optional | |
| If provided, this array is filled with the result. | |
| Returns | |
| ------- | |
| out : array of datetime64[D] | |
| An array with a shape from broadcasting ``dates`` and ``offsets`` | |
| together, containing the dates with offsets applied. | |
| See Also | |
| -------- | |
| busdaycalendar : An object that specifies a custom set of valid days. | |
| is_busday : Returns a boolean array indicating valid days. | |
| busday_count : Counts how many valid days are in a half-open date range. | |
| Examples | |
| -------- | |
| >>> # First business day in October 2011 (not accounting for holidays) | |
| ... np.busday_offset('2011-10', 0, roll='forward') | |
| numpy.datetime64('2011-10-03') | |
| >>> # Last business day in February 2012 (not accounting for holidays) | |
| ... np.busday_offset('2012-03', -1, roll='forward') | |
| numpy.datetime64('2012-02-29') | |
| >>> # Third Wednesday in January 2011 | |
| ... np.busday_offset('2011-01', 2, roll='forward', weekmask='Wed') | |
| numpy.datetime64('2011-01-19') | |
| >>> # 2012 Mother's Day in Canada and the U.S. | |
| ... np.busday_offset('2012-05', 1, roll='forward', weekmask='Sun') | |
| numpy.datetime64('2012-05-13') | |
| >>> # First business day on or after a date | |
| ... np.busday_offset('2011-03-20', 0, roll='forward') | |
| numpy.datetime64('2011-03-21') | |
| >>> np.busday_offset('2011-03-22', 0, roll='forward') | |
| numpy.datetime64('2011-03-22') | |
| >>> # First business day after a date | |
| ... np.busday_offset('2011-03-20', 1, roll='backward') | |
| numpy.datetime64('2011-03-21') | |
| >>> np.busday_offset('2011-03-22', 1, roll='backward') | |
| numpy.datetime64('2011-03-23') | |
| """ | |
| return (dates, offsets, weekmask, holidays, out) | |
| def busday_count(begindates, enddates, weekmask=None, holidays=None, | |
| busdaycal=None, out=None): | |
| """ | |
| busday_count(begindates, enddates, weekmask='1111100', holidays=[], busdaycal=None, out=None) | |
| Counts the number of valid days between `begindates` and | |
| `enddates`, not including the day of `enddates`. | |
| If ``enddates`` specifies a date value that is earlier than the | |
| corresponding ``begindates`` date value, the count will be negative. | |
| .. versionadded:: 1.7.0 | |
| Parameters | |
| ---------- | |
| begindates : array_like of datetime64[D] | |
| The array of the first dates for counting. | |
| enddates : array_like of datetime64[D] | |
| The array of the end dates for counting, which are excluded | |
| from the count themselves. | |
| weekmask : str or array_like of bool, optional | |
| A seven-element array indicating which of Monday through Sunday are | |
| valid days. May be specified as a length-seven list or array, like | |
| [1,1,1,1,1,0,0]; a length-seven string, like '1111100'; or a string | |
| like "Mon Tue Wed Thu Fri", made up of 3-character abbreviations for | |
| weekdays, optionally separated by white space. Valid abbreviations | |
| are: Mon Tue Wed Thu Fri Sat Sun | |
| holidays : array_like of datetime64[D], optional | |
| An array of dates to consider as invalid dates. They may be | |
| specified in any order, and NaT (not-a-time) dates are ignored. | |
| This list is saved in a normalized form that is suited for | |
| fast calculations of valid days. | |
| busdaycal : busdaycalendar, optional | |
| A `busdaycalendar` object which specifies the valid days. If this | |
| parameter is provided, neither weekmask nor holidays may be | |
| provided. | |
| out : array of int, optional | |
| If provided, this array is filled with the result. | |
| Returns | |
| ------- | |
| out : array of int | |
| An array with a shape from broadcasting ``begindates`` and ``enddates`` | |
| together, containing the number of valid days between | |
| the begin and end dates. | |
| See Also | |
| -------- | |
| busdaycalendar : An object that specifies a custom set of valid days. | |
| is_busday : Returns a boolean array indicating valid days. | |
| busday_offset : Applies an offset counted in valid days. | |
| Examples | |
| -------- | |
| >>> # Number of weekdays in January 2011 | |
| ... np.busday_count('2011-01', '2011-02') | |
| 21 | |
| >>> # Number of weekdays in 2011 | |
| >>> np.busday_count('2011', '2012') | |
| 260 | |
| >>> # Number of Saturdays in 2011 | |
| ... np.busday_count('2011', '2012', weekmask='Sat') | |
| 53 | |
| """ | |
| return (begindates, enddates, weekmask, holidays, out) | |
| def datetime_as_string(arr, unit=None, timezone=None, casting=None): | |
| """ | |
| datetime_as_string(arr, unit=None, timezone='naive', casting='same_kind') | |
| Convert an array of datetimes into an array of strings. | |
| Parameters | |
| ---------- | |
| arr : array_like of datetime64 | |
| The array of UTC timestamps to format. | |
| unit : str | |
| One of None, 'auto', or a :ref:`datetime unit <arrays.dtypes.dateunits>`. | |
| timezone : {'naive', 'UTC', 'local'} or tzinfo | |
| Timezone information to use when displaying the datetime. If 'UTC', end | |
| with a Z to indicate UTC time. If 'local', convert to the local timezone | |
| first, and suffix with a +-#### timezone offset. If a tzinfo object, | |
| then do as with 'local', but use the specified timezone. | |
| casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'} | |
| Casting to allow when changing between datetime units. | |
| Returns | |
| ------- | |
| str_arr : ndarray | |
| An array of strings the same shape as `arr`. | |
| Examples | |
| -------- | |
| >>> import pytz | |
| >>> d = np.arange('2002-10-27T04:30', 4*60, 60, dtype='M8[m]') | |
| >>> d | |
| array(['2002-10-27T04:30', '2002-10-27T05:30', '2002-10-27T06:30', | |
| '2002-10-27T07:30'], dtype='datetime64[m]') | |
| Setting the timezone to UTC shows the same information, but with a Z suffix | |
| >>> np.datetime_as_string(d, timezone='UTC') | |
| array(['2002-10-27T04:30Z', '2002-10-27T05:30Z', '2002-10-27T06:30Z', | |
| '2002-10-27T07:30Z'], dtype='<U35') | |
| Note that we picked datetimes that cross a DST boundary. Passing in a | |
| ``pytz`` timezone object will print the appropriate offset | |
| >>> np.datetime_as_string(d, timezone=pytz.timezone('US/Eastern')) | |
| array(['2002-10-27T00:30-0400', '2002-10-27T01:30-0400', | |
| '2002-10-27T01:30-0500', '2002-10-27T02:30-0500'], dtype='<U39') | |
| Passing in a unit will change the precision | |
| >>> np.datetime_as_string(d, unit='h') | |
| array(['2002-10-27T04', '2002-10-27T05', '2002-10-27T06', '2002-10-27T07'], | |
| dtype='<U32') | |
| >>> np.datetime_as_string(d, unit='s') | |
| array(['2002-10-27T04:30:00', '2002-10-27T05:30:00', '2002-10-27T06:30:00', | |
| '2002-10-27T07:30:00'], dtype='<U38') | |
| 'casting' can be used to specify whether precision can be changed | |
| >>> np.datetime_as_string(d, unit='h', casting='safe') | |
| Traceback (most recent call last): | |
| ... | |
| TypeError: Cannot create a datetime string as units 'h' from a NumPy | |
| datetime with units 'm' according to the rule 'safe' | |
| """ | |
| return (arr,) | |