2.7. Documentation
Open the notebook in Colab

Due to constraints on the length of this book, we cannot possibly introduce every single MXNet function and class (and you probably would not want us to). The API documentation and additional tutorials and examples provide plenty of documentation beyond the book. In this section we provide you with some guidance to exploring the MXNet API.

2.7.1. Finding All the Functions and Classes in a Module

In order to know which functions and classes can be called in a module, we invoke the dir function. For instance, we can query all properties in the np.random module as follows:

from mxnet import np
print(dir(np.random))

['__all__', '__builtins__', '__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__spec__', '_mx_nd_np', 'absolute_import', 'choice', 'multinomial', 'normal', 'rand', 'randint', 'randn', 'shuffle', 'uniform']

Generally, we can ignore functions that start and end with __ (special objects in Python) or functions that start with a single _(usually internal functions). Based on the remaining function or attribute names, we might hazard a guess that this module offers various methods for generating random numbers, including sampling from the uniform distribution (uniform), normal distribution (normal), and multinomial distribution (multinomial).

2.7.2. Finding the Usage of Specific Functions and Classes

For more specific instructions on how to use a given function or class, we can invoke the help function. As an example, let’s explore the usage instructions for ndarray’s ones_like function.

help(np.ones_like)

Help on function ones_like in module mxnet.numpy:

ones_like(a, dtype=None, order='C', ctx=None, out=None)
    Return an array of ones with the same shape and type as a given array.

    Parameters
    ----------
    a : ndarray
        The shape and data-type of a define these same attributes of
        the returned array.
    dtype : data-type, optional
        Overrides the data type of the result.
        Temporarily do not support boolean type.
    order : {'C'}, optional
        Whether to store multidimensional data in C- or Fortran-contiguous
        (row- or column-wise) order in memory. Currently only supports C order.
    ctx: to specify the device, e.g. the i-th GPU.
    out : ndarray or None, optional
        A location into which the result is stored.
        If provided, it must have the same shape and dtype as input ndarray.
        If not provided or None, a freshly-allocated array is returned.

    Returns
    -------
    out : ndarray
        Array of ones with the same shape and type as a.

    See Also
    --------
    empty_like : Return an empty array with shape and type of input.
    zeros_like : Return an array of zeros with shape and type of input.
    full_like : Return a new array with shape of input filled with value.
    ones : Return a new array setting values to one.

    Examples
    --------
    >>> x = np.arange(6)
    >>> x = x.reshape((2, 3))
    >>> x
    array([[0., 1., 2.],
           [3., 4., 5.]])
    >>> np.ones_like(x)
    array([[1., 1., 1.],
           [1., 1., 1.]])
    >>> np.ones_like(x, int)
    array([[1, 1, 1],
           [1, 1, 1]], dtype=int64)
    >>> y = np.arange(3, dtype=float)
    >>> y
    array([0., 1., 2.], dtype=float64)
    >>> np.ones_like(y)
    array([1., 1., 1.], dtype=float64)

From the documentation, we can see that the ones_like function creates a new array with the same shape as the supplied ndarray and sets all the elements to 1. Whenever possible, you should run a quick test to confirm your interpretation:

x = np.array([[0, 0, 0], [2, 2, 2]])
np.ones_like(x)

array([[1., 1., 1.],
       [1., 1., 1.]])

In the Jupyter notebook, we can use ? to display the document in another window. For example, np.random.uniform? will create content that is almost identical to help(np.random.uniform), displaying it in a new browser window. In addition, if we use two question marks, such as np.random.uniform??, the code implementing the function will also be displayed.

2.7.3. API Documentation

For further details on the API details check the MXNet website at http://mxnet.apache.org/. You can find the details under the appropriate headings (also for programming languages other than Python).

2.7.4. Summary

  • The official documentation provides plenty of descriptions and examples that are beyond this book.

  • We can look up documentation for the usage of MXNet API by calling the dir and help functions, or checking the MXNet website.

2.7.5. Exercises

  1. Look up ones_like and autograd on the MXNet website.

  2. What are all the possible outputs after running np.random.choice(4, 2)?

  3. Can you rewrite np.random.choice(4, 2) by using the np.random.randint function?

2.7.6. Discussions

image0