| NumPy 1.7.0 Release Notes | |
| ************************* | |
| This release includes several new features as well as numerous bug fixes and | |
| refactorings. It supports Python 2.4 - 2.7 and 3.1 - 3.3 and is the last | |
| release that supports Python 2.4 - 2.5. | |
| Highlights | |
| ========== | |
| * ``where=`` parameter to ufuncs (allows the use of boolean arrays to choose | |
| where a computation should be done) | |
| * ``vectorize`` improvements (added 'excluded' and 'cache' keyword, general | |
| cleanup and bug fixes) | |
| * ``numpy.random.choice`` (random sample generating function) | |
| Compatibility notes | |
| =================== | |
| In a future version of numpy, the functions np.diag, np.diagonal, and the | |
| diagonal method of ndarrays will return a view onto the original array, | |
| instead of producing a copy as they do now. This makes a difference if you | |
| write to the array returned by any of these functions. To facilitate this | |
| transition, numpy 1.7 produces a FutureWarning if it detects that you may | |
| be attempting to write to such an array. See the documentation for | |
| np.diagonal for details. | |
| Similar to np.diagonal above, in a future version of numpy, indexing a | |
| record array by a list of field names will return a view onto the original | |
| array, instead of producing a copy as they do now. As with np.diagonal, | |
| numpy 1.7 produces a FutureWarning if it detects that you may be attempting | |
| to write to such an array. See the documentation for array indexing for | |
| details. | |
| In a future version of numpy, the default casting rule for UFunc out= | |
| parameters will be changed from 'unsafe' to 'same_kind'. (This also applies | |
| to in-place operations like a += b, which is equivalent to np.add(a, b, | |
| out=a).) Most usages which violate the 'same_kind' rule are likely bugs, so | |
| this change may expose previously undetected errors in projects that depend | |
| on NumPy. In this version of numpy, such usages will continue to succeed, | |
| but will raise a DeprecationWarning. | |
| Full-array boolean indexing has been optimized to use a different, | |
| optimized code path. This code path should produce the same results, | |
| but any feedback about changes to your code would be appreciated. | |
| Attempting to write to a read-only array (one with ``arr.flags.writeable`` | |
| set to ``False``) used to raise either a RuntimeError, ValueError, or | |
| TypeError inconsistently, depending on which code path was taken. It now | |
| consistently raises a ValueError. | |
| The <ufunc>.reduce functions evaluate some reductions in a different order | |
| than in previous versions of NumPy, generally providing higher performance. | |
| Because of the nature of floating-point arithmetic, this may subtly change | |
| some results, just as linking NumPy to a different BLAS implementations | |
| such as MKL can. | |
| If upgrading from 1.5, then generally in 1.6 and 1.7 there have been | |
| substantial code added and some code paths altered, particularly in the | |
| areas of type resolution and buffered iteration over universal functions. | |
| This might have an impact on your code particularly if you relied on | |
| accidental behavior in the past. | |
| New features | |
| ============ | |
| Reduction UFuncs Generalize axis= Parameter | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| Any ufunc.reduce function call, as well as other reductions like sum, prod, | |
| any, all, max and min support the ability to choose a subset of the axes to | |
| reduce over. Previously, one could say axis=None to mean all the axes or | |
| axis=# to pick a single axis. Now, one can also say axis=(#,#) to pick a | |
| list of axes for reduction. | |
| Reduction UFuncs New keepdims= Parameter | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| There is a new keepdims= parameter, which if set to True, doesn't throw | |
| away the reduction axes but instead sets them to have size one. When this | |
| option is set, the reduction result will broadcast correctly to the | |
| original operand which was reduced. | |
| Datetime support | |
| ~~~~~~~~~~~~~~~~ | |
| .. note:: The datetime API is *experimental* in 1.7.0, and may undergo changes | |
| in future versions of NumPy. | |
| There have been a lot of fixes and enhancements to datetime64 compared | |
| to NumPy 1.6: | |
| * the parser is quite strict about only accepting ISO 8601 dates, with a few | |
| convenience extensions | |
| * converts between units correctly | |
| * datetime arithmetic works correctly | |
| * business day functionality (allows the datetime to be used in contexts where | |
| only certain days of the week are valid) | |
| The notes in `doc/source/reference/arrays.datetime.rst <https://github.com/numpy/numpy/blob/maintenance/1.7.x/doc/source/reference/arrays.datetime.rst>`_ | |
| (also available in the online docs at `arrays.datetime.html | |
| <http://docs.scipy.org/doc/numpy/reference/arrays.datetime.html>`_) should be | |
| consulted for more details. | |
| Custom formatter for printing arrays | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| See the new ``formatter`` parameter of the ``numpy.set_printoptions`` | |
| function. | |
| New function numpy.random.choice | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| A generic sampling function has been added which will generate samples from | |
| a given array-like. The samples can be with or without replacement, and | |
| with uniform or given non-uniform probabilities. | |
| New function isclose | |
| ~~~~~~~~~~~~~~~~~~~~ | |
| Returns a boolean array where two arrays are element-wise equal within a | |
| tolerance. Both relative and absolute tolerance can be specified. | |
| Preliminary multi-dimensional support in the polynomial package | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| Axis keywords have been added to the integration and differentiation | |
| functions and a tensor keyword was added to the evaluation functions. | |
| These additions allow multi-dimensional coefficient arrays to be used in | |
| those functions. New functions for evaluating 2-D and 3-D coefficient | |
| arrays on grids or sets of points were added together with 2-D and 3-D | |
| pseudo-Vandermonde matrices that can be used for fitting. | |
| Ability to pad rank-n arrays | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| A pad module containing functions for padding n-dimensional arrays has been | |
| added. The various private padding functions are exposed as options to a | |
| public 'pad' function. Example:: | |
| pad(a, 5, mode='mean') | |
| Current modes are ``constant``, ``edge``, ``linear_ramp``, ``maximum``, | |
| ``mean``, ``median``, ``minimum``, ``reflect``, ``symmetric``, ``wrap``, and | |
| ``<function>``. | |
| New argument to searchsorted | |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | |
| The function searchsorted now accepts a 'sorter' argument that is a | |
| permutation array that sorts the array to search. | |
| Build system | |
| ~~~~~~~~~~~~ | |
| Added experimental support for the AArch64 architecture. | |
| C API | |
| ~~~~~ | |
| New function ``PyArray_RequireWriteable`` provides a consistent interface | |
| for checking array writeability -- any C code which works with arrays whose | |
| WRITEABLE flag is not known to be True a priori, should make sure to call | |
| this function before writing. | |
| NumPy C Style Guide added (``doc/C_STYLE_GUIDE.rst.txt``). | |
| Changes | |
| ======= | |
| General | |
| ~~~~~~~ | |
| The function np.concatenate tries to match the layout of its input arrays. | |
| Previously, the layout did not follow any particular reason, and depended | |
| in an undesirable way on the particular axis chosen for concatenation. A | |
| bug was also fixed which silently allowed out of bounds axis arguments. | |
| The ufuncs logical_or, logical_and, and logical_not now follow Python's | |
| behavior with object arrays, instead of trying to call methods on the | |
| objects. For example the expression (3 and 'test') produces the string | |
| 'test', and now np.logical_and(np.array(3, 'O'), np.array('test', 'O')) | |
| produces 'test' as well. | |
| The ``.base`` attribute on ndarrays, which is used on views to ensure that the | |
| underlying array owning the memory is not deallocated prematurely, now | |
| collapses out references when you have a view-of-a-view. For example:: | |
| a = np.arange(10) | |
| b = a[1:] | |
| c = b[1:] | |
| In numpy 1.6, ``c.base`` is ``b``, and ``c.base.base`` is ``a``. In numpy 1.7, | |
| ``c.base`` is ``a``. | |
| To increase backwards compatibility for software which relies on the old | |
| behaviour of ``.base``, we only 'skip over' objects which have exactly the same | |
| type as the newly created view. This makes a difference if you use ``ndarray`` | |
| subclasses. For example, if we have a mix of ``ndarray`` and ``matrix`` objects | |
| which are all views on the same original ``ndarray``:: | |
| a = np.arange(10) | |
| b = np.asmatrix(a) | |
| c = b[0, 1:] | |
| d = c[0, 1:] | |
| then ``d.base`` will be ``b``. This is because ``d`` is a ``matrix`` object, | |
| and so the collapsing process only continues so long as it encounters other | |
| ``matrix`` objects. It considers ``c``, ``b``, and ``a`` in that order, and | |
| ``b`` is the last entry in that list which is a ``matrix`` object. | |
| Casting Rules | |
| ~~~~~~~~~~~~~ | |
| Casting rules have undergone some changes in corner cases, due to the | |
| NA-related work. In particular for combinations of scalar+scalar: | |
| * the `longlong` type (`q`) now stays `longlong` for operations with any other | |
| number (`? b h i l q p B H I`), previously it was cast as `int_` (`l`). The | |
| `ulonglong` type (`Q`) now stays as `ulonglong` instead of `uint` (`L`). | |
| * the `timedelta64` type (`m`) can now be mixed with any integer type (`b h i l | |
| q p B H I L Q P`), previously it raised `TypeError`. | |
| For array + scalar, the above rules just broadcast except the case when | |
| the array and scalars are unsigned/signed integers, then the result gets | |
| converted to the array type (of possibly larger size) as illustrated by the | |
| following examples:: | |
| >>> (np.zeros((2,), dtype=np.uint8) + np.int16(257)).dtype | |
| dtype('uint16') | |
| >>> (np.zeros((2,), dtype=np.int8) + np.uint16(257)).dtype | |
| dtype('int16') | |
| >>> (np.zeros((2,), dtype=np.int16) + np.uint32(2**17)).dtype | |
| dtype('int32') | |
| Whether the size gets increased depends on the size of the scalar, for | |
| example:: | |
| >>> (np.zeros((2,), dtype=np.uint8) + np.int16(255)).dtype | |
| dtype('uint8') | |
| >>> (np.zeros((2,), dtype=np.uint8) + np.int16(256)).dtype | |
| dtype('uint16') | |
| Also a ``complex128`` scalar + ``float32`` array is cast to ``complex64``. | |
| In NumPy 1.7 the `datetime64` type (`M`) must be constructed by explicitly | |
| specifying the type as the second argument (e.g. ``np.datetime64(2000, 'Y')``). | |
| Deprecations | |
| ============ | |
| General | |
| ~~~~~~~ | |
| Specifying a custom string formatter with a `_format` array attribute is | |
| deprecated. The new `formatter` keyword in ``numpy.set_printoptions`` or | |
| ``numpy.array2string`` can be used instead. | |
| The deprecated imports in the polynomial package have been removed. | |
| ``concatenate`` now raises DepractionWarning for 1D arrays if ``axis != 0``. | |
| Versions of numpy < 1.7.0 ignored axis argument value for 1D arrays. We | |
| allow this for now, but in due course we will raise an error. | |
| C-API | |
| ~~~~~ | |
| Direct access to the fields of PyArrayObject* has been deprecated. Direct | |
| access has been recommended against for many releases. Expect similar | |
| deprecations for PyArray_Descr* and other core objects in the future as | |
| preparation for NumPy 2.0. | |
| The macros in old_defines.h are deprecated and will be removed in the next | |
| major release (>= 2.0). The sed script tools/replace_old_macros.sed can be | |
| used to replace these macros with the newer versions. | |
| You can test your code against the deprecated C API by #defining | |
| NPY_NO_DEPRECATED_API to the target version number, for example | |
| NPY_1_7_API_VERSION, before including any NumPy headers. | |
| The ``NPY_CHAR`` member of the ``NPY_TYPES`` enum is deprecated and will be | |
| removed in NumPy 1.8. See the discussion at | |
| `gh-2801 <https://github.com/numpy/numpy/issues/2801>`_ for more details. | |