Documentation Link

https://matplotlib.org/devdocs/gallery/lines_bars_and_markers/scatter_masked.html

Problem

This example contains nothing specifically "wrong" but there are some areas where I see room for improvement:

Introduction

Theexisting 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 theNumPy 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 thatthis page does, for example.

Suggested improvement

I plan to put together a PR addressing the problems noted above. I will:

1. Expand the introduction and add one or more links to the relevant NumPy documentation
2. Simplify the marker styling so that it isn't distracting and doesn't overlap the boundary line
3. Add another example plot (at the top) that shows a basic masking use case
4. Add an explanation to the existing plot to describe how it plots a decision boundary
5. Add references admonition at the end