DOC: New color line by value example #28307

eytanadler · 2024-05-26T21:32:51Z

PR summary

I opened issue #28242, which is asking for better ways to plot a line with a color at each point assigned by a third value. @timhoffm suggested a nice way to do this. This PR adds a new example that implements his improved method.

@timhoffm said this should replace this example. @rcomer also thought this example could be replaced by it. I haven't removed either of the examples since I want to be clear on the expectations before I start deleting previous work.

The approach in previous methods produce results that look something like this:

The new approach in the provided example applied to the same plot produces this:

PR checklist

"closes #0000" is in the body of the PR description to link the related issue
new and changed code is tested
Plotting related features are demonstrated in an example
New Features and API Changes are noted with a directive and release note
Documentation complies with general and docstring guidelines

github-actions

Thank you for opening your first PR into Matplotlib!

If you have not heard from us in a week or so, please leave a new comment below and that should bring it to our attention. Most of our reviewers are volunteers and sometimes things fall through the cracks.

You can also join us on gitter for real-time discussion.

For details on testing, writing docs, and our review process, please see the developer guide

We strive to be a welcoming and open project. Please follow our Code of Conduct.

jklymak · 2024-05-28T00:05:43Z

https://matplotlib.org/stable/gallery/lines_bars_and_markers/multicolored_line.html is the correct example to change. If it were me I'd add a second plot to the simpler example. I agree that this strategy is superior to what is in the current example, but it is more convoluted to follow, so I think there is value in both.

timhoffm · 2024-05-28T07:44:05Z

https://matplotlib.org/stable/gallery/lines_bars_and_markers/multicolored_line.html is the correct example to change. If it were me I'd add a second plot to the simpler example. I agree that this strategy is superior to what is in the current example, but it is more convoluted to follow, so I think there is value in both.

Indeed, it makes sense to collect the content under the multicolored_line example. We could keep parts of the original example. Some suggestions on that:

Drop the second part of the existing example. Using a BoundaryNorm for discrete coloring is an orthogonal topic and additionally likely more of a niche case for line coloring. So let's not clutter the example with that.
The existing example nicely conceals the topic that the color information is between the points instead of at the points by choosing the derivative as a quantity that lives between the points.
This would be a good way of distinguishing the two approaches. If the to-be-colored information is between the points, use the simple segments. If you have information at the points, use the more advanced segmentation.

davidlowryduda · 2024-05-31T19:26:02Z

galleries/examples/lines_bars_and_markers/color_line_by_value.py

+def colored_line(x, y, c, ax, **lc_kwargs):
+    """
+    Plot a line with a color specified along the line by a third value. It does this
+    by creating a collection of line segments. Each line segment is made up of two
+    straight lines each connecting the current (x, y) point to the midpoints of the
+    lines connecting the current point with its two neighbors. This creates a smooth
+    line with no gaps between the line segments.


This is very minor, but I suggest that you add a new line to reflect standard docstring conventions.

Suggested change

def colored_line(x, y, c, ax, **lc_kwargs):

"""

Plot a line with a color specified along the line by a third value. It does this

by creating a collection of line segments. Each line segment is made up of two

straight lines each connecting the current (x, y) point to the midpoints of the

lines connecting the current point with its two neighbors. This creates a smooth

line with no gaps between the line segments.

def colored_line(x, y, c, ax, **lc_kwargs):

"""

Plot a line with a color specified along the line by a third value.

It does this by creating a collection of line segments. Each line segment

is made up of two straight lines each connecting the current (x, y) point

to the midpoints of the lines connecting the current point with its two

neighbors. This creates a smooth line with no gaps between the line

segments.

eytanadler · 2024-05-31T20:38:53Z

Based on feedback, I merged the new example into the multicolored line example. It's now a bit verbose, but my goal was to put the code into well-documented functions so that using them is easy. That way users can copy these functions and use them for their own purposes without having to do too much parsing of the example.

timhoffm

I suggest you make two independent code blocks for the two plots. It's simpler to follow only half of the code that is relevant for the respective plot. You may also consider giving the two variants separate sections.

Docstring structure:

"""
==================
Multicolored lines
==================

