From e1811e11108cd05d4d026a3007809f5c731757ee Mon Sep 17 00:00:00 2001 From: Allan Haldane Date: Sun, 19 Nov 2017 19:02:18 -0500 Subject: [PATCH] DOC: v/h/dstack docstr shouldn't imply deprecation [ci skip] --- numpy/core/shape_base.py | 43 ++++++++++++++++++---------------------- numpy/lib/shape_base.py | 26 ++++++++++-------------- 2 files changed, 30 insertions(+), 39 deletions(-) diff --git a/numpy/core/shape_base.py b/numpy/core/shape_base.py index 8a047fddab1c..65c3ed00dbd3 100644 --- a/numpy/core/shape_base.py +++ b/numpy/core/shape_base.py @@ -183,23 +183,25 @@ def vstack(tup): """ Stack arrays in sequence vertically (row wise). - Take a sequence of arrays and stack them vertically to make a single - array. Rebuild arrays divided by `vsplit`. + This is equivalent to concatenation along the first axis after 1-D arrays + of shape `(N,)` have been reshaped to `(1,N)`. Rebuilds arrays divided by + `vsplit`. - This function continues to be supported for backward compatibility, but - you should prefer ``np.concatenate`` or ``np.stack``. The ``np.stack`` - function was added in NumPy 1.10. + This function makes most sense for arrays with up to 3 dimensions. For + instance, for pixel-data with a height (first axis), width (second axis), + and r/g/b channels (third axis). The functions `concatenate`, `stack` and + `block` provide more general stacking and concatenation operations. Parameters ---------- tup : sequence of ndarrays - Tuple containing arrays to be stacked. The arrays must have the same - shape along all but the first axis. + The arrays must have the same shape along all but the first axis. + 1-D arrays must have the same length. Returns ------- stacked : ndarray - The array formed by stacking the given arrays. + The array formed by stacking the given arrays, will be at least 2-D. See Also -------- @@ -210,11 +212,6 @@ def vstack(tup): vsplit : Split array into a list of multiple sub-arrays vertically. block : Assemble arrays from blocks. - Notes - ----- - Equivalent to ``np.concatenate(tup, axis=0)`` if `tup` contains arrays that - are at least 2-dimensional. - Examples -------- >>> a = np.array([1, 2, 3]) @@ -240,17 +237,20 @@ def hstack(tup): """ Stack arrays in sequence horizontally (column wise). - Take a sequence of arrays and stack them horizontally to make - a single array. Rebuild arrays divided by `hsplit`. + This is equivalent to concatenation along the second axis, except for 1-D + arrays where it concatenates along the first axis. Rebuilds arrays divided + by `hsplit`. - This function continues to be supported for backward compatibility, but - you should prefer ``np.concatenate`` or ``np.stack``. The ``np.stack`` - function was added in NumPy 1.10. + This function makes most sense for arrays with up to 3 dimensions. For + instance, for pixel-data with a height (first axis), width (second axis), + and r/g/b channels (third axis). The functions `concatenate`, `stack` and + `block` provide more general stacking and concatenation operations. Parameters ---------- tup : sequence of ndarrays - All arrays must have the same shape along all but the second axis. + The arrays must have the same shape along all but the second axis, + except 1-D arrays which can be any length. Returns ------- @@ -266,11 +266,6 @@ def hstack(tup): hsplit : Split array along second axis. block : Assemble arrays from blocks. - Notes - ----- - Equivalent to ``np.concatenate(tup, axis=1)`` if `tup` contains arrays that - are at least 2-dimensional. - Examples -------- >>> a = np.array((1,2,3)) diff --git a/numpy/lib/shape_base.py b/numpy/lib/shape_base.py index a8977bd4ccf0..83e39f9f5e0d 100644 --- a/numpy/lib/shape_base.py +++ b/numpy/lib/shape_base.py @@ -354,25 +354,26 @@ def dstack(tup): """ Stack arrays in sequence depth wise (along third axis). - Takes a sequence of arrays and stack them along the third axis - to make a single array. Rebuilds arrays divided by `dsplit`. - This is a simple way to stack 2D arrays (images) into a single - 3D array for processing. + This is equivalent to concatenation along the third axis after 2-D arrays + of shape `(M,N)` have been reshaped to `(M,N,1)` and 1-D arrays of shape + `(N,)` have been reshaped to `(1,N,1)`. Rebuilds arrays divided by + `dsplit`. - This function continues to be supported for backward compatibility, but - you should prefer ``np.concatenate`` or ``np.stack``. The ``np.stack`` - function was added in NumPy 1.10. + This function makes most sense for arrays with up to 3 dimensions. For + instance, for pixel-data with a height (first axis), width (second axis), + and r/g/b channels (third axis). The functions `concatenate`, `stack` and + `block` provide more general stacking and concatenation operations. Parameters ---------- tup : sequence of arrays - Arrays to stack. All of them must have the same shape along all - but the third axis. + The arrays must have the same shape along all but the third axis. + 1-D or 2-D arrays must have the same shape. Returns ------- stacked : ndarray - The array formed by stacking the given arrays. + The array formed by stacking the given arrays, will be at least 3-D. See Also -------- @@ -382,11 +383,6 @@ def dstack(tup): concatenate : Join a sequence of arrays along an existing axis. dsplit : Split array along third axis. - Notes - ----- - Equivalent to ``np.concatenate(tup, axis=2)`` if `tup` contains arrays that - are at least 3-dimensional. - Examples -------- >>> a = np.array((1,2,3))