From eb0a00ada29a327e57686d1ece801954ac57502f Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Mon, 16 Nov 2020 13:16:51 -0800 Subject: [PATCH 01/25] Initial draft of getting_started.py --- tutorials/introductory/getting_started.py | 317 ++++++++++++++++++++++ 1 file changed, 317 insertions(+) create mode 100644 tutorials/introductory/getting_started.py diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py new file mode 100644 index 000000000000..04e008bb9a66 --- /dev/null +++ b/tutorials/introductory/getting_started.py @@ -0,0 +1,317 @@ +""" +*************** +Getting Started +*************** + +This tutorial covers some basic usage patterns and best-practices to +help you get started with 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 on the backend and is not user-facing. For more +# information regarding manipulating backend capabilities, see """ref""". +# +# There are two main ways of producing graphs with Matplotlib, explicit and +# implicit. Explicit code, using Object Oriented Programmiong (OOP), and +# implicit code, using `pyplot`, are the foundation for creating and +# manipulating data into visualizations. +# +# Explicit programming, OOP, 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 can call methods on each item. +# +# The implicit `pyplot` approach to generate plots is simple. It is helpful +# for basic plots and for interactive environments, such as Jupyter Notebooks. +# Users familiar with MATLAB or would like to have Matplotlib automatically +# create and manage parts of the visualization benefit from using `pyplot` +# functions to plot their data. +# +# + + +############################################################################## +# +# 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 Maptlotlib is required in order to generate plots with the +# library. You can install Matplotlib for your own development environment(s) +# or use a third-party package distribution. +# +# Third-party package distributions, such as +# `Anaconda `_, +# `ActiveState `_, +# or `WinPython `_, +# already provide Matplotlib and its dependencies. They have the added benefit +# of including other scientific Python libraries as well. These packages work +# as is and do not require additional installations. +# +# Installation from source +# ------------------------ +# +# In order to install Matplotlib from the source directory, you can run the +# following command line executions using Python and installer program `pip` +# for the latest version of Matplotlib and its dependencies. This will compile +# the library from the current directory on your machine. +# +# `python -m pip install matplotlib` +# +# .. note:: +# +# If you would like to contribute to Matplotlib, see the developer +# installation guide for details about the process. +# +# Interactive environments +# ------------------------ +# +# The Matplotlib community suggests using `IPython `_ +# through `Jupyter `_ as the primary +# interactive environment. + +############################################################################## +# +# Plotting +# ======== +# +# The common conventions for preparing to plot data involve importing the +# necessary libraries with abbreviations for convenience. Both implicit and +# explicit programming require the following. + +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. +# +# These are the two common strategies for creating plots with Matplotlib. +# +# * Explicit: Code has explicit references to objects. Users manage objects +# for specific figures and axes and call on methods for manipulating data. +# * Object-oriented programming (OOP), robust control and useful for +# generalized code. +# +# * Implicit: The programming is designed to remember preceding events or +# interactions. Matplotlib automatically manages figures and axes. +# * `pyplot`, most similar to MATLAB and convenient for interactive +# environments. +# +# .. note:: +# +# The Matplotlib community does not recommend interchanging explicit and +# implicit strategies. When using one as standard, all code should follow +# the same strategy. Switching back and forth between explicit and +# implicit programming can yield errors. +# +# For other techniques of creating plots with Matplotlib, refer to +# """ref""". +# +# Data +# ---- +# +# The Matplotlib library manages data in the form of iterables and/or +# sequenced items. These can also take the form of NumPy arrays like +# `numpy.array` or `numpy.ma.masked_array`. All plotting functions take these +# data structures. +# + +# Sample Data + +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 `pandas` data objects, may not work as +# intended. +# +# Explicit: Object Oriented Programming (OOP) +# -------------------------------------------- +# +# To use explicit programming for Matplotlib involves using a single instance +# of the `pyplot` module to unpack a set or sets of explicit figure and axes. +# Each axes has its own methods to graph data. In addition, each axes also +# uses separate methods to create and manage parts of a figure. These methods +# are different from those of the implicit programming approach. + +# Explicit programming with OOP + +x = months +y1 = income +y2 = chk_acct_09 +y3 = svg_acct_09 + +fig, ax = plt.subplots() # Figure & axes unpacked separately with module. + +ax.plot(x, y1, label='Checking Account') +ax.plot(x, y2, label='Savings Account') +ax.plot(x, y3, label='Income') +ax.set_xlabel('Month') # Axes use separate methods to manage parts of figure. +ax.set_ylabel('USD') +ax.set_title('Personal Financial Tracking from 2010') +ax.legend() + +############################################################################## +# +# For the OOP example, the figure and axes are unpacked from the module using +# a single instance of `pyplot`. This convention uses `plt.subplots()` and +# defaults to one figure, `fig`, and one axes, `ax`. The section below on +# customizations contains additional information about multiple visulizations +# and other modifications. +# +# Using the OOP approach allows for `fig` and `ax` to use separate methods to +# manipulate the visualization. Instead of using the module `pyplot` for all +# instances of managing objects, the specfic axes refers to OOP usage and +# manages the respective data. +# +# Implicit: `pyplot` +# ------------------ +# +# To use implicit programming for Matplotlib involves using the `pyplot` +# module. The figure and axes are automatically generated by the module. +# Pass data through as arguments using methods within the module. +# Additional parts of the figure are also available through the module +# methods. + +# Implicit programming with pyplot + +y4 = chk_acct_10 +y5 = svg_acct_10 + +plt.plot(x, y1, label='Income') +plt.plot(x, y4, label='Checking Account') +plt.plot(x, y5, label='Savings Account') +plt.xlabel('Month') # Module methods generate parts of figure. +plt.ylabel('USD') +plt.title("Personal Financial Tracking from 2009") +plt.legend() + +############################################################################## +# +# In the example above, the `pyplot` module contains its own methods 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 OOP approach. +# +# .. note:: +# +# The names and spelling for methods may be similar for both `pyplot` and +# OOP approaches. Errors may occur when using the wrong corresponding +# method. Confirm with the documentation API for specific method names +# according to your programming. + +############################################################################## +# +# Customizations +# ============== +# +# 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. +# +# * Figure +# * The figure is the working space for the programming. All visible +# objects on a graph are located within the figure. +# * Axes +# * Axes are subplots within the figure. They contain figure elements and +# are responsible for plotting and configuring additional details. +# * Note: Axes and Axis are not synonymous. Axis refers to +# """ref""". +# +# 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. The third argument represents the specific +# axes involved. +# +# When looking for more complex solutions to multiple graphs within a figure, +# use the GridSpec module to organize the layout. + +# Explicit with OOP + +fig, (ax1, ax2) = plt.subplots(1, 2, sharey='row', + figsize=[8, 4], constrained_layout=True) + +fig.suptitle('Personal Financial Tracking \'09 - \'10', + fontsize=16, weight='black') + +ax1.plot(x, y1, label='Income') +ax1.plot(x, y2, label='Checking') +ax1.plot(x, y3, color='green', label='Savings') +ax1.set_xticklabels(months, rotation=270) +ax1.set_title('2009', fontsize='small') +ax1.legend(loc='upper left') + +ax2.plot(x, y1, label='Income') +ax2.plot(x, y2, label='Checking') +ax2.plot(x, y3, color='green', label='Savings') +ax2.set_xticklabels(months, rotation=270) +ax2.set_title('2010', fontsize='small') + +############################################################################## +# +# The OOP example above also uses two axes to graph the data. However, the OOP +# approach must refer to an explicitly generated axes after creating both the +# figure and axes. + +# Implicit with pyplot + +plt.subplot(1, 2, 1) # Note the different method name for implicit. +plt.plot(x, y1, label='Income') +plt.plot(x, y2, label='Checking') +plt.plot(x, y1, color='green', label='Savings') +plt.xticks(x, months, rotation=270) +plt.title('2009', fontsize='small') + +plt.subplot(1, 2, 2) +plt.plot(x, y1, label='Income') +plt.plot(x, y4, label='Checking') +plt.plot(x, y5, color='green', label='Savings') +plt.xticks(x, months, rotation=270) +plt.title('2009', fontsize='small') +plt.legend(bbox_to_anchor=(1, 1), loc='upper left') + +plt.suptitle('Personal Financial Tracking', weight='black') +plt.tight_layout() + +############################################################################## +# +# The `pyplot` example above uses two axes to graph data. In each instance, +# Matplotlib auotmatically manages the specific axes so that each action of +# plotting data does not interfere with the previous instance. From fa7715364ccdb5ee2f56f0bb488b079ec227866f Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Wed, 11 Nov 2020 21:05:31 -0800 Subject: [PATCH 02/25] Added links, additional text, formatting --- tutorials/introductory/getting_started.py | 368 +++++++++++++++------- 1 file changed, 259 insertions(+), 109 deletions(-) diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py index 04e008bb9a66..74b15fcb3dac 100644 --- a/tutorials/introductory/getting_started.py +++ b/tutorials/introductory/getting_started.py @@ -3,8 +3,8 @@ Getting Started *************** -This tutorial covers some basic usage patterns and best-practices to -help you get started with Matplotlib. +This tutorial covers basic usage patterns and best-practices to help you get +started with Matplotlib. """ ############################################################################## @@ -19,39 +19,75 @@ # programming environments. The fundamental ideas behind Matplotlib for # visualizations involve taking data and transforming it through functions and # methods. This process occurs on the backend and is not user-facing. For more -# information regarding manipulating backend capabilities, see """ref""". +# information regarding manipulating backend capabilities, see +# :ref:`backends`. # # There are two main ways of producing graphs with Matplotlib, explicit and -# implicit. Explicit code, using Object Oriented Programmiong (OOP), and -# implicit code, using `pyplot`, are the foundation for creating 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 programming, OOP, 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 can call methods on each item. +# +------------------------------------+------------------------------------+ +# | Explicit, Object Oriented | Implicit, ``pyplot`` | +# | Programming (OOP) | | +# +====================================+====================================+ +# | Users explicitly create and manage | Automatically manages Figure and | +# | all Figure elements. | Axes. | +# +------------------------------------+------------------------------------+ +# | Useful for repeated code use, | Helpful for quickly graphing data | +# | generalization, robust | when using interactive | +# | configurations of graphs. | environments. | +# +------------------------------------+------------------------------------+ +# | Recommended to new users for | Most useful for users coming from | +# | learning fundamentals. | MATLAB. | +# +------------------------------------+------------------------------------+ +# +# 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 can 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 would like to have Matplotlib automatically create +# and manage parts of the visualization benefit from using the ``pyplot`` +# module to graph data. New users to Matplotlib may experience difficulty +# understanding how elements of a visualization work together when using the +# implicit approach. +# +# Examples +# -------- +# +# +------------------------------------+------------------------------------+ +# | 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. | +# +------------------------------------+------------------------------------+ # -# The implicit `pyplot` approach to generate plots is simple. It is helpful -# for basic plots and for interactive environments, such as Jupyter Notebooks. -# Users familiar with MATLAB or would like to have Matplotlib automatically -# create and manage parts of the visualization benefit from using `pyplot` -# functions to plot their data. -# -# - - -############################################################################## # # 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 +# 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 Maptlotlib is required in order to generate plots with the -# library. You can install Matplotlib for your own development environment(s) -# or use a third-party package distribution. +# Installing Maptlotlib 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. # # Third-party package distributions, such as # `Anaconda `_, @@ -64,17 +100,19 @@ # Installation from source # ------------------------ # -# In order to install Matplotlib from the source directory, you can run the -# following command line executions using Python and installer program `pip` +# In order to install Matplotlib from the source directory, run the +# following command line executions using Python and installer program ``pip`` # for the latest version of Matplotlib and its dependencies. This will compile -# the library from the current directory on your machine. +# the library from the current directory on your machine. Depending on your +# operating system, you may need additional support. # -# `python -m pip install matplotlib` +# ``python -m pip install matplotlib`` # -# .. note:: +# .. seealso:: # -# If you would like to contribute to Matplotlib, see the developer -# installation guide for details about the process. +# To contribute to the Matplotlib community, check +# :ref:`developers-guide-index` +# for details about working with the latest sources. # # Interactive environments # ------------------------ @@ -88,29 +126,41 @@ # Plotting # ======== # -# The common conventions for preparing to plot data involve importing the -# necessary libraries with abbreviations for convenience. Both implicit and -# explicit programming require the following. +# 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 following +# code. 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. -# -# These are the two common strategies for creating plots with Matplotlib. -# -# * Explicit: Code has explicit references to objects. Users manage objects -# for specific figures and axes and call on methods for manipulating data. -# * Object-oriented programming (OOP), robust control and useful for -# generalized code. -# -# * Implicit: The programming is designed to remember preceding events or -# interactions. Matplotlib automatically manages figures and axes. -# * `pyplot`, most similar to MATLAB and convenient for interactive -# environments. +# 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. +# +# 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:: # @@ -120,7 +170,7 @@ # implicit programming can yield errors. # # For other techniques of creating plots with Matplotlib, refer to -# """ref""". +# :ref:`user_interfaces`. # # Data # ---- @@ -131,7 +181,7 @@ # data structures. # -# Sample Data +# Sample Data for Personal Financial Tracking in 2009 & 2010 months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'] @@ -157,10 +207,13 @@ # -------------------------------------------- # # To use explicit programming for Matplotlib involves using a single instance -# of the `pyplot` module to unpack a set or sets of explicit figure and axes. -# Each axes has its own methods to graph data. In addition, each axes also -# uses separate methods to create and manage parts of a figure. These methods -# are different from those of the implicit programming approach. +# of the ``pyplot`` module. This unpacks a set of an explicit Figure and Axes. +# There can be more than one Axes; however, each Axes can only be on one +# Figure. +# +# Each Axes has its own methods to graph data. In addition, each Axes +# also uses separate methods to create and manage parts of a Figure. These +# methods are different from those of the implicit programming approach. # Explicit programming with OOP @@ -168,150 +221,247 @@ y1 = income y2 = chk_acct_09 y3 = svg_acct_09 +# Assigning sample data to labeled variables. -fig, ax = plt.subplots() # Figure & axes unpacked separately with module. +fig, ax = plt.subplots() +# Explicit Figure & Axes unpacked separately with module. ax.plot(x, y1, label='Checking Account') ax.plot(x, y2, label='Savings Account') ax.plot(x, y3, label='Income') -ax.set_xlabel('Month') # Axes use separate methods to manage parts of figure. +# Single explicit Axes graphs multiple data points. + +ax.set_xlabel('Month') ax.set_ylabel('USD') -ax.set_title('Personal Financial Tracking from 2010') +ax.set_title('Personal Financial Tracking from 2009') ax.legend() +# Explicit Axes use separate methods to manage parts of Figure. + +plt.show() +# The pyplot module displays the Figure. ############################################################################## # -# For the OOP example, the figure and axes are unpacked from the module using -# a single instance of `pyplot`. This convention uses `plt.subplots()` and -# defaults to one figure, `fig`, and one axes, `ax`. The section below on -# customizations contains additional information about multiple visulizations -# and other modifications. +# For the OOP example, the Figure and Axes are unpacked from the module using +# a single instance of ``pyplot``. This convention uses ``plt.subplots()`` +# and defaults to one Figure, ``fig``, and one Axes, ``ax``. The +# `Customizations`_ section below contains additional information about +# multiple visulizations and other modifications. # -# Using the OOP approach allows for `fig` and `ax` to use separate methods to -# manipulate the visualization. Instead of using the module `pyplot` for all -# instances of managing objects, the specfic axes refers to OOP usage and +# Using the OOP approach allows for ``fig`` and ``ax`` to use separate methods +# to manipulate the visualization. Instead of using the module ``pyplot`` for +# all instances of managing objects, the specfic Axes refers to OOP usage and # manages the respective data. # -# Implicit: `pyplot` -# ------------------ +# Implicit: ``pyplot`` +# -------------------- # -# To use implicit programming for Matplotlib involves using the `pyplot` -# module. The figure and axes are automatically generated by the module. +# To use implicit programming for Matplotlib involves using the ``pyplot`` +# module. The Figure and Axes are automatically generated by the module. # Pass data through as arguments using methods within the module. -# Additional parts of the figure are also available through the module +# Additional parts of the Figure are also available through the module # methods. # Implicit programming with pyplot y4 = chk_acct_10 y5 = svg_acct_10 +# Assigning former data to labeled variable. +# Previous variables are still referenced. plt.plot(x, y1, label='Income') plt.plot(x, y4, label='Checking Account') plt.plot(x, y5, label='Savings Account') -plt.xlabel('Month') # Module methods generate parts of figure. +# Module plots multiple data points on implicitly generated Axes. + +plt.xlabel('Month') plt.ylabel('USD') -plt.title("Personal Financial Tracking from 2009") +plt.title("Personal Financial Tracking from 2010") plt.legend() +# Module methods generate parts of Figure. + +plt.show() +# The module displays the Figure. ############################################################################## # -# In the example above, the `pyplot` module contains its own methods of -# actionable tasks for the data. The `plt.plot` plots data as a line graph +# In the example above, the ``pyplot`` module contains its own methods 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 OOP approach. # # .. note:: # -# The names and spelling for methods may be similar for both `pyplot` and -# OOP approaches. Errors may occur when using the wrong corresponding -# method. Confirm with the documentation API for specific method names -# according to your programming. - -############################################################################## +# 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. # # Customizations # ============== # # There are two main parts to building a visualization with Matplotlib, the -# figure and the axes. +# `Figure`_ and the `Axes`_. # # Components of Matplotlib Figure # ------------------------------- # # The image below depicts each visible element of a Matplotlib graph. +# **Note**: ``Figure`` and ``Axes`` identify empty regions of the diagram; +# however, these elements are foundational in operation. +# +# .. image:: ../../_static/anatomy.png +# +# :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 Figure elements and +# are responsible for plotting and configuring additional details. Each +# Figure can contain multiple Axes, but each Axes is specific to one +# Figure. +# +# Other Components +# ^^^^^^^^^^^^^^^^ +# +# * :class:`~matplotlib.artist.Artist` +# +# Artists are the visible elements when the Figure is rendered. They +# correspond to a specific Axes and cannot be shared or transferred. +# +# .. note:: +# +# Axes and Axis are not synonymous. Axis refers to +# :class:`~matplotlib.axis.Axis`. # -# * Figure -# * The figure is the working space for the programming. All visible -# objects on a graph are located within the figure. -# * Axes -# * Axes are subplots within the figure. They contain figure elements and -# are responsible for plotting and configuring additional details. -# * Note: Axes and Axis are not synonymous. Axis refers to -# """ref""". # # 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 +# 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. The third argument represents the specific -# axes involved. +# Axes involved. # -# When looking for more complex solutions to multiple graphs within a figure, +# When looking for more complex solutions to multiple graphs within a Figure, # use the GridSpec module to organize the layout. +# +# Explicit +# ^^^^^^^^ # Explicit with OOP -fig, (ax1, ax2) = plt.subplots(1, 2, sharey='row', - figsize=[8, 4], constrained_layout=True) +fig, (ax1, ax2) = plt.subplots(1, 2, + sharey='row', + figsize=[8, 4], + constrained_layout=True) +# Figure and two Axes unpacked from arguments (1, 2) as row & column +# Keyword arguments provide additional details of sharing Y-axis, Figure size +# and layout formatting. -fig.suptitle('Personal Financial Tracking \'09 - \'10', - fontsize=16, weight='black') +fig.suptitle('Personal Financial Tracking \'09 - \'10') +# Explicit Figure object has separate method for title. ax1.plot(x, y1, label='Income') ax1.plot(x, y2, label='Checking') ax1.plot(x, y3, color='green', label='Savings') +# First explicit Axes object plots data with additional keyword arguments. + +ax1.set_xticks(months) ax1.set_xticklabels(months, rotation=270) ax1.set_title('2009', fontsize='small') ax1.legend(loc='upper left') +# First explicit Axes object uses separate methods for ticks on the X-axis, +# title, and legend. Keyword arguments are for additional configurations. ax2.plot(x, y1, label='Income') -ax2.plot(x, y2, label='Checking') -ax2.plot(x, y3, color='green', label='Savings') +ax2.plot(x, y4, label='Checking') +ax2.plot(x, y5, color='green', label='Savings') +# Explicit second Axes object plots data similarly to first explicit Axes. + +ax2.set_xticks(months) ax2.set_xticklabels(months, rotation=270) ax2.set_title('2010', fontsize='small') +# Explicit second Axes object has separate methods as well. + +plt.show() +# The pyplot module displays the Figure. ############################################################################## # -# The OOP example above also uses two axes to graph the data. However, the OOP -# approach must refer to an explicitly generated axes after creating both the -# figure and axes. +# The OOP example above also uses two Axes to graph the data. However, the OOP +# approach must refer to an explicitly generated Axes after creating both the +# Figure and Axes. +# +# In the unpacking process, numerous Axes can also be assigned to the single +# variable. To reference a specific Axes, you can index the location of the +# respective Axes as a matrix through the single variable. +# +# .. note:: +# +# The code below demonstrates indexing multiple Axes. +# :: +# +# fig, ax = plt.subplots(2,2) +# +# ax[0,0].plot([1,2,3],[1,2,3]) +# ax[0,1].plot([3,2,1],[3,2,1]) +# ax[1,0].plot([3,2,1],[3,2,1]) +# ax[1,1].plot([1,2,3],[1,2,3]) +# +# Implicit +# ^^^^^^^^ # Implicit with pyplot -plt.subplot(1, 2, 1) # Note the different method name for implicit. +plt.subplot(1, 2, 1) +# Module implicitly manages a matrix size of (1, 2) for row & column +# to work on the first implicit Axes. + plt.plot(x, y1, label='Income') plt.plot(x, y2, label='Checking') -plt.plot(x, y1, color='green', label='Savings') +plt.plot(x, y3, color='green', label='Savings') +# Module plots data on first implicit Axes. + plt.xticks(x, months, rotation=270) plt.title('2009', fontsize='small') +# Module methods generate parts of Figure for first implicit Axes. plt.subplot(1, 2, 2) +# Module implicitly manages matching matrix size to work on second implicit +# Axes. + plt.plot(x, y1, label='Income') plt.plot(x, y4, label='Checking') plt.plot(x, y5, color='green', label='Savings') +# Module plots data on second implicit Axes. + plt.xticks(x, months, rotation=270) plt.title('2009', fontsize='small') plt.legend(bbox_to_anchor=(1, 1), loc='upper left') +# Module methods generate parts of Figure for second implicit Axes. -plt.suptitle('Personal Financial Tracking', weight='black') +plt.suptitle('Personal Financial Tracking') plt.tight_layout() +# Module methods for managing Figure elements. + +plt.show() +# Module displays the Figure. ############################################################################## # -# The `pyplot` example above uses two axes to graph data. In each instance, -# Matplotlib auotmatically manages the specific axes so that each action of +# The ``pyplot`` example above uses two Axes to graph data. In each instance, +# Matplotlib auotmatically manages the specific Axes so that each action of # plotting data does not interfere with the previous instance. +# +# Additional Resources +# ==================== +# From be9c148fc0e6b9df85b58d13bc68975f7253821f Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Mon, 16 Nov 2020 11:41:43 -0800 Subject: [PATCH 03/25] Additional text and references for customization --- tutorials/introductory/getting_started.py | 60 ++++++++++++++++++----- 1 file changed, 49 insertions(+), 11 deletions(-) diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py index 74b15fcb3dac..e2ef0cf80b9b 100644 --- a/tutorials/introductory/getting_started.py +++ b/tutorials/introductory/getting_started.py @@ -256,9 +256,9 @@ # Implicit: ``pyplot`` # -------------------- # -# To use implicit programming for Matplotlib involves using the ``pyplot`` +# Implicit programming for Matplotlib centers around using the ``pyplot`` # module. The Figure and Axes are automatically generated by the module. -# Pass data through as arguments using methods within the module. +# The methods and functions within the module take incoming data as arguments. # Additional parts of the Figure are also available through the module # methods. @@ -303,25 +303,28 @@ # ============== # # There are two main parts to building a visualization with Matplotlib, the -# `Figure`_ and the `Axes`_. +# ``Figure`` and the ``Axes``. # # Components of Matplotlib Figure # ------------------------------- # -# The image below depicts each visible element of a Matplotlib graph. -# **Note**: ``Figure`` and ``Axes`` identify empty regions of the diagram; -# however, these elements are foundational in operation. +# 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. The source code is available as :ref:`Anatomy-of-a-figure`. +# +# .. note:: +# +# ``Figure`` and ``Axes`` identify empty regions of the diagram; +# however, these elements are foundational in operation. # # .. image:: ../../_static/anatomy.png # # :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 Figure elements and # are responsible for plotting and configuring additional details. Each @@ -331,7 +334,7 @@ # Other Components # ^^^^^^^^^^^^^^^^ # -# * :class:`~matplotlib.artist.Artist` +# :class:`~matplotlib.artist.Artist` # # Artists are the visible elements when the Figure is rendered. They # correspond to a specific Axes and cannot be shared or transferred. @@ -352,7 +355,7 @@ # Axes involved. # # When looking for more complex solutions to multiple graphs within a Figure, -# use the GridSpec module to organize the layout. +# use the :class:`matplotlib.gridspec.GridSpec` module to organize the layout. # # Explicit # ^^^^^^^^ @@ -363,7 +366,7 @@ sharey='row', figsize=[8, 4], constrained_layout=True) -# Figure and two Axes unpacked from arguments (1, 2) as row & column +# Figure and two Axes unpacked from arguments (1, 2) as row & column. # Keyword arguments provide additional details of sharing Y-axis, Figure size # and layout formatting. @@ -462,6 +465,41 @@ # Matplotlib auotmatically manages the specific Axes so that each action of # plotting data does not interfere with the previous instance. # +# .. note:: +# +# There are limitations for customizing the implicit approach without +# referencing specific Axes and Artists within the Figure. For more +# advanced configurations, the explicit approach is recommended. +# +# Generalized Function Guidelines +# ------------------------------- +# +# For users with that have recurring plots and graphs, the Matplotlib +# community recommends a signature function similar to the format below. + + +def my_plotter(ax, data1, data2, param_dict): + """ + Parameters + ---------- + :param ax: Axes + :param data1: array of X data + :param data2: array of Y data + :param param_dict: Dictionary of keyword arguments to pass to method + + Returns + ------- + :returns: out : list of artists added + """ + out = ax.plot(data1, data2, **param_dict) + # Note: Other methods from Axes class are also applicable. + return out + +############################################################################## +# +# .. currentmodule:: getting_started +# .. autofunction:: my_plotter +# # Additional Resources # ==================== # From 42f754bc1281c9bec8d70ec8dba11cab2327deb7 Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Mon, 16 Nov 2020 15:14:26 -0800 Subject: [PATCH 04/25] * Added Style Guide .rst file with outline * Fixed reference to Anatomy of a figure --- doc/devel/style_guide.rst | 29 +++++++++++++++++++++++ tutorials/introductory/getting_started.py | 6 ++++- 2 files changed, 34 insertions(+), 1 deletion(-) create mode 100644 doc/devel/style_guide.rst diff --git a/doc/devel/style_guide.rst b/doc/devel/style_guide.rst new file mode 100644 index 000000000000..6a4b677b5738 --- /dev/null +++ b/doc/devel/style_guide.rst @@ -0,0 +1,29 @@ + +=========== +Style Guide +=========== + +Expository Language +=================== + +Terminology +----------- + + + +Grammar +------- + + + +Formatting +========== + + + +Additional Resources +==================== + +* `Red Hat Style Guide `_ +* `IBM Style Guide `_ +* `Google Developer Style Guide `_ \ No newline at end of file diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py index e2ef0cf80b9b..bb3bd5b68441 100644 --- a/tutorials/introductory/getting_started.py +++ b/tutorials/introductory/getting_started.py @@ -1,4 +1,7 @@ """ + +.. _getting_started: + *************** Getting Started *************** @@ -310,7 +313,8 @@ # # 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. The source code is available as :ref:`Anatomy-of-a-figure`. +# visualization. The source code is available as +# :ref:`sphx_glr_gallery_showcase_anatomy.py`. # # .. note:: # From 9419b12aefba6fa5e0e4a3bb922b978672c955ee Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Sun, 22 Nov 2020 22:52:33 -0800 Subject: [PATCH 05/25] Pie charts plus more sections and style guide additions --- doc/devel/style_guide.rst | 40 +++++ tutorials/introductory/getting_started.py | 198 +++++++++++++++++++++- 2 files changed, 231 insertions(+), 7 deletions(-) diff --git a/doc/devel/style_guide.rst b/doc/devel/style_guide.rst index 6a4b677b5738..213724c75f7a 100644 --- a/doc/devel/style_guide.rst +++ b/doc/devel/style_guide.rst @@ -9,16 +9,56 @@ Expository Language Terminology ----------- ++-----------------------+--------------------------+------------------------+ +| Term | Description | ++----------------------------------------------+ +| Figure | ++-----------------------+--------------------------+------------------------+ +| Axes | ++-----------------------+--------------------------+------------------------+ +| Object Oriented | +| Programming (OOP) | ++-----------------------+--------------------------+------------------------+ Grammar ------- +Subject +^^^^^^^ +The audience is the "user" in the documentation. A "user" is a person +programming in Python with the Matplotlib library. + +Use second-person sentences for instructions directed at user for specifying +an action. + +Tense +^^^^^ +Use present simple tense for explanations. Avoid future tense and other modal +or auxiliary verbs when possible. + +Voice +^^^^^ +Write in active sentences. Passive voice is best for situations or condtions +for warning prompts. + +Sentence structure +^^^^^^^^^^^^^^^^^^ +Write wih short sentences using Subject-Verb-Object order regularly. Limit +how frequently coordinating conjunctions appear in sentences. Avoid pronoun +referenes and subordinating conjunctive prhases. Formatting ========== +reStructuredText standards +-------------------------- + +Lists +^^^^^ +Bulleted lists are for items that do not require sequencing. +Numbered Lists are exclusively for performing actions in specific order. Additional Resources diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py index bb3bd5b68441..ee97a2930f39 100644 --- a/tutorials/introductory/getting_started.py +++ b/tutorials/introductory/getting_started.py @@ -123,8 +123,6 @@ # The Matplotlib community suggests using `IPython `_ # through `Jupyter `_ as the primary # interactive environment. - -############################################################################## # # Plotting # ======== @@ -135,6 +133,7 @@ # code. import matplotlib.pyplot as plt +import numpy as np ############################################################################## # @@ -142,6 +141,9 @@ # module's functions create, manage, and manipulate the current Figure and the # plotting area. # +# NumPy is a common scientific Python library that benefits users with +# additional robust tools for manipulating data. +# # Two Approaches for Creating Graphs # ---------------------------------- # @@ -228,6 +230,7 @@ fig, ax = plt.subplots() # Explicit Figure & Axes unpacked separately with module. +# Conventional object abbreviations are `fig` and `ax`, respectively. ax.plot(x, y1, label='Checking Account') ax.plot(x, y2, label='Savings Account') @@ -299,11 +302,11 @@ # 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 +# and :mod:`matplotlib.pyplot` for implicit or other respective method # names. # -# Customizations -# ============== +# Configuration +# ============= # # There are two main parts to building a visualization with Matplotlib, the # ``Figure`` and the ``Axes``. @@ -335,19 +338,200 @@ # Figure can contain multiple Axes, but each Axes is specific to one # Figure. # +# In a Figure, each Axes can contain any number of visual elements. An Axes may +# have 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. +# # Other Components # ^^^^^^^^^^^^^^^^ # # :class:`~matplotlib.artist.Artist` # -# Artists are the visible elements when the Figure is rendered. They -# correspond to a specific Axes and cannot be shared or transferred. +# Artists are broad Matplotlib objects that display visuals. These 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`. # +# Manipulating Artists +# -------------------- +# +# With simple plots, Matplotlib automatically generates the basic elements of +# a graph. Artists as objects allow for more control over the visual. +# +# Matplotlib generates additional visual elements as Artists in the form of +# objects. As Artists, each has its own respective methods and functions. +# Explicit and implicit approaches use different methods and are not +# interchangeable. +# +# The table below compares common Artists and their different methods. +# +# +-----------------------+--------------------------+------------------------+ +# | 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. | +# +-----------------------+--------------------------+------------------------+ +# | X-axis labels | ``ax.set_xticks()`` | ``plt.xlabel()`` | +# | | ``ax.set_xticklabels()`` | | +# +-----------------------+--------------------------+------------------------+ +# | Y-axis labels | ``x.set_yticks()`` | ``plt.ylabel()` | +# | | ``ax.set_yticklabels()`` | | +# +-----------------------+--------------------------+------------------------+ +# | Title (Axes) | ``ax.set_title()`` | ``plt.title()`` | +# +-----------------------+--------------------------+------------------------+ +# | Legend (Axes) | ``ax.legend()`` | ``plt.legend()`` | +# +-----------------------+--------------------------+------------------------+ +# +# .. note:: +# +# In explicit programming, ``ax`` refers to an assigned variable for a +# specific Axes. Also, axis labels require separate setting actions for +# each specific Axes. +# +# In implicit programming, the ``pyplot`` module automatically manages +# separate setting actions for state-based Matplotlib objects. +# +# +# Pie Chart Examples +# ------------------ +# +# Matplotlib pie charts create wedges based on data and manipulate the size of +# the Artists based on the ratio of the slice to the sum of the data. The +# ``.pie()`` method is similar for 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. +# +# See `matplotlib.axes.Axes.pie` and `matplotlib.pyplot.pie` for more +# information about the APIs for explicit and implicit, respectively. + +# Data + +budget = [475, 300, 125, 50] +# Data points are represented in wedge size compared to total sum. + +descriptions = ['Shared house in Philadelphia', + 'Dog costs, phone, utilities', + 'Groceries & takeout', + 'Treasury bonds'] +categories = ['Rent', 'Bills', 'Food', 'Savings'] +# These lists of strings contribute to labeling corresponding to data. + +colors = ['#1f77b4', '#ff7f0e', '#d62728', '#2ca02c'] +# Hex color codes determine respective wedge color. + +explode = [0, 0.1, 0.15, 0.35] +# Float list represents percentage of radius to separate from center. + + +def autopct_format(percent, group): + """ + Takes percent equivalent and calculates original value from data. + Returns fstring of value above percentage. + """ + value = int(percent/100.*np.sum(group)) + return f'${value:<4}\n{percent:1.1f}%' +# This function is used as a lambda for formatting labels in wedges. + +############################################################################## +# +# The following two plots are identical. Both the explicit and implicit +# approaches generate the exact same plot when using the same variables. +# +# Basic +# ^^^^^ + +# Explicit + + +fig, ax = plt.subplots() + +ax.pie(budget, colors=colors, labels=categories) +ax.legend() +ax.set_title('Average Monthly Income Expenses') +ax.axis('equal') + +plt.show() + +############################################################################## +# +# + +plt.pie(budget, colors=colors, labels=categories) +plt.legend() +plt.axis('equal') +plt.title('Average Monthly Income Expenses') +plt.show() + +############################################################################## +# +# .. note:: +# +# There are minor differences in the method names. Overall, each method +# performs the same action through the different approaches. +# +# Additional Configurations +# ^^^^^^^^^^^^^^^^^^^^^^^^^ +# +# Many methods contain optional keyword arguments for further configuration. +# In the explicit example below, there are values and functions in keyword +# arguments that format the Artists. + +fig, ax = plt.subplots() + +ax.pie(budget, + colors=colors, + explode=explode, + labels=categories, + autopct=lambda pct: autopct_format(pct, budget), + startangle=-80, + shadow=True) + + +ax.legend() +ax.axis('equal') +ax.set_title('Average Monthly Income Expenses') +plt.show() + +############################################################################## +# +# + +fig, ax = plt.subplots() + +wedges, texts, autotexts = ax.pie(budget, labels=descriptions, + colors=colors, explode=explode, + autopct='%d', startangle=45, + pctdistance=0.85, labeldistance=1.125, + wedgeprops=dict(width=0.3), + shadow=True) + +for text, value in zip(autotexts, budget): + text.set_text(f'${value}\n{text.get_text()}%') + text.set_fontweight('medium') + +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') + +plt.show() + +############################################################################## +# +# +# Customization +# ============= # # Multiple Graphs within a Figure # ------------------------------- From 1d8061da4e69e1d4e5dade677be459559a7f634c Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Mon, 23 Nov 2020 11:32:53 -0800 Subject: [PATCH 06/25] Refining getting_started.py comments and fixing table layout for style_guide.rst --- doc/devel/style_guide.rst | 16 +- tutorials/introductory/getting_started.py | 172 ++++++++++++++++------ 2 files changed, 133 insertions(+), 55 deletions(-) diff --git a/doc/devel/style_guide.rst b/doc/devel/style_guide.rst index 213724c75f7a..dec82121b5b3 100644 --- a/doc/devel/style_guide.rst +++ b/doc/devel/style_guide.rst @@ -10,14 +10,14 @@ Terminology ----------- +-----------------------+--------------------------+------------------------+ -| Term | Description | -+----------------------------------------------+ -| Figure | +| Term | Description | | +-----------------------+--------------------------+------------------------+ -| Axes | +| Figure | | | +-----------------------+--------------------------+------------------------+ -| Object Oriented | -| Programming (OOP) | +| Axes | | | ++-----------------------+--------------------------+------------------------+ +| Object Oriented | | | +| Programming (OOP) | | | +-----------------------+--------------------------+------------------------+ @@ -32,6 +32,10 @@ programming in Python with the Matplotlib library. Use second-person sentences for instructions directed at user for specifying an action. ++------------------------------------+------------------------------------+ +| Correct | Incorrect | ++------------------------------------+------------------------------------+ + Tense ^^^^^ Use present simple tense for explanations. Avoid future tense and other modal diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py index ee97a2930f39..7d665f61cf80 100644 --- a/tutorials/introductory/getting_started.py +++ b/tutorials/introductory/getting_started.py @@ -105,7 +105,7 @@ # # In order to install Matplotlib from the source directory, run the # following command line executions using Python and installer program ``pip`` -# for the latest version of Matplotlib and its dependencies. This will compile +# for the latest version of Matplotlib and its dependencies. This compiles # the library from the current directory on your machine. Depending on your # operating system, you may need additional support. # @@ -172,7 +172,7 @@ # The Matplotlib community does not recommend interchanging explicit and # implicit strategies. When using one as standard, all code should follow # the same strategy. Switching back and forth between explicit and -# implicit programming can yield errors. +# implicit programming may yield errors. # # For other techniques of creating plots with Matplotlib, refer to # :ref:`user_interfaces`. @@ -251,8 +251,8 @@ # For the OOP example, the Figure and Axes are unpacked from the module using # a single instance of ``pyplot``. This convention uses ``plt.subplots()`` # and defaults to one Figure, ``fig``, and one Axes, ``ax``. The -# `Customizations`_ section below contains additional information about -# multiple visulizations and other modifications. +# `Configuration`_ section below contains additional information about +# manipulating visuals, multiple visulizations, and other modifications. # # Using the OOP approach allows for ``fig`` and ``ax`` to use separate methods # to manipulate the visualization. Instead of using the module ``pyplot`` for @@ -316,8 +316,8 @@ # # 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. The source code is available as -# :ref:`sphx_glr_gallery_showcase_anatomy.py`. +# visualization. To see how the programming operates, the source code is +# available at :ref:`sphx_glr_gallery_showcase_anatomy.py`. # # .. note:: # @@ -363,7 +363,7 @@ # -------------------- # # With simple plots, Matplotlib automatically generates the basic elements of -# a graph. Artists as objects allow for more control over the visual. +# a graph. For more control over the visual, use Artists and its methods. # # Matplotlib generates additional visual elements as Artists in the form of # objects. As Artists, each has its own respective methods and functions. @@ -383,7 +383,7 @@ # | X-axis labels | ``ax.set_xticks()`` | ``plt.xlabel()`` | # | | ``ax.set_xticklabels()`` | | # +-----------------------+--------------------------+------------------------+ -# | Y-axis labels | ``x.set_yticks()`` | ``plt.ylabel()` | +# | Y-axis labels | ``ax.set_yticks()`` | ``plt.ylabel()`` | # | | ``ax.set_yticklabels()`` | | # +-----------------------+--------------------------+------------------------+ # | Title (Axes) | ``ax.set_title()`` | ``plt.title()`` | @@ -391,14 +391,18 @@ # | Legend (Axes) | ``ax.legend()`` | ``plt.legend()`` | # +-----------------------+--------------------------+------------------------+ # -# .. note:: +# The term ``ax`` refers to an assigned variable for a specific Axes. Using +# explicit programming requires additional tasks of setting objects prior to +# assigning labels. Whereas with implicit programming, the module manages +# those tasks without specification. # -# In explicit programming, ``ax`` refers to an assigned variable for a -# specific Axes. Also, axis labels require separate setting actions for -# each specific Axes. +# For additional information about available methods, see the table below. # -# In implicit programming, the ``pyplot`` module automatically manages -# separate setting actions for state-based Matplotlib objects. +# +------------------------------------+------------------------------------+ +# | Explicit | :class:`matplotlib.axes.Axes` | +# +------------------------------------+------------------------------------+ +# | Implicit | :mod:`matplotlib.pyplot` | +# +------------------------------------+------------------------------------+ # # # Pie Chart Examples @@ -412,32 +416,31 @@ # arguments as well as Artist methods for both explicit and implicit # programming. # -# See `matplotlib.axes.Axes.pie` and `matplotlib.pyplot.pie` for more -# information about the APIs for explicit and implicit, respectively. # Data budget = [475, 300, 125, 50] # Data points are represented in wedge size compared to total sum. +# Matplotlib methods calculate these values automatically based on input. -descriptions = ['Shared house in Philadelphia', - 'Dog costs, phone, utilities', - 'Groceries & takeout', +descriptions = ['Shared house\nin Philadelphia', + 'Dog costs, phone,\nutilities', + 'Groceries\n& takeout', 'Treasury bonds'] categories = ['Rent', 'Bills', 'Food', 'Savings'] -# These lists of strings contribute to labeling corresponding to data. +# These lists of strings contribute to labeling corresponding data. colors = ['#1f77b4', '#ff7f0e', '#d62728', '#2ca02c'] # Hex color codes determine respective wedge color. explode = [0, 0.1, 0.15, 0.35] -# Float list represents percentage of radius to separate from center. +# List of floats represents percentage of radius to separate from center. def autopct_format(percent, group): """ Takes percent equivalent and calculates original value from data. - Returns fstring of value above percentage. + Returns fstring of value new line above percentage. """ value = int(percent/100.*np.sum(group)) return f'${value:<4}\n{percent:1.1f}%' @@ -445,11 +448,14 @@ def autopct_format(percent, group): ############################################################################## # +# Basic +# ^^^^^ +# # The following two plots are identical. Both the explicit and implicit # approaches generate the exact same plot when using the same variables. # -# Basic -# ^^^^^ +# See `matplotlib.axes.Axes.pie` and `matplotlib.pyplot.pie` for more +# information about the APIs for explicit and implicit, respectively. # Explicit @@ -460,6 +466,7 @@ def autopct_format(percent, group): ax.legend() ax.set_title('Average Monthly Income Expenses') ax.axis('equal') +# The axis method sets the aspect ratio of the visual as equal. plt.show() @@ -469,8 +476,10 @@ def autopct_format(percent, group): plt.pie(budget, colors=colors, labels=categories) plt.legend() -plt.axis('equal') plt.title('Average Monthly Income Expenses') +plt.axis('equal') +# The pyplot module contains an identical method for aspect ratio setting. + plt.show() ############################################################################## @@ -480,58 +489,123 @@ def autopct_format(percent, group): # There are minor differences in the method names. Overall, each method # performs the same action through the different approaches. # -# Additional Configurations -# ^^^^^^^^^^^^^^^^^^^^^^^^^ +# These pie charts are simple in that there is not much 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 explicit example below, there are values and functions in keyword -# arguments that format the Artists. +# In the examples for explicit programming below, there are values and +# functions in keyword arguments that format 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 manipulate the Artists. + +# Explicit fig, ax = plt.subplots() ax.pie(budget, colors=colors, - explode=explode, labels=categories, - autopct=lambda pct: autopct_format(pct, budget), + explode=explode, + # The explode keyword argument uses the explode variable from data to + # separate respective wedges from the center. + autopct='%1.1f%%', + # The autopct keyword argument takes formatting strings and functions + # to generate text within the wedge. '%1.1f%%' uses string formatters. startangle=-80, - shadow=True) - + # The startangle keyword argument changes where the first wedge spans. + # Angles start at 0 degrees on the X-axis and move counterclockwise. + shadow=True + # The shadow keyword argument toggles a shadow on the visual. + ) ax.legend() -ax.axis('equal') ax.set_title('Average Monthly Income Expenses') +ax.axis('equal') + plt.show() ############################################################################## # -# +# In the pie chart below, there are 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 +# :ref:`legend-guide` -fig, ax = plt.subplots() +# Explicit -wedges, texts, autotexts = ax.pie(budget, labels=descriptions, - colors=colors, explode=explode, - autopct='%d', startangle=45, - pctdistance=0.85, labeldistance=1.125, - wedgeprops=dict(width=0.3), - shadow=True) +fig, ax = plt.subplots() -for text, value in zip(autotexts, budget): - text.set_text(f'${value}\n{text.get_text()}%') - text.set_fontweight('medium') +budget_pie = ax.pie(budget, + colors=colors, + labels=descriptions, + # Instead of using the categories data as a label, the + # descriptions act as text to label the wedges. This aids + # in removing redundant information from the previous + # pie chart. + explode=explode, + autopct=lambda pct: autopct_format(pct, budget), + # The autopct keyword argument in this instance uses a + # function in a lambda to return a formatted string. + startangle=45, + pctdistance=0.85, + # The pctdistance keyword argument places the autopct + # Artist at a location using the float as a percentage of + # the radius. + labeldistance=1.125, + # The labeldistance keyword argument specifies the float as + # a percentage of the radius to place labels. + wedgeprops=dict(width=0.3), + # The wedgeprops keyword argument can also take + # dictionaries to pass on to the artists. In this + # instance, the float for width sets the wedge size as a + # percentage of the radius starting from the outer edge. + shadow=True) + +wedges, texts, autotexts = budget_pie +# The pie() method unpacks into three objects, wedges, texts, and autotexts. +# These Artists have their own methods for addtional customization. + +ax.legend(wedges, + # The wedges variable unpacked from the method serve as the handles + # for the legend. + categories, + # The information from the data categories correspond to each + # respective wedge instead of redundant labeling from the previous + # pie chart. + title='Categories', + # The legend has a title keyword argument. + bbox_to_anchor=(0.125, 0.5), + # This keyword argument in conjunction with loc places the legend + # at a specific point. The tuple floats are coordinates for the + # Figure. + loc='center right' + # The loc keyword argument works in conjunction with bbox_to_anchor + # and in this instance, determines the part of the legend for + # placement. Without bbox_to_anchor, Matplotlib automatically + # manages coordinates in relation to specifications of the + # 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') +fig.tight_layout() +# The Figure method tight_layout() manages the space between all Artists to +# maximize visiblity on the Figure. This method also contains various +# parameters for configuration. + plt.show() ############################################################################## # # -# Customization -# ============= # # Multiple Graphs within a Figure # ------------------------------- From 2183c5a7614f214f1581ff6c4d0bf0ac741138d3 Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Mon, 23 Nov 2020 11:47:58 -0800 Subject: [PATCH 07/25] Small tweaks to both files --- doc/devel/style_guide.rst | 24 +++++++++++++++++++++++ tutorials/introductory/getting_started.py | 2 +- 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/doc/devel/style_guide.rst b/doc/devel/style_guide.rst index dec82121b5b3..cad81ca0ddee 100644 --- a/doc/devel/style_guide.rst +++ b/doc/devel/style_guide.rst @@ -35,23 +35,42 @@ an action. +------------------------------------+------------------------------------+ | Correct | Incorrect | +------------------------------------+------------------------------------+ +| | | ++------------------------------------+------------------------------------+ Tense ^^^^^ Use present simple tense for explanations. Avoid future tense and other modal or auxiliary verbs when possible. ++------------------------------------+------------------------------------+ +| Correct | Incorrect | ++------------------------------------+------------------------------------+ +| | | ++------------------------------------+------------------------------------+ + Voice ^^^^^ Write in active sentences. Passive voice is best for situations or condtions for warning prompts. ++------------------------------------+------------------------------------+ +| Correct | Incorrect | ++------------------------------------+------------------------------------+ +| | | ++------------------------------------+------------------------------------+ + Sentence structure ^^^^^^^^^^^^^^^^^^ Write wih short sentences using Subject-Verb-Object order regularly. Limit how frequently coordinating conjunctions appear in sentences. Avoid pronoun referenes and subordinating conjunctive prhases. ++------------------------------------+------------------------------------+ +| Correct | Incorrect | ++------------------------------------+------------------------------------+ +| | | ++------------------------------------+------------------------------------+ Formatting ========== @@ -64,6 +83,11 @@ Lists Bulleted lists are for items that do not require sequencing. Numbered Lists are exclusively for performing actions in specific order. ++------------------------------------+------------------------------------+ +| Correct | Incorrect | ++------------------------------------+------------------------------------+ +| | | ++------------------------------------+------------------------------------+ Additional Resources ==================== diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py index 7d665f61cf80..4462e104ba5f 100644 --- a/tutorials/introductory/getting_started.py +++ b/tutorials/introductory/getting_started.py @@ -668,7 +668,7 @@ def autopct_format(percent, group): # # In the unpacking process, numerous Axes can also be assigned to the single # variable. To reference a specific Axes, you can index the location of the -# respective Axes as a matrix through the single variable. +# respective Axes as a matrix through the single variable as well. # # .. note:: # From 5871848e16a3236e381f021913f0a52cb7efc989 Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Tue, 24 Nov 2020 16:12:03 -0800 Subject: [PATCH 08/25] Fixed installation section and helper function doc format --- tutorials/introductory/getting_started.py | 40 ++++++++--------------- 1 file changed, 14 insertions(+), 26 deletions(-) diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py index 4462e104ba5f..3932e3829fe2 100644 --- a/tutorials/introductory/getting_started.py +++ b/tutorials/introductory/getting_started.py @@ -92,24 +92,8 @@ # library. Install Matplotlib for your own development environment manually or # use a third-party package distribution. # -# Third-party package distributions, such as -# `Anaconda `_, -# `ActiveState `_, -# or `WinPython `_, -# already provide Matplotlib and its dependencies. They have the added benefit -# of including other scientific Python libraries as well. These packages work -# as is and do not require additional installations. -# -# Installation from source -# ------------------------ -# -# In order to install Matplotlib from the source directory, run the -# following command line executions using Python and installer program ``pip`` -# for the latest version of Matplotlib and its dependencies. This compiles -# the library from the current directory on your machine. Depending on your -# operating system, you may need additional support. -# -# ``python -m pip install matplotlib`` +# The :ref:`installation-guide` contains more information about install +# methods and resources for third-party package distributions. # # .. seealso:: # @@ -742,25 +726,29 @@ def autopct_format(percent, group): def my_plotter(ax, data1, data2, param_dict): """ + Helper function to make a graph. + Parameters ---------- - :param ax: Axes - :param data1: array of X data - :param data2: array of Y data - :param param_dict: Dictionary of keyword arguments to pass to method + 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 ------- - :returns: out : list of artists added + out : list + List of Artists added """ out = ax.plot(data1, data2, **param_dict) - # Note: Other methods from Axes class are also applicable. return out ############################################################################## # -# .. currentmodule:: getting_started -# .. autofunction:: my_plotter # # Additional Resources # ==================== From a24c9cd28af8b7611fa03ece990994d6e2e912cc Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Mon, 30 Nov 2020 11:55:34 -0800 Subject: [PATCH 09/25] Resolving 6 comments from PR for getting_started and adding examples for style_guide --- doc/devel/style_guide.rst | 102 ++++++++++-- tutorials/introductory/getting_started.py | 187 +++++++++++----------- 2 files changed, 181 insertions(+), 108 deletions(-) diff --git a/doc/devel/style_guide.rst b/doc/devel/style_guide.rst index cad81ca0ddee..a8f6872f1e0a 100644 --- a/doc/devel/style_guide.rst +++ b/doc/devel/style_guide.rst @@ -3,22 +3,44 @@ Style Guide =========== +This guide is for contributors to understand conventions and expectations for +quality control of Matplotlib written content. + Expository Language =================== +For explanatory writing, the following guidelines are for clear and concise +language use. + Terminology ----------- -+-----------------------+--------------------------+------------------------+ -| Term | Description | | -+-----------------------+--------------------------+------------------------+ -| Figure | | | -+-----------------------+--------------------------+------------------------+ -| Axes | | | -+-----------------------+--------------------------+------------------------+ -| Object Oriented | | | -| Programming (OOP) | | | -+-----------------------+--------------------------+------------------------+ +There are several key terms in Matplotlib that are standards for +reliability and consistency in documentation. They are case-sensitive and +are not interchangeable. + ++----------------------+--------------------------+-------------------------+ +| Term | Description | Correct | Incorrect | ++----------------------+--------------------------+-------------------------+ +| Figure | Workign space for | | | +| | programming. | | | ++----------------------+--------------------------+-------------------------+ +| Axes | Subplots within Figure. | | | +| | Contains Figure elements | | | +| | and is responsible for | | | +| | plotting and configuring | | | +| | additional details. | | | ++----------------------+--------------------------+-------------------------+ +| Axis | Refers to visible object | | | +| | corresponding to labeling| | | +| | of plotted data. | | | ++----------------------+--------------------------+-------------------------+ +| Artist | Broad Matplotlib object | | | +| | that displays visuals. | | | ++----------------------+--------------------------+-------------------------+ +| Object Oriented | Explicit approach of | | | +| Programming (OOP) | programing in Matplotlib.| | | ++----------------------+--------------------------+-------------------------+ Grammar @@ -35,7 +57,11 @@ an action. +------------------------------------+------------------------------------+ | Correct | Incorrect | +------------------------------------+------------------------------------+ -| | | +| Users install Matplotlib from the | You can install Matplotlib from the| +| source directory using the Python | source directory. You can find | +| ``pip`` installer program. | additional support if you are | +| Depending on your operating system,| having troulbe with your | +| you may need additional support. | installation. | +------------------------------------+------------------------------------+ Tense @@ -46,18 +72,27 @@ 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. This should be the basic | +| transforming it thorugh functions | fundamental idea behind Matplotlib | +| and methods. | for visualizations. | +------------------------------------+------------------------------------+ Voice ^^^^^ Write in active sentences. Passive voice is best for situations or condtions -for warning prompts. +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 @@ -69,15 +104,31 @@ referenes and subordinating conjunctive prhases. +------------------------------------+------------------------------------+ | 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. | | +------------------------------------+------------------------------------+ Formatting ========== +Matplotlib uses reStructuredText Markup for documentation. Sphinx helps to +transform these documents into proper formats for access and visibility. + reStructuredText standards -------------------------- +https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html +https://docutils.sourceforge.io/docs/user/rst/quickref.html + + Lists ^^^^^ Bulleted lists are for items that do not require sequencing. @@ -86,7 +137,18 @@ Numbered Lists are exclusively for performing actions in specific order. +------------------------------------+------------------------------------+ | Correct | Incorrect | +------------------------------------+------------------------------------+ -| | | +| The example uses three graphs. | The example uses three graphs. | +| - Bar | 1. Bar | +| - Line | 2. Line | +| - Pie | 3. Pie | ++------------------------------------+------------------------------------+ +| These three 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. | +------------------------------------+------------------------------------+ Additional Resources @@ -94,4 +156,10 @@ Additional Resources * `Red Hat Style Guide `_ * `IBM Style Guide `_ -* `Google Developer Style Guide `_ \ No newline at end of file +* `Google Developer Style Guide `_ + ++------------------------------------+------------------------------------+ +| Correct | Incorrect | ++------------------------------------+------------------------------------+ +| | | ++------------------------------------+------------------------------------+ diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py index 3932e3829fe2..725c21c24d7f 100644 --- a/tutorials/introductory/getting_started.py +++ b/tutorials/introductory/getting_started.py @@ -92,8 +92,9 @@ # library. Install Matplotlib for your own development environment manually or # use a third-party package distribution. # -# The :ref:`installation-guide` contains more information about install -# methods and resources for third-party package distributions. +# The `Installation Guide `_ +# page contains more information about install methods and resources for +# third-party package distributions. # # .. seealso:: # @@ -119,14 +120,18 @@ import matplotlib.pyplot as plt import numpy as np +from functools import partial + ############################################################################## # -# 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. -# -# NumPy is a common scientific Python library that benefits users with -# additional robust tools for manipulating data. +# - 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. +# - NumPy is a common scientific Python library that benefits users with +# additional robust tools for manipulating data. +# - The ``functools`` module helps manage functions that act on or return +# otherfunctions. The `Pie Chart Examples`_ section contains more +# information about the purpose of this module. # # Two Approaches for Creating Graphs # ---------------------------------- @@ -154,9 +159,9 @@ # .. note:: # # The Matplotlib community does not recommend interchanging explicit and -# implicit strategies. When using one as standard, all code should follow -# the same strategy. Switching back and forth between explicit and -# implicit programming may yield errors. +# 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`. @@ -189,8 +194,12 @@ # # .. note:: # -# Other containers, such as `pandas` data objects, may not work as -# intended. +# Other containers, such as data objects from various libraries, may not +# work as intended. +# +# 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) # -------------------------------------------- @@ -210,15 +219,17 @@ y1 = income y2 = chk_acct_09 y3 = svg_acct_09 +y4 = chk_acct_10 +y5 = svg_acct_10 # Assigning sample data to labeled variables. fig, ax = plt.subplots() # Explicit Figure & Axes unpacked separately with module. # Conventional object abbreviations are `fig` and `ax`, respectively. -ax.plot(x, y1, label='Checking Account') -ax.plot(x, y2, label='Savings Account') -ax.plot(x, y3, label='Income') +ax.plot(x, y1, label='Income') +ax.plot(x, y2, label='Checking Account') +ax.plot(x, y3, label='Savings Account') # Single explicit Axes graphs multiple data points. ax.set_xlabel('Month') @@ -254,19 +265,16 @@ # Implicit programming with pyplot -y4 = chk_acct_10 -y5 = svg_acct_10 -# Assigning former data to labeled variable. # Previous variables are still referenced. plt.plot(x, y1, label='Income') -plt.plot(x, y4, label='Checking Account') -plt.plot(x, y5, label='Savings Account') +plt.plot(x, y2, label='Checking Account') +plt.plot(x, y3, label='Savings Account') # Module plots multiple data points on implicitly generated Axes. plt.xlabel('Month') plt.ylabel('USD') -plt.title("Personal Financial Tracking from 2010") +plt.title("Personal Financial Tracking from 2009") plt.legend() # Module methods generate parts of Figure. @@ -354,7 +362,7 @@ # Explicit and implicit approaches use different methods and are not # interchangeable. # -# The table below compares common Artists and their different methods. +# The table below compares formatter Artists and their different methods. # # +-----------------------+--------------------------+------------------------+ # | Artist | Explicit | Implicit | @@ -364,17 +372,30 @@ # | | artists. | on most recent Figure | # | | | or Axes. | # +-----------------------+--------------------------+------------------------+ -# | X-axis labels | ``ax.set_xticks()`` | ``plt.xlabel()`` | +# | X-axis labels | ``ax.set_xticks()`` | ``plt.xticks()`` | # | | ``ax.set_xticklabels()`` | | # +-----------------------+--------------------------+------------------------+ -# | Y-axis labels | ``ax.set_yticks()`` | ``plt.ylabel()`` | +# | 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. 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()`` | # +-----------------------+--------------------------+------------------------+ # +# # The term ``ax`` refers to an assigned variable for a specific Axes. Using # explicit programming requires additional tasks of setting objects prior to # assigning labels. Whereas with implicit programming, the module manages @@ -428,7 +449,8 @@ def autopct_format(percent, group): """ value = int(percent/100.*np.sum(group)) return f'${value:<4}\n{percent:1.1f}%' -# This function is used as a lambda for formatting labels in wedges. +# This function is used in conjunction with the functools partial function +# for formatting labels in wedges. ############################################################################## # @@ -473,9 +495,9 @@ def autopct_format(percent, group): # There are minor differences in the method names. Overall, each method # performs the same action through the different approaches. # -# These pie charts are simple in that there is not much distinguishing -# information. Keyword arguments and Artists add the ability to implement -# more ways of displaying content. +# 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 # ^^^^^^^^^^^^^^^^^^^^^^^^ @@ -517,10 +539,11 @@ def autopct_format(percent, group): ############################################################################## # -# In the pie chart below, there are additional keyword arguments to further +# 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 -# :ref:`legend-guide` +# `Legend Guide +# `_ # Explicit @@ -534,9 +557,10 @@ def autopct_format(percent, group): # in removing redundant information from the previous # pie chart. explode=explode, - autopct=lambda pct: autopct_format(pct, budget), + autopct=partial(autopct_format, group=budget), # The autopct keyword argument in this instance uses a - # function in a lambda to return a formatted string. + # function callable with the functools.partial function + # to return a formatted string. See Note below for more. startangle=45, pctdistance=0.85, # The pctdistance keyword argument places the autopct @@ -553,8 +577,8 @@ def autopct_format(percent, group): shadow=True) wedges, texts, autotexts = budget_pie -# The pie() method unpacks into three objects, wedges, texts, and autotexts. -# These Artists have their own methods for addtional customization. +# The pie() method unpacks into three Artist objects, wedges, texts, and +# autotexts. These Artists have their own methods for addtional customization. ax.legend(wedges, # The wedges variable unpacked from the method serve as the handles @@ -589,7 +613,17 @@ def autopct_format(percent, group): ############################################################################## # +# .. 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 a function with one fewer argument. For +# details about the functools module, see +# `functools +# `_. # # Multiple Graphs within a Figure # ------------------------------- @@ -650,72 +684,43 @@ def autopct_format(percent, group): # approach must refer to an explicitly generated Axes after creating both the # Figure and Axes. # -# In the unpacking process, numerous Axes can also be assigned to the single -# variable. To reference a specific Axes, you can index the location of the -# respective Axes as a matrix through the single variable as well. +# In the unpacking process, numerous 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].plot([1,2,3],[1,2,3]) +# ax[0,1].plot([3,2,1],[3,2,1]) +# ax[1,0].plot([3,2,1],[3,2,1]) +# ax[1,1].plot([1,2,3],[1,2,3]) # # .. note:: # -# The code below demonstrates indexing multiple Axes. +# The method `~.subplot_mosaic` also works to label Axes +# with contextual names. The link contains more info for using the method. +# Below is a code example. # :: # -# fig, ax = plt.subplots(2,2) +# fig = plt.figure() +# ax_dict = fig.subplot_mosaic([['bar', 'plot'], +# ['hist', 'image']]) # -# ax[0,0].plot([1,2,3],[1,2,3]) -# ax[0,1].plot([3,2,1],[3,2,1]) -# ax[1,0].plot([3,2,1],[3,2,1]) -# ax[1,1].plot([1,2,3],[1,2,3]) +# 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 # ^^^^^^^^ - -# Implicit with pyplot - -plt.subplot(1, 2, 1) -# Module implicitly manages a matrix size of (1, 2) for row & column -# to work on the first implicit Axes. - -plt.plot(x, y1, label='Income') -plt.plot(x, y2, label='Checking') -plt.plot(x, y3, color='green', label='Savings') -# Module plots data on first implicit Axes. - -plt.xticks(x, months, rotation=270) -plt.title('2009', fontsize='small') -# Module methods generate parts of Figure for first implicit Axes. - -plt.subplot(1, 2, 2) -# Module implicitly manages matching matrix size to work on second implicit -# Axes. - -plt.plot(x, y1, label='Income') -plt.plot(x, y4, label='Checking') -plt.plot(x, y5, color='green', label='Savings') -# Module plots data on second implicit Axes. - -plt.xticks(x, months, rotation=270) -plt.title('2009', fontsize='small') -plt.legend(bbox_to_anchor=(1, 1), loc='upper left') -# Module methods generate parts of Figure for second implicit Axes. - -plt.suptitle('Personal Financial Tracking') -plt.tight_layout() -# Module methods for managing Figure elements. - -plt.show() -# Module displays the Figure. - -############################################################################## -# -# The ``pyplot`` example above uses two Axes to graph data. In each instance, -# Matplotlib auotmatically manages the specific Axes so that each action of -# plotting data does not interfere with the previous instance. -# -# .. note:: # -# There are limitations for customizing the implicit approach without -# referencing specific Axes and Artists within the Figure. For more -# advanced configurations, the explicit approach is recommended. +# 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 users to use explicit programming for +# these tasks. # # Generalized Function Guidelines # ------------------------------- From b55966d687742a31071cd36eb4d1e4018ba748d2 Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Wed, 2 Dec 2020 11:18:35 -0800 Subject: [PATCH 10/25] style_guide.rst referenced in toctree added basic line plot image for getting_started.py draft complete for review --- doc/_static/getting_started_example.png | Bin 0 -> 21222 bytes doc/devel/index.rst | 2 + doc/devel/style_guide.rst | 108 ++++---- tutorials/introductory/getting_started.py | 304 +++++++++++++--------- 4 files changed, 241 insertions(+), 173 deletions(-) create mode 100644 doc/_static/getting_started_example.png diff --git a/doc/_static/getting_started_example.png b/doc/_static/getting_started_example.png new file mode 100644 index 0000000000000000000000000000000000000000..a9ca8c151d52f100c6b02e6ed9ebc1bb916adb43 GIT binary patch literal 21222 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⁡tBI`Q4U%%*C=?L;<`{Q z3ABcrX*B5dt5@bop-#wE^TbJ6jxB+224nV_p9rLS~9b9Eek{6wCGs;DlC8}rLR+&-*gn=S93*0CZ zo-5<;wj0kP&VLxlW8TC1KZKzVE2uzdmNTz^o=ViC%%W)YnEk@Q*3&We zHU8as%DweUe+TL`!OCICYW5S~zI`htmkd1#9gI3J1MQAj<+qDB_>b52MBtaF z?%ilQjr0VACIFk;6uQoXbm;g%D)BiO&Nov-YtA4IY{M}}rGe11`3>m90l8JQ7NPME zqFfSeHSvS(p2~aoRE0(MHw|!LO#`9faM)l%>wyz`&sA98z7)F!Dvk_#-2qhZ6ZoXw zPz&VzIB*2_C0O(!$YcbDho@_TJ3n+XGc~n^Lr}1!qc=gP+$9B!8ZOXEk9L_WJ2s`+ zFw`xf-R~jn+Fg)hrRL>ircuk?}7K0`Q(CSIS`XpH=oWM@(-?JapxI2Dm zr#6N0$w8=nD*_#LwzBvG9Y|+!1?HLwNl88OC1z-*qd!G6_a;EpNF0Xuw_Aud&AK}~m7oD8i@VmM&*opP=hEGBQGS*Kr<_HkF52Bz22?zkCcXL6J`IJ62bAFOrY{>fC9Lk~0_65VpQ40=q@YI!uGxBjcMBXR z-EcRPYkjsMP4y~-8u$aaR;gue(^ey~g0Mznd}``KN=nKdQ`6K-^-iEs`2o<3fz1@| z(yCRG6Mi%RWjC_1jm2Tht_;l{CupPfix6_8f{noo*{vT4XsT~M!W9qD&*=xnB+>Iw!sCOao7%$z4O$>O>NQ0Q_w%DIz<^Cj`b}d2q85<8TmVR}l@r~2`1R{o zN;5!ClS`|v;J1APSXk+H$F;-&a8Mk0?E@eQHlz*tk@n zGfkDtNeX%g+*o;~m)rYhe0*F=)E2Ua6iVA+_l@%?NvXlZd(hFw{@!}me7%zo5JZt(q+-W^y7>-C@NFQbNmln~3w$&I1io_TT} z9u<0&mHYQ@EPp*$3uo33IGRC?580hUi@`V03`z+{`?P2!9C|9?X7hp|`pgV6vrm;cnehN>b!?)eMbC4U5f}@wB?Q{NO}xf zMFgijhF#{^;y}ec{Nr3BIRm&01tg1l=@nm=Ofcj=md#VacH8dA3ZEWy?;nd6xT4bjNvVOgPR68)l>i+(IC-~D= z*C>BG;#NLBOwdI&cqOHTsGHT--oUMH1HdRV&}Z1qcGYiAhFLNXS^y>+MY(sMASUKc zS532SWGkeE95VCCc@+nSRlt}n=MA)@1>oCyvgy15w36Q$tM&7Pyn+&7j}I*kEA8Jc z#%@6#SMg&Ru5U9QaGA@v0~|78$3Ae(h*E8ztHi8_U0hM(-L@{g*}-O=C>8p5fn@oC z&E^8!Zz7%0)Upe+3gx;tW_H)lLf$Ux)dPKy|3_Sa_~C%aT=R`N>Ffnc7#M<)kiDIG I>%r6i2j-sNH2?qr literal 0 HcmV?d00001 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 index a8f6872f1e0a..9e8485d14f2c 100644 --- a/doc/devel/style_guide.rst +++ b/doc/devel/style_guide.rst @@ -19,28 +19,34 @@ There are several key terms in Matplotlib that are standards for reliability and consistency in documentation. They are case-sensitive and are not interchangeable. -+----------------------+--------------------------+-------------------------+ -| Term | Description | Correct | Incorrect | -+----------------------+--------------------------+-------------------------+ -| Figure | Workign space for | | | -| | programming. | | | -+----------------------+--------------------------+-------------------------+ -| Axes | Subplots within Figure. | | | -| | Contains Figure elements | | | -| | and is responsible for | | | -| | plotting and configuring | | | -| | additional details. | | | -+----------------------+--------------------------+-------------------------+ -| Axis | Refers to visible object | | | -| | corresponding to labeling| | | -| | of plotted data. | | | -+----------------------+--------------------------+-------------------------+ -| Artist | Broad Matplotlib object | | | -| | that displays visuals. | | | -+----------------------+--------------------------+-------------------------+ -| Object Oriented | Explicit approach of | | | -| Programming (OOP) | programing in Matplotlib.| | | -+----------------------+--------------------------+-------------------------+ ++------------------+--------------------------+--------------+--------------+ +| Term | Description | Correct | Incorrect | ++==================+==========================+==============+==============+ +| Figure | Matplotlib working space |- One Figure |- One figure | +| | for programming. |- 11 Figures |- 11 figures | ++------------------+--------------------------+--------------+--------------+ +| Axes | Subplots within Figure. | - One Axes | - One axes | +| | Contains Figure elements | - Four Axes | - Four Axeses| +| | and is responsible for | - 32 Axes | - 32 Axii | +| | plotting and configuring | | | +| | additional details. | | | ++------------------+--------------------------+--------------+--------------+ +| Artist | Broad Matplotlib object | - One Artist | - One artist | +| | that displays visuals. | - Two Artists| - Two artists| ++------------------+--------------------------+--------------+--------------+ +| Axis | Refers to visible object | - One Axis | - One axis | +| | corresponding to labeling| - Four Axis | - Four Axises| +| | of plotted data. | objects | - 32 Axes | ++------------------+--------------------------+--------------+--------------+ +| 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 | ++------------------+--------------------------+--------------+--------------+ Grammar @@ -52,11 +58,11 @@ The audience is the "user" in the documentation. A "user" is a person programming in Python with the Matplotlib library. Use second-person sentences for instructions directed at user for specifying -an action. +an action or a possessive reference. +------------------------------------+------------------------------------+ | Correct | Incorrect | -+------------------------------------+------------------------------------+ ++====================================+====================================+ | Users install Matplotlib from the | You can install Matplotlib from the| | source directory using the Python | source directory. You can find | | ``pip`` installer program. | additional support if you are | @@ -71,12 +77,12 @@ 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. This should be the basic | -| transforming it thorugh functions | fundamental idea behind Matplotlib | -| and methods. | for visualizations. | +| 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 @@ -86,7 +92,7 @@ related to warning prompts. +------------------------------------+------------------------------------+ | Correct | Incorrect | -+------------------------------------+------------------------------------+ ++====================================+====================================+ | The function ``plot`` generates the| The graph is generated by the | | graph. | ``plot`` function. | +------------------------------------+------------------------------------+ @@ -97,13 +103,13 @@ related to warning prompts. Sentence structure ^^^^^^^^^^^^^^^^^^ -Write wih short sentences using Subject-Verb-Object order regularly. Limit +Write with short sentences using Subject-Verb-Object order regularly. Limit how frequently coordinating conjunctions appear in sentences. Avoid pronoun referenes and subordinating conjunctive prhases. +------------------------------------+------------------------------------+ | 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 | @@ -115,18 +121,23 @@ referenes and subordinating conjunctive prhases. | 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 ========== Matplotlib uses reStructuredText Markup for documentation. Sphinx helps to -transform these documents into proper formats for access and visibility. +transform these documents into appropriate formats for accessibility and +visibility. reStructuredText standards -------------------------- - -https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html -https://docutils.sourceforge.io/docs/user/rst/quickref.html +- https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html +- https://docutils.sourceforge.io/docs/user/rst/quickref.html Lists @@ -136,19 +147,21 @@ Numbered Lists are exclusively for performing actions in specific order. +------------------------------------+------------------------------------+ | Correct | Incorrect | -+------------------------------------+------------------------------------+ ++====================================+====================================+ | The example uses three graphs. | The example uses three graphs. | -| - Bar | 1. Bar | -| - Line | 2. Line | -| - Pie | 3. Pie | +------------------------------------+------------------------------------+ -| These three steps help to get | The following steps are important | +| - 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. | ++------------------------------------+------------------------------------+ +| 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. | +------------------------------------+------------------------------------+ Additional Resources @@ -158,8 +171,3 @@ Additional Resources * `IBM Style Guide `_ * `Google Developer Style Guide `_ -+------------------------------------+------------------------------------+ -| Correct | Incorrect | -+------------------------------------+------------------------------------+ -| | | -+------------------------------------+------------------------------------+ diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py index 725c21c24d7f..8894b899be29 100644 --- a/tutorials/introductory/getting_started.py +++ b/tutorials/introductory/getting_started.py @@ -6,8 +6,8 @@ Getting Started *************** -This tutorial covers basic usage patterns and best-practices to help you get -started with Matplotlib. +This tutorial covers basic usage patterns and best practices to help get +started using Matplotlib. """ ############################################################################## @@ -42,13 +42,16 @@ # | configurations of graphs. | environments. | # +------------------------------------+------------------------------------+ # | Recommended to new users for | Most useful for users coming from | -# | learning fundamentals. | MATLAB. | +# | 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 can call methods on each item. Most users benefit using +# 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. # @@ -56,13 +59,18 @@ # plots and for interactive environments, such as Jupyter Notebooks. Users # familiar with MATLAB or would like to have Matplotlib automatically create # and manage parts of the visualization benefit from using the ``pyplot`` -# module to graph data. New users to Matplotlib may experience difficulty -# understanding how elements of a visualization work together when using the -# implicit approach. +# module to graph data. 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) | | @@ -80,6 +88,11 @@ # | | the data. | # +------------------------------------+------------------------------------+ # +# .. image:: ../../_static/getting_started_example.png +# +# .. note:: +# +# The example image is identical for both explicit and implicit code. # # Requirements # ============ @@ -114,23 +127,30 @@ # # 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 following -# code. +# 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 abbreviation as ``plt`` is the standard shortcut. +# + import numpy as np from functools import partial ############################################################################## # -# - 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. # - NumPy is a common scientific Python library that benefits users with -# additional robust tools for manipulating data. +# additional tools for manipulating data. # - The ``functools`` module helps manage functions that act on or return -# otherfunctions. The `Pie Chart Examples`_ section contains more +# other functions. The `Pie Chart Examples`_ section note contains more # information about the purpose of this module. # # Two Approaches for Creating Graphs @@ -144,13 +164,13 @@ # +------------------------------------+------------------------------------+ # | Explicit | Implicit | # +====================================+====================================+ -# | * Code has explicit references to | * The programming is designed to | +# | - 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 | +# | - 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. | @@ -170,7 +190,7 @@ # ---- # # The Matplotlib library manages data in the form of iterables and/or -# sequenced items. These can also take the form of NumPy arrays like +# 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. # @@ -197,17 +217,18 @@ # Other containers, such as data objects from various libraries, may not # work as intended. # -# 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 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) # -------------------------------------------- # -# To use explicit programming for Matplotlib involves using a single instance -# of the ``pyplot`` module. This unpacks a set of an explicit Figure and Axes. -# There can be more than one Axes; however, each Axes can only be on one -# Figure. +# Explicit programming for Matplotlib involves using a single instance of the +# ``pyplot`` module. This unpacks a set of an explicit Figure and Axes. +# 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 parts of a Figure. These @@ -243,25 +264,23 @@ ############################################################################## # -# For the OOP example, the Figure and Axes are unpacked from the module using -# a single instance of ``pyplot``. This convention uses ``plt.subplots()`` -# and defaults to one Figure, ``fig``, and one Axes, ``ax``. The -# `Configuration`_ section below contains additional information about -# manipulating visuals, multiple visulizations, and other modifications. +# The module for the OOP example unpacks the Figure and Axes using a single +# instance of ``pyplot``. This convention uses ``plt.subplots()`` and defaults +# to one Figure, ``fig``, and one Axes, ``ax``. The `Configuration`_ section +# below contains additional information about manipulating visuals, multiple +# visulizations, and other modifications. # -# Using the OOP approach allows for ``fig`` and ``ax`` to use separate methods -# to manipulate the visualization. Instead of using the module ``pyplot`` for -# all instances of managing objects, the specfic Axes refers to OOP usage and -# manages the respective data. +# Using explicit programming allows for ``fig`` and ``ax`` to use separate +# methods to manipulate the visualization. Specific Figures and Axes refer to +# methods in OOP conventions for managing respective data. # # Implicit: ``pyplot`` # -------------------- # # Implicit programming for Matplotlib centers around using the ``pyplot`` -# module. The Figure and Axes are automatically generated by the module. -# The methods and functions within the module take incoming data as arguments. -# Additional parts of the Figure are also available through the module -# methods. +# module. The module automatically generates 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 @@ -287,7 +306,7 @@ # 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 OOP approach. +# use different methods from the explicit approach. # # .. note:: # @@ -308,15 +327,29 @@ # # 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 see how the programming operates, the source code is +# visualization. To view the programming for the image, the source code is # available at :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. +# 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. # -# .. image:: ../../_static/anatomy.png + +fig, ax = plt.subplots() +# Explicit Figure and Axes unpacked from module function. +# No data transformed for visualizations. +plt.show() +# Module displays empty Figure and Axes. + +############################################################################## # # :class:`~matplotlib.figure.Figure` # @@ -330,11 +363,11 @@ # Figure can contain multiple Axes, but each Axes is specific to one # Figure. # -# In a Figure, each Axes can contain any number of visual elements. An Axes may -# have 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 a Figure, each Axes contains any number of visual 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. # # Other Components # ^^^^^^^^^^^^^^^^ @@ -349,20 +382,17 @@ # .. note:: # # Axes and Axis are not synonymous. Axis refers to -# :class:`~matplotlib.axis.Axis`. +# :class:`~matplotlib.axis.Axis`, a separate Matplotlib object. # # Manipulating Artists # -------------------- # # With simple plots, Matplotlib automatically generates the basic elements of -# a graph. For more control over the visual, use Artists and its methods. +# 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 its own respective methods and functions. -# Explicit and implicit approaches use different methods and are not -# interchangeable. -# -# The table below compares formatter Artists and their different methods. +# objects. As Artists, each has respective methods and functions. Explicit and +# implicit approaches use different methods and are not interchangeable. # # +-----------------------+--------------------------+------------------------+ # | Artist | Explicit | Implicit | @@ -372,18 +402,31 @@ # | | artists. | on most recent Figure | # | | | or Axes. | # +-----------------------+--------------------------+------------------------+ -# | X-axis labels | ``ax.set_xticks()`` | ``plt.xticks()`` | +# +# 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()`` | +# | 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. These -# methods often overlap in naming conventions and make use of identical keyword -# arguments and other parameters. +# 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 | @@ -395,37 +438,31 @@ # | Legend (Axes) | ``ax.legend()`` | ``plt.legend()`` | # +-----------------------+--------------------------+------------------------+ # +# For complete information about available methods, refer to the table below. # -# The term ``ax`` refers to an assigned variable for a specific Axes. Using -# explicit programming requires additional tasks of setting objects prior to -# assigning labels. Whereas with implicit programming, the module manages -# those tasks without specification. -# -# For additional information about available methods, see the table below. -# -# +------------------------------------+------------------------------------+ -# | Explicit | :class:`matplotlib.axes.Axes` | # +------------------------------------+------------------------------------+ -# | Implicit | :mod:`matplotlib.pyplot` | +# | Explicit | Implicit | +# +====================================+====================================+ +# | :class:`matplotlib.axes.Axes` | :mod:`matplotlib.pyplot` | # +------------------------------------+------------------------------------+ # # # Pie Chart Examples # ------------------ # -# Matplotlib pie charts create wedges based on data and manipulate the size of -# the Artists based on the ratio of the slice to the sum of the data. The -# ``.pie()`` method is similar for both explicit and implicit approaches. +# 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. # -# Data +# Sample data for monthly spending averages. budget = [475, 300, 125, 50] -# Data points are represented in wedge size compared to total sum. +# Data points correspond to wedge size as a ratio of total sum. # Matplotlib methods calculate these values automatically based on input. descriptions = ['Shared house\nin Philadelphia', @@ -433,7 +470,7 @@ 'Groceries\n& takeout', 'Treasury bonds'] categories = ['Rent', 'Bills', 'Food', 'Savings'] -# These lists of strings contribute to labeling corresponding data. +# Lists of strings contribute to labeling corresponding data. colors = ['#1f77b4', '#ff7f0e', '#d62728', '#2ca02c'] # Hex color codes determine respective wedge color. @@ -446,10 +483,23 @@ def autopct_format(percent, group): """ Takes percent equivalent and calculates original value from data. Returns fstring 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)) - return f'${value:<4}\n{percent:1.1f}%' -# This function is used in conjunction with the functools partial function + formatted = f'${value:<4}\n{percent:1.1f}%' + return formatted +# This function operates in conjunction with the functools partial function # for formatting labels in wedges. ############################################################################## @@ -460,7 +510,7 @@ def autopct_format(percent, group): # The following two plots are identical. Both the explicit and implicit # approaches generate the exact same plot when using the same variables. # -# See `matplotlib.axes.Axes.pie` and `matplotlib.pyplot.pie` for more +# Review `matplotlib.axes.Axes.pie` and `matplotlib.pyplot.pie` for more # information about the APIs for explicit and implicit, respectively. # Explicit @@ -484,7 +534,7 @@ def autopct_format(percent, group): plt.legend() plt.title('Average Monthly Income Expenses') plt.axis('equal') -# The pyplot module contains an identical method for aspect ratio setting. +# The pyplot module contains an identical method for setting aspect ratio. plt.show() @@ -504,7 +554,7 @@ def autopct_format(percent, group): # # Many methods contain optional keyword arguments for further configuration. # In the examples for explicit programming below, there are values and -# functions in keyword arguments that format the Artists. These changes also +# 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 @@ -519,11 +569,11 @@ def autopct_format(percent, group): colors=colors, labels=categories, explode=explode, - # The explode keyword argument uses the explode variable from data to + # The explode keyword argument uses the explode variable data to # separate respective wedges from the center. autopct='%1.1f%%', # The autopct keyword argument takes formatting strings and functions - # to generate text within the wedge. '%1.1f%%' uses string formatters. + # to generate text within the wedge. '%1.1f%%' is a string formatter. startangle=-80, # The startangle keyword argument changes where the first wedge spans. # Angles start at 0 degrees on the X-axis and move counterclockwise. @@ -543,7 +593,7 @@ def autopct_format(percent, group): # customize the visual. Also, the ``legend`` as an Artist has parameters that # enable more specification for the information displayed. For more, see the # `Legend Guide -# `_ +# `_. # Explicit @@ -552,15 +602,14 @@ def autopct_format(percent, group): budget_pie = ax.pie(budget, colors=colors, labels=descriptions, - # Instead of using the categories data as a label, the - # descriptions act as text to label the wedges. This aids - # in removing redundant information from the previous + # Descriptions now act as text labels for the wedges. + # This removes redundant information from the previous # pie chart. explode=explode, autopct=partial(autopct_format, group=budget), - # The autopct keyword argument in this instance uses a - # function callable with the functools.partial function - # to return a formatted string. See Note below for more. + # The autopct keyword argument calls a function as well. + # The functools partial function returns a formatted + # string. See Note below for more. startangle=45, pctdistance=0.85, # The pctdistance keyword argument places the autopct @@ -570,21 +619,21 @@ def autopct_format(percent, group): # The labeldistance keyword argument specifies the float as # a percentage of the radius to place labels. wedgeprops=dict(width=0.3), - # The wedgeprops keyword argument can also take - # dictionaries to pass on to the artists. In this - # instance, the float for width sets the wedge size as a - # percentage of the radius starting from the outer edge. + # The wedgeprops keyword argument also takes dictionaries + # to pass on to the artists. The float for width sets the + # wedge size as a percentage of the radius starting from + # the outer edge. shadow=True) wedges, texts, autotexts = budget_pie -# The pie() method unpacks into three Artist objects, wedges, texts, and -# autotexts. These Artists have their own methods for addtional customization. +# The pie() method unpacks into three Artist objects. The Artists wedges, +# texts, and autotexts have their own methods for addtional customization. ax.legend(wedges, # The wedges variable unpacked from the method serve as the handles # for the legend. categories, - # The information from the data categories correspond to each + # The information from the data categories corresponds to each # respective wedge instead of redundant labeling from the previous # pie chart. title='Categories', @@ -592,13 +641,12 @@ def autopct_format(percent, group): bbox_to_anchor=(0.125, 0.5), # This keyword argument in conjunction with loc places the legend # at a specific point. The tuple floats are coordinates for the - # Figure. + # Figure in terms of row and column of Axes. loc='center right' # The loc keyword argument works in conjunction with bbox_to_anchor - # and in this instance, determines the part of the legend for - # placement. Without bbox_to_anchor, Matplotlib automatically - # manages coordinates in relation to specifications of the - # parameters of loc. + # and determines the part of the legend for placement. Without + # bbox_to_anchor, Matplotlib automatically manages coordinates in + # relation to specifications of the parameters of loc. ) ax.set_title('Average Monthly Income Expenses') @@ -631,7 +679,10 @@ def autopct_format(percent, group): # 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. The third argument represents the specific +# 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, @@ -647,7 +698,7 @@ def autopct_format(percent, group): figsize=[8, 4], constrained_layout=True) # Figure and two Axes unpacked from arguments (1, 2) as row & column. -# Keyword arguments provide additional details of sharing Y-axis, Figure size +# Keyword arguments provide additional details of sharing Y-Axis, Figure size # and layout formatting. fig.suptitle('Personal Financial Tracking \'09 - \'10') @@ -662,7 +713,7 @@ def autopct_format(percent, group): ax1.set_xticklabels(months, rotation=270) ax1.set_title('2009', fontsize='small') ax1.legend(loc='upper left') -# First explicit Axes object uses separate methods for ticks on the X-axis, +# First explicit Axes object uses separate methods for ticks on the X-Axis, # title, and legend. Keyword arguments are for additional configurations. ax2.plot(x, y1, label='Income') @@ -680,9 +731,9 @@ def autopct_format(percent, group): ############################################################################## # -# The OOP example above also uses two Axes to graph the data. However, the OOP -# approach must refer to an explicitly generated Axes after creating both the -# Figure and Axes. +# 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, numerous Axes are assigned to a single variable. # To reference a specific Axes, indexing the location of the respective Axes @@ -697,21 +748,21 @@ def autopct_format(percent, group): # ax[1,0].plot([3,2,1],[3,2,1]) # ax[1,1].plot([1,2,3],[1,2,3]) # -# .. note:: # -# The method `~.subplot_mosaic` also works to label Axes -# with contextual names. The link contains more info for using the method. -# Below is a code example. -# :: +# 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']]) +# 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]]) +# 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 # ^^^^^^^^ @@ -719,14 +770,14 @@ def autopct_format(percent, group): # 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 users to use explicit programming for -# these tasks. +# The Matplotlib community recommends using explicit programming for these +# tasks. # # Generalized Function Guidelines # ------------------------------- # -# For users with that have recurring plots and graphs, the Matplotlib -# community recommends a signature function similar to the format below. +# 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): @@ -758,3 +809,10 @@ def my_plotter(ax, data1, data2, param_dict): # 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. +# From ddfeb4a72028c6f5d6c807b3a53f271bd4320fe3 Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Wed, 2 Dec 2020 16:52:03 -0800 Subject: [PATCH 11/25] style_guide & getting_started modifications links in tables, proofreading, supplemental section, 2nd person subject --- doc/devel/style_guide.rst | 56 +++++++++++++---------- tutorials/introductory/getting_started.py | 40 +++++++++++++--- 2 files changed, 65 insertions(+), 31 deletions(-) diff --git a/doc/devel/style_guide.rst b/doc/devel/style_guide.rst index 9e8485d14f2c..01a59d47ec08 100644 --- a/doc/devel/style_guide.rst +++ b/doc/devel/style_guide.rst @@ -16,27 +16,30 @@ Terminology ----------- There are several key terms in Matplotlib that are standards for -reliability and consistency in documentation. They are case-sensitive and -are not interchangeable. +reliability and consistency in documentation. They are case-sensitive and are +not interchangeable. +------------------+--------------------------+--------------+--------------+ | Term | Description | Correct | Incorrect | +==================+==========================+==============+==============+ -| Figure | Matplotlib working space |- One Figure |- One figure | +| Figure_ | Matplotlib working space |- One Figure |- One figure | | | for programming. |- 11 Figures |- 11 figures | +------------------+--------------------------+--------------+--------------+ -| Axes | Subplots within Figure. | - One Axes | - One axes | +| Axes_ | Subplots within Figure. | - One Axes | - One axes | | | Contains Figure elements | - Four Axes | - Four Axeses| | | and is responsible for | - 32 Axes | - 32 Axii | | | plotting and configuring | | | | | additional details. | | | +------------------+--------------------------+--------------+--------------+ -| Artist | Broad Matplotlib object | - One Artist | - One artist | +| Artist_ | Broad Matplotlib object | - One Artist | - One artist | | | that displays visuals. | - Two Artists| - Two artists| +------------------+--------------------------+--------------+--------------+ -| Axis | Refers to visible object | - One Axis | - One axis | -| | corresponding to labeling| - Four Axis | - Four Axises| -| | of plotted data. | objects | - 32 Axes | +| Axis_ | Human-readable single | - One Axis | - One Axis | +| | dimensional object | object | - One axis | +| | of reference marks | - Four Axis | - Four Axises| +| | containing ticks, tick | objects | - 32 Axes | +| | labels, spines, and | - 32 Axis | | +| | edges. | objects | | +------------------+--------------------------+--------------+--------------+ | Explicit, | Explicit approach of | - Explicit | - object | | Object Oriented | programing in Matplotlib.| - explicit | oriented | @@ -48,26 +51,29 @@ are not interchangeable. | | | | interface | +------------------+--------------------------+--------------+--------------+ +.. _Figure: :class:`~matplotlib.figure.Figure` +.. _Axes: :class:`~matplotlib.axes.Axes` +.. _Artist: :class:`~matplotlib.artist.Artist` +.. _Axis: :class:`matplotlib.axis.Axis` + Grammar ------- Subject ^^^^^^^ -The audience is the "user" in the documentation. A "user" is a person -programming in Python with the Matplotlib library. - -Use second-person sentences for instructions directed at user for specifying -an action or a possessive reference. +Use second-person imperative sentences for directed instructions specifying an +action. Second-person pronouns are for individual-specific contexts and +possessive reference. +------------------------------------+------------------------------------+ | Correct | Incorrect | +====================================+====================================+ -| Users install Matplotlib from the | You can install Matplotlib from the| -| source directory using the Python | source directory. You can find | -| ``pip`` installer program. | additional support if you are | -| Depending on your operating system,| having troulbe with your | -| you may need additional support. | installation. | +| 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 @@ -105,7 +111,7 @@ Sentence structure ^^^^^^^^^^^^^^^^^^ Write with short sentences using Subject-Verb-Object order regularly. Limit how frequently coordinating conjunctions appear in sentences. Avoid pronoun -referenes and subordinating conjunctive prhases. +references and subordinating conjunctive phrases. +------------------------------------+------------------------------------+ | Correct | Incorrect | @@ -136,14 +142,14 @@ visibility. reStructuredText standards -------------------------- -- https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html -- https://docutils.sourceforge.io/docs/user/rst/quickref.html +- `reStructuredText Specifications `_ +- `Quick Reference Document `_ Lists ^^^^^ -Bulleted lists are for items that do not require sequencing. -Numbered Lists are exclusively for performing actions in specific order. +Bulleted lists are for items that do not require sequencing. Numbered lists are +exclusively for performing actions in a determined order. +------------------------------------+------------------------------------+ | Correct | Incorrect | @@ -167,7 +173,7 @@ Numbered Lists are exclusively for performing actions in specific order. Additional Resources ==================== -* `Red Hat Style Guide `_ -* `IBM Style 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 index 8894b899be29..993aaff08c06 100644 --- a/tutorials/introductory/getting_started.py +++ b/tutorials/introductory/getting_started.py @@ -369,6 +369,10 @@ # contain multiple types of visualizations of data on a single Axes. Each of # these types are specific to the Axes they are in. # +# Matplotlib Axes also intergrate 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 # ^^^^^^^^^^^^^^^^ # @@ -438,7 +442,32 @@ # | Legend (Axes) | ``ax.legend()`` | ``plt.legend()`` | # +-----------------------+--------------------------+------------------------+ # -# For complete information about available methods, refer to the table below. +# 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 Artists, refer to the +# table below. # # +------------------------------------+------------------------------------+ # | Explicit | Implicit | @@ -592,8 +621,7 @@ def autopct_format(percent, group): # 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 -# `Legend Guide -# `_. +# :doc:`/tutorials/intermediate/legend_guide`. # Explicit @@ -743,10 +771,10 @@ def autopct_format(percent, group): # # fig, ax = plt.subplots(2,2) # -# ax[0,0].plot([1,2,3],[1,2,3]) +# ax[0,0].bar([1,2,3],[1,2,3]) # ax[0,1].plot([3,2,1],[3,2,1]) -# ax[1,0].plot([3,2,1],[3,2,1]) -# ax[1,1].plot([1,2,3],[1,2,3]) +# 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 From 0ba4f1e3e384d688106966931e73521734057cd5 Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Thu, 3 Dec 2020 14:38:45 -0800 Subject: [PATCH 12/25] style_guide.rst typos, table section, terminology getting_started.py embedded plot, concise language, formatting --- doc/_static/getting_started_example.png | Bin 21222 -> 0 bytes doc/devel/style_guide.rst | 37 +++++++++++++++- tutorials/introductory/getting_started.py | 49 ++++++++++++---------- 3 files changed, 64 insertions(+), 22 deletions(-) delete mode 100644 doc/_static/getting_started_example.png diff --git a/doc/_static/getting_started_example.png b/doc/_static/getting_started_example.png deleted file mode 100644 index a9ca8c151d52f100c6b02e6ed9ebc1bb916adb43..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 21222 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⁡tBI`Q4U%%*C=?L;<`{Q z3ABcrX*B5dt5@bop-#wE^TbJ6jxB+224nV_p9rLS~9b9Eek{6wCGs;DlC8}rLR+&-*gn=S93*0CZ zo-5<;wj0kP&VLxlW8TC1KZKzVE2uzdmNTz^o=ViC%%W)YnEk@Q*3&We zHU8as%DweUe+TL`!OCICYW5S~zI`htmkd1#9gI3J1MQAj<+qDB_>b52MBtaF z?%ilQjr0VACIFk;6uQoXbm;g%D)BiO&Nov-YtA4IY{M}}rGe11`3>m90l8JQ7NPME zqFfSeHSvS(p2~aoRE0(MHw|!LO#`9faM)l%>wyz`&sA98z7)F!Dvk_#-2qhZ6ZoXw zPz&VzIB*2_C0O(!$YcbDho@_TJ3n+XGc~n^Lr}1!qc=gP+$9B!8ZOXEk9L_WJ2s`+ zFw`xf-R~jn+Fg)hrRL>ircuk?}7K0`Q(CSIS`XpH=oWM@(-?JapxI2Dm zr#6N0$w8=nD*_#LwzBvG9Y|+!1?HLwNl88OC1z-*qd!G6_a;EpNF0Xuw_Aud&AK}~m7oD8i@VmM&*opP=hEGBQGS*Kr<_HkF52Bz22?zkCcXL6J`IJ62bAFOrY{>fC9Lk~0_65VpQ40=q@YI!uGxBjcMBXR z-EcRPYkjsMP4y~-8u$aaR;gue(^ey~g0Mznd}``KN=nKdQ`6K-^-iEs`2o<3fz1@| z(yCRG6Mi%RWjC_1jm2Tht_;l{CupPfix6_8f{noo*{vT4XsT~M!W9qD&*=xnB+>Iw!sCOao7%$z4O$>O>NQ0Q_w%DIz<^Cj`b}d2q85<8TmVR}l@r~2`1R{o zN;5!ClS`|v;J1APSXk+H$F;-&a8Mk0?E@eQHlz*tk@n zGfkDtNeX%g+*o;~m)rYhe0*F=)E2Ua6iVA+_l@%?NvXlZd(hFw{@!}me7%zo5JZt(q+-W^y7>-C@NFQbNmln~3w$&I1io_TT} z9u<0&mHYQ@EPp*$3uo33IGRC?580hUi@`V03`z+{`?P2!9C|9?X7hp|`pgV6vrm;cnehN>b!?)eMbC4U5f}@wB?Q{NO}xf zMFgijhF#{^;y}ec{Nr3BIRm&01tg1l=@nm=Ofcj=md#VacH8dA3ZEWy?;nd6xT4bjNvVOgPR68)l>i+(IC-~D= z*C>BG;#NLBOwdI&cqOHTsGHT--oUMH1HdRV&}Z1qcGYiAhFLNXS^y>+MY(sMASUKc zS532SWGkeE95VCCc@+nSRlt}n=MA)@1>oCyvgy15w36Q$tM&7Pyn+&7j}I*kEA8Jc z#%@6#SMg&Ru5U9QaGA@v0~|78$3Ae(h*E8ztHi8_U0hM(-L@{g*}-O=C>8p5fn@oC z&E^8!Zz7%0)Upe+3gx;tW_H)lLf$Ux)dPKy|3_Sa_~C%aT=R`N>Ffnc7#M<)kiDIG I>%r6i2j-sNH2?qr diff --git a/doc/devel/style_guide.rst b/doc/devel/style_guide.rst index 01a59d47ec08..4b691993c9cb 100644 --- a/doc/devel/style_guide.rst +++ b/doc/devel/style_guide.rst @@ -93,7 +93,7 @@ or auxiliary verbs when possible. Voice ^^^^^ -Write in active sentences. Passive voice is best for situations or condtions +Write in active sentences. Passive voice is best for situations or conditions related to warning prompts. +------------------------------------+------------------------------------+ @@ -170,6 +170,41 @@ exclusively for performing actions in a determined order. | 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 ==================== diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py index 993aaff08c06..22f34abe9ba1 100644 --- a/tutorials/introductory/getting_started.py +++ b/tutorials/introductory/getting_started.py @@ -39,7 +39,7 @@ # +------------------------------------+------------------------------------+ # | Useful for repeated code use, | Helpful for quickly graphing data | # | generalization, robust | when using interactive | -# | configurations of graphs. | environments. | +# | configurations of visuals. | environments. | # +------------------------------------+------------------------------------+ # | Recommended to new users for | Most useful for users coming from | # | learning fundamentals. | MATLAB. Users already familiar with| @@ -77,8 +77,8 @@ # +====================================+====================================+ # | :: | :: | # | | | -# | fig, ax = plt.subplots() | plt.plot([1,2,3],[1,2,3]) | -# | ax.plot([1,2,3],[1,2,3]) | | +# | 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 | @@ -87,12 +87,16 @@ # | `.Axes.plot` plots the data. | elements and `.pyplot.plot` plots | # | | the data. | # +------------------------------------+------------------------------------+ -# -# .. image:: ../../_static/getting_started_example.png +# | .. 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 image is identical for both explicit and implicit code. +# The example graphs are identical for both explicit and implicit code. # # Requirements # ============ @@ -264,15 +268,18 @@ ############################################################################## # -# The module for the OOP example unpacks the Figure and Axes using a single -# instance of ``pyplot``. This convention uses ``plt.subplots()`` and defaults -# to one Figure, ``fig``, and one Axes, ``ax``. The `Configuration`_ section -# below contains additional information about manipulating visuals, multiple -# visulizations, and other modifications. +# The module ``pyplot`` for the OOP example unpacks the Figure and Axes. +# This convention uses ``plt.subplots()`` and defaults to one Figure, ``fig``, +# and one Axes, ``ax``. The variable names are common shorthand terms. 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 manipulate the visualization. Specific Figures and Axes refer to -# methods in OOP conventions for managing respective data. +# methods to manipulate the visualization. Specific Figures and Axes manage +# data components with their own respective methods. +# # # Implicit: ``pyplot`` # -------------------- @@ -327,8 +334,8 @@ # # 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 the programming for the image, the source code is -# available at :ref:`sphx_glr_gallery_showcase_anatomy.py`. +# visualization. To view source code for the image, see +# :ref:`sphx_glr_gallery_showcase_anatomy.py`. # # # .. image:: ../../_static/anatomy.png @@ -369,7 +376,7 @@ # contain multiple types of visualizations of data on a single Axes. Each of # these types are specific to the Axes they are in. # -# Matplotlib Axes also intergrate with other Python libraries. In Axes-based +# 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. # @@ -378,10 +385,10 @@ # # :class:`~matplotlib.artist.Artist` # -# Artists are broad Matplotlib objects that display visuals. These 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. +# 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:: # @@ -511,7 +518,7 @@ def autopct_format(percent, group): """ Takes percent equivalent and calculates original value from data. - Returns fstring of value new line above percentage. + Returns string of value new line above percentage. Parameters ---------- From 5af38d62410b74cbe56754610c18320b71da100a Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Fri, 4 Dec 2020 21:47:26 -0800 Subject: [PATCH 13/25] style_guide.rst table fix getting_started.py language clarifications --- doc/devel/style_guide.rst | 12 ++++++------ tutorials/introductory/getting_started.py | 16 ++++++++-------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/doc/devel/style_guide.rst b/doc/devel/style_guide.rst index 4b691993c9cb..c55809b9ab53 100644 --- a/doc/devel/style_guide.rst +++ b/doc/devel/style_guide.rst @@ -22,8 +22,8 @@ not interchangeable. +------------------+--------------------------+--------------+--------------+ | Term | Description | Correct | Incorrect | +==================+==========================+==============+==============+ -| Figure_ | Matplotlib working space |- One Figure |- One figure | -| | for programming. |- 11 Figures |- 11 figures | +| Figure_ | Matplotlib working space | - One Figure | - One figure | +| | for programming. | - 11 Figures | - 11 figures | +------------------+--------------------------+--------------+--------------+ | Axes_ | Subplots within Figure. | - One Axes | - One axes | | | Contains Figure elements | - Four Axes | - Four Axeses| @@ -31,8 +31,9 @@ not interchangeable. | | plotting and configuring | | | | | additional details. | | | +------------------+--------------------------+--------------+--------------+ -| Artist_ | Broad Matplotlib object | - One Artist | - One artist | -| | that displays visuals. | - Two Artists| - Two artists| +| Artist_ | Broad variety of | - One Artist | - One artist | +| | Matplotlib objects that | - Two Artists| - Two artists| +| | display visuals. | | | +------------------+--------------------------+--------------+--------------+ | Axis_ | Human-readable single | - One Axis | - One Axis | | | dimensional object | object | - One axis | @@ -145,7 +146,6 @@ reStructuredText standards - `reStructuredText Specifications `_ - `Quick Reference Document `_ - Lists ^^^^^ Bulleted lists are for items that do not require sequencing. Numbered lists are @@ -184,7 +184,7 @@ Markdown tables and the csv-table directive are not accepted. | | OK | Not OK | | | ------- | --------- | | | +----------+----------+ | | OK | Not OK | | | | | -+--------------------------------+----------------------------------------| ++--------------------------------+----------------------------------------+ | :: | :: | | | | | +----------+----------+ | .. csv-table:: | diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py index 22f34abe9ba1..71805b3bc1aa 100644 --- a/tutorials/introductory/getting_started.py +++ b/tutorials/introductory/getting_started.py @@ -229,10 +229,10 @@ # Explicit: Object Oriented Programming (OOP) # -------------------------------------------- # -# Explicit programming for Matplotlib involves using a single instance of the -# ``pyplot`` module. This unpacks a set of an explicit Figure and Axes. -# More than one Axes is configurable; however, each Axes only corresponds to a -# single Figure. +# Explicit programming for Matplotlib involves calling the method ``subplots`` +# in the ``pyplot`` module once. This unpacks a group of an explicit Figure and +# Axes. 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 parts of a Figure. These @@ -410,7 +410,7 @@ # +=======================+==========================+========================+ # | Visible elements from | Each specific Axes has | The ``pyplot`` module | # | rendered Figure. | its own method for | manages Artists based | -# | | artists. | on most recent Figure | +# | | Artists. | on most recent Figure | # | | | or Axes. | # +-----------------------+--------------------------+------------------------+ # @@ -655,7 +655,7 @@ def autopct_format(percent, group): # a percentage of the radius to place labels. wedgeprops=dict(width=0.3), # The wedgeprops keyword argument also takes dictionaries - # to pass on to the artists. The float for width sets the + # to pass on to the Artists. The float for width sets the # wedge size as a percentage of the radius starting from # the outer edge. shadow=True) @@ -703,8 +703,8 @@ def autopct_format(percent, group): # 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 a function with one fewer argument. For -# details about the functools module, see +# signature object then behaves as the same function with one fewer argument. +# For details about the functools module, see # `functools # `_. # From f679c00295e1d81a6a073c1d118ba238f1e1d874 Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Mon, 14 Dec 2020 17:44:42 -0800 Subject: [PATCH 14/25] Language for clarification, comments above or on same line of code --- tutorials/introductory/getting_started.py | 153 ++++++++++------------ 1 file changed, 71 insertions(+), 82 deletions(-) diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py index 71805b3bc1aa..2ca37c242c44 100644 --- a/tutorials/introductory/getting_started.py +++ b/tutorials/introductory/getting_started.py @@ -21,9 +21,7 @@ # 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 on the backend and is not user-facing. For more -# information regarding manipulating backend capabilities, see -# :ref:`backends`. +# 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 @@ -57,12 +55,12 @@ # # 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 would like to have Matplotlib automatically create -# and manage parts of the visualization benefit from using the ``pyplot`` -# module to graph data. 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. +# familiar with MATLAB or wish 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 # -------- @@ -240,31 +238,31 @@ # Explicit programming with OOP +# Assigning sample data to labeled variables. x = months y1 = income y2 = chk_acct_09 y3 = svg_acct_09 y4 = chk_acct_10 y5 = svg_acct_10 -# Assigning sample data to labeled variables. -fig, ax = plt.subplots() # 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') -# Single explicit Axes graphs multiple data points. +# 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() -# Explicit Axes use separate methods to manage parts of Figure. -plt.show() # The pyplot module displays the Figure. +plt.show() ############################################################################## # @@ -293,19 +291,19 @@ # 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 plots multiple data points on implicitly generated Axes. +# Module methods generate parts of Figure. plt.xlabel('Month') plt.ylabel('USD') plt.title("Personal Financial Tracking from 2009") plt.legend() -# Module methods generate parts of Figure. -plt.show() # The module displays the Figure. +plt.show() ############################################################################## # @@ -350,11 +348,12 @@ # without assigned data. # -fig, ax = plt.subplots() # Explicit Figure and Axes unpacked from module function. # No data transformed for visualizations. -plt.show() +fig, ax = plt.subplots() + # Module displays empty Figure and Axes. +plt.show() ############################################################################## # @@ -497,22 +496,25 @@ # Sample data for monthly spending averages. -budget = [475, 300, 125, 50] # 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'] -# Lists of strings contribute to labeling corresponding data. -colors = ['#1f77b4', '#ff7f0e', '#d62728', '#2ca02c'] # Hex color codes determine respective wedge color. +colors = ['#1f77b4', '#ff7f0e', '#d62728', '#2ca02c'] -explode = [0, 0.1, 0.15, 0.35] # 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): @@ -535,8 +537,7 @@ def autopct_format(percent, group): value = int(percent/100.*np.sum(group)) formatted = f'${value:<4}\n{percent:1.1f}%' return formatted -# This function operates in conjunction with the functools partial function -# for formatting labels in wedges. + ############################################################################## # @@ -557,8 +558,7 @@ def autopct_format(percent, group): 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 of the visual as equal. +ax.axis('equal') # The axis method sets the aspect ratio as equal. plt.show() @@ -569,8 +569,7 @@ def autopct_format(percent, group): plt.pie(budget, colors=colors, labels=categories) plt.legend() plt.title('Average Monthly Income Expenses') -plt.axis('equal') -# The pyplot module contains an identical method for setting aspect ratio. +plt.axis('equal') # The pyplot module has identical method for aspect ratio. plt.show() @@ -601,21 +600,20 @@ def autopct_format(percent, group): 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 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, - # The explode keyword argument uses the explode variable data to - # separate respective wedges from the center. autopct='%1.1f%%', - # The autopct keyword argument takes formatting strings and functions - # to generate text within the wedge. '%1.1f%%' is a string formatter. startangle=-80, - # The startangle keyword argument changes where the first wedge spans. - # Angles start at 0 degrees on the X-axis and move counterclockwise. - shadow=True - # The shadow keyword argument toggles a shadow on the visual. - ) + shadow=True) ax.legend() ax.set_title('Average Monthly Income Expenses') @@ -634,63 +632,54 @@ def autopct_format(percent, group): 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, - # Descriptions now act as text labels for the wedges. - # This removes redundant information from the previous - # pie chart. explode=explode, autopct=partial(autopct_format, group=budget), - # The autopct keyword argument calls a function as well. - # The functools partial function returns a formatted - # string. See Note below for more. startangle=45, pctdistance=0.85, - # The pctdistance keyword argument places the autopct - # Artist at a location using the float as a percentage of - # the radius. labeldistance=1.125, - # The labeldistance keyword argument specifies the float as - # a percentage of the radius to place labels. wedgeprops=dict(width=0.3), - # The wedgeprops keyword argument also takes dictionaries - # to pass on to the Artists. The float for width sets the - # wedge size as a percentage of the radius starting from - # the outer edge. shadow=True) -wedges, texts, autotexts = budget_pie # 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, - # The wedges variable unpacked from the method serve as the handles - # for the legend. categories, - # The information from the data categories corresponds to each - # respective wedge instead of redundant labeling from the previous - # pie chart. title='Categories', - # The legend has a title keyword argument. bbox_to_anchor=(0.125, 0.5), - # This keyword argument in conjunction with loc places the legend - # at a specific point. The tuple floats are coordinates for the - # Figure in terms of row and column of Axes. - loc='center right' - # The loc keyword argument works in conjunction with bbox_to_anchor - # and determines the part of the legend for placement. Without - # bbox_to_anchor, Matplotlib automatically manages coordinates in - # relation to specifications of the parameters of loc. - ) + loc='center right') ax.set_title('Average Monthly Income Expenses') ax.axis('equal') -fig.tight_layout() -# The Figure method tight_layout() manages the space between all Artists to -# maximize visiblity on the Figure. This method also contains various +# The Figure method tight_layout() manages space between all Artists to +# maximize visiblity on Figure. This method also contains various # parameters for configuration. +fig.tight_layout() plt.show() @@ -728,41 +717,41 @@ def autopct_format(percent, group): # 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) -# Figure and two Axes unpacked from arguments (1, 2) as row & column. -# Keyword arguments provide additional details of sharing Y-Axis, Figure size -# and layout formatting. -fig.suptitle('Personal Financial Tracking \'09 - \'10') # 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 plots data with additional keyword arguments. +# 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') -# First explicit Axes object uses separate methods for ticks on the X-Axis, -# title, and legend. Keyword arguments are for additional configurations. +# 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 plots data similarly to first explicit Axes. +# 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') -# Explicit second Axes object has separate methods as well. +# The pyplot module displays Figure. plt.show() -# The pyplot module displays the Figure. ############################################################################## # From 53c17764a11bea93267b7d51ecea803392003130 Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Wed, 23 Dec 2020 20:12:25 -0800 Subject: [PATCH 15/25] Added code examples for formatting and rebased --- doc/devel/style_guide.rst | 58 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 56 insertions(+), 2 deletions(-) diff --git a/doc/devel/style_guide.rst b/doc/devel/style_guide.rst index c55809b9ab53..7fd3a717bf06 100644 --- a/doc/devel/style_guide.rst +++ b/doc/devel/style_guide.rst @@ -6,6 +6,11 @@ Style Guide This guide is for contributors to understand conventions and expectations for quality control of Matplotlib written content. +.. seealso:: + + For more information about contributing, see the :ref:`documenting-matplotlib` + section. + Expository Language =================== @@ -137,15 +142,64 @@ references and subordinating conjunctive phrases. 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 ``show()`` to provide 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 standards --------------------------- - `reStructuredText Specifications `_ - `Quick Reference Document `_ + Lists ^^^^^ Bulleted lists are for items that do not require sequencing. Numbered lists are From 66a16e51a3c38f2f39f84a80891d4c21ac7fb574 Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Fri, 15 Jan 2021 15:42:09 -0800 Subject: [PATCH 16/25] Fixed wording and linked docs for pyplot.show --- doc/devel/style_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/devel/style_guide.rst b/doc/devel/style_guide.rst index 7fd3a717bf06..dc5fd1bd6027 100644 --- a/doc/devel/style_guide.rst +++ b/doc/devel/style_guide.rst @@ -171,7 +171,7 @@ Examples of Python code have comments before or on the same line. Outputs ^^^^^^^ When generating visuals with Matplotlib using ``.py`` files in examples, -display the visual with ``show()`` to provide display the visual. +display the visual with `matplotlib.pyplot.show` to display the visual. Keep the documentation clear of Python output lines. +------------------------------------+------------------------------------+ From c240dafbc414bf2e17b2fb6b1ffb3e7c41c87f72 Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Wed, 20 Jan 2021 17:02:04 -0800 Subject: [PATCH 17/25] Resolving comments for getting_started.py --- tutorials/introductory/getting_started.py | 98 ++++++++++++----------- 1 file changed, 53 insertions(+), 45 deletions(-) diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py index 2ca37c242c44..7a9cbc0b2734 100644 --- a/tutorials/introductory/getting_started.py +++ b/tutorials/introductory/getting_started.py @@ -32,8 +32,8 @@ # | Explicit, Object Oriented | Implicit, ``pyplot`` | # | Programming (OOP) | | # +====================================+====================================+ -# | Users explicitly create and manage | Automatically manages Figure and | -# | all Figure elements. | Axes. | +# | Users explicitly create and manage | The Matplotlib library implicitly | +# | all Figure elements. | manages Figure and Axes. | # +------------------------------------+------------------------------------+ # | Useful for repeated code use, | Helpful for quickly graphing data | # | generalization, robust | when using interactive | @@ -55,7 +55,7 @@ # # 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 wish to have Matplotlib create and manage parts of +# 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 @@ -75,20 +75,21 @@ # +====================================+====================================+ # | :: | :: | # | | | -# | fig, ax = plt.subplots() | plt.plot([1, 2, 3],[1, 2, 3]) | -# | ax.plot([1, 2, 3],[1, 2, 3]) | | +# | 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. | +# | | 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]) | | +# | fig, ax = plt.subplots() | plt.plot([1, 2, 3], [1, 2, 3]) | +# | ax.plot([1, 2, 3], [1, 2, 3]) | | # | | | # +------------------------------------+------------------------------------+ # @@ -103,7 +104,7 @@ # higher* is required. Depending on your operating system, Python may already # be installed on your machine. # -# Installing Maptlotlib is required in order to generate graphs with the +# 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. # @@ -140,7 +141,7 @@ # # - 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 abbreviation as ``plt`` is the standard shortcut. +# the plotting area. The ``plt`` abbreviation is the standard shortcut. # import numpy as np @@ -149,12 +150,14 @@ ############################################################################## # -# - NumPy is a common scientific Python library that benefits users with -# additional tools for manipulating data. +# - `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 # ---------------------------------- # @@ -227,18 +230,19 @@ # Explicit: Object Oriented Programming (OOP) # -------------------------------------------- # -# Explicit programming for Matplotlib involves calling the method ``subplots`` -# in the ``pyplot`` module once. This unpacks a group of an explicit Figure and -# Axes. More than one Axes is configurable; however, each Axes only corresponds -# to a single Figure. +# Explicit programming for Matplotlib involves calling the function +# `pyploy.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 parts of a Figure. These -# methods are different from those of the implicit programming approach. +# 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 labeled variables. +# Assigning sample data to variables. x = months y1 = income y2 = chk_acct_09 @@ -266,24 +270,24 @@ ############################################################################## # -# The module ``pyplot`` for the OOP example unpacks the Figure and Axes. -# This convention uses ``plt.subplots()`` and defaults to one Figure, ``fig``, -# and one Axes, ``ax``. The variable names are common shorthand terms. Any -# naming conventions also work. +# 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 manipulate the visualization. Specific Figures and Axes manage -# data components with their own respective methods. +# 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 automatically generates Figure and Axes. Methods and +# 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. @@ -307,7 +311,7 @@ ############################################################################## # -# In the example above, the ``pyplot`` module contains its own methods of +# 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 @@ -364,7 +368,7 @@ # # :class:`~matplotlib.axes.Axes` # -# Axes are subplots within the Figure. They contain Figure elements and +# 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. @@ -372,8 +376,12 @@ # In a Figure, each Axes contains any number of visual 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. +# 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 @@ -472,8 +480,8 @@ # | | :doc:`/tutorials/text/annotations` | # +------------------------------+--------------------------------------------+ # -# For complete information about available methods for Artists, refer to the -# table below. +# For complete information about available methods for creating new Artists, +# refer to the table below. # # +------------------------------------+------------------------------------+ # | Explicit | Implicit | @@ -594,7 +602,7 @@ def autopct_format(percent, group): # # The pie chart below adds configurations with keyword arguments for # ``explode``, ``autopct``, ``startangle``, and ``shadow``. These keyword -# arguments help to manipulate the Artists. +# arguments help to define the display of Artists. # Explicit @@ -603,7 +611,7 @@ def autopct_format(percent, group): # 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 wedge. '%1.1f%%' is the string formatter. +# 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. @@ -676,8 +684,8 @@ def autopct_format(percent, group): ax.set_title('Average Monthly Income Expenses') ax.axis('equal') -# The Figure method tight_layout() manages space between all Artists to -# maximize visiblity on Figure. This method also contains various +# 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() @@ -759,18 +767,18 @@ def autopct_format(percent, group): # the explicit approach refers to an explicitly generated Axes after creating # both the Figure and Axes. # -# In the unpacking process, numerous Axes are assigned to a single variable. +# 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) +# 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[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]]) +# ax[1,1].imshow([[1, 2], [2, 1]]) # # # The method `matplotlib.figure.Figure.subplot_mosaic` also generates Axes in @@ -783,10 +791,10 @@ def autopct_format(percent, group): # 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['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]]) +# ax_dict['image'].imshow([[1, 2], [2, 1]]) # # Implicit # ^^^^^^^^ @@ -816,7 +824,7 @@ def my_plotter(ax, data1, data2, param_dict): X data data2 : array Y data - param_dict : dict() + param_dict : dict Dictionary of keyword arguments passes to method Returns From f9dbb014889ca721c4ecb537a48e58d63c52421a Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Wed, 20 Jan 2021 17:03:10 -0800 Subject: [PATCH 18/25] Fixed trailing whitespaces --- tutorials/introductory/getting_started.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py index 7a9cbc0b2734..35421e78385a 100644 --- a/tutorials/introductory/getting_started.py +++ b/tutorials/introductory/getting_started.py @@ -156,7 +156,7 @@ # other functions. The `Pie Chart Examples`_ section note contains more # information about the purpose of this module. # -# +# # # Two Approaches for Creating Graphs # ---------------------------------- @@ -230,7 +230,7 @@ # Explicit: Object Oriented Programming (OOP) # -------------------------------------------- # -# Explicit programming for Matplotlib involves calling the function +# Explicit programming for Matplotlib involves calling the function # `pyploy.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 @@ -376,7 +376,7 @@ # In a Figure, each Axes contains any number of visual 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. +# 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 From 7f7ce1f960900ed9db70b4d875bb5967fd54d1a1 Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Thu, 21 Jan 2021 00:28:12 -0800 Subject: [PATCH 19/25] Repairing broken reST section formatting --- tutorials/introductory/getting_started.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py index 35421e78385a..e7f86df600eb 100644 --- a/tutorials/introductory/getting_started.py +++ b/tutorials/introductory/getting_started.py @@ -351,7 +351,7 @@ # 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() @@ -377,7 +377,7 @@ # 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 @@ -560,7 +560,6 @@ def autopct_format(percent, group): # Explicit - fig, ax = plt.subplots() ax.pie(budget, colors=colors, labels=categories) @@ -574,6 +573,8 @@ def autopct_format(percent, group): # # +# Implicit + plt.pie(budget, colors=colors, labels=categories) plt.legend() plt.title('Average Monthly Income Expenses') From 8547339699439e0a56fc9a50cc4f2ed027ba8a70 Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Wed, 27 Jan 2021 10:17:29 -0800 Subject: [PATCH 20/25] Removed extra comment for formatting line 354 in .py --- tutorials/introductory/getting_started.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py index e7f86df600eb..867ac875c990 100644 --- a/tutorials/introductory/getting_started.py +++ b/tutorials/introductory/getting_started.py @@ -351,7 +351,7 @@ # 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() From 2d419983b438f71f156ce5bf1060744f581a5fc2 Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Mon, 1 Feb 2021 13:36:03 -0800 Subject: [PATCH 21/25] Fixed reference for pyplot.subplots --- tutorials/introductory/getting_started.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py index 867ac875c990..1cf168147de5 100644 --- a/tutorials/introductory/getting_started.py +++ b/tutorials/introductory/getting_started.py @@ -231,10 +231,10 @@ # -------------------------------------------- # # Explicit programming for Matplotlib involves calling the function -# `pyploy.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. +# `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. From 0721ab453bcbfdff35ff6d45b6c721fb1cb9c4f3 Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Mon, 15 Feb 2021 11:47:22 -0800 Subject: [PATCH 22/25] Changed language for plot elements plus rebase --- doc/devel/style_guide.rst | 6 +++--- tutorials/introductory/getting_started.py | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/devel/style_guide.rst b/doc/devel/style_guide.rst index dc5fd1bd6027..4d9b8224865d 100644 --- a/doc/devel/style_guide.rst +++ b/doc/devel/style_guide.rst @@ -31,7 +31,7 @@ not interchangeable. | | for programming. | - 11 Figures | - 11 figures | +------------------+--------------------------+--------------+--------------+ | Axes_ | Subplots within Figure. | - One Axes | - One axes | -| | Contains Figure elements | - Four Axes | - Four Axeses| +| | Contains plot elements | - Four Axes | - Four Axeses| | | and is responsible for | - 32 Axes | - 32 Axii | | | plotting and configuring | | | | | additional details. | | | @@ -116,8 +116,8 @@ related to warning prompts. Sentence structure ^^^^^^^^^^^^^^^^^^ Write with short sentences using Subject-Verb-Object order regularly. Limit -how frequently coordinating conjunctions appear in sentences. Avoid pronoun -references and subordinating conjunctive phrases. +coordinating conjunctions in sentences. Avoid pronoun references and +subordinating conjunctive phrases. +------------------------------------+------------------------------------+ | Correct | Incorrect | diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py index 1cf168147de5..da9b73096c1f 100644 --- a/tutorials/introductory/getting_started.py +++ b/tutorials/introductory/getting_started.py @@ -33,7 +33,7 @@ # | Programming (OOP) | | # +====================================+====================================+ # | Users explicitly create and manage | The Matplotlib library implicitly | -# | all Figure elements. | manages Figure and Axes. | +# | all plot elements. | manages Figure and Axes. | # +------------------------------------+------------------------------------+ # | Useful for repeated code use, | Helpful for quickly graphing data | # | generalization, robust | when using interactive | @@ -373,7 +373,7 @@ # Figure can contain multiple Axes, but each Axes is specific to one # Figure. # -# In a Figure, each Axes contains any number of visual elements. Axes are +# 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. @@ -405,8 +405,8 @@ # Manipulating Artists # -------------------- # -# With simple plots, Matplotlib automatically generates the basic elements of -# a graph. For more control over the visual, use Artists and methods. +# 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 From 317e07e277b947930a5d2f4db89f885324248f59 Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Fri, 19 Feb 2021 19:29:51 -0800 Subject: [PATCH 23/25] Modifications to style_guide.rst for review, added link to Python docs --- doc/devel/style_guide.rst | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/doc/devel/style_guide.rst b/doc/devel/style_guide.rst index 4d9b8224865d..5faecf622006 100644 --- a/doc/devel/style_guide.rst +++ b/doc/devel/style_guide.rst @@ -1,17 +1,17 @@ -=========== -Style Guide -=========== +========================= +Documentation Style Guide +========================= -This guide is for contributors to understand conventions and expectations for -quality control of Matplotlib written content. +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 +Expository language =================== For explanatory writing, the following guidelines are for clear and concise @@ -259,9 +259,13 @@ Markdown tables and the csv-table directive are not accepted. +--------------------------------+----------------------------------------+ -Additional Resources +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 `_ From 86a157098a335d5f9875df45d4518659a0113a8f Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Mon, 1 Mar 2021 12:01:22 -0800 Subject: [PATCH 24/25] Terminology clarification for Figure, Axes, Artist changed style_guide.rst --- doc/devel/style_guide.rst | 100 ++++++++++++++++++++++++++++++++------ 1 file changed, 86 insertions(+), 14 deletions(-) diff --git a/doc/devel/style_guide.rst b/doc/devel/style_guide.rst index 5faecf622006..e936cb76e5f2 100644 --- a/doc/devel/style_guide.rst +++ b/doc/devel/style_guide.rst @@ -21,28 +21,100 @@ Terminology ----------- There are several key terms in Matplotlib that are standards for -reliability and consistency in documentation. They are case-sensitive and are -not interchangeable. +reliability and consistency in documentation. They are not interchangeable. +------------------+--------------------------+--------------+--------------+ | Term | Description | Correct | Incorrect | +==================+==========================+==============+==============+ -| Figure_ | Matplotlib working space | - One Figure | - One figure | -| | for programming. | - 11 Figures | - 11 figures | +| 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_ on | +| | | Figure_ , | the page is| +| | | "Methods | static." | +| | | within the | | +| | | Figure_ | | +| | | provide the| | +| | | visuals." | | +| | | - *General | | +| | | objects*: | | +| | | figure, | | +| | | "All of the| | +| | | figures for| | +| | | this page | | +| | | are | | +| | | static." | | +------------------+--------------------------+--------------+--------------+ -| Axes_ | Subplots within Figure. | - One Axes | - One axes | -| | Contains plot elements | - Four Axes | - Four Axeses| -| | and is responsible for | - 32 Axes | - 32 Axii | -| | plotting and configuring | | | -| | additional details. | | | +| 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 | - "All of the| +| | | to class*: | Axes are | +| | | Axes_ , | compatible | +| | | "Each Axes_| with other | +| | | is specific| libraries."| +| | | to one | | +| | | Figure." | | +| | | - *General | | +| | | objects*: | | +| | | axes, "Both| | +| | | explicit | | +| | | and | | +| | | implicit | | +| | | strategies | | +| | | contain | | +| | | multiple | | +| | | types of | | +| | | data | | +| | | visuals | | +| | | on a single| | +| | | axes." | | +------------------+--------------------------+--------------+--------------+ -| Artist_ | Broad variety of | - One Artist | - One artist | -| | Matplotlib objects that | - Two Artists| - Two artists| -| | display visuals. | | | +| 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 are | +| | | are the | many | +| | | visible | Artists_ in| +| | | elements | this | +| | | when the | graph." | +| | | rendering | - "Some | +| | | a Figure." | Artists | +| | | - *Referring | have an | +| | | to class*: | overlapping| +| | | Artist_ , | naming | +| | | "Each | convention | +| | | Artist_ has| in both | +| | | respective | explicit | +| | | methods and| and | +| | | functions."| implicit | +| | | - *General | uses." | +| | | objects*: | | +| | | artist, | | +| | | "The | | +| | | artists in | | +| | | this table | | +| | | generate | | +| | | visuals." | | +------------------+--------------------------+--------------+--------------+ | Axis_ | Human-readable single | - One Axis | - One Axis | -| | dimensional object | object | - One axis | -| | of reference marks | - Four Axis | - Four Axises| +| | dimensional object | object | - One axes | +| | of reference marks | - Four axis | - Four Axises| | | containing ticks, tick | objects | - 32 Axes | | | labels, spines, and | - 32 Axis | | | | edges. | objects | | From 2273289170c2ca4516c2de2020c4c3fec07b31be Mon Sep 17 00:00:00 2001 From: Jerome Villegas Date: Sun, 7 Mar 2021 22:23:10 -0800 Subject: [PATCH 25/25] Changed examples in style_guide.rst correct/incorrect for Figure, Axes, Artist, Axis --- doc/devel/style_guide.rst | 144 +++++++++++++++++++++++--------------- 1 file changed, 87 insertions(+), 57 deletions(-) diff --git a/doc/devel/style_guide.rst b/doc/devel/style_guide.rst index e936cb76e5f2..957cd76ed685 100644 --- a/doc/devel/style_guide.rst +++ b/doc/devel/style_guide.rst @@ -32,25 +32,25 @@ reliability and consistency in documentation. They are not interchangeable. | | | Figure, | space for | | | | "The Figure| visuals." | | | | is the | - "Methods in| -| | | working | the Figure | +| | | working | the figure | | | | space for | provide the| | | | the visual.| visuals." | | | | - *Referring | - "The | -| | | to class*: | Figure_ on | -| | | Figure_ , | the page is| -| | | "Methods | static." | -| | | within the | | -| | | Figure_ | | +| | | to class*: | Figure_ | +| | | Figure_ , | Four | +| | | "Methods | leglock is | +| | | within the | a wrestling| +| | | Figure_ | move." | | | | provide the| | | | | visuals." | | | | | - *General | | -| | | objects*: | | +| | | language*: | | | | | figure, | | -| | | "All of the| | -| | | figures for| | -| | | this page | | -| | | are | | -| | | static." | | +| | | "Michelle | | +| | | Kwan is a | | +| | | famous | | +| | | figure | | +| | | skater." | | +------------------+--------------------------+--------------+--------------+ | Axes_ | Subplots within Figure. | - *For | - "The axes | | | Contains plot elements | Matplotlib | methods | @@ -60,27 +60,31 @@ reliability and consistency in documentation. They are not interchangeable. | | | subplot | is specific| | | | within the | to a | | | | Figure." | Figure." | -| | | - *Referring | - "All of the| -| | | to class*: | Axes are | -| | | Axes_ , | compatible | -| | | "Each Axes_| with other | -| | | is specific| libraries."| -| | | to one | | -| | | Figure." | | -| | | - *General | | -| | | objects*: | | -| | | axes, "Both| | -| | | explicit | | -| | | and | | -| | | implicit | | -| | | strategies | | -| | | contain | | -| | | multiple | | -| | | types of | | -| | | data | | -| | | visuals | | -| | | on a single| | +| | | - *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 | @@ -88,36 +92,62 @@ reliability and consistency in documentation. They are not interchangeable. | | | Artist, | its | | | | "Artists | respective | | | | display | method." | -| | | visuals and| - "There are | -| | | are the | many | -| | | visible | Artists_ in| -| | | elements | this | -| | | when the | graph." | +| | | visuals and| - "There is | +| | | are the | an Artist_ | +| | | visible | for that | +| | | elements | visual in | +| | | when the | the graph."| | | | rendering | - "Some | | | | a Figure." | Artists | -| | | - *Referring | have an | -| | | to class*: | overlapping| -| | | Artist_ , | naming | -| | | "Each | convention | -| | | Artist_ has| in both | -| | | respective | explicit | -| | | methods and| and | -| | | functions."| implicit | -| | | - *General | uses." | -| | | objects*: | | +| | | - *Referring | became | +| | | to class*: | famous only| +| | | Artist_ , | by | +| | | "Each | accident." | +| | | Artist_ has| | +| | | respective | | +| | | methods and| | +| | | functions."| | +| | | - *General | | +| | | language*: | | | | | artist, | | | | | "The | | -| | | artists in | | -| | | this table | | -| | | generate | | -| | | visuals." | | +| | | artist in | | +| | | the museum | | +| | | is from | | +| | | France." | | +------------------+--------------------------+--------------+--------------+ -| Axis_ | Human-readable single | - One Axis | - One Axis | -| | dimensional object | object | - One axes | -| | of reference marks | - Four axis | - Four Axises| -| | containing ticks, tick | objects | - 32 Axes | -| | labels, spines, and | - 32 Axis | | -| | edges. | objects | | +| 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 | 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