reminisce commented on a change in pull request #8766: NDArray Indexing tutorial and Gradient Compression FAQ URL: https://github.com/apache/incubator-mxnet/pull/8766#discussion_r152465053
########## File path: docs/tutorials/basic/ndarray_indexing.md ########## @@ -0,0 +1,375 @@ + +# NDArray Indexing - Array indexing features + +MXNet's advanced indexing features are modeled after [NumPy's implementation and documentation](https://docs.scipy.org/doc/numpy-1.13.0/reference/arrays.indexing.html#combining-advanced-and-basic-indexing). You will see direct adaptations of many NumPy indexing features, and these are close, if not identical. + +`NDArray`s can be indexed using the standard Python `x[obj]` syntax, where _x_ is the array and _obj_ the selection. + +There are three kinds of indexing available: + +1. field access +1. basic slicing +1. advanced indexing + +In MXNet, we support both basic and advanced indexing following the convention of indexing NumPy's `ndarray`. + + +## Basic Slicing and Indexing + +Basic slicing extends Python?s basic concept of slicing to N dimensions. For a quick review: + +``` +a[start:end] # items start through end-1 +a[start:] # items start through the rest of the array +a[:end] # items from the beginning through end-1 +a[:] # a copy of the whole array +``` + + +```python +import mxnet as mx +from mxnet import nd +``` + +For some working examples of basic slicing we'll start simple. + + +```python +x = nd.array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9], dtype='int32') +x[5:] +``` + + + + + + [5 6 7 8 9] + <NDArray 5 @cpu(0)> + + + + +```python +x = nd.array([0, 1, 2, 3]) +print('1D complete array, x=', x) +s = x[1:3] +print('slicing the 2nd and 3rd elements, s=', s) +``` + + 1D complete array, x= + [ 0. 1. 2. 3.] + <NDArray 4 @cpu(0)> + slicing the 2nd and 3rd elements, s= + [ 1. 2.] + <NDArray 2 @cpu(0)> + + +Now let's try slicing the 2nd and 3rd elements of a multi-dimensional array. + + +```python +x = nd.array([[1, 2, 3, 4], [5, 6, 7, 8], [9, 10, 11, 12]]) +print('multi-D complete array, x=', x) +s = x[1:3] +print('slicing the 2nd and 3rd elements, s=', s) +``` + + multi-D complete array, x= + [[ 1. 2. 3. 4.] + [ 5. 6. 7. 8.] + [ 9. 10. 11. 12.]] + <NDArray 3x4 @cpu(0)> + slicing the 2nd and 3rd elements, s= + [[ 5. 6. 7. 8.] + [ 9. 10. 11. 12.]] + <NDArray 2x4 @cpu(0)> + + +Now let's try writing to a specific element. We'll write `9` to element `2` using `x[2] = 9.0`, which update the whole row. + + +```python +print('original x, x=', x) +x[2] = 9.0 +print('replaced entire row with x[2] = 9.0, x=', x) +``` + + original x, x= + [[ 1. 2. 3. 4.] + [ 5. 6. 7. 8.] + [ 9. 10. 11. 12.]] + <NDArray 3x4 @cpu(0)> + replaced entire row with x[2] = 9.0, x= + [[ 1. 2. 3. 4.] + [ 5. 6. 7. 8.] + [ 9. 9. 9. 9.]] + <NDArray 3x4 @cpu(0)> + + +We can target specific elements too. Let's replace the number `3` in the first row with the number `9` using `x[0,2] = 9.0`. + + +```python +print('original x, x=', x) +x[0,2] = 9.0 +print('replaced specific element with x[0,2] = 9.0, x=', x) +``` + + original x, x= + [[ 1. 2. 3. 4.] + [ 5. 6. 7. 8.] + [ 9. 9. 9. 9.]] + <NDArray 3x4 @cpu(0)> + replaced specific element with x[0,2] = 9.0, x= + [[ 1. 2. 9. 4.] + [ 5. 6. 7. 8.] + [ 9. 9. 9. 9.]] + <NDArray 3x4 @cpu(0)> + + +Now lets target even more by selecting a couple of targets at the same time. We'll replace the `6` and the `7` with `x[1:2,1:3] = 5.0`. + + +```python +print('original x, x=', x) +x[1:2,1:3] = 5.0 +print('replaced range of elements with x[1:2,1:3] = 5.0, x=', x) +``` + + original x, x= + [[ 1. 2. 9. 4.] + [ 5. 6. 7. 8.] + [ 9. 9. 9. 9.]] + <NDArray 3x4 @cpu(0)> + replaced range of elements with x[1:2,1:3] = 5.0, x= + [[ 1. 2. 9. 4.] + [ 5. 5. 5. 8.] + [ 9. 9. 9. 9.]] + <NDArray 3x4 @cpu(0)> + + +## New Indexing Features in v1.0 + +### Step + +The basic slice syntax is `i:j:k` where _i_ is the starting index, _j_ is the stopping index, and _k_ is the step (k must be nonzero). Review comment: The last k should be _k_. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: us...@infra.apache.org With regards, Apache Git Services
