Skip to content

[ENH] Add data parameter in Axes3D.plot #30270

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 19 commits into
base: main
Choose a base branch
from

Conversation

vagnermcj
Copy link
Contributor

@vagnermcj vagnermcj commented Jul 7, 2025

PR summary

This PR modernizes and clarifies the Axes3D.plot API by requiring an explicit zs argument and using a new explicit fmt keyword parameter instead of relying on positional argument parsing.

What is the reasoning for this implementation?

zs is now a dedicated positional argument with a default (0) for compatibility with 2D-like plots.

Format strings are passed explicitly via fmt=..., which removes the need for positional parsing heuristics.

The new signature simplifies error handling and reduces bugs related to ambiguous argument positions.

Summary of changes:

Updated Axes3D.plot to use xs, ys, zs=0, fmt=None, *, zdir='z', axlim_clip=False, data=None, **kwargs.

Added support for data keyword argument, allowing string keys as input (e.g., plot('x', 'y', 'z', fmt='r', data=...)).

This implementation intend to solve issue #30238

Copy link
Member

@timhoffm timhoffm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add an API change note according to https://matplotlib.org/devdocs/devel/api_changes.html#announce-new-and-deprecated-api.

While we skip a deprecation we must still announce the formal API incompatibility for edge cases like plot(xs, ys, 'ro', zs=zs) (please check if there are more).

@story645
Copy link
Member

story645 commented Jul 7, 2025

How come the unpacking is done manually here and not using the _preprocess_data decorator?

@timhoffm
Copy link
Member

timhoffm commented Jul 7, 2025

How come the unpacking is done manually here and not using the _preprocess_data decorator?

I suspect, that's taken over from the 2d Axes.plot - there it has to be manual because of the *args wildcard. But here with explicit xs, ys, zs parameter the decorator can and should be used.

Comment on lines 2012 to 2015
if data is not None:
xs = data[xs] if isinstance(xs, str) else xs
ys = data[ys] if isinstance(ys, str) else ys
zs = data[zs] if isinstance(zs, str) else zs
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of these lines, you should use the preprocess data decorator. Here's an example:

@_preprocess_data(replace_names=["xs", "ys", "zs", "s",
"edgecolors", "c", "facecolor",
"facecolors", "color"])
def scatter(self, xs, ys, zs=0, zdir='z', s=20, c=None, depthshade=None,
*args,
depthshade_minalpha=None,
axlim_clip=False,
**kwargs):


.. versionadded:: 3.10
data : indexable object, optional
If given, provides labeled data to plot.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If given, provides labeled data to plot.
DATA_PARAMETER_PLACEHOLDER

This will be replaced by a customized message by the decorator.

Comment on lines 1974 to 1975
.. api-changed:: 3.10

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
.. api-changed:: 3.10

AFAIK, there is on api-changed directive?!?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

so, I was also a bit confused about this, what kind of API change note should we add here?

Copy link
Member

@story645 story645 Jul 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo - there's no api-changed directive and that's why Tim is suggesting you delete it.

Comment on lines 1992 to 1999
xs : 1D array-like or label
x coordinates of vertices, or a column label if 'data' is given.
ys : 1D array-like or label
y coordinates of vertices, or a column label if 'data' is given.
zs : float or 1D array-like or label, default: 0
z coordinates of vertices, or a column label if 'data' is given.
fmt : str, optional
A format string, e.g., 'ro' for red circles.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please revert. We don't explicitly document the modified behavior through the data parameter in each affected parameter, instead it's all in the data docstring.

Comment on lines 1976 to 1988
The signature of ``Axes3D.plot`` was changed to require all positional data
arguments (xs, ys, zs) and the format string (fmt) to be passed
positionally.All other arguments, including ``zdir``, ``axlim_clip``,
and ``data``, must be passed as keyword arguments.

This is a formal API incompatibility for edge cases such as
``plot(xs, ys, 'ro', zs=zs)``, which is no longer supported. Instead,
use ``plot(xs, ys, zs, 'ro')`` or ``plot(xs, ys, zs=zs, fmt='ro')``.

This change brings the 3D API in line with the 2D API and avoids
ambiguity in argument parsing.Other similar edge cases where a style
string is followed by a keyword data argument are
also now formally incompatible.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The signature of ``Axes3D.plot`` was changed to require all positional data
arguments (xs, ys, zs) and the format string (fmt) to be passed
positionally.All other arguments, including ``zdir``, ``axlim_clip``,
and ``data``, must be passed as keyword arguments.
This is a formal API incompatibility for edge cases such as
``plot(xs, ys, 'ro', zs=zs)``, which is no longer supported. Instead,
use ``plot(xs, ys, zs, 'ro')`` or ``plot(xs, ys, zs=zs, fmt='ro')``.
This change brings the 3D API in line with the 2D API and avoids
ambiguity in argument parsing.Other similar edge cases where a style
string is followed by a keyword data argument are
also now formally incompatible.
The signature was changed to make the parameters *zs* and *fmt* explicit.
The unconventional but previously valid call signature
``plot(xs, ys, 'ro', zs=zs)`` is no longer supported.

**kwargs
Other arguments are forwarded to `matplotlib.axes.Axes.plot`.
Other arguments forwarded to 'Axes.plot'.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please revert.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but leave the are since that's correct grammar

Comment on lines 1967 to 1968
def plot(self, xs, ys, zs=0, fmt=None, *, zdir='z', axlim_clip=False,
**kwargs):
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
def plot(self, xs, ys, zs=0, fmt=None, *, zdir='z', axlim_clip=False,
**kwargs):
def plot(self, xs, ys, zs=0, fmt=None, *, zdir='z', axlim_clip=False, **kwargs):

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy