content/numpy-advanced: more intersphinx

Author: rkdarst

content/numpy-advanced.rst

@@ -10,10 +10,10 @@ Advanced NumPy
 .. objectives::
 
    - Understand why NumPy has so many specialized functions for specific operations
-   - Understand the underlying machinery of the Numpy ``ndarray`` object
+   - Understand the underlying machinery of the Numpy :class:`~numpy.ndarray` object
    - Understand when and why NumPy makes a copy of the data rather than a view
 
-   This is intended as a follow-up to the basic NumPy lesson.  The indended
+   This is intended as a follow-up to the :doc:`basic NumPy lesson <numpy>`.  The intended
    audience for this advanced lesson is those who have used NumPy before and
    now want to learn how to get the most out of this amazing package.
 
@@ -70,7 +70,9 @@ Exercise 1
    Can you beat the C version?
 
    If you are having trouble with this, we recommend completing the
-   :ref:`basic NumPy lession <numpy>` before continuing with this advanced lesson.
+   :ref:`basic NumPy lession <numpy>` before continuing with this
+   advanced lesson.  If you are taking a live course - don't
+   worry, watch and learn and explore some during the exercises!
 
 .. solution:: Solutions: Numpy-Advanced-2
 
@@ -118,7 +120,7 @@ use ``%%timeit`` to record how long it takes to execute::
   l = np.sqrt(np.sum(a ** 2))
   print(l)
 
-And here is the version using the specialized BLAS function::
+And here is the version using the specialized BLAS function :func:`~numpy.linalg.norm`::
 
   %%timeit
   l = np.linalg.norm(a)
@@ -141,13 +143,14 @@ An example: matrix transpose
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Transposing a matrix means that all rows become columns and all columns become
 rows. All off-diagonal values change places. Let's see how long NumPy's
-transpose function takes, by transposing a huge (10 000 ✕ 20 000) matrix::
+transpose function takes, by transposing a huge (10 000 ✕ 20 000)
+:func:`~numpy.random.rand` matrix::
 
   import numpy as np
   a = np.random.rand(10_000, 20_000)
   print(f'Matrix `a` takes up {a.nbytes / 10**6} MB')
 
-Let's time the :func:`numpy.transpose` function::
+Let's time the :meth:`~numpy.ndarray.transpose` method::
 
   %%timeit
   b = a.transpose()
@@ -216,16 +219,16 @@ of "strides"::
   np.zeros((4, 8)).strides           # (64, 8)
   np.zeros((4, 5, 6, 7, 8)).strides  # (13440, 2688, 448, 64, 8)
 
-The ``.strides`` attribute contains for each dimension, the number of *bytes* (not array indexes) we
+The :attr:`~numpy.ndarray.strides` attribute contains for each dimension, the number of *bytes* (not array indexes) we
 have to skip over to get to the next element along that dimension. For example,
 the result above tells us that to get to the next row in a 4 ✕ 8 matrix, we
 have to skip ahead 64 bytes. 64? Yes! We have created a matrix consisting of
 double-precision floating point numbers. Each one of those bad boys takes up 8
 bytes, so all the indices are multiplied by 8 to get to the proper byte in the
 memory array. To move to the next column in the matrix, we skip ahead 8 bytes.
 
-So now we know the mystery beding the speed of `transpose()`.  NumPy can avoid
-copying any data by just modifying the ``.strides`` of the array::
+So now we know the mystery behind the speed of :meth:`~numpy.ndarray.transpose`.  NumPy can avoid
+copying any data by just modifying the :attr:`~numpy.ndarray.strides` of the array::
 
   import numpy as np
 
@@ -238,7 +241,7 @@ copying any data by just modifying the ``.strides`` of the array::
 Another example: reshaping
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 Modifying the shape of an array through :func:`numpy.reshape` is also
-accomplished without any copying of data by modifying the ``.strides``::
+accomplished without any copying of data by modifying the :attr:`~numpy.ndarray.strides`::
 
   a = np.random.rand(20_000, 10_000)
   print(f'{a.strides=}')  # (80000, 8)
@@ -253,12 +256,12 @@ Exercises 3
 
 .. challenge:: Exercises: Numpy-Advanced-3
 
-    A little known feature of NumPy is the :data:`numpy.stride_tricks` module
-    that allows you to modify the ``.strides`` attribute directly. Playing
+    A little known feature of NumPy is the ``numpy.stride_tricks`` module
+    that allows you to modify the :attr:`~numpy.ndarray.strides` attribute directly. Playing
     around with this is very educational.
 
     1. Create your own ``transpose()`` function that will transpose a 2D matrix
-       by reversing its ``.shape`` and ``.strides`` attributes using
+       by reversing its :attr:`~numpy.ndarray.shape` and :attr:`~numpy.ndarray.strides` attributes using
        :func:`numpy.lib.stride_tricks.as_strided`.
 
     2. Create a (5 ✕ 100 000 000 000) array containing on the first row all
@@ -319,7 +322,7 @@ out in memory row-by-row (see image above). The transpose left the data laid
 out in memory column-by-column. To see why the copying of data was inevitable,
 look at what happens to this smaller (2 ✕ 3) matrix after transposition and
 reshaping. You can verify for yourself there is no way to get the final array
-based on the first array and some clever setting of the ``.strides``::
+based on the first array and some clever setting of the :attr:`~numpy.ndarray.strides`::
 
   a = np.array([[1, 2, 3], [4, 5, 6]])
   
@@ -336,11 +339,11 @@ based on the first array and some clever setting of the ``.strides``::
 Copy versus view
 ----------------
 
-Whenever NumPy constructs a new array by modifying the ``.strides`` instead of
+Whenever NumPy constructs a new array by modifying the :attr:`~numpy.ndarray.strides` instead of
 copying data, we way it created a "view". This also happens when we select only
 a portion of an existing matrix. Whenever a view is created, the
 :class:`numpy.ndarray` object will have a reference to the original array in
-its ``.base`` attribute::
+its :attr:`~numpy.ndarray.base` attribute::
 
   a = np.zeros((5, 5))
   print(a.base)  # None
@@ -357,7 +360,7 @@ it has been derived from::
   print(a.__array_interface__['data'])
   print(b.__array_interface__['data'])
 
-Views are created by virtue of modifying the value of the `.shape` attribute
+Views are created by virtue of modifying the value of the :attr:`~numpy.ndarray.shape` attribute
 and, if necessary, apply an offset to the pointer into the memory buffer so it
 no longer points to the start of the buffer, but somewhere in the middle::