1.. _array.assignment:
2
3Assignment
4==========
5
6Dask Array supports most of the NumPy assignment indexing syntax. In
7particular, it supports combinations of the following:
8
9* Indexing by integers: ``x[1] = y``
10* Indexing by slices: ``x[2::-1] = y``
11* Indexing by a list of integers: ``x[[0, -1, 1]] = y``
12* Indexing by a 1-d :class:`numpy` array of integers: ``x[np.arange(3)] = y``
13* Indexing by a 1-d :class:`~dask.array.Array` of integers: ``x[da.arange(3)] = y``, ``x[da.from_array([0, -1, 1])] = y``, ``x[da.where(np.array([1, 2, 3]) < 3)[0]] = y``
14* Indexing by a list of booleans: ``x[[False, True, True]] = y``
15* Indexing by a 1-d :class:`numpy` array of booleans: ``x[np.arange(3) > 0] = y``
16
17It also supports:
18
19* Indexing by one broadcastable :class:`~dask.array.Array` of
20  booleans: ``x[x > 0] = y``.
21
22However, it does not currently support the following:
23
24* Indexing with lists in multiple axes: ``x[[1, 2, 3], [3, 1, 2]] = y``
25
26
27.. _array.assignment.broadcasting:
28
29Broadcasting
30------------
31
32The normal NumPy broadcasting rules apply:
33
34.. code-block:: python
35
36   >>> x = da.zeros((2, 6))
37   >>> x[0] = 1
38   >>> x[..., 1] = 2.0
39   >>> x[:, 2] = [3, 4]
40   >>> x[:, 5:2:-2] = [[6, 5]]
41   >>> x.compute()
42   array([[1., 2., 3., 5., 1., 6.],
43          [0., 2., 4., 5., 0., 6.]])
44   >>> x[1] = -x[0]
45   >>> x.compute()
46   array([[ 1.,  2.,  3.,  5.,  1.,  6.],
47          [-1., -2., -3., -5., -1., -6.]])
48
49.. _array.assignment.masking:
50
51Masking
52-------
53
54Elements may be masked by assigning to the NumPy masked value, or to an
55array with masked values:
56
57.. code-block:: python
58
59   >>> x = da.ones((2, 6))
60   >>> x[0, [1, -2]] = np.ma.masked
61   >>> x[1] = np.ma.array([0, 1, 2, 3, 4, 5], mask=[0, 1, 1, 0, 0, 0])
62   >>> print(x.compute())
63   [[1.0 -- 1.0 1.0 -- 1.0]
64    [0.0 -- -- 3.0 4.0 5.0]]
65   >>> x[:, 0] = x[:, 1]
66   >>> print(x.compute())
67   [[1.0 -- 1.0 1.0 -- 1.0]
68    [0.0 -- -- 3.0 4.0 5.0]]
69   >>> x[:, 0] = x[:, 1]
70   >>> print(x.compute())
71   [[-- -- 1.0 1.0 -- 1.0]
72    [-- -- -- 3.0 4.0 5.0]]
73
74If, and only if, a single broadcastable :class:`~dask.array.Array` of
75booleans is provided then masked array assignment does not yet work as
76expected. In this case the data underlying the mask are assigned:
77
78.. code-block:: python
79
80   >>> x = da.arange(12).reshape(2, 6)
81   >>> x[x > 7] = np.ma.array(-99, mask=True)
82   >>> print(x.compute())
83   [[  0   1   2   3   4   5]
84    [  6   7 -99 -99 -99 -99]]
85
86Note that masked assignments do work when a boolean
87:class:`~dask.array.Array` index used in a tuple, or implicit tuple,
88of indices:
89
90.. code-block:: python
91
92   >>> x = da.arange(12).reshape(2, 6)
93   >>> x[1, x[0] > 3] = np.ma.masked
94   >>> print(x.compute())
95   [[0 1 2 3 4 5]
96    [6 7 8 9 -- --]]
97   >>> x = da.arange(12).reshape(2, 6)
98   >>> print(x.compute())
99   [[ 0  1  2  3  4  5]
100    [ 6  7  8  9 10 11]]
101   >>> x[(x[:, 2] < 4,)] = np.ma.masked
102   >>> print(x.compute())
103   [[-- -- -- -- -- --]
104    [6 7 8 9 10 11]]
105
106
107