Glossary

       >>> np.arange(12).reshape(4, -1).shape
       (4, 3)

   - **In an index**, any negative value
     `denotes <https://docs.python.org/dev/faq/programming.html#what-s-a-negative-index>`_
     indexing from the right.

   - **When indexing an array**, shorthand that the missing axes, if they
     exist, are full slices.

       >>> a = np.arange(24).reshape(2,3,4)

       >>> a[...].shape
       (2, 3, 4)

       >>> a[...,0].shape
       (2, 3)

       >>> a[0,...].shape
       (3, 4)

       >>> a[0,...,0].shape
       (3,)

     It can be used at most once; ``a[...,0,...]`` raises an :exc:`IndexError`.

   - **In printouts**, NumPy substitutes ``...`` for the middle elements of
     large arrays. To see the entire array, use `numpy.printoptions`

       >>> a = np.arange(24).reshape(2,3,4)
       >>> a
       array([[[ 0,  1,  2,  3],
               [ 4,  5,  6,  7],
               [ 8,  9, 10, 11]],
       <BLANKLINE>
              [[12, 13, 14, 15],
               [16, 17, 18, 19],
               [20, 21, 22, 23]]])
       <BLANKLINE>
       >>> a[1:,-2:,:-1]
       array([[[16, 17, 18],
               [20, 21, 22]]])

   Trailing slices can be omitted: ::

       >>> a[1] == a[1,:,:]
       array([[ True,  True,  True,  True],
              [ True,  True,  True,  True],
              [ True,  True,  True,  True]])

   In contrast to Python, where slicing creates a copy, in NumPy slicing
   creates a :term:`view`.

   For details, see :ref:`combining-advanced-and-basic-indexing`.

       >>> dt = np.dtype('<f')  # little-endian single-precision float

   In a dtype declaration, indicates that the data is

   :term:`big-endian` (the bracket is big on the left). ::

       >>> dt = np.dtype('>H')  # big-endian unsigned short

   For example, if ``a`` is a 3 x `N` array, an operation along axis 0
   behaves as if its argument were an array containing slices of each row:

       >>> np.array((a[0,:], a[1,:], a[2,:])) #doctest: +SKIP

   To make it concrete, we can pick the operation to be the array-reversal
   function :func:`numpy.flip`, which accepts an ``axis`` argument. We
   construct a 3 x 4 array ``a``:

       >>> a = np.arange(12).reshape(3,4)
       >>> a
       array([[ 0,  1,  2,  3],
              [ 4,  5,  6,  7],
              [ 8,  9, 10, 11]])

   Reversing along axis 0 (the row axis) yields

       >>> np.flip(a,axis=0)
       array([[ 8,  9, 10, 11],
              [ 4,  5,  6,  7],
              [ 0,  1,  2,  3]])

   Recalling the definition of `along an axis`,  ``flip`` along axis 0 is
   treating its argument as if it were

       >>> np.array((a[0,:], a[1,:], a[2,:]))
       array([[ 0,  1,  2,  3],
              [ 4,  5,  6,  7],
              [ 8,  9, 10, 11]])

   and the result of ``np.flip(a,axis=0)`` is to reverse the slices:

       >>> np.array((a[2,:],a[1,:],a[0,:]))
       array([[ 8,  9, 10, 11],
              [ 4,  5,  6,  7],
              [ 0,  1,  2,  3]])

       >>> a = np.array([[1, 2.0], [0, 0], (1+1j, 3.)])

       >>> a
       array([[1.+0.j, 2.+0.j],
              [0.+0.j, 0.+0.j],
              [1.+1.j, 3.+0.j]])

   In a two-dimensional vector, the elements of axis 0 are rows and the
   elements of axis 1 are columns.

   In higher dimensions, the picture changes. NumPy prints
   higher-dimensional vectors as replications of row-by-column building
   blocks, as in this three-dimensional vector:

       >>> a = np.arange(12).reshape(2,2,3)
       >>> a
       array([[[ 0,  1,  2],
               [ 3,  4,  5]],
              [[ 6,  7,  8],
               [ 9, 10, 11]]])

   ``a`` is depicted as a two-element array whose elements are 2x3 vectors.
   From this point of view, rows and columns are the final two axes,
   respectively, in any shape.

   This rule helps you anticipate how a vector will be printed, and
   conversely how to find the index of any of the printed elements. For
   instance, in the example, the last two values of 8's index must be 0 and
   2. Since 8 appears in the second of the two 2x3's, the first index must
   be 1:

       >>> a[1,0,2]
       8

   A convenient way to count dimensions in a printed vector is to
   count ``[`` symbols after the open-parenthesis. This is
   useful in distinguishing, say, a (1,2,3) shape from a (2,3) shape:

       >>> a = np.arange(6).reshape(2,3)
       >>> a.ndim
       2
       >>> a
       array([[0, 1, 2],
              [3, 4, 5]])

       >>> a = np.arange(6).reshape(1,2,3)
       >>> a.ndim
       3
       >>> a
       array([[[0, 1, 2],
               [3, 4, 5]]])

   If an array does not own its memory, then its
   :doc:`base <reference/generated/numpy.ndarray.base>` attribute returns
   the object whose memory the array is referencing. That object may be
   referencing the memory from still another object, so the owning object
   may be ``a.base.base.base...``. Some writers erroneously claim that
   testing ``base`` determines if arrays are :term:`view`\ s. For the
   correct way, see :func:`numpy.shares_memory`.

   It permits an elegant do-what-I-mean behavior where, for instance,
   adding a scalar to a vector adds the scalar value to every element.

       >>> a = np.arange(3)
       >>> a
       array([0, 1, 2])

       >>> a + [3, 3, 3]
       array([3, 4, 5])

       >>> a + 3
       array([3, 4, 5])

   Ordinarily, vector operands must all be the same size, because NumPy
   works element by element -- for instance, ``c = a * b`` is ::

       c[0,0,0] = a[0,0,0] * b[0,0,0]
       c[0,0,1] = a[0,0,1] * b[0,0,1]
      ...

   But in certain useful cases, NumPy can duplicate data along "missing"
   axes or "too-short" dimensions so shapes will match. The duplication
   costs no memory or time. For details, see
   :doc:`Broadcasting. <user/basics.broadcasting>`

   - ``no``: The data types should not be cast at all.
     Any mismatch in data types between the arrays will raise a
     `TypeError`.
   - ``equiv``: Only byte-order changes are allowed.
   - ``safe``: Only casts that can preserve values are allowed. Upcasting
     (e.g., from int to float) is allowed, but downcasting is not.
   - ``same_kind``: The 'same_kind' casting option allows safe casts and
     casts within a kind, like float64 to float32.
   - ``unsafe``: any data conversions may be done.

   An array is contiguous if:

   - it occupies an unbroken block of memory, and
   - array elements with higher indexes occupy higher addresses (that
     is, no :term:`stride` is negative).

   There are two types of proper-contiguous NumPy arrays:

   - Fortran-contiguous arrays refer to data that is stored column-wise,
     i.e. the indexing of data as stored in memory starts from the
     lowest dimension;
   - C-contiguous, or simply contiguous arrays, refer to data that is
     stored row-wise, i.e. the indexing of data as stored in memory
     starts from the highest dimension.

   For one-dimensional arrays these notions coincide.

   For example, a 2x2 array ``A`` is Fortran-contiguous if its elements are
   stored in memory in the following order::

       A[0,0] A[1,0] A[0,1] A[1,1]

   and C-contiguous if the order is as follows::

       A[0,0] A[0,1] A[1,0] A[1,1]

   To test whether an array is C-contiguous, use the ``.flags.c_contiguous``
   attribute of NumPy arrays.  To test for Fortran contiguity, use the
   ``.flags.f_contiguous`` attribute.

   NumPy `object arrays <#term-object-array>`_, which contain references to
   Python objects, fill the role of heterogeneous arrays.

       >>> x = np.arange(5)
       >>> x
       array([0, 1, 2, 3, 4])

       >>> mask = (x > 2)
       >>> mask
       array([False, False, False, True,  True])

       >>> x[mask] = -1
       >>> x
       array([ 0,  1,  2,  -1, -1])

     >>> a = np.ma.masked_array([np.nan, 2, np.nan], [True, False, True])
     >>> a
     masked_array(data=[--, 2.0, --],
                  mask=[ True, False,  True],
            fill_value=1e+20)

     >>> a + [1, 2, 3]
     masked_array(data=[--, 4.0, --],
                  mask=[ True, False,  True],
            fill_value=1e+20)

   For details, see :doc:`Masked arrays. <reference/maskedarray>`

   Flattening collapses a multidimensional array to a single dimension;
   details of how this is done (for instance, whether ``a[n+1]`` should be
   the next row or next column) are parameters.

   Strides are computed automatically from an array's dtype and
   shape, but can be directly specified using
   :doc:`as_strided <reference/generated/numpy.lib.stride_tricks.as_strided>`.
   Bounds validation can be enabled with the ``check_bounds`` parameter.

   For details, see
   :doc:`numpy.ndarray.strides <reference/generated/numpy.ndarray.strides>`.

   To see how striding underlies the power of NumPy views, see
   `The NumPy array: a structure for efficient numerical computation. \
   <https://arxiv.org/pdf/1102.1523.pdf>`_

    >>> dt = np.dtype([('a', np.int32), ('b', np.float32, (3,))])
    >>> np.zeros(3, dtype=dt)
    array([(0, [0., 0., 0.]), (0, [0., 0., 0.]), (0, [0., 0., 0.])],
          dtype=[('a', '<i4'), ('b', '<f4', (3,))])

   An array created this way is a `view`, and NumPy often exploits the
   performance gain of using a view versus making a new array.

   A potential drawback is that writing to a view can alter the original
   as well. If this is a problem, NumPy instead needs to create a
   physically distinct array -- a `copy`.

   Some NumPy routines always return views, some always return copies, some
   may return one or the other, and for some the choice can be specified.
   Responsibility for managing views and copies falls to the programmer.
   :func:`numpy.shares_memory` will check whether ``b`` is a view of
   ``a``, but an exact answer isn't always feasible, as the documentation
   page explains.

     >>> x = np.arange(5)
     >>> x
     array([0, 1, 2, 3, 4])

     >>> y = x[::2]
     >>> y
     array([0, 2, 4])

     >>> x[0] = 3 # changing x changes y as well, since y is a view on x
     >>> y
     array([3, 2, 4])