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 |