Skip to content

make series axis parameter docs consistent #47109

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.

Sign up for GitHub

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

Merged
merged 11 commits into from
May 27, 2022
Merged

make series axis parameter docs consistent #47109

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
35c06ad
make series docs consistent
uncjackg May 25, 2022
969d456
fix trailing whitespace
jackgoldsmith4 May 25, 2022
5550f3c
fix docs build
jackgoldsmith4 May 25, 2022
c5a8b41
add unused
jackgoldsmith4 May 25, 2022
1582bd9
add or update docs for all series methods
jackgoldsmith4 May 26, 2022
72f8f8c
small fix
jackgoldsmith4 May 26, 2022
054c641
fix line length
jackgoldsmith4 May 26, 2022
03a0b33
fix param order
jackgoldsmith4 May 26, 2022
2cf6d8c
fix param order
jackgoldsmith4 May 26, 2022
f62a1b4
add
jackgoldsmith4 May 27, 2022
95cedca
add backticks to None and fix space
jackgoldsmith4 May 27, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions pandas/core/arrays/datetimes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2004,6 +2004,7 @@ def std(
----------
axis : int optional, default None
Axis for the function to be applied on.
For `Series` this parameter is unused and defaults to None.
ddof : int, default 1
Degrees of Freedom. The divisor used in calculations is N - ddof,
where N represents the number of elements.
Expand Down
2 changes: 1 addition & 1 deletion pandas/core/base.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -599,7 +599,7 @@ def argmax(self, axis=None, skipna: bool = True, *args, **kwargs) -> int:
Parameters
----------
axis : {{None}}
Dummy argument for consistency with Series.
Unused. Parameter needed for compatibility with DataFrame.
skipna : bool, default True
Exclude NA/null values when showing the result.
*args, **kwargs
Expand Down
48 changes: 34 additions & 14 deletions pandas/core/generic.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -727,7 +727,8 @@ def set_axis(self, labels, axis: Axis = 0, inplace: bool_t = False):
The values for the new index.

axis : %(axes_single_arg)s, default 0
The axis to update. The value 0 identifies the rows%(axis_description_sub)s.
The axis to update. The value 0 identifies the rows. For `Series`
this parameter is unused and defaults to 0.

inplace : bool, default False
Whether to return a new %(klass)s instance.
Expand Down Expand Up @@ -807,6 +808,8 @@ def droplevel(self: NDFrameT, level, axis=0) -> NDFrameT:
* 0 or 'index': remove level(s) in column.
* 1 or 'columns': remove level(s) in row.

For `Series` this parameter is unused and defaults to 0.

Returns
-------
{klass}
Expand Down Expand Up @@ -875,7 +878,7 @@ def squeeze(self, axis=None):
----------
axis : {0 or 'index', 1 or 'columns', None}, default None
A specific axis to squeeze. By default, all length-1 axes are
squeezed.
squeezed. For `Series` this parameter is unused and defaults to None.

Returns
-------
Expand Down Expand Up @@ -1063,7 +1066,7 @@ def rename_axis(self, mapper=lib.no_default, **kwargs):
specify the axis to target with ``mapper``, or ``index``
and/or ``columns``.
axis : {0 or 'index', 1 or 'columns'}, default 0
The axis to rename.
The axis to rename. For `Series` this parameter is unused and defaults to 0.
copy : bool, default True
Also copy underlying data.
inplace : bool, default False
Expand Down Expand Up @@ -3541,6 +3544,7 @@ def take(
axis : {0 or 'index', 1 or 'columns', None}, default 0
The axis on which to select elements. ``0`` means that we are
selecting rows, ``1`` means that we are selecting columns.
For `Series` this parameter is unused and defaults to 0.
is_copy : bool
Before pandas 1.0, ``is_copy=False`` can be specified to ensure
that the return value is an actual copy. Starting with pandas 1.0,
Expand Down Expand Up @@ -5086,8 +5090,8 @@ def filter(
Keep labels from axis for which re.search(regex, label) == True.
axis : {0 or ‘index’, 1 or ‘columns’, None}, default None
The axis to filter on, expressed either as an index (int)
or axis name (str). By default this is the info axis,
'index' for Series, 'columns' for DataFrame.
or axis name (str). By default this is the info axis, 'columns' for
DataFrame.For `Series` this parameter is unused and defaults to None.

Returns
-------
Expand Down Expand Up @@ -5371,7 +5375,7 @@ def sample(

axis : {0 or ‘index’, 1 or ‘columns’, None}, default None
Axis to sample. Accepts axis number or name. Default is stat axis
for given data type (0 for Series and DataFrames).
for given data type. For `Series` this parameter is unused and defaults to None.
ignore_index : bool, default False
If True, the resulting index will be labeled 0, 1, …, n - 1.

Expand Down Expand Up @@ -6353,7 +6357,8 @@ def fillna(
pad / ffill: propagate last valid observation forward to next valid
backfill / bfill: use next valid observation to fill gap.
axis : {axes_single_arg}
Axis along which to fill missing values.
Axis along which to fill missing values. For `Series`
this parameter is unused and defaults to 0.
inplace : bool, default False
If True, fill in-place. Note: this will modify any
other views on this object (e.g., a no-copy slice for a column in a
Expand Down Expand Up @@ -6829,7 +6834,8 @@ def interpolate(
scipy 0.18.

axis : {{0 or 'index', 1 or 'columns', None}}, default None
Axis to interpolate along.
Axis to interpolate along. For `Series` this parameter is unused
and defaults to 0.
limit : int, optional
Maximum number of consecutive NaNs to fill. Must be greater than
0.
Expand Down Expand Up @@ -7476,8 +7482,9 @@ def clip(
Maximum threshold value. All values above this
threshold will be set to it. A missing
threshold (e.g `NA`) will not clip the value.
axis : int or str axis name, optional
axis : {{0 or 'index', 1 or 'columns', None}}, default None
Align object with lower and upper along the given axis.
For `Series` this parameter is unused and defaults to None.
inplace : bool, default False
Whether to perform the operation in place on the data.
*args, **kwargs
Expand Down Expand Up @@ -7743,6 +7750,7 @@ def at_time(self: NDFrameT, time, asof: bool_t = False, axis=None) -> NDFrameT:
----------
time : datetime.time or str
axis : {0 or 'index', 1 or 'columns'}, default 0
For `Series` this parameter is unused and defaults to 0.

Returns
-------
Expand Down Expand Up @@ -7829,6 +7837,7 @@ def between_time(
Include boundaries; whether to set each bound as closed or open.
axis : {0 or 'index', 1 or 'columns'}, default 0
Determine range time on index or columns value.
For `Series` this parameter is unused and defaults to 0.

Returns
-------
Expand Down Expand Up @@ -7950,8 +7959,8 @@ def resample(
rule : DateOffset, Timedelta or str
The offset string or object representing target conversion.
axis : {{0 or 'index', 1 or 'columns'}}, default 0
Which axis to use for up- or down-sampling. For `Series` this
will default to 0, i.e. along the rows. Must be
Which axis to use for up- or down-sampling. For `Series` this parameter
is unused and defaults to 0. Must be
`DatetimeIndex`, `TimedeltaIndex` or `PeriodIndex`.
closed : {{'right', 'left'}}, default None
Which side of bin interval is closed. The default is 'left'
Expand Down Expand Up @@ -8520,6 +8529,7 @@ def rank(
----------
axis : {0 or 'index', 1 or 'columns'}, default 0
Index to direct ranking.
For `Series` this parameter is unused and defaults to 0.
method : {'average', 'min', 'max', 'first', 'dense'}, default 'average'
How to rank the group of records that have the same value (i.e. ties):

Expand Down Expand Up @@ -9257,7 +9267,8 @@ def where(
inplace : bool, default False
Whether to perform the operation in place on the data.
axis : int, default None
Alignment axis if needed.
Alignment axis if needed. For `Series` this parameter is
unused and defaults to 0.
level : int, default None
Alignment level if needed.
errors : str, {{'raise', 'ignore'}}, default 'raise'
Expand Down Expand Up @@ -9442,7 +9453,7 @@ def shift(
the freq or inferred_freq attributes of the index. If neither of
those attributes exist, a ValueError is thrown.
axis : {{0 or 'index', 1 or 'columns', None}}, default None
Shift direction.
Shift direction. For `Series` this parameter is unused and defaults to 0.
fill_value : object, optional
The scalar value to use for newly introduced missing values.
the default depends on the dtype of `self`.
Expand Down Expand Up @@ -9576,6 +9587,8 @@ def slice_shift(self: NDFrameT, periods: int = 1, axis=0) -> NDFrameT:
----------
periods : int
Number of periods to move, can be positive or negative.
axis : {0 or 'index', 1 or 'columns', None}, default 0
For `Series` this parameter is unused and defaults to 0.

Returns
-------
Expand Down Expand Up @@ -9627,6 +9640,7 @@ def tshift(self: NDFrameT, periods: int = 1, freq=None, axis: Axis = 0) -> NDFra
or time rule expressed as a string (e.g. 'EOM').
axis : {0 or ‘index’, 1 or ‘columns’, None}, default 0
Corresponds to the axis that contains the Index.
For `Series` this parameter is unused and defaults to 0.

Returns
-------
Expand Down Expand Up @@ -9669,6 +9683,7 @@ def truncate(
Truncate all rows after this index value.
axis : {0 or 'index', 1 or 'columns'}, optional
Axis to truncate. Truncates the index (rows) by default.
For `Series` this parameter is unused and defaults to 0.
copy : bool, default is True,
Return a copy of the truncated section.

Expand Down Expand Up @@ -10891,6 +10906,7 @@ def mad(
----------
axis : {axis_descr}
Axis for the function to be applied on.
For `Series` this parameter is unused and defaults to 0.
skipna : bool, default True
Exclude NA/null values when computing the result.
level : int or level name, default None
Expand Down Expand Up @@ -11549,6 +11565,7 @@ def _doc_params(cls):
----------
axis : {axis_descr}
Axis for the function to be applied on.
For `Series` this parameter is unused and defaults to 0.
skipna : bool, default True
Exclude NA/null values when computing the result.
level : int or level name, default None
Expand Down Expand Up @@ -11579,6 +11596,7 @@ def _doc_params(cls):
Parameters
----------
axis : {axis_descr}
For `Series` this parameter is unused and defaults to 0.
skipna : bool, default True
Exclude NA/null values. If an entire row/column is NA, the result
will be NA.
Expand Down Expand Up @@ -11670,7 +11688,8 @@ def _doc_params(cls):
Parameters
----------
axis : {{0 or 'index', 1 or 'columns', None}}, default 0
Indicate which axis or axes should be reduced.
Indicate which axis or axes should be reduced. For `Series` this parameter
is unused and defaults to 0.

* 0 / 'index' : reduce the index, return a Series whose index is the
original column labels.
Expand Down Expand Up @@ -11772,6 +11791,7 @@ def _doc_params(cls):
----------
axis : {{0 or 'index', 1 or 'columns'}}, default 0
The index or the name of the axis. 0 is equivalent to None or 'index'.
For `Series` this parameter is unused and defaults to 0.
skipna : bool, default True
Exclude NA/null values. If an entire row/column is NA, the result
will be NA.
Expand Down
10 changes: 6 additions & 4 deletions pandas/core/ops/docstrings.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -428,14 +428,16 @@ def make_flex_doc(op_name: str, typ: str) -> str:
Parameters
----------
other : Series or scalar value
level : int or name
Broadcast across a level, matching Index values on the
passed MultiIndex level.
fill_value : None or float value, default None (NaN)
Fill existing missing (NaN) values, and any new element needed for
successful Series alignment, with this value before computation.
If data in both corresponding Series locations is missing
the result of filling (at that location) will be missing.
level : int or name
Broadcast across a level, matching Index values on the
passed MultiIndex level.
axis : {{0 or 'index'}}
Unused. Parameter needed for compatibility with DataFrame.

Returns
-------
Expand All @@ -462,7 +464,7 @@ def make_flex_doc(op_name: str, typ: str) -> str:
other : scalar, sequence, Series, or DataFrame
Any single or multiple element data structure, or list-like object.
axis : {{0 or 'index', 1 or 'columns'}}
Whether to compare by the index (0 or 'index') or columns
Whether to compare by the index (0 or 'index') or columns.
(1 or 'columns'). For Series input, axis to match Series index on.
level : int or label
Broadcast across a level, matching Index values on the
Expand Down
40 changes: 18 additions & 22 deletions pandas/core/series.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,7 +171,7 @@
"klass": "Series",
"axes_single_arg": "{0 or 'index'}",
"axis": """axis : {0 or 'index'}
Parameter needed for compatibility with DataFrame.""",
Unused. Parameter needed for compatibility with DataFrame.""",
"inplace": """inplace : bool, default False
If True, performs operation inplace and returns None.""",
"unique": "np.ndarray",
Expand Down Expand Up @@ -1322,8 +1322,7 @@ def repeat(self, repeats, axis=None) -> Series:
non-negative integer. Repeating 0 times will return an empty
Series.
axis : None
Must be ``None``. Has no effect but is accepted for compatibility
with numpy.
Unused. Parameter needed for compatibility with DataFrame.

Returns
-------
Expand Down Expand Up @@ -2311,9 +2310,8 @@ def idxmin(self, axis=0, skipna=True, *args, **kwargs):

Parameters
----------
axis : int, default 0
For compatibility with DataFrame.idxmin. Redundant for application
on Series.
axis : {0 or 'index'}
Unused. Parameter needed for compatibility with DataFrame.
skipna : bool, default True
Exclude NA/null values. If the entire Series is NA, the result
will be NA.
Expand Down Expand Up @@ -2380,9 +2378,8 @@ def idxmax(self, axis=0, skipna=True, *args, **kwargs):

Parameters
----------
axis : int, default 0
For compatibility with DataFrame.idxmax. Redundant for application
on Series.
axis : {0 or 'index'}
Unused. Parameter needed for compatibility with DataFrame.
skipna : bool, default True
Exclude NA/null values. If the entire Series is NA, the result
will be NA.
Expand Down Expand Up @@ -3389,9 +3386,8 @@ def sort_values(

Parameters
----------
axis : {0 or 'index'}, default 0
Axis to direct sorting. The value 'index' is accepted for
compatibility with DataFrame.sort_values.
axis : {0 or 'index'}
Unused. Parameter needed for compatibility with DataFrame.
ascending : bool or list of bools, default True
If True, sort values in ascending order, otherwise descending.
inplace : bool, default False
Expand Down Expand Up @@ -3650,8 +3646,8 @@ def sort_index( # type: ignore[override]

Parameters
----------
axis : int, default 0
Axis to direct sorting. This can only be 0 for Series.
axis : {0 or 'index'}
Unused. Parameter needed for compatibility with DataFrame.
level : int, optional
If not None, sort on values in specified index level(s).
ascending : bool or list-like of bools, default True
Expand Down Expand Up @@ -3798,8 +3794,8 @@ def argsort(self, axis=0, kind="quicksort", order=None) -> Series:

Parameters
----------
axis : {0 or "index"}
Has no effect but is accepted for compatibility with numpy.
axis : {0 or 'index'}
Unused. Parameter needed for compatibility with DataFrame.
kind : {'mergesort', 'quicksort', 'heapsort', 'stable'}, default 'quicksort'
Choice of sorting algorithm. See :func:`numpy.sort` for more
information. 'mergesort' and 'stable' are the only stable algorithms.
Expand Down Expand Up @@ -4716,8 +4712,8 @@ def rename(

Parameters
----------
axis : {0 or "index"}
Unused. Accepted for compatibility with DataFrame method only.
axis : {0 or 'index'}
Unused. Parameter needed for compatibility with DataFrame.
index : scalar, hashable sequence, dict-like or function, optional
Functions or dict-like are transformations to apply to
the index.
Expand Down Expand Up @@ -4914,8 +4910,8 @@ def drop( # type: ignore[override]
----------
labels : single label or list-like
Index labels to drop.
axis : 0, default 0
Redundant for application on Series.
axis : {0 or 'index'}
Unused. Parameter needed for compatibility with DataFrame.
index : single label or list-like
Redundant for application on Series, but 'index' can be used instead
of 'labels'.
Expand Down Expand Up @@ -5529,8 +5525,8 @@ def dropna(self, axis=0, inplace=False, how=None):

Parameters
----------
axis : {0 or 'index'}, default 0
There is only one axis to drop values from.
axis : {0 or 'index'}
Unused. Parameter needed for compatibility with DataFrame.
inplace : bool, default False
If True, do operation inplace and return None.
how : str, optional
Expand Down
3 changes: 2 additions & 1 deletion pandas/core/shared_docs.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,8 @@
of labels may be passed to group by the columns in ``self``.
Notice that a tuple is interpreted as a (single) key.
axis : {0 or 'index', 1 or 'columns'}, default 0
Split along rows (0) or columns (1).
Split along rows (0) or columns (1). For `Series` this parameter
is unused and defaults to 0.
level : int, level name, or sequence of such, default None
If the axis is a MultiIndex (hierarchical), group by a particular
level or levels.
Expand Down
2 changes: 2 additions & 0 deletions pandas/core/window/ewm.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -211,6 +211,8 @@ class ExponentialMovingWindow(BaseWindow):

If ``1`` or ``'columns'``, calculate across the columns.

For `Series` this parameter is unused and defaults to 0.

times : str, np.ndarray, Series, default None

.. versionadded:: 1.1.0
Expand Down
Loading