...

Color values at points
----------------------

"""
<first code block>
####################################################################
# Color values between points
# ---------------------------
# ...
<second code block>

timhoffm

Minor style suggestions.

timhoffm · 2024-06-01T23:30:45Z

galleries/examples/lines_bars_and_markers/multicolored_line.py

+    matplotlib.collections.LineCollection
+        The generated line collection representing the colored line.
+    """
+    # Give a warning if the user specified an array keyword argument


Suggested change

# Give a warning if the user specified an array keyword argument

The comment does not add information that is not already obvious from the code.

timhoffm · 2024-06-01T23:32:21Z

galleries/examples/lines_bars_and_markers/multicolored_line.py

+    # Create the line collection and set the colors of each segment
+    lc = LineCollection(segments, **default_kwargs)
+    lc.set_array(c)


Suggested change

# Create the line collection and set the colors of each segment

lc = LineCollection(segments, **default_kwargs)

lc.set_array(c)

lc = LineCollection(segments, **default_kwargs)

lc.set_array(c) # set the colors of each segment

a bit more compact

timhoffm · 2024-06-01T23:33:39Z

galleries/examples/lines_bars_and_markers/multicolored_line.py

+    lc = LineCollection(segments, **default_kwargs)
+    lc.set_array(c)
+
+    # Add the collection to the axis and return the line collection object


Suggested change

# Add the collection to the axis and return the line collection object

# Add the collection to the Axes and return the line collection object

But IMHO the comment is on the border of not-needed.

timhoffm · 2024-06-01T23:33:55Z

galleries/examples/lines_bars_and_markers/multicolored_line.py

