Ctrl+K

expand_dims#

ivy.expand_dims(x, /, *, copy=None, axis=0, out=None)[source]#

Expand the shape of an array by inserting a new axis (dimension) of size one at the position specified by axis.

Parameters:

  • x (Union[Array, NativeArray]) – input array.

  • copy (Optional[bool], default: None) – boolean indicating whether or not to copy the input array. If True, the function must always copy. If False, the function must never copy. In case copy is False we avoid copying by returning a view of the input array.

  • axis (Union[int, Sequence[int]], default: 0) – axis position (zero-based). If x has rank (i.e, number of dimensions) N, a valid axis must reside on the closed-interval [-N-1, N]. If provided a negative axis, the axis position at which to insert a singleton dimension is computed as N + axis + 1. Hence, if provided -1, the resolved axis position is N (i.e., a singleton dimension is appended to the input array x). If provided -N-1, the resolved axis position is 0 (i.e., a singleton dimension is prepended to the input array x). An IndexError exception is raised if provided an invalid axis position.

  • out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.

Return type:

Array

Returns:

ret – an array with its dimension added by one in a given axis.

This function conforms to the Array API Standard. This docstring is an extension of the docstring in the standard.

Both the description and the type hints above assumes an array input for simplicity, but this function is nestable, and therefore also accepts ivy.Container instances in place of any of the arguments.

Examples

With ivy.Array input:

>>> x = ivy.array([0, 1, 2])
>>> y = ivy.expand_dims(x)
>>> print(y)
ivy.array([[0, 1, 2]])

>>> x = ivy.array([[0.5, -0.7, 2.4],
...                [  1,    2,   3]])
>>> y = ivy.zeros((2, 1, 3))
>>> ivy.expand_dims(x, axis=1, out=y)
>>> print(y)
ivy.array([[[0.5, -0.7, 2.4]],
           [[ 1.,   2.,  3.]]])

>>> x = ivy.array([[-1, -2],
...                [ 3,  4]])
>>> y = ivy.zeros((1, 2, 2))
>>> ivy.expand_dims(x, axis=0, out=y)
>>> print(y)
ivy.array([[[-1, -2],
            [3,  4]]])

>>> x = ivy.array([[-1.1, -2.2, 3.3],
...                [ 4.4,  5.5, 6.6]])
>>> y = ivy.expand_dims(x, axis=(0, -1))
>>> print(y)
ivy.array([[[[-1.1],
             [-2.2],
             [ 3.3]],
            [[ 4.4],
             [ 5.5],
             [ 6.6]]]])

>>> x = ivy.array([[-1.7, -3.2, 2.3],
...                [ 6.3,  1.4, 5.7]])
>>> y = ivy.expand_dims(x, axis=[0, 1, -1])
>>> print(y)
ivy.array([[[[[-1.7],
              [-3.2],
              [ 2.3]],
             [[ 6.3],
              [ 1.4],
              [ 5.7]]]]])

With one ivy.Container input:

>>> x = ivy.Container(a=ivy.array([0., 1., 2.]),
...                   b=ivy.array([3., 4., 5.]))
>>> y = ivy.expand_dims(x, axis=-1)
>>> print(y)
{
    a: ivy.array([[0.],
                  [1.],
                  [2.]]),
    b: ivy.array([[3.],
                  [4.],
                  [5.]])
}

With multiple ivy.Container inputs:

>>> x = ivy.Container(a=ivy.array([0., 1., 2.]),
...                   b=ivy.array([3., 4., 5.]))
>>> container_axis = ivy.Container(a=0, b=1)
>>> y = ivy.expand_dims(x, axis=container_axis)
>>> print(y)
{
    a: ivy.array([[0., 1., 2.]]),
    b: ivy.array([[3.],
                  [4.],
                  [5.]])
}
Array.expand_dims(self, /, *, copy=None, axis=0, out=None)[source]#

ivy.Array instance method variant of ivy.expand_dims. This method simply wraps the function, and so the docstring for ivy.expand_dims also applies to this method with minimal changes.

Parameters:

  • self (Array) – input array.

  • axis (Union[int, Sequence[int]], default: 0) – position in the expanded array where a new axis (dimension) of size one will be added. If array self has the rank of N, the axis needs to be between [-N-1, N]. Default: 0.

  • copy (Optional[bool], default: None) – boolean indicating whether or not to copy the input array. If True, the function must always copy. If False, the function must never copy. In case copy is False we avoid copying by returning a view of the input array.

  • out (Optional[Array], default: None) – optional output array, for writing the result to. It must have a shape that the inputs broadcast to.

Return type:

Array

Returns:

ret – An array with the elements of self, but with its dimension added by one in a given axis.

Examples

>>> x = ivy.array([-4.7, -2.3, 0.7]) #x.shape->(3,)
>>> y = x.expand_dims() #y.shape->(1, 3)
>>> print(y)
ivy.array([[-4.7, -2.3,  0.7]])
Container.expand_dims(self, /, *, copy=None, axis=0, key_chains=None, to_apply=True, prune_unapplied=False, map_sequences=False, out=None)[source]#

ivy.Container instance method variant of ivy.expand_dims. This method simply wraps the function, and so the docstring for ivy.expand_dims also applies to this method with minimal changes.

Parameters:

  • self (Container) – input container.

  • copy (Optional[Union[bool, Container]], default: None) – boolean indicating whether or not to copy the input array. If True, the function must always copy. If False, the function must never copy and must raise a ValueError in case a copy would be necessary. If None, the function must reuse existing memory buffer if possible and copy otherwise. Default: None.

  • axis (Union[int, Sequence[int], Container], default: 0) – position where a new axis (dimension) of size one will be added. If an element of the container has the rank of N, the axis needs to be between [-N-1, N]. Default: 0.

  • out (Optional[Container], default: None) – optional output container, for writing the result to. It must have a shape that the inputs broadcast to.

Return type:

Container

Returns:

ret – A container with the elements of self, but with the dimensions of its elements added by one in a given axis.

Examples

>>> x = ivy.Container(a=ivy.array([[0., 1.],
...                                [2., 3.]]),
...                   b=ivy.array([[4., 5.],
...                                [6., 7.]]))
>>> y = x.expand_dims(axis=1)
>>> print(y)
{
    a: ivy.array([[[0., 1.]],
                  [[2., 3.]]]),
    b: ivy.array([[[4., 5.]],
                  [[6., 7.]]])
}
On this page