Switch explicit/implicit order and text.

jeromefv · jeromefv · commit 9abbf92be3db · 2020-11-10T15:20:55.000-08:00
diff --git a/tutorials/introductory/getting_started.py b/tutorials/introductory/getting_started.py
@@ -18,24 +18,24 @@
 # 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.
-#
-# There are two main ways of producing graphs with Matplotlib, stateful and
-# stateless. Stateful code, using `pyplot`, or stateless code, using Object
-# Oriented Programming (OOP), are the foundation for creating and manipulating
-# data into visualizations.
+# methods. This process occurs on the backend and is not user-facing. For more
+# information regarding manipulating backend capabilities, see """ref""".
 #
-# The stateful `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.
+# 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.
 #
-# Stateless programming, OOP, helps users generalize code and is useful for
+# 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.
 #
 #
 
@@ -71,6 +71,11 @@
 #
 # `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
 # ------------------------
 #
@@ -84,8 +89,8 @@
 # ========
 #
 # The common conventions for preparing to plot data involve importing the
-# necessary libraries with abbreviations for convenience. Both stateful and
-# stateless programming require the following.
+# necessary libraries with abbreviations for convenience. Both implicit and
+# explicit programming require the following.
 
 import matplotlib.pyplot as plt
 
@@ -97,24 +102,25 @@
 #
 # These are the two common strategies for creating plots with Matplotlib.
 #
-# * Stateful: 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.
-# * Stateless: Code has explicit references to objects. Users manage objects
+# * 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 stateful and
-#     stateless strategies. When using one as standard, all code should follow
-#     the same strategy. Switching back and forth between stateful and
-#     stateless programming can yield errors.
+#     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
-# """insert reference""".
+# """ref""".
 #
 # Data
 # ----
@@ -147,57 +153,27 @@
 #    Other containers, such as `pandas` data objects, may not work as
 #    intended.
 #
-# Stateful: `pyplot`
-# ------------------
-#
-# To use stateful 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.
-
-# Stateful programming with pyplot
-
-x = months
-y1 = income
-y2 = chk_acct_09
-y3 = svg_acct_09
-
-plt.plot(x, y1, label='Income')
-plt.plot(x, y2, label='Checking Account')
-plt.plot(x, y3, 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.
-#
-# Stateless: Object Oriented Programming (OOP)
+# Explicit: Object Oriented Programming (OOP)
 # --------------------------------------------
 #
-# To use stateless programming for Matplotlib involves using a single instance
+# 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 stateful programming approach.
+# are different from those of the implicit programming approach.
 
-# Stateless programming with OOP
+# Explicit programming with OOP
 
-y4 = chk_acct_10
-y5 = svg_acct_10
+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, y4, label='Savings Account')
-ax.plot(x, y5, label='Income')
+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')
@@ -216,6 +192,36 @@
 # 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
@@ -243,12 +249,12 @@
 #    * 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
-#         """insert reference""".
+#         """ref""".
 #
 # Multiple Graphs within a Figure
 # -------------------------------
 #
-# For multiple graphs using a single figure, stateful and stateless approaches
+# 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
@@ -257,39 +263,12 @@
 # When looking for more complex solutions to multiple graphs within a figure,
 # use the GridSpec module to organize the layout.
 
-# Stateful with pyplot
-
-plt.subplot(1, 2, 1)
-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()
+# Explicit with OOP
 
-##############################################################################
-#
-# 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.
-
-# Stateless with OOP
-
-fig, (ax1, ax2) = plt.subplots(2, 1, sharey='row',
+fig, (ax1, ax2) = plt.subplots(1, 2, sharey='row',
                                figsize=[8, 4], constrained_layout=True)
-# Note the different method name for OOP.
 
-fig.suptitle('Personal Financial Tarcking \'09 - \'10',
+fig.suptitle('Personal Financial Tracking \'09 - \'10',
              fontsize=16, weight='black')
 
 ax1.plot(x, y1, label='Income')
@@ -310,3 +289,29 @@
 # 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.