+    matplotlib.collections.LineCollection
+        The generated line collection representing the colored line.
+    """
+    # Give a warning if the user specified an array keyword argument


Suggested change

# Give a warning if the user specified an array keyword argument

as above

timhoffm · 2024-06-01T23:38:04Z

galleries/examples/lines_bars_and_markers/multicolored_line.py

+lines = colored_line(x, y, color, ax1, linewidth=10, cmap="plasma")
+cax1 = fig1.colorbar(lines)  # add a color legend


Suggested change

lines = colored_line(x, y, color, ax1, linewidth=10, cmap="plasma")

cax1 = fig1.colorbar(lines) # add a color legend

lines = colored_line(x, y, color, ax1, linewidth=10, cmap="plasma")

fig1.colorbar(lines) # add a color legend

If return values are not used, don't assign them to variables. This keeps the code more readable.

timhoffm · 2024-06-01T23:40:13Z

galleries/examples/lines_bars_and_markers/multicolored_line.py

+line = colored_line_between_pts(x, y, dydx, ax2, linewidth=2, cmap="viridis")
+cax2 = fig2.colorbar(line, ax=ax2)


Suggested change

line = colored_line_between_pts(x, y, dydx, ax2, linewidth=2, cmap="viridis")

cax2 = fig2.colorbar(line, ax=ax2)

line = colored_line_between_pts(x, y, dydx, ax2, linewidth=2, cmap="viridis")

fig2.colorbar(line, ax=ax2, label="dy/dx")

timhoffm · 2024-06-01T23:40:38Z

galleries/examples/lines_bars_and_markers/multicolored_line.py

+
+# Labels
+ax2.set_title("Color between points")
+cax2.set_label("dy/dx")


Suggested change

# Labels

ax2.set_title("Color between points")

cax2.set_label("dy/dx")

ax2.set_title("Color between points")

timhoffm

Sorry, I still found some nits, but let's try to be as precise and helpful to users as possible.

Also please squash your commits. They currently add and remove a file, which CI flags as unnecessary overhead.

timhoffm · 2024-06-04T20:05:59Z

galleries/examples/lines_bars_and_markers/multicolored_line.py

+    coord_start = np.column_stack((x_midpts[:-1], y_midpts[:-1])).reshape(x.size, 1, 2)
+    coord_mid = np.column_stack((x, y)).reshape(x.size, 1, 2)
+    coord_end = np.column_stack((x_midpts[1:], y_midpts[1:])).reshape(x.size, 1, 2)


Optional, but you could use a[:, np.newaxis, :] instead of a.reshape(x.size, 1, 2), wich is slightly more telling that you only introduce an extra dimension.

Suggested change

coord_start = np.column_stack((x_midpts[:-1], y_midpts[:-1])).reshape(x.size, 1, 2)

coord_mid = np.column_stack((x, y)).reshape(x.size, 1, 2)

coord_end = np.column_stack((x_midpts[1:], y_midpts[1:])).reshape(x.size, 1, 2)

coord_start = np.column_stack((x_midpts[:-1], y_midpts[:-1]))[:, np.newaxis, :]

coord_mid = np.column_stack((x, y))[:, np.newaxis, :]

coord_end = np.column_stack((x_midpts[1:], y_midpts[1:]))[:, np.newaxis, :]

timhoffm · 2024-06-04T20:24:39Z

galleries/examples/lines_bars_and_markers/multicolored_line.py

+
+    # Compute the midpoints of the line segments. Include the first and last points
+    # twice so we don't need any special syntax later to handle them.
+    x_midpts = np.hstack((x[0], 0.5 * (x[1:] + x[:-1]), x[-1]))


Suggested change

x_midpts = np.hstack((x[0], 0.5 * (x[1:] + x[:-1]), x[-1]))

x = np.asarray(x)

y = np.asarray(y)

x_midpts = np.hstack((x[0], 0.5 * (x[1:] + x[:-1]), x[-1]))

Otherwise, we'd have to claim "array" instead of "array-like" in the docstring.

timhoffm · 2024-06-04T20:38:07Z

galleries/examples/lines_bars_and_markers/multicolored_line.py

+plt.show()
+
+
+####################################################################


Do we want an additional plot to illustrate the mechanism?

Suggested change

####################################################################

####################################################################

# This method is designed to give a smooth impression when distances and color

# differences between adjacent points are not too large. The following example

# does not meet this criteria and by that serves to illustrate the segmentation

# and coloring mechanism.

x = [0, 1, 2, 3, 4]

y = [0, 1, 2, 1, 1]

c = [1, 2, 3, 4, 5]

fig, ax = plt.subplots()

ax.scatter(x, y, c=c, cmap='rainbow')

colored_line(x, y, c=c, ax=ax, cmap='rainbow')

####################################################################

timhoffm · 2024-06-04T20:42:48Z

galleries/examples/lines_bars_and_markers/multicolored_line.py

+
+    Parameters
+    ----------
+    x, y : array-like or scalar


Suggested change

x, y : array-like or scalar

x, y : array-like

scalars do not work because you index below. But that's ok, let's just not bother with them.

timhoffm · 2024-06-04T20:43:05Z

galleries/examples/lines_bars_and_markers/multicolored_line.py

+    ----------
+    x, y : array-like or scalar
+        The horizontal and vertical coordinates of the data points.
+    c : array-like or scalar


As above

Suggested change

c : array-like or scalar

c : array-like

eytanadler · 2024-06-05T15:15:19Z

Sorry, I still found some nits, but let's try to be as precise and helpful to users as possible.

Also please squash your commits. They currently add and remove a file, which CI flags as unnecessary overhead.

These are useful fixes, thanks! I tried fixing the git history, but I think I may have made it worse. What git commands do I need to properly squash the previous commits?

rcomer · 2024-06-05T17:10:09Z

@eytanadler to squash, you can do an interactive rebase. I strongly recommend saving a backup copy of your branch first if you have not done this (much) before.

timhoffm · 2024-06-05T21:36:02Z

Thanks @eytanadler and congratulations on your first contribution to Matplotlib 🎉. We hope to hear from you again.

timhoffm · 2024-06-05T21:38:45Z

@meeseeksdev backport to v3.9.x

eytanadler · 2024-06-05T21:40:11Z

Thank you @timhoffm! I’ve gotten so much use out of matplotlib that contributing an example is the least I can do.

…307-on-v3.9.x Backport PR #28307 on branch v3.9.x (DOC: New color line by value example)

* New color line example with multiple coloring methods

github-actions bot added the Documentation: examples files in galleries/examples label May 26, 2024

github-actions bot reviewed May 26, 2024

View reviewed changes

davidlowryduda reviewed May 31, 2024

View reviewed changes

timhoffm reviewed Jun 1, 2024

View reviewed changes

QuLogic mentioned this pull request Jun 4, 2024

[ENH]: Color along line by a value #28242

Closed

eytanadler requested a review from timhoffm June 4, 2024 15:16

QuLogic linked an issue Jun 4, 2024 that may be closed by this pull request

[ENH]: Color along line by a value #28242

Closed

timhoffm reviewed Jun 4, 2024

View reviewed changes

New color line example with multiple coloring methods

19bfcf5

eytanadler force-pushed the colorline_example branch from bad8da4 to 19bfcf5 Compare June 5, 2024 18:16

Add newline to fix flake

2a50e20

timhoffm approved these changes Jun 5, 2024

View reviewed changes

timhoffm merged commit 7ccfd38 into matplotlib:main Jun 5, 2024
20 checks passed

timhoffm added this to the v3.9.1 milestone Jun 5, 2024

meeseeksmachine pushed a commit to meeseeksmachine/matplotlib that referenced this pull request Jun 5, 2024

Backport PR matplotlib#28307: DOC: New color line by value example

7278380

meeseeksmachine mentioned this pull request Jun 5, 2024

Backport PR #28307 on branch v3.9.x (DOC: New color line by value example) #28351

Merged

eytanadler deleted the colorline_example branch June 5, 2024 21:40

timhoffm added a commit that referenced this pull request Jun 5, 2024

Merge pull request #28351 from meeseeksmachine/auto-backport-of-pr-28…

19fe788

…307-on-v3.9.x Backport PR #28307 on branch v3.9.x (DOC: New color line by value example)

muchojp pushed a commit to muchojp/matplotlib that referenced this pull request Jun 6, 2024

DOC: New color line by value example (matplotlib#28307)

1b36a55

* New color line example with multiple coloring methods

	# Add the collection to the axis and return the line collection object
	# Add the collection to the Axes and return the line collection object

		lines = colored_line(x, y, color, ax1, linewidth=10, cmap="plasma")
		cax1 = fig1.colorbar(lines) # add a color legend

		line = colored_line_between_pts(x, y, dydx, ax2, linewidth=2, cmap="viridis")
		cax2 = fig2.colorbar(line, ax=ax2)

		plt.show()


		####################################################################

-####################################################################
+####################################################################
+# This method is designed to give a smooth impression when distances and color
+# differences between adjacent points are not too large. The following example
+# does not meet this criteria and by that serves to illustrate the segmentation
+# and coloring mechanism.
+x = [0, 1, 2, 3, 4]
+y = [0, 1, 2, 1, 1]
+c = [1, 2, 3, 4, 5]
+fig, ax = plt.subplots()
+ax.scatter(x, y, c=c, cmap='rainbow')
+colored_line(x, y, c=c, ax=ax, cmap='rainbow')
+####################################################################

Uh oh!

DOC: New color line by value example #28307

DOC: New color line by value example #28307

Uh oh!

Conversation

eytanadler commented May 26, 2024

PR summary

PR checklist

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

Uh oh!

jklymak commented May 28, 2024

Uh oh!

timhoffm commented May 28, 2024

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eytanadler commented May 31, 2024

Uh oh!

timhoffm left a comment

Choose a reason for hiding this comment

Uh oh!

timhoffm left a comment

Choose a reason for hiding this comment

Uh oh!

timhoffm Jun 1, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

timhoffm Jun 1, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

timhoffm Jun 1, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

timhoffm left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eytanadler commented Jun 5, 2024

Uh oh!

rcomer commented Jun 5, 2024

Uh oh!

Uh oh!

timhoffm commented Jun 5, 2024

Uh oh!

timhoffm commented Jun 5, 2024

Uh oh!

eytanadler commented Jun 5, 2024

Uh oh!

Uh oh!

timhoffm Jun 1, 2024 •

edited

Loading

timhoffm Jun 1, 2024 •

edited

Loading

timhoffm Jun 1, 2024 •

edited

Loading