From 1cf723ac90d1a1f75639e6f183e437091059171b Mon Sep 17 00:00:00 2001 From: Arpad Fulop Date: Wed, 14 Mar 2018 15:06:02 +0100 Subject: [PATCH 1/4] DOC: update the pd.Index.asof docstring --- pandas/core/indexes/base.py | 43 ++++++++++++++++++++++++++++++++++--- 1 file changed, 40 insertions(+), 3 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index f69777af31c9c..69d488218f5a6 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -2378,12 +2378,49 @@ def identical(self, other): def asof(self, label): """ - For a sorted index, return the most recent label up to and including - the passed label. Return NaN if not found. + Return the latest index label up to and including the passed label. + + For sorted indexes, return the index label that is the latest among + the labels that are not later than the passed index label. + + Parameters + ---------- + label : object + The label up to which the method returns the latest index label. + + Returns + ------- + object : The index label that is the latest as of the passed label, + or NaN if there is no such label. See also -------- - get_loc : asof is a thin wrapper around get_loc with method='pad' + Index.get_loc : `asof` is a thin wrapper around `get_loc` + with method='pad'. + + Examples + -------- + The method returns the latest index label up to the passed label. + + >>> pd.Index([13, 18, 20]).asof(14) + 13 + + If the label is in the index, the method returns the passed label. + + >>> pd.Index([13, 18, 20]).asof(18) + 18 + + If all of the labels in the index are later than the passed label, + NaN is returned. + + >>> pd.Index([13, 18, 20]).asof(1) + nan + + If the index is not sorted, an error is raised. + + >>> pd.Index([13, 20, 18]).asof(18) + Traceback (most recent call last): + ValueError: index must be monotonic increasing or decreasing """ try: loc = self.get_loc(label, method='pad') From d75bf5b1a2d45f906d9c20f793df52b70afb7485 Mon Sep 17 00:00:00 2001 From: Arpad Fulop Date: Mon, 19 Mar 2018 12:47:14 +0100 Subject: [PATCH 2/4] clearer descriptions, restructured examples. --- pandas/core/indexes/base.py | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 69d488218f5a6..45abb609582b5 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -2378,10 +2378,11 @@ def identical(self, other): def asof(self, label): """ - Return the latest index label up to and including the passed label. + Return the label from the index, or, if not present, the previous one. - For sorted indexes, return the index label that is the latest among - the labels that are not later than the passed index label. + Assuming that the index is sorted, return the passed index label if it + is in the index, or return the previous index label if the passed one + is not in the index. Parameters ---------- @@ -2390,10 +2391,11 @@ def asof(self, label): Returns ------- - object : The index label that is the latest as of the passed label, - or NaN if there is no such label. + object : The passed label if it is in the index. The previous label + if the passed label is not in the sorted index, or NaN if there + is no such label. - See also + See Also -------- Index.get_loc : `asof` is a thin wrapper around `get_loc` with method='pad'. @@ -2402,23 +2404,25 @@ def asof(self, label): -------- The method returns the latest index label up to the passed label. - >>> pd.Index([13, 18, 20]).asof(14) + >>> idx = pd.Index([13, 18, 20]) + >>> idx.asof(14) 13 If the label is in the index, the method returns the passed label. - >>> pd.Index([13, 18, 20]).asof(18) + >>> idx.asof(18) 18 If all of the labels in the index are later than the passed label, NaN is returned. - >>> pd.Index([13, 18, 20]).asof(1) + >>> idx.asof(1) nan If the index is not sorted, an error is raised. - >>> pd.Index([13, 20, 18]).asof(18) + >>> idx_not_sorted = pd.Index([13, 20, 18]) + >>> idx_not_sorted.asof(18) Traceback (most recent call last): ValueError: index must be monotonic increasing or decreasing """ From f6e3b2ed5d4b4bee3484ce897e89a5869390aa8f Mon Sep 17 00:00:00 2001 From: Arpad Fulop Date: Wed, 25 Apr 2018 14:25:18 +0200 Subject: [PATCH 3/4] extended See Also section, dates instead of integers in Examples --- pandas/core/indexes/base.py | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 45abb609582b5..e27898d234a52 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -2397,32 +2397,37 @@ def asof(self, label): See Also -------- + Series.asof : Return the latest value in a Series up to the + passed index. + merge_asof : Perform an asof merge (similar to left join but it + matches on nearest key rather than equal key). Index.get_loc : `asof` is a thin wrapper around `get_loc` with method='pad'. Examples -------- - The method returns the latest index label up to the passed label. + `Index.asof` returns the latest index label up to the passed label. - >>> idx = pd.Index([13, 18, 20]) - >>> idx.asof(14) - 13 + >>> idx = pd.Index(['2013-12-31', '2014-01-02', '2014-01-03']) + >>> idx.asof('2014-01-01') + '2013-12-31' If the label is in the index, the method returns the passed label. - >>> idx.asof(18) - 18 + >>> idx.asof('2014-01-02') + '2014-01-02' If all of the labels in the index are later than the passed label, NaN is returned. - >>> idx.asof(1) + >>> idx.asof('1999-01-02') nan If the index is not sorted, an error is raised. - >>> idx_not_sorted = pd.Index([13, 20, 18]) - >>> idx_not_sorted.asof(18) + >>> idx_not_sorted = pd.Index(['2013-12-31', '2015-01-02', + ... '2014-01-03']) + >>> idx_not_sorted.asof('2013-12-31') Traceback (most recent call last): ValueError: index must be monotonic increasing or decreasing """ From 9bc532ab65dc89159ca478fafa9da5403fd874d2 Mon Sep 17 00:00:00 2001 From: Arpad Fulop Date: Wed, 25 Apr 2018 14:56:42 +0200 Subject: [PATCH 4/4] minor formatting --- pandas/core/indexes/base.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index e27898d234a52..1cc3c288da479 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -2391,9 +2391,10 @@ def asof(self, label): Returns ------- - object : The passed label if it is in the index. The previous label - if the passed label is not in the sorted index, or NaN if there - is no such label. + object + The passed label if it is in the index. The previous label if the + passed label is not in the sorted index or `NaN` if there is no + such label. See Also --------