diff --git a/doc/devel/index.rst b/doc/devel/index.rst index 446283bc0f22..f6c315d11d04 100644 --- a/doc/devel/index.rst +++ b/doc/devel/index.rst @@ -36,6 +36,8 @@ process or how to fix something feel free to ask on `gitter development_setup.rst testing.rst documenting_mpl.rst + style_guide.rst + add_new_projection.rst gitwash/index.rst coding_guide.rst release_guide.rst diff --git a/doc/devel/style_guide.rst b/doc/devel/style_guide.rst new file mode 100644 index 000000000000..957cd76ed685 --- /dev/null +++ b/doc/devel/style_guide.rst @@ -0,0 +1,374 @@ + +========================= +Documentation Style Guide +========================= + +This guide contains best practices for the language and formatting of Matplotlib +documentation. + +.. seealso:: + + For more information about contributing, see the :ref:`documenting-matplotlib` + section. + +Expository language +=================== + +For explanatory writing, the following guidelines are for clear and concise +language use. + +Terminology +----------- + +There are several key terms in Matplotlib that are standards for +reliability and consistency in documentation. They are not interchangeable. + ++------------------+--------------------------+--------------+--------------+ +| Term | Description | Correct | Incorrect | ++==================+==========================+==============+==============+ +| Figure_ | Matplotlib working space | - *For | - "The figure| +| | for programming. | Matplotlib | is the | +| | | objects*: | working | +| | | Figure, | space for | +| | | "The Figure| visuals." | +| | | is the | - "Methods in| +| | | working | the figure | +| | | space for | provide the| +| | | the visual.| visuals." | +| | | - *Referring | - "The | +| | | to class*: | Figure_ | +| | | Figure_ , | Four | +| | | "Methods | leglock is | +| | | within the | a wrestling| +| | | Figure_ | move." | +| | | provide the| | +| | | visuals." | | +| | | - *General | | +| | | language*: | | +| | | figure, | | +| | | "Michelle | | +| | | Kwan is a | | +| | | famous | | +| | | figure | | +| | | skater." | | ++------------------+--------------------------+--------------+--------------+ +| Axes_ | Subplots within Figure. | - *For | - "The axes | +| | Contains plot elements | Matplotlib | methods | +| | and is responsible for | objects*: | transform | +| | plotting and configuring | Axes, "An | the data." | +| | additional details. | Axes is a | - "Each Axes_| +| | | subplot | is specific| +| | | within the | to a | +| | | Figure." | Figure." | +| | | - *Referring | - "The | +| | | to class*: | musicians | +| | | Axes_ , | on stage | +| | | "Each Axes_| call their | +| | | is specific| guitars | +| | | to one | Axes." | +| | | Figure." | - "The point | +| | | - *General | where the | +| | | language*: | Axes meet | +| | | axes, "Both| is the | +| | | loggers and| origin of | +| | | lumberjacks| the | +| | | use axes to| coordinate | +| | | chop wood."| system." | +| | | OR "There | | +| | | are no | | +| | | standard | | +| | | names for | | +| | | the | | +| | | coordinates| | +| | | in the | | +| | | three | | +| | | axes." | | +| | | (Plural of | | +| | | axis) | | ++------------------+--------------------------+--------------+--------------+ +| Artist_ | Broad variety of | - *For | - "Configure | +| | Matplotlib objects that | Matplotlib | the legend | +| | display visuals. | objects*: | artist with| +| | | Artist, | its | +| | | "Artists | respective | +| | | display | method." | +| | | visuals and| - "There is | +| | | are the | an Artist_ | +| | | visible | for that | +| | | elements | visual in | +| | | when the | the graph."| +| | | rendering | - "Some | +| | | a Figure." | Artists | +| | | - *Referring | became | +| | | to class*: | famous only| +| | | Artist_ , | by | +| | | "Each | accident." | +| | | Artist_ has| | +| | | respective | | +| | | methods and| | +| | | functions."| | +| | | - *General | | +| | | language*: | | +| | | artist, | | +| | | "The | | +| | | artist in | | +| | | the museum | | +| | | is from | | +| | | France." | | ++------------------+--------------------------+--------------+--------------+ +| Axis_ | Human-readable single | - *For | - "Plot the | +| | dimensional object | Matplotlib | graph onto | +| | of reference marks | objects*: | the axis." | +| | containing ticks, tick | Axis, "The | - "Each Axis | +| | labels, spines, and | Axis for | is usually | +| | edges. | the bar | named after| +| | | chart is a | the | +| | | separate | coordinate | +| | | Artist." | which is | +| | | (plural, | measured | +| | | Axis | along it." | +| | | objects) | - "In some | +| | | - *Referring | computer | +| | | to class*: | graphics | +| | | Axis_ , | contexts, | +| | | "The Axis_ | the | +| | | contains | ordinate | +| | | respective | Axis_ may | +| | | XAxis and | be oriented| +| | | YAxis | downwards."| +| | | objects." | | +| | | - *General | | +| | | language*: | | +| | | axis, | | +| | | "Rotation | | +| | | around a | | +| | | fixed axis | | +| | | is a | | +| | | special | | +| | | case of | | +| | | rotational | | +| | | motion." | | ++------------------+--------------------------+--------------+--------------+ +| Explicit, | Explicit approach of | - Explicit | - object | +| Object Oriented | programing in Matplotlib.| - explicit | oriented | +| Programming (OOP)| | - OOP | - OO-style | ++------------------+--------------------------+--------------+--------------+ +| Implicit, | Implicit approach of | - Implicit | - MATLAB like| +| ``pyplot`` | programming in Matplotlib| - implicit | - Pyplot | +| | with ``pyplot`` module. | - ``pyplot`` | - pyplot | +| | | | interface | ++------------------+--------------------------+--------------+--------------+ + +.. _Figure: :class:`~matplotlib.figure.Figure` +.. _Axes: :class:`~matplotlib.axes.Axes` +.. _Artist: :class:`~matplotlib.artist.Artist` +.. _Axis: :class:`matplotlib.axis.Axis` + + +Grammar +------- + +Subject +^^^^^^^ +Use second-person imperative sentences for directed instructions specifying an +action. Second-person pronouns are for individual-specific contexts and +possessive reference. + ++------------------------------------+------------------------------------+ +| Correct | Incorrect | ++====================================+====================================+ +| Install Matplotlib from the source | You can install Matplotlib from the| +| directory using the Python ``pip`` | source directory. You can find | +| installer program. Depending on | additional support if you are | +| your operating system, you may need| having trouble with your | +| additional support. | installation. | ++------------------------------------+------------------------------------+ + +Tense +^^^^^ +Use present simple tense for explanations. Avoid future tense and other modal +or auxiliary verbs when possible. + ++------------------------------------+------------------------------------+ +| Correct | Incorrect | ++====================================+====================================+ +| The fundamental ideas behind | Matplotlib will take data and | +| Matplotlib for visualization | transform it through functions and | +| involve taking data and | methods. They can generate many | +| transforming it through functions | kinds of visuals. These will be the| +| and methods. | fundamentals for using Matplotlib. | ++------------------------------------+------------------------------------+ + +Voice +^^^^^ +Write in active sentences. Passive voice is best for situations or conditions +related to warning prompts. + ++------------------------------------+------------------------------------+ +| Correct | Incorrect | ++====================================+====================================+ +| The function ``plot`` generates the| The graph is generated by the | +| graph. | ``plot`` function. | ++------------------------------------+------------------------------------+ +| An error message is returned by the| You will see an error message from | +| function if there are no arguments.| the function if there are no | +| | arguments. | ++------------------------------------+------------------------------------+ + +Sentence structure +^^^^^^^^^^^^^^^^^^ +Write with short sentences using Subject-Verb-Object order regularly. Limit +coordinating conjunctions in sentences. Avoid pronoun references and +subordinating conjunctive phrases. + ++------------------------------------+------------------------------------+ +| Correct | Incorrect | ++====================================+====================================+ +| The ``pyplot`` module in Matplotlib| The ``pyplot`` module in Matplotlib| +| is a collection of functions. These| is a collection of functions which | +| functions create, manage, and | create, manage, and manipulate the | +| manipulate the current Figure and | current Figure and plotting area. | +| plotting area. | | ++------------------------------------+------------------------------------+ +| The ``plot`` function plots data | The ``plot`` function plots data | +| to the respective Axes. The Axes | within its respective Axes for its | +| corresponds to the respective | respective Figure. | +| Figure. | | ++------------------------------------+------------------------------------+ +| The implicit approach is a | Users that wish to have convenient | +| convenient shortcut for | shortcuts for generating plots use | +| generating simple plots. | the implicit approach. | ++------------------------------------+------------------------------------+ + + +Formatting +========== + +The following guidelines specify how to incorporate code and use appropriate +formatting for Matplotlib documentation. + +Code +---- + +Matplotlib is a Python library and follows the same standards for +documentation. + +Comments +^^^^^^^^ +Examples of Python code have comments before or on the same line. + ++---------------------------------------+---------------------------------+ +| Correct | Incorrect | ++=======================================+=================================+ +| :: | :: | +| | | +| # Data | years = [2006, 2007, 2008] | +| years = [2006, 2007, 2008] | # Data | ++---------------------------------------+ | +| :: | | +| | | +| years = [2006, 2007, 2008] # Data | | ++---------------------------------------+---------------------------------+ + +Outputs +^^^^^^^ +When generating visuals with Matplotlib using ``.py`` files in examples, +display the visual with `matplotlib.pyplot.show` to display the visual. +Keep the documentation clear of Python output lines. + ++------------------------------------+------------------------------------+ +| Correct | Incorrect | ++====================================+====================================+ +| :: | :: | +| | | +| plt.plot([1, 2, 3], [1, 2, 3]) | plt.plot([1, 2, 3], [1, 2, 3]) | +| plt.show() | | ++------------------------------------+------------------------------------+ +| :: | :: | +| | | +| fig, ax = plt.subplots() | fig, ax = plt.subplots() | +| ax.plot([1, 2, 3], [1, 2, 3]) | ax.plot([1, 2, 3], [1, 2, 3]) | +| fig.show() | | ++------------------------------------+------------------------------------+ + +reStructuredText +---------------- + +Matplotlib uses reStructuredText Markup for documentation. Sphinx helps to +transform these documents into appropriate formats for accessibility and +visibility. + +- `reStructuredText Specifications `_ +- `Quick Reference Document `_ + + +Lists +^^^^^ +Bulleted lists are for items that do not require sequencing. Numbered lists are +exclusively for performing actions in a determined order. + ++------------------------------------+------------------------------------+ +| Correct | Incorrect | ++====================================+====================================+ +| The example uses three graphs. | The example uses three graphs. | ++------------------------------------+------------------------------------+ +| - Bar | 1. Bar | +| - Line | 2. Line | +| - Pie | 3. Pie | ++------------------------------------+------------------------------------+ +| These four steps help to get | The following steps are important | +| started using Matplotlib. | to get started using Matplotlib. | ++------------------------------------+------------------------------------+ +| 1. Import the Matplotlib library. | - Import the Matplotlib library. | +| 2. Import the necessary modules. | - Import the necessary modules. | +| 3. Set and assign data to work on.| - Set and assign data to work on. | +| 4. Transform data with methods and| - Transform data with methods and | +| functions. | functions. | ++------------------------------------+------------------------------------+ + +Tables +^^^^^^ +Use ASCII tables with reStructuredText standards in organizing content. +Markdown tables and the csv-table directive are not accepted. + ++--------------------------------+----------------------------------------+ +| Correct | Incorrect | ++================================+========================================+ +| +----------+----------+ | :: | +| | Correct | Incorrect| | | +| +==========+==========+ | | Correct | Incorrect | | +| | OK | Not OK | | | ------- | --------- | | +| +----------+----------+ | | OK | Not OK | | +| | | ++--------------------------------+----------------------------------------+ +| :: | :: | +| | | +| +----------+----------+ | .. csv-table:: | +| | Correct | Incorrect| | :header: "correct", "incorrect" | +| +==========+==========+ | :widths: 10, 10 | +| | OK | Not OK | | | +| +----------+----------+ | "OK ", "Not OK" | +| | | ++--------------------------------+ | +| :: | | +| | | +| =========== =========== | | +| Correct Incorrect | | +| =========== =========== | | +| OK Not OK | | +| =========== =========== | | +| | | ++--------------------------------+----------------------------------------+ + + +Additional resources +==================== +This style guide is not a comprehensive standard. For a more thorough +reference of how to contribute to documentation, see the links below. These +resources contain common best practices for writing documentation. + +* `Python Developer's Guide `_ +* `Google Developer Style Guide `_ +* `IBM Style Guide `_ +* `Red Hat Style Guide `_ + diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py new file mode 100644 index 000000000000..da9b73096c1f --- /dev/null +++ b/tutorials/introductory/getting_started.py @@ -0,0 +1,851 @@ +""" + +.. _getting_started: + +*************** +Getting Started +*************** + +This tutorial covers basic usage patterns and best practices to help get +started using Matplotlib. +""" + +############################################################################## +# +# Introduction +# ============ +# +# Matplotlib is a Python library providing tools for users to create +# visualizations with data. +# +# The library is accessible through a variety of operating systems and +# programming environments. The fundamental ideas behind Matplotlib for +# visualizations involve taking data and transforming it through functions and +# methods. This process occurs internally and is not user-facing. +# +# There are two main ways of producing graphs with Matplotlib, explicit and +# implicit. Explicit code, using Object Oriented Programming (OOP), and +# implicit code, using ``pyplot``, are the foundation for creating and +# manipulating data into visualizations. +# +# +------------------------------------+------------------------------------+ +# | Explicit, Object Oriented | Implicit, ``pyplot`` | +# | Programming (OOP) | | +# +====================================+====================================+ +# | Users explicitly create and manage | The Matplotlib library implicitly | +# | all plot elements. | manages Figure and Axes. | +# +------------------------------------+------------------------------------+ +# | Useful for repeated code use, | Helpful for quickly graphing data | +# | generalization, robust | when using interactive | +# | configurations of visuals. | environments. | +# +------------------------------------+------------------------------------+ +# | Recommended to new users for | Most useful for users coming from | +# | learning fundamentals. | MATLAB. Users already familiar with| +# | | Matplotlib also benefit from using | +# | | ``pyplot`` for convenient | +# | | shortcuts. | +# +------------------------------------+------------------------------------+ +# +# Explicit programming helps users generalize code and is useful for repeated +# uses or larger projects. This is also a more robust way of controlling +# customizations for visualizations. Users looking to have control over every +# part of the graph call methods on each item. Most users benefit using +# explicit programming for regular Matplotlib use as the user manages each +# element of building a graph. +# +# Implicit programming with ``pyplot`` is simpler. It is helpful for basic +# plots and for interactive environments, such as Jupyter Notebooks. Users +# familiar with MATLAB or wishing to have Matplotlib create and manage parts of +# the visualization in state-based programming benefit from using ``pyplot``. +# Using implicit programming acts as a convenient shortcut for generating +# visualizations. New users to Matplotlib may experience difficulty +# understanding how elements of a visualization work together when using the +# implicit approach. +# +# Examples +# -------- +# +# The table below depicts the two alternative approaches to plotting a +# simple graph. The image following the table is the visualization of the +# programming. +# +# +------------------------------------+------------------------------------+ +# | Explicit, Object Oriented | Implicit, ``pyplot`` | +# | Programming (OOP) | | +# +====================================+====================================+ +# | :: | :: | +# | | | +# | fig, ax = plt.subplots() | plt.plot([1, 2, 3], [1, 2, 3]) | +# | ax.plot([1, 2, 3], [1, 2, 3]) | | +# | | | +# +------------------------------------+------------------------------------+ +# | `.pyplot.subplots` generates a | :mod:`matplotlib.pyplot` creates | +# | `~.figure.Figure` and one or | implicit Figure and Axes if | +# | more `~.axes.Axes` explicitly. | there are no pre-existing | +# | `.Axes.plot` plots the data. | elements and `.pyplot.plot` plots | +# | | the data. This also plots over any | +# | | existing Figure if applicable. | +# +------------------------------------+------------------------------------+ +# | .. plot:: | .. plot:: | +# | | | +# | fig, ax = plt.subplots() | plt.plot([1, 2, 3], [1, 2, 3]) | +# | ax.plot([1, 2, 3], [1, 2, 3]) | | +# | | | +# +------------------------------------+------------------------------------+ +# +# .. note:: +# +# The example graphs are identical for both explicit and implicit code. +# +# Requirements +# ============ +# +# Matplotlib is a Python library and an installed version of *Python 3.6 or +# higher* is required. Depending on your operating system, Python may already +# be installed on your machine. +# +# Installing Matplotlib is required in order to generate graphs with the +# library. Install Matplotlib for your own development environment manually or +# use a third-party package distribution. +# +# The `Installation Guide `_ +# page contains more information about install methods and resources for +# third-party package distributions. +# +# .. seealso:: +# +# To contribute to the Matplotlib community, check +# :ref:`developers-guide-index` +# for details about working with the latest sources. +# +# Interactive environments +# ------------------------ +# +# The Matplotlib community suggests using `IPython `_ +# through `Jupyter `_ as the primary +# interactive environment. +# +# Plotting +# ======== +# +# The common convention for preparing to plot data involves importing the +# Matplotlib library module ``pyplot`` with the abbreviation ``plt`` for +# convenience. Both explicit and implicit programming require the module. +# +# The other library imports are for support. Explanations on their purposes +# are included below. + +import matplotlib.pyplot as plt + +############################################################################## +# +# - The ``pyplot`` module in Matplotlib is a collection of functions. The +# module's functions create, manage, and manipulate the current Figure and +# the plotting area. The ``plt`` abbreviation is the standard shortcut. +# + +import numpy as np + +from functools import partial + +############################################################################## +# +# - `NumPy `_ is a common scientific +# Python library that benefits users working with numerical data. +# - The ``functools`` module helps manage functions that act on or return +# other functions. The `Pie Chart Examples`_ section note contains more +# information about the purpose of this module. +# +# +# +# Two Approaches for Creating Graphs +# ---------------------------------- +# +# The two strategies, explicit and implicit, both involve using the ``pyplot`` +# module. However, they differ in how users interact with the data in the +# transformation process. The `Introduction`_ and `Examples`_ sections above +# provide key differences. +# +# +------------------------------------+------------------------------------+ +# | Explicit | Implicit | +# +====================================+====================================+ +# | - Code has explicit references to | - The programming is designed to | +# | objects. Users manage objects for| remember preceding events or | +# | the specific Figure and Axes and | interactions. This preserved | +# | call on methods for manipulating | state allows Matplotlib to | +# | data. | automatically manage a Figure and| +# | - Object Oriented Programming | Axes. | +# | allows for robust control and is | - The module ``pyplot`` operates | +# | useful for generalized code. | similarly to MATLAB and is | +# | | convenient for interactive | +# | | environments. | +# +------------------------------------+------------------------------------+ +# +# .. note:: +# +# The Matplotlib community does not recommend interchanging explicit and +# implicit strategies. When using one as standard, all code following +# the same strategy reduces troubleshooting issues. Switching back and +# forth between explicit and implicit programming may yield errors. +# +# For other techniques of creating plots with Matplotlib, refer to +# :ref:`user_interfaces`. +# +# Data +# ---- +# +# The Matplotlib library manages data in the form of iterables and/or +# sequenced items. These also take the form of NumPy arrays like +# `numpy.array` or `numpy.ma.masked_array`. All plotting functions take these +# data structures. +# + +# Sample Data for Personal Financial Tracking in 2009 & 2010 + +months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', + 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'] +income = [950, 950, 950, 950, 950, 950, + 950, 950, 950, 950, 950, 950] +chk_acct_09 = [1250, 1325, 1200, 1220, 1100, 1055, + 1255, 1090, 1190, 1205, 1205, 1180] +svg_acct_09 = [1000, 1050, 1100, 1150, 1200, 1250, + 1300, 1350, 1400, 1450, 1500, 1550] +chk_acct_10 = [1180, 1270, 1280, 1280, 1260, 1140, + 1270, 1160, 1120, 1250, 1270, 1160] +svg_acct_10 = [1550, 1600, 1650, 1700, 1750, 1800, + 1850, 1900, 1950, 2000, 2050, 2100] + +############################################################################## +# +# .. note:: +# +# Other containers, such as data objects from various libraries, may not +# work as intended. +# +# Explicit and implicit examples of a basic line plot are below. Both of the +# following plots are identical. Each uses a different approach to graph the +# data. The results do not change for either approach when using the same data +# points. +# +# Explicit: Object Oriented Programming (OOP) +# -------------------------------------------- +# +# Explicit programming for Matplotlib involves calling the function +# `matplotlib.pyplot.subplots` in the ``pyplot`` module once. This returns a +# group of an explicit Figure and Axes to be unpacked as part of variable +# assignment. More than one Axes is configurable; however, each Axes only +# corresponds to a single Figure. +# +# Each Axes has its own methods to graph data. In addition, each Axes +# also uses separate methods to create and manage objects within a Figure. +# These methods are different from those of the implicit programming approach. + +# Explicit programming with OOP + +# Assigning sample data to variables. +x = months +y1 = income +y2 = chk_acct_09 +y3 = svg_acct_09 +y4 = chk_acct_10 +y5 = svg_acct_10 + +# Explicit Figure & Axes unpacked separately with module. +# Conventional object abbreviations are `fig` and `ax`, respectively. +fig, ax = plt.subplots() + +# Single explicit Axes graphs multiple data points. +ax.plot(x, y1, label='Income') +ax.plot(x, y2, label='Checking Account') +ax.plot(x, y3, label='Savings Account') + +# Explicit Axes use separate methods to manage parts of Figure. +ax.set_xlabel('Month') +ax.set_ylabel('USD') +ax.set_title('Personal Financial Tracking from 2009') +ax.legend() + +# The pyplot module displays the Figure. +plt.show() + +############################################################################## +# +# The module ``pyplot`` for the explicit example uses a function that returns +# the Figure and Axes. This convention uses ``plt.subplots()``. It defaults +# to one Figure, ``fig``, and one Axes, ``ax``. The variable names are common +# shorthand terms and any naming conventions also work. +# +# The `Configuration`_ section below contains additional information about +# manipulating visuals, multiple visualizations, and other modifications. +# +# Using explicit programming allows for ``fig`` and ``ax`` to use separate +# methods to manage objects within the visualization. Specific Figures and +# Axes manage data components with their own respective methods. +# +# +# Implicit: ``pyplot`` +# -------------------- +# +# Implicit programming for Matplotlib centers around using the ``pyplot`` +# module. The module implicitly generates the Figure and Axes. Methods and +# functions within the module take incoming data as arguments. Additional parts +# of the Figure are also available through the module methods. + +# Implicit programming with pyplot + +# Previous variables are still referenced. + +# Module plots multiple data points on implicitly generated Axes. +plt.plot(x, y1, label='Income') +plt.plot(x, y2, label='Checking Account') +plt.plot(x, y3, label='Savings Account') + +# Module methods generate parts of Figure. +plt.xlabel('Month') +plt.ylabel('USD') +plt.title("Personal Financial Tracking from 2009") +plt.legend() + +# The module displays the Figure. +plt.show() + +############################################################################## +# +# In the example above, the ``pyplot`` module contains its own functions of +# actionable tasks for the data. The ``plt.plot`` plots data as a line graph +# with various keyword arguments as customizable options. The module also +# includes other methods for generating parts of the visualization. These parts +# use different methods from the explicit approach. +# +# .. note:: +# +# The names and spelling for methods may be similar for both explicit and +# implicit approaches. Errors may occur when using the wrong corresponding +# method. Confirm with the documentation API of `~.axes.Axes` for explicit +# and :mod:`matplotlib.pyplot` for implicit or other respective method +# names. +# +# Configuration +# ============= +# +# There are two main parts to building a visualization with Matplotlib, the +# ``Figure`` and the ``Axes``. +# +# Components of Matplotlib Figure +# ------------------------------- +# +# The image below depicts each visible element of a Matplotlib graph. The +# graphic uses Matplotlib to display and highlight each individual part of the +# visualization. To view source code for the image, see +# :ref:`sphx_glr_gallery_showcase_anatomy.py`. +# +# +# .. image:: ../../_static/anatomy.png +# +# +# .. note:: +# +# ``Figure`` and ``Axes`` identify empty regions of the diagram; +# however, these elements are foundational in operation. The example below +# illustrates an empty Figure and respective Axes. Matplotlib also +# automatically generates certain Artists for the visualization even +# without assigned data. +# + +# Explicit Figure and Axes unpacked from module function. +# No data transformed for visualizations. +fig, ax = plt.subplots() + +# Module displays empty Figure and Axes. +plt.show() + +############################################################################## +# +# :class:`~matplotlib.figure.Figure` +# +# The Figure is the working space for the programming. All visible +# objects on a graph are located within the Figure. +# +# :class:`~matplotlib.axes.Axes` +# +# Axes are subplots within the Figure. They contain Matplotlib objects and +# are responsible for plotting and configuring additional details. Each +# Figure can contain multiple Axes, but each Axes is specific to one +# Figure. +# +# In a Figure, each Axes contains any number of plot elements. Axes are +# configurable for more than one type of visualization of data. From the +# `Plotting`_ section above, the Axes in both explicit and implicit strategies +# contain multiple types of visualizations of data on a single Axes. +# +# Each of these types are specific to the Axes they are in. In the example, the +# two plots each have one Axes. These Axes each have multiple plot lines. The +# lines as objects are not shared between the two plots even though the data is +# shared. +# +# Matplotlib Axes also integrate with other Python libraries. In Axes-based +# interfaces, other libraries take an Axes object as input. Libraries such as +# `pandas` and `Seaborn `_ act on specific Axes. +# +# Other Components +# ^^^^^^^^^^^^^^^^ +# +# :class:`~matplotlib.artist.Artist` +# +# Artists are a broad variety of Matplotlib objects. They display visuals and +# are the visible elements when the Figure is rendered. They correspond to a +# specific Axes and cannot be shared or transferred. In Matplotlib programming, +# all objects for display are Artists. +# +# .. note:: +# +# Axes and Axis are not synonymous. Axis refers to +# :class:`~matplotlib.axis.Axis`, a separate Matplotlib object. +# +# Manipulating Artists +# -------------------- +# +# With simple plots, Matplotlib automatically generates the basic plot elements +# of a graph. For more control over the visual, use Artists and methods. +# +# Matplotlib generates additional visual elements as Artists in the form of +# objects. As Artists, each has respective methods and functions. Explicit and +# implicit approaches use different methods and are not interchangeable. +# +# +-----------------------+--------------------------+------------------------+ +# | Artist | Explicit | Implicit | +# +=======================+==========================+========================+ +# | Visible elements from | Each specific Axes has | The ``pyplot`` module | +# | rendered Figure. | its own method for | manages Artists based | +# | | Artists. | on most recent Figure | +# | | | or Axes. | +# +-----------------------+--------------------------+------------------------+ +# +# The table below compares common formatter Artists and their different +# methods. These Artists label and identify parts of a visualization. +# +# The term ``ax`` refers to an assigned variable for a specific Axes. Using +# explicit programming may require additional tasks of setting objects prior +# to assigning labels. Whereas with implicit programming, the module manages +# those tasks without specification. +# +# +-----------------------+--------------------------+------------------------+ +# | Artist | Explicit | Implicit | +# +=======================+==========================+========================+ +# | X-Axis labels | ``ax.set_xticks()`` | ``plt.xticks()`` | +# | | ``ax.set_xticklabels()`` | | +# +-----------------------+--------------------------+------------------------+ +# | Y-Axis labels | ``ax.set_yticks()`` | ``plt.yticks()`` | +# | | ``ax.set_yticklabels()`` | | +# +-----------------------+--------------------------+------------------------+ +# | Title (Axes) | ``ax.set_title()`` | ``plt.title()`` | +# +-----------------------+--------------------------+------------------------+ +# +# The following table represents common Artists for transforming data. The +# Artists in this table generate data visualizations from transformations. +# These methods often overlap in naming conventions and make use of identical +# keyword arguments and other parameters. +# +# +-----------------------+--------------------------+------------------------+ +# | Artist | Explicit | Implicit | +# +=======================+==========================+========================+ +# | Plot | ``ax.plot()`` | ``plt.plot()`` | +# +-----------------------+--------------------------+------------------------+ +# | Pie | ``ax.pie()`` | ``plt.pie()`` | +# +-----------------------+--------------------------+------------------------+ +# | Legend (Axes) | ``ax.legend()`` | ``plt.legend()`` | +# +-----------------------+--------------------------+------------------------+ +# +# Supplemental Resources +# ^^^^^^^^^^^^^^^^^^^^^^ +# +# Customizations with robust options have their own guides and tutorials. The +# topics below include common in-depth documents for additional support. +# +# +------------------------------+--------------------------------------------+ +# | Topic | Tutorial | +# +==============================+============================================+ +# | :ref:`tutorials-introductory`| :doc:`/tutorials/introductory/customizing` | +# +------------------------------+--------------------------------------------+ +# | :ref:`tutorials-intermediate`| :doc:`/tutorials/intermediate/legend_guide`| +# +------------------------------+--------------------------------------------+ +# | :ref:`tutorials-colors` | :doc:`/tutorials/colors/colors` | +# | +--------------------------------------------+ +# | | :doc:`/tutorials/colors/colormaps` | +# +------------------------------+--------------------------------------------+ +# | :ref:`tutorials-text` | :doc:`/tutorials/text/text_intro` | +# | +--------------------------------------------+ +# | | :doc:`/tutorials/text/text_props` | +# | +--------------------------------------------+ +# | | :doc:`/tutorials/text/annotations` | +# +------------------------------+--------------------------------------------+ +# +# For complete information about available methods for creating new Artists, +# refer to the table below. +# +# +------------------------------------+------------------------------------+ +# | Explicit | Implicit | +# +====================================+====================================+ +# | :class:`matplotlib.axes.Axes` | :mod:`matplotlib.pyplot` | +# +------------------------------------+------------------------------------+ +# +# +# Pie Chart Examples +# ------------------ +# +# Matplotlib pie charts create wedges based on data. They manipulate the size +# of the Artists based on the ratio of the wedge to the sum of the data. The +# ``.pie()`` method is similar in both explicit and implicit approaches. +# +# The code below illustrates various levels of configuration in keyword +# arguments as well as Artist methods for both explicit and implicit +# programming. +# + +# Sample data for monthly spending averages. + +# Data points correspond to wedge size as a ratio of total sum. +# Matplotlib methods calculate these values automatically based on input. +budget = [475, 300, 125, 50] + +# Lists of strings contribute to labeling corresponding data. +descriptions = ['Shared house\nin Philadelphia', + 'Dog costs, phone,\nutilities', + 'Groceries\n& takeout', + 'Treasury bonds'] +categories = ['Rent', 'Bills', 'Food', 'Savings'] + +# Hex color codes determine respective wedge color. +colors = ['#1f77b4', '#ff7f0e', '#d62728', '#2ca02c'] + +# List of floats represents percentage of radius to separate from center. +explode = [0, 0.1, 0.15, 0.35] + +# This function operates in conjunction with the functools partial function +# for formatting labels in wedges. + + +def autopct_format(percent, group): + """ + Takes percent equivalent and calculates original value from data. + Returns string of value new line above percentage. + + Parameters + ---------- + percent : float + Number as percentage equivalent + group : array + Collection of values + + Returns + ------- + formatted : fstring + Formatted string with symbols, spacing, and line breaks + """ + value = int(percent/100.*np.sum(group)) + formatted = f'${value:<4}\n{percent:1.1f}%' + return formatted + + +############################################################################## +# +# Basic +# ^^^^^ +# +# The following two plots are identical. Both the explicit and implicit +# approaches generate the exact same plot when using the same variables. +# +# Review `matplotlib.axes.Axes.pie` and `matplotlib.pyplot.pie` for more +# information about the APIs for explicit and implicit, respectively. + +# Explicit + +fig, ax = plt.subplots() + +ax.pie(budget, colors=colors, labels=categories) +ax.legend() +ax.set_title('Average Monthly Income Expenses') +ax.axis('equal') # The axis method sets the aspect ratio as equal. + +plt.show() + +############################################################################## +# +# + +# Implicit + +plt.pie(budget, colors=colors, labels=categories) +plt.legend() +plt.title('Average Monthly Income Expenses') +plt.axis('equal') # The pyplot module has identical method for aspect ratio. + +plt.show() + +############################################################################## +# +# .. note:: +# +# There are minor differences in the method names. Overall, each method +# performs the same action through the different approaches. +# +# These pie charts are simple and do not have distinguishing information. +# Keyword arguments and Artists add the ability to implement more ways of +# displaying content. +# +# Additional Customization +# ^^^^^^^^^^^^^^^^^^^^^^^^ +# +# Many methods contain optional keyword arguments for further configuration. +# In the examples for explicit programming below, there are values and +# functions in keyword arguments for formatting the Artists. These changes also +# apply to implicit programming, though with varying method names. +# +# The pie chart below adds configurations with keyword arguments for +# ``explode``, ``autopct``, ``startangle``, and ``shadow``. These keyword +# arguments help to define the display of Artists. + +# Explicit + +fig, ax = plt.subplots() + +# The explode keyword argument uses explode variable data to separate +# respective wedges from center. +# The autopct keyword argument takes formatting strings and functions to +# generate text within each wedge. '%1.1f%%' is the string formatter. +# The startangle keyword argument changes where first wedge spans. Angles start +# at 0 degrees on X-axis and move counterclockwise. +# The shadow keyword argument toggles a shadow on the visual. +ax.pie(budget, + colors=colors, + labels=categories, + explode=explode, + autopct='%1.1f%%', + startangle=-80, + shadow=True) + +ax.legend() +ax.set_title('Average Monthly Income Expenses') +ax.axis('equal') + +plt.show() + +############################################################################## +# +# The following pie chart has additional keyword arguments to further +# customize the visual. Also, the ``legend`` as an Artist has parameters that +# enable more specification for the information displayed. For more, see the +# :doc:`/tutorials/intermediate/legend_guide`. + +# Explicit + +fig, ax = plt.subplots() + +# Descriptions now act as text labels for wedges. This removes redundant +# information from previous pie chart. +# The autopct keyword argument calls a function as well. The functools partial +# function returns a formatted string. See Note below for more. +# The pctdistance keyword argument places autopct Artist at a location using +# float as percentage of radius. +# The labeldistance keyword argument specifies float as percentage of radius to +# place labels. +# The wedgeprops keyword argument also takes dictionaries to pass to Artists. +# The float for width sets wedge size as percentage of radius starting from +# outer edge. +budget_pie = ax.pie(budget, + colors=colors, + labels=descriptions, + explode=explode, + autopct=partial(autopct_format, group=budget), + startangle=45, + pctdistance=0.85, + labeldistance=1.125, + wedgeprops=dict(width=0.3), + shadow=True) + +# The pie() method unpacks into three Artist objects. The Artists wedges, +# texts, and autotexts have their own methods for addtional customization. +wedges, texts, autotexts = budget_pie + +# The unpacked wedges variable serve as handles for legend. +# Info from categories correspond to respective wedge instead of redundant +# labeling from previous pie chart. +# Legend has title keyword argument. +# Keyword argument bbox_to_anchor with loc places legend at specific point. +# Tuple floats are coordinates for Figure as row and column of Axes. +# Keyword argument loc works with bbox_to_anchor to determine part of legend +# for placement. Without bbox_to_anchor, Matplotlib automatically manages +# coordinates in relation to parameters of loc. +ax.legend(wedges, + categories, + title='Categories', + bbox_to_anchor=(0.125, 0.5), + loc='center right') + +ax.set_title('Average Monthly Income Expenses') +ax.axis('equal') + +# The Figure method tight_layout() adjusts spacing between all Artists to +# maximize visiblity on the Figure. This method also contains various +# parameters for configuration. +fig.tight_layout() + +plt.show() + +############################################################################## +# +# .. note:: +# +# The ``partial`` function in functools works as a callable for simplifying +# a function's arguments. In the ``autopct`` keyword argument, only one +# argument is provided, the data acting as a percentage equivalent. The +# ``autopct_format`` function requires two arguments, so ``partial`` takes +# the argument for ``group`` and sets it to ``budget``. This smaller +# signature object then behaves as the same function with one fewer argument. +# For details about the functools module, see +# `functools +# `_. +# +# Multiple Graphs within a Figure +# ------------------------------- +# +# For multiple graphs using a single Figure, explicit and implicit approaches +# use a similar convention for mapping out multiple Axes. Matplotlib manages +# more than one Axes in a two-dimensional matrix. They are arranged by row +# amount and then by column amount. +# +# Implicit coding uses a separate method with a similar name. The method +# ``plt.subplot`` also includes a third argument to represent the specific +# Axes involved. +# +# When looking for more complex solutions to multiple graphs within a Figure, +# use the :class:`matplotlib.gridspec.GridSpec` module to organize the layout. +# +# Explicit +# ^^^^^^^^ + +# Explicit with OOP + +# Figure and two Axes unpacked from matrix as row (1) & column (2). +# Keyword arguments provide additional details of sharing Y-Axis, Figure size +# and layout formatting. +fig, (ax1, ax2) = plt.subplots(1, 2, + sharey='row', + figsize=[8, 4], + constrained_layout=True) + +# Explicit Figure object has separate method for title. +fig.suptitle('Personal Financial Tracking \'09 - \'10') + +# First explicit Axes object plots data with additional keyword arguments. +ax1.plot(x, y1, label='Income') +ax1.plot(x, y2, label='Checking') +ax1.plot(x, y3, color='green', label='Savings') + +# First explicit Axes object uses separate methods for ticks on X-Axis, +# title, and legend. Keyword arguments are for additional configurations. +ax1.set_xticks(months) +ax1.set_xticklabels(months, rotation=270) +ax1.set_title('2009', fontsize='small') +ax1.legend(loc='upper left') + +# Explicit second Axes object plots data similarly to first explicit Axes. +ax2.plot(x, y1, label='Income') +ax2.plot(x, y4, label='Checking') +ax2.plot(x, y5, color='green', label='Savings') + +# Explicit second Axes object has separate methods as well. +ax2.set_xticks(months) +ax2.set_xticklabels(months, rotation=270) +ax2.set_title('2010', fontsize='small') + +# The pyplot module displays Figure. +plt.show() + +############################################################################## +# +# The explicit example above also uses two Axes to graph the data. However, +# the explicit approach refers to an explicitly generated Axes after creating +# both the Figure and Axes. +# +# In the unpacking process, multiple Axes are assigned to a single variable. +# To reference a specific Axes, indexing the location of the respective Axes +# as a matrix through the single variable works as well. +# +# The code below demonstrates indexing multiple Axes:: +# +# fig, ax = plt.subplots(2, 2) +# +# ax[0,0].bar([1, 2, 3], [1, 2, 3]) +# ax[0,1].plot([3, 2, 1], [3, 2, 1]) +# ax[1,0].hist(hist_data) +# ax[1,1].imshow([[1, 2], [2, 1]]) +# +# +# The method `matplotlib.figure.Figure.subplot_mosaic` also generates Axes in +# a layout with contextual names. The link contains more info for using the +# method. +# +# See code example below:: +# +# fig = plt.figure() +# ax_dict = fig.subplot_mosaic([['bar', 'plot'], +# ['hist', 'image']]) +# +# ax_dict['bar'].bar([1, 2, 3], [1, 2, 3]) +# ax_dict['plot'].plot([3, 2, 1], [3, 2, 1]) +# ax_dict['hist'].hist(hist_data) +# ax_dict['image'].imshow([[1, 2], [2, 1]]) +# +# Implicit +# ^^^^^^^^ +# +# There are limitations for customizing the implicit approach without +# referencing specific Axes and Artists within the Figure. For more advanced +# configurations, the explicit approach offers more flexibility and control. +# The Matplotlib community recommends using explicit programming for these +# tasks. +# +# Generalized Function Guidelines +# ------------------------------- +# +# For users that have recurring plots and graphs, the signature function +# similar to the format below serves as a reusable template. + + +def my_plotter(ax, data1, data2, param_dict): + """ + Helper function to make a graph. + + Parameters + ---------- + ax : Axes + Specific Axes to graph data to + data1 : array + X data + data2 : array + Y data + param_dict : dict + Dictionary of keyword arguments passes to method + + Returns + ------- + out : list + List of Artists added + """ + out = ax.plot(data1, data2, **param_dict) + return out + +############################################################################## +# +# +# Additional Resources +# ==================== +# +# - :ref:`tutorials` +# More on detailed guides and specific topics. +# - :ref:`gallery` +# Collection of visualizations and demonstrative examples. +# - `External Resources `_ +# Curated content from other users. +# pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy