[ENH] Add data parameter in Axes3D.plot #30270
Conversation
…j/matplotlib into new_feature_issue_30238
Co-Authored-By: Bruno Wolf Povoa <brunowpovoa@gmail.com>
There was a problem hiding this comment.
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).
|
How come the unpacking is done manually here and not using the |
I suspect, that's taken over from the 2d |
lib/mpl_toolkits/mplot3d/axes3d.py
Outdated
| 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 |
There was a problem hiding this comment.
Instead of these lines, you should use the preprocess data decorator. Here's an example:
matplotlib/lib/mpl_toolkits/mplot3d/axes3d.py
Lines 2907 to 2914 in 4c345b4
lib/mpl_toolkits/mplot3d/axes3d.py
Outdated
| .. versionadded:: 3.10 | ||
| data : indexable object, optional | ||
| If given, provides labeled data to plot. |
There was a problem hiding this comment.
| If given, provides labeled data to plot. | |
| DATA_PARAMETER_PLACEHOLDER |
This will be replaced by a customized message by the decorator.
lib/mpl_toolkits/mplot3d/axes3d.py
Outdated
| .. api-changed:: 3.10 | ||
There was a problem hiding this comment.
| .. api-changed:: 3.10 |
AFAIK, there is on api-changed directive?!?
There was a problem hiding this comment.
so, I was also a bit confused about this, what kind of API change note should we add here?
There was a problem hiding this comment.
typo - there's no api-changed directive and that's why Tim is suggesting you delete it.
lib/mpl_toolkits/mplot3d/axes3d.py
Outdated
| 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. |
There was a problem hiding this comment.
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.
lib/mpl_toolkits/mplot3d/axes3d.py
Outdated
| 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. |
There was a problem hiding this comment.
| 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. |
lib/mpl_toolkits/mplot3d/axes3d.py
Outdated
| **kwargs | ||
| Other arguments are forwarded to `matplotlib.axes.Axes.plot`. | ||
| Other arguments forwarded to 'Axes.plot'. |
There was a problem hiding this comment.
but leave the are since that's correct grammar
lib/mpl_toolkits/mplot3d/axes3d.py
Outdated
| def plot(self, xs, ys, zs=0, fmt=None, *, zdir='z', axlim_clip=False, | ||
| **kwargs): |
There was a problem hiding this comment.
| 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): |
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