API Overview ============ .. toctree:: :hidden: api_changes .. contents:: :local: See also the :doc:`api_changes`. Usage patterns -------------- Below we describe several common approaches to plotting with Matplotlib. The pyplot API ^^^^^^^^^^^^^^ `matplotlib.pyplot` is a collection of command style functions that make Matplotlib work like MATLAB. Each pyplot function makes some change to a figure: e.g., creates a figure, creates a plotting area in a figure, plots some lines in a plotting area, decorates the plot with labels, etc. `.pyplot` is mainly intended for interactive plots and simple cases of programmatic plot generation. Further reading: - The `matplotlib.pyplot` function reference - :doc:`/tutorials/introductory/pyplot` - :ref:`Pyplot examples ` .. _api-index: The object-oriented API ^^^^^^^^^^^^^^^^^^^^^^^ At its core, Matplotlib is object-oriented. We recommend directly working with the objects, if you need more control and customization of your plots. In many cases you will create a `.Figure` and one or more `~matplotlib.axes.Axes` using `.pyplot.subplots` and from then on only work on these objects. However, it's also possible to create `.Figure`\ s explicitly (e.g. when including them in GUI applications). Further reading: - `matplotlib.axes.Axes` and `matplotlib.figure.Figure` for an overview of plotting functions. - Most of the :ref:`examples ` use the object-oriented approach (except for the pyplot section) The pylab API (disapproved) ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. warning:: Since heavily importing into the global namespace may result in unexpected behavior, the use of pylab is strongly discouraged. Use `matplotlib.pyplot` instead. `pylab` is a module that includes `matplotlib.pyplot`, `numpy` and some additional functions within a single namespace. Its original purpose was to mimic a MATLAB-like way of working by importing all functions into the global namespace. This is considered bad style nowadays. Modules ------- Matplotlib consists of the following submodules: .. toctree:: :maxdepth: 1 matplotlib_configuration_api.rst afm_api.rst animation_api.rst artist_api.rst axes_api.rst axis_api.rst backend_bases_api.rst backend_managers_api.rst backend_tools_api.rst index_backend_api.rst blocking_input_api.rst category_api.rst cbook_api.rst cm_api.rst collections_api.rst colorbar_api.rst colors_api.rst container_api.rst contour_api.rst dates_api.rst dviread.rst figure_api.rst font_manager_api.rst fontconfig_pattern_api.rst gridspec_api.rst image_api.rst legend_api.rst legend_handler_api.rst lines_api.rst markers_api.rst mathtext_api.rst mlab_api.rst offsetbox_api.rst patches_api.rst path_api.rst patheffects_api.rst pyplot_summary.rst projections_api.rst quiver_api.rst rcsetup_api.rst sankey_api.rst scale_api.rst sphinxext_plot_directive_api.rst spines_api.rst style_api.rst table_api.rst testing_api.rst text_api.rst textpath_api.rst ticker_api.rst tight_layout_api.rst transformations.rst tri_api.rst type1font.rst units_api.rst widgets_api.rst Toolkits -------- :ref:`toolkits-index` are collections of application-specific functions that extend Matplotlib. The following toolkits are included: .. toctree:: :maxdepth: 1 toolkits/index.rst toolkits/mplot3d.rst toolkits/axes_grid1.rst toolkits/axisartist.rst toolkits/axes_grid.rst