matplotlib
diff --git a/‎galleries/users_explain/plotting/pairwise.py
Lines changed: 38 additions & 36 deletions b/‎galleries/users_explain/plotting/pairwise.py
Lines changed: 38 additions & 36 deletions
@@ -35,7 +35,7 @@
 # %%
 # By default, `~.Axes.plot` joins data points with a solid straight line, as
 # shown in the jagged nature of the plot above. We can style that line,
-# with dashes or plot the data with symbols, or both, as below.
+# with dashes, plot the data with symbols, or both styles, as demonstrated below.
 
 fig, axs = plt.subplots(3, 1, sharex=True)
 ax = axs[0]
@@ -48,12 +48,12 @@
 ax.set_xlabel('x')
 
 # %%
-# It is possible to plot multiple datasets at once against one ``x`` array
-# if the shape of ``Y`` matches.  Here note that ``Y`` has shape ``(30,3)``
-# so the length of each column is the same as the length of ``x``.
-# Each column of data in ``Y`` gets a different color following the
+# Multiple datasets can be plotted simultaneously against a single ``x`` array
+# if the shape of ``Y`` is compatible. In this example, ``Y`` has the shape ``(30, 3)``,
+# meaning each column has the same length as ``x``.
+# Each column in ``Y`` is assigned a different color according to the
 # default :ref:`color cycle <color_cycle>`. A legend for each column in
-# ``Y`` is created by passing a **label** with a list of column names:
+# ``Y`` is generated by providing a **label** with a list of column names:
 
 Y = np.arange(30*3).reshape(3, 30).T
 fig, ax = plt.subplots(figsize=(5, 3))
@@ -63,7 +63,7 @@
 
 # %%
 # fill_between, fill_betweenx, and stackplot
-# ------------------------------------------
+# -----------------------------------------
 #
 # The `~.Axes.fill_between` method is useful to indicate a confidence interval
 # around a line plot. In this example, the confidence interval is imagined to
@@ -153,12 +153,12 @@
 
 # %%
 #
-# `~.Axes.errorbar` inherits from `~.Axes.plot`, so the same format strings can
-# be used to control the marker's appearance. Errorbar appearance is controlled
-# by keyword arguments such as *ecolor* for the color of the error bar lines,
-# **capsize** for the length of the error bar caps, and *elinewidth* for the
-# thickness of the error bar lines. The error bars can also be asymmetric if
-# *yerr* or *xerr* are 2D arrays.
+# `~.Axes.errorbar` inherits from `~.Axes.plot`, allowing the use of the same
+# format to control the marker's appearance. The appearance of error bars is
+# controlled by keyword arguments such as *ecolor* for the color of the error
+# bar lines, **capsize** for the length of the error bar caps, and *elinewidth*
+# for the thickness of the error bar lines. Error bars can also be asymmetric
+# if *yerr* or *xerr* are provided as 2D arrays.
 
 fig, ax = plt.subplots()
 ax.errorbar(x, y, yerr=[erry, 2*erry], xerr=[errx, 2*errx], fmt='o',
@@ -171,13 +171,13 @@
 # scatter
 # -------
 #
-# The `~.Axes.scatter` method is similar to `~.Axes.plot` in that it will plot two
-# arrays of data against each other, but differs in that
+# The `~.Axes.scatter` method is similar to `~.Axes.plot` in that it plots two
+# arrays of data against each other, but differs in the following ways:
 #
-# * there is no option to connect markers with lines
-# * the size and color of markers can vary according to the value of other data arrays.
+# * there is no option to connect markers with lines,
+# * the size and color of markers can vary according to the values of other data arrays.
 #
-# This example shows how to plot a scatter plot with varying point sizes using
+# This example demonstrates how to create a scatter plot with varying point sizes using
 # the *s* keyword and and colors using the *c* keyword.
 
 y = np.sin(x)
@@ -194,9 +194,10 @@
 fig.colorbar(scatter, label="Value of sin(x)")
 
 #######################################################################################
-# We can change the marker (see :mod:`matplotlib.markers` for a full list), but each
-# call to scatter can only accept one *marker*.  If it is desired to code data by
-# marker shape, then make multiple calls to `~.Axes.scatter`
+# The marker style can be changed (see :mod:`matplotlib.markers` for a full
+# list), but each call to `~.Axes.scatter` can only accept one *marker* type.
+# To code data by different marker shapes, make multiple calls to
+# `~.Axes.scatter`.
 
 y2 = np.cos(x)
 colors2 = y2
@@ -226,7 +227,7 @@
 # ---------------------
 #
 # `~.Axes.bar`, `~.Axes.stairs`, and `~.Axes.stem` are useful for plotting data
-# that deviates from a zero or mean value, and are often used to plot
+# that deviates from a zero or mean value. These methods are often used to plot
 # histograms.
 
 x = x[::2]
@@ -246,9 +247,9 @@
 ax.set_ylabel('sin(x)')
 
 # %%
-# `~.Axes.bar` does not automatically calculate a *width* for the bars, so you
-# typically have to calculate it yourself to get the correct spacing. *width*
-# can also be an array with the same length as *x* to specify the width of each
+# `~.Axes.bar` does not automatically calculate the *width* of the bars, so it
+# typically needs to be calculated manually to achieve the correct spacing. The *width*
+# can also be specified as an array with the same length as *x* to set the width of each
 # bar individually.
 
 fig, ax = plt.subplots()
@@ -262,10 +263,10 @@
 #
 # `~.Axes.step` and `~.Axes.stairs` are similar to `~.Axes.plot` but plot a
 # step between each data point. They accept differently shaped data depending
-# on your use case.
+# on the use case.
 #
-# `~.Axes.step` is useful for plotting steps, and accepts the same data shape
-# as `~.Axes.plot`.
+# `~.Axes.step` particularly useful as it accepts the same data shape as
+# `~.Axes.plot`.
 
 fig, ax = plt.subplots()
 
@@ -275,11 +276,12 @@
 ax.set_title('step')
 
 # %%
-# Note that we can center the steps on the data in different ways
-# using the **where** keyword. The default is **where='pre'** which
-# mea
C034
ns the step extends to the left of the data point. **where='mid'**
-# means the step extends half way to the next data point, and **where='post'**
-# means the step extends to the right of the data point:
+
+# The steps can be centered on the data in different ways using the **where**
+# keyword. The default is **where='pre'**, which means the step extends to the
+# left of the data point. **where='mid'** means the step extends halfway to the
+# next data point, and **where='post'** means the step extends to the right of
+# the data point:
 
 fig, axs = plt.subplots(3, 1, sharex=True, sharey=True, figsize=(4.5, 5))
 
@@ -295,9 +297,9 @@
 
 # %%
 #
-# `~.Axes.stairs` is useful for plotting histograms, and specifies the edges of steps
-# rather than the centers.  This is particularly useful for plotting histograms, and can
-# be used with the result from `~numpy.histogram`.
+# `~.Axes.stairs` is useful for plotting histograms, and specifies the edges of
+# steps rather than the centers, so  can directly be used with the result from
+# `~numpy.histogram`.
 
 data = rng.normal(size=1000)
 hist, bin_edges = np.histogram(data, bins=np.arange(-4, 4, 0.2), density=True)