Chris@87: """ Chris@87: This is only meant to add docs to objects defined in C-extension modules. Chris@87: The purpose is to allow easier editing of the docstrings without Chris@87: requiring a re-compile. Chris@87: Chris@87: NOTE: Many of the methods of ndarray have corresponding functions. Chris@87: If you update these docstrings, please keep also the ones in Chris@87: core/fromnumeric.py, core/defmatrix.py up-to-date. Chris@87: Chris@87: """ Chris@87: from __future__ import division, absolute_import, print_function Chris@87: Chris@87: from numpy.lib import add_newdoc Chris@87: Chris@87: ############################################################################### Chris@87: # Chris@87: # flatiter Chris@87: # Chris@87: # flatiter needs a toplevel description Chris@87: # Chris@87: ############################################################################### Chris@87: Chris@87: add_newdoc('numpy.core', 'flatiter', Chris@87: """ Chris@87: Flat iterator object to iterate over arrays. Chris@87: Chris@87: A `flatiter` iterator is returned by ``x.flat`` for any array `x`. Chris@87: It allows iterating over the array as if it were a 1-D array, Chris@87: either in a for-loop or by calling its `next` method. Chris@87: Chris@87: Iteration is done in C-contiguous style, with the last index varying the Chris@87: fastest. The iterator can also be indexed using basic slicing or Chris@87: advanced indexing. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: ndarray.flat : Return a flat iterator over an array. Chris@87: ndarray.flatten : Returns a flattened copy of an array. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: A `flatiter` iterator can not be constructed directly from Python code Chris@87: by calling the `flatiter` constructor. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.arange(6).reshape(2, 3) Chris@87: >>> fl = x.flat Chris@87: >>> type(fl) Chris@87: Chris@87: >>> for item in fl: Chris@87: ... print item Chris@87: ... Chris@87: 0 Chris@87: 1 Chris@87: 2 Chris@87: 3 Chris@87: 4 Chris@87: 5 Chris@87: Chris@87: >>> fl[2:4] Chris@87: array([2, 3]) Chris@87: Chris@87: """) Chris@87: Chris@87: # flatiter attributes Chris@87: Chris@87: add_newdoc('numpy.core', 'flatiter', ('base', Chris@87: """ Chris@87: A reference to the array that is iterated over. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.arange(5) Chris@87: >>> fl = x.flat Chris@87: >>> fl.base is x Chris@87: True Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core', 'flatiter', ('coords', Chris@87: """ Chris@87: An N-dimensional tuple of current coordinates. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.arange(6).reshape(2, 3) Chris@87: >>> fl = x.flat Chris@87: >>> fl.coords Chris@87: (0, 0) Chris@87: >>> fl.next() Chris@87: 0 Chris@87: >>> fl.coords Chris@87: (0, 1) Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core', 'flatiter', ('index', Chris@87: """ Chris@87: Current flat index into the array. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.arange(6).reshape(2, 3) Chris@87: >>> fl = x.flat Chris@87: >>> fl.index Chris@87: 0 Chris@87: >>> fl.next() Chris@87: 0 Chris@87: >>> fl.index Chris@87: 1 Chris@87: Chris@87: """)) Chris@87: Chris@87: # flatiter functions Chris@87: Chris@87: add_newdoc('numpy.core', 'flatiter', ('__array__', Chris@87: """__array__(type=None) Get array from iterator Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core', 'flatiter', ('copy', Chris@87: """ Chris@87: copy() Chris@87: Chris@87: Get a copy of the iterator as a 1-D array. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.arange(6).reshape(2, 3) Chris@87: >>> x Chris@87: array([[0, 1, 2], Chris@87: [3, 4, 5]]) Chris@87: >>> fl = x.flat Chris@87: >>> fl.copy() Chris@87: array([0, 1, 2, 3, 4, 5]) Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: ############################################################################### Chris@87: # Chris@87: # nditer Chris@87: # Chris@87: ############################################################################### Chris@87: Chris@87: add_newdoc('numpy.core', 'nditer', Chris@87: """ Chris@87: Efficient multi-dimensional iterator object to iterate over arrays. Chris@87: To get started using this object, see the Chris@87: :ref:`introductory guide to array iteration `. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: op : ndarray or sequence of array_like Chris@87: The array(s) to iterate over. Chris@87: flags : sequence of str, optional Chris@87: Flags to control the behavior of the iterator. Chris@87: Chris@87: * "buffered" enables buffering when required. Chris@87: * "c_index" causes a C-order index to be tracked. Chris@87: * "f_index" causes a Fortran-order index to be tracked. Chris@87: * "multi_index" causes a multi-index, or a tuple of indices Chris@87: with one per iteration dimension, to be tracked. Chris@87: * "common_dtype" causes all the operands to be converted to Chris@87: a common data type, with copying or buffering as necessary. Chris@87: * "delay_bufalloc" delays allocation of the buffers until Chris@87: a reset() call is made. Allows "allocate" operands to Chris@87: be initialized before their values are copied into the buffers. Chris@87: * "external_loop" causes the `values` given to be Chris@87: one-dimensional arrays with multiple values instead of Chris@87: zero-dimensional arrays. Chris@87: * "grow_inner" allows the `value` array sizes to be made Chris@87: larger than the buffer size when both "buffered" and Chris@87: "external_loop" is used. Chris@87: * "ranged" allows the iterator to be restricted to a sub-range Chris@87: of the iterindex values. Chris@87: * "refs_ok" enables iteration of reference types, such as Chris@87: object arrays. Chris@87: * "reduce_ok" enables iteration of "readwrite" operands Chris@87: which are broadcasted, also known as reduction operands. Chris@87: * "zerosize_ok" allows `itersize` to be zero. Chris@87: op_flags : list of list of str, optional Chris@87: This is a list of flags for each operand. At minimum, one of Chris@87: "readonly", "readwrite", or "writeonly" must be specified. Chris@87: Chris@87: * "readonly" indicates the operand will only be read from. Chris@87: * "readwrite" indicates the operand will be read from and written to. Chris@87: * "writeonly" indicates the operand will only be written to. Chris@87: * "no_broadcast" prevents the operand from being broadcasted. Chris@87: * "contig" forces the operand data to be contiguous. Chris@87: * "aligned" forces the operand data to be aligned. Chris@87: * "nbo" forces the operand data to be in native byte order. Chris@87: * "copy" allows a temporary read-only copy if required. Chris@87: * "updateifcopy" allows a temporary read-write copy if required. Chris@87: * "allocate" causes the array to be allocated if it is None Chris@87: in the `op` parameter. Chris@87: * "no_subtype" prevents an "allocate" operand from using a subtype. Chris@87: * "arraymask" indicates that this operand is the mask to use Chris@87: for selecting elements when writing to operands with the Chris@87: 'writemasked' flag set. The iterator does not enforce this, Chris@87: but when writing from a buffer back to the array, it only Chris@87: copies those elements indicated by this mask. Chris@87: * 'writemasked' indicates that only elements where the chosen Chris@87: 'arraymask' operand is True will be written to. Chris@87: op_dtypes : dtype or tuple of dtype(s), optional Chris@87: The required data type(s) of the operands. If copying or buffering Chris@87: is enabled, the data will be converted to/from their original types. Chris@87: order : {'C', 'F', 'A', 'K'}, optional Chris@87: Controls the iteration order. 'C' means C order, 'F' means Chris@87: Fortran order, 'A' means 'F' order if all the arrays are Fortran Chris@87: contiguous, 'C' order otherwise, and 'K' means as close to the Chris@87: order the array elements appear in memory as possible. This also Chris@87: affects the element memory order of "allocate" operands, as they Chris@87: are allocated to be compatible with iteration order. Chris@87: Default is 'K'. Chris@87: casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional Chris@87: Controls what kind of data casting may occur when making a copy Chris@87: or buffering. Setting this to 'unsafe' is not recommended, Chris@87: as it can adversely affect accumulations. Chris@87: Chris@87: * 'no' means the data types should not be cast at all. Chris@87: * 'equiv' means only byte-order changes are allowed. Chris@87: * 'safe' means only casts which can preserve values are allowed. Chris@87: * 'same_kind' means only safe casts or casts within a kind, Chris@87: like float64 to float32, are allowed. Chris@87: * 'unsafe' means any data conversions may be done. Chris@87: op_axes : list of list of ints, optional Chris@87: If provided, is a list of ints or None for each operands. Chris@87: The list of axes for an operand is a mapping from the dimensions Chris@87: of the iterator to the dimensions of the operand. A value of Chris@87: -1 can be placed for entries, causing that dimension to be Chris@87: treated as "newaxis". Chris@87: itershape : tuple of ints, optional Chris@87: The desired shape of the iterator. This allows "allocate" operands Chris@87: with a dimension mapped by op_axes not corresponding to a dimension Chris@87: of a different operand to get a value not equal to 1 for that Chris@87: dimension. Chris@87: buffersize : int, optional Chris@87: When buffering is enabled, controls the size of the temporary Chris@87: buffers. Set to 0 for the default value. Chris@87: Chris@87: Attributes Chris@87: ---------- Chris@87: dtypes : tuple of dtype(s) Chris@87: The data types of the values provided in `value`. This may be Chris@87: different from the operand data types if buffering is enabled. Chris@87: finished : bool Chris@87: Whether the iteration over the operands is finished or not. Chris@87: has_delayed_bufalloc : bool Chris@87: If True, the iterator was created with the "delay_bufalloc" flag, Chris@87: and no reset() function was called on it yet. Chris@87: has_index : bool Chris@87: If True, the iterator was created with either the "c_index" or Chris@87: the "f_index" flag, and the property `index` can be used to Chris@87: retrieve it. Chris@87: has_multi_index : bool Chris@87: If True, the iterator was created with the "multi_index" flag, Chris@87: and the property `multi_index` can be used to retrieve it. Chris@87: index : Chris@87: When the "c_index" or "f_index" flag was used, this property Chris@87: provides access to the index. Raises a ValueError if accessed Chris@87: and `has_index` is False. Chris@87: iterationneedsapi : bool Chris@87: Whether iteration requires access to the Python API, for example Chris@87: if one of the operands is an object array. Chris@87: iterindex : int Chris@87: An index which matches the order of iteration. Chris@87: itersize : int Chris@87: Size of the iterator. Chris@87: itviews : Chris@87: Structured view(s) of `operands` in memory, matching the reordered Chris@87: and optimized iterator access pattern. Chris@87: multi_index : Chris@87: When the "multi_index" flag was used, this property Chris@87: provides access to the index. Raises a ValueError if accessed Chris@87: accessed and `has_multi_index` is False. Chris@87: ndim : int Chris@87: The iterator's dimension. Chris@87: nop : int Chris@87: The number of iterator operands. Chris@87: operands : tuple of operand(s) Chris@87: The array(s) to be iterated over. Chris@87: shape : tuple of ints Chris@87: Shape tuple, the shape of the iterator. Chris@87: value : Chris@87: Value of `operands` at current iteration. Normally, this is a Chris@87: tuple of array scalars, but if the flag "external_loop" is used, Chris@87: it is a tuple of one dimensional arrays. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: `nditer` supersedes `flatiter`. The iterator implementation behind Chris@87: `nditer` is also exposed by the Numpy C API. Chris@87: Chris@87: The Python exposure supplies two iteration interfaces, one which follows Chris@87: the Python iterator protocol, and another which mirrors the C-style Chris@87: do-while pattern. The native Python approach is better in most cases, but Chris@87: if you need the iterator's coordinates or index, use the C-style pattern. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: Here is how we might write an ``iter_add`` function, using the Chris@87: Python iterator protocol:: Chris@87: Chris@87: def iter_add_py(x, y, out=None): Chris@87: addop = np.add Chris@87: it = np.nditer([x, y, out], [], Chris@87: [['readonly'], ['readonly'], ['writeonly','allocate']]) Chris@87: for (a, b, c) in it: Chris@87: addop(a, b, out=c) Chris@87: return it.operands[2] Chris@87: Chris@87: Here is the same function, but following the C-style pattern:: Chris@87: Chris@87: def iter_add(x, y, out=None): Chris@87: addop = np.add Chris@87: Chris@87: it = np.nditer([x, y, out], [], Chris@87: [['readonly'], ['readonly'], ['writeonly','allocate']]) Chris@87: Chris@87: while not it.finished: Chris@87: addop(it[0], it[1], out=it[2]) Chris@87: it.iternext() Chris@87: Chris@87: return it.operands[2] Chris@87: Chris@87: Here is an example outer product function:: Chris@87: Chris@87: def outer_it(x, y, out=None): Chris@87: mulop = np.multiply Chris@87: Chris@87: it = np.nditer([x, y, out], ['external_loop'], Chris@87: [['readonly'], ['readonly'], ['writeonly', 'allocate']], Chris@87: op_axes=[range(x.ndim)+[-1]*y.ndim, Chris@87: [-1]*x.ndim+range(y.ndim), Chris@87: None]) Chris@87: Chris@87: for (a, b, c) in it: Chris@87: mulop(a, b, out=c) Chris@87: Chris@87: return it.operands[2] Chris@87: Chris@87: >>> a = np.arange(2)+1 Chris@87: >>> b = np.arange(3)+1 Chris@87: >>> outer_it(a,b) Chris@87: array([[1, 2, 3], Chris@87: [2, 4, 6]]) Chris@87: Chris@87: Here is an example function which operates like a "lambda" ufunc:: Chris@87: Chris@87: def luf(lamdaexpr, *args, **kwargs): Chris@87: "luf(lambdaexpr, op1, ..., opn, out=None, order='K', casting='safe', buffersize=0)" Chris@87: nargs = len(args) Chris@87: op = (kwargs.get('out',None),) + args Chris@87: it = np.nditer(op, ['buffered','external_loop'], Chris@87: [['writeonly','allocate','no_broadcast']] + Chris@87: [['readonly','nbo','aligned']]*nargs, Chris@87: order=kwargs.get('order','K'), Chris@87: casting=kwargs.get('casting','safe'), Chris@87: buffersize=kwargs.get('buffersize',0)) Chris@87: while not it.finished: Chris@87: it[0] = lamdaexpr(*it[1:]) Chris@87: it.iternext() Chris@87: return it.operands[0] Chris@87: Chris@87: >>> a = np.arange(5) Chris@87: >>> b = np.ones(5) Chris@87: >>> luf(lambda i,j:i*i + j/2, a, b) Chris@87: array([ 0.5, 1.5, 4.5, 9.5, 16.5]) Chris@87: Chris@87: """) Chris@87: Chris@87: # nditer methods Chris@87: Chris@87: add_newdoc('numpy.core', 'nditer', ('copy', Chris@87: """ Chris@87: copy() Chris@87: Chris@87: Get a copy of the iterator in its current state. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.arange(10) Chris@87: >>> y = x + 1 Chris@87: >>> it = np.nditer([x, y]) Chris@87: >>> it.next() Chris@87: (array(0), array(1)) Chris@87: >>> it2 = it.copy() Chris@87: >>> it2.next() Chris@87: (array(1), array(2)) Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'nditer', ('debug_print', Chris@87: """ Chris@87: debug_print() Chris@87: Chris@87: Print the current state of the `nditer` instance and debug info to stdout. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'nditer', ('enable_external_loop', Chris@87: """ Chris@87: enable_external_loop() Chris@87: Chris@87: When the "external_loop" was not used during construction, but Chris@87: is desired, this modifies the iterator to behave as if the flag Chris@87: was specified. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'nditer', ('iternext', Chris@87: """ Chris@87: iternext() Chris@87: Chris@87: Check whether iterations are left, and perform a single internal iteration Chris@87: without returning the result. Used in the C-style pattern do-while Chris@87: pattern. For an example, see `nditer`. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: iternext : bool Chris@87: Whether or not there are iterations left. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'nditer', ('remove_axis', Chris@87: """ Chris@87: remove_axis(i) Chris@87: Chris@87: Removes axis `i` from the iterator. Requires that the flag "multi_index" Chris@87: be enabled. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'nditer', ('remove_multi_index', Chris@87: """ Chris@87: remove_multi_index() Chris@87: Chris@87: When the "multi_index" flag was specified, this removes it, allowing Chris@87: the internal iteration structure to be optimized further. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'nditer', ('reset', Chris@87: """ Chris@87: reset() Chris@87: Chris@87: Reset the iterator to its initial state. Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: Chris@87: ############################################################################### Chris@87: # Chris@87: # broadcast Chris@87: # Chris@87: ############################################################################### Chris@87: Chris@87: add_newdoc('numpy.core', 'broadcast', Chris@87: """ Chris@87: Produce an object that mimics broadcasting. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: in1, in2, ... : array_like Chris@87: Input parameters. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: b : broadcast object Chris@87: Broadcast the input parameters against one another, and Chris@87: return an object that encapsulates the result. Chris@87: Amongst others, it has ``shape`` and ``nd`` properties, and Chris@87: may be used as an iterator. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: Manually adding two vectors, using broadcasting: Chris@87: Chris@87: >>> x = np.array([[1], [2], [3]]) Chris@87: >>> y = np.array([4, 5, 6]) Chris@87: >>> b = np.broadcast(x, y) Chris@87: Chris@87: >>> out = np.empty(b.shape) Chris@87: >>> out.flat = [u+v for (u,v) in b] Chris@87: >>> out Chris@87: array([[ 5., 6., 7.], Chris@87: [ 6., 7., 8.], Chris@87: [ 7., 8., 9.]]) Chris@87: Chris@87: Compare against built-in broadcasting: Chris@87: Chris@87: >>> x + y Chris@87: array([[5, 6, 7], Chris@87: [6, 7, 8], Chris@87: [7, 8, 9]]) Chris@87: Chris@87: """) Chris@87: Chris@87: # attributes Chris@87: Chris@87: add_newdoc('numpy.core', 'broadcast', ('index', Chris@87: """ Chris@87: current index in broadcasted result Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.array([[1], [2], [3]]) Chris@87: >>> y = np.array([4, 5, 6]) Chris@87: >>> b = np.broadcast(x, y) Chris@87: >>> b.index Chris@87: 0 Chris@87: >>> b.next(), b.next(), b.next() Chris@87: ((1, 4), (1, 5), (1, 6)) Chris@87: >>> b.index Chris@87: 3 Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'broadcast', ('iters', Chris@87: """ Chris@87: tuple of iterators along ``self``'s "components." Chris@87: Chris@87: Returns a tuple of `numpy.flatiter` objects, one for each "component" Chris@87: of ``self``. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.flatiter Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.array([1, 2, 3]) Chris@87: >>> y = np.array([[4], [5], [6]]) Chris@87: >>> b = np.broadcast(x, y) Chris@87: >>> row, col = b.iters Chris@87: >>> row.next(), col.next() Chris@87: (1, 4) Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'broadcast', ('nd', Chris@87: """ Chris@87: Number of dimensions of broadcasted result. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.array([1, 2, 3]) Chris@87: >>> y = np.array([[4], [5], [6]]) Chris@87: >>> b = np.broadcast(x, y) Chris@87: >>> b.nd Chris@87: 2 Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'broadcast', ('numiter', Chris@87: """ Chris@87: Number of iterators possessed by the broadcasted result. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.array([1, 2, 3]) Chris@87: >>> y = np.array([[4], [5], [6]]) Chris@87: >>> b = np.broadcast(x, y) Chris@87: >>> b.numiter Chris@87: 2 Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'broadcast', ('shape', Chris@87: """ Chris@87: Shape of broadcasted result. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.array([1, 2, 3]) Chris@87: >>> y = np.array([[4], [5], [6]]) Chris@87: >>> b = np.broadcast(x, y) Chris@87: >>> b.shape Chris@87: (3, 3) Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'broadcast', ('size', Chris@87: """ Chris@87: Total size of broadcasted result. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.array([1, 2, 3]) Chris@87: >>> y = np.array([[4], [5], [6]]) Chris@87: >>> b = np.broadcast(x, y) Chris@87: >>> b.size Chris@87: 9 Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'broadcast', ('reset', Chris@87: """ Chris@87: reset() Chris@87: Chris@87: Reset the broadcasted result's iterator(s). Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: None Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: None Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.array([1, 2, 3]) Chris@87: >>> y = np.array([[4], [5], [6]] Chris@87: >>> b = np.broadcast(x, y) Chris@87: >>> b.index Chris@87: 0 Chris@87: >>> b.next(), b.next(), b.next() Chris@87: ((1, 4), (2, 4), (3, 4)) Chris@87: >>> b.index Chris@87: 3 Chris@87: >>> b.reset() Chris@87: >>> b.index Chris@87: 0 Chris@87: Chris@87: """)) Chris@87: Chris@87: ############################################################################### Chris@87: # Chris@87: # numpy functions Chris@87: # Chris@87: ############################################################################### Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'array', Chris@87: """ Chris@87: array(object, dtype=None, copy=True, order=None, subok=False, ndmin=0) Chris@87: Chris@87: Create an array. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: object : array_like Chris@87: An array, any object exposing the array interface, an Chris@87: object whose __array__ method returns an array, or any Chris@87: (nested) sequence. Chris@87: dtype : data-type, optional Chris@87: The desired data-type for the array. If not given, then Chris@87: the type will be determined as the minimum type required Chris@87: to hold the objects in the sequence. This argument can only Chris@87: be used to 'upcast' the array. For downcasting, use the Chris@87: .astype(t) method. Chris@87: copy : bool, optional Chris@87: If true (default), then the object is copied. Otherwise, a copy Chris@87: will only be made if __array__ returns a copy, if obj is a Chris@87: nested sequence, or if a copy is needed to satisfy any of the other Chris@87: requirements (`dtype`, `order`, etc.). Chris@87: order : {'C', 'F', 'A'}, optional Chris@87: Specify the order of the array. If order is 'C' (default), then the Chris@87: array will be in C-contiguous order (last-index varies the Chris@87: fastest). If order is 'F', then the returned array Chris@87: will be in Fortran-contiguous order (first-index varies the Chris@87: fastest). If order is 'A', then the returned array may Chris@87: be in any order (either C-, Fortran-contiguous, or even Chris@87: discontiguous). Chris@87: subok : bool, optional Chris@87: If True, then sub-classes will be passed-through, otherwise Chris@87: the returned array will be forced to be a base-class array (default). Chris@87: ndmin : int, optional Chris@87: Specifies the minimum number of dimensions that the resulting Chris@87: array should have. Ones will be pre-pended to the shape as Chris@87: needed to meet this requirement. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: out : ndarray Chris@87: An array object satisfying the specified requirements. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: empty, empty_like, zeros, zeros_like, ones, ones_like, fill Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.array([1, 2, 3]) Chris@87: array([1, 2, 3]) Chris@87: Chris@87: Upcasting: Chris@87: Chris@87: >>> np.array([1, 2, 3.0]) Chris@87: array([ 1., 2., 3.]) Chris@87: Chris@87: More than one dimension: Chris@87: Chris@87: >>> np.array([[1, 2], [3, 4]]) Chris@87: array([[1, 2], Chris@87: [3, 4]]) Chris@87: Chris@87: Minimum dimensions 2: Chris@87: Chris@87: >>> np.array([1, 2, 3], ndmin=2) Chris@87: array([[1, 2, 3]]) Chris@87: Chris@87: Type provided: Chris@87: Chris@87: >>> np.array([1, 2, 3], dtype=complex) Chris@87: array([ 1.+0.j, 2.+0.j, 3.+0.j]) Chris@87: Chris@87: Data-type consisting of more than one element: Chris@87: Chris@87: >>> x = np.array([(1,2),(3,4)],dtype=[('a','>> x['a'] Chris@87: array([1, 3]) Chris@87: Chris@87: Creating an array from sub-classes: Chris@87: Chris@87: >>> np.array(np.mat('1 2; 3 4')) Chris@87: array([[1, 2], Chris@87: [3, 4]]) Chris@87: Chris@87: >>> np.array(np.mat('1 2; 3 4'), subok=True) Chris@87: matrix([[1, 2], Chris@87: [3, 4]]) Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'empty', Chris@87: """ Chris@87: empty(shape, dtype=float, order='C') Chris@87: Chris@87: Return a new array of given shape and type, without initializing entries. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: shape : int or tuple of int Chris@87: Shape of the empty array Chris@87: dtype : data-type, optional Chris@87: Desired output data-type. Chris@87: order : {'C', 'F'}, optional Chris@87: Whether to store multi-dimensional data in C (row-major) or Chris@87: Fortran (column-major) order in memory. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: out : ndarray Chris@87: Array of uninitialized (arbitrary) data with the given Chris@87: shape, dtype, and order. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: empty_like, zeros, ones Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: `empty`, unlike `zeros`, does not set the array values to zero, Chris@87: and may therefore be marginally faster. On the other hand, it requires Chris@87: the user to manually set all the values in the array, and should be Chris@87: used with caution. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.empty([2, 2]) Chris@87: array([[ -9.74499359e+001, 6.69583040e-309], Chris@87: [ 2.13182611e-314, 3.06959433e-309]]) #random Chris@87: Chris@87: >>> np.empty([2, 2], dtype=int) Chris@87: array([[-1073741821, -1067949133], Chris@87: [ 496041986, 19249760]]) #random Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'empty_like', Chris@87: """ Chris@87: empty_like(a, dtype=None, order='K', subok=True) Chris@87: Chris@87: Return a new array with the same shape and type as a given array. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: a : array_like Chris@87: The shape and data-type of `a` define these same attributes of the Chris@87: returned array. Chris@87: dtype : data-type, optional Chris@87: .. versionadded:: 1.6.0 Chris@87: Overrides the data type of the result. Chris@87: order : {'C', 'F', 'A', or 'K'}, optional Chris@87: .. versionadded:: 1.6.0 Chris@87: Overrides the memory layout of the result. 'C' means C-order, Chris@87: 'F' means F-order, 'A' means 'F' if ``a`` is Fortran contiguous, Chris@87: 'C' otherwise. 'K' means match the layout of ``a`` as closely Chris@87: as possible. Chris@87: subok : bool, optional. Chris@87: If True, then the newly created array will use the sub-class Chris@87: type of 'a', otherwise it will be a base-class array. Defaults Chris@87: to True. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: out : ndarray Chris@87: Array of uninitialized (arbitrary) data with the same Chris@87: shape and type as `a`. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: ones_like : Return an array of ones with shape and type of input. Chris@87: zeros_like : Return an array of zeros with shape and type of input. Chris@87: empty : Return a new uninitialized array. Chris@87: ones : Return a new array setting values to one. Chris@87: zeros : Return a new array setting values to zero. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: This function does *not* initialize the returned array; to do that use Chris@87: `zeros_like` or `ones_like` instead. It may be marginally faster than Chris@87: the functions that do set the array values. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> a = ([1,2,3], [4,5,6]) # a is array-like Chris@87: >>> np.empty_like(a) Chris@87: array([[-1073741821, -1073741821, 3], #random Chris@87: [ 0, 0, -1073741821]]) Chris@87: >>> a = np.array([[1., 2., 3.],[4.,5.,6.]]) Chris@87: >>> np.empty_like(a) Chris@87: array([[ -2.00000715e+000, 1.48219694e-323, -2.00000572e+000],#random Chris@87: [ 4.38791518e-305, -2.00000715e+000, 4.17269252e-309]]) Chris@87: Chris@87: """) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'scalar', Chris@87: """ Chris@87: scalar(dtype, obj) Chris@87: Chris@87: Return a new scalar array of the given type initialized with obj. Chris@87: Chris@87: This function is meant mainly for pickle support. `dtype` must be a Chris@87: valid data-type descriptor. If `dtype` corresponds to an object Chris@87: descriptor, then `obj` can be any object, otherwise `obj` must be a Chris@87: string. If `obj` is not given, it will be interpreted as None for object Chris@87: type and as zeros for all other types. Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'zeros', Chris@87: """ Chris@87: zeros(shape, dtype=float, order='C') Chris@87: Chris@87: Return a new array of given shape and type, filled with zeros. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: shape : int or sequence of ints Chris@87: Shape of the new array, e.g., ``(2, 3)`` or ``2``. Chris@87: dtype : data-type, optional Chris@87: The desired data-type for the array, e.g., `numpy.int8`. Default is Chris@87: `numpy.float64`. Chris@87: order : {'C', 'F'}, optional Chris@87: Whether to store multidimensional data in C- or Fortran-contiguous Chris@87: (row- or column-wise) order in memory. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: out : ndarray Chris@87: Array of zeros with the given shape, dtype, and order. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: zeros_like : Return an array of zeros with shape and type of input. Chris@87: ones_like : Return an array of ones with shape and type of input. Chris@87: empty_like : Return an empty array with shape and type of input. Chris@87: ones : Return a new array setting values to one. Chris@87: empty : Return a new uninitialized array. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.zeros(5) Chris@87: array([ 0., 0., 0., 0., 0.]) Chris@87: Chris@87: >>> np.zeros((5,), dtype=numpy.int) Chris@87: array([0, 0, 0, 0, 0]) Chris@87: Chris@87: >>> np.zeros((2, 1)) Chris@87: array([[ 0.], Chris@87: [ 0.]]) Chris@87: Chris@87: >>> s = (2,2) Chris@87: >>> np.zeros(s) Chris@87: array([[ 0., 0.], Chris@87: [ 0., 0.]]) Chris@87: Chris@87: >>> np.zeros((2,), dtype=[('x', 'i4'), ('y', 'i4')]) # custom dtype Chris@87: array([(0, 0), (0, 0)], Chris@87: dtype=[('x', '>> np.count_nonzero(np.eye(4)) Chris@87: 4 Chris@87: >>> np.count_nonzero([[0,1,7,0,0],[3,0,0,2,19]]) Chris@87: 5 Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'set_typeDict', Chris@87: """set_typeDict(dict) Chris@87: Chris@87: Set the internal dictionary that can look up an array type using a Chris@87: registered code. Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'fromstring', Chris@87: """ Chris@87: fromstring(string, dtype=float, count=-1, sep='') Chris@87: Chris@87: A new 1-D array initialized from raw binary or text data in a string. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: string : str Chris@87: A string containing the data. Chris@87: dtype : data-type, optional Chris@87: The data type of the array; default: float. For binary input data, Chris@87: the data must be in exactly this format. Chris@87: count : int, optional Chris@87: Read this number of `dtype` elements from the data. If this is Chris@87: negative (the default), the count will be determined from the Chris@87: length of the data. Chris@87: sep : str, optional Chris@87: If not provided or, equivalently, the empty string, the data will Chris@87: be interpreted as binary data; otherwise, as ASCII text with Chris@87: decimal numbers. Also in this latter case, this argument is Chris@87: interpreted as the string separating numbers in the data; extra Chris@87: whitespace between elements is also ignored. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: arr : ndarray Chris@87: The constructed array. Chris@87: Chris@87: Raises Chris@87: ------ Chris@87: ValueError Chris@87: If the string is not the correct size to satisfy the requested Chris@87: `dtype` and `count`. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: frombuffer, fromfile, fromiter Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.fromstring('\\x01\\x02', dtype=np.uint8) Chris@87: array([1, 2], dtype=uint8) Chris@87: >>> np.fromstring('1 2', dtype=int, sep=' ') Chris@87: array([1, 2]) Chris@87: >>> np.fromstring('1, 2', dtype=int, sep=',') Chris@87: array([1, 2]) Chris@87: >>> np.fromstring('\\x01\\x02\\x03\\x04\\x05', dtype=np.uint8, count=3) Chris@87: array([1, 2, 3], dtype=uint8) Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'fromiter', Chris@87: """ Chris@87: fromiter(iterable, dtype, count=-1) Chris@87: Chris@87: Create a new 1-dimensional array from an iterable object. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: iterable : iterable object Chris@87: An iterable object providing data for the array. Chris@87: dtype : data-type Chris@87: The data-type of the returned array. Chris@87: count : int, optional Chris@87: The number of items to read from *iterable*. The default is -1, Chris@87: which means all data is read. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: out : ndarray Chris@87: The output array. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: Specify `count` to improve performance. It allows ``fromiter`` to Chris@87: pre-allocate the output array, instead of resizing it on demand. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> iterable = (x*x for x in range(5)) Chris@87: >>> np.fromiter(iterable, np.float) Chris@87: array([ 0., 1., 4., 9., 16.]) Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'fromfile', Chris@87: """ Chris@87: fromfile(file, dtype=float, count=-1, sep='') Chris@87: Chris@87: Construct an array from data in a text or binary file. Chris@87: Chris@87: A highly efficient way of reading binary data with a known data-type, Chris@87: as well as parsing simply formatted text files. Data written using the Chris@87: `tofile` method can be read using this function. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: file : file or str Chris@87: Open file object or filename. Chris@87: dtype : data-type Chris@87: Data type of the returned array. Chris@87: For binary files, it is used to determine the size and byte-order Chris@87: of the items in the file. Chris@87: count : int Chris@87: Number of items to read. ``-1`` means all items (i.e., the complete Chris@87: file). Chris@87: sep : str Chris@87: Separator between items if file is a text file. Chris@87: Empty ("") separator means the file should be treated as binary. Chris@87: Spaces (" ") in the separator match zero or more whitespace characters. Chris@87: A separator consisting only of spaces must match at least one Chris@87: whitespace. Chris@87: Chris@87: See also Chris@87: -------- Chris@87: load, save Chris@87: ndarray.tofile Chris@87: loadtxt : More flexible way of loading data from a text file. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: Do not rely on the combination of `tofile` and `fromfile` for Chris@87: data storage, as the binary files generated are are not platform Chris@87: independent. In particular, no byte-order or data-type information is Chris@87: saved. Data can be stored in the platform independent ``.npy`` format Chris@87: using `save` and `load` instead. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: Construct an ndarray: Chris@87: Chris@87: >>> dt = np.dtype([('time', [('min', int), ('sec', int)]), Chris@87: ... ('temp', float)]) Chris@87: >>> x = np.zeros((1,), dtype=dt) Chris@87: >>> x['time']['min'] = 10; x['temp'] = 98.25 Chris@87: >>> x Chris@87: array([((10, 0), 98.25)], Chris@87: dtype=[('time', [('min', '>> import os Chris@87: >>> fname = os.tmpnam() Chris@87: >>> x.tofile(fname) Chris@87: Chris@87: Read the raw data from disk: Chris@87: Chris@87: >>> np.fromfile(fname, dtype=dt) Chris@87: array([((10, 0), 98.25)], Chris@87: dtype=[('time', [('min', '>> np.save(fname, x) Chris@87: >>> np.load(fname + '.npy') Chris@87: array([((10, 0), 98.25)], Chris@87: dtype=[('time', [('min', '>> dt = np.dtype(int) Chris@87: >>> dt = dt.newbyteorder('>') Chris@87: >>> np.frombuffer(buf, dtype=dt) Chris@87: Chris@87: The data of the resulting array will not be byteswapped, but will be Chris@87: interpreted correctly. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> s = 'hello world' Chris@87: >>> np.frombuffer(s, dtype='S1', count=5, offset=6) Chris@87: array(['w', 'o', 'r', 'l', 'd'], Chris@87: dtype='|S1') Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'concatenate', Chris@87: """ Chris@87: concatenate((a1, a2, ...), axis=0) Chris@87: Chris@87: Join a sequence of arrays together. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: a1, a2, ... : sequence of array_like Chris@87: The arrays must have the same shape, except in the dimension Chris@87: corresponding to `axis` (the first, by default). Chris@87: axis : int, optional Chris@87: The axis along which the arrays will be joined. Default is 0. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: res : ndarray Chris@87: The concatenated array. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: ma.concatenate : Concatenate function that preserves input masks. Chris@87: array_split : Split an array into multiple sub-arrays of equal or Chris@87: near-equal size. Chris@87: split : Split array into a list of multiple sub-arrays of equal size. Chris@87: hsplit : Split array into multiple sub-arrays horizontally (column wise) Chris@87: vsplit : Split array into multiple sub-arrays vertically (row wise) Chris@87: dsplit : Split array into multiple sub-arrays along the 3rd axis (depth). Chris@87: hstack : Stack arrays in sequence horizontally (column wise) Chris@87: vstack : Stack arrays in sequence vertically (row wise) Chris@87: dstack : Stack arrays in sequence depth wise (along third dimension) Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: When one or more of the arrays to be concatenated is a MaskedArray, Chris@87: this function will return a MaskedArray object instead of an ndarray, Chris@87: but the input masks are *not* preserved. In cases where a MaskedArray Chris@87: is expected as input, use the ma.concatenate function from the masked Chris@87: array module instead. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> a = np.array([[1, 2], [3, 4]]) Chris@87: >>> b = np.array([[5, 6]]) Chris@87: >>> np.concatenate((a, b), axis=0) Chris@87: array([[1, 2], Chris@87: [3, 4], Chris@87: [5, 6]]) Chris@87: >>> np.concatenate((a, b.T), axis=1) Chris@87: array([[1, 2, 5], Chris@87: [3, 4, 6]]) Chris@87: Chris@87: This function will not preserve masking of MaskedArray inputs. Chris@87: Chris@87: >>> a = np.ma.arange(3) Chris@87: >>> a[1] = np.ma.masked Chris@87: >>> b = np.arange(2, 5) Chris@87: >>> a Chris@87: masked_array(data = [0 -- 2], Chris@87: mask = [False True False], Chris@87: fill_value = 999999) Chris@87: >>> b Chris@87: array([2, 3, 4]) Chris@87: >>> np.concatenate([a, b]) Chris@87: masked_array(data = [0 1 2 2 3 4], Chris@87: mask = False, Chris@87: fill_value = 999999) Chris@87: >>> np.ma.concatenate([a, b]) Chris@87: masked_array(data = [0 -- 2 2 3 4], Chris@87: mask = [False True False False False False], Chris@87: fill_value = 999999) Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core', 'inner', Chris@87: """ Chris@87: inner(a, b) Chris@87: Chris@87: Inner product of two arrays. Chris@87: Chris@87: Ordinary inner product of vectors for 1-D arrays (without complex Chris@87: conjugation), in higher dimensions a sum product over the last axes. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: a, b : array_like Chris@87: If `a` and `b` are nonscalar, their last dimensions of must match. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: out : ndarray Chris@87: `out.shape = a.shape[:-1] + b.shape[:-1]` Chris@87: Chris@87: Raises Chris@87: ------ Chris@87: ValueError Chris@87: If the last dimension of `a` and `b` has different size. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: tensordot : Sum products over arbitrary axes. Chris@87: dot : Generalised matrix product, using second last dimension of `b`. Chris@87: einsum : Einstein summation convention. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: For vectors (1-D arrays) it computes the ordinary inner-product:: Chris@87: Chris@87: np.inner(a, b) = sum(a[:]*b[:]) Chris@87: Chris@87: More generally, if `ndim(a) = r > 0` and `ndim(b) = s > 0`:: Chris@87: Chris@87: np.inner(a, b) = np.tensordot(a, b, axes=(-1,-1)) Chris@87: Chris@87: or explicitly:: Chris@87: Chris@87: np.inner(a, b)[i0,...,ir-1,j0,...,js-1] Chris@87: = sum(a[i0,...,ir-1,:]*b[j0,...,js-1,:]) Chris@87: Chris@87: In addition `a` or `b` may be scalars, in which case:: Chris@87: Chris@87: np.inner(a,b) = a*b Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: Ordinary inner product for vectors: Chris@87: Chris@87: >>> a = np.array([1,2,3]) Chris@87: >>> b = np.array([0,1,0]) Chris@87: >>> np.inner(a, b) Chris@87: 2 Chris@87: Chris@87: A multidimensional example: Chris@87: Chris@87: >>> a = np.arange(24).reshape((2,3,4)) Chris@87: >>> b = np.arange(4) Chris@87: >>> np.inner(a, b) Chris@87: array([[ 14, 38, 62], Chris@87: [ 86, 110, 134]]) Chris@87: Chris@87: An example where `b` is a scalar: Chris@87: Chris@87: >>> np.inner(np.eye(2), 7) Chris@87: array([[ 7., 0.], Chris@87: [ 0., 7.]]) Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core', 'fastCopyAndTranspose', Chris@87: """_fastCopyAndTranspose(a)""") Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'correlate', Chris@87: """cross_correlate(a,v, mode=0)""") Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'arange', Chris@87: """ Chris@87: arange([start,] stop[, step,], dtype=None) Chris@87: Chris@87: Return evenly spaced values within a given interval. Chris@87: Chris@87: Values are generated within the half-open interval ``[start, stop)`` Chris@87: (in other words, the interval including `start` but excluding `stop`). Chris@87: For integer arguments the function is equivalent to the Python built-in Chris@87: `range `_ function, Chris@87: but returns an ndarray rather than a list. Chris@87: Chris@87: When using a non-integer step, such as 0.1, the results will often not Chris@87: be consistent. It is better to use ``linspace`` for these cases. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: start : number, optional Chris@87: Start of interval. The interval includes this value. The default Chris@87: start value is 0. Chris@87: stop : number Chris@87: End of interval. The interval does not include this value, except Chris@87: in some cases where `step` is not an integer and floating point Chris@87: round-off affects the length of `out`. Chris@87: step : number, optional Chris@87: Spacing between values. For any output `out`, this is the distance Chris@87: between two adjacent values, ``out[i+1] - out[i]``. The default Chris@87: step size is 1. If `step` is specified, `start` must also be given. Chris@87: dtype : dtype Chris@87: The type of the output array. If `dtype` is not given, infer the data Chris@87: type from the other input arguments. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: arange : ndarray Chris@87: Array of evenly spaced values. Chris@87: Chris@87: For floating point arguments, the length of the result is Chris@87: ``ceil((stop - start)/step)``. Because of floating point overflow, Chris@87: this rule may result in the last element of `out` being greater Chris@87: than `stop`. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: linspace : Evenly spaced numbers with careful handling of endpoints. Chris@87: ogrid: Arrays of evenly spaced numbers in N-dimensions. Chris@87: mgrid: Grid-shaped arrays of evenly spaced numbers in N-dimensions. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.arange(3) Chris@87: array([0, 1, 2]) Chris@87: >>> np.arange(3.0) Chris@87: array([ 0., 1., 2.]) Chris@87: >>> np.arange(3,7) Chris@87: array([3, 4, 5, 6]) Chris@87: >>> np.arange(3,7,2) Chris@87: array([3, 5]) Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', '_get_ndarray_c_version', Chris@87: """_get_ndarray_c_version() Chris@87: Chris@87: Return the compile time NDARRAY_VERSION number. Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', '_reconstruct', Chris@87: """_reconstruct(subtype, shape, dtype) Chris@87: Chris@87: Construct an empty array. Used by Pickles. Chris@87: Chris@87: """) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'set_string_function', Chris@87: """ Chris@87: set_string_function(f, repr=1) Chris@87: Chris@87: Internal method to set a function to be used when pretty printing arrays. Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'set_numeric_ops', Chris@87: """ Chris@87: set_numeric_ops(op1=func1, op2=func2, ...) Chris@87: Chris@87: Set numerical operators for array objects. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: op1, op2, ... : callable Chris@87: Each ``op = func`` pair describes an operator to be replaced. Chris@87: For example, ``add = lambda x, y: np.add(x, y) % 5`` would replace Chris@87: addition by modulus 5 addition. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: saved_ops : list of callables Chris@87: A list of all operators, stored before making replacements. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: .. WARNING:: Chris@87: Use with care! Incorrect usage may lead to memory errors. Chris@87: Chris@87: A function replacing an operator cannot make use of that operator. Chris@87: For example, when replacing add, you may not use ``+``. Instead, Chris@87: directly call ufuncs. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> def add_mod5(x, y): Chris@87: ... return np.add(x, y) % 5 Chris@87: ... Chris@87: >>> old_funcs = np.set_numeric_ops(add=add_mod5) Chris@87: Chris@87: >>> x = np.arange(12).reshape((3, 4)) Chris@87: >>> x + x Chris@87: array([[0, 2, 4, 1], Chris@87: [3, 0, 2, 4], Chris@87: [1, 3, 0, 2]]) Chris@87: Chris@87: >>> ignore = np.set_numeric_ops(**old_funcs) # restore operators Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'where', Chris@87: """ Chris@87: where(condition, [x, y]) Chris@87: Chris@87: Return elements, either from `x` or `y`, depending on `condition`. Chris@87: Chris@87: If only `condition` is given, return ``condition.nonzero()``. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: condition : array_like, bool Chris@87: When True, yield `x`, otherwise yield `y`. Chris@87: x, y : array_like, optional Chris@87: Values from which to choose. `x` and `y` need to have the same Chris@87: shape as `condition`. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: out : ndarray or tuple of ndarrays Chris@87: If both `x` and `y` are specified, the output array contains Chris@87: elements of `x` where `condition` is True, and elements from Chris@87: `y` elsewhere. Chris@87: Chris@87: If only `condition` is given, return the tuple Chris@87: ``condition.nonzero()``, the indices where `condition` is True. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: nonzero, choose Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: If `x` and `y` are given and input arrays are 1-D, `where` is Chris@87: equivalent to:: Chris@87: Chris@87: [xv if c else yv for (c,xv,yv) in zip(condition,x,y)] Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.where([[True, False], [True, True]], Chris@87: ... [[1, 2], [3, 4]], Chris@87: ... [[9, 8], [7, 6]]) Chris@87: array([[1, 8], Chris@87: [3, 4]]) Chris@87: Chris@87: >>> np.where([[0, 1], [1, 0]]) Chris@87: (array([0, 1]), array([1, 0])) Chris@87: Chris@87: >>> x = np.arange(9.).reshape(3, 3) Chris@87: >>> np.where( x > 5 ) Chris@87: (array([2, 2, 2]), array([0, 1, 2])) Chris@87: >>> x[np.where( x > 3.0 )] # Note: result is 1D. Chris@87: array([ 4., 5., 6., 7., 8.]) Chris@87: >>> np.where(x < 5, x, -1) # Note: broadcasting. Chris@87: array([[ 0., 1., 2.], Chris@87: [ 3., 4., -1.], Chris@87: [-1., -1., -1.]]) Chris@87: Chris@87: Find the indices of elements of `x` that are in `goodvalues`. Chris@87: Chris@87: >>> goodvalues = [3, 4, 7] Chris@87: >>> ix = np.in1d(x.ravel(), goodvalues).reshape(x.shape) Chris@87: >>> ix Chris@87: array([[False, False, False], Chris@87: [ True, True, False], Chris@87: [False, True, False]], dtype=bool) Chris@87: >>> np.where(ix) Chris@87: (array([1, 1, 2]), array([0, 1, 1])) Chris@87: Chris@87: """) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'lexsort', Chris@87: """ Chris@87: lexsort(keys, axis=-1) Chris@87: Chris@87: Perform an indirect sort using a sequence of keys. Chris@87: Chris@87: Given multiple sorting keys, which can be interpreted as columns in a Chris@87: spreadsheet, lexsort returns an array of integer indices that describes Chris@87: the sort order by multiple columns. The last key in the sequence is used Chris@87: for the primary sort order, the second-to-last key for the secondary sort Chris@87: order, and so on. The keys argument must be a sequence of objects that Chris@87: can be converted to arrays of the same shape. If a 2D array is provided Chris@87: for the keys argument, it's rows are interpreted as the sorting keys and Chris@87: sorting is according to the last row, second last row etc. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: keys : (k, N) array or tuple containing k (N,)-shaped sequences Chris@87: The `k` different "columns" to be sorted. The last column (or row if Chris@87: `keys` is a 2D array) is the primary sort key. Chris@87: axis : int, optional Chris@87: Axis to be indirectly sorted. By default, sort over the last axis. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: indices : (N,) ndarray of ints Chris@87: Array of indices that sort the keys along the specified axis. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: argsort : Indirect sort. Chris@87: ndarray.sort : In-place sort. Chris@87: sort : Return a sorted copy of an array. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: Sort names: first by surname, then by name. Chris@87: Chris@87: >>> surnames = ('Hertz', 'Galilei', 'Hertz') Chris@87: >>> first_names = ('Heinrich', 'Galileo', 'Gustav') Chris@87: >>> ind = np.lexsort((first_names, surnames)) Chris@87: >>> ind Chris@87: array([1, 2, 0]) Chris@87: Chris@87: >>> [surnames[i] + ", " + first_names[i] for i in ind] Chris@87: ['Galilei, Galileo', 'Hertz, Gustav', 'Hertz, Heinrich'] Chris@87: Chris@87: Sort two columns of numbers: Chris@87: Chris@87: >>> a = [1,5,1,4,3,4,4] # First column Chris@87: >>> b = [9,4,0,4,0,2,1] # Second column Chris@87: >>> ind = np.lexsort((b,a)) # Sort by a, then by b Chris@87: >>> print ind Chris@87: [2 0 4 6 5 3 1] Chris@87: Chris@87: >>> [(a[i],b[i]) for i in ind] Chris@87: [(1, 0), (1, 9), (3, 0), (4, 1), (4, 2), (4, 4), (5, 4)] Chris@87: Chris@87: Note that sorting is first according to the elements of ``a``. Chris@87: Secondary sorting is according to the elements of ``b``. Chris@87: Chris@87: A normal ``argsort`` would have yielded: Chris@87: Chris@87: >>> [(a[i],b[i]) for i in np.argsort(a)] Chris@87: [(1, 9), (1, 0), (3, 0), (4, 4), (4, 2), (4, 1), (5, 4)] Chris@87: Chris@87: Structured arrays are sorted lexically by ``argsort``: Chris@87: Chris@87: >>> x = np.array([(1,9), (5,4), (1,0), (4,4), (3,0), (4,2), (4,1)], Chris@87: ... dtype=np.dtype([('x', int), ('y', int)])) Chris@87: Chris@87: >>> np.argsort(x) # or np.argsort(x, order=('x', 'y')) Chris@87: array([2, 0, 4, 6, 5, 3, 1]) Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'can_cast', Chris@87: """ Chris@87: can_cast(from, totype, casting = 'safe') Chris@87: Chris@87: Returns True if cast between data types can occur according to the Chris@87: casting rule. If from is a scalar or array scalar, also returns Chris@87: True if the scalar value can be cast without overflow or truncation Chris@87: to an integer. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: from : dtype, dtype specifier, scalar, or array Chris@87: Data type, scalar, or array to cast from. Chris@87: totype : dtype or dtype specifier Chris@87: Data type to cast to. Chris@87: casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional Chris@87: Controls what kind of data casting may occur. Chris@87: Chris@87: * 'no' means the data types should not be cast at all. Chris@87: * 'equiv' means only byte-order changes are allowed. Chris@87: * 'safe' means only casts which can preserve values are allowed. Chris@87: * 'same_kind' means only safe casts or casts within a kind, Chris@87: like float64 to float32, are allowed. Chris@87: * 'unsafe' means any data conversions may be done. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: out : bool Chris@87: True if cast can occur according to the casting rule. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: Starting in NumPy 1.9, can_cast function now returns False in 'safe' Chris@87: casting mode for integer/float dtype and string dtype if the string dtype Chris@87: length is not long enough to store the max integer/float value converted Chris@87: to a string. Previously can_cast in 'safe' mode returned True for Chris@87: integer/float dtype and a string dtype of any length. Chris@87: Chris@87: See also Chris@87: -------- Chris@87: dtype, result_type Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: Basic examples Chris@87: Chris@87: >>> np.can_cast(np.int32, np.int64) Chris@87: True Chris@87: >>> np.can_cast(np.float64, np.complex) Chris@87: True Chris@87: >>> np.can_cast(np.complex, np.float) Chris@87: False Chris@87: Chris@87: >>> np.can_cast('i8', 'f8') Chris@87: True Chris@87: >>> np.can_cast('i8', 'f4') Chris@87: False Chris@87: >>> np.can_cast('i4', 'S4') Chris@87: False Chris@87: Chris@87: Casting scalars Chris@87: Chris@87: >>> np.can_cast(100, 'i1') Chris@87: True Chris@87: >>> np.can_cast(150, 'i1') Chris@87: False Chris@87: >>> np.can_cast(150, 'u1') Chris@87: True Chris@87: Chris@87: >>> np.can_cast(3.5e100, np.float32) Chris@87: False Chris@87: >>> np.can_cast(1000.0, np.float32) Chris@87: True Chris@87: Chris@87: Array scalar checks the value, array does not Chris@87: Chris@87: >>> np.can_cast(np.array(1000.0), np.float32) Chris@87: True Chris@87: >>> np.can_cast(np.array([1000.0]), np.float32) Chris@87: False Chris@87: Chris@87: Using the casting rules Chris@87: Chris@87: >>> np.can_cast('i8', 'i8', 'no') Chris@87: True Chris@87: >>> np.can_cast('i8', 'no') Chris@87: False Chris@87: Chris@87: >>> np.can_cast('i8', 'equiv') Chris@87: True Chris@87: >>> np.can_cast('i8', 'equiv') Chris@87: False Chris@87: Chris@87: >>> np.can_cast('i8', 'safe') Chris@87: True Chris@87: >>> np.can_cast('i4', 'safe') Chris@87: False Chris@87: Chris@87: >>> np.can_cast('i4', 'same_kind') Chris@87: True Chris@87: >>> np.can_cast('u4', 'same_kind') Chris@87: False Chris@87: Chris@87: >>> np.can_cast('u4', 'unsafe') Chris@87: True Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'promote_types', Chris@87: """ Chris@87: promote_types(type1, type2) Chris@87: Chris@87: Returns the data type with the smallest size and smallest scalar Chris@87: kind to which both ``type1`` and ``type2`` may be safely cast. Chris@87: The returned data type is always in native byte order. Chris@87: Chris@87: This function is symmetric and associative. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: type1 : dtype or dtype specifier Chris@87: First data type. Chris@87: type2 : dtype or dtype specifier Chris@87: Second data type. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: out : dtype Chris@87: The promoted data type. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: .. versionadded:: 1.6.0 Chris@87: Starting in NumPy 1.9, promote_types function now returns a valid string Chris@87: length when given an integer or float dtype as one argument and a string Chris@87: dtype as another argument. Previously it always returned the input string Chris@87: dtype, even if it wasn't long enough to store the max integer/float value Chris@87: converted to a string. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: result_type, dtype, can_cast Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.promote_types('f4', 'f8') Chris@87: dtype('float64') Chris@87: Chris@87: >>> np.promote_types('i8', 'f4') Chris@87: dtype('float64') Chris@87: Chris@87: >>> np.promote_types('>i8', '>> np.promote_types('i4', 'S8') Chris@87: dtype('S11') Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'min_scalar_type', Chris@87: """ Chris@87: min_scalar_type(a) Chris@87: Chris@87: For scalar ``a``, returns the data type with the smallest size Chris@87: and smallest scalar kind which can hold its value. For non-scalar Chris@87: array ``a``, returns the vector's dtype unmodified. Chris@87: Chris@87: Floating point values are not demoted to integers, Chris@87: and complex values are not demoted to floats. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: a : scalar or array_like Chris@87: The value whose minimal data type is to be found. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: out : dtype Chris@87: The minimal data type. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: .. versionadded:: 1.6.0 Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: result_type, promote_types, dtype, can_cast Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.min_scalar_type(10) Chris@87: dtype('uint8') Chris@87: Chris@87: >>> np.min_scalar_type(-260) Chris@87: dtype('int16') Chris@87: Chris@87: >>> np.min_scalar_type(3.1) Chris@87: dtype('float16') Chris@87: Chris@87: >>> np.min_scalar_type(1e50) Chris@87: dtype('float64') Chris@87: Chris@87: >>> np.min_scalar_type(np.arange(4,dtype='f8')) Chris@87: dtype('float64') Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'result_type', Chris@87: """ Chris@87: result_type(*arrays_and_dtypes) Chris@87: Chris@87: Returns the type that results from applying the NumPy Chris@87: type promotion rules to the arguments. Chris@87: Chris@87: Type promotion in NumPy works similarly to the rules in languages Chris@87: like C++, with some slight differences. When both scalars and Chris@87: arrays are used, the array's type takes precedence and the actual value Chris@87: of the scalar is taken into account. Chris@87: Chris@87: For example, calculating 3*a, where a is an array of 32-bit floats, Chris@87: intuitively should result in a 32-bit float output. If the 3 is a Chris@87: 32-bit integer, the NumPy rules indicate it can't convert losslessly Chris@87: into a 32-bit float, so a 64-bit float should be the result type. Chris@87: By examining the value of the constant, '3', we see that it fits in Chris@87: an 8-bit integer, which can be cast losslessly into the 32-bit float. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: arrays_and_dtypes : list of arrays and dtypes Chris@87: The operands of some operation whose result type is needed. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: out : dtype Chris@87: The result type. Chris@87: Chris@87: See also Chris@87: -------- Chris@87: dtype, promote_types, min_scalar_type, can_cast Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: .. versionadded:: 1.6.0 Chris@87: Chris@87: The specific algorithm used is as follows. Chris@87: Chris@87: Categories are determined by first checking which of boolean, Chris@87: integer (int/uint), or floating point (float/complex) the maximum Chris@87: kind of all the arrays and the scalars are. Chris@87: Chris@87: If there are only scalars or the maximum category of the scalars Chris@87: is higher than the maximum category of the arrays, Chris@87: the data types are combined with :func:`promote_types` Chris@87: to produce the return value. Chris@87: Chris@87: Otherwise, `min_scalar_type` is called on each array, and Chris@87: the resulting data types are all combined with :func:`promote_types` Chris@87: to produce the return value. Chris@87: Chris@87: The set of int values is not a subset of the uint values for types Chris@87: with the same number of bits, something not reflected in Chris@87: :func:`min_scalar_type`, but handled as a special case in `result_type`. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.result_type(3, np.arange(7, dtype='i1')) Chris@87: dtype('int8') Chris@87: Chris@87: >>> np.result_type('i4', 'c8') Chris@87: dtype('complex128') Chris@87: Chris@87: >>> np.result_type(3.0, -2) Chris@87: dtype('float64') Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'newbuffer', Chris@87: """ Chris@87: newbuffer(size) Chris@87: Chris@87: Return a new uninitialized buffer object. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: size : int Chris@87: Size in bytes of returned buffer object. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: newbuffer : buffer object Chris@87: Returned, uninitialized buffer object of `size` bytes. Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'getbuffer', Chris@87: """ Chris@87: getbuffer(obj [,offset[, size]]) Chris@87: Chris@87: Create a buffer object from the given object referencing a slice of Chris@87: length size starting at offset. Chris@87: Chris@87: Default is the entire buffer. A read-write buffer is attempted followed Chris@87: by a read-only buffer. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: obj : object Chris@87: Chris@87: offset : int, optional Chris@87: Chris@87: size : int, optional Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: buffer_obj : buffer Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> buf = np.getbuffer(np.ones(5), 1, 3) Chris@87: >>> len(buf) Chris@87: 3 Chris@87: >>> buf[0] Chris@87: '\\x00' Chris@87: >>> buf Chris@87: Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core', 'dot', Chris@87: """ Chris@87: dot(a, b, out=None) Chris@87: Chris@87: Dot product of two arrays. Chris@87: Chris@87: For 2-D arrays it is equivalent to matrix multiplication, and for 1-D Chris@87: arrays to inner product of vectors (without complex conjugation). For Chris@87: N dimensions it is a sum product over the last axis of `a` and Chris@87: the second-to-last of `b`:: Chris@87: Chris@87: dot(a, b)[i,j,k,m] = sum(a[i,j,:] * b[k,:,m]) Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: a : array_like Chris@87: First argument. Chris@87: b : array_like Chris@87: Second argument. Chris@87: out : ndarray, optional Chris@87: Output argument. This must have the exact kind that would be returned Chris@87: if it was not used. In particular, it must have the right type, must be Chris@87: C-contiguous, and its dtype must be the dtype that would be returned Chris@87: for `dot(a,b)`. This is a performance feature. Therefore, if these Chris@87: conditions are not met, an exception is raised, instead of attempting Chris@87: to be flexible. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: output : ndarray Chris@87: Returns the dot product of `a` and `b`. If `a` and `b` are both Chris@87: scalars or both 1-D arrays then a scalar is returned; otherwise Chris@87: an array is returned. Chris@87: If `out` is given, then it is returned. Chris@87: Chris@87: Raises Chris@87: ------ Chris@87: ValueError Chris@87: If the last dimension of `a` is not the same size as Chris@87: the second-to-last dimension of `b`. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: vdot : Complex-conjugating dot product. Chris@87: tensordot : Sum products over arbitrary axes. Chris@87: einsum : Einstein summation convention. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.dot(3, 4) Chris@87: 12 Chris@87: Chris@87: Neither argument is complex-conjugated: Chris@87: Chris@87: >>> np.dot([2j, 3j], [2j, 3j]) Chris@87: (-13+0j) Chris@87: Chris@87: For 2-D arrays it's the matrix product: Chris@87: Chris@87: >>> a = [[1, 0], [0, 1]] Chris@87: >>> b = [[4, 1], [2, 2]] Chris@87: >>> np.dot(a, b) Chris@87: array([[4, 1], Chris@87: [2, 2]]) Chris@87: Chris@87: >>> a = np.arange(3*4*5*6).reshape((3,4,5,6)) Chris@87: >>> b = np.arange(3*4*5*6)[::-1].reshape((5,4,6,3)) Chris@87: >>> np.dot(a, b)[2,3,2,1,2,2] Chris@87: 499128 Chris@87: >>> sum(a[2,3,2,:] * b[1,2,:,2]) Chris@87: 499128 Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core', 'einsum', Chris@87: """ Chris@87: einsum(subscripts, *operands, out=None, dtype=None, order='K', casting='safe') Chris@87: Chris@87: Evaluates the Einstein summation convention on the operands. Chris@87: Chris@87: Using the Einstein summation convention, many common multi-dimensional Chris@87: array operations can be represented in a simple fashion. This function Chris@87: provides a way compute such summations. The best way to understand this Chris@87: function is to try the examples below, which show how many common NumPy Chris@87: functions can be implemented as calls to `einsum`. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: subscripts : str Chris@87: Specifies the subscripts for summation. Chris@87: operands : list of array_like Chris@87: These are the arrays for the operation. Chris@87: out : ndarray, optional Chris@87: If provided, the calculation is done into this array. Chris@87: dtype : data-type, optional Chris@87: If provided, forces the calculation to use the data type specified. Chris@87: Note that you may have to also give a more liberal `casting` Chris@87: parameter to allow the conversions. Chris@87: order : {'C', 'F', 'A', 'K'}, optional Chris@87: Controls the memory layout of the output. 'C' means it should Chris@87: be C contiguous. 'F' means it should be Fortran contiguous, Chris@87: 'A' means it should be 'F' if the inputs are all 'F', 'C' otherwise. Chris@87: 'K' means it should be as close to the layout as the inputs as Chris@87: is possible, including arbitrarily permuted axes. Chris@87: Default is 'K'. Chris@87: casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional Chris@87: Controls what kind of data casting may occur. Setting this to Chris@87: 'unsafe' is not recommended, as it can adversely affect accumulations. Chris@87: Chris@87: * 'no' means the data types should not be cast at all. Chris@87: * 'equiv' means only byte-order changes are allowed. Chris@87: * 'safe' means only casts which can preserve values are allowed. Chris@87: * 'same_kind' means only safe casts or casts within a kind, Chris@87: like float64 to float32, are allowed. Chris@87: * 'unsafe' means any data conversions may be done. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: output : ndarray Chris@87: The calculation based on the Einstein summation convention. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: dot, inner, outer, tensordot Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: .. versionadded:: 1.6.0 Chris@87: Chris@87: The subscripts string is a comma-separated list of subscript labels, Chris@87: where each label refers to a dimension of the corresponding operand. Chris@87: Repeated subscripts labels in one operand take the diagonal. For example, Chris@87: ``np.einsum('ii', a)`` is equivalent to ``np.trace(a)``. Chris@87: Chris@87: Whenever a label is repeated, it is summed, so ``np.einsum('i,i', a, b)`` Chris@87: is equivalent to ``np.inner(a,b)``. If a label appears only once, Chris@87: it is not summed, so ``np.einsum('i', a)`` produces a view of ``a`` Chris@87: with no changes. Chris@87: Chris@87: The order of labels in the output is by default alphabetical. This Chris@87: means that ``np.einsum('ij', a)`` doesn't affect a 2D array, while Chris@87: ``np.einsum('ji', a)`` takes its transpose. Chris@87: Chris@87: The output can be controlled by specifying output subscript labels Chris@87: as well. This specifies the label order, and allows summing to Chris@87: be disallowed or forced when desired. The call ``np.einsum('i->', a)`` Chris@87: is like ``np.sum(a, axis=-1)``, and ``np.einsum('ii->i', a)`` Chris@87: is like ``np.diag(a)``. The difference is that `einsum` does not Chris@87: allow broadcasting by default. Chris@87: Chris@87: To enable and control broadcasting, use an ellipsis. Default Chris@87: NumPy-style broadcasting is done by adding an ellipsis Chris@87: to the left of each term, like ``np.einsum('...ii->...i', a)``. Chris@87: To take the trace along the first and last axes, Chris@87: you can do ``np.einsum('i...i', a)``, or to do a matrix-matrix Chris@87: product with the left-most indices instead of rightmost, you can do Chris@87: ``np.einsum('ij...,jk...->ik...', a, b)``. Chris@87: Chris@87: When there is only one operand, no axes are summed, and no output Chris@87: parameter is provided, a view into the operand is returned instead Chris@87: of a new array. Thus, taking the diagonal as ``np.einsum('ii->i', a)`` Chris@87: produces a view. Chris@87: Chris@87: An alternative way to provide the subscripts and operands is as Chris@87: ``einsum(op0, sublist0, op1, sublist1, ..., [sublistout])``. The examples Chris@87: below have corresponding `einsum` calls with the two parameter methods. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> a = np.arange(25).reshape(5,5) Chris@87: >>> b = np.arange(5) Chris@87: >>> c = np.arange(6).reshape(2,3) Chris@87: Chris@87: >>> np.einsum('ii', a) Chris@87: 60 Chris@87: >>> np.einsum(a, [0,0]) Chris@87: 60 Chris@87: >>> np.trace(a) Chris@87: 60 Chris@87: Chris@87: >>> np.einsum('ii->i', a) Chris@87: array([ 0, 6, 12, 18, 24]) Chris@87: >>> np.einsum(a, [0,0], [0]) Chris@87: array([ 0, 6, 12, 18, 24]) Chris@87: >>> np.diag(a) Chris@87: array([ 0, 6, 12, 18, 24]) Chris@87: Chris@87: >>> np.einsum('ij,j', a, b) Chris@87: array([ 30, 80, 130, 180, 230]) Chris@87: >>> np.einsum(a, [0,1], b, [1]) Chris@87: array([ 30, 80, 130, 180, 230]) Chris@87: >>> np.dot(a, b) Chris@87: array([ 30, 80, 130, 180, 230]) Chris@87: >>> np.einsum('...j,j', a, b) Chris@87: array([ 30, 80, 130, 180, 230]) Chris@87: Chris@87: >>> np.einsum('ji', c) Chris@87: array([[0, 3], Chris@87: [1, 4], Chris@87: [2, 5]]) Chris@87: >>> np.einsum(c, [1,0]) Chris@87: array([[0, 3], Chris@87: [1, 4], Chris@87: [2, 5]]) Chris@87: >>> c.T Chris@87: array([[0, 3], Chris@87: [1, 4], Chris@87: [2, 5]]) Chris@87: Chris@87: >>> np.einsum('..., ...', 3, c) Chris@87: array([[ 0, 3, 6], Chris@87: [ 9, 12, 15]]) Chris@87: >>> np.einsum(3, [Ellipsis], c, [Ellipsis]) Chris@87: array([[ 0, 3, 6], Chris@87: [ 9, 12, 15]]) Chris@87: >>> np.multiply(3, c) Chris@87: array([[ 0, 3, 6], Chris@87: [ 9, 12, 15]]) Chris@87: Chris@87: >>> np.einsum('i,i', b, b) Chris@87: 30 Chris@87: >>> np.einsum(b, [0], b, [0]) Chris@87: 30 Chris@87: >>> np.inner(b,b) Chris@87: 30 Chris@87: Chris@87: >>> np.einsum('i,j', np.arange(2)+1, b) Chris@87: array([[0, 1, 2, 3, 4], Chris@87: [0, 2, 4, 6, 8]]) Chris@87: >>> np.einsum(np.arange(2)+1, [0], b, [1]) Chris@87: array([[0, 1, 2, 3, 4], Chris@87: [0, 2, 4, 6, 8]]) Chris@87: >>> np.outer(np.arange(2)+1, b) Chris@87: array([[0, 1, 2, 3, 4], Chris@87: [0, 2, 4, 6, 8]]) Chris@87: Chris@87: >>> np.einsum('i...->...', a) Chris@87: array([50, 55, 60, 65, 70]) Chris@87: >>> np.einsum(a, [0,Ellipsis], [Ellipsis]) Chris@87: array([50, 55, 60, 65, 70]) Chris@87: >>> np.sum(a, axis=0) Chris@87: array([50, 55, 60, 65, 70]) Chris@87: Chris@87: >>> a = np.arange(60.).reshape(3,4,5) Chris@87: >>> b = np.arange(24.).reshape(4,3,2) Chris@87: >>> np.einsum('ijk,jil->kl', a, b) Chris@87: array([[ 4400., 4730.], Chris@87: [ 4532., 4874.], Chris@87: [ 4664., 5018.], Chris@87: [ 4796., 5162.], Chris@87: [ 4928., 5306.]]) Chris@87: >>> np.einsum(a, [0,1,2], b, [1,0,3], [2,3]) Chris@87: array([[ 4400., 4730.], Chris@87: [ 4532., 4874.], Chris@87: [ 4664., 5018.], Chris@87: [ 4796., 5162.], Chris@87: [ 4928., 5306.]]) Chris@87: >>> np.tensordot(a,b, axes=([1,0],[0,1])) Chris@87: array([[ 4400., 4730.], Chris@87: [ 4532., 4874.], Chris@87: [ 4664., 5018.], Chris@87: [ 4796., 5162.], Chris@87: [ 4928., 5306.]]) Chris@87: Chris@87: >>> a = np.arange(6).reshape((3,2)) Chris@87: >>> b = np.arange(12).reshape((4,3)) Chris@87: >>> np.einsum('ki,jk->ij', a, b) Chris@87: array([[10, 28, 46, 64], Chris@87: [13, 40, 67, 94]]) Chris@87: >>> np.einsum('ki,...k->i...', a, b) Chris@87: array([[10, 28, 46, 64], Chris@87: [13, 40, 67, 94]]) Chris@87: >>> np.einsum('k...,jk', a, b) Chris@87: array([[10, 28, 46, 64], Chris@87: [13, 40, 67, 94]]) Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core', 'alterdot', Chris@87: """ Chris@87: Change `dot`, `vdot`, and `inner` to use accelerated BLAS functions. Chris@87: Chris@87: Typically, as a user of Numpy, you do not explicitly call this function. If Chris@87: Numpy is built with an accelerated BLAS, this function is automatically Chris@87: called when Numpy is imported. Chris@87: Chris@87: When Numpy is built with an accelerated BLAS like ATLAS, these functions Chris@87: are replaced to make use of the faster implementations. The faster Chris@87: implementations only affect float32, float64, complex64, and complex128 Chris@87: arrays. Furthermore, the BLAS API only includes matrix-matrix, Chris@87: matrix-vector, and vector-vector products. Products of arrays with larger Chris@87: dimensionalities use the built in functions and are not accelerated. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: restoredot : `restoredot` undoes the effects of `alterdot`. Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core', 'restoredot', Chris@87: """ Chris@87: Restore `dot`, `vdot`, and `innerproduct` to the default non-BLAS Chris@87: implementations. Chris@87: Chris@87: Typically, the user will only need to call this when troubleshooting and Chris@87: installation problem, reproducing the conditions of a build without an Chris@87: accelerated BLAS, or when being very careful about benchmarking linear Chris@87: algebra operations. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: alterdot : `restoredot` undoes the effects of `alterdot`. Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core', 'vdot', Chris@87: """ Chris@87: vdot(a, b) Chris@87: Chris@87: Return the dot product of two vectors. Chris@87: Chris@87: The vdot(`a`, `b`) function handles complex numbers differently than Chris@87: dot(`a`, `b`). If the first argument is complex the complex conjugate Chris@87: of the first argument is used for the calculation of the dot product. Chris@87: Chris@87: Note that `vdot` handles multidimensional arrays differently than `dot`: Chris@87: it does *not* perform a matrix product, but flattens input arguments Chris@87: to 1-D vectors first. Consequently, it should only be used for vectors. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: a : array_like Chris@87: If `a` is complex the complex conjugate is taken before calculation Chris@87: of the dot product. Chris@87: b : array_like Chris@87: Second argument to the dot product. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: output : ndarray Chris@87: Dot product of `a` and `b`. Can be an int, float, or Chris@87: complex depending on the types of `a` and `b`. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: dot : Return the dot product without using the complex conjugate of the Chris@87: first argument. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> a = np.array([1+2j,3+4j]) Chris@87: >>> b = np.array([5+6j,7+8j]) Chris@87: >>> np.vdot(a, b) Chris@87: (70-8j) Chris@87: >>> np.vdot(b, a) Chris@87: (70+8j) Chris@87: Chris@87: Note that higher-dimensional arrays are flattened! Chris@87: Chris@87: >>> a = np.array([[1, 4], [5, 6]]) Chris@87: >>> b = np.array([[4, 1], [2, 2]]) Chris@87: >>> np.vdot(a, b) Chris@87: 30 Chris@87: >>> np.vdot(b, a) Chris@87: 30 Chris@87: >>> 1*4 + 4*1 + 5*2 + 6*2 Chris@87: 30 Chris@87: Chris@87: """) Chris@87: Chris@87: Chris@87: ############################################################################## Chris@87: # Chris@87: # Documentation for ndarray attributes and methods Chris@87: # Chris@87: ############################################################################## Chris@87: Chris@87: Chris@87: ############################################################################## Chris@87: # Chris@87: # ndarray object Chris@87: # Chris@87: ############################################################################## Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', Chris@87: """ Chris@87: ndarray(shape, dtype=float, buffer=None, offset=0, Chris@87: strides=None, order=None) Chris@87: Chris@87: An array object represents a multidimensional, homogeneous array Chris@87: of fixed-size items. An associated data-type object describes the Chris@87: format of each element in the array (its byte-order, how many bytes it Chris@87: occupies in memory, whether it is an integer, a floating point number, Chris@87: or something else, etc.) Chris@87: Chris@87: Arrays should be constructed using `array`, `zeros` or `empty` (refer Chris@87: to the See Also section below). The parameters given here refer to Chris@87: a low-level method (`ndarray(...)`) for instantiating an array. Chris@87: Chris@87: For more information, refer to the `numpy` module and examine the Chris@87: the methods and attributes of an array. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: (for the __new__ method; see Notes below) Chris@87: Chris@87: shape : tuple of ints Chris@87: Shape of created array. Chris@87: dtype : data-type, optional Chris@87: Any object that can be interpreted as a numpy data type. Chris@87: buffer : object exposing buffer interface, optional Chris@87: Used to fill the array with data. Chris@87: offset : int, optional Chris@87: Offset of array data in buffer. Chris@87: strides : tuple of ints, optional Chris@87: Strides of data in memory. Chris@87: order : {'C', 'F'}, optional Chris@87: Row-major or column-major order. Chris@87: Chris@87: Attributes Chris@87: ---------- Chris@87: T : ndarray Chris@87: Transpose of the array. Chris@87: data : buffer Chris@87: The array's elements, in memory. Chris@87: dtype : dtype object Chris@87: Describes the format of the elements in the array. Chris@87: flags : dict Chris@87: Dictionary containing information related to memory use, e.g., Chris@87: 'C_CONTIGUOUS', 'OWNDATA', 'WRITEABLE', etc. Chris@87: flat : numpy.flatiter object Chris@87: Flattened version of the array as an iterator. The iterator Chris@87: allows assignments, e.g., ``x.flat = 3`` (See `ndarray.flat` for Chris@87: assignment examples; TODO). Chris@87: imag : ndarray Chris@87: Imaginary part of the array. Chris@87: real : ndarray Chris@87: Real part of the array. Chris@87: size : int Chris@87: Number of elements in the array. Chris@87: itemsize : int Chris@87: The memory use of each array element in bytes. Chris@87: nbytes : int Chris@87: The total number of bytes required to store the array data, Chris@87: i.e., ``itemsize * size``. Chris@87: ndim : int Chris@87: The array's number of dimensions. Chris@87: shape : tuple of ints Chris@87: Shape of the array. Chris@87: strides : tuple of ints Chris@87: The step-size required to move from one element to the next in Chris@87: memory. For example, a contiguous ``(3, 4)`` array of type Chris@87: ``int16`` in C-order has strides ``(8, 2)``. This implies that Chris@87: to move from element to element in memory requires jumps of 2 bytes. Chris@87: To move from row-to-row, one needs to jump 8 bytes at a time Chris@87: (``2 * 4``). Chris@87: ctypes : ctypes object Chris@87: Class containing properties of the array needed for interaction Chris@87: with ctypes. Chris@87: base : ndarray Chris@87: If the array is a view into another array, that array is its `base` Chris@87: (unless that array is also a view). The `base` array is where the Chris@87: array data is actually stored. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: array : Construct an array. Chris@87: zeros : Create an array, each element of which is zero. Chris@87: empty : Create an array, but leave its allocated memory unchanged (i.e., Chris@87: it contains "garbage"). Chris@87: dtype : Create a data-type. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: There are two modes of creating an array using ``__new__``: Chris@87: Chris@87: 1. If `buffer` is None, then only `shape`, `dtype`, and `order` Chris@87: are used. Chris@87: 2. If `buffer` is an object exposing the buffer interface, then Chris@87: all keywords are interpreted. Chris@87: Chris@87: No ``__init__`` method is needed because the array is fully initialized Chris@87: after the ``__new__`` method. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: These examples illustrate the low-level `ndarray` constructor. Refer Chris@87: to the `See Also` section above for easier ways of constructing an Chris@87: ndarray. Chris@87: Chris@87: First mode, `buffer` is None: Chris@87: Chris@87: >>> np.ndarray(shape=(2,2), dtype=float, order='F') Chris@87: array([[ -1.13698227e+002, 4.25087011e-303], Chris@87: [ 2.88528414e-306, 3.27025015e-309]]) #random Chris@87: Chris@87: Second mode: Chris@87: Chris@87: >>> np.ndarray((2,), buffer=np.array([1,2,3]), Chris@87: ... offset=np.int_().itemsize, Chris@87: ... dtype=int) # offset = 1*itemsize, i.e. skip first element Chris@87: array([2, 3]) Chris@87: Chris@87: """) Chris@87: Chris@87: Chris@87: ############################################################################## Chris@87: # Chris@87: # ndarray attributes Chris@87: # Chris@87: ############################################################################## Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('__array_interface__', Chris@87: """Array protocol: Python side.""")) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('__array_finalize__', Chris@87: """None.""")) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('__array_priority__', Chris@87: """Array priority.""")) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('__array_struct__', Chris@87: """Array protocol: C-struct side.""")) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('_as_parameter_', Chris@87: """Allow the array to be interpreted as a ctypes object by returning the Chris@87: data-memory location as an integer Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('base', Chris@87: """ Chris@87: Base object if memory is from some other object. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: The base of an array that owns its memory is None: Chris@87: Chris@87: >>> x = np.array([1,2,3,4]) Chris@87: >>> x.base is None Chris@87: True Chris@87: Chris@87: Slicing creates a view, whose memory is shared with x: Chris@87: Chris@87: >>> y = x[2:] Chris@87: >>> y.base is x Chris@87: True Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('ctypes', Chris@87: """ Chris@87: An object to simplify the interaction of the array with the ctypes Chris@87: module. Chris@87: Chris@87: This attribute creates an object that makes it easier to use arrays Chris@87: when calling shared libraries with the ctypes module. The returned Chris@87: object has, among others, data, shape, and strides attributes (see Chris@87: Notes below) which themselves return ctypes objects that can be used Chris@87: as arguments to a shared library. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: None Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: c : Python object Chris@87: Possessing attributes data, shape, strides, etc. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.ctypeslib Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: Below are the public attributes of this object which were documented Chris@87: in "Guide to NumPy" (we have omitted undocumented public attributes, Chris@87: as well as documented private attributes): Chris@87: Chris@87: * data: A pointer to the memory area of the array as a Python integer. Chris@87: This memory area may contain data that is not aligned, or not in correct Chris@87: byte-order. The memory area may not even be writeable. The array Chris@87: flags and data-type of this array should be respected when passing this Chris@87: attribute to arbitrary C-code to avoid trouble that can include Python Chris@87: crashing. User Beware! The value of this attribute is exactly the same Chris@87: as self._array_interface_['data'][0]. Chris@87: Chris@87: * shape (c_intp*self.ndim): A ctypes array of length self.ndim where Chris@87: the basetype is the C-integer corresponding to dtype('p') on this Chris@87: platform. This base-type could be c_int, c_long, or c_longlong Chris@87: depending on the platform. The c_intp type is defined accordingly in Chris@87: numpy.ctypeslib. The ctypes array contains the shape of the underlying Chris@87: array. Chris@87: Chris@87: * strides (c_intp*self.ndim): A ctypes array of length self.ndim where Chris@87: the basetype is the same as for the shape attribute. This ctypes array Chris@87: contains the strides information from the underlying array. This strides Chris@87: information is important for showing how many bytes must be jumped to Chris@87: get to the next element in the array. Chris@87: Chris@87: * data_as(obj): Return the data pointer cast to a particular c-types object. Chris@87: For example, calling self._as_parameter_ is equivalent to Chris@87: self.data_as(ctypes.c_void_p). Perhaps you want to use the data as a Chris@87: pointer to a ctypes array of floating-point data: Chris@87: self.data_as(ctypes.POINTER(ctypes.c_double)). Chris@87: Chris@87: * shape_as(obj): Return the shape tuple as an array of some other c-types Chris@87: type. For example: self.shape_as(ctypes.c_short). Chris@87: Chris@87: * strides_as(obj): Return the strides tuple as an array of some other Chris@87: c-types type. For example: self.strides_as(ctypes.c_longlong). Chris@87: Chris@87: Be careful using the ctypes attribute - especially on temporary Chris@87: arrays or arrays constructed on the fly. For example, calling Chris@87: ``(a+b).ctypes.data_as(ctypes.c_void_p)`` returns a pointer to memory Chris@87: that is invalid because the array created as (a+b) is deallocated Chris@87: before the next Python statement. You can avoid this problem using Chris@87: either ``c=a+b`` or ``ct=(a+b).ctypes``. In the latter case, ct will Chris@87: hold a reference to the array until ct is deleted or re-assigned. Chris@87: Chris@87: If the ctypes module is not available, then the ctypes attribute Chris@87: of array objects still returns something useful, but ctypes objects Chris@87: are not returned and errors may be raised instead. In particular, Chris@87: the object will still have the as parameter attribute which will Chris@87: return an integer equal to the data attribute. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> import ctypes Chris@87: >>> x Chris@87: array([[0, 1], Chris@87: [2, 3]]) Chris@87: >>> x.ctypes.data Chris@87: 30439712 Chris@87: >>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long)) Chris@87: Chris@87: >>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_long)).contents Chris@87: c_long(0) Chris@87: >>> x.ctypes.data_as(ctypes.POINTER(ctypes.c_longlong)).contents Chris@87: c_longlong(4294967296L) Chris@87: >>> x.ctypes.shape Chris@87: Chris@87: >>> x.ctypes.shape_as(ctypes.c_long) Chris@87: Chris@87: >>> x.ctypes.strides Chris@87: Chris@87: >>> x.ctypes.strides_as(ctypes.c_longlong) Chris@87: Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('data', Chris@87: """Python buffer object pointing to the start of the array's data.""")) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('dtype', Chris@87: """ Chris@87: Data-type of the array's elements. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: None Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: d : numpy dtype object Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.dtype Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x Chris@87: array([[0, 1], Chris@87: [2, 3]]) Chris@87: >>> x.dtype Chris@87: dtype('int32') Chris@87: >>> type(x.dtype) Chris@87: Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('imag', Chris@87: """ Chris@87: The imaginary part of the array. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.sqrt([1+0j, 0+1j]) Chris@87: >>> x.imag Chris@87: array([ 0. , 0.70710678]) Chris@87: >>> x.imag.dtype Chris@87: dtype('float64') Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('itemsize', Chris@87: """ Chris@87: Length of one array element in bytes. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.array([1,2,3], dtype=np.float64) Chris@87: >>> x.itemsize Chris@87: 8 Chris@87: >>> x = np.array([1,2,3], dtype=np.complex128) Chris@87: >>> x.itemsize Chris@87: 16 Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('flags', Chris@87: """ Chris@87: Information about the memory layout of the array. Chris@87: Chris@87: Attributes Chris@87: ---------- Chris@87: C_CONTIGUOUS (C) Chris@87: The data is in a single, C-style contiguous segment. Chris@87: F_CONTIGUOUS (F) Chris@87: The data is in a single, Fortran-style contiguous segment. Chris@87: OWNDATA (O) Chris@87: The array owns the memory it uses or borrows it from another object. Chris@87: WRITEABLE (W) Chris@87: The data area can be written to. Setting this to False locks Chris@87: the data, making it read-only. A view (slice, etc.) inherits WRITEABLE Chris@87: from its base array at creation time, but a view of a writeable Chris@87: array may be subsequently locked while the base array remains writeable. Chris@87: (The opposite is not true, in that a view of a locked array may not Chris@87: be made writeable. However, currently, locking a base object does not Chris@87: lock any views that already reference it, so under that circumstance it Chris@87: is possible to alter the contents of a locked array via a previously Chris@87: created writeable view onto it.) Attempting to change a non-writeable Chris@87: array raises a RuntimeError exception. Chris@87: ALIGNED (A) Chris@87: The data and all elements are aligned appropriately for the hardware. Chris@87: UPDATEIFCOPY (U) Chris@87: This array is a copy of some other array. When this array is Chris@87: deallocated, the base array will be updated with the contents of Chris@87: this array. Chris@87: FNC Chris@87: F_CONTIGUOUS and not C_CONTIGUOUS. Chris@87: FORC Chris@87: F_CONTIGUOUS or C_CONTIGUOUS (one-segment test). Chris@87: BEHAVED (B) Chris@87: ALIGNED and WRITEABLE. Chris@87: CARRAY (CA) Chris@87: BEHAVED and C_CONTIGUOUS. Chris@87: FARRAY (FA) Chris@87: BEHAVED and F_CONTIGUOUS and not C_CONTIGUOUS. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: The `flags` object can be accessed dictionary-like (as in ``a.flags['WRITEABLE']``), Chris@87: or by using lowercased attribute names (as in ``a.flags.writeable``). Short flag Chris@87: names are only supported in dictionary access. Chris@87: Chris@87: Only the UPDATEIFCOPY, WRITEABLE, and ALIGNED flags can be changed by Chris@87: the user, via direct assignment to the attribute or dictionary entry, Chris@87: or by calling `ndarray.setflags`. Chris@87: Chris@87: The array flags cannot be set arbitrarily: Chris@87: Chris@87: - UPDATEIFCOPY can only be set ``False``. Chris@87: - ALIGNED can only be set ``True`` if the data is truly aligned. Chris@87: - WRITEABLE can only be set ``True`` if the array owns its own memory Chris@87: or the ultimate owner of the memory exposes a writeable buffer Chris@87: interface or is a string. Chris@87: Chris@87: Arrays can be both C-style and Fortran-style contiguous simultaneously. Chris@87: This is clear for 1-dimensional arrays, but can also be true for higher Chris@87: dimensional arrays. Chris@87: Chris@87: Even for contiguous arrays a stride for a given dimension Chris@87: ``arr.strides[dim]`` may be *arbitrary* if ``arr.shape[dim] == 1`` Chris@87: or the array has no elements. Chris@87: It does *not* generally hold that ``self.strides[-1] == self.itemsize`` Chris@87: for C-style contiguous arrays or ``self.strides[0] == self.itemsize`` for Chris@87: Fortran-style contiguous arrays is true. Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('flat', Chris@87: """ Chris@87: A 1-D iterator over the array. Chris@87: Chris@87: This is a `numpy.flatiter` instance, which acts similarly to, but is not Chris@87: a subclass of, Python's built-in iterator object. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: flatten : Return a copy of the array collapsed into one dimension. Chris@87: Chris@87: flatiter Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.arange(1, 7).reshape(2, 3) Chris@87: >>> x Chris@87: array([[1, 2, 3], Chris@87: [4, 5, 6]]) Chris@87: >>> x.flat[3] Chris@87: 4 Chris@87: >>> x.T Chris@87: array([[1, 4], Chris@87: [2, 5], Chris@87: [3, 6]]) Chris@87: >>> x.T.flat[3] Chris@87: 5 Chris@87: >>> type(x.flat) Chris@87: Chris@87: Chris@87: An assignment example: Chris@87: Chris@87: >>> x.flat = 3; x Chris@87: array([[3, 3, 3], Chris@87: [3, 3, 3]]) Chris@87: >>> x.flat[[1,4]] = 1; x Chris@87: array([[3, 1, 3], Chris@87: [3, 1, 3]]) Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('nbytes', Chris@87: """ Chris@87: Total bytes consumed by the elements of the array. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: Does not include memory consumed by non-element attributes of the Chris@87: array object. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.zeros((3,5,2), dtype=np.complex128) Chris@87: >>> x.nbytes Chris@87: 480 Chris@87: >>> np.prod(x.shape) * x.itemsize Chris@87: 480 Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('ndim', Chris@87: """ Chris@87: Number of array dimensions. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.array([1, 2, 3]) Chris@87: >>> x.ndim Chris@87: 1 Chris@87: >>> y = np.zeros((2, 3, 4)) Chris@87: >>> y.ndim Chris@87: 3 Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('real', Chris@87: """ Chris@87: The real part of the array. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.sqrt([1+0j, 0+1j]) Chris@87: >>> x.real Chris@87: array([ 1. , 0.70710678]) Chris@87: >>> x.real.dtype Chris@87: dtype('float64') Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.real : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('shape', Chris@87: """ Chris@87: Tuple of array dimensions. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: May be used to "reshape" the array, as long as this would not Chris@87: require a change in the total number of elements Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.array([1, 2, 3, 4]) Chris@87: >>> x.shape Chris@87: (4,) Chris@87: >>> y = np.zeros((2, 3, 4)) Chris@87: >>> y.shape Chris@87: (2, 3, 4) Chris@87: >>> y.shape = (3, 8) Chris@87: >>> y Chris@87: array([[ 0., 0., 0., 0., 0., 0., 0., 0.], Chris@87: [ 0., 0., 0., 0., 0., 0., 0., 0.], Chris@87: [ 0., 0., 0., 0., 0., 0., 0., 0.]]) Chris@87: >>> y.shape = (3, 6) Chris@87: Traceback (most recent call last): Chris@87: File "", line 1, in Chris@87: ValueError: total size of new array must be unchanged Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('size', Chris@87: """ Chris@87: Number of elements in the array. Chris@87: Chris@87: Equivalent to ``np.prod(a.shape)``, i.e., the product of the array's Chris@87: dimensions. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.zeros((3, 5, 2), dtype=np.complex128) Chris@87: >>> x.size Chris@87: 30 Chris@87: >>> np.prod(x.shape) Chris@87: 30 Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('strides', Chris@87: """ Chris@87: Tuple of bytes to step in each dimension when traversing an array. Chris@87: Chris@87: The byte offset of element ``(i[0], i[1], ..., i[n])`` in an array `a` Chris@87: is:: Chris@87: Chris@87: offset = sum(np.array(i) * a.strides) Chris@87: Chris@87: A more detailed explanation of strides can be found in the Chris@87: "ndarray.rst" file in the NumPy reference guide. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: Imagine an array of 32-bit integers (each 4 bytes):: Chris@87: Chris@87: x = np.array([[0, 1, 2, 3, 4], Chris@87: [5, 6, 7, 8, 9]], dtype=np.int32) Chris@87: Chris@87: This array is stored in memory as 40 bytes, one after the other Chris@87: (known as a contiguous block of memory). The strides of an array tell Chris@87: us how many bytes we have to skip in memory to move to the next position Chris@87: along a certain axis. For example, we have to skip 4 bytes (1 value) to Chris@87: move to the next column, but 20 bytes (5 values) to get to the same Chris@87: position in the next row. As such, the strides for the array `x` will be Chris@87: ``(20, 4)``. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.lib.stride_tricks.as_strided Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> y = np.reshape(np.arange(2*3*4), (2,3,4)) Chris@87: >>> y Chris@87: array([[[ 0, 1, 2, 3], Chris@87: [ 4, 5, 6, 7], Chris@87: [ 8, 9, 10, 11]], Chris@87: [[12, 13, 14, 15], Chris@87: [16, 17, 18, 19], Chris@87: [20, 21, 22, 23]]]) Chris@87: >>> y.strides Chris@87: (48, 16, 4) Chris@87: >>> y[1,1,1] Chris@87: 17 Chris@87: >>> offset=sum(y.strides * np.array((1,1,1))) Chris@87: >>> offset/y.itemsize Chris@87: 17 Chris@87: Chris@87: >>> x = np.reshape(np.arange(5*6*7*8), (5,6,7,8)).transpose(2,3,1,0) Chris@87: >>> x.strides Chris@87: (32, 4, 224, 1344) Chris@87: >>> i = np.array([3,5,2,2]) Chris@87: >>> offset = sum(i * x.strides) Chris@87: >>> x[3,5,2,2] Chris@87: 813 Chris@87: >>> offset / x.itemsize Chris@87: 813 Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('T', Chris@87: """ Chris@87: Same as self.transpose(), except that self is returned if Chris@87: self.ndim < 2. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.array([[1.,2.],[3.,4.]]) Chris@87: >>> x Chris@87: array([[ 1., 2.], Chris@87: [ 3., 4.]]) Chris@87: >>> x.T Chris@87: array([[ 1., 3.], Chris@87: [ 2., 4.]]) Chris@87: >>> x = np.array([1.,2.,3.,4.]) Chris@87: >>> x Chris@87: array([ 1., 2., 3., 4.]) Chris@87: >>> x.T Chris@87: array([ 1., 2., 3., 4.]) Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: ############################################################################## Chris@87: # Chris@87: # ndarray methods Chris@87: # Chris@87: ############################################################################## Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('__array__', Chris@87: """ a.__array__(|dtype) -> reference if type unchanged, copy otherwise. Chris@87: Chris@87: Returns either a new reference to self if dtype is not given or a new array Chris@87: of provided data type if dtype is different from the current dtype of the Chris@87: array. Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('__array_prepare__', Chris@87: """a.__array_prepare__(obj) -> Object of same type as ndarray object obj. Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('__array_wrap__', Chris@87: """a.__array_wrap__(obj) -> Object of same type as ndarray object a. Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('__copy__', Chris@87: """a.__copy__([order]) Chris@87: Chris@87: Return a copy of the array. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: order : {'C', 'F', 'A'}, optional Chris@87: If order is 'C' (False) then the result is contiguous (default). Chris@87: If order is 'Fortran' (True) then the result has fortran order. Chris@87: If order is 'Any' (None) then the result has fortran order Chris@87: only if the array already is in fortran order. Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('__deepcopy__', Chris@87: """a.__deepcopy__() -> Deep copy of array. Chris@87: Chris@87: Used if copy.deepcopy is called on an array. Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('__reduce__', Chris@87: """a.__reduce__() Chris@87: Chris@87: For pickling. Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('__setstate__', Chris@87: """a.__setstate__(version, shape, dtype, isfortran, rawdata) Chris@87: Chris@87: For unpickling. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: version : int Chris@87: optional pickle version. If omitted defaults to 0. Chris@87: shape : tuple Chris@87: dtype : data-type Chris@87: isFortran : bool Chris@87: rawdata : string or list Chris@87: a binary string with the data (or a list if 'a' is an object array) Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('all', Chris@87: """ Chris@87: a.all(axis=None, out=None) Chris@87: Chris@87: Returns True if all elements evaluate to True. Chris@87: Chris@87: Refer to `numpy.all` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.all : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('any', Chris@87: """ Chris@87: a.any(axis=None, out=None) Chris@87: Chris@87: Returns True if any of the elements of `a` evaluate to True. Chris@87: Chris@87: Refer to `numpy.any` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.any : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('argmax', Chris@87: """ Chris@87: a.argmax(axis=None, out=None) Chris@87: Chris@87: Return indices of the maximum values along the given axis. Chris@87: Chris@87: Refer to `numpy.argmax` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.argmax : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('argmin', Chris@87: """ Chris@87: a.argmin(axis=None, out=None) Chris@87: Chris@87: Return indices of the minimum values along the given axis of `a`. Chris@87: Chris@87: Refer to `numpy.argmin` for detailed documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.argmin : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('argsort', Chris@87: """ Chris@87: a.argsort(axis=-1, kind='quicksort', order=None) Chris@87: Chris@87: Returns the indices that would sort this array. Chris@87: Chris@87: Refer to `numpy.argsort` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.argsort : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('argpartition', Chris@87: """ Chris@87: a.argpartition(kth, axis=-1, kind='introselect', order=None) Chris@87: Chris@87: Returns the indices that would partition this array. Chris@87: Chris@87: Refer to `numpy.argpartition` for full documentation. Chris@87: Chris@87: .. versionadded:: 1.8.0 Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.argpartition : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('astype', Chris@87: """ Chris@87: a.astype(dtype, order='K', casting='unsafe', subok=True, copy=True) Chris@87: Chris@87: Copy of the array, cast to a specified type. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: dtype : str or dtype Chris@87: Typecode or data-type to which the array is cast. Chris@87: order : {'C', 'F', 'A', 'K'}, optional Chris@87: Controls the memory layout order of the result. Chris@87: 'C' means C order, 'F' means Fortran order, 'A' Chris@87: means 'F' order if all the arrays are Fortran contiguous, Chris@87: 'C' order otherwise, and 'K' means as close to the Chris@87: order the array elements appear in memory as possible. Chris@87: Default is 'K'. Chris@87: casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional Chris@87: Controls what kind of data casting may occur. Defaults to 'unsafe' Chris@87: for backwards compatibility. Chris@87: Chris@87: * 'no' means the data types should not be cast at all. Chris@87: * 'equiv' means only byte-order changes are allowed. Chris@87: * 'safe' means only casts which can preserve values are allowed. Chris@87: * 'same_kind' means only safe casts or casts within a kind, Chris@87: like float64 to float32, are allowed. Chris@87: * 'unsafe' means any data conversions may be done. Chris@87: subok : bool, optional Chris@87: If True, then sub-classes will be passed-through (default), otherwise Chris@87: the returned array will be forced to be a base-class array. Chris@87: copy : bool, optional Chris@87: By default, astype always returns a newly allocated array. If this Chris@87: is set to false, and the `dtype`, `order`, and `subok` Chris@87: requirements are satisfied, the input array is returned instead Chris@87: of a copy. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: arr_t : ndarray Chris@87: Unless `copy` is False and the other conditions for returning the input Chris@87: array are satisfied (see description for `copy` input paramter), `arr_t` Chris@87: is a new array of the same shape as the input array, with dtype, order Chris@87: given by `dtype`, `order`. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: Starting in NumPy 1.9, astype method now returns an error if the string Chris@87: dtype to cast to is not long enough in 'safe' casting mode to hold the max Chris@87: value of integer/float array that is being casted. Previously the casting Chris@87: was allowed even if the result was truncated. Chris@87: Chris@87: Raises Chris@87: ------ Chris@87: ComplexWarning Chris@87: When casting from complex to float or int. To avoid this, Chris@87: one should use ``a.real.astype(t)``. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.array([1, 2, 2.5]) Chris@87: >>> x Chris@87: array([ 1. , 2. , 2.5]) Chris@87: Chris@87: >>> x.astype(int) Chris@87: array([1, 2, 2]) Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('byteswap', Chris@87: """ Chris@87: a.byteswap(inplace) Chris@87: Chris@87: Swap the bytes of the array elements Chris@87: Chris@87: Toggle between low-endian and big-endian data representation by Chris@87: returning a byteswapped array, optionally swapped in-place. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: inplace : bool, optional Chris@87: If ``True``, swap bytes in-place, default is ``False``. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: out : ndarray Chris@87: The byteswapped array. If `inplace` is ``True``, this is Chris@87: a view to self. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> A = np.array([1, 256, 8755], dtype=np.int16) Chris@87: >>> map(hex, A) Chris@87: ['0x1', '0x100', '0x2233'] Chris@87: >>> A.byteswap(True) Chris@87: array([ 256, 1, 13090], dtype=int16) Chris@87: >>> map(hex, A) Chris@87: ['0x100', '0x1', '0x3322'] Chris@87: Chris@87: Arrays of strings are not swapped Chris@87: Chris@87: >>> A = np.array(['ceg', 'fac']) Chris@87: >>> A.byteswap() Chris@87: array(['ceg', 'fac'], Chris@87: dtype='|S3') Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('choose', Chris@87: """ Chris@87: a.choose(choices, out=None, mode='raise') Chris@87: Chris@87: Use an index array to construct a new array from a set of choices. Chris@87: Chris@87: Refer to `numpy.choose` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.choose : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('clip', Chris@87: """ Chris@87: a.clip(a_min, a_max, out=None) Chris@87: Chris@87: Return an array whose values are limited to ``[a_min, a_max]``. Chris@87: Chris@87: Refer to `numpy.clip` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.clip : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('compress', Chris@87: """ Chris@87: a.compress(condition, axis=None, out=None) Chris@87: Chris@87: Return selected slices of this array along given axis. Chris@87: Chris@87: Refer to `numpy.compress` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.compress : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('conj', Chris@87: """ Chris@87: a.conj() Chris@87: Chris@87: Complex-conjugate all elements. Chris@87: Chris@87: Refer to `numpy.conjugate` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.conjugate : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('conjugate', Chris@87: """ Chris@87: a.conjugate() Chris@87: Chris@87: Return the complex conjugate, element-wise. Chris@87: Chris@87: Refer to `numpy.conjugate` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.conjugate : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('copy', Chris@87: """ Chris@87: a.copy(order='C') Chris@87: Chris@87: Return a copy of the array. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: order : {'C', 'F', 'A', 'K'}, optional Chris@87: Controls the memory layout of the copy. 'C' means C-order, Chris@87: 'F' means F-order, 'A' means 'F' if `a` is Fortran contiguous, Chris@87: 'C' otherwise. 'K' means match the layout of `a` as closely Chris@87: as possible. (Note that this function and :func:numpy.copy are very Chris@87: similar, but have different default values for their order= Chris@87: arguments.) Chris@87: Chris@87: See also Chris@87: -------- Chris@87: numpy.copy Chris@87: numpy.copyto Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.array([[1,2,3],[4,5,6]], order='F') Chris@87: Chris@87: >>> y = x.copy() Chris@87: Chris@87: >>> x.fill(0) Chris@87: Chris@87: >>> x Chris@87: array([[0, 0, 0], Chris@87: [0, 0, 0]]) Chris@87: Chris@87: >>> y Chris@87: array([[1, 2, 3], Chris@87: [4, 5, 6]]) Chris@87: Chris@87: >>> y.flags['C_CONTIGUOUS'] Chris@87: True Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('cumprod', Chris@87: """ Chris@87: a.cumprod(axis=None, dtype=None, out=None) Chris@87: Chris@87: Return the cumulative product of the elements along the given axis. Chris@87: Chris@87: Refer to `numpy.cumprod` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.cumprod : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('cumsum', Chris@87: """ Chris@87: a.cumsum(axis=None, dtype=None, out=None) Chris@87: Chris@87: Return the cumulative sum of the elements along the given axis. Chris@87: Chris@87: Refer to `numpy.cumsum` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.cumsum : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('diagonal', Chris@87: """ Chris@87: a.diagonal(offset=0, axis1=0, axis2=1) Chris@87: Chris@87: Return specified diagonals. In NumPy 1.9 the returned array is a Chris@87: read-only view instead of a copy as in previous NumPy versions. In Chris@87: NumPy 1.10 the read-only restriction will be removed. Chris@87: Chris@87: Refer to :func:`numpy.diagonal` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.diagonal : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('dot', Chris@87: """ Chris@87: a.dot(b, out=None) Chris@87: Chris@87: Dot product of two arrays. Chris@87: Chris@87: Refer to `numpy.dot` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.dot : equivalent function Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> a = np.eye(2) Chris@87: >>> b = np.ones((2, 2)) * 2 Chris@87: >>> a.dot(b) Chris@87: array([[ 2., 2.], Chris@87: [ 2., 2.]]) Chris@87: Chris@87: This array method can be conveniently chained: Chris@87: Chris@87: >>> a.dot(b).dot(b) Chris@87: array([[ 8., 8.], Chris@87: [ 8., 8.]]) Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('dump', Chris@87: """a.dump(file) Chris@87: Chris@87: Dump a pickle of the array to the specified file. Chris@87: The array can be read back with pickle.load or numpy.load. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: file : str Chris@87: A string naming the dump file. Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('dumps', Chris@87: """ Chris@87: a.dumps() Chris@87: Chris@87: Returns the pickle of the array as a string. Chris@87: pickle.loads or numpy.loads will convert the string back to an array. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: None Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('fill', Chris@87: """ Chris@87: a.fill(value) Chris@87: Chris@87: Fill the array with a scalar value. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: value : scalar Chris@87: All elements of `a` will be assigned this value. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> a = np.array([1, 2]) Chris@87: >>> a.fill(0) Chris@87: >>> a Chris@87: array([0, 0]) Chris@87: >>> a = np.empty(2) Chris@87: >>> a.fill(1) Chris@87: >>> a Chris@87: array([ 1., 1.]) Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('flatten', Chris@87: """ Chris@87: a.flatten(order='C') Chris@87: Chris@87: Return a copy of the array collapsed into one dimension. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: order : {'C', 'F', 'A'}, optional Chris@87: Whether to flatten in C (row-major), Fortran (column-major) order, Chris@87: or preserve the C/Fortran ordering from `a`. Chris@87: The default is 'C'. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: y : ndarray Chris@87: A copy of the input array, flattened to one dimension. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: ravel : Return a flattened array. Chris@87: flat : A 1-D flat iterator over the array. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> a = np.array([[1,2], [3,4]]) Chris@87: >>> a.flatten() Chris@87: array([1, 2, 3, 4]) Chris@87: >>> a.flatten('F') Chris@87: array([1, 3, 2, 4]) Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('getfield', Chris@87: """ Chris@87: a.getfield(dtype, offset=0) Chris@87: Chris@87: Returns a field of the given array as a certain type. Chris@87: Chris@87: A field is a view of the array data with a given data-type. The values in Chris@87: the view are determined by the given type and the offset into the current Chris@87: array in bytes. The offset needs to be such that the view dtype fits in the Chris@87: array dtype; for example an array of dtype complex128 has 16-byte elements. Chris@87: If taking a view with a 32-bit integer (4 bytes), the offset needs to be Chris@87: between 0 and 12 bytes. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: dtype : str or dtype Chris@87: The data type of the view. The dtype size of the view can not be larger Chris@87: than that of the array itself. Chris@87: offset : int Chris@87: Number of bytes to skip before beginning the element view. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.diag([1.+1.j]*2) Chris@87: >>> x[1, 1] = 2 + 4.j Chris@87: >>> x Chris@87: array([[ 1.+1.j, 0.+0.j], Chris@87: [ 0.+0.j, 2.+4.j]]) Chris@87: >>> x.getfield(np.float64) Chris@87: array([[ 1., 0.], Chris@87: [ 0., 2.]]) Chris@87: Chris@87: By choosing an offset of 8 bytes we can select the complex part of the Chris@87: array for our view: Chris@87: Chris@87: >>> x.getfield(np.float64, offset=8) Chris@87: array([[ 1., 0.], Chris@87: [ 0., 4.]]) Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('item', Chris@87: """ Chris@87: a.item(*args) Chris@87: Chris@87: Copy an element of an array to a standard Python scalar and return it. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: \\*args : Arguments (variable number and type) Chris@87: Chris@87: * none: in this case, the method only works for arrays Chris@87: with one element (`a.size == 1`), which element is Chris@87: copied into a standard Python scalar object and returned. Chris@87: Chris@87: * int_type: this argument is interpreted as a flat index into Chris@87: the array, specifying which element to copy and return. Chris@87: Chris@87: * tuple of int_types: functions as does a single int_type argument, Chris@87: except that the argument is interpreted as an nd-index into the Chris@87: array. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: z : Standard Python scalar object Chris@87: A copy of the specified element of the array as a suitable Chris@87: Python scalar Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: When the data type of `a` is longdouble or clongdouble, item() returns Chris@87: a scalar array object because there is no available Python scalar that Chris@87: would not lose information. Void arrays return a buffer object for item(), Chris@87: unless fields are defined, in which case a tuple is returned. Chris@87: Chris@87: `item` is very similar to a[args], except, instead of an array scalar, Chris@87: a standard Python scalar is returned. This can be useful for speeding up Chris@87: access to elements of the array and doing arithmetic on elements of the Chris@87: array using Python's optimized math. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.random.randint(9, size=(3, 3)) Chris@87: >>> x Chris@87: array([[3, 1, 7], Chris@87: [2, 8, 3], Chris@87: [8, 5, 3]]) Chris@87: >>> x.item(3) Chris@87: 2 Chris@87: >>> x.item(7) Chris@87: 5 Chris@87: >>> x.item((0, 1)) Chris@87: 1 Chris@87: >>> x.item((2, 2)) Chris@87: 3 Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('itemset', Chris@87: """ Chris@87: a.itemset(*args) Chris@87: Chris@87: Insert scalar into an array (scalar is cast to array's dtype, if possible) Chris@87: Chris@87: There must be at least 1 argument, and define the last argument Chris@87: as *item*. Then, ``a.itemset(*args)`` is equivalent to but faster Chris@87: than ``a[args] = item``. The item should be a scalar value and `args` Chris@87: must select a single item in the array `a`. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: \*args : Arguments Chris@87: If one argument: a scalar, only used in case `a` is of size 1. Chris@87: If two arguments: the last argument is the value to be set Chris@87: and must be a scalar, the first argument specifies a single array Chris@87: element location. It is either an int or a tuple. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: Compared to indexing syntax, `itemset` provides some speed increase Chris@87: for placing a scalar into a particular location in an `ndarray`, Chris@87: if you must do this. However, generally this is discouraged: Chris@87: among other problems, it complicates the appearance of the code. Chris@87: Also, when using `itemset` (and `item`) inside a loop, be sure Chris@87: to assign the methods to a local variable to avoid the attribute Chris@87: look-up at each loop iteration. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.random.randint(9, size=(3, 3)) Chris@87: >>> x Chris@87: array([[3, 1, 7], Chris@87: [2, 8, 3], Chris@87: [8, 5, 3]]) Chris@87: >>> x.itemset(4, 0) Chris@87: >>> x.itemset((2, 2), 9) Chris@87: >>> x Chris@87: array([[3, 1, 7], Chris@87: [2, 0, 3], Chris@87: [8, 5, 9]]) Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('setasflat', Chris@87: """ Chris@87: a.setasflat(arr) Chris@87: Chris@87: Equivalent to a.flat = arr.flat, but is generally more efficient. Chris@87: This function does not check for overlap, so if ``arr`` and ``a`` Chris@87: are viewing the same data with different strides, the results will Chris@87: be unpredictable. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: arr : array_like Chris@87: The array to copy into a. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> a = np.arange(2*4).reshape(2,4)[:,:-1]; a Chris@87: array([[0, 1, 2], Chris@87: [4, 5, 6]]) Chris@87: >>> b = np.arange(3*3, dtype='f4').reshape(3,3).T[::-1,:-1]; b Chris@87: array([[ 2., 5.], Chris@87: [ 1., 4.], Chris@87: [ 0., 3.]], dtype=float32) Chris@87: >>> a.setasflat(b) Chris@87: >>> a Chris@87: array([[2, 5, 1], Chris@87: [4, 0, 3]]) Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('max', Chris@87: """ Chris@87: a.max(axis=None, out=None) Chris@87: Chris@87: Return the maximum along a given axis. Chris@87: Chris@87: Refer to `numpy.amax` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.amax : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('mean', Chris@87: """ Chris@87: a.mean(axis=None, dtype=None, out=None) Chris@87: Chris@87: Returns the average of the array elements along given axis. Chris@87: Chris@87: Refer to `numpy.mean` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.mean : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('min', Chris@87: """ Chris@87: a.min(axis=None, out=None) Chris@87: Chris@87: Return the minimum along a given axis. Chris@87: Chris@87: Refer to `numpy.amin` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.amin : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'may_share_memory', Chris@87: """ Chris@87: Determine if two arrays can share memory Chris@87: Chris@87: The memory-bounds of a and b are computed. If they overlap then Chris@87: this function returns True. Otherwise, it returns False. Chris@87: Chris@87: A return of True does not necessarily mean that the two arrays Chris@87: share any element. It just means that they *might*. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: a, b : ndarray Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: out : bool Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.may_share_memory(np.array([1,2]), np.array([5,8,9])) Chris@87: False Chris@87: Chris@87: """) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('newbyteorder', Chris@87: """ Chris@87: arr.newbyteorder(new_order='S') Chris@87: Chris@87: Return the array with the same data viewed with a different byte order. Chris@87: Chris@87: Equivalent to:: Chris@87: Chris@87: arr.view(arr.dtype.newbytorder(new_order)) Chris@87: Chris@87: Changes are also made in all fields and sub-arrays of the array data Chris@87: type. Chris@87: Chris@87: Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: new_order : string, optional Chris@87: Byte order to force; a value from the byte order specifications Chris@87: above. `new_order` codes can be any of:: Chris@87: Chris@87: * 'S' - swap dtype from current to opposite endian Chris@87: * {'<', 'L'} - little endian Chris@87: * {'>', 'B'} - big endian Chris@87: * {'=', 'N'} - native order Chris@87: * {'|', 'I'} - ignore (no change to byte order) Chris@87: Chris@87: The default value ('S') results in swapping the current Chris@87: byte order. The code does a case-insensitive check on the first Chris@87: letter of `new_order` for the alternatives above. For example, Chris@87: any of 'B' or 'b' or 'biggish' are valid to specify big-endian. Chris@87: Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: new_arr : array Chris@87: New array object with the dtype reflecting given change to the Chris@87: byte order. Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('nonzero', Chris@87: """ Chris@87: a.nonzero() Chris@87: Chris@87: Return the indices of the elements that are non-zero. Chris@87: Chris@87: Refer to `numpy.nonzero` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.nonzero : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('prod', Chris@87: """ Chris@87: a.prod(axis=None, dtype=None, out=None) Chris@87: Chris@87: Return the product of the array elements over the given axis Chris@87: Chris@87: Refer to `numpy.prod` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.prod : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('ptp', Chris@87: """ Chris@87: a.ptp(axis=None, out=None) Chris@87: Chris@87: Peak to peak (maximum - minimum) value along a given axis. Chris@87: Chris@87: Refer to `numpy.ptp` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.ptp : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('put', Chris@87: """ Chris@87: a.put(indices, values, mode='raise') Chris@87: Chris@87: Set ``a.flat[n] = values[n]`` for all `n` in indices. Chris@87: Chris@87: Refer to `numpy.put` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.put : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'copyto', Chris@87: """ Chris@87: copyto(dst, src, casting='same_kind', where=None) Chris@87: Chris@87: Copies values from one array to another, broadcasting as necessary. Chris@87: Chris@87: Raises a TypeError if the `casting` rule is violated, and if Chris@87: `where` is provided, it selects which elements to copy. Chris@87: Chris@87: .. versionadded:: 1.7.0 Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: dst : ndarray Chris@87: The array into which values are copied. Chris@87: src : array_like Chris@87: The array from which values are copied. Chris@87: casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional Chris@87: Controls what kind of data casting may occur when copying. Chris@87: Chris@87: * 'no' means the data types should not be cast at all. Chris@87: * 'equiv' means only byte-order changes are allowed. Chris@87: * 'safe' means only casts which can preserve values are allowed. Chris@87: * 'same_kind' means only safe casts or casts within a kind, Chris@87: like float64 to float32, are allowed. Chris@87: * 'unsafe' means any data conversions may be done. Chris@87: where : array_like of bool, optional Chris@87: A boolean array which is broadcasted to match the dimensions Chris@87: of `dst`, and selects elements to copy from `src` to `dst` Chris@87: wherever it contains the value True. Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'putmask', Chris@87: """ Chris@87: putmask(a, mask, values) Chris@87: Chris@87: Changes elements of an array based on conditional and input values. Chris@87: Chris@87: Sets ``a.flat[n] = values[n]`` for each n where ``mask.flat[n]==True``. Chris@87: Chris@87: If `values` is not the same size as `a` and `mask` then it will repeat. Chris@87: This gives behavior different from ``a[mask] = values``. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: a : array_like Chris@87: Target array. Chris@87: mask : array_like Chris@87: Boolean mask array. It has to be the same shape as `a`. Chris@87: values : array_like Chris@87: Values to put into `a` where `mask` is True. If `values` is smaller Chris@87: than `a` it will be repeated. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: place, put, take, copyto Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.arange(6).reshape(2, 3) Chris@87: >>> np.putmask(x, x>2, x**2) Chris@87: >>> x Chris@87: array([[ 0, 1, 2], Chris@87: [ 9, 16, 25]]) Chris@87: Chris@87: If `values` is smaller than `a` it is repeated: Chris@87: Chris@87: >>> x = np.arange(5) Chris@87: >>> np.putmask(x, x>1, [-33, -44]) Chris@87: >>> x Chris@87: array([ 0, 1, -33, -44, -33]) Chris@87: Chris@87: """) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('ravel', Chris@87: """ Chris@87: a.ravel([order]) Chris@87: Chris@87: Return a flattened array. Chris@87: Chris@87: Refer to `numpy.ravel` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.ravel : equivalent function Chris@87: Chris@87: ndarray.flat : a flat iterator on the array. Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('repeat', Chris@87: """ Chris@87: a.repeat(repeats, axis=None) Chris@87: Chris@87: Repeat elements of an array. Chris@87: Chris@87: Refer to `numpy.repeat` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.repeat : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('reshape', Chris@87: """ Chris@87: a.reshape(shape, order='C') Chris@87: Chris@87: Returns an array containing the same data with a new shape. Chris@87: Chris@87: Refer to `numpy.reshape` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.reshape : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('resize', Chris@87: """ Chris@87: a.resize(new_shape, refcheck=True) Chris@87: Chris@87: Change shape and size of array in-place. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: new_shape : tuple of ints, or `n` ints Chris@87: Shape of resized array. Chris@87: refcheck : bool, optional Chris@87: If False, reference count will not be checked. Default is True. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: None Chris@87: Chris@87: Raises Chris@87: ------ Chris@87: ValueError Chris@87: If `a` does not own its own data or references or views to it exist, Chris@87: and the data memory must be changed. Chris@87: Chris@87: SystemError Chris@87: If the `order` keyword argument is specified. This behaviour is a Chris@87: bug in NumPy. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: resize : Return a new array with the specified shape. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: This reallocates space for the data area if necessary. Chris@87: Chris@87: Only contiguous arrays (data elements consecutive in memory) can be Chris@87: resized. Chris@87: Chris@87: The purpose of the reference count check is to make sure you Chris@87: do not use this array as a buffer for another Python object and then Chris@87: reallocate the memory. However, reference counts can increase in Chris@87: other ways so if you are sure that you have not shared the memory Chris@87: for this array with another Python object, then you may safely set Chris@87: `refcheck` to False. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: Shrinking an array: array is flattened (in the order that the data are Chris@87: stored in memory), resized, and reshaped: Chris@87: Chris@87: >>> a = np.array([[0, 1], [2, 3]], order='C') Chris@87: >>> a.resize((2, 1)) Chris@87: >>> a Chris@87: array([[0], Chris@87: [1]]) Chris@87: Chris@87: >>> a = np.array([[0, 1], [2, 3]], order='F') Chris@87: >>> a.resize((2, 1)) Chris@87: >>> a Chris@87: array([[0], Chris@87: [2]]) Chris@87: Chris@87: Enlarging an array: as above, but missing entries are filled with zeros: Chris@87: Chris@87: >>> b = np.array([[0, 1], [2, 3]]) Chris@87: >>> b.resize(2, 3) # new_shape parameter doesn't have to be a tuple Chris@87: >>> b Chris@87: array([[0, 1, 2], Chris@87: [3, 0, 0]]) Chris@87: Chris@87: Referencing an array prevents resizing... Chris@87: Chris@87: >>> c = a Chris@87: >>> a.resize((1, 1)) Chris@87: Traceback (most recent call last): Chris@87: ... Chris@87: ValueError: cannot resize an array that has been referenced ... Chris@87: Chris@87: Unless `refcheck` is False: Chris@87: Chris@87: >>> a.resize((1, 1), refcheck=False) Chris@87: >>> a Chris@87: array([[0]]) Chris@87: >>> c Chris@87: array([[0]]) Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('round', Chris@87: """ Chris@87: a.round(decimals=0, out=None) Chris@87: Chris@87: Return `a` with each element rounded to the given number of decimals. Chris@87: Chris@87: Refer to `numpy.around` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.around : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('searchsorted', Chris@87: """ Chris@87: a.searchsorted(v, side='left', sorter=None) Chris@87: Chris@87: Find indices where elements of v should be inserted in a to maintain order. Chris@87: Chris@87: For full documentation, see `numpy.searchsorted` Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.searchsorted : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('setfield', Chris@87: """ Chris@87: a.setfield(val, dtype, offset=0) Chris@87: Chris@87: Put a value into a specified place in a field defined by a data-type. Chris@87: Chris@87: Place `val` into `a`'s field defined by `dtype` and beginning `offset` Chris@87: bytes into the field. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: val : object Chris@87: Value to be placed in field. Chris@87: dtype : dtype object Chris@87: Data-type of the field in which to place `val`. Chris@87: offset : int, optional Chris@87: The number of bytes into the field at which to place `val`. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: None Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: getfield Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.eye(3) Chris@87: >>> x.getfield(np.float64) Chris@87: array([[ 1., 0., 0.], Chris@87: [ 0., 1., 0.], Chris@87: [ 0., 0., 1.]]) Chris@87: >>> x.setfield(3, np.int32) Chris@87: >>> x.getfield(np.int32) Chris@87: array([[3, 3, 3], Chris@87: [3, 3, 3], Chris@87: [3, 3, 3]]) Chris@87: >>> x Chris@87: array([[ 1.00000000e+000, 1.48219694e-323, 1.48219694e-323], Chris@87: [ 1.48219694e-323, 1.00000000e+000, 1.48219694e-323], Chris@87: [ 1.48219694e-323, 1.48219694e-323, 1.00000000e+000]]) Chris@87: >>> x.setfield(np.eye(3), np.int32) Chris@87: >>> x Chris@87: array([[ 1., 0., 0.], Chris@87: [ 0., 1., 0.], Chris@87: [ 0., 0., 1.]]) Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('setflags', Chris@87: """ Chris@87: a.setflags(write=None, align=None, uic=None) Chris@87: Chris@87: Set array flags WRITEABLE, ALIGNED, and UPDATEIFCOPY, respectively. Chris@87: Chris@87: These Boolean-valued flags affect how numpy interprets the memory Chris@87: area used by `a` (see Notes below). The ALIGNED flag can only Chris@87: be set to True if the data is actually aligned according to the type. Chris@87: The UPDATEIFCOPY flag can never be set to True. The flag WRITEABLE Chris@87: can only be set to True if the array owns its own memory, or the Chris@87: ultimate owner of the memory exposes a writeable buffer interface, Chris@87: or is a string. (The exception for string is made so that unpickling Chris@87: can be done without copying memory.) Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: write : bool, optional Chris@87: Describes whether or not `a` can be written to. Chris@87: align : bool, optional Chris@87: Describes whether or not `a` is aligned properly for its type. Chris@87: uic : bool, optional Chris@87: Describes whether or not `a` is a copy of another "base" array. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: Array flags provide information about how the memory area used Chris@87: for the array is to be interpreted. There are 6 Boolean flags Chris@87: in use, only three of which can be changed by the user: Chris@87: UPDATEIFCOPY, WRITEABLE, and ALIGNED. Chris@87: Chris@87: WRITEABLE (W) the data area can be written to; Chris@87: Chris@87: ALIGNED (A) the data and strides are aligned appropriately for the hardware Chris@87: (as determined by the compiler); Chris@87: Chris@87: UPDATEIFCOPY (U) this array is a copy of some other array (referenced Chris@87: by .base). When this array is deallocated, the base array will be Chris@87: updated with the contents of this array. Chris@87: Chris@87: All flags can be accessed using their first (upper case) letter as well Chris@87: as the full name. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> y Chris@87: array([[3, 1, 7], Chris@87: [2, 0, 0], Chris@87: [8, 5, 9]]) Chris@87: >>> y.flags Chris@87: C_CONTIGUOUS : True Chris@87: F_CONTIGUOUS : False Chris@87: OWNDATA : True Chris@87: WRITEABLE : True Chris@87: ALIGNED : True Chris@87: UPDATEIFCOPY : False Chris@87: >>> y.setflags(write=0, align=0) Chris@87: >>> y.flags Chris@87: C_CONTIGUOUS : True Chris@87: F_CONTIGUOUS : False Chris@87: OWNDATA : True Chris@87: WRITEABLE : False Chris@87: ALIGNED : False Chris@87: UPDATEIFCOPY : False Chris@87: >>> y.setflags(uic=1) Chris@87: Traceback (most recent call last): Chris@87: File "", line 1, in Chris@87: ValueError: cannot set UPDATEIFCOPY flag to True Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('sort', Chris@87: """ Chris@87: a.sort(axis=-1, kind='quicksort', order=None) Chris@87: Chris@87: Sort an array, in-place. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: axis : int, optional Chris@87: Axis along which to sort. Default is -1, which means sort along the Chris@87: last axis. Chris@87: kind : {'quicksort', 'mergesort', 'heapsort'}, optional Chris@87: Sorting algorithm. Default is 'quicksort'. Chris@87: order : list, optional Chris@87: When `a` is an array with fields defined, this argument specifies Chris@87: which fields to compare first, second, etc. Not all fields need be Chris@87: specified. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.sort : Return a sorted copy of an array. Chris@87: argsort : Indirect sort. Chris@87: lexsort : Indirect stable sort on multiple keys. Chris@87: searchsorted : Find elements in sorted array. Chris@87: partition: Partial sort. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: See ``sort`` for notes on the different sorting algorithms. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> a = np.array([[1,4], [3,1]]) Chris@87: >>> a.sort(axis=1) Chris@87: >>> a Chris@87: array([[1, 4], Chris@87: [1, 3]]) Chris@87: >>> a.sort(axis=0) Chris@87: >>> a Chris@87: array([[1, 3], Chris@87: [1, 4]]) Chris@87: Chris@87: Use the `order` keyword to specify a field to use when sorting a Chris@87: structured array: Chris@87: Chris@87: >>> a = np.array([('a', 2), ('c', 1)], dtype=[('x', 'S1'), ('y', int)]) Chris@87: >>> a.sort(order='y') Chris@87: >>> a Chris@87: array([('c', 1), ('a', 2)], Chris@87: dtype=[('x', '|S1'), ('y', '>> a = np.array([3, 4, 2, 1]) Chris@87: >>> a.partition(a, 3) Chris@87: >>> a Chris@87: array([2, 1, 3, 4]) Chris@87: Chris@87: >>> a.partition((1, 3)) Chris@87: array([1, 2, 3, 4]) Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('squeeze', Chris@87: """ Chris@87: a.squeeze(axis=None) Chris@87: Chris@87: Remove single-dimensional entries from the shape of `a`. Chris@87: Chris@87: Refer to `numpy.squeeze` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.squeeze : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('std', Chris@87: """ Chris@87: a.std(axis=None, dtype=None, out=None, ddof=0) Chris@87: Chris@87: Returns the standard deviation of the array elements along given axis. Chris@87: Chris@87: Refer to `numpy.std` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.std : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('sum', Chris@87: """ Chris@87: a.sum(axis=None, dtype=None, out=None) Chris@87: Chris@87: Return the sum of the array elements over the given axis. Chris@87: Chris@87: Refer to `numpy.sum` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.sum : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('swapaxes', Chris@87: """ Chris@87: a.swapaxes(axis1, axis2) Chris@87: Chris@87: Return a view of the array with `axis1` and `axis2` interchanged. Chris@87: Chris@87: Refer to `numpy.swapaxes` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.swapaxes : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('take', Chris@87: """ Chris@87: a.take(indices, axis=None, out=None, mode='raise') Chris@87: Chris@87: Return an array formed from the elements of `a` at the given indices. Chris@87: Chris@87: Refer to `numpy.take` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.take : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('tofile', Chris@87: """ Chris@87: a.tofile(fid, sep="", format="%s") Chris@87: Chris@87: Write array to a file as text or binary (default). Chris@87: Chris@87: Data is always written in 'C' order, independent of the order of `a`. Chris@87: The data produced by this method can be recovered using the function Chris@87: fromfile(). Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: fid : file or str Chris@87: An open file object, or a string containing a filename. Chris@87: sep : str Chris@87: Separator between array items for text output. Chris@87: If "" (empty), a binary file is written, equivalent to Chris@87: ``file.write(a.tobytes())``. Chris@87: format : str Chris@87: Format string for text file output. Chris@87: Each entry in the array is formatted to text by first converting Chris@87: it to the closest Python type, and then using "format" % item. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: This is a convenience function for quick storage of array data. Chris@87: Information on endianness and precision is lost, so this method is not a Chris@87: good choice for files intended to archive data or transport data between Chris@87: machines with different endianness. Some of these problems can be overcome Chris@87: by outputting the data as text files, at the expense of speed and file Chris@87: size. Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('tolist', Chris@87: """ Chris@87: a.tolist() Chris@87: Chris@87: Return the array as a (possibly nested) list. Chris@87: Chris@87: Return a copy of the array data as a (nested) Python list. Chris@87: Data items are converted to the nearest compatible Python type. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: none Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: y : list Chris@87: The possibly nested list of array elements. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: The array may be recreated, ``a = np.array(a.tolist())``. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> a = np.array([1, 2]) Chris@87: >>> a.tolist() Chris@87: [1, 2] Chris@87: >>> a = np.array([[1, 2], [3, 4]]) Chris@87: >>> list(a) Chris@87: [array([1, 2]), array([3, 4])] Chris@87: >>> a.tolist() Chris@87: [[1, 2], [3, 4]] Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: tobytesdoc = """ Chris@87: a.{name}(order='C') Chris@87: Chris@87: Construct Python bytes containing the raw data bytes in the array. Chris@87: Chris@87: Constructs Python bytes showing a copy of the raw contents of Chris@87: data memory. The bytes object can be produced in either 'C' or 'Fortran', Chris@87: or 'Any' order (the default is 'C'-order). 'Any' order means C-order Chris@87: unless the F_CONTIGUOUS flag in the array is set, in which case it Chris@87: means 'Fortran' order. Chris@87: Chris@87: {deprecated} Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: order : {{'C', 'F', None}}, optional Chris@87: Order of the data for multidimensional arrays: Chris@87: C, Fortran, or the same as for the original array. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: s : bytes Chris@87: Python bytes exhibiting a copy of `a`'s raw data. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.array([[0, 1], [2, 3]]) Chris@87: >>> x.tobytes() Chris@87: b'\\x00\\x00\\x00\\x00\\x01\\x00\\x00\\x00\\x02\\x00\\x00\\x00\\x03\\x00\\x00\\x00' Chris@87: >>> x.tobytes('C') == x.tobytes() Chris@87: True Chris@87: >>> x.tobytes('F') Chris@87: b'\\x00\\x00\\x00\\x00\\x02\\x00\\x00\\x00\\x01\\x00\\x00\\x00\\x03\\x00\\x00\\x00' Chris@87: Chris@87: """ Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', Chris@87: ('tostring', tobytesdoc.format(name='tostring', Chris@87: deprecated= Chris@87: 'This function is a compatibility ' Chris@87: 'alias for tobytes. Despite its ' Chris@87: 'name it returns bytes not ' Chris@87: 'strings.'))) Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', Chris@87: ('tobytes', tobytesdoc.format(name='tobytes', Chris@87: deprecated='.. versionadded:: 1.9.0'))) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('trace', Chris@87: """ Chris@87: a.trace(offset=0, axis1=0, axis2=1, dtype=None, out=None) Chris@87: Chris@87: Return the sum along diagonals of the array. Chris@87: Chris@87: Refer to `numpy.trace` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.trace : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('transpose', Chris@87: """ Chris@87: a.transpose(*axes) Chris@87: Chris@87: Returns a view of the array with axes transposed. Chris@87: Chris@87: For a 1-D array, this has no effect. (To change between column and Chris@87: row vectors, first cast the 1-D array into a matrix object.) Chris@87: For a 2-D array, this is the usual matrix transpose. Chris@87: For an n-D array, if axes are given, their order indicates how the Chris@87: axes are permuted (see Examples). If axes are not provided and Chris@87: ``a.shape = (i[0], i[1], ... i[n-2], i[n-1])``, then Chris@87: ``a.transpose().shape = (i[n-1], i[n-2], ... i[1], i[0])``. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: axes : None, tuple of ints, or `n` ints Chris@87: Chris@87: * None or no argument: reverses the order of the axes. Chris@87: Chris@87: * tuple of ints: `i` in the `j`-th place in the tuple means `a`'s Chris@87: `i`-th axis becomes `a.transpose()`'s `j`-th axis. Chris@87: Chris@87: * `n` ints: same as an n-tuple of the same ints (this form is Chris@87: intended simply as a "convenience" alternative to the tuple form) Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: out : ndarray Chris@87: View of `a`, with axes suitably permuted. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: ndarray.T : Array property returning the array transposed. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> a = np.array([[1, 2], [3, 4]]) Chris@87: >>> a Chris@87: array([[1, 2], Chris@87: [3, 4]]) Chris@87: >>> a.transpose() Chris@87: array([[1, 3], Chris@87: [2, 4]]) Chris@87: >>> a.transpose((1, 0)) Chris@87: array([[1, 3], Chris@87: [2, 4]]) Chris@87: >>> a.transpose(1, 0) Chris@87: array([[1, 3], Chris@87: [2, 4]]) Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('var', Chris@87: """ Chris@87: a.var(axis=None, dtype=None, out=None, ddof=0) Chris@87: Chris@87: Returns the variance of the array elements, along given axis. Chris@87: Chris@87: Refer to `numpy.var` for full documentation. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.var : equivalent function Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'ndarray', ('view', Chris@87: """ Chris@87: a.view(dtype=None, type=None) Chris@87: Chris@87: New view of array with the same data. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: dtype : data-type or ndarray sub-class, optional Chris@87: Data-type descriptor of the returned view, e.g., float32 or int16. The Chris@87: default, None, results in the view having the same data-type as `a`. Chris@87: This argument can also be specified as an ndarray sub-class, which Chris@87: then specifies the type of the returned object (this is equivalent to Chris@87: setting the ``type`` parameter). Chris@87: type : Python type, optional Chris@87: Type of the returned view, e.g., ndarray or matrix. Again, the Chris@87: default None results in type preservation. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: ``a.view()`` is used two different ways: Chris@87: Chris@87: ``a.view(some_dtype)`` or ``a.view(dtype=some_dtype)`` constructs a view Chris@87: of the array's memory with a different data-type. This can cause a Chris@87: reinterpretation of the bytes of memory. Chris@87: Chris@87: ``a.view(ndarray_subclass)`` or ``a.view(type=ndarray_subclass)`` just Chris@87: returns an instance of `ndarray_subclass` that looks at the same array Chris@87: (same shape, dtype, etc.) This does not cause a reinterpretation of the Chris@87: memory. Chris@87: Chris@87: For ``a.view(some_dtype)``, if ``some_dtype`` has a different number of Chris@87: bytes per entry than the previous dtype (for example, converting a Chris@87: regular array to a structured array), then the behavior of the view Chris@87: cannot be predicted just from the superficial appearance of ``a`` (shown Chris@87: by ``print(a)``). It also depends on exactly how ``a`` is stored in Chris@87: memory. Therefore if ``a`` is C-ordered versus fortran-ordered, versus Chris@87: defined as a slice or transpose, etc., the view may give different Chris@87: results. Chris@87: Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.array([(1, 2)], dtype=[('a', np.int8), ('b', np.int8)]) Chris@87: Chris@87: Viewing array data using a different type and dtype: Chris@87: Chris@87: >>> y = x.view(dtype=np.int16, type=np.matrix) Chris@87: >>> y Chris@87: matrix([[513]], dtype=int16) Chris@87: >>> print type(y) Chris@87: Chris@87: Chris@87: Creating a view on a structured array so it can be used in calculations Chris@87: Chris@87: >>> x = np.array([(1, 2),(3,4)], dtype=[('a', np.int8), ('b', np.int8)]) Chris@87: >>> xv = x.view(dtype=np.int8).reshape(-1,2) Chris@87: >>> xv Chris@87: array([[1, 2], Chris@87: [3, 4]], dtype=int8) Chris@87: >>> xv.mean(0) Chris@87: array([ 2., 3.]) Chris@87: Chris@87: Making changes to the view changes the underlying array Chris@87: Chris@87: >>> xv[0,1] = 20 Chris@87: >>> print x Chris@87: [(1, 20) (3, 4)] Chris@87: Chris@87: Using a view to convert an array to a record array: Chris@87: Chris@87: >>> z = x.view(np.recarray) Chris@87: >>> z.a Chris@87: array([1], dtype=int8) Chris@87: Chris@87: Views share data: Chris@87: Chris@87: >>> x[0] = (9, 10) Chris@87: >>> z[0] Chris@87: (9, 10) Chris@87: Chris@87: Views that change the dtype size (bytes per entry) should normally be Chris@87: avoided on arrays defined by slices, transposes, fortran-ordering, etc.: Chris@87: Chris@87: >>> x = np.array([[1,2,3],[4,5,6]], dtype=np.int16) Chris@87: >>> y = x[:, 0:2] Chris@87: >>> y Chris@87: array([[1, 2], Chris@87: [4, 5]], dtype=int16) Chris@87: >>> y.view(dtype=[('width', np.int16), ('length', np.int16)]) Chris@87: Traceback (most recent call last): Chris@87: File "", line 1, in Chris@87: ValueError: new type not compatible with array. Chris@87: >>> z = y.copy() Chris@87: >>> z.view(dtype=[('width', np.int16), ('length', np.int16)]) Chris@87: array([[(1, 2)], Chris@87: [(4, 5)]], dtype=[('width', '>> oct_array = np.frompyfunc(oct, 1, 1) Chris@87: >>> oct_array(np.array((10, 30, 100))) Chris@87: array([012, 036, 0144], dtype=object) Chris@87: >>> np.array((oct(10), oct(30), oct(100))) # for comparison Chris@87: array(['012', '036', '0144'], Chris@87: dtype='|S4') Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.umath', 'geterrobj', Chris@87: """ Chris@87: geterrobj() Chris@87: Chris@87: Return the current object that defines floating-point error handling. Chris@87: Chris@87: The error object contains all information that defines the error handling Chris@87: behavior in Numpy. `geterrobj` is used internally by the other Chris@87: functions that get and set error handling behavior (`geterr`, `seterr`, Chris@87: `geterrcall`, `seterrcall`). Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: errobj : list Chris@87: The error object, a list containing three elements: Chris@87: [internal numpy buffer size, error mask, error callback function]. Chris@87: Chris@87: The error mask is a single integer that holds the treatment information Chris@87: on all four floating point errors. The information for each error type Chris@87: is contained in three bits of the integer. If we print it in base 8, we Chris@87: can see what treatment is set for "invalid", "under", "over", and Chris@87: "divide" (in that order). The printed string can be interpreted with Chris@87: Chris@87: * 0 : 'ignore' Chris@87: * 1 : 'warn' Chris@87: * 2 : 'raise' Chris@87: * 3 : 'call' Chris@87: * 4 : 'print' Chris@87: * 5 : 'log' Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: seterrobj, seterr, geterr, seterrcall, geterrcall Chris@87: getbufsize, setbufsize Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: For complete documentation of the types of floating-point exceptions and Chris@87: treatment options, see `seterr`. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.geterrobj() # first get the defaults Chris@87: [10000, 0, None] Chris@87: Chris@87: >>> def err_handler(type, flag): Chris@87: ... print "Floating point error (%s), with flag %s" % (type, flag) Chris@87: ... Chris@87: >>> old_bufsize = np.setbufsize(20000) Chris@87: >>> old_err = np.seterr(divide='raise') Chris@87: >>> old_handler = np.seterrcall(err_handler) Chris@87: >>> np.geterrobj() Chris@87: [20000, 2, ] Chris@87: Chris@87: >>> old_err = np.seterr(all='ignore') Chris@87: >>> np.base_repr(np.geterrobj()[1], 8) Chris@87: '0' Chris@87: >>> old_err = np.seterr(divide='warn', over='log', under='call', Chris@87: invalid='print') Chris@87: >>> np.base_repr(np.geterrobj()[1], 8) Chris@87: '4351' Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.umath', 'seterrobj', Chris@87: """ Chris@87: seterrobj(errobj) Chris@87: Chris@87: Set the object that defines floating-point error handling. Chris@87: Chris@87: The error object contains all information that defines the error handling Chris@87: behavior in Numpy. `seterrobj` is used internally by the other Chris@87: functions that set error handling behavior (`seterr`, `seterrcall`). Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: errobj : list Chris@87: The error object, a list containing three elements: Chris@87: [internal numpy buffer size, error mask, error callback function]. Chris@87: Chris@87: The error mask is a single integer that holds the treatment information Chris@87: on all four floating point errors. The information for each error type Chris@87: is contained in three bits of the integer. If we print it in base 8, we Chris@87: can see what treatment is set for "invalid", "under", "over", and Chris@87: "divide" (in that order). The printed string can be interpreted with Chris@87: Chris@87: * 0 : 'ignore' Chris@87: * 1 : 'warn' Chris@87: * 2 : 'raise' Chris@87: * 3 : 'call' Chris@87: * 4 : 'print' Chris@87: * 5 : 'log' Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: geterrobj, seterr, geterr, seterrcall, geterrcall Chris@87: getbufsize, setbufsize Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: For complete documentation of the types of floating-point exceptions and Chris@87: treatment options, see `seterr`. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> old_errobj = np.geterrobj() # first get the defaults Chris@87: >>> old_errobj Chris@87: [10000, 0, None] Chris@87: Chris@87: >>> def err_handler(type, flag): Chris@87: ... print "Floating point error (%s), with flag %s" % (type, flag) Chris@87: ... Chris@87: >>> new_errobj = [20000, 12, err_handler] Chris@87: >>> np.seterrobj(new_errobj) Chris@87: >>> np.base_repr(12, 8) # int for divide=4 ('print') and over=1 ('warn') Chris@87: '14' Chris@87: >>> np.geterr() Chris@87: {'over': 'warn', 'divide': 'print', 'invalid': 'ignore', 'under': 'ignore'} Chris@87: >>> np.geterrcall() is err_handler Chris@87: True Chris@87: Chris@87: """) Chris@87: Chris@87: Chris@87: ############################################################################## Chris@87: # Chris@87: # lib._compiled_base functions Chris@87: # Chris@87: ############################################################################## Chris@87: Chris@87: add_newdoc('numpy.lib._compiled_base', 'digitize', Chris@87: """ Chris@87: digitize(x, bins, right=False) Chris@87: Chris@87: Return the indices of the bins to which each value in input array belongs. Chris@87: Chris@87: Each index ``i`` returned is such that ``bins[i-1] <= x < bins[i]`` if Chris@87: `bins` is monotonically increasing, or ``bins[i-1] > x >= bins[i]`` if Chris@87: `bins` is monotonically decreasing. If values in `x` are beyond the Chris@87: bounds of `bins`, 0 or ``len(bins)`` is returned as appropriate. If right Chris@87: is True, then the right bin is closed so that the index ``i`` is such Chris@87: that ``bins[i-1] < x <= bins[i]`` or bins[i-1] >= x > bins[i]`` if `bins` Chris@87: is monotonically increasing or decreasing, respectively. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: x : array_like Chris@87: Input array to be binned. It has to be 1-dimensional. Chris@87: bins : array_like Chris@87: Array of bins. It has to be 1-dimensional and monotonic. Chris@87: right : bool, optional Chris@87: Indicating whether the intervals include the right or the left bin Chris@87: edge. Default behavior is (right==False) indicating that the interval Chris@87: does not include the right edge. The left bin and is open in this Chris@87: case. Ie., bins[i-1] <= x < bins[i] is the default behavior for Chris@87: monotonically increasing bins. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: out : ndarray of ints Chris@87: Output array of indices, of same shape as `x`. Chris@87: Chris@87: Raises Chris@87: ------ Chris@87: ValueError Chris@87: If the input is not 1-dimensional, or if `bins` is not monotonic. Chris@87: TypeError Chris@87: If the type of the input is complex. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: bincount, histogram, unique Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: If values in `x` are such that they fall outside the bin range, Chris@87: attempting to index `bins` with the indices that `digitize` returns Chris@87: will result in an IndexError. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> x = np.array([0.2, 6.4, 3.0, 1.6]) Chris@87: >>> bins = np.array([0.0, 1.0, 2.5, 4.0, 10.0]) Chris@87: >>> inds = np.digitize(x, bins) Chris@87: >>> inds Chris@87: array([1, 4, 3, 2]) Chris@87: >>> for n in range(x.size): Chris@87: ... print bins[inds[n]-1], "<=", x[n], "<", bins[inds[n]] Chris@87: ... Chris@87: 0.0 <= 0.2 < 1.0 Chris@87: 4.0 <= 6.4 < 10.0 Chris@87: 2.5 <= 3.0 < 4.0 Chris@87: 1.0 <= 1.6 < 2.5 Chris@87: Chris@87: >>> x = np.array([1.2, 10.0, 12.4, 15.5, 20.]) Chris@87: >>> bins = np.array([0,5,10,15,20]) Chris@87: >>> np.digitize(x,bins,right=True) Chris@87: array([1, 2, 3, 4, 4]) Chris@87: >>> np.digitize(x,bins,right=False) Chris@87: array([1, 3, 3, 4, 5]) Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.lib._compiled_base', 'bincount', Chris@87: """ Chris@87: bincount(x, weights=None, minlength=None) Chris@87: Chris@87: Count number of occurrences of each value in array of non-negative ints. Chris@87: Chris@87: The number of bins (of size 1) is one larger than the largest value in Chris@87: `x`. If `minlength` is specified, there will be at least this number Chris@87: of bins in the output array (though it will be longer if necessary, Chris@87: depending on the contents of `x`). Chris@87: Each bin gives the number of occurrences of its index value in `x`. Chris@87: If `weights` is specified the input array is weighted by it, i.e. if a Chris@87: value ``n`` is found at position ``i``, ``out[n] += weight[i]`` instead Chris@87: of ``out[n] += 1``. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: x : array_like, 1 dimension, nonnegative ints Chris@87: Input array. Chris@87: weights : array_like, optional Chris@87: Weights, array of the same shape as `x`. Chris@87: minlength : int, optional Chris@87: .. versionadded:: 1.6.0 Chris@87: Chris@87: A minimum number of bins for the output array. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: out : ndarray of ints Chris@87: The result of binning the input array. Chris@87: The length of `out` is equal to ``np.amax(x)+1``. Chris@87: Chris@87: Raises Chris@87: ------ Chris@87: ValueError Chris@87: If the input is not 1-dimensional, or contains elements with negative Chris@87: values, or if `minlength` is non-positive. Chris@87: TypeError Chris@87: If the type of the input is float or complex. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: histogram, digitize, unique Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.bincount(np.arange(5)) Chris@87: array([1, 1, 1, 1, 1]) Chris@87: >>> np.bincount(np.array([0, 1, 1, 3, 2, 1, 7])) Chris@87: array([1, 3, 1, 1, 0, 0, 0, 1]) Chris@87: Chris@87: >>> x = np.array([0, 1, 1, 3, 2, 1, 7, 23]) Chris@87: >>> np.bincount(x).size == np.amax(x)+1 Chris@87: True Chris@87: Chris@87: The input array needs to be of integer dtype, otherwise a Chris@87: TypeError is raised: Chris@87: Chris@87: >>> np.bincount(np.arange(5, dtype=np.float)) Chris@87: Traceback (most recent call last): Chris@87: File "", line 1, in Chris@87: TypeError: array cannot be safely cast to required type Chris@87: Chris@87: A possible use of ``bincount`` is to perform sums over Chris@87: variable-size chunks of an array, using the ``weights`` keyword. Chris@87: Chris@87: >>> w = np.array([0.3, 0.5, 0.2, 0.7, 1., -0.6]) # weights Chris@87: >>> x = np.array([0, 1, 1, 2, 2, 2]) Chris@87: >>> np.bincount(x, weights=w) Chris@87: array([ 0.3, 0.7, 1.1]) Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.lib._compiled_base', 'ravel_multi_index', Chris@87: """ Chris@87: ravel_multi_index(multi_index, dims, mode='raise', order='C') Chris@87: Chris@87: Converts a tuple of index arrays into an array of flat Chris@87: indices, applying boundary modes to the multi-index. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: multi_index : tuple of array_like Chris@87: A tuple of integer arrays, one array for each dimension. Chris@87: dims : tuple of ints Chris@87: The shape of array into which the indices from ``multi_index`` apply. Chris@87: mode : {'raise', 'wrap', 'clip'}, optional Chris@87: Specifies how out-of-bounds indices are handled. Can specify Chris@87: either one mode or a tuple of modes, one mode per index. Chris@87: Chris@87: * 'raise' -- raise an error (default) Chris@87: * 'wrap' -- wrap around Chris@87: * 'clip' -- clip to the range Chris@87: Chris@87: In 'clip' mode, a negative index which would normally Chris@87: wrap will clip to 0 instead. Chris@87: order : {'C', 'F'}, optional Chris@87: Determines whether the multi-index should be viewed as indexing in Chris@87: C (row-major) order or FORTRAN (column-major) order. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: raveled_indices : ndarray Chris@87: An array of indices into the flattened version of an array Chris@87: of dimensions ``dims``. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: unravel_index Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: .. versionadded:: 1.6.0 Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> arr = np.array([[3,6,6],[4,5,1]]) Chris@87: >>> np.ravel_multi_index(arr, (7,6)) Chris@87: array([22, 41, 37]) Chris@87: >>> np.ravel_multi_index(arr, (7,6), order='F') Chris@87: array([31, 41, 13]) Chris@87: >>> np.ravel_multi_index(arr, (4,6), mode='clip') Chris@87: array([22, 23, 19]) Chris@87: >>> np.ravel_multi_index(arr, (4,4), mode=('clip','wrap')) Chris@87: array([12, 13, 13]) Chris@87: Chris@87: >>> np.ravel_multi_index((3,1,4,1), (6,7,8,9)) Chris@87: 1621 Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.lib._compiled_base', 'unravel_index', Chris@87: """ Chris@87: unravel_index(indices, dims, order='C') Chris@87: Chris@87: Converts a flat index or array of flat indices into a tuple Chris@87: of coordinate arrays. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: indices : array_like Chris@87: An integer array whose elements are indices into the flattened Chris@87: version of an array of dimensions ``dims``. Before version 1.6.0, Chris@87: this function accepted just one index value. Chris@87: dims : tuple of ints Chris@87: The shape of the array to use for unraveling ``indices``. Chris@87: order : {'C', 'F'}, optional Chris@87: .. versionadded:: 1.6.0 Chris@87: Chris@87: Determines whether the indices should be viewed as indexing in Chris@87: C (row-major) order or FORTRAN (column-major) order. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: unraveled_coords : tuple of ndarray Chris@87: Each array in the tuple has the same shape as the ``indices`` Chris@87: array. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: ravel_multi_index Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.unravel_index([22, 41, 37], (7,6)) Chris@87: (array([3, 6, 6]), array([4, 5, 1])) Chris@87: >>> np.unravel_index([31, 41, 13], (7,6), order='F') Chris@87: (array([3, 6, 6]), array([4, 5, 1])) Chris@87: Chris@87: >>> np.unravel_index(1621, (6,7,8,9)) Chris@87: (3, 1, 4, 1) Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.lib._compiled_base', 'add_docstring', Chris@87: """ Chris@87: add_docstring(obj, docstring) Chris@87: Chris@87: Add a docstring to a built-in obj if possible. Chris@87: If the obj already has a docstring raise a RuntimeError Chris@87: If this routine does not know how to add a docstring to the object Chris@87: raise a TypeError Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.lib._compiled_base', 'add_newdoc_ufunc', Chris@87: """ Chris@87: add_ufunc_docstring(ufunc, new_docstring) Chris@87: Chris@87: Replace the docstring for a ufunc with new_docstring. Chris@87: This method will only work if the current docstring for Chris@87: the ufunc is NULL. (At the C level, i.e. when ufunc->doc is NULL.) Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: ufunc : numpy.ufunc Chris@87: A ufunc whose current doc is NULL. Chris@87: new_docstring : string Chris@87: The new docstring for the ufunc. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: This method allocates memory for new_docstring on Chris@87: the heap. Technically this creates a mempory leak, since this Chris@87: memory will not be reclaimed until the end of the program Chris@87: even if the ufunc itself is removed. However this will only Chris@87: be a problem if the user is repeatedly creating ufuncs with Chris@87: no documentation, adding documentation via add_newdoc_ufunc, Chris@87: and then throwing away the ufunc. Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.lib._compiled_base', 'packbits', Chris@87: """ Chris@87: packbits(myarray, axis=None) Chris@87: Chris@87: Packs the elements of a binary-valued array into bits in a uint8 array. Chris@87: Chris@87: The result is padded to full bytes by inserting zero bits at the end. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: myarray : array_like Chris@87: An integer type array whose elements should be packed to bits. Chris@87: axis : int, optional Chris@87: The dimension over which bit-packing is done. Chris@87: ``None`` implies packing the flattened array. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: packed : ndarray Chris@87: Array of type uint8 whose elements represent bits corresponding to the Chris@87: logical (0 or nonzero) value of the input elements. The shape of Chris@87: `packed` has the same number of dimensions as the input (unless `axis` Chris@87: is None, in which case the output is 1-D). Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: unpackbits: Unpacks elements of a uint8 array into a binary-valued output Chris@87: array. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> a = np.array([[[1,0,1], Chris@87: ... [0,1,0]], Chris@87: ... [[1,1,0], Chris@87: ... [0,0,1]]]) Chris@87: >>> b = np.packbits(a, axis=-1) Chris@87: >>> b Chris@87: array([[[160],[64]],[[192],[32]]], dtype=uint8) Chris@87: Chris@87: Note that in binary 160 = 1010 0000, 64 = 0100 0000, 192 = 1100 0000, Chris@87: and 32 = 0010 0000. Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.lib._compiled_base', 'unpackbits', Chris@87: """ Chris@87: unpackbits(myarray, axis=None) Chris@87: Chris@87: Unpacks elements of a uint8 array into a binary-valued output array. Chris@87: Chris@87: Each element of `myarray` represents a bit-field that should be unpacked Chris@87: into a binary-valued output array. The shape of the output array is either Chris@87: 1-D (if `axis` is None) or the same shape as the input array with unpacking Chris@87: done along the axis specified. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: myarray : ndarray, uint8 type Chris@87: Input array. Chris@87: axis : int, optional Chris@87: Unpacks along this axis. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: unpacked : ndarray, uint8 type Chris@87: The elements are binary-valued (0 or 1). Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: packbits : Packs the elements of a binary-valued array into bits in a uint8 Chris@87: array. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> a = np.array([[2], [7], [23]], dtype=np.uint8) Chris@87: >>> a Chris@87: array([[ 2], Chris@87: [ 7], Chris@87: [23]], dtype=uint8) Chris@87: >>> b = np.unpackbits(a, axis=1) Chris@87: >>> b Chris@87: array([[0, 0, 0, 0, 0, 0, 1, 0], Chris@87: [0, 0, 0, 0, 0, 1, 1, 1], Chris@87: [0, 0, 0, 1, 0, 1, 1, 1]], dtype=uint8) Chris@87: Chris@87: """) Chris@87: Chris@87: Chris@87: ############################################################################## Chris@87: # Chris@87: # Documentation for ufunc attributes and methods Chris@87: # Chris@87: ############################################################################## Chris@87: Chris@87: Chris@87: ############################################################################## Chris@87: # Chris@87: # ufunc object Chris@87: # Chris@87: ############################################################################## Chris@87: Chris@87: add_newdoc('numpy.core', 'ufunc', Chris@87: """ Chris@87: Functions that operate element by element on whole arrays. Chris@87: Chris@87: To see the documentation for a specific ufunc, use np.info(). For Chris@87: example, np.info(np.sin). Because ufuncs are written in C Chris@87: (for speed) and linked into Python with NumPy's ufunc facility, Chris@87: Python's help() function finds this page whenever help() is called Chris@87: on a ufunc. Chris@87: Chris@87: A detailed explanation of ufuncs can be found in the "ufuncs.rst" Chris@87: file in the NumPy reference guide. Chris@87: Chris@87: Unary ufuncs: Chris@87: ============= Chris@87: Chris@87: op(X, out=None) Chris@87: Apply op to X elementwise Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: X : array_like Chris@87: Input array. Chris@87: out : array_like Chris@87: An array to store the output. Must be the same shape as `X`. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: r : array_like Chris@87: `r` will have the same shape as `X`; if out is provided, `r` Chris@87: will be equal to out. Chris@87: Chris@87: Binary ufuncs: Chris@87: ============== Chris@87: Chris@87: op(X, Y, out=None) Chris@87: Apply `op` to `X` and `Y` elementwise. May "broadcast" to make Chris@87: the shapes of `X` and `Y` congruent. Chris@87: Chris@87: The broadcasting rules are: Chris@87: Chris@87: * Dimensions of length 1 may be prepended to either array. Chris@87: * Arrays may be repeated along dimensions of length 1. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: X : array_like Chris@87: First input array. Chris@87: Y : array_like Chris@87: Second input array. Chris@87: out : array_like Chris@87: An array to store the output. Must be the same shape as the Chris@87: output would have. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: r : array_like Chris@87: The return value; if out is provided, `r` will be equal to out. Chris@87: Chris@87: """) Chris@87: Chris@87: Chris@87: ############################################################################## Chris@87: # Chris@87: # ufunc attributes Chris@87: # Chris@87: ############################################################################## Chris@87: Chris@87: add_newdoc('numpy.core', 'ufunc', ('identity', Chris@87: """ Chris@87: The identity value. Chris@87: Chris@87: Data attribute containing the identity element for the ufunc, if it has one. Chris@87: If it does not, the attribute value is None. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.add.identity Chris@87: 0 Chris@87: >>> np.multiply.identity Chris@87: 1 Chris@87: >>> np.power.identity Chris@87: 1 Chris@87: >>> print np.exp.identity Chris@87: None Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'ufunc', ('nargs', Chris@87: """ Chris@87: The number of arguments. Chris@87: Chris@87: Data attribute containing the number of arguments the ufunc takes, including Chris@87: optional ones. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: Typically this value will be one more than what you might expect because all Chris@87: ufuncs take the optional "out" argument. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.add.nargs Chris@87: 3 Chris@87: >>> np.multiply.nargs Chris@87: 3 Chris@87: >>> np.power.nargs Chris@87: 3 Chris@87: >>> np.exp.nargs Chris@87: 2 Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'ufunc', ('nin', Chris@87: """ Chris@87: The number of inputs. Chris@87: Chris@87: Data attribute containing the number of arguments the ufunc treats as input. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.add.nin Chris@87: 2 Chris@87: >>> np.multiply.nin Chris@87: 2 Chris@87: >>> np.power.nin Chris@87: 2 Chris@87: >>> np.exp.nin Chris@87: 1 Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'ufunc', ('nout', Chris@87: """ Chris@87: The number of outputs. Chris@87: Chris@87: Data attribute containing the number of arguments the ufunc treats as output. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: Since all ufuncs can take output arguments, this will always be (at least) 1. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.add.nout Chris@87: 1 Chris@87: >>> np.multiply.nout Chris@87: 1 Chris@87: >>> np.power.nout Chris@87: 1 Chris@87: >>> np.exp.nout Chris@87: 1 Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'ufunc', ('ntypes', Chris@87: """ Chris@87: The number of types. Chris@87: Chris@87: The number of numerical NumPy types - of which there are 18 total - on which Chris@87: the ufunc can operate. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.ufunc.types Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.add.ntypes Chris@87: 18 Chris@87: >>> np.multiply.ntypes Chris@87: 18 Chris@87: >>> np.power.ntypes Chris@87: 17 Chris@87: >>> np.exp.ntypes Chris@87: 7 Chris@87: >>> np.remainder.ntypes Chris@87: 14 Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'ufunc', ('types', Chris@87: """ Chris@87: Returns a list with types grouped input->output. Chris@87: Chris@87: Data attribute listing the data-type "Domain-Range" groupings the ufunc can Chris@87: deliver. The data-types are given using the character codes. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.ufunc.ntypes Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.add.types Chris@87: ['??->?', 'bb->b', 'BB->B', 'hh->h', 'HH->H', 'ii->i', 'II->I', 'll->l', Chris@87: 'LL->L', 'qq->q', 'QQ->Q', 'ff->f', 'dd->d', 'gg->g', 'FF->F', 'DD->D', Chris@87: 'GG->G', 'OO->O'] Chris@87: Chris@87: >>> np.multiply.types Chris@87: ['??->?', 'bb->b', 'BB->B', 'hh->h', 'HH->H', 'ii->i', 'II->I', 'll->l', Chris@87: 'LL->L', 'qq->q', 'QQ->Q', 'ff->f', 'dd->d', 'gg->g', 'FF->F', 'DD->D', Chris@87: 'GG->G', 'OO->O'] Chris@87: Chris@87: >>> np.power.types Chris@87: ['bb->b', 'BB->B', 'hh->h', 'HH->H', 'ii->i', 'II->I', 'll->l', 'LL->L', Chris@87: 'qq->q', 'QQ->Q', 'ff->f', 'dd->d', 'gg->g', 'FF->F', 'DD->D', 'GG->G', Chris@87: 'OO->O'] Chris@87: Chris@87: >>> np.exp.types Chris@87: ['f->f', 'd->d', 'g->g', 'F->F', 'D->D', 'G->G', 'O->O'] Chris@87: Chris@87: >>> np.remainder.types Chris@87: ['bb->b', 'BB->B', 'hh->h', 'HH->H', 'ii->i', 'II->I', 'll->l', 'LL->L', Chris@87: 'qq->q', 'QQ->Q', 'ff->f', 'dd->d', 'gg->g', 'OO->O'] Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: ############################################################################## Chris@87: # Chris@87: # ufunc methods Chris@87: # Chris@87: ############################################################################## Chris@87: Chris@87: add_newdoc('numpy.core', 'ufunc', ('reduce', Chris@87: """ Chris@87: reduce(a, axis=0, dtype=None, out=None, keepdims=False) Chris@87: Chris@87: Reduces `a`'s dimension by one, by applying ufunc along one axis. Chris@87: Chris@87: Let :math:`a.shape = (N_0, ..., N_i, ..., N_{M-1})`. Then Chris@87: :math:`ufunc.reduce(a, axis=i)[k_0, ..,k_{i-1}, k_{i+1}, .., k_{M-1}]` = Chris@87: the result of iterating `j` over :math:`range(N_i)`, cumulatively applying Chris@87: ufunc to each :math:`a[k_0, ..,k_{i-1}, j, k_{i+1}, .., k_{M-1}]`. Chris@87: For a one-dimensional array, reduce produces results equivalent to: Chris@87: :: Chris@87: Chris@87: r = op.identity # op = ufunc Chris@87: for i in range(len(A)): Chris@87: r = op(r, A[i]) Chris@87: return r Chris@87: Chris@87: For example, add.reduce() is equivalent to sum(). Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: a : array_like Chris@87: The array to act on. Chris@87: axis : None or int or tuple of ints, optional Chris@87: Axis or axes along which a reduction is performed. Chris@87: The default (`axis` = 0) is perform a reduction over the first Chris@87: dimension of the input array. `axis` may be negative, in Chris@87: which case it counts from the last to the first axis. Chris@87: Chris@87: .. versionadded:: 1.7.0 Chris@87: Chris@87: If this is `None`, a reduction is performed over all the axes. Chris@87: If this is a tuple of ints, a reduction is performed on multiple Chris@87: axes, instead of a single axis or all the axes as before. Chris@87: Chris@87: For operations which are either not commutative or not associative, Chris@87: doing a reduction over multiple axes is not well-defined. The Chris@87: ufuncs do not currently raise an exception in this case, but will Chris@87: likely do so in the future. Chris@87: dtype : data-type code, optional Chris@87: The type used to represent the intermediate results. Defaults Chris@87: to the data-type of the output array if this is provided, or Chris@87: the data-type of the input array if no output array is provided. Chris@87: out : ndarray, optional Chris@87: A location into which the result is stored. If not provided, a Chris@87: freshly-allocated array is returned. Chris@87: keepdims : bool, optional Chris@87: If this is set to True, the axes which are reduced are left Chris@87: in the result as dimensions with size one. With this option, Chris@87: the result will broadcast correctly against the original `arr`. Chris@87: Chris@87: .. versionadded:: 1.7.0 Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: r : ndarray Chris@87: The reduced array. If `out` was supplied, `r` is a reference to it. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.multiply.reduce([2,3,5]) Chris@87: 30 Chris@87: Chris@87: A multi-dimensional array example: Chris@87: Chris@87: >>> X = np.arange(8).reshape((2,2,2)) Chris@87: >>> X Chris@87: array([[[0, 1], Chris@87: [2, 3]], Chris@87: [[4, 5], Chris@87: [6, 7]]]) Chris@87: >>> np.add.reduce(X, 0) Chris@87: array([[ 4, 6], Chris@87: [ 8, 10]]) Chris@87: >>> np.add.reduce(X) # confirm: default axis value is 0 Chris@87: array([[ 4, 6], Chris@87: [ 8, 10]]) Chris@87: >>> np.add.reduce(X, 1) Chris@87: array([[ 2, 4], Chris@87: [10, 12]]) Chris@87: >>> np.add.reduce(X, 2) Chris@87: array([[ 1, 5], Chris@87: [ 9, 13]]) Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'ufunc', ('accumulate', Chris@87: """ Chris@87: accumulate(array, axis=0, dtype=None, out=None) Chris@87: Chris@87: Accumulate the result of applying the operator to all elements. Chris@87: Chris@87: For a one-dimensional array, accumulate produces results equivalent to:: Chris@87: Chris@87: r = np.empty(len(A)) Chris@87: t = op.identity # op = the ufunc being applied to A's elements Chris@87: for i in range(len(A)): Chris@87: t = op(t, A[i]) Chris@87: r[i] = t Chris@87: return r Chris@87: Chris@87: For example, add.accumulate() is equivalent to np.cumsum(). Chris@87: Chris@87: For a multi-dimensional array, accumulate is applied along only one Chris@87: axis (axis zero by default; see Examples below) so repeated use is Chris@87: necessary if one wants to accumulate over multiple axes. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: array : array_like Chris@87: The array to act on. Chris@87: axis : int, optional Chris@87: The axis along which to apply the accumulation; default is zero. Chris@87: dtype : data-type code, optional Chris@87: The data-type used to represent the intermediate results. Defaults Chris@87: to the data-type of the output array if such is provided, or the Chris@87: the data-type of the input array if no output array is provided. Chris@87: out : ndarray, optional Chris@87: A location into which the result is stored. If not provided a Chris@87: freshly-allocated array is returned. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: r : ndarray Chris@87: The accumulated values. If `out` was supplied, `r` is a reference to Chris@87: `out`. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: 1-D array examples: Chris@87: Chris@87: >>> np.add.accumulate([2, 3, 5]) Chris@87: array([ 2, 5, 10]) Chris@87: >>> np.multiply.accumulate([2, 3, 5]) Chris@87: array([ 2, 6, 30]) Chris@87: Chris@87: 2-D array examples: Chris@87: Chris@87: >>> I = np.eye(2) Chris@87: >>> I Chris@87: array([[ 1., 0.], Chris@87: [ 0., 1.]]) Chris@87: Chris@87: Accumulate along axis 0 (rows), down columns: Chris@87: Chris@87: >>> np.add.accumulate(I, 0) Chris@87: array([[ 1., 0.], Chris@87: [ 1., 1.]]) Chris@87: >>> np.add.accumulate(I) # no axis specified = axis zero Chris@87: array([[ 1., 0.], Chris@87: [ 1., 1.]]) Chris@87: Chris@87: Accumulate along axis 1 (columns), through rows: Chris@87: Chris@87: >>> np.add.accumulate(I, 1) Chris@87: array([[ 1., 1.], Chris@87: [ 0., 1.]]) Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'ufunc', ('reduceat', Chris@87: """ Chris@87: reduceat(a, indices, axis=0, dtype=None, out=None) Chris@87: Chris@87: Performs a (local) reduce with specified slices over a single axis. Chris@87: Chris@87: For i in ``range(len(indices))``, `reduceat` computes Chris@87: ``ufunc.reduce(a[indices[i]:indices[i+1]])``, which becomes the i-th Chris@87: generalized "row" parallel to `axis` in the final result (i.e., in a Chris@87: 2-D array, for example, if `axis = 0`, it becomes the i-th row, but if Chris@87: `axis = 1`, it becomes the i-th column). There are three exceptions to this: Chris@87: Chris@87: * when ``i = len(indices) - 1`` (so for the last index), Chris@87: ``indices[i+1] = a.shape[axis]``. Chris@87: * if ``indices[i] >= indices[i + 1]``, the i-th generalized "row" is Chris@87: simply ``a[indices[i]]``. Chris@87: * if ``indices[i] >= len(a)`` or ``indices[i] < 0``, an error is raised. Chris@87: Chris@87: The shape of the output depends on the size of `indices`, and may be Chris@87: larger than `a` (this happens if ``len(indices) > a.shape[axis]``). Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: a : array_like Chris@87: The array to act on. Chris@87: indices : array_like Chris@87: Paired indices, comma separated (not colon), specifying slices to Chris@87: reduce. Chris@87: axis : int, optional Chris@87: The axis along which to apply the reduceat. Chris@87: dtype : data-type code, optional Chris@87: The type used to represent the intermediate results. Defaults Chris@87: to the data type of the output array if this is provided, or Chris@87: the data type of the input array if no output array is provided. Chris@87: out : ndarray, optional Chris@87: A location into which the result is stored. If not provided a Chris@87: freshly-allocated array is returned. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: r : ndarray Chris@87: The reduced values. If `out` was supplied, `r` is a reference to Chris@87: `out`. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: A descriptive example: Chris@87: Chris@87: If `a` is 1-D, the function `ufunc.accumulate(a)` is the same as Chris@87: ``ufunc.reduceat(a, indices)[::2]`` where `indices` is Chris@87: ``range(len(array) - 1)`` with a zero placed Chris@87: in every other element: Chris@87: ``indices = zeros(2 * len(a) - 1)``, ``indices[1::2] = range(1, len(a))``. Chris@87: Chris@87: Don't be fooled by this attribute's name: `reduceat(a)` is not Chris@87: necessarily smaller than `a`. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: To take the running sum of four successive values: Chris@87: Chris@87: >>> np.add.reduceat(np.arange(8),[0,4, 1,5, 2,6, 3,7])[::2] Chris@87: array([ 6, 10, 14, 18]) Chris@87: Chris@87: A 2-D example: Chris@87: Chris@87: >>> x = np.linspace(0, 15, 16).reshape(4,4) Chris@87: >>> x Chris@87: array([[ 0., 1., 2., 3.], Chris@87: [ 4., 5., 6., 7.], Chris@87: [ 8., 9., 10., 11.], Chris@87: [ 12., 13., 14., 15.]]) Chris@87: Chris@87: :: Chris@87: Chris@87: # reduce such that the result has the following five rows: Chris@87: # [row1 + row2 + row3] Chris@87: # [row4] Chris@87: # [row2] Chris@87: # [row3] Chris@87: # [row1 + row2 + row3 + row4] Chris@87: Chris@87: >>> np.add.reduceat(x, [0, 3, 1, 2, 0]) Chris@87: array([[ 12., 15., 18., 21.], Chris@87: [ 12., 13., 14., 15.], Chris@87: [ 4., 5., 6., 7.], Chris@87: [ 8., 9., 10., 11.], Chris@87: [ 24., 28., 32., 36.]]) Chris@87: Chris@87: :: Chris@87: Chris@87: # reduce such that result has the following two columns: Chris@87: # [col1 * col2 * col3, col4] Chris@87: Chris@87: >>> np.multiply.reduceat(x, [0, 3], 1) Chris@87: array([[ 0., 3.], Chris@87: [ 120., 7.], Chris@87: [ 720., 11.], Chris@87: [ 2184., 15.]]) Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'ufunc', ('outer', Chris@87: """ Chris@87: outer(A, B) Chris@87: Chris@87: Apply the ufunc `op` to all pairs (a, b) with a in `A` and b in `B`. Chris@87: Chris@87: Let ``M = A.ndim``, ``N = B.ndim``. Then the result, `C`, of Chris@87: ``op.outer(A, B)`` is an array of dimension M + N such that: Chris@87: Chris@87: .. math:: C[i_0, ..., i_{M-1}, j_0, ..., j_{N-1}] = Chris@87: op(A[i_0, ..., i_{M-1}], B[j_0, ..., j_{N-1}]) Chris@87: Chris@87: For `A` and `B` one-dimensional, this is equivalent to:: Chris@87: Chris@87: r = empty(len(A),len(B)) Chris@87: for i in range(len(A)): Chris@87: for j in range(len(B)): Chris@87: r[i,j] = op(A[i], B[j]) # op = ufunc in question Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: A : array_like Chris@87: First array Chris@87: B : array_like Chris@87: Second array Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: r : ndarray Chris@87: Output array Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.outer Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.multiply.outer([1, 2, 3], [4, 5, 6]) Chris@87: array([[ 4, 5, 6], Chris@87: [ 8, 10, 12], Chris@87: [12, 15, 18]]) Chris@87: Chris@87: A multi-dimensional example: Chris@87: Chris@87: >>> A = np.array([[1, 2, 3], [4, 5, 6]]) Chris@87: >>> A.shape Chris@87: (2, 3) Chris@87: >>> B = np.array([[1, 2, 3, 4]]) Chris@87: >>> B.shape Chris@87: (1, 4) Chris@87: >>> C = np.multiply.outer(A, B) Chris@87: >>> C.shape; C Chris@87: (2, 3, 1, 4) Chris@87: array([[[[ 1, 2, 3, 4]], Chris@87: [[ 2, 4, 6, 8]], Chris@87: [[ 3, 6, 9, 12]]], Chris@87: [[[ 4, 8, 12, 16]], Chris@87: [[ 5, 10, 15, 20]], Chris@87: [[ 6, 12, 18, 24]]]]) Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core', 'ufunc', ('at', Chris@87: """ Chris@87: at(a, indices, b=None) Chris@87: Chris@87: Performs unbuffered in place operation on operand 'a' for elements Chris@87: specified by 'indices'. For addition ufunc, this method is equivalent to Chris@87: `a[indices] += b`, except that results are accumulated for elements that Chris@87: are indexed more than once. For example, `a[[0,0]] += 1` will only Chris@87: increment the first element once because of buffering, whereas Chris@87: `add.at(a, [0,0], 1)` will increment the first element twice. Chris@87: Chris@87: .. versionadded:: 1.8.0 Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: a : array_like Chris@87: The array to perform in place operation on. Chris@87: indices : array_like or tuple Chris@87: Array like index object or slice object for indexing into first Chris@87: operand. If first operand has multiple dimensions, indices can be a Chris@87: tuple of array like index objects or slice objects. Chris@87: b : array_like Chris@87: Second operand for ufuncs requiring two operands. Operand must be Chris@87: broadcastable over first operand after indexing or slicing. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: Set items 0 and 1 to their negative values: Chris@87: Chris@87: >>> a = np.array([1, 2, 3, 4]) Chris@87: >>> np.negative.at(a, [0, 1]) Chris@87: >>> print(a) Chris@87: array([-1, -2, 3, 4]) Chris@87: Chris@87: :: Chris@87: Chris@87: Increment items 0 and 1, and increment item 2 twice: Chris@87: Chris@87: >>> a = np.array([1, 2, 3, 4]) Chris@87: >>> np.add.at(a, [0, 1, 2, 2], 1) Chris@87: >>> print(a) Chris@87: array([2, 3, 5, 4]) Chris@87: Chris@87: :: Chris@87: Chris@87: Add items 0 and 1 in first array to second array, Chris@87: and store results in first array: Chris@87: Chris@87: >>> a = np.array([1, 2, 3, 4]) Chris@87: >>> b = np.array([1, 2]) Chris@87: >>> np.add.at(a, [0, 1], b) Chris@87: >>> print(a) Chris@87: array([2, 4, 3, 4]) Chris@87: Chris@87: """)) Chris@87: Chris@87: ############################################################################## Chris@87: # Chris@87: # Documentation for dtype attributes and methods Chris@87: # Chris@87: ############################################################################## Chris@87: Chris@87: ############################################################################## Chris@87: # Chris@87: # dtype object Chris@87: # Chris@87: ############################################################################## Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', Chris@87: """ Chris@87: dtype(obj, align=False, copy=False) Chris@87: Chris@87: Create a data type object. Chris@87: Chris@87: A numpy array is homogeneous, and contains elements described by a Chris@87: dtype object. A dtype object can be constructed from different Chris@87: combinations of fundamental numeric types. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: obj Chris@87: Object to be converted to a data type object. Chris@87: align : bool, optional Chris@87: Add padding to the fields to match what a C compiler would output Chris@87: for a similar C-struct. Can be ``True`` only if `obj` is a dictionary Chris@87: or a comma-separated string. If a struct dtype is being created, Chris@87: this also sets a sticky alignment flag ``isalignedstruct``. Chris@87: copy : bool, optional Chris@87: Make a new copy of the data-type object. If ``False``, the result Chris@87: may just be a reference to a built-in data-type object. Chris@87: Chris@87: See also Chris@87: -------- Chris@87: result_type Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: Using array-scalar type: Chris@87: Chris@87: >>> np.dtype(np.int16) Chris@87: dtype('int16') Chris@87: Chris@87: Record, one field name 'f1', containing int16: Chris@87: Chris@87: >>> np.dtype([('f1', np.int16)]) Chris@87: dtype([('f1', '>> np.dtype([('f1', [('f1', np.int16)])]) Chris@87: dtype([('f1', [('f1', '>> np.dtype([('f1', np.uint), ('f2', np.int32)]) Chris@87: dtype([('f1', '>> np.dtype([('a','f8'),('b','S10')]) Chris@87: dtype([('a', '>> np.dtype("i4, (2,3)f8") Chris@87: dtype([('f0', '>> np.dtype([('hello',(np.int,3)),('world',np.void,10)]) Chris@87: dtype([('hello', '>> np.dtype((np.int16, {'x':(np.int8,0), 'y':(np.int8,1)})) Chris@87: dtype(('>> np.dtype({'names':['gender','age'], 'formats':['S1',np.uint8]}) Chris@87: dtype([('gender', '|S1'), ('age', '|u1')]) Chris@87: Chris@87: Offsets in bytes, here 0 and 25: Chris@87: Chris@87: >>> np.dtype({'surname':('S25',0),'age':(np.uint8,25)}) Chris@87: dtype([('surname', '|S25'), ('age', '|u1')]) Chris@87: Chris@87: """) Chris@87: Chris@87: ############################################################################## Chris@87: # Chris@87: # dtype attributes Chris@87: # Chris@87: ############################################################################## Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', ('alignment', Chris@87: """ Chris@87: The required alignment (bytes) of this data-type according to the compiler. Chris@87: Chris@87: More information is available in the C-API section of the manual. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', ('byteorder', Chris@87: """ Chris@87: A character indicating the byte-order of this data-type object. Chris@87: Chris@87: One of: Chris@87: Chris@87: === ============== Chris@87: '=' native Chris@87: '<' little-endian Chris@87: '>' big-endian Chris@87: '|' not applicable Chris@87: === ============== Chris@87: Chris@87: All built-in data-type objects have byteorder either '=' or '|'. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: Chris@87: >>> dt = np.dtype('i2') Chris@87: >>> dt.byteorder Chris@87: '=' Chris@87: >>> # endian is not relevant for 8 bit numbers Chris@87: >>> np.dtype('i1').byteorder Chris@87: '|' Chris@87: >>> # or ASCII strings Chris@87: >>> np.dtype('S2').byteorder Chris@87: '|' Chris@87: >>> # Even if specific code is given, and it is native Chris@87: >>> # '=' is the byteorder Chris@87: >>> import sys Chris@87: >>> sys_is_le = sys.byteorder == 'little' Chris@87: >>> native_code = sys_is_le and '<' or '>' Chris@87: >>> swapped_code = sys_is_le and '>' or '<' Chris@87: >>> dt = np.dtype(native_code + 'i2') Chris@87: >>> dt.byteorder Chris@87: '=' Chris@87: >>> # Swapped code shows up as itself Chris@87: >>> dt = np.dtype(swapped_code + 'i2') Chris@87: >>> dt.byteorder == swapped_code Chris@87: True Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', ('char', Chris@87: """A unique character code for each of the 21 different built-in types.""")) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', ('descr', Chris@87: """ Chris@87: Array-interface compliant full description of the data-type. Chris@87: Chris@87: The format is that required by the 'descr' key in the Chris@87: `__array_interface__` attribute. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', ('fields', Chris@87: """ Chris@87: Dictionary of named fields defined for this data type, or ``None``. Chris@87: Chris@87: The dictionary is indexed by keys that are the names of the fields. Chris@87: Each entry in the dictionary is a tuple fully describing the field:: Chris@87: Chris@87: (dtype, offset[, title]) Chris@87: Chris@87: If present, the optional title can be any object (if it is a string Chris@87: or unicode then it will also be a key in the fields dictionary, Chris@87: otherwise it's meta-data). Notice also that the first two elements Chris@87: of the tuple can be passed directly as arguments to the ``ndarray.getfield`` Chris@87: and ``ndarray.setfield`` methods. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: ndarray.getfield, ndarray.setfield Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))]) Chris@87: >>> print dt.fields Chris@87: {'grades': (dtype(('float64',(2,))), 16), 'name': (dtype('|S16'), 0)} Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', ('flags', Chris@87: """ Chris@87: Bit-flags describing how this data type is to be interpreted. Chris@87: Chris@87: Bit-masks are in `numpy.core.multiarray` as the constants Chris@87: `ITEM_HASOBJECT`, `LIST_PICKLE`, `ITEM_IS_POINTER`, `NEEDS_INIT`, Chris@87: `NEEDS_PYAPI`, `USE_GETITEM`, `USE_SETITEM`. A full explanation Chris@87: of these flags is in C-API documentation; they are largely useful Chris@87: for user-defined data-types. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', ('hasobject', Chris@87: """ Chris@87: Boolean indicating whether this dtype contains any reference-counted Chris@87: objects in any fields or sub-dtypes. Chris@87: Chris@87: Recall that what is actually in the ndarray memory representing Chris@87: the Python object is the memory address of that object (a pointer). Chris@87: Special handling may be required, and this attribute is useful for Chris@87: distinguishing data types that may contain arbitrary Python objects Chris@87: and data-types that won't. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', ('isbuiltin', Chris@87: """ Chris@87: Integer indicating how this dtype relates to the built-in dtypes. Chris@87: Chris@87: Read-only. Chris@87: Chris@87: = ======================================================================== Chris@87: 0 if this is a structured array type, with fields Chris@87: 1 if this is a dtype compiled into numpy (such as ints, floats etc) Chris@87: 2 if the dtype is for a user-defined numpy type Chris@87: A user-defined type uses the numpy C-API machinery to extend Chris@87: numpy to handle a new array type. See Chris@87: :ref:`user.user-defined-data-types` in the Numpy manual. Chris@87: = ======================================================================== Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> dt = np.dtype('i2') Chris@87: >>> dt.isbuiltin Chris@87: 1 Chris@87: >>> dt = np.dtype('f8') Chris@87: >>> dt.isbuiltin Chris@87: 1 Chris@87: >>> dt = np.dtype([('field1', 'f8')]) Chris@87: >>> dt.isbuiltin Chris@87: 0 Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', ('isnative', Chris@87: """ Chris@87: Boolean indicating whether the byte order of this dtype is native Chris@87: to the platform. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', ('isalignedstruct', Chris@87: """ Chris@87: Boolean indicating whether the dtype is a struct which maintains Chris@87: field alignment. This flag is sticky, so when combining multiple Chris@87: structs together, it is preserved and produces new dtypes which Chris@87: are also aligned. Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', ('itemsize', Chris@87: """ Chris@87: The element size of this data-type object. Chris@87: Chris@87: For 18 of the 21 types this number is fixed by the data-type. Chris@87: For the flexible data-types, this number can be anything. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', ('kind', Chris@87: """ Chris@87: A character code (one of 'biufcOSUV') identifying the general kind of data. Chris@87: Chris@87: = ====================== Chris@87: b boolean Chris@87: i signed integer Chris@87: u unsigned integer Chris@87: f floating-point Chris@87: c complex floating-point Chris@87: O object Chris@87: S (byte-)string Chris@87: U Unicode Chris@87: V void Chris@87: = ====================== Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', ('name', Chris@87: """ Chris@87: A bit-width name for this data-type. Chris@87: Chris@87: Un-sized flexible data-type objects do not have this attribute. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', ('names', Chris@87: """ Chris@87: Ordered list of field names, or ``None`` if there are no fields. Chris@87: Chris@87: The names are ordered according to increasing byte offset. This can be Chris@87: used, for example, to walk through all of the named fields in offset order. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> dt = np.dtype([('name', np.str_, 16), ('grades', np.float64, (2,))]) Chris@87: >>> dt.names Chris@87: ('name', 'grades') Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', ('num', Chris@87: """ Chris@87: A unique number for each of the 21 different built-in types. Chris@87: Chris@87: These are roughly ordered from least-to-most precision. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', ('shape', Chris@87: """ Chris@87: Shape tuple of the sub-array if this data type describes a sub-array, Chris@87: and ``()`` otherwise. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', ('str', Chris@87: """The array-protocol typestring of this data-type object.""")) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', ('subdtype', Chris@87: """ Chris@87: Tuple ``(item_dtype, shape)`` if this `dtype` describes a sub-array, and Chris@87: None otherwise. Chris@87: Chris@87: The *shape* is the fixed shape of the sub-array described by this Chris@87: data type, and *item_dtype* the data type of the array. Chris@87: Chris@87: If a field whose dtype object has this attribute is retrieved, Chris@87: then the extra dimensions implied by *shape* are tacked on to Chris@87: the end of the retrieved array. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', ('type', Chris@87: """The type object used to instantiate a scalar of this data-type.""")) Chris@87: Chris@87: ############################################################################## Chris@87: # Chris@87: # dtype methods Chris@87: # Chris@87: ############################################################################## Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'dtype', ('newbyteorder', Chris@87: """ Chris@87: newbyteorder(new_order='S') Chris@87: Chris@87: Return a new dtype with a different byte order. Chris@87: Chris@87: Changes are also made in all fields and sub-arrays of the data type. Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: new_order : string, optional Chris@87: Byte order to force; a value from the byte order Chris@87: specifications below. The default value ('S') results in Chris@87: swapping the current byte order. Chris@87: `new_order` codes can be any of:: Chris@87: Chris@87: * 'S' - swap dtype from current to opposite endian Chris@87: * {'<', 'L'} - little endian Chris@87: * {'>', 'B'} - big endian Chris@87: * {'=', 'N'} - native order Chris@87: * {'|', 'I'} - ignore (no change to byte order) Chris@87: Chris@87: The code does a case-insensitive check on the first letter of Chris@87: `new_order` for these alternatives. For example, any of '>' Chris@87: or 'B' or 'b' or 'brian' are valid to specify big-endian. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: new_dtype : dtype Chris@87: New dtype object with the given change to the byte order. Chris@87: Chris@87: Notes Chris@87: ----- Chris@87: Changes are also made in all fields and sub-arrays of the data type. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> import sys Chris@87: >>> sys_is_le = sys.byteorder == 'little' Chris@87: >>> native_code = sys_is_le and '<' or '>' Chris@87: >>> swapped_code = sys_is_le and '>' or '<' Chris@87: >>> native_dt = np.dtype(native_code+'i2') Chris@87: >>> swapped_dt = np.dtype(swapped_code+'i2') Chris@87: >>> native_dt.newbyteorder('S') == swapped_dt Chris@87: True Chris@87: >>> native_dt.newbyteorder() == swapped_dt Chris@87: True Chris@87: >>> native_dt == swapped_dt.newbyteorder('S') Chris@87: True Chris@87: >>> native_dt == swapped_dt.newbyteorder('=') Chris@87: True Chris@87: >>> native_dt == swapped_dt.newbyteorder('N') Chris@87: True Chris@87: >>> native_dt == native_dt.newbyteorder('|') Chris@87: True Chris@87: >>> np.dtype('>> np.dtype('>> np.dtype('>i2') == native_dt.newbyteorder('>') Chris@87: True Chris@87: >>> np.dtype('>i2') == native_dt.newbyteorder('B') Chris@87: True Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: ############################################################################## Chris@87: # Chris@87: # Datetime-related Methods Chris@87: # Chris@87: ############################################################################## Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'busdaycalendar', Chris@87: """ Chris@87: busdaycalendar(weekmask='1111100', holidays=None) Chris@87: Chris@87: A business day calendar object that efficiently stores information Chris@87: defining valid days for the busday family of functions. Chris@87: Chris@87: The default valid days are Monday through Friday ("business days"). Chris@87: A busdaycalendar object can be specified with any set of weekly Chris@87: valid days, plus an optional "holiday" dates that always will be invalid. Chris@87: Chris@87: Once a busdaycalendar object is created, the weekmask and holidays Chris@87: cannot be modified. Chris@87: Chris@87: .. versionadded:: 1.7.0 Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: weekmask : str or array_like of bool, optional Chris@87: A seven-element array indicating which of Monday through Sunday are Chris@87: valid days. May be specified as a length-seven list or array, like Chris@87: [1,1,1,1,1,0,0]; a length-seven string, like '1111100'; or a string Chris@87: like "Mon Tue Wed Thu Fri", made up of 3-character abbreviations for Chris@87: weekdays, optionally separated by white space. Valid abbreviations Chris@87: are: Mon Tue Wed Thu Fri Sat Sun Chris@87: holidays : array_like of datetime64[D], optional Chris@87: An array of dates to consider as invalid dates, no matter which Chris@87: weekday they fall upon. Holiday dates may be specified in any Chris@87: order, and NaT (not-a-time) dates are ignored. This list is Chris@87: saved in a normalized form that is suited for fast calculations Chris@87: of valid days. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: out : busdaycalendar Chris@87: A business day calendar object containing the specified Chris@87: weekmask and holidays values. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: is_busday : Returns a boolean array indicating valid days. Chris@87: busday_offset : Applies an offset counted in valid days. Chris@87: busday_count : Counts how many valid days are in a half-open date range. Chris@87: Chris@87: Attributes Chris@87: ---------- Chris@87: Note: once a busdaycalendar object is created, you cannot modify the Chris@87: weekmask or holidays. The attributes return copies of internal data. Chris@87: weekmask : (copy) seven-element array of bool Chris@87: holidays : (copy) sorted array of datetime64[D] Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> # Some important days in July Chris@87: ... bdd = np.busdaycalendar( Chris@87: ... holidays=['2011-07-01', '2011-07-04', '2011-07-17']) Chris@87: >>> # Default is Monday to Friday weekdays Chris@87: ... bdd.weekmask Chris@87: array([ True, True, True, True, True, False, False], dtype='bool') Chris@87: >>> # Any holidays already on the weekend are removed Chris@87: ... bdd.holidays Chris@87: array(['2011-07-01', '2011-07-04'], dtype='datetime64[D]') Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'busdaycalendar', ('weekmask', Chris@87: """A copy of the seven-element boolean mask indicating valid days.""")) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'busdaycalendar', ('holidays', Chris@87: """A copy of the holiday array indicating additional invalid days.""")) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'is_busday', Chris@87: """ Chris@87: is_busday(dates, weekmask='1111100', holidays=None, busdaycal=None, out=None) Chris@87: Chris@87: Calculates which of the given dates are valid days, and which are not. Chris@87: Chris@87: .. versionadded:: 1.7.0 Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: dates : array_like of datetime64[D] Chris@87: The array of dates to process. Chris@87: weekmask : str or array_like of bool, optional Chris@87: A seven-element array indicating which of Monday through Sunday are Chris@87: valid days. May be specified as a length-seven list or array, like Chris@87: [1,1,1,1,1,0,0]; a length-seven string, like '1111100'; or a string Chris@87: like "Mon Tue Wed Thu Fri", made up of 3-character abbreviations for Chris@87: weekdays, optionally separated by white space. Valid abbreviations Chris@87: are: Mon Tue Wed Thu Fri Sat Sun Chris@87: holidays : array_like of datetime64[D], optional Chris@87: An array of dates to consider as invalid dates. They may be Chris@87: specified in any order, and NaT (not-a-time) dates are ignored. Chris@87: This list is saved in a normalized form that is suited for Chris@87: fast calculations of valid days. Chris@87: busdaycal : busdaycalendar, optional Chris@87: A `busdaycalendar` object which specifies the valid days. If this Chris@87: parameter is provided, neither weekmask nor holidays may be Chris@87: provided. Chris@87: out : array of bool, optional Chris@87: If provided, this array is filled with the result. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: out : array of bool Chris@87: An array with the same shape as ``dates``, containing True for Chris@87: each valid day, and False for each invalid day. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: busdaycalendar: An object that specifies a custom set of valid days. Chris@87: busday_offset : Applies an offset counted in valid days. Chris@87: busday_count : Counts how many valid days are in a half-open date range. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> # The weekdays are Friday, Saturday, and Monday Chris@87: ... np.is_busday(['2011-07-01', '2011-07-02', '2011-07-18'], Chris@87: ... holidays=['2011-07-01', '2011-07-04', '2011-07-17']) Chris@87: array([False, False, True], dtype='bool') Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'busday_offset', Chris@87: """ Chris@87: busday_offset(dates, offsets, roll='raise', weekmask='1111100', holidays=None, busdaycal=None, out=None) Chris@87: Chris@87: First adjusts the date to fall on a valid day according to Chris@87: the ``roll`` rule, then applies offsets to the given dates Chris@87: counted in valid days. Chris@87: Chris@87: .. versionadded:: 1.7.0 Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: dates : array_like of datetime64[D] Chris@87: The array of dates to process. Chris@87: offsets : array_like of int Chris@87: The array of offsets, which is broadcast with ``dates``. Chris@87: roll : {'raise', 'nat', 'forward', 'following', 'backward', 'preceding', 'modifiedfollowing', 'modifiedpreceding'}, optional Chris@87: How to treat dates that do not fall on a valid day. The default Chris@87: is 'raise'. Chris@87: Chris@87: * 'raise' means to raise an exception for an invalid day. Chris@87: * 'nat' means to return a NaT (not-a-time) for an invalid day. Chris@87: * 'forward' and 'following' mean to take the first valid day Chris@87: later in time. Chris@87: * 'backward' and 'preceding' mean to take the first valid day Chris@87: earlier in time. Chris@87: * 'modifiedfollowing' means to take the first valid day Chris@87: later in time unless it is across a Month boundary, in which Chris@87: case to take the first valid day earlier in time. Chris@87: * 'modifiedpreceding' means to take the first valid day Chris@87: earlier in time unless it is across a Month boundary, in which Chris@87: case to take the first valid day later in time. Chris@87: weekmask : str or array_like of bool, optional Chris@87: A seven-element array indicating which of Monday through Sunday are Chris@87: valid days. May be specified as a length-seven list or array, like Chris@87: [1,1,1,1,1,0,0]; a length-seven string, like '1111100'; or a string Chris@87: like "Mon Tue Wed Thu Fri", made up of 3-character abbreviations for Chris@87: weekdays, optionally separated by white space. Valid abbreviations Chris@87: are: Mon Tue Wed Thu Fri Sat Sun Chris@87: holidays : array_like of datetime64[D], optional Chris@87: An array of dates to consider as invalid dates. They may be Chris@87: specified in any order, and NaT (not-a-time) dates are ignored. Chris@87: This list is saved in a normalized form that is suited for Chris@87: fast calculations of valid days. Chris@87: busdaycal : busdaycalendar, optional Chris@87: A `busdaycalendar` object which specifies the valid days. If this Chris@87: parameter is provided, neither weekmask nor holidays may be Chris@87: provided. Chris@87: out : array of datetime64[D], optional Chris@87: If provided, this array is filled with the result. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: out : array of datetime64[D] Chris@87: An array with a shape from broadcasting ``dates`` and ``offsets`` Chris@87: together, containing the dates with offsets applied. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: busdaycalendar: An object that specifies a custom set of valid days. Chris@87: is_busday : Returns a boolean array indicating valid days. Chris@87: busday_count : Counts how many valid days are in a half-open date range. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> # First business day in October 2011 (not accounting for holidays) Chris@87: ... np.busday_offset('2011-10', 0, roll='forward') Chris@87: numpy.datetime64('2011-10-03','D') Chris@87: >>> # Last business day in February 2012 (not accounting for holidays) Chris@87: ... np.busday_offset('2012-03', -1, roll='forward') Chris@87: numpy.datetime64('2012-02-29','D') Chris@87: >>> # Third Wednesday in January 2011 Chris@87: ... np.busday_offset('2011-01', 2, roll='forward', weekmask='Wed') Chris@87: numpy.datetime64('2011-01-19','D') Chris@87: >>> # 2012 Mother's Day in Canada and the U.S. Chris@87: ... np.busday_offset('2012-05', 1, roll='forward', weekmask='Sun') Chris@87: numpy.datetime64('2012-05-13','D') Chris@87: Chris@87: >>> # First business day on or after a date Chris@87: ... np.busday_offset('2011-03-20', 0, roll='forward') Chris@87: numpy.datetime64('2011-03-21','D') Chris@87: >>> np.busday_offset('2011-03-22', 0, roll='forward') Chris@87: numpy.datetime64('2011-03-22','D') Chris@87: >>> # First business day after a date Chris@87: ... np.busday_offset('2011-03-20', 1, roll='backward') Chris@87: numpy.datetime64('2011-03-21','D') Chris@87: >>> np.busday_offset('2011-03-22', 1, roll='backward') Chris@87: numpy.datetime64('2011-03-23','D') Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.multiarray', 'busday_count', Chris@87: """ Chris@87: busday_count(begindates, enddates, weekmask='1111100', holidays=[], busdaycal=None, out=None) Chris@87: Chris@87: Counts the number of valid days between `begindates` and Chris@87: `enddates`, not including the day of `enddates`. Chris@87: Chris@87: If ``enddates`` specifies a date value that is earlier than the Chris@87: corresponding ``begindates`` date value, the count will be negative. Chris@87: Chris@87: .. versionadded:: 1.7.0 Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: begindates : array_like of datetime64[D] Chris@87: The array of the first dates for counting. Chris@87: enddates : array_like of datetime64[D] Chris@87: The array of the end dates for counting, which are excluded Chris@87: from the count themselves. Chris@87: weekmask : str or array_like of bool, optional Chris@87: A seven-element array indicating which of Monday through Sunday are Chris@87: valid days. May be specified as a length-seven list or array, like Chris@87: [1,1,1,1,1,0,0]; a length-seven string, like '1111100'; or a string Chris@87: like "Mon Tue Wed Thu Fri", made up of 3-character abbreviations for Chris@87: weekdays, optionally separated by white space. Valid abbreviations Chris@87: are: Mon Tue Wed Thu Fri Sat Sun Chris@87: holidays : array_like of datetime64[D], optional Chris@87: An array of dates to consider as invalid dates. They may be Chris@87: specified in any order, and NaT (not-a-time) dates are ignored. Chris@87: This list is saved in a normalized form that is suited for Chris@87: fast calculations of valid days. Chris@87: busdaycal : busdaycalendar, optional Chris@87: A `busdaycalendar` object which specifies the valid days. If this Chris@87: parameter is provided, neither weekmask nor holidays may be Chris@87: provided. Chris@87: out : array of int, optional Chris@87: If provided, this array is filled with the result. Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: out : array of int Chris@87: An array with a shape from broadcasting ``begindates`` and ``enddates`` Chris@87: together, containing the number of valid days between Chris@87: the begin and end dates. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: busdaycalendar: An object that specifies a custom set of valid days. Chris@87: is_busday : Returns a boolean array indicating valid days. Chris@87: busday_offset : Applies an offset counted in valid days. Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> # Number of weekdays in January 2011 Chris@87: ... np.busday_count('2011-01', '2011-02') Chris@87: 21 Chris@87: >>> # Number of weekdays in 2011 Chris@87: ... np.busday_count('2011', '2012') Chris@87: 260 Chris@87: >>> # Number of Saturdays in 2011 Chris@87: ... np.busday_count('2011', '2012', weekmask='Sat') Chris@87: 53 Chris@87: """) Chris@87: Chris@87: ############################################################################## Chris@87: # Chris@87: # nd_grid instances Chris@87: # Chris@87: ############################################################################## Chris@87: Chris@87: add_newdoc('numpy.lib.index_tricks', 'mgrid', Chris@87: """ Chris@87: `nd_grid` instance which returns a dense multi-dimensional "meshgrid". Chris@87: Chris@87: An instance of `numpy.lib.index_tricks.nd_grid` which returns an dense Chris@87: (or fleshed out) mesh-grid when indexed, so that each returned argument Chris@87: has the same shape. The dimensions and number of the output arrays are Chris@87: equal to the number of indexing dimensions. If the step length is not a Chris@87: complex number, then the stop is not inclusive. Chris@87: Chris@87: However, if the step length is a **complex number** (e.g. 5j), then Chris@87: the integer part of its magnitude is interpreted as specifying the Chris@87: number of points to create between the start and stop values, where Chris@87: the stop value **is inclusive**. Chris@87: Chris@87: Returns Chris@87: ---------- Chris@87: mesh-grid `ndarrays` all of the same dimensions Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: numpy.lib.index_tricks.nd_grid : class of `ogrid` and `mgrid` objects Chris@87: ogrid : like mgrid but returns open (not fleshed out) mesh grids Chris@87: r_ : array concatenator Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> np.mgrid[0:5,0:5] Chris@87: array([[[0, 0, 0, 0, 0], Chris@87: [1, 1, 1, 1, 1], Chris@87: [2, 2, 2, 2, 2], Chris@87: [3, 3, 3, 3, 3], Chris@87: [4, 4, 4, 4, 4]], Chris@87: [[0, 1, 2, 3, 4], Chris@87: [0, 1, 2, 3, 4], Chris@87: [0, 1, 2, 3, 4], Chris@87: [0, 1, 2, 3, 4], Chris@87: [0, 1, 2, 3, 4]]]) Chris@87: >>> np.mgrid[-1:1:5j] Chris@87: array([-1. , -0.5, 0. , 0.5, 1. ]) Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.lib.index_tricks', 'ogrid', Chris@87: """ Chris@87: `nd_grid` instance which returns an open multi-dimensional "meshgrid". Chris@87: Chris@87: An instance of `numpy.lib.index_tricks.nd_grid` which returns an open Chris@87: (i.e. not fleshed out) mesh-grid when indexed, so that only one dimension Chris@87: of each returned array is greater than 1. The dimension and number of the Chris@87: output arrays are equal to the number of indexing dimensions. If the step Chris@87: length is not a complex number, then the stop is not inclusive. Chris@87: Chris@87: However, if the step length is a **complex number** (e.g. 5j), then Chris@87: the integer part of its magnitude is interpreted as specifying the Chris@87: number of points to create between the start and stop values, where Chris@87: the stop value **is inclusive**. Chris@87: Chris@87: Returns Chris@87: ---------- Chris@87: mesh-grid `ndarrays` with only one dimension :math:`\\neq 1` Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: np.lib.index_tricks.nd_grid : class of `ogrid` and `mgrid` objects Chris@87: mgrid : like `ogrid` but returns dense (or fleshed out) mesh grids Chris@87: r_ : array concatenator Chris@87: Chris@87: Examples Chris@87: -------- Chris@87: >>> from numpy import ogrid Chris@87: >>> ogrid[-1:1:5j] Chris@87: array([-1. , -0.5, 0. , 0.5, 1. ]) Chris@87: >>> ogrid[0:5,0:5] Chris@87: [array([[0], Chris@87: [1], Chris@87: [2], Chris@87: [3], Chris@87: [4]]), array([[0, 1, 2, 3, 4]])] Chris@87: Chris@87: """) Chris@87: Chris@87: Chris@87: ############################################################################## Chris@87: # Chris@87: # Documentation for `generic` attributes and methods Chris@87: # Chris@87: ############################################################################## Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', Chris@87: """ Chris@87: Base class for numpy scalar types. Chris@87: Chris@87: Class from which most (all?) numpy scalar types are derived. For Chris@87: consistency, exposes the same API as `ndarray`, despite many Chris@87: consequent attributes being either "get-only," or completely irrelevant. Chris@87: This is the class from which it is strongly suggested users should derive Chris@87: custom scalar types. Chris@87: Chris@87: """) Chris@87: Chris@87: # Attributes Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('T', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class so as to Chris@87: provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('base', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class so as to Chris@87: a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('data', Chris@87: """Pointer to start of data.""")) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('dtype', Chris@87: """Get array data-descriptor.""")) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('flags', Chris@87: """The integer value of flags.""")) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('flat', Chris@87: """A 1-D view of the scalar.""")) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('imag', Chris@87: """The imaginary part of the scalar.""")) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('itemsize', Chris@87: """The length of one element in bytes.""")) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('nbytes', Chris@87: """The length of the scalar in bytes.""")) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('ndim', Chris@87: """The number of array dimensions.""")) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('real', Chris@87: """The real part of the scalar.""")) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('shape', Chris@87: """Tuple of array dimensions.""")) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('size', Chris@87: """The number of elements in the gentype.""")) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('strides', Chris@87: """Tuple of bytes steps in each dimension.""")) Chris@87: Chris@87: # Methods Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('all', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('any', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('argmax', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('argmin', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('argsort', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('astype', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('byteswap', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class so as to Chris@87: provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('choose', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('clip', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('compress', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('conjugate', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('copy', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('cumprod', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('cumsum', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('diagonal', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('dump', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('dumps', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('fill', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('flatten', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('getfield', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('item', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('itemset', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('max', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('mean', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('min', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('newbyteorder', Chris@87: """ Chris@87: newbyteorder(new_order='S') Chris@87: Chris@87: Return a new `dtype` with a different byte order. Chris@87: Chris@87: Changes are also made in all fields and sub-arrays of the data type. Chris@87: Chris@87: The `new_order` code can be any from the following: Chris@87: Chris@87: * {'<', 'L'} - little endian Chris@87: * {'>', 'B'} - big endian Chris@87: * {'=', 'N'} - native order Chris@87: * 'S' - swap dtype from current to opposite endian Chris@87: * {'|', 'I'} - ignore (no change to byte order) Chris@87: Chris@87: Parameters Chris@87: ---------- Chris@87: new_order : str, optional Chris@87: Byte order to force; a value from the byte order specifications Chris@87: above. The default value ('S') results in swapping the current Chris@87: byte order. The code does a case-insensitive check on the first Chris@87: letter of `new_order` for the alternatives above. For example, Chris@87: any of 'B' or 'b' or 'biggish' are valid to specify big-endian. Chris@87: Chris@87: Chris@87: Returns Chris@87: ------- Chris@87: new_dtype : dtype Chris@87: New `dtype` object with the given change to the byte order. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('nonzero', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('prod', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('ptp', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('put', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('ravel', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('repeat', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('reshape', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('resize', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('round', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('searchsorted', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('setfield', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('setflags', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class so as to Chris@87: provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('sort', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('squeeze', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('std', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('sum', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('swapaxes', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('take', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('tofile', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('tolist', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('tostring', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('trace', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('transpose', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('var', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'generic', ('view', Chris@87: """ Chris@87: Not implemented (virtual attribute) Chris@87: Chris@87: Class generic exists solely to derive numpy scalars from, and possesses, Chris@87: albeit unimplemented, all the attributes of the ndarray class Chris@87: so as to provide a uniform API. Chris@87: Chris@87: See Also Chris@87: -------- Chris@87: The corresponding attribute of the derived class of interest. Chris@87: Chris@87: """)) Chris@87: Chris@87: Chris@87: ############################################################################## Chris@87: # Chris@87: # Documentation for other scalar classes Chris@87: # Chris@87: ############################################################################## Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'bool_', Chris@87: """Numpy's Boolean type. Character code: ``?``. Alias: bool8""") Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'complex64', Chris@87: """ Chris@87: Complex number type composed of two 32 bit floats. Character code: 'F'. Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'complex128', Chris@87: """ Chris@87: Complex number type composed of two 64 bit floats. Character code: 'D'. Chris@87: Python complex compatible. Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'complex256', Chris@87: """ Chris@87: Complex number type composed of two 128-bit floats. Character code: 'G'. Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'float32', Chris@87: """ Chris@87: 32-bit floating-point number. Character code 'f'. C float compatible. Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'float64', Chris@87: """ Chris@87: 64-bit floating-point number. Character code 'd'. Python float compatible. Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'float96', Chris@87: """ Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'float128', Chris@87: """ Chris@87: 128-bit floating-point number. Character code: 'g'. C long float Chris@87: compatible. Chris@87: Chris@87: """) Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'int8', Chris@87: """8-bit integer. Character code ``b``. C char compatible.""") Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'int16', Chris@87: """16-bit integer. Character code ``h``. C short compatible.""") Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'int32', Chris@87: """32-bit integer. Character code 'i'. C int compatible.""") Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'int64', Chris@87: """64-bit integer. Character code 'l'. Python int compatible.""") Chris@87: Chris@87: add_newdoc('numpy.core.numerictypes', 'object_', Chris@87: """Any Python object. Character code: 'O'.""")