Repository navigation
[Doc]: Revise "Scatter Masked" Example #24357
Description
Documentation Link
Problem
This example contains nothing specifically "wrong" but there are some areas where I see room for improvement:
Introduction
The existing example introduction reads:
Mask some data points and add a line demarking masked regions.
This doesn't provide the context that it's actually showing how to work with the NumPy masked array construct + Matplotlib. Matplotlib is not actually performing the masking.
Plot Styling
The marker sizes and colors are assigned randomly, add visual noise, and don't contribute to the explanation of masking.
Also the large size of some markers cause them to overlap with the boundary line:
Masking vs. Decision Boundary Conceptual Confusion
I believe that masking is most commonly used with Matplotlib to avoid drawing some data points altogether. For example, this StackOverflow answer.
The current example does not do that, and instead uses masking to style some data points in one way and some data points in another way. This is conceptually more like plotting a decision boundary.
References
The page does not include links to the referenced Matplotlib methods, the way that this page does, for example.
Suggested improvement
I plan to put together a PR addressing the problems noted above. I will:
- Expand the introduction and add one or more links to the relevant NumPy documentation
- Simplify the marker styling so that it isn't distracting and doesn't overlap the boundary line
- Add another example plot (at the top) that shows a basic masking use case
- Add an explanation to the existing plot to describe how it plots a decision boundary
- Add references admonition at the end
Activity
timhoffm commentedon Nov 3, 2022
Thanks for bringing this up! I totally agree that the example does not make much sense as is. The suggestions look good overall. Feel free to change whatever you think is reasonsable. This can go as far as replacing the whole contents of the example; or even removing it and optionally creating other examples.
github-actions commentedon Jan 12, 2026
This issue has been marked "inactive" because it has been 365 days since the last comment. If this issue is still present in recent Matplotlib releases, or the feature request is still wanted, please leave a comment and this label will be removed. If there are no updates in another 30 days, this issue will be automatically closed, but you are free to re-open or create a new issue if needed. We value issue reports, and this procedure is meant to help us resurface and prioritize issues that have not been addressed yet, not make them disappear. Thanks for your help!
timhoffm commentedon Jan 12, 2026
I was about to say that we don't need this example at all. You can always partition your data through a boolean mask and plot the different parts.
the slight twist here is to use a masked array (or what equally works is copying and setting the respective values to NaN). This is sufficient on one of the input arrays.
I propose to just delete the example as it's mainly data preprocessing and not so much about plotting. The only plotting relevant aspect I see is the usage and handling of masked/NaN data. We already have an example for that https://matplotlib.org/devdocs/gallery/lines_bars_and_markers/masked_demo.html. The only additional aspect here is that you use the mask and it's inverse, but again this is more data handling, not plotting.