Skip to content
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

DOC: update the pandas.DataFrame.all docstring #20216

Merged
merged 13 commits into from
Mar 11, 2018
Merged

DOC: update the pandas.DataFrame.all docstring #20216

Changes from 6 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
68657f4
improved docs for pandas.Dataframe.all
Mar 10, 2018
25012e0
Merge remote-tracking branch 'upstream/master' into pandas_dataframe_…
Mar 10, 2018
2088c9f
fixed spacing in examples text
Mar 10, 2018
75e370e
passes pep8 styling
Mar 10, 2018
adacc34
added axis description
Mar 10, 2018
ce5a115
readded the axis paramerte reference and added a kwargs
Mar 10, 2018
cea3edd
Merge remote-tracking branch 'upstream/master' into pandas_dataframe_…
Mar 10, 2018
3347753
made changes requested by core developers
Mar 10, 2018
7ebd4da
removed changes from other branches
Mar 10, 2018
49da2fc
removed typo
Mar 10, 2018
aceed8c
added series.all to see also
Mar 10, 2018
af464c8
fixed doc typo
Mar 10, 2018
23928f9
Merge branch 'master' into PR_TOOL_MERGE_PR_20216
jreback Mar 11, 2018
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
129 changes: 60 additions & 69 deletions pandas/core/generic.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3669,12 +3669,12 @@ def tail(self, n=5):

Returns
-------
type of caller
The last `n` rows of the caller object.
obj_tail : type of caller
The last n rows of the caller object.

See Also
--------
pandas.DataFrame.head : The first `n` rows of the caller object.
pandas.DataFrame.head

Examples
--------
Expand Down Expand Up @@ -4232,55 +4232,7 @@ def as_matrix(self, columns=None):

@property
def values(self):
"""
Return a Numpy representation of the DataFrame.

Only the values in the DataFrame will be returned, the axes labels
will be removed.

Returns
-------
numpy.ndarray
The values of the DataFrame.

Examples
--------
A DataFrame where all columns are the same type (e.g., int64) results
in an array of the same type.

>>> df = pd.DataFrame({'age': [ 3, 29],
... 'height': [94, 170],
... 'weight': [31, 115]})
>>> df
age height weight
0 3 94 31
1 29 170 115
>>> df.dtypes
age int64
height int64
weight int64
dtype: object
>>> df.values
array([[ 3, 94, 31],
[ 29, 170, 115]], dtype=int64)

A DataFrame with mixed type columns(e.g., str/object, int64, float32)
results in an ndarray of the broadest type that accommodates these
mixed types (e.g., object).

>>> df2 = pd.DataFrame([('parrot', 24.0, 'second'),
... ('lion', 80.5, 1),
... ('monkey', np.nan, None)],
... columns=('name', 'max_speed', 'rank'))
>>> df2.dtypes
name object
max_speed float64
rank object
dtype: object
>>> df2.values
array([['parrot', 24.0, 'second'],
['lion', 80.5, 1],
['monkey', nan, None]], dtype=object)
"""Numpy representation of NDFrame

Notes
-----
Expand All @@ -4291,13 +4243,8 @@ def values(self):

e.g. If the dtypes are float16 and float32, dtype will be upcast to
float32. If dtypes are int32 and uint8, dtype will be upcast to
int32. By :func:`numpy.find_common_type` convention, mixing int64
and uint64 will result in a float64 dtype.

