DOC: update the pandas.DataFrame.isna and pandas.Series.isna docstring #20138

datadonK23 · 2018-03-10T13:55:00Z

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

PR title is "DOC: update the docstring"
The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
The html version looks good: python doc/make.py --single <your-function-or-method>
It has been proofread on language by another sprint participant

Two Validations for pandas.DataFrame.isna and pandas.Series.isna (shared docs).

################################################################################
###################### Docstring (pandas.DataFrame.isna)  ######################
################################################################################

Detect missing values.

Return a boolean same-sized object indicating if the values are NA.
NA values, such as None or :attr:`numpy.NaN`, get mapped to True
values.
Everything else get mapped to False values. Characters such as empty
strings `''` or :attr:`numpy.inf` are not considered NA values
(unless you set :attr:`pandas.options.mode.use_inf_as_na` `= True`).

Returns
-------
bool of type DataFrame
    Mask of True/False values for each element in DataFrame that
    indicates whether an element is an NA value

See Also
--------
DataFrame.isnull : alias of isna
DataFrame.notna : boolean inverse of isna
DataFrame.dropna : omit axes labels with missing values
isna : top-level isna

Examples
--------
Show which entries in a DataFrame are NA.

>>> df = pd.DataFrame({'age': [5, 6, np.NaN],
...                    'born': [pd.NaT, pd.Timestamp('1939-05-27'),
...                             pd.Timestamp('1940-04-25')],
...                    'name': ['Alfred', 'Batman', ''],
...                    'toy': [None, 'Batmobile', 'Joker']})
>>> df
   age       born    name        toy
0  5.0        NaT  Alfred       None
1  6.0 1939-05-27  Batman  Batmobile
2  NaN 1940-04-25              Joker

>>> df.isna()
     age   born   name    toy
0  False   True  False   True
1  False  False  False  False
2   True  False  False  False

Show which entries in a Series are NA.

>>> ser = pd.Series([5, 6, np.NaN])
>>> ser
0    5.0
1    6.0
2    NaN
dtype: float64

>>> ser.isna()
0    False
1    False
2     True
dtype: bool

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.isna" correct. :)

################################################################################
######################## Docstring (pandas.Series.isna) ########################
################################################################################

Detect missing values.

Return a boolean same-sized object indicating if the values are NA.
NA values, such as None or :attr:`numpy.NaN`, get mapped to True
values.
Everything else get mapped to False values. Characters such as empty
strings `''` or :attr:`numpy.inf` are not considered NA values
(unless you set :attr:`pandas.options.mode.use_inf_as_na` `= True`).

Returns
-------
bool of type Series
    Mask of True/False values for each element in Series that
    indicates whether an element is an NA value

See Also
--------
Series.isnull : alias of isna
Series.notna : boolean inverse of isna
Series.dropna : omit axes labels with missing values
isna : top-level isna

Examples
--------
Show which entries in a DataFrame are NA.

>>> df = pd.DataFrame({'age': [5, 6, np.NaN],
...                    'born': [pd.NaT, pd.Timestamp('1939-05-27'),
...                             pd.Timestamp('1940-04-25')],
...                    'name': ['Alfred', 'Batman', ''],
...                    'toy': [None, 'Batmobile', 'Joker']})
>>> df
   age       born    name        toy
0  5.0        NaT  Alfred       None
1  6.0 1939-05-27  Batman  Batmobile
2  NaN 1940-04-25              Joker

>>> df.isna()
     age   born   name    toy
0  False   True  False   True
1  False  False  False  False
2   True  False  False  False

Show which entries in a Series are NA.

>>> ser = pd.Series([5, 6, np.NaN])
>>> ser
0    5.0
1    6.0
2    NaN
dtype: float64

>>> ser.isna()
0    False
1    False
2     True
dtype: bool

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.Series.isna" correct. :)

villasv · 2018-03-10T14:39:19Z

pandas/core/generic.py

+        -------
+        bool of type %(klass)s
+            Mask of True/False values for each element in %(klass)s that
+            indicates whether an element is an NA value


Missing dot

villasv · 2018-03-10T14:39:35Z

pandas/core/indexes/base.py


        .. versionadded:: 0.20.0

        Returns
        -------
-        a boolean array of whether my values are NA
+        numpy.ndarray
+            A boolean array of whether my values are NA


Missing dot

pep8speaks · 2018-03-10T14:52:00Z

Hello @Donk23! Thanks for updating the PR.

Cheers ! There are no PEP8 issues in this Pull Request. 🍻

Comment last updated on March 13, 2018 at 12:47 Hours UTC

datadonK23 · 2018-03-10T14:56:41Z

################################################################################
###################### Docstring (pandas.DataFrame.isna)  ######################
################################################################################

Detect missing values.

Return a boolean same-sized object indicating if the values are NA.
NA values, such as None or :attr:`numpy.NaN`, get mapped to True
values.
Everything else get mapped to False values. Characters such as empty
strings `''` or :attr:`numpy.inf` are not considered NA values
(unless you set :attr:`pandas.options.mode.use_inf_as_na` `= True`).

Returns
-------
bool of type DataFrame
    Mask of True/False values for each element in DataFrame that
    indicates whether an element is an NA value.

See Also
--------
DataFrame.isnull : alias of isna
DataFrame.notna : boolean inverse of isna
DataFrame.dropna : omit axes labels with missing values
isna : top-level isna

Examples
--------
Show which entries in a DataFrame are NA.

>>> df = pd.DataFrame({'age': [5, 6, np.NaN],
...                    'born': [pd.NaT, pd.Timestamp('1939-05-27'),
...                             pd.Timestamp('1940-04-25')],
...                    'name': ['Alfred', 'Batman', ''],
...                    'toy': [None, 'Batmobile', 'Joker']})
>>> df
   age       born    name        toy
0  5.0        NaT  Alfred       None
1  6.0 1939-05-27  Batman  Batmobile
2  NaN 1940-04-25              Joker

>>> df.isna()
     age   born   name    toy
0  False   True  False   True
1  False  False  False  False
2   True  False  False  False

Show which entries in a Series are NA.

>>> ser = pd.Series([5, 6, np.NaN])
>>> ser
0    5.0
1    6.0
2    NaN
dtype: float64

>>> ser.isna()
0    False
1    False
2     True
dtype: bool

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.isna" correct. :)

villasv · 2018-03-10T14:58:24Z

pandas/core/indexes/base.py


        .. versionadded:: 0.20.0

        Returns
        -------
-        numpy.ndarray
-            A boolean array of whether my values are NA
+        a boolean array of whether my values are NA


The right format should probably be

numpy.ndarray Boolean array of whether my values are NA.

Though I'd advise against "my values" and refer to the data structure.

The documentation of the return is also similar to the parameters. But in this case, no name will be provided, unless the method returns or yields more than one value (a tuple of values).

The parameters are defined by their name, followed by a space, a colon, another space, and the type (or types). Note that the space between the name and the colon is important. Types are not defined for *args and **kwargs, but must be defined for all other parameters. After the parameter definition, it is required to have a line with the parameter description, which is indented, and can have multiple lines. The description must start with a capital letter, and finish with a dot.

Please ignore, was from incorrect commit

jorisvandenbossche

Minor comment, for the rest looking very good!

jorisvandenbossche · 2018-03-12T22:55:07Z

pandas/core/generic.py

+        values.
+        Everything else get mapped to False values. Characters such as empty
+        strings `''` or :attr:`numpy.inf` are not considered NA values
+        (unless you set :attr:`pandas.options.mode.use_inf_as_na` `= True`).


Similar comment here as on the notna PR

jorisvandenbossche · 2018-03-12T22:55:19Z

pandas/core/generic.py

+
+        Returns
+        -------
+        bool of type %(klass)s


and here as well

codecov · 2018-03-13T12:47:15Z

Codecov Report

❗ No coverage uploaded for pull request base (master@fb556ed). Click here to learn what that means.
The diff coverage is 100%.

@@            Coverage Diff            @@
##             master   #20138   +/-   ##
=========================================
  Coverage          ?    91.7%           
