1.6. Getting help and finding documentation

Author: Emmanuelle Gouillart

Rather than knowing all functions in NumPy and SciPy, it is important to find rapidly information throughout the documentation and the available help. Here are some ways to get information:

  • In Ipython, help function opens the docstring of the function. Only type the beginning of the function’s name and use tab completion to display the matching functions.

    In [1]: help(np.van<TAB>

    

    In [2]: help(np.vander)

    Help on _ArrayFunctionDispatcher in module numpy:

    

    vander(x, N=None, increasing=False)

        Generate a Vandermonde matrix.

        

        The columns of the output matrix are powers of the input vector. The

        order of the powers is determined by the `increasing` boolean argument.

        Specifically, when `increasing` is False, the `i`-th output column is

        the input vector raised element-wise to the power of ``N - i - 1``. Such

        a matrix with a geometric progression in each row is named for Alexandre-

        Theophile Vandermonde.

        

        Parameters

        ----------

        x : array_like

            1-D input array.

        N : int, optional

            Number of columns in the output.  If `N` is not specified, a square

            array is returned (``N = len(x)``).

        increasing : bool, optional

            Order of the powers of the columns.  If True, the powers increase

            from left to right, if False (the default) they are reversed.

        

            .. versionadded:: 1.9.0

        

        Returns

        -------

        out : ndarray

            Vandermonde matrix.  If `increasing` is False, the first column is

            ``x^(N-1)``, the second ``x^(N-2)`` and so forth. If `increasing` is

            True, the columns are ``x^0, x^1, ..., x^(N-1)``.

        

        See Also

        --------

        polynomial.polynomial.polyvander

        

        Examples

        --------

        >>> x = np.array([1, 2, 3, 5])

        >>> N = 3

        >>> np.vander(x, N)

        array([[ 1,  1,  1],

               [ 4,  2,  1],

               [ 9,  3,  1],

               [25,  5,  1]])

        

        >>> np.column_stack([x**(N-1-i) for i in range(N)])

        array([[ 1,  1,  1],

               [ 4,  2,  1],

               [ 9,  3,  1],

               [25,  5,  1]])

        

        >>> x = np.array([1, 2, 3, 5])

        >>> np.vander(x)

        array([[  1,   1,   1,   1],

               [  8,   4,   2,   1],

               [ 27,   9,   3,   1],

               [125,  25,   5,   1]])

        >>> np.vander(x, increasing=True)

        array([[  1,   1,   1,   1],

               [  1,   2,   4,   8],

               [  1,   3,   9,  27],

               [  1,   5,  25, 125]])

        

        The determinant of a square Vandermonde matrix is the product

        of the differences between the values of the input vector:

        

        >>> np.linalg.det(np.vander(x))

        48.000000000000043 # may vary

        >>> (5-3)*(5-2)*(5-1)*(3-2)*(3-1)*(2-1)

        48

In Ipython it is not possible to open a separated window for help and documentation; however one can always open a second Ipython shell just to display help and docstrings…

  • Numpy’s and Scipy’s documentations can be browsed online on https://scipy.org and https://numpy.org. The search button is quite useful inside the reference documentation of the two packages.

    Tutorials on various topics as well as the complete API with all docstrings are found on this website.

  • Numpy’s and Scipy’s documentation is enriched and updated on a regular basis by users on a wiki https://numpy.org/doc/stable/. As a result, some docstrings are clearer or more detailed on the wiki, and you may want to read directly the documentation on the wiki instead of the official documentation website. Note that anyone can create an account on the wiki and write better documentation; this is an easy way to contribute to an open-source project and improve the tools you are using!

  • The SciPy Cookbook https://scipy-cookbook.readthedocs.io gives recipes on many common problems frequently encountered, such as fitting data points, solving ODE, etc.

  • Matplotlib’s website https://matplotlib.org/ features a very nice gallery with a large number of plots, each of them shows both the source code and the resulting plot. This is very useful for learning by example. More standard documentation is also available.

  • In Ipython, the magical function %psearch search for objects matching patterns. This is useful if, for example, one does not know the exact name of a function.

    In [3]: import numpy as np

  • If everything listed above fails (and Google doesn’t have the answer)… don’t despair! There is a vibrant Scientific Python community. Scientific Python is present on various platform. https://scientific-python.org/community/

    Packages like SciPy and NumPy also have their own channels. Have a look at their respective websites to find out how to engage with users and maintainers.