See Also
--------
pandas.DataFrame.index : Retrievie the index labels
pandas.DataFrame.columns : Retrieving the column names
int32. By numpy.find_common_type convention, mixing int64 and uint64
will result in a flot64 dtype.
"""
self._consolidate_inplace()
return self._data.as_array(transpose=self._AXIS_REVERSED)
Expand Down Expand Up @@ -7576,11 +7523,10 @@ def _add_numeric_operations(cls):
cls.any = _make_logical_function(
cls, 'any', name, name2, axis_descr,
'Return whether any element is True over requested axis',
nanops.nanany)
nanops.nanany, '', '')
Copy link
Contributor

Choose a reason for hiding this comment

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

Maybe remove these so they don't conflict with the other PR.

Copy link
Contributor Author

@mlaforet mlaforet Mar 10, 2018 •
edited
Loading

Choose a reason for hiding this comment

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

@TomAugspurger If I do this an error

Traceback (most recent call last):
  File "../scripts/validate_docstrings.py", line 37, in <module>
    import pandas
  File "/Users/marconlaforet/pandas-dev/pandas/__init__.py", line 42, in <module>
    from pandas.core.api import *
  File "/Users/marconlaforet/pandas-dev/pandas/core/api.py", line 10, in <module>
    from pandas.core.groupby import Grouper
  File "/Users/marconlaforet/pandas-dev/pandas/core/groupby.py", line 48, in <module>
    from pandas.core.frame import DataFrame
  File "/Users/marconlaforet/pandas-dev/pandas/core/frame.py", line 75, in <module>
    from pandas.core.series import Series
  File "/Users/marconlaforet/pandas-dev/pandas/core/series.py", line 3202, in <module>
    Series._add_numeric_operations()
  File "/Users/marconlaforet/pandas-dev/pandas/core/generic.py", line 7530, in _add_numeric_operations
    nanops.nanany)
TypeError: _make_logical_function() missing 2 required positional arguments: 'examples' and 'see_also'```

Copy link
Member

Choose a reason for hiding this comment

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

Yes, you can keep this. Just depending on which one of the two PRs is merged first, you might need to solve the conflict on the other. But that should be no problem

cls.all = _make_logical_function(
cls, 'all', name, name2, axis_descr,
'Return whether all elements are True over requested axis',
nanops.nanall)
cls, 'all', name, name2, axis_descr, _all_doc,
nanops.nanall, _all_examples, _all_see_also)

@Substitution(outname='mad',
desc="Return the mean absolute deviation of the values "
Expand Down Expand Up @@ -7837,25 +7783,69 @@ def _doc_parms(cls):
%(outname)s : %(name1)s or %(name2)s (if level specified)\n"""

_bool_doc = """

%(desc)s

Parameters
----------
axis : %(axis_descr)s
skipna : boolean, default True
Exclude NA/null values. If an entire row/column is NA, the result
will be NA
will be NA.
level : int or level name, default None
If the axis is a MultiIndex (hierarchical), count along a
particular level, collapsing into a %(name1)s
particular level, collapsing into a %(name1)s.
bool_only : boolean, default None
Include only boolean columns. If None, will attempt to use everything,
then use only boolean data. Not implemented for Series.
**kwargs : any, default None
Additional keywords have no fect but might be accepted for
Copy link
Contributor

Choose a reason for hiding this comment

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

fect -> affect.

compatibility with numpy.

Returns
-------
%(outname)s : %(name1)s or %(name2)s (if level specified)\n"""
%(outname)s : %(name1)s or %(name2)s (if level specified)

%(examples)s
%(see_also)s"""

_all_doc = """\
Return whether all elements are True over requested axis.

Returns True if all elements along a dataframe
axis are non-zero, not-empty or not-False.
Also note that a series consisting of different data
Copy link
Contributor

Choose a reason for hiding this comment

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

You can remove this second sentence. THe fact that this happens is a bug, so we don't want to document it.

types returns the first occurence of the non-zero, not-empty
or not-False element."""

_all_examples = """\
Examples
--------
First create a pandas dataframe::
Copy link
Contributor

Choose a reason for hiding this comment

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

No dobule colon.

>>> d = {'col1': [True, True], 'col2': [True, False]}
Copy link
Contributor

Choose a reason for hiding this comment

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

No indent.

>>> df = pd.DataFrame(data=d)
>>> df
col1 col2
0 True True
1 True False

Default behaviour checks if column-wise values all return True
>>> df.all()
col1 True
col2 False
dtype: bool

Adding axis=1 will check row-wise values
>>> df.all(axis=1)
0 True
1 False
dtype: bool
"""

_all_see_also = """\
See also
--------
pandas.DataFrame.any : Checks if one (or more) items return True
"""
Copy link
Contributor

Choose a reason for hiding this comment

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

add Series.all

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@jreback its been added


_cnum_doc = """

Expand Down Expand Up @@ -8038,9 +8028,10 @@ def cum_func(self, axis=None, skipna=True, *args, **kwargs):
return set_function_name(cum_func, name, cls)


def _make_logical_function(cls, name, name1, name2, axis_descr, desc, f):
def _make_logical_function(cls, name, name1, name2, axis_descr, desc, f,
examples, see_also):
@Substitution(outname=name, desc=desc, name1=name1, name2=name2,
axis_descr=axis_descr)
axis_descr=axis_descr, examples=examples, see_also=see_also)
@Appender(_bool_doc)
def logical_func(self, axis=None, bool_only=None, skipna=None, level=None,
**kwargs):
Expand Down