From e9640fb5b8372c37409b6669043c5bf751a454d4 Mon Sep 17 00:00:00 2001 From: Cheuk Ting Ho Date: Thu, 22 Mar 2018 21:25:02 +0000 Subject: [PATCH 1/5] DOC: update the isna, isnull, notna, notnull docstring --- pandas/core/dtypes/missing.py | 36 ++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/pandas/core/dtypes/missing.py b/pandas/core/dtypes/missing.py index 01c88c269e7e0..9878bd4919460 100644 --- a/pandas/core/dtypes/missing.py +++ b/pandas/core/dtypes/missing.py @@ -29,7 +29,12 @@ def isna(obj): - """Detect missing values (NaN in numeric arrays, None/NaN in object arrays) + """Detect missing values for an array + + This function takes an array-like object, for each element, if it is + a missing value (NaN in numeric arrays, None/NaN in object arrays) + the correisponding element of the output boolean array will be true, + otherwise false. Parameters ---------- @@ -46,6 +51,18 @@ def isna(obj): -------- pandas.notna: boolean inverse of pandas.isna pandas.isnull: alias of isna + + Examples + -------- + >>> df = pd.DataFrame([[1, pd.np.nan, 3], [4, 5, pd.np.nan]]) + >>> df + 0 1 2 + 0 1 NaN 3.0 + 1 4 5.0 NaN + >>> pd.isna(df) + 0 1 2 + 0 False True False + 1 False False True """ return _isna(obj) @@ -200,6 +217,11 @@ def notna(obj): """Replacement for numpy.isfinite / -numpy.isnan which is suitable for use on object arrays. + This function takes an array-like object, for each element, if it is *not* + a missing.value (NaN in numeric arrays, None/NaN in object arrays) the + correisponding element of the output boolean array will be true, + otherwise false. + Parameters ---------- arr : ndarray or object value @@ -215,6 +237,18 @@ def notna(obj): -------- pandas.isna : boolean inverse of pandas.notna pandas.notnull : alias of notna + + Examples + -------- + >>> df = pd.DataFrame([[1, pd.np.nan, 3], [4, 5, pd.np.nan]]) + >>> df + 0 1 2 + 0 1 NaN 3.0 + 1 4 5.0 NaN + >>> pd.notna(df) + 0 1 2 + 0 True False True + 1 True True False """ res = isna(obj) if is_scalar(res): From 8ea572ed1900e7eef02c3e069e392b02deedea0e Mon Sep 17 00:00:00 2001 From: Cheuk Ting Ho Date: Thu, 22 Mar 2018 21:57:28 +0000 Subject: [PATCH 2/5] improve docstring --- pandas/core/dtypes/missing.py | 82 ++++++++++++++++++++++------------- 1 file changed, 51 insertions(+), 31 deletions(-) diff --git a/pandas/core/dtypes/missing.py b/pandas/core/dtypes/missing.py index 9878bd4919460..d9d56dfa20408 100644 --- a/pandas/core/dtypes/missing.py +++ b/pandas/core/dtypes/missing.py @@ -29,40 +29,50 @@ def isna(obj): - """Detect missing values for an array + """Detect missing values for an array-like object. This function takes an array-like object, for each element, if it is - a missing value (NaN in numeric arrays, None/NaN in object arrays) - the correisponding element of the output boolean array will be true, - otherwise false. + a missing value (`NaN` in numeric arrays, `None`/`NaN` in object arrays) + the correisponding element of the output boolean array will be `True`, + otherwise `False`. Parameters ---------- - arr : ndarray or object value - Object to check for null-ness + arr : array-like or object + Object to check for null-ness. Returns ------- - isna : array-like of bool or bool + array-like of bool or bool Array or bool indicating whether an object is null or if an array is given which of the element is null. - See also + See Also -------- - pandas.notna: boolean inverse of pandas.isna - pandas.isnull: alias of isna + notna : boolean inverse of pandas.isna + isnull : alias of isna Examples -------- - >>> df = pd.DataFrame([[1, pd.np.nan, 3], [4, 5, pd.np.nan]]) + >>> pd.isna('dog') + False + >>> pd.isna(np.nan) + True + >>> array + array([[ 1., nan, 3.], + [ 4., 5., nan]]) + >>> pd.isna(array) + array([[False, True, False], + [False, False, True]]) + >>> df = pd.DataFrame([['ant', 'bee', 'cat'], ['dog', None, 'fly']]) >>> df - 0 1 2 - 0 1 NaN 3.0 - 1 4 5.0 NaN + 0 1 2 + 0 ant bee cat + 1 dog None fly >>> pd.isna(df) 0 1 2 - 0 False True False - 1 False False True + 0 False False False + 1 False True False """ return _isna(obj) @@ -218,37 +228,47 @@ def notna(obj): on object arrays. This function takes an array-like object, for each element, if it is *not* - a missing.value (NaN in numeric arrays, None/NaN in object arrays) the - correisponding element of the output boolean array will be true, - otherwise false. + a missing.value (`NaN` in numeric arrays, `None`/`NaN` in object arrays) + the correisponding element of the output boolean array will be `True`, + otherwise `False`. Parameters ---------- - arr : ndarray or object value + arr : array-like or object value Object to check for *not*-null-ness Returns ------- - notisna : array-like of bool or bool + array-like of bool or bool Array or bool indicating whether an object is *not* null or if an array is given which of the element is *not* null. - See also + See Also -------- - pandas.isna : boolean inverse of pandas.notna - pandas.notnull : alias of notna + isna : boolean inverse of pandas.notna + notnull : alias of notna Examples -------- - >>> df = pd.DataFrame([[1, pd.np.nan, 3], [4, 5, pd.np.nan]]) + >>> pd.notna('dog') + True + >>> pd.notna(np.nan) + False + >>> array + array([[ 1., nan, 3.], + [ 4., 5., nan]]) + >>> pd.notna(array) + array([[ True, False, True], + [ True, True, False]]) + >>> df = pd.DataFrame([['ant', 'bee', 'cat'], ['dog', None, 'fly']]) >>> df - 0 1 2 - 0 1 NaN 3.0 - 1 4 5.0 NaN + 0 1 2 + 0 ant bee cat + 1 dog None fly >>> pd.notna(df) - 0 1 2 - 0 True False True - 1 True True False + 0 1 2 + 0 True True True + 1 True False True """ res = isna(obj) if is_scalar(res): From 0c33a43080b6485ad58c11aec8d09ad3b5f6e4b3 Mon Sep 17 00:00:00 2001 From: Cheuk Ting Ho Date: Thu, 22 Mar 2018 22:03:10 +0000 Subject: [PATCH 3/5] Furthe improve docstring --- pandas/core/dtypes/missing.py | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/pandas/core/dtypes/missing.py b/pandas/core/dtypes/missing.py index d9d56dfa20408..4c5e6ba552916 100644 --- a/pandas/core/dtypes/missing.py +++ b/pandas/core/dtypes/missing.py @@ -38,7 +38,7 @@ def isna(obj): Parameters ---------- - arr : array-like or object + obj : array-like or object Object to check for null-ness. Returns @@ -51,6 +51,9 @@ def isna(obj): -------- notna : boolean inverse of pandas.isna isnull : alias of isna + Series.isna + DataFrame.isna + Index.isna Examples -------- @@ -234,7 +237,7 @@ def notna(obj): Parameters ---------- - arr : array-like or object value + obj : array-like or object value Object to check for *not*-null-ness Returns @@ -247,6 +250,9 @@ def notna(obj): -------- isna : boolean inverse of pandas.notna notnull : alias of notna + Series.notna + DataFrame.notna + Index.notna Examples -------- From 85fe9b87829f4a326fef09709ccd2286a25f2b2e Mon Sep 17 00:00:00 2001 From: Cheuk Ting Ho Date: Thu, 22 Mar 2018 22:55:34 +0000 Subject: [PATCH 4/5] Improve more on docstring --- pandas/core/dtypes/missing.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/pandas/core/dtypes/missing.py b/pandas/core/dtypes/missing.py index 4c5e6ba552916..642b6249abcec 100644 --- a/pandas/core/dtypes/missing.py +++ b/pandas/core/dtypes/missing.py @@ -227,8 +227,7 @@ def _isna_ndarraylike_old(obj): def notna(obj): - """Replacement for numpy.isfinite / -numpy.isnan which is suitable for use - on object arrays. + """Detect non-missing values for an array-like object. This function takes an array-like object, for each element, if it is *not* a missing.value (`NaN` in numeric arrays, `None`/`NaN` in object arrays) From eb38aefe206077c167213f54f36b74f1e86aa32a Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Mon, 26 Mar 2018 11:27:09 -0500 Subject: [PATCH 5/5] Updates. Reword types. Reformat for linter. PEP8. Move example order. --- pandas/core/dtypes/missing.py | 104 +++++++++++++++++++++------------- 1 file changed, 65 insertions(+), 39 deletions(-) diff --git a/pandas/core/dtypes/missing.py b/pandas/core/dtypes/missing.py index e7d51f53f74fd..2c8d229f9b0cb 100644 --- a/pandas/core/dtypes/missing.py +++ b/pandas/core/dtypes/missing.py @@ -29,47 +29,43 @@ def isna(obj): - """Detect missing values for an array-like object. + """ + Detect missing values for an array-like object. - This function takes an array-like object, for each element, if it is - a missing value (`NaN` in numeric arrays, `None`/`NaN` in object arrays, - `NaT` in datetimelike) the correisponding element of the output boolean - array will be `True`, otherwise `False`. + This function takes a scalar or array-like object and indictates + whether values are missing (``NaN`` in numeric arrays, ``None`` or ``NaN`` + in object arrays, ``NaT`` in datetimelike). Parameters ---------- - obj : array-like or object + obj : scalar or array-like Object to check for null or missing values. Returns ------- bool or array-like of bool - For scalar input, a scalar boolean is returned. - For array input, an array of boolean indicating whether the - correisponding element is missing is returned. + For scalar input, returns a scalar boolean. + For array input, returns an array of boolean indicating whether each + corresponding element is missing. See Also -------- - notna : boolean inverse of pandas.isna - isnull : alias of isna - Series.isna - DataFrame.isna - Index.isna + notna : boolean inverse of pandas.isna. + Series.isna : Detetct missing values in a Series. + DataFrame.isna : Detect missing values in a DataFrame. + Index.isna : Detect missing values in an Index. Examples -------- + Scalar arguments (including strings) result in a scalar boolean. + >>> pd.isna('dog') False >>> pd.isna(np.nan) True - >>> index = pd.DatetimeIndex(["2017-07-05","2017-07-06",None,"2017-07-08"]) - >>> index - DatetimeIndex(['2017-07-05', '2017-07-06', 'NaT', '2017-07-08'], - dtype='datetime64[ns]', freq=None) - >>> pd.isna(index) - array([False, False, True, False]) + ndarrays result in an ndarray of booleans. >>> array = np.array([[1, np.nan, 3], [4, 5, np.nan]]) >>> array @@ -79,6 +75,18 @@ def isna(obj): array([[False, True, False], [False, False, True]]) + For indexes, an ndarray of booleans is returned. + + >>> index = pd.DatetimeIndex(["2017-07-05", "2017-07-06", None, + ... "2017-07-08"]) + >>> index + DatetimeIndex(['2017-07-05', '2017-07-06', 'NaT', '2017-07-08'], + dtype='datetime64[ns]', freq=None) + >>> pd.isna(index) + array([False, False, True, False]) + + For Series and DataFrame, the same type is returned, containing booleans. + >>> df = pd.DataFrame([['ant', 'bee', 'cat'], ['dog', None, 'fly']]) >>> df 0 1 2 @@ -88,6 +96,11 @@ def isna(obj): 0 1 2 0 False False False 1 False True False + + >>> pd.isna(df[1]) + 0 False + 1 True + Name: 1, dtype: bool """ return _isna(obj) @@ -239,12 +252,12 @@ def _isna_ndarraylike_old(obj): def notna(obj): - """Detect non-missing values for an array-like object. + """ + Detect non-missing values for an array-like object. - This function takes an array-like object, for each element, if it is *not* - a missing.value (`NaN` in numeric arrays, `None`/`NaN` in object arrays, - `NaT` in datetimelike) the correisponding element of the output boolean - array will be `True`, otherwise `False`. + This function takes a scalar or array-like object and indictates + whether values are valid (not missing, which is ``NaN`` in numeric + arrays, ``None`` or ``NaN`` in object arrays, ``NaT`` in datetimelike). Parameters ---------- @@ -254,32 +267,28 @@ def notna(obj): Returns ------- bool or array-like of bool - For scalar input, a scalar boolean is returned. - For array input, an array of boolean indicating whether the - correisponding element is *not* missing is returned. + For scalar input, returns a scalar boolean. + For array input, returns an array of boolean indicating whether each + corresponding element is valid. See Also -------- - isna : boolean inverse of pandas.notna - notnull : alias of notna - Series.notna - DataFrame.notna - Index.notna + isna : boolean inverse of pandas.notna. + Series.notna : Detetct valid values in a Series. + DataFrame.notna : Detect valid values in a DataFrame. + Index.notna : Detect valid values in an Index. Examples -------- + Scalar arguments (including strings) result in a scalar boolean. + >>> pd.notna('dog') True >>> pd.notna(np.nan) False - >>> index = pd.DatetimeIndex(["2017-07-05","2017-07-06",None,"2017-07-08"]) - >>> index - DatetimeIndex(['2017-07-05', '2017-07-06', 'NaT', '2017-07-08'], - dtype='datetime64[ns]', freq=None) - >>> pd.notna(index) - array([ True, True, False, True]) + ndarrays result in an ndarray of booleans. >>> array = np.array([[1, np.nan, 3], [4, 5, np.nan]]) >>> array @@ -289,6 +298,18 @@ def notna(obj): array([[ True, False, True], [ True, True, False]]) + For indexes, an ndarray of booleans is returned. + + >>> index = pd.DatetimeIndex(["2017-07-05", "2017-07-06", None, + ... "2017-07-08"]) + >>> index + DatetimeIndex(['2017-07-05', '2017-07-06', 'NaT', '2017-07-08'], + dtype='datetime64[ns]', freq=None) + >>> pd.notna(index) + array([ True, True, False, True]) + + For Series and DataFrame, the same type is returned, containing booleans. + >>> df = pd.DataFrame([['ant', 'bee', 'cat'], ['dog', None, 'fly']]) >>> df 0 1 2 @@ -298,6 +319,11 @@ def notna(obj): 0 1 2 0 True True True 1 True False True + + >>> pd.notna(df[1]) + 0 True + 1 False + Name: 1, dtype: bool """ res = isna(obj) if is_scalar(res):