=========================================
  Files             ?      150           
  Lines             ?    49152           
  Branches          ?        0           
=========================================
  Hits              ?    45074           
  Misses            ?     4078           
  Partials          ?        0

Flag	Coverage Δ
#multiple	`90.08% <100%> (?)`
#single	`41.84% <2.85%> (?)`

Impacted Files	Coverage Δ
pandas/core/indexes/base.py	`96.66% <ø> (ø)`
pandas/core/generic.py	`95.84% <100%> (ø)`

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update fb556ed...d2d5fcc. Read the comment docs.

datadonK23 · 2018-03-13T12:50:47Z

Made the changes. Now it should be consistent with the .notna docstrings (PR #20160).

TomAugspurger · 2018-03-13T12:51:17Z

Thanks @Donk23 !

datadonK23 added 3 commits March 10, 2018 13:56

DOC: improved docstring of pandas.Index.isna

31b80ae

DOC: improved docstring of pandas.Index.isna

c25704f

DOC: update pandas.DataFrame.isna and pandas.Series.isna

bab0012

villasv suggested changes Mar 10, 2018

View reviewed changes

DOC: fixed docstring and undid accidental commit

a3a6b85

DOC: Trying to undo accidental commit

c630f65

villasv suggested changes Mar 10, 2018

View reviewed changes

Merge remote-tracking branch 'upstream/master' into docstring_isna

80f0d37

jorisvandenbossche added the Docs label Mar 12, 2018

jorisvandenbossche reviewed Mar 12, 2018

View reviewed changes

Fixed Returns, link and typos

d2d5fcc

TomAugspurger merged commit b547454 into pandas-dev:master Mar 13, 2018

TomAugspurger added this to the 0.23.0 milestone Mar 13, 2018

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

DOC: update the pandas.DataFrame.isna and pandas.Series.isna docstring #20138

DOC: update the pandas.DataFrame.isna and pandas.Series.isna docstring #20138

Uh oh!

datadonK23 commented Mar 10, 2018

Uh oh!

villasv Mar 10, 2018

Uh oh!

villasv Mar 10, 2018

Uh oh!

pep8speaks commented Mar 10, 2018 •

edited

Loading

Uh oh!

datadonK23 commented Mar 10, 2018

Uh oh!

villasv Mar 10, 2018

Uh oh!

datadonK23 Mar 10, 2018

Uh oh!

jorisvandenbossche left a comment

Uh oh!

jorisvandenbossche Mar 12, 2018

Uh oh!

jorisvandenbossche Mar 12, 2018

Uh oh!

codecov bot commented Mar 13, 2018

Uh oh!

datadonK23 commented Mar 13, 2018

Uh oh!

TomAugspurger commented Mar 13, 2018

Uh oh!

Uh oh!

Uh oh!

DOC: update the pandas.DataFrame.isna and pandas.Series.isna docstring #20138

DOC: update the pandas.DataFrame.isna and pandas.Series.isna docstring #20138

Uh oh!

Conversation

datadonK23 commented Mar 10, 2018

Uh oh!

villasv Mar 10, 2018

Choose a reason for hiding this comment

Uh oh!

villasv Mar 10, 2018

Choose a reason for hiding this comment

Uh oh!

pep8speaks commented Mar 10, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Comment last updated on March 13, 2018 at 12:47 Hours UTC

Uh oh!

datadonK23 commented Mar 10, 2018

Uh oh!

villasv Mar 10, 2018

Choose a reason for hiding this comment

Uh oh!

datadonK23 Mar 10, 2018

Choose a reason for hiding this comment

Uh oh!

jorisvandenbossche left a comment

Choose a reason for hiding this comment

Uh oh!

jorisvandenbossche Mar 12, 2018

Choose a reason for hiding this comment

Uh oh!

jorisvandenbossche Mar 12, 2018

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Mar 13, 2018

Codecov Report

Uh oh!

datadonK23 commented Mar 13, 2018

Uh oh!

TomAugspurger commented Mar 13, 2018

Uh oh!

Uh oh!

pep8speaks commented Mar 10, 2018 •

edited

Loading