From 85a618998208da318de95a423a52be11973c964d Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Sat, 2 Jan 2021 16:26:14 -0800 Subject: [PATCH 01/23] Create new system for rolling docs --- pandas/core/window/common.py | 2 +- pandas/core/window/doc.py | 37 +++++ pandas/core/window/rolling.py | 259 +++++++++++++++------------------- 3 files changed, 153 insertions(+), 145 deletions(-) create mode 100644 pandas/core/window/doc.py diff --git a/pandas/core/window/common.py b/pandas/core/window/common.py index 6ebf610587d30..c6760e96e6f1f 100644 --- a/pandas/core/window/common.py +++ b/pandas/core/window/common.py @@ -15,7 +15,7 @@ Returns ------- Series or DataFrame - Return type is determined by the caller. + Return type is the same as the original object. See Also -------- diff --git a/pandas/core/window/doc.py b/pandas/core/window/doc.py new file mode 100644 index 0000000000000..b8bd96c8bd823 --- /dev/null +++ b/pandas/core/window/doc.py @@ -0,0 +1,37 @@ +from textwrap import dedent + +from pandas.core.shared_docs import _shared_docs + +_shared_docs = dict(**_shared_docs) + +doc_template = dedent( + """ + "Calculate the {window_method} {aggregation_description}" + + Parameters + ---------- + {parameters} + + {numpy_args_kwargs} + + Returns + ------- + Series or DataFrame + Return type is the same as the original object. + + See Also + -------- + pandas.Series.{window_method} : Calling {window_method} with Series data. + pandas.DataFrame.{window_method} : Calling {window_method} with DataFrames. + pandas.Series.{agg_method} : {agg_method} for Series. + pandas.DataFrame.{agg_method} : {agg_method} for DataFrame. + {other_see_also} + """ +) + +numpy_args_kwargs = dedent( + """ + *args, **kwargs + For Numpy compatibility and has no effect on the computed value. + """ +) diff --git a/pandas/core/window/rolling.py b/pandas/core/window/rolling.py index db8a48300206b..0ce6668015376 100644 --- a/pandas/core/window/rolling.py +++ b/pandas/core/window/rolling.py @@ -58,6 +58,7 @@ flex_binary_moment, zsqrt, ) +from pandas.core.window.doc import doc_template, numpy_args_kwargs from pandas.core.window.indexers import ( BaseIndexer, FixedWindowIndexer, @@ -478,83 +479,6 @@ def aggregate(self, func, *args, **kwargs): agg = aggregate - _shared_docs["sum"] = dedent( - """ - Calculate %(name)s sum of given DataFrame or Series. - - Parameters - ---------- - *args, **kwargs - For compatibility with other %(name)s methods. Has no effect - on the computed value. - - Returns - ------- - Series or DataFrame - Same type as the input, with the same index, containing the - %(name)s sum. - - See Also - -------- - pandas.Series.sum : Reducing sum for Series. - pandas.DataFrame.sum : Reducing sum for DataFrame. - - Examples - -------- - >>> s = pd.Series([1, 2, 3, 4, 5]) - >>> s - 0 1 - 1 2 - 2 3 - 3 4 - 4 5 - dtype: int64 - - >>> s.rolling(3).sum() - 0 NaN - 1 NaN - 2 6.0 - 3 9.0 - 4 12.0 - dtype: float64 - - >>> s.expanding(3).sum() - 0 NaN - 1 NaN - 2 6.0 - 3 10.0 - 4 15.0 - dtype: float64 - - >>> s.rolling(3, center=True).sum() - 0 NaN - 1 6.0 - 2 9.0 - 3 12.0 - 4 NaN - dtype: float64 - - For DataFrame, each %(name)s sum is computed column-wise. - - >>> df = pd.DataFrame({"A": s, "B": s ** 2}) - >>> df - A B - 0 1 1 - 1 2 4 - 2 3 9 - 3 4 16 - 4 5 25 - - >>> df.rolling(3).sum() - A B - 0 NaN NaN - 1 NaN NaN - 2 6.0 14.0 - 3 9.0 29.0 - 4 12.0 50.0 - """ - ) - _shared_docs["mean"] = dedent( """ Calculate the %(name)s mean of the values. @@ -1146,8 +1070,8 @@ def aggregate(self, func, *args, **kwargs): agg = aggregate - @Substitution(name="window") - @Appender(_shared_docs["sum"]) + # @Substitution(name="window") + # @Appender(_shared_docs["sum"]) def sum(self, *args, **kwargs): nv.validate_window_func("sum", args, kwargs) window_func = window_aggregations.roll_weighted_sum @@ -1176,57 +1100,12 @@ def std(self, ddof: int = 1, *args, **kwargs): class RollingAndExpandingMixin(BaseWindow): - - _shared_docs["count"] = dedent( - r""" - The %(name)s count of any non-NaN observations inside the window. - - Returns - ------- - Series or DataFrame - Returned object type is determined by the caller of the %(name)s - calculation. - - See Also - -------- - pandas.Series.%(name)s : Calling object with Series data. - pandas.DataFrame.%(name)s : Calling object with DataFrames. - pandas.DataFrame.count : Count of the full DataFrame. - - Examples - -------- - >>> s = pd.Series([2, 3, np.nan, 10]) - >>> s.rolling(2).count() - 0 1.0 - 1 2.0 - 2 1.0 - 3 1.0 - dtype: float64 - >>> s.rolling(3).count() - 0 1.0 - 1 2.0 - 2 2.0 - 3 2.0 - dtype: float64 - >>> s.rolling(4).count() - 0 1.0 - 1 2.0 - 2 2.0 - 3 3.0 - dtype: float64 - """ - ) - def count(self): window_func = window_aggregations.roll_sum return self._apply(window_func, name="count") - _shared_docs["apply"] = dedent( - r""" - Apply an arbitrary function to each %(name)s window. - - Parameters - ---------- + _shared_docs["window_apply_parameters"] = dedent( + """ func : function Must produce a single value from an ndarray input if ``raw=True`` or a single value from a Series if ``raw=False``. Can also accept a @@ -1263,19 +1142,11 @@ def count(self): Positional arguments to be passed into func. kwargs : dict, default None Keyword arguments to be passed into func. + """ + ) - Returns - ------- - Series or DataFrame - Return type is determined by the caller. - - See Also - -------- - pandas.Series.%(name)s : Calling object with Series data. - pandas.DataFrame.%(name)s : Calling object with DataFrame data. - pandas.Series.apply : Similar method for Series. - pandas.DataFrame.apply : Similar method for DataFrame. - + _shared_docs["window_apply_notes"] = dedent( + """ Notes ----- See :ref:`window.numba_engine` for extended documentation and performance @@ -1964,8 +1835,42 @@ def aggregate(self, func, *args, **kwargs): agg = aggregate - @Substitution(name="rolling") - @Appender(_shared_docs["count"]) + _count_example_doc = dedent( + """ + Examples + -------- + >>> s = pd.Series([2, 3, np.nan, 10]) + >>> s.rolling(2).count() + 0 1.0 + 1 2.0 + 2 1.0 + 3 1.0 + dtype: float64 + >>> s.rolling(3).count() + 0 1.0 + 1 2.0 + 2 2.0 + 3 2.0 + dtype: float64 + >>> s.rolling(4).count() + 0 1.0 + 1 2.0 + 2 2.0 + 3 3.0 + dtype: float64 + """ + ) + + @doc( + doc_template, + _count_example_doc, + window_method="rolling", + aggregation_description="count of any non-NaN observations", + parameters="", + numpy_args_kwargs="", + agg_method="count", + other_see_also="", + ) def count(self): if self.min_periods is None: warnings.warn( @@ -1979,8 +1884,16 @@ def count(self): self.min_periods = 0 return super().count() - @Substitution(name="rolling") - @Appender(_shared_docs["apply"]) + @doc( + doc_template, + _shared_docs["window_apply_notes"], + window_method="rolling", + aggregation_description="sum", + parameters=_shared_docs["window_apply_parameters"], + numpy_args_kwargs="", + agg_method="apply", + other_see_also="", + ) def apply( self, func, raw=False, engine=None, engine_kwargs=None, args=None, kwargs=None ): @@ -1993,8 +1906,66 @@ def apply( kwargs=kwargs, ) - @Substitution(name="rolling") - @Appender(_shared_docs["sum"]) + _sum_example_doc = dedent( + """ + Examples + -------- + >>> s = pd.Series([1, 2, 3, 4, 5]) + >>> s + 0 1 + 1 2 + 2 3 + 3 4 + 4 5 + dtype: int64 + + >>> s.rolling(3).sum() + 0 NaN + 1 NaN + 2 6.0 + 3 9.0 + 4 12.0 + dtype: float64 + + >>> s.rolling(3, center=True).sum() + 0 NaN + 1 6.0 + 2 9.0 + 3 12.0 + 4 NaN + dtype: float64 + + For DataFrame, each sum is computed column-wise. + + >>> df = pd.DataFrame({"A": s, "B": s ** 2}) + >>> df + A B + 0 1 1 + 1 2 4 + 2 3 9 + 3 4 16 + 4 5 25 + + >>> df.rolling(3).sum() + A B + 0 NaN NaN + 1 NaN NaN + 2 6.0 14.0 + 3 9.0 29.0 + 4 12.0 50.0 + """ + ) + + @doc( + doc_template, + _sum_example_doc, + window_method="rolling", + aggregation_description="sum", + parameters="", + numpy_args_kwargs=numpy_args_kwargs, + agg_method="sum", + other_see_also="", + ) def sum(self, *args, **kwargs): nv.validate_rolling_func("sum", args, kwargs) return super().sum(*args, **kwargs) From 213e19aeb6edb543431e3c5ad78637be11930771 Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Sun, 3 Jan 2021 18:20:04 -0800 Subject: [PATCH 02/23] Add doc decorators to all rolling methods --- pandas/core/window/doc.py | 65 +++ pandas/core/window/rolling.py | 878 +++++++++++++++++++++++----------- 2 files changed, 652 insertions(+), 291 deletions(-) diff --git a/pandas/core/window/doc.py b/pandas/core/window/doc.py index b8bd96c8bd823..f26291d47fa2d 100644 --- a/pandas/core/window/doc.py +++ b/pandas/core/window/doc.py @@ -26,6 +26,14 @@ pandas.Series.{agg_method} : {agg_method} for Series. pandas.DataFrame.{agg_method} : {agg_method} for DataFrame. {other_see_also} + + Notes + ----- + {notes} + + Examples + -------- + {examples} """ ) @@ -35,3 +43,60 @@ For Numpy compatibility and has no effect on the computed value. """ ) + +kwargs_compat = dedent( + """ + **kwargs + For function compatibility and will not have an effect on the result. + """ +) + +window_apply_parameters = dedent( + """ + func : function + Must produce a single value from an ndarray input if ``raw=True`` + or a single value from a Series if ``raw=False``. Can also accept a + Numba JIT function with ``engine='numba'`` specified. + + .. versionchanged:: 1.0.0 + + raw : bool, default None + * ``False`` : passes each row or column as a Series to the + function. + * ``True`` : the passed function will receive ndarray + objects instead. + If you are just applying a NumPy reduction function this will + achieve much better performance. + engine : str, default None + * ``'cython'`` : Runs rolling apply through C-extensions from cython. + * ``'numba'`` : Runs rolling apply through JIT compiled code from numba. + Only available when ``raw`` is set to ``True``. + * ``None`` : Defaults to ``'cython'`` or globally setting ``compute.use_numba`` + + .. versionadded:: 1.0.0 + + engine_kwargs : dict, default None + * For ``'cython'`` engine, there are no accepted ``engine_kwargs`` + * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil`` + and ``parallel`` dictionary keys. The values must either be ``True`` or + ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is + ``{'nopython': True, 'nogil': False, 'parallel': False}`` and will be + applied to both the ``func`` and the ``apply`` rolling aggregation. + + .. versionadded:: 1.0.0 + + args : tuple, default None + Positional arguments to be passed into func. + kwargs : dict, default None + Keyword arguments to be passed into func. + """ +) + +window_apply_notes = dedent( + """ + Notes + ----- + See :ref:`window.numba_engine` for extended documentation and performance + considerations for the Numba engine. + """ +) diff --git a/pandas/core/window/rolling.py b/pandas/core/window/rolling.py index 0ce6668015376..b607bdd6b4615 100644 --- a/pandas/core/window/rolling.py +++ b/pandas/core/window/rolling.py @@ -52,13 +52,14 @@ from pandas.core.groupby.base import GotItemMixin, ShallowMixin from pandas.core.indexes.api import Index, MultiIndex from pandas.core.util.numba_ import NUMBA_FUNC_CACHE, maybe_use_numba -from pandas.core.window.common import ( - _doc_template, - _shared_docs, - flex_binary_moment, - zsqrt, +from pandas.core.window.common import _shared_docs, flex_binary_moment, zsqrt +from pandas.core.window.doc import ( + doc_template, + kwargs_compat, + numpy_args_kwargs, + window_apply_notes, + window_apply_parameters, ) -from pandas.core.window.doc import doc_template, numpy_args_kwargs from pandas.core.window.indexers import ( BaseIndexer, FixedWindowIndexer, @@ -1024,38 +1025,34 @@ def calc(x): return self._apply_blockwise(homogeneous_func, name) - _agg_see_also_doc = dedent( - """ - See Also - -------- - pandas.DataFrame.aggregate : Similar DataFrame method. - pandas.Series.aggregate : Similar Series method. - """ - ) - - _agg_examples_doc = dedent( - """ - Examples - -------- - >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6], "C": [7, 8, 9]}) - >>> df - A B C - 0 1 4 7 - 1 2 5 8 - 2 3 6 9 - - >>> df.rolling(2, win_type="boxcar").agg("mean") - A B C - 0 NaN NaN NaN - 1 1.5 4.5 7.5 - 2 2.5 5.5 8.5 - """ - ) - @doc( _shared_docs["aggregate"], - see_also=_agg_see_also_doc, - examples=_agg_examples_doc, + see_also=dedent( + """ + See Also + -------- + pandas.DataFrame.aggregate : Similar DataFrame method. + pandas.Series.aggregate : Similar Series method. + """ + ), + examples=dedent( + """ + Examples + -------- + >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6], "C": [7, 8, 9]}) + >>> df + A B C + 0 1 4 7 + 1 2 5 8 + 2 3 6 9 + + >>> df.rolling(2, win_type="boxcar").agg("mean") + A B C + 0 NaN NaN NaN + 1 1.5 4.5 7.5 + 2 2.5 5.5 8.5 + """ + ), klass="Series/DataFrame", axis="", ) @@ -1104,56 +1101,6 @@ def count(self): window_func = window_aggregations.roll_sum return self._apply(window_func, name="count") - _shared_docs["window_apply_parameters"] = dedent( - """ - func : function - Must produce a single value from an ndarray input if ``raw=True`` - or a single value from a Series if ``raw=False``. Can also accept a - Numba JIT function with ``engine='numba'`` specified. - - .. versionchanged:: 1.0.0 - - raw : bool, default None - * ``False`` : passes each row or column as a Series to the - function. - * ``True`` : the passed function will receive ndarray - objects instead. - If you are just applying a NumPy reduction function this will - achieve much better performance. - engine : str, default None - * ``'cython'`` : Runs rolling apply through C-extensions from cython. - * ``'numba'`` : Runs rolling apply through JIT compiled code from numba. - Only available when ``raw`` is set to ``True``. - * ``None`` : Defaults to ``'cython'`` or globally setting ``compute.use_numba`` - - .. versionadded:: 1.0.0 - - engine_kwargs : dict, default None - * For ``'cython'`` engine, there are no accepted ``engine_kwargs`` - * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil`` - and ``parallel`` dictionary keys. The values must either be ``True`` or - ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is - ``{'nopython': True, 'nogil': False, 'parallel': False}`` and will be - applied to both the ``func`` and the ``apply`` rolling aggregation. - - .. versionadded:: 1.0.0 - - args : tuple, default None - Positional arguments to be passed into func. - kwargs : dict, default None - Keyword arguments to be passed into func. - """ - ) - - _shared_docs["window_apply_notes"] = dedent( - """ - Notes - ----- - See :ref:`window.numba_engine` for extended documentation and performance - considerations for the Numba engine. - """ - ) - def apply( self, func: Callable[..., Any], @@ -1243,43 +1190,6 @@ def max(self, *args, **kwargs): window_func = window_aggregations.roll_max return self._apply(window_func, name="max", **kwargs) - _shared_docs["min"] = dedent( - """ - Calculate the %(name)s minimum. - - Parameters - ---------- - **kwargs - Under Review. - - Returns - ------- - Series or DataFrame - Returned object type is determined by the caller of the %(name)s - calculation. - - See Also - -------- - pandas.Series.%(name)s : Calling object with a Series. - pandas.DataFrame.%(name)s : Calling object with a DataFrame. - pandas.Series.min : Similar method for Series. - pandas.DataFrame.min : Similar method for DataFrame. - - Examples - -------- - Performing a rolling minimum with a window size of 3. - - >>> s = pd.Series([4, 3, 5, 2, 6]) - >>> s.rolling(3).min() - 0 NaN - 1 NaN - 2 3.0 - 3 2.0 - 4 2.0 - dtype: float64 - """ - ) - def min(self, *args, **kwargs): nv.validate_window_func("min", args, kwargs) window_func = window_aggregations.roll_min @@ -1789,44 +1699,40 @@ def _raise_monotonic_error(self): formatted = "index" raise ValueError(f"{formatted} must be monotonic") - _agg_see_also_doc = dedent( - """ - See Also - -------- - pandas.Series.rolling : Calling object with Series data. - pandas.DataFrame.rolling : Calling object with DataFrame data. - """ - ) - - _agg_examples_doc = dedent( - """ - Examples - -------- - >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6], "C": [7, 8, 9]}) - >>> df - A B C - 0 1 4 7 - 1 2 5 8 - 2 3 6 9 - - >>> df.rolling(2).sum() - A B C - 0 NaN NaN NaN - 1 3.0 9.0 15.0 - 2 5.0 11.0 17.0 - - >>> df.rolling(2).agg({"A": "sum", "B": "min"}) - A B - 0 NaN NaN - 1 3.0 4.0 - 2 5.0 5.0 - """ - ) - @doc( _shared_docs["aggregate"], - see_also=_agg_see_also_doc, - examples=_agg_examples_doc, + see_also=dedent( + """ + See Also + -------- + pandas.Series.rolling : Calling object with Series data. + pandas.DataFrame.rolling : Calling object with DataFrame data. + """ + ), + examples=dedent( + """ + Examples + -------- + >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6], "C": [7, 8, 9]}) + >>> df + A B C + 0 1 4 7 + 1 2 5 8 + 2 3 6 9 + + >>> df.rolling(2).sum() + A B C + 0 NaN NaN NaN + 1 3.0 9.0 15.0 + 2 5.0 11.0 17.0 + + >>> df.rolling(2).agg({"A": "sum", "B": "min"}) + A B + 0 NaN NaN + 1 3.0 4.0 + 2 5.0 5.0 + """ + ), klass="Series/Dataframe", axis="", ) @@ -1835,41 +1741,38 @@ def aggregate(self, func, *args, **kwargs): agg = aggregate - _count_example_doc = dedent( - """ - Examples - -------- - >>> s = pd.Series([2, 3, np.nan, 10]) - >>> s.rolling(2).count() - 0 1.0 - 1 2.0 - 2 1.0 - 3 1.0 - dtype: float64 - >>> s.rolling(3).count() - 0 1.0 - 1 2.0 - 2 2.0 - 3 2.0 - dtype: float64 - >>> s.rolling(4).count() - 0 1.0 - 1 2.0 - 2 2.0 - 3 3.0 - dtype: float64 - """ - ) - @doc( doc_template, - _count_example_doc, window_method="rolling", aggregation_description="count of any non-NaN observations", parameters="", numpy_args_kwargs="", agg_method="count", other_see_also="", + notes="", + examples=dedent( + """ + >>> s = pd.Series([2, 3, np.nan, 10]) + >>> s.rolling(2).count() + 0 1.0 + 1 2.0 + 2 1.0 + 3 1.0 + dtype: float64 + >>> s.rolling(3).count() + 0 1.0 + 1 2.0 + 2 2.0 + 3 2.0 + dtype: float64 + >>> s.rolling(4).count() + 0 1.0 + 1 2.0 + 2 2.0 + 3 3.0 + dtype: float64 + """ + ), ) def count(self): if self.min_periods is None: @@ -1886,13 +1789,14 @@ def count(self): @doc( doc_template, - _shared_docs["window_apply_notes"], window_method="rolling", - aggregation_description="sum", - parameters=_shared_docs["window_apply_parameters"], + aggregation_description="custom aggregation function", + parameters=window_apply_parameters, numpy_args_kwargs="", agg_method="apply", other_see_also="", + notes=window_apply_notes, + examples="", ) def apply( self, func, raw=False, engine=None, engine_kwargs=None, args=None, kwargs=None @@ -1906,163 +1810,555 @@ def apply( kwargs=kwargs, ) - _sum_example_doc = dedent( - """ - Examples - -------- - >>> s = pd.Series([1, 2, 3, 4, 5]) - >>> s - 0 1 - 1 2 - 2 3 - 3 4 - 4 5 - dtype: int64 - - >>> s.rolling(3).sum() - 0 NaN - 1 NaN - 2 6.0 - 3 9.0 - 4 12.0 - dtype: float64 - - >>> s.rolling(3, center=True).sum() - 0 NaN - 1 6.0 - 2 9.0 - 3 12.0 - 4 NaN - dtype: float64 - - For DataFrame, each sum is computed column-wise. - - >>> df = pd.DataFrame({"A": s, "B": s ** 2}) - >>> df - A B - 0 1 1 - 1 2 4 - 2 3 9 - 3 4 16 - 4 5 25 - - >>> df.rolling(3).sum() - A B - 0 NaN NaN - 1 NaN NaN - 2 6.0 14.0 - 3 9.0 29.0 - 4 12.0 50.0 - """ - ) - @doc( doc_template, - _sum_example_doc, window_method="rolling", aggregation_description="sum", parameters="", numpy_args_kwargs=numpy_args_kwargs, agg_method="sum", other_see_also="", + notes="", + examples=dedent( + """ + Examples + -------- + >>> s = pd.Series([1, 2, 3, 4, 5]) + >>> s + 0 1 + 1 2 + 2 3 + 3 4 + 4 5 + dtype: int64 + + >>> s.rolling(3).sum() + 0 NaN + 1 NaN + 2 6.0 + 3 9.0 + 4 12.0 + dtype: float64 + + >>> s.rolling(3, center=True).sum() + 0 NaN + 1 6.0 + 2 9.0 + 3 12.0 + 4 NaN + dtype: float64 + + For DataFrame, each sum is computed column-wise. + + >>> df = pd.DataFrame({"A": s, "B": s ** 2}) + >>> df + A B + 0 1 1 + 1 2 4 + 2 3 9 + 3 4 16 + 4 5 25 + + >>> df.rolling(3).sum() + A B + 0 NaN NaN + 1 NaN NaN + 2 6.0 14.0 + 3 9.0 29.0 + 4 12.0 50.0 + """ + ), ) def sum(self, *args, **kwargs): nv.validate_rolling_func("sum", args, kwargs) return super().sum(*args, **kwargs) - @Substitution(name="rolling", func_name="max") - @Appender(_doc_template) - @Appender(_shared_docs["max"]) + @doc( + doc_template, + window_method="rolling", + aggregation_description="max", + parameters="", + numpy_args_kwargs=numpy_args_kwargs, + agg_method="max", + other_see_also="", + notes="", + examples="", + ) def max(self, *args, **kwargs): nv.validate_rolling_func("max", args, kwargs) return super().max(*args, **kwargs) - @Substitution(name="rolling") - @Appender(_shared_docs["min"]) + @doc( + doc_template, + window_method="rolling", + aggregation_description="min", + parameters="", + numpy_args_kwargs=numpy_args_kwargs, + agg_method="min", + other_see_also="", + notes="", + examples=dedent( + """ + Performing a rolling minimum with a window size of 3. + + >>> s = pd.Series([4, 3, 5, 2, 6]) + >>> s.rolling(3).min() + 0 NaN + 1 NaN + 2 3.0 + 3 2.0 + 4 2.0 + dtype: float64 + """ + ), + ) def min(self, *args, **kwargs): nv.validate_rolling_func("min", args, kwargs) return super().min(*args, **kwargs) - @Substitution(name="rolling") - @Appender(_shared_docs["mean"]) + @doc( + doc_template, + window_method="rolling", + aggregation_description="mean", + parameters="", + numpy_args_kwargs=numpy_args_kwargs, + agg_method="mean", + other_see_also="", + notes="", + examples=dedent( + """ + The below examples will show rolling mean calculations with window sizes of + two and three, respectively. + + >>> s = pd.Series([1, 2, 3, 4]) + >>> s.rolling(2).mean() + 0 NaN + 1 1.5 + 2 2.5 + 3 3.5 + dtype: float64 + + >>> s.rolling(3).mean() + 0 NaN + 1 NaN + 2 2.0 + 3 3.0 + dtype: float64 + """ + ), + ) def mean(self, *args, **kwargs): nv.validate_rolling_func("mean", args, kwargs) return super().mean(*args, **kwargs) - @Substitution(name="rolling") - @Appender(_shared_docs["median"]) + @doc( + doc_template, + window_method="rolling", + aggregation_description="median", + parameters=kwargs_compat, + numpy_args_kwargs="", + agg_method="median", + other_see_also="", + notes="", + examples=dedent( + """ + Compute the rolling median of a series with a window size of 3. + + >>> s = pd.Series([0, 1, 2, 3, 4]) + >>> s.rolling(3).median() + 0 NaN + 1 NaN + 2 1.0 + 3 2.0 + 4 3.0 + dtype: float64 + """ + ), + ) def median(self, **kwargs): return super().median(**kwargs) - @Substitution(name="rolling", versionadded="") - @Appender(_shared_docs["std"]) + @doc( + doc_template, + window_method="rolling", + aggregation_description="standard deviation", + parameters=dedent( + """ + ddof : int, default 1 + Delta Degrees of Freedom. The divisor used in calculations + is ``N - ddof``, where ``N`` represents the number of elements. + """ + ), + numpy_args_kwargs=numpy_args_kwargs, + agg_method="std", + other_see_also="numpy.std : Equivalent method for Numpy array.", + notes=dedent( + """ + The default ``ddof`` of 1 used in :meth:`Series.std` is different + than the default ``ddof`` of 0 in :func:`numpy.std`. + + A minimum of one period is required for the rolling calculation. + """ + ), + examples=dedent( + """ + >>> s = pd.Series([5, 5, 6, 7, 5, 5, 5]) + >>> s.rolling(3).std() + 0 NaN + 1 NaN + 2 0.577350 + 3 1.000000 + 4 1.000000 + 5 1.154701 + 6 0.000000 + dtype: float64 + + >>> s.expanding(3).std() + 0 NaN + 1 NaN + 2 0.577350 + 3 0.957427 + 4 0.894427 + 5 0.836660 + 6 0.786796 + dtype: float64 + """ + ), + ) def std(self, ddof=1, *args, **kwargs): nv.validate_rolling_func("std", args, kwargs) return super().std(ddof=ddof, **kwargs) - @Substitution(name="rolling", versionadded="") - @Appender(_shared_docs["var"]) + @doc( + doc_template, + window_method="rolling", + aggregation_description="variance", + parameters=dedent( + """ + ddof : int, default 1 + Delta Degrees of Freedom. The divisor used in calculations + is ``N - ddof``, where ``N`` represents the number of elements. + """ + ), + numpy_args_kwargs=numpy_args_kwargs, + agg_method="std", + other_see_also="numpy.var : Equivalent method for Numpy array.", + notes=dedent( + """ + The default ``ddof`` of 1 used in :meth:`Series.std` is different + than the default ``ddof`` of 0 in :func:`numpy.var`. + + A minimum of one period is required for the rolling calculation. + """ + ), + examples=dedent( + """ + >>> s = pd.Series([5, 5, 6, 7, 5, 5, 5]) + >>> s.rolling(3).var() + 0 NaN + 1 NaN + 2 0.333333 + 3 1.000000 + 4 1.000000 + 5 1.333333 + 6 0.000000 + dtype: float64 + + >>> s.expanding(3).var() + 0 NaN + 1 NaN + 2 0.333333 + 3 0.916667 + 4 0.800000 + 5 0.700000 + 6 0.619048 + dtype: float64 + """ + ), + ) def var(self, ddof=1, *args, **kwargs): nv.validate_rolling_func("var", args, kwargs) return super().var(ddof=ddof, **kwargs) - @Substitution(name="rolling", func_name="skew") - @Appender(_doc_template) - @Appender(_shared_docs["skew"]) + @doc( + doc_template, + window_method="rolling", + aggregation_description="unbiased skewness", + parameters=kwargs_compat, + numpy_args_kwargs=numpy_args_kwargs, + agg_method="skew", + other_see_also="scipy.stats.skew : Third moment of a probability density.", + notes="A minimum of three periods is required for the rolling calculation.", + examples="", + ) def skew(self, **kwargs): return super().skew(**kwargs) - @Substitution(name="rolling") - @Appender(_shared_docs["sem"]) + @doc( + doc_template, + window_method="rolling", + aggregation_description="standard error of mean", + parameters=dedent( + """ + ddof : int, default 1 + Delta Degrees of Freedom. The divisor used in calculations + is ``N - ddof``, where ``N`` represents the number of elements. + """ + ), + numpy_args_kwargs="", + agg_method="sem", + other_see_also="A minimum of one period is required for the calculation.", + notes="", + examples=dedent( + """ + >>> s = pd.Series([0, 1, 2, 3]) + >>> s.rolling(2, min_periods=1).sem() + 0 NaN + 1 0.707107 + 2 0.707107 + 3 0.707107 + dtype: float64 + + >>> s.expanding().sem() + 0 NaN + 1 0.707107 + 2 0.707107 + 3 0.745356 + dtype: float64 + """ + ), + ) def sem(self, ddof=1, *args, **kwargs): return self.std(*args, **kwargs) / (self.count() - ddof).pow(0.5) - _agg_doc = dedent( + @doc( + doc_template, + window_method="rolling", + aggregation_description="Fisher's definition of kurtosis without bias", + parameters=kwargs_compat, + numpy_args_kwargs="", + agg_method="kurt", + other_see_also="scipy.stats.kurtosis : Reference SciPy method.", + notes=dedent( + """ + A minimum of 4 periods is required for the calculation. """ - Examples - -------- - - The example below will show a rolling calculation with a window size of - four matching the equivalent function call using `scipy.stats`. - - >>> arr = [1, 2, 3, 4, 999] - >>> import scipy.stats - >>> print(f"{scipy.stats.kurtosis(arr[:-1], bias=False):.6f}") - -1.200000 - >>> print(f"{scipy.stats.kurtosis(arr[1:], bias=False):.6f}") - 3.999946 - >>> s = pd.Series(arr) - >>> s.rolling(4).kurt() - 0 NaN - 1 NaN - 2 NaN - 3 -1.200000 - 4 3.999946 - dtype: float64 - """ + ), + examples=dedent( + """ + Examples + -------- + + The example below will show a rolling calculation with a window size of + four matching the equivalent function call using `scipy.stats`. + + >>> arr = [1, 2, 3, 4, 999] + >>> import scipy.stats + >>> print(f"{scipy.stats.kurtosis(arr[:-1], bias=False):.6f}") + -1.200000 + >>> print(f"{scipy.stats.kurtosis(arr[1:], bias=False):.6f}") + 3.999946 + >>> s = pd.Series(arr) + >>> s.rolling(4).kurt() + 0 NaN + 1 NaN + 2 NaN + 3 -1.200000 + 4 3.999946 + dtype: float64 + """ + ), ) - - @Appender(_agg_doc) - @Substitution(name="rolling") - @Appender(_shared_docs["kurt"]) def kurt(self, **kwargs): return super().kurt(**kwargs) - @Substitution(name="rolling") - @Appender(_shared_docs["quantile"]) + @doc( + doc_template, + window_method="rolling", + aggregation_description="quantile", + parameters=dedent( + """ + quantile : float + Quantile to compute. 0 <= quantile <= 1. + interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'} + This optional parameter specifies the interpolation method to use, + when the desired quantile lies between two data points `i` and `j`: + + * linear: `i + (j - i) * fraction`, where `fraction` is the + fractional part of the index surrounded by `i` and `j`. + * lower: `i`. + * higher: `j`. + * nearest: `i` or `j` whichever is nearest. + * midpoint: (`i` + `j`) / 2. + **kwargs + For function compatibility and will not have an effect on the result. + """ + ), + numpy_args_kwargs="", + agg_method="quantile", + other_see_also="", + notes="", + examples=dedent( + """ + >>> s = pd.Series([1, 2, 3, 4]) + >>> s.rolling(2).quantile(.4, interpolation='lower') + 0 NaN + 1 1.0 + 2 2.0 + 3 3.0 + dtype: float64 + + >>> s.rolling(2).quantile(.4, interpolation='midpoint') + 0 NaN + 1 1.5 + 2 2.5 + 3 3.5 + dtype: float64 + """ + ), + ) def quantile(self, quantile, interpolation="linear", **kwargs): return super().quantile( quantile=quantile, interpolation=interpolation, **kwargs ) - @Substitution(name="rolling", func_name="cov") - @Appender(_doc_template) - @Appender(_shared_docs["cov"]) + @doc( + doc_template, + window_method="rolling", + aggregation_description="sample covariance", + parameters=dedent( + """ + other : Series, DataFrame, or ndarray, optional + If not supplied then will default to self and produce pairwise + output. + pairwise : bool, default None + If False then only matching columns between self and other will be + used and the output will be a DataFrame. + If True then all pairwise combinations will be calculated and the + output will be a MultiIndexed DataFrame in the case of DataFrame + inputs. In the case of missing elements, only complete pairwise + observations will be used. + ddof : int, default 1 + Delta Degrees of Freedom. The divisor used in calculations + is ``N - ddof``, where ``N`` represents the number of elements. + **kwargs + For function compatibility and will not have an effect on the result. + """ + ), + numpy_args_kwargs="", + agg_method="cov", + other_see_also="", + notes="", + examples="", + ) def cov(self, other=None, pairwise=None, ddof=1, **kwargs): return super().cov(other=other, pairwise=pairwise, ddof=ddof, **kwargs) - @Substitution(name="rolling") - @Appender(_shared_docs["corr"]) + @doc( + doc_template, + window_method="rolling", + aggregation_description="covariance", + parameters=dedent( + """ + other : Series, DataFrame, or ndarray, optional + If not supplied then will default to self. + pairwise : bool, default None + Calculate pairwise combinations of columns within a + DataFrame. If `other` is not specified, defaults to `True`, + otherwise defaults to `False`. + Not relevant for :class:`~pandas.Series`. + **kwargs + For function compatibility and will not have an effect on the result. + """ + ), + numpy_args_kwargs="", + agg_method="corr", + other_see_also=dedent( + """ + cov : Similar method to calculate covariance. + numpy.corrcoef : NumPy Pearson's correlation calculation. + """ + ), + notes=dedent( + """ + This function uses Pearson's definition of correlation + (https://en.wikipedia.org/wiki/Pearson_correlation_coefficient). + + When `other` is not specified, the output will be self correlation (e.g. + all 1's), except for :class:`~pandas.DataFrame` inputs with `pairwise` + set to `True`. + + Function will return ``NaN`` for correlations of equal valued sequences; + this is the result of a 0/0 division error. + + When `pairwise` is set to `False`, only matching columns between `self` and + `other` will be used. + + When `pairwise` is set to `True`, the output will be a MultiIndex DataFrame + with the original index on the first level, and the `other` DataFrame + columns on the second level. + + In the case of missing elements, only complete pairwise observations + will be used. + """ + ), + examples=dedent( + """ + The below example shows a rolling calculation with a window size of + four matching the equivalent function call using :meth:`numpy.corrcoef`. + + >>> v1 = [3, 3, 3, 5, 8] + >>> v2 = [3, 4, 4, 4, 8] + >>> # numpy returns a 2X2 array, the correlation coefficient + >>> # is the number at entry [0][1] + >>> print(f"{np.corrcoef(v1[:-1], v2[:-1])[0][1]:.6f}") + 0.333333 + >>> print(f"{np.corrcoef(v1[1:], v2[1:])[0][1]:.6f}") + 0.916949 + >>> s1 = pd.Series(v1) + >>> s2 = pd.Series(v2) + >>> s1.rolling(4).corr(s2) + 0 NaN + 1 NaN + 2 NaN + 3 0.333333 + 4 0.916949 + dtype: float64 + + The below example shows a similar rolling calculation on a + DataFrame using the pairwise option. + + >>> matrix = np.array([[51., 35.], [49., 30.], [47., 32.],\ + [46., 31.], [50., 36.]]) + >>> print(np.corrcoef(matrix[:-1,0], matrix[:-1,1]).round(7)) + [[1. 0.6263001] + [0.6263001 1. ]] + >>> print(np.corrcoef(matrix[1:,0], matrix[1:,1]).round(7)) + [[1. 0.5553681] + [0.5553681 1. ]] + >>> df = pd.DataFrame(matrix, columns=['X','Y']) + >>> df + X Y + 0 51.0 35.0 + 1 49.0 30.0 + 2 47.0 32.0 + 3 46.0 31.0 + 4 50.0 36.0 + >>> df.rolling(4).corr(pairwise=True) + X Y + 0 X NaN NaN + Y NaN NaN + 1 X NaN NaN + Y NaN NaN + 2 X NaN NaN + Y NaN NaN + 3 X 1.000000 0.626300 + Y 0.626300 1.000000 + 4 X 1.000000 0.555368 + Y 0.555368 1.000000 + """ + ), + ) def corr(self, other=None, pairwise=None, **kwargs): return super().corr(other=other, pairwise=pairwise, **kwargs) From aab5d08c596caa49c3591f1940c25b56e0f0f4ac Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Thu, 14 Jan 2021 17:12:36 -0800 Subject: [PATCH 03/23] Remove redundant Notes section --- pandas/core/window/common.py | 16 -- pandas/core/window/doc.py | 10 +- pandas/core/window/ewm.py | 206 +++++++------- pandas/core/window/expanding.py | 461 +++++++++++++++++++++++++------- pandas/core/window/rolling.py | 87 +++--- 5 files changed, 539 insertions(+), 241 deletions(-) diff --git a/pandas/core/window/common.py b/pandas/core/window/common.py index c6760e96e6f1f..8e935b7c05300 100644 --- a/pandas/core/window/common.py +++ b/pandas/core/window/common.py @@ -8,22 +8,6 @@ from pandas.core.dtypes.generic import ABCDataFrame, ABCSeries from pandas.core.indexes.api import MultiIndex -from pandas.core.shared_docs import _shared_docs - -_shared_docs = dict(**_shared_docs) -_doc_template = """ - Returns - ------- - Series or DataFrame - Return type is the same as the original object. - - See Also - -------- - pandas.Series.%(name)s : Calling object with Series data. - pandas.DataFrame.%(name)s : Calling object with DataFrame data. - pandas.Series.%(func_name)s : Similar method for Series. - pandas.DataFrame.%(func_name)s : Similar method for DataFrame. -""" def flex_binary_moment(arg1, arg2, f, pairwise=False): diff --git a/pandas/core/window/doc.py b/pandas/core/window/doc.py index f26291d47fa2d..dccb013053e39 100644 --- a/pandas/core/window/doc.py +++ b/pandas/core/window/doc.py @@ -1,3 +1,4 @@ +"""Any shareable docstring components for rolling/expanding/ewm""" from textwrap import dedent from pandas.core.shared_docs import _shared_docs @@ -44,6 +45,13 @@ """ ) +kwargs_scipy = dedent( + """ + **kwargs + Keyword arguments to configure the ``Scipy`` weighted window type. + """ +) + kwargs_compat = dedent( """ **kwargs @@ -94,8 +102,6 @@ window_apply_notes = dedent( """ - Notes - ----- See :ref:`window.numba_engine` for extended documentation and performance considerations for the Numba engine. """ diff --git a/pandas/core/window/ewm.py b/pandas/core/window/ewm.py index 983f7220c2fb9..f1ded67786573 100644 --- a/pandas/core/window/ewm.py +++ b/pandas/core/window/ewm.py @@ -9,19 +9,15 @@ import pandas._libs.window.aggregations as window_aggregations from pandas._typing import FrameOrSeries, TimedeltaConvertibleTypes from pandas.compat.numpy import function as nv -from pandas.util._decorators import Appender, Substitution, doc +from pandas.util._decorators import doc from pandas.core.dtypes.common import is_datetime64_ns_dtype from pandas.core.dtypes.missing import isna import pandas.core.common as common from pandas.core.util.numba_ import maybe_use_numba -from pandas.core.window.common import ( - _doc_template, - _shared_docs, - flex_binary_moment, - zsqrt, -) +from pandas.core.window.common import flex_binary_moment, zsqrt +from pandas.core.window.doc import _shared_docs, doc_template, numpy_args_kwargs from pandas.core.window.indexers import ( BaseIndexer, ExponentialMovingWindowIndexer, @@ -34,16 +30,6 @@ from pandas import Series -_bias_template = """ - Parameters - ---------- - bias : bool, default False - Use a standard estimation bias correction. - *args, **kwargs - Arguments and keyword arguments to be passed into func. -""" - - def get_center_of_mass( comass: Optional[float], span: Optional[float], @@ -280,37 +266,33 @@ def _get_window_indexer(self) -> BaseIndexer: """ return ExponentialMovingWindowIndexer() - _agg_see_also_doc = dedent( - """ - See Also - -------- - pandas.DataFrame.rolling.aggregate - """ - ) - - _agg_examples_doc = dedent( - """ - Examples - -------- - >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6], "C": [7, 8, 9]}) - >>> df - A B C - 0 1 4 7 - 1 2 5 8 - 2 3 6 9 - - >>> df.ewm(alpha=0.5).mean() - A B C - 0 1.000000 4.000000 7.000000 - 1 1.666667 4.666667 7.666667 - 2 2.428571 5.428571 8.428571 - """ - ) - @doc( _shared_docs["aggregate"], - see_also=_agg_see_also_doc, - examples=_agg_examples_doc, + see_also=dedent( + """ + See Also + -------- + pandas.DataFrame.rolling.aggregate + """ + ), + examples=dedent( + """ + Examples + -------- + >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6], "C": [7, 8, 9]}) + >>> df + A B C + 0 1 4 7 + 1 2 5 8 + 2 3 6 9 + + >>> df.ewm(alpha=0.5).mean() + A B C + 0 1.000000 4.000000 7.000000 + 1 1.666667 4.666667 7.666667 + 2 2.428571 5.428571 8.428571 + """ + ), klass="Series/Dataframe", axis="", ) @@ -319,17 +301,18 @@ def aggregate(self, func, *args, **kwargs): agg = aggregate - @Substitution(name="ewm", func_name="mean") - @Appender(_doc_template) + @doc( + doc_template, + window_method="ewm", + aggregation_description="(exponential weighted moment) mean", + parameters="", + numpy_args_kwargs=numpy_args_kwargs, + agg_method="mean", + other_see_also="", + notes="", + examples="", + ) def mean(self, *args, **kwargs): - """ - Exponential weighted moving average. - - Parameters - ---------- - *args, **kwargs - Arguments and keyword arguments to be passed into func. - """ nv.validate_window_func("mean", args, kwargs) if self.times is not None: window_func = window_aggregations.ewma_time @@ -348,21 +331,44 @@ def mean(self, *args, **kwargs): ) return self._apply(window_func) - @Substitution(name="ewm", func_name="std") - @Appender(_doc_template) - @Appender(_bias_template) - def std(self, bias: bool = False, *args, **kwargs): - """ - Exponential weighted moving stddev. + @doc( + doc_template, + window_method="ewm", + aggregation_description="(exponential weighted moment) standard deviation", + parameters=dedent( + """ + bias : bool, default False + Use a standard estimation bias correction. """ + ), + numpy_args_kwargs=numpy_args_kwargs, + agg_method="std", + other_see_also="", + notes="", + examples="", + ) + def std(self, bias: bool = False, *args, **kwargs): nv.validate_window_func("std", args, kwargs) return zsqrt(self.var(bias=bias, **kwargs)) vol = std - @Substitution(name="ewm", func_name="var") - @Appender(_doc_template) - @Appender(_bias_template) + @doc( + doc_template, + window_method="ewm", + aggregation_description="(exponential weighted moment) variance", + parameters=dedent( + """ + bias : bool, default False + Use a standard estimation bias correction. + """ + ), + numpy_args_kwargs=numpy_args_kwargs, + agg_method="var", + other_see_also="", + notes="", + examples="", + ) def var(self, bias: bool = False, *args, **kwargs): """ Exponential weighted moving variance. @@ -382,20 +388,12 @@ def var_func(values, begin, end, min_periods): return self._apply(var_func) - @Substitution(name="ewm", func_name="cov") - @Appender(_doc_template) - def cov( - self, - other: Optional[Union[np.ndarray, FrameOrSeries]] = None, - pairwise: Optional[bool] = None, - bias: bool = False, - **kwargs, - ): - """ - Exponential weighted sample covariance. - - Parameters - ---------- + @doc( + doc_template, + window_method="ewm", + aggregation_description="(exponential weighted moment) sample covarance", + parameters=dedent( + """ other : Series, DataFrame, or ndarray, optional If not supplied then will default to self and produce pairwise output. @@ -408,9 +406,21 @@ def cov( observations will be used. bias : bool, default False Use a standard estimation bias correction. - **kwargs - Keyword arguments to be passed into func. """ + ), + numpy_args_kwargs=numpy_args_kwargs, + agg_method="cov", + other_see_also="", + notes="", + examples="", + ) + def cov( + self, + other: Optional[Union[np.ndarray, FrameOrSeries]] = None, + pairwise: Optional[bool] = None, + bias: bool = False, + **kwargs, + ): if other is None: other = self._selected_obj # only default unset @@ -437,19 +447,12 @@ def _get_cov(X, Y): self._selected_obj, other._selected_obj, _get_cov, pairwise=bool(pairwise) ) - @Substitution(name="ewm", func_name="corr") - @Appender(_doc_template) - def corr( - self, - other: Optional[Union[np.ndarray, FrameOrSeries]] = None, - pairwise: Optional[bool] = None, - **kwargs, - ): - """ - Exponential weighted sample correlation. - - Parameters - ---------- + @doc( + doc_template, + window_method="ewm", + aggregation_description="(exponential weighted moment) sample correlation", + parameters=dedent( + """ other : Series, DataFrame, or ndarray, optional If not supplied then will default to self and produce pairwise output. @@ -460,9 +463,20 @@ def corr( output will be a MultiIndex DataFrame in the case of DataFrame inputs. In the case of missing elements, only complete pairwise observations will be used. - **kwargs - Keyword arguments to be passed into func. """ + ), + numpy_args_kwargs=numpy_args_kwargs, + agg_method="corr", + other_see_also="", + notes="", + examples="", + ) + def corr( + self, + other: Optional[Union[np.ndarray, FrameOrSeries]] = None, + pairwise: Optional[bool] = None, + **kwargs, + ): if other is None: other = self._selected_obj # only default unset diff --git a/pandas/core/window/expanding.py b/pandas/core/window/expanding.py index 1f0c16fb5aa8f..d9d8f9f7bdf68 100644 --- a/pandas/core/window/expanding.py +++ b/pandas/core/window/expanding.py @@ -5,9 +5,16 @@ from pandas._typing import FrameOrSeries from pandas.compat.numpy import function as nv -from pandas.util._decorators import Appender, Substitution, doc - -from pandas.core.window.common import _doc_template, _shared_docs +from pandas.util._decorators import doc + +from pandas.core.window.doc import ( + _shared_docs, + doc_template, + kwargs_compat, + numpy_args_kwargs, + window_apply_notes, + window_apply_parameters, +) from pandas.core.window.indexers import BaseIndexer, ExpandingIndexer, GroupbyIndexer from pandas.core.window.rolling import BaseWindowGroupby, RollingAndExpandingMixin @@ -105,38 +112,34 @@ def _get_cov_corr_window( other = self.min_periods or -1 return max(length, other) - _agg_see_also_doc = dedent( - """ - See Also - -------- - pandas.DataFrame.aggregate : Similar DataFrame method. - pandas.Series.aggregate : Similar Series method. - """ - ) - - _agg_examples_doc = dedent( - """ - Examples - -------- - >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6], "C": [7, 8, 9]}) - >>> df - A B C - 0 1 4 7 - 1 2 5 8 - 2 3 6 9 - - >>> df.ewm(alpha=0.5).mean() - A B C - 0 1.000000 4.000000 7.000000 - 1 1.666667 4.666667 7.666667 - 2 2.428571 5.428571 8.428571 - """ - ) - @doc( _shared_docs["aggregate"], - see_also=_agg_see_also_doc, - examples=_agg_examples_doc, + see_also=dedent( + """ + See Also + -------- + pandas.DataFrame.aggregate : Similar DataFrame method. + pandas.Series.aggregate : Similar Series method. + """ + ), + examples=dedent( + """ + Examples + -------- + >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6], "C": [7, 8, 9]}) + >>> df + A B C + 0 1 4 7 + 1 2 5 8 + 2 3 6 9 + + >>> df.ewm(alpha=0.5).mean() + A B C + 0 1.000000 4.000000 7.000000 + 1 1.666667 4.666667 7.666667 + 2 2.428571 5.428571 8.428571 + """ + ), klass="Series/Dataframe", axis="", ) @@ -145,13 +148,31 @@ def aggregate(self, func, *args, **kwargs): agg = aggregate - @Substitution(name="expanding") - @Appender(_shared_docs["count"]) + @doc( + doc_template, + window_method="expanding", + aggregation_description="count of any non-NaN observations", + parameters="", + numpy_args_kwargs="", + agg_method="count", + other_see_also="", + notes="", + examples="", + ) def count(self): return super().count() - @Substitution(name="expanding") - @Appender(_shared_docs["apply"]) + @doc( + doc_template, + window_method="expanding", + aggregation_description="custom aggregation function", + parameters=window_apply_parameters, + numpy_args_kwargs="", + agg_method="apply", + other_see_also="", + notes=window_apply_notes, + examples="", + ) def apply( self, func: Callable[..., Any], @@ -170,92 +191,278 @@ def apply( kwargs=kwargs, ) - @Substitution(name="expanding") - @Appender(_shared_docs["sum"]) + @doc( + doc_template, + window_method="expanding", + aggregation_description="sum", + parameters="", + numpy_args_kwargs=numpy_args_kwargs, + agg_method="sum", + other_see_also="", + notes="", + examples="", + ) def sum(self, *args, engine=None, engine_kwargs=None, **kwargs): nv.validate_expanding_func("sum", args, kwargs) return super().sum(*args, engine=engine, engine_kwargs=engine_kwargs, **kwargs) - @Substitution(name="expanding", func_name="max") - @Appender(_doc_template) - @Appender(_shared_docs["max"]) + @doc( + doc_template, + window_method="expanding", + aggregation_description="max", + parameters="", + numpy_args_kwargs=numpy_args_kwargs, + agg_method="max", + other_see_also="", + notes="", + examples="", + ) def max(self, *args, engine=None, engine_kwargs=None, **kwargs): nv.validate_expanding_func("max", args, kwargs) return super().max(*args, engine=engine, engine_kwargs=engine_kwargs, **kwargs) - @Substitution(name="expanding") - @Appender(_shared_docs["min"]) + @doc( + doc_template, + window_method="expanding", + aggregation_description="min", + parameters="", + numpy_args_kwargs=numpy_args_kwargs, + agg_method="min", + other_see_also="", + notes="", + examples="", + ) def min(self, *args, engine=None, engine_kwargs=None, **kwargs): nv.validate_expanding_func("min", args, kwargs) return super().min(*args, engine=engine, engine_kwargs=engine_kwargs, **kwargs) - @Substitution(name="expanding") - @Appender(_shared_docs["mean"]) + @doc( + doc_template, + window_method="expanding", + aggregation_description="mean", + parameters="", + numpy_args_kwargs=numpy_args_kwargs, + agg_method="mean", + other_see_also="", + notes="", + examples="", + ) def mean(self, *args, engine=None, engine_kwargs=None, **kwargs): nv.validate_expanding_func("mean", args, kwargs) return super().mean(*args, engine=engine, engine_kwargs=engine_kwargs, **kwargs) - @Substitution(name="expanding") - @Appender(_shared_docs["median"]) + @doc( + doc_template, + window_method="expanding", + aggregation_description="median", + parameters=kwargs_compat, + numpy_args_kwargs="", + agg_method="median", + other_see_also="", + notes="", + examples="", + ) def median(self, engine=None, engine_kwargs=None, **kwargs): return super().median(engine=engine, engine_kwargs=engine_kwargs, **kwargs) - @Substitution(name="expanding", versionadded="") - @Appender(_shared_docs["std"]) + @doc( + doc_template, + window_method="expanding", + aggregation_description="standard deviation", + parameters=dedent( + """ + ddof : int, default 1 + Delta Degrees of Freedom. The divisor used in calculations + is ``N - ddof``, where ``N`` represents the number of elements. + """ + ), + numpy_args_kwargs=numpy_args_kwargs, + agg_method="std", + other_see_also="numpy.std : Equivalent method for Numpy array.", + notes=dedent( + """ + The default ``ddof`` of 1 used in :meth:`Series.std` is different + than the default ``ddof`` of 0 in :func:`numpy.std`. + + A minimum of one period is required for the rolling calculation. + """ + ), + examples=dedent( + """ + >>> s = pd.Series([5, 5, 6, 7, 5, 5, 5]) + + >>> s.expanding(3).std() + 0 NaN + 1 NaN + 2 0.577350 + 3 0.957427 + 4 0.894427 + 5 0.836660 + 6 0.786796 + dtype: float64 + """ + ), + ) def std(self, ddof: int = 1, *args, **kwargs): nv.validate_expanding_func("std", args, kwargs) return super().std(ddof=ddof, **kwargs) - @Substitution(name="expanding", versionadded="") - @Appender(_shared_docs["var"]) + @doc( + doc_template, + window_method="expanding", + aggregation_description="variance", + parameters=dedent( + """ + ddof : int, default 1 + Delta Degrees of Freedom. The divisor used in calculations + is ``N - ddof``, where ``N`` represents the number of elements. + """ + ), + numpy_args_kwargs=numpy_args_kwargs, + agg_method="std", + other_see_also="numpy.var : Equivalent method for Numpy array.", + notes=dedent( + """ + The default ``ddof`` of 1 used in :meth:`Series.std` is different + than the default ``ddof`` of 0 in :func:`numpy.var`. + + A minimum of one period is required for the rolling calculation. + """ + ), + examples=dedent( + """ + >>> s = pd.Series([5, 5, 6, 7, 5, 5, 5]) + + >>> s.expanding(3).var() + 0 NaN + 1 NaN + 2 0.333333 + 3 0.916667 + 4 0.800000 + 5 0.700000 + 6 0.619048 + dtype: float64 + """ + ), + ) def var(self, ddof: int = 1, *args, **kwargs): nv.validate_expanding_func("var", args, kwargs) return super().var(ddof=ddof, **kwargs) - @Substitution(name="expanding") - @Appender(_shared_docs["sem"]) + @doc( + doc_template, + window_method="expanding", + aggregation_description="standard error of mean", + parameters=dedent( + """ + ddof : int, default 1 + Delta Degrees of Freedom. The divisor used in calculations + is ``N - ddof``, where ``N`` represents the number of elements. + """ + ), + numpy_args_kwargs="", + agg_method="sem", + other_see_also="A minimum of one period is required for the calculation.", + notes="", + examples=dedent( + """ + >>> s = pd.Series([0, 1, 2, 3]) + + >>> s.expanding().sem() + 0 NaN + 1 0.707107 + 2 0.707107 + 3 0.745356 + dtype: float64 + """ + ), + ) def sem(self, ddof: int = 1, *args, **kwargs): return super().sem(ddof=ddof, **kwargs) - @Substitution(name="expanding", func_name="skew") - @Appender(_doc_template) - @Appender(_shared_docs["skew"]) + @doc( + doc_template, + window_method="expanding", + aggregation_description="unbiased skewness", + parameters=kwargs_compat, + numpy_args_kwargs=numpy_args_kwargs, + agg_method="skew", + other_see_also="scipy.stats.skew : Third moment of a probability density.", + notes="A minimum of three periods is required for the rolling calculation.", + examples="", + ) def skew(self, **kwargs): return super().skew(**kwargs) - _agg_doc = dedent( + @doc( + doc_template, + window_method="expanding", + aggregation_description="Fisher's definition of kurtosis without bias", + parameters=kwargs_compat, + numpy_args_kwargs="", + agg_method="kurt", + other_see_also="scipy.stats.kurtosis : Reference SciPy method.", + notes=dedent( + """ + A minimum of 4 periods is required for the calculation. """ - Examples - -------- - - The example below will show an expanding calculation with a window size of - four matching the equivalent function call using `scipy.stats`. - - >>> arr = [1, 2, 3, 4, 999] - >>> import scipy.stats - >>> print(f"{scipy.stats.kurtosis(arr[:-1], bias=False):.6f}") - -1.200000 - >>> print(f"{scipy.stats.kurtosis(arr, bias=False):.6f}") - 4.999874 - >>> s = pd.Series(arr) - >>> s.expanding(4).kurt() - 0 NaN - 1 NaN - 2 NaN - 3 -1.200000 - 4 4.999874 - dtype: float64 - """ + ), + examples=dedent( + """ + Examples + -------- + + The example below will show a rolling calculation with a window size of + four matching the equivalent function call using `scipy.stats`. + + >>> arr = [1, 2, 3, 4, 999] + >>> import scipy.stats + >>> print(f"{scipy.stats.kurtosis(arr[:-1], bias=False):.6f}") + -1.200000 + >>> print(f"{scipy.stats.kurtosis(arr, bias=False):.6f}") + 4.999874 + >>> s = pd.Series(arr) + >>> s.expanding(4).kurt() + 0 NaN + 1 NaN + 2 NaN + 3 -1.200000 + 4 4.999874 + dtype: float64 + """ + ), ) - - @Appender(_agg_doc) - @Substitution(name="expanding") - @Appender(_shared_docs["kurt"]) def kurt(self, **kwargs): return super().kurt(**kwargs) - @Substitution(name="expanding") - @Appender(_shared_docs["quantile"]) + @doc( + doc_template, + window_method="expanding", + aggregation_description="quantile", + parameters=dedent( + """ + quantile : float + Quantile to compute. 0 <= quantile <= 1. + interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'} + This optional parameter specifies the interpolation method to use, + when the desired quantile lies between two data points `i` and `j`: + + * linear: `i + (j - i) * fraction`, where `fraction` is the + fractional part of the index surrounded by `i` and `j`. + * lower: `i`. + * higher: `j`. + * nearest: `i` or `j` whichever is nearest. + * midpoint: (`i` + `j`) / 2. + **kwargs + For function compatibility and will not have an effect on the result. + """ + ), + numpy_args_kwargs="", + agg_method="quantile", + other_see_also="", + notes="", + examples="", + ) def quantile( self, quantile, @@ -268,9 +475,35 @@ def quantile( **kwargs, ) - @Substitution(name="expanding", func_name="cov") - @Appender(_doc_template) - @Appender(_shared_docs["cov"]) + @doc( + doc_template, + window_method="expanding", + aggregation_description="sample covariance", + parameters=dedent( + """ + other : Series, DataFrame, or ndarray, optional + If not supplied then will default to self and produce pairwise + output. + pairwise : bool, default None + If False then only matching columns between self and other will be + used and the output will be a DataFrame. + If True then all pairwise combinations will be calculated and the + output will be a MultiIndexed DataFrame in the case of DataFrame + inputs. In the case of missing elements, only complete pairwise + observations will be used. + ddof : int, default 1 + Delta Degrees of Freedom. The divisor used in calculations + is ``N - ddof``, where ``N`` represents the number of elements. + **kwargs + For function compatibility and will not have an effect on the result. + """ + ), + numpy_args_kwargs="", + agg_method="cov", + other_see_also="", + notes="", + examples="", + ) def cov( self, other: Optional[Union[np.ndarray, FrameOrSeries]] = None, @@ -280,8 +513,56 @@ def cov( ): return super().cov(other=other, pairwise=pairwise, ddof=ddof, **kwargs) - @Substitution(name="expanding") - @Appender(_shared_docs["corr"]) + @doc( + doc_template, + window_method="rolling", + aggregation_description="covariance", + parameters=dedent( + """ + other : Series, DataFrame, or ndarray, optional + If not supplied then will default to self. + pairwise : bool, default None + Calculate pairwise combinations of columns within a + DataFrame. If `other` is not specified, defaults to `True`, + otherwise defaults to `False`. + Not relevant for :class:`~pandas.Series`. + **kwargs + For function compatibility and will not have an effect on the result. + """ + ), + numpy_args_kwargs="", + agg_method="corr", + other_see_also=dedent( + """ + cov : Similar method to calculate covariance. + numpy.corrcoef : NumPy Pearson's correlation calculation. + """ + ), + notes=dedent( + """ + This function uses Pearson's definition of correlation + (https://en.wikipedia.org/wiki/Pearson_correlation_coefficient). + + When `other` is not specified, the output will be self correlation (e.g. + all 1's), except for :class:`~pandas.DataFrame` inputs with `pairwise` + set to `True`. + + Function will return ``NaN`` for correlations of equal valued sequences; + this is the result of a 0/0 division error. + + When `pairwise` is set to `False`, only matching columns between `self` and + `other` will be used. + + When `pairwise` is set to `True`, the output will be a MultiIndex DataFrame + with the original index on the first level, and the `other` DataFrame + columns on the second level. + + In the case of missing elements, only complete pairwise observations + will be used. + """ + ), + examples="", + ) def corr( self, other: Optional[Union[np.ndarray, FrameOrSeries]] = None, diff --git a/pandas/core/window/rolling.py b/pandas/core/window/rolling.py index a6be199071980..6f7ac02627458 100644 --- a/pandas/core/window/rolling.py +++ b/pandas/core/window/rolling.py @@ -29,7 +29,7 @@ from pandas._typing import ArrayLike, Axis, FrameOrSeries, FrameOrSeriesUnion from pandas.compat._optional import import_optional_dependency from pandas.compat.numpy import function as nv -from pandas.util._decorators import Appender, Substitution, doc +from pandas.util._decorators import doc from pandas.core.dtypes.common import ( ensure_float64, @@ -54,10 +54,12 @@ from pandas.core.groupby.base import GotItemMixin, ShallowMixin from pandas.core.indexes.api import Index, MultiIndex from pandas.core.util.numba_ import NUMBA_FUNC_CACHE, maybe_use_numba -from pandas.core.window.common import _shared_docs, flex_binary_moment, zsqrt +from pandas.core.window.common import flex_binary_moment, zsqrt from pandas.core.window.doc import ( + _shared_docs, doc_template, kwargs_compat, + kwargs_scipy, numpy_args_kwargs, window_apply_notes, window_apply_parameters, @@ -1092,30 +1094,68 @@ def aggregate(self, func, *args, **kwargs): agg = aggregate - # @Substitution(name="window") - # @Appender(_shared_docs["sum"]) + @doc( + doc_template, + window_method="rolling", + aggregation_description="weighted window sum", + parameters=kwargs_scipy, + numpy_args_kwargs="", + agg_method="sum", + other_see_also="", + notes="", + examples="", + ) def sum(self, *args, **kwargs): nv.validate_window_func("sum", args, kwargs) window_func = window_aggregations.roll_weighted_sum return self._apply(window_func, name="sum", **kwargs) - @Substitution(name="window") - @Appender(_shared_docs["mean"]) + @doc( + doc_template, + window_method="rolling", + aggregation_description="weighted window mean", + parameters=kwargs_scipy, + numpy_args_kwargs="", + agg_method="mean", + other_see_also="", + notes="", + examples="", + ) def mean(self, *args, **kwargs): nv.validate_window_func("mean", args, kwargs) window_func = window_aggregations.roll_weighted_mean return self._apply(window_func, name="mean", **kwargs) - @Substitution(name="window", versionadded="\n.. versionadded:: 1.0.0\n") - @Appender(_shared_docs["var"]) + @doc( + doc_template, + window_method="rolling", + aggregation_description="weighted window variance \n.. versionadded:: 1.0.0\n", + parameters=kwargs_scipy, + numpy_args_kwargs="", + agg_method="var", + other_see_also="", + notes="", + examples="", + ) def var(self, ddof: int = 1, *args, **kwargs): nv.validate_window_func("var", args, kwargs) window_func = partial(window_aggregations.roll_weighted_var, ddof=ddof) kwargs.pop("name", None) return self._apply(window_func, name="var", **kwargs) - @Substitution(name="window", versionadded="\n.. versionadded:: 1.0.0\n") - @Appender(_shared_docs["std"]) + @doc( + doc_template, + window_method="rolling", + aggregation_description=( + "weighted window standard deviation \n.. versionadded:: 1.0.0\n" + ), + parameters="", + numpy_args_kwargs=numpy_args_kwargs, + agg_method="std", + other_see_also="", + notes="", + examples="", + ) def std(self, ddof: int = 1, *args, **kwargs): nv.validate_window_func("std", args, kwargs) return zsqrt(self.var(ddof=ddof, name="std", **kwargs)) @@ -2148,16 +2188,6 @@ def median(self, engine=None, engine_kwargs=None, **kwargs): 5 1.154701 6 0.000000 dtype: float64 - - >>> s.expanding(3).std() - 0 NaN - 1 NaN - 2 0.577350 - 3 0.957427 - 4 0.894427 - 5 0.836660 - 6 0.786796 - dtype: float64 """ ), ) @@ -2199,16 +2229,6 @@ def std(self, ddof=1, *args, **kwargs): 5 1.333333 6 0.000000 dtype: float64 - - >>> s.expanding(3).var() - 0 NaN - 1 NaN - 2 0.333333 - 3 0.916667 - 4 0.800000 - 5 0.700000 - 6 0.619048 - dtype: float64 """ ), ) @@ -2254,13 +2274,6 @@ def skew(self, **kwargs): 2 0.707107 3 0.707107 dtype: float64 - - >>> s.expanding().sem() - 0 NaN - 1 0.707107 - 2 0.707107 - 3 0.745356 - dtype: float64 """ ), ) From d0ebf56fc67021910fd9f048d471cfe704f8c291 Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Thu, 14 Jan 2021 17:27:57 -0800 Subject: [PATCH 04/23] Add new template for numba params --- pandas/core/window/doc.py | 20 ++++++++++++++++++++ pandas/core/window/expanding.py | 9 +++++---- pandas/core/window/rolling.py | 11 ++++++----- 3 files changed, 31 insertions(+), 9 deletions(-) diff --git a/pandas/core/window/doc.py b/pandas/core/window/doc.py index dccb013053e39..d254da8d7b4b2 100644 --- a/pandas/core/window/doc.py +++ b/pandas/core/window/doc.py @@ -106,3 +106,23 @@ considerations for the Numba engine. """ ) + +window_agg_numba_parameters = dedent( + """ + engine : str, default None + * ``'cython'`` : Runs rolling max through C-extensions from cython. + * ``'numba'`` : Runs rolling max through JIT compiled code from numba. + * ``None`` : Defaults to ``'cython'`` or globally setting ``compute.use_numba`` + + .. versionadded:: 1.3.0 + + engine_kwargs : dict, default None + * For ``'cython'`` engine, there are no accepted ``engine_kwargs`` + * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil`` + and ``parallel`` dictionary keys. The values must either be ``True`` or + ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is + ``{'nopython': True, 'nogil': False, 'parallel': False}`` + + .. versionadded:: 1.3.0 + """ +) diff --git a/pandas/core/window/expanding.py b/pandas/core/window/expanding.py index d9d8f9f7bdf68..0839f0129b0a3 100644 --- a/pandas/core/window/expanding.py +++ b/pandas/core/window/expanding.py @@ -12,6 +12,7 @@ doc_template, kwargs_compat, numpy_args_kwargs, + window_agg_numba_parameters, window_apply_notes, window_apply_parameters, ) @@ -195,7 +196,7 @@ def apply( doc_template, window_method="expanding", aggregation_description="sum", - parameters="", + parameters=window_agg_numba_parameters, numpy_args_kwargs=numpy_args_kwargs, agg_method="sum", other_see_also="", @@ -210,7 +211,7 @@ def sum(self, *args, engine=None, engine_kwargs=None, **kwargs): doc_template, window_method="expanding", aggregation_description="max", - parameters="", + parameters=window_agg_numba_parameters, numpy_args_kwargs=numpy_args_kwargs, agg_method="max", other_see_also="", @@ -240,7 +241,7 @@ def min(self, *args, engine=None, engine_kwargs=None, **kwargs): doc_template, window_method="expanding", aggregation_description="mean", - parameters="", + parameters=window_agg_numba_parameters, numpy_args_kwargs=numpy_args_kwargs, agg_method="mean", other_see_also="", @@ -255,7 +256,7 @@ def mean(self, *args, engine=None, engine_kwargs=None, **kwargs): doc_template, window_method="expanding", aggregation_description="median", - parameters=kwargs_compat, + parameters=window_agg_numba_parameters, numpy_args_kwargs="", agg_method="median", other_see_also="", diff --git a/pandas/core/window/rolling.py b/pandas/core/window/rolling.py index 6f7ac02627458..fbf655e8ede73 100644 --- a/pandas/core/window/rolling.py +++ b/pandas/core/window/rolling.py @@ -61,6 +61,7 @@ kwargs_compat, kwargs_scipy, numpy_args_kwargs, + window_agg_numba_parameters, window_apply_notes, window_apply_parameters, ) @@ -1990,7 +1991,7 @@ def apply( doc_template, window_method="rolling", aggregation_description="sum", - parameters="", + parameters=window_agg_numba_parameters, numpy_args_kwargs=numpy_args_kwargs, agg_method="sum", other_see_also="", @@ -2053,7 +2054,7 @@ def sum(self, *args, engine=None, engine_kwargs=None, **kwargs): doc_template, window_method="rolling", aggregation_description="max", - parameters="", + parameters=window_agg_numba_parameters, numpy_args_kwargs=numpy_args_kwargs, agg_method="max", other_see_also="", @@ -2068,7 +2069,7 @@ def max(self, *args, engine=None, engine_kwargs=None, **kwargs): doc_template, window_method="rolling", aggregation_description="min", - parameters="", + parameters=window_agg_numba_parameters, numpy_args_kwargs=numpy_args_kwargs, agg_method="min", other_see_also="", @@ -2096,7 +2097,7 @@ def min(self, *args, engine=None, engine_kwargs=None, **kwargs): doc_template, window_method="rolling", aggregation_description="mean", - parameters="", + parameters=window_agg_numba_parameters, numpy_args_kwargs=numpy_args_kwargs, agg_method="mean", other_see_also="", @@ -2131,7 +2132,7 @@ def mean(self, *args, engine=None, engine_kwargs=None, **kwargs): doc_template, window_method="rolling", aggregation_description="median", - parameters=kwargs_compat, + parameters=window_agg_numba_parameters, numpy_args_kwargs="", agg_method="median", other_see_also="", From d6252c50cef6a4dfec4aefe008d3d34f9064c71a Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Thu, 14 Jan 2021 17:30:37 -0800 Subject: [PATCH 05/23] Remove old shared docs method --- pandas/core/window/rolling.py | 548 ---------------------------------- 1 file changed, 548 deletions(-) diff --git a/pandas/core/window/rolling.py b/pandas/core/window/rolling.py index fbf655e8ede73..1d24c64d952cc 100644 --- a/pandas/core/window/rolling.py +++ b/pandas/core/window/rolling.py @@ -508,172 +508,6 @@ def aggregate(self, func, *args, **kwargs): agg = aggregate - _shared_docs["mean"] = dedent( - """ - Calculate the %(name)s mean of the values. - - Parameters - ---------- - *args - Under Review. - **kwargs - Under Review. - - Returns - ------- - Series or DataFrame - Returned object type is determined by the caller of the %(name)s - calculation. - - See Also - -------- - pandas.Series.%(name)s : Calling object with Series data. - pandas.DataFrame.%(name)s : Calling object with DataFrames. - pandas.Series.mean : Equivalent method for Series. - pandas.DataFrame.mean : Equivalent method for DataFrame. - - Examples - -------- - The below examples will show rolling mean calculations with window sizes of - two and three, respectively. - - >>> s = pd.Series([1, 2, 3, 4]) - >>> s.rolling(2).mean() - 0 NaN - 1 1.5 - 2 2.5 - 3 3.5 - dtype: float64 - - >>> s.rolling(3).mean() - 0 NaN - 1 NaN - 2 2.0 - 3 3.0 - dtype: float64 - """ - ) - - _shared_docs["var"] = dedent( - """ - Calculate unbiased %(name)s variance. - %(versionadded)s - Normalized by N-1 by default. This can be changed using the `ddof` - argument. - - Parameters - ---------- - ddof : int, default 1 - Delta Degrees of Freedom. The divisor used in calculations - is ``N - ddof``, where ``N`` represents the number of elements. - *args, **kwargs - For NumPy compatibility. No additional arguments are used. - - Returns - ------- - Series or DataFrame - Returns the same object type as the caller of the %(name)s calculation. - - See Also - -------- - pandas.Series.%(name)s : Calling object with Series data. - pandas.DataFrame.%(name)s : Calling object with DataFrames. - pandas.Series.var : Equivalent method for Series. - pandas.DataFrame.var : Equivalent method for DataFrame. - numpy.var : Equivalent method for Numpy array. - - Notes - ----- - The default `ddof` of 1 used in :meth:`Series.var` is different than the - default `ddof` of 0 in :func:`numpy.var`. - - A minimum of 1 period is required for the rolling calculation. - - Examples - -------- - >>> s = pd.Series([5, 5, 6, 7, 5, 5, 5]) - >>> s.rolling(3).var() - 0 NaN - 1 NaN - 2 0.333333 - 3 1.000000 - 4 1.000000 - 5 1.333333 - 6 0.000000 - dtype: float64 - - >>> s.expanding(3).var() - 0 NaN - 1 NaN - 2 0.333333 - 3 0.916667 - 4 0.800000 - 5 0.700000 - 6 0.619048 - dtype: float64 - """ - ) - - _shared_docs["std"] = dedent( - """ - Calculate %(name)s standard deviation. - %(versionadded)s - Normalized by N-1 by default. This can be changed using the `ddof` - argument. - - Parameters - ---------- - ddof : int, default 1 - Delta Degrees of Freedom. The divisor used in calculations - is ``N - ddof``, where ``N`` represents the number of elements. - *args, **kwargs - For NumPy compatibility. No additional arguments are used. - - Returns - ------- - Series or DataFrame - Returns the same object type as the caller of the %(name)s calculation. - - See Also - -------- - pandas.Series.%(name)s : Calling object with Series data. - pandas.DataFrame.%(name)s : Calling object with DataFrames. - pandas.Series.std : Equivalent method for Series. - pandas.DataFrame.std : Equivalent method for DataFrame. - numpy.std : Equivalent method for Numpy array. - - Notes - ----- - The default `ddof` of 1 used in Series.std is different than the default - `ddof` of 0 in numpy.std. - - A minimum of one period is required for the rolling calculation. - - Examples - -------- - >>> s = pd.Series([5, 5, 6, 7, 5, 5, 5]) - >>> s.rolling(3).std() - 0 NaN - 1 NaN - 2 0.577350 - 3 1.000000 - 4 1.000000 - 5 1.154701 - 6 0.000000 - dtype: float64 - - >>> s.expanding(3).std() - 0 NaN - 1 NaN - 2 0.577350 - 3 0.957427 - 4 0.894427 - 5 0.836660 - 6 0.786796 - dtype: float64 - """ - ) - def dispatch(name: str, *args, **kwargs): """ @@ -1252,34 +1086,6 @@ def sum(self, *args, engine=None, engine_kwargs=None, **kwargs): window_func = window_aggregations.roll_sum return self._apply(window_func, name="sum", **kwargs) - _shared_docs["max"] = dedent( - """ - Calculate the %(name)s maximum. - - Parameters - ---------- - engine : str, default None - * ``'cython'`` : Runs rolling max through C-extensions from cython. - * ``'numba'`` : Runs rolling max through JIT compiled code from numba. - * ``None`` : Defaults to ``'cython'`` or globally setting ``compute.use_numba`` - - .. versionadded:: 1.3.0 - - engine_kwargs : dict, default None - * For ``'cython'`` engine, there are no accepted ``engine_kwargs`` - * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil`` - and ``parallel`` dictionary keys. The values must either be ``True`` or - ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is - ``{'nopython': True, 'nogil': False, 'parallel': False}`` - - .. versionadded:: 1.3.0 - - **kwargs - For compatibility with other %(name)s methods. Has no effect on - the result. - """ - ) - def max(self, *args, engine=None, engine_kwargs=None, **kwargs): nv.validate_window_func("max", args, kwargs) if maybe_use_numba(engine): @@ -1331,59 +1137,6 @@ def mean(self, *args, engine=None, engine_kwargs=None, **kwargs): window_func = window_aggregations.roll_mean return self._apply(window_func, name="mean", **kwargs) - _shared_docs["median"] = dedent( - """ - Calculate the %(name)s median. - - Parameters - ---------- - engine : str, default None - * ``'cython'`` : Runs rolling median through C-extensions from cython. - * ``'numba'`` : Runs rolling median through JIT compiled code from numba. - * ``None`` : Defaults to ``'cython'`` or globally setting ``compute.use_numba`` - - .. versionadded:: 1.3.0 - - engine_kwargs : dict, default None - * For ``'cython'`` engine, there are no accepted ``engine_kwargs`` - * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil`` - and ``parallel`` dictionary keys. The values must either be ``True`` or - ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is - ``{'nopython': True, 'nogil': False, 'parallel': False}`` - - .. versionadded:: 1.3.0 - - **kwargs - For compatibility with other %(name)s methods. Has no effect - on the computed result. - - Returns - ------- - Series or DataFrame - Returned type is the same as the original object. - - See Also - -------- - pandas.Series.%(name)s : Calling object with Series data. - pandas.DataFrame.%(name)s : Calling object with DataFrames. - pandas.Series.median : Equivalent method for Series. - pandas.DataFrame.median : Equivalent method for DataFrame. - - Examples - -------- - Compute the rolling median of a series with a window size of 3. - - >>> s = pd.Series([0, 1, 2, 3, 4]) - >>> s.rolling(3).median() - 0 NaN - 1 NaN - 2 1.0 - 3 2.0 - 4 3.0 - dtype: float64 - """ - ) - def median(self, engine=None, engine_kwargs=None, **kwargs): if maybe_use_numba(engine): if self.method == "table": @@ -1422,18 +1175,6 @@ def var(self, ddof: int = 1, *args, **kwargs): **kwargs, ) - _shared_docs[ - "skew" - ] = """ - Unbiased %(name)s skewness. - - Parameters - ---------- - **kwargs - For compatibility with other %(name)s methods. Has no effect on - the result. - """ - def skew(self, **kwargs): window_func = window_aggregations.roll_skew return self._apply( @@ -1442,92 +1183,9 @@ def skew(self, **kwargs): **kwargs, ) - _shared_docs["kurt"] = dedent( - """ - Calculate unbiased %(name)s kurtosis. - - This function uses Fisher's definition of kurtosis without bias. - - Parameters - ---------- - **kwargs - For compatibility with other %(name)s methods. Has no effect on - the result. - - Returns - ------- - Series or DataFrame - Returned object type is determined by the caller of the %(name)s - calculation. - - See Also - -------- - pandas.Series.%(name)s : Calling object with Series data. - pandas.DataFrame.%(name)s : Calling object with DataFrames. - pandas.Series.kurt : Equivalent method for Series. - pandas.DataFrame.kurt : Equivalent method for DataFrame. - scipy.stats.skew : Third moment of a probability density. - scipy.stats.kurtosis : Reference SciPy method. - - Notes - ----- - A minimum of 4 periods is required for the %(name)s calculation. - """ - ) - def sem(self, ddof: int = 1, *args, **kwargs): return self.std(*args, **kwargs) / (self.count() - ddof).pow(0.5) - _shared_docs["sem"] = dedent( - """ - Compute %(name)s standard error of mean. - - Parameters - ---------- - - ddof : int, default 1 - Delta Degrees of Freedom. The divisor used in calculations - is ``N - ddof``, where ``N`` represents the number of elements. - - *args, **kwargs - For NumPy compatibility. No additional arguments are used. - - Returns - ------- - Series or DataFrame - Returned object type is determined by the caller of the %(name)s - calculation. - - See Also - -------- - pandas.Series.%(name)s : Calling object with Series data. - pandas.DataFrame.%(name)s : Calling object with DataFrames. - pandas.Series.sem : Equivalent method for Series. - pandas.DataFrame.sem : Equivalent method for DataFrame. - - Notes - ----- - A minimum of one period is required for the rolling calculation. - - Examples - -------- - >>> s = pd.Series([0, 1, 2, 3]) - >>> s.rolling(2, min_periods=1).sem() - 0 NaN - 1 0.707107 - 2 0.707107 - 3 0.707107 - dtype: float64 - - >>> s.expanding().sem() - 0 NaN - 1 0.707107 - 2 0.707107 - 3 0.745356 - dtype: float64 - """ - ) - def kurt(self, **kwargs): window_func = window_aggregations.roll_kurt return self._apply( @@ -1536,78 +1194,6 @@ def kurt(self, **kwargs): **kwargs, ) - _shared_docs["quantile"] = dedent( - """ - Calculate the %(name)s quantile. - - Parameters - ---------- - quantile : float - Quantile to compute. 0 <= quantile <= 1. - - interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'} - This optional parameter specifies the interpolation method to use, - when the desired quantile lies between two data points `i` and `j`: - - * linear: `i + (j - i) * fraction`, where `fraction` is the - fractional part of the index surrounded by `i` and `j`. - * lower: `i`. - * higher: `j`. - * nearest: `i` or `j` whichever is nearest. - * midpoint: (`i` + `j`) / 2. - - engine : str, default None - * ``'cython'`` : Runs rolling quantile through C-extensions from cython. - * ``'numba'`` : Runs rolling quantile through JIT compiled code from numba. - * ``None`` : Defaults to ``'cython'`` or globally setting ``compute.use_numba`` - - .. versionadded:: 1.3.0 - - engine_kwargs : dict, default None - * For ``'cython'`` engine, there are no accepted ``engine_kwargs`` - * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil`` - and ``parallel`` dictionary keys. The values must either be ``True`` or - ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is - ``{'nopython': True, 'nogil': False, 'parallel': False}`` - - .. versionadded:: 1.3.0 - - **kwargs - For compatibility with other %(name)s methods. Has no effect on - the result. - - Returns - ------- - Series or DataFrame - Returned object type is determined by the caller of the %(name)s - calculation. - - See Also - -------- - pandas.Series.quantile : Computes value at the given quantile over all data - in Series. - pandas.DataFrame.quantile : Computes values at the given quantile over - requested axis in DataFrame. - - Examples - -------- - >>> s = pd.Series([1, 2, 3, 4]) - >>> s.rolling(2).quantile(.4, interpolation='lower') - 0 NaN - 1 1.0 - 2 2.0 - 3 3.0 - dtype: float64 - - >>> s.rolling(2).quantile(.4, interpolation='midpoint') - 0 NaN - 1 1.5 - 2 2.5 - 3 3.5 - dtype: float64 - """ - ) - def quantile(self, quantile: float, interpolation: str = "linear", **kwargs): if quantile == 1.0: window_func = window_aggregations.roll_max @@ -1622,30 +1208,6 @@ def quantile(self, quantile: float, interpolation: str = "linear", **kwargs): return self._apply(window_func, name="quantile", **kwargs) - _shared_docs[ - "cov" - ] = """ - Calculate the %(name)s sample covariance. - - Parameters - ---------- - other : Series, DataFrame, or ndarray, optional - If not supplied then will default to self and produce pairwise - output. - pairwise : bool, default None - If False then only matching columns between self and other will be - used and the output will be a DataFrame. - If True then all pairwise combinations will be calculated and the - output will be a MultiIndexed DataFrame in the case of DataFrame - inputs. In the case of missing elements, only complete pairwise - observations will be used. - ddof : int, default 1 - Delta Degrees of Freedom. The divisor used in calculations - is ``N - ddof``, where ``N`` represents the number of elements. - **kwargs - Keyword arguments to be passed into func. - """ - def cov(self, other=None, pairwise=None, ddof=1, **kwargs): if other is None: other = self._selected_obj @@ -1679,116 +1241,6 @@ def _get_cov(X, Y): self._selected_obj, other._selected_obj, _get_cov, pairwise=bool(pairwise) ) - _shared_docs["corr"] = dedent( - """ - Calculate %(name)s correlation. - - Parameters - ---------- - other : Series, DataFrame, or ndarray, optional - If not supplied then will default to self. - pairwise : bool, default None - Calculate pairwise combinations of columns within a - DataFrame. If `other` is not specified, defaults to `True`, - otherwise defaults to `False`. - Not relevant for :class:`~pandas.Series`. - **kwargs - Unused. - - Returns - ------- - Series or DataFrame - Returned object type is determined by the caller of the - %(name)s calculation. - - See Also - -------- - pandas.Series.%(name)s : Calling object with Series data. - pandas.DataFrame.%(name)s : Calling object with DataFrames. - pandas.Series.corr : Equivalent method for Series. - pandas.DataFrame.corr : Equivalent method for DataFrame. - cov : Similar method to calculate covariance. - numpy.corrcoef : NumPy Pearson's correlation calculation. - - Notes - ----- - This function uses Pearson's definition of correlation - (https://en.wikipedia.org/wiki/Pearson_correlation_coefficient). - - When `other` is not specified, the output will be self correlation (e.g. - all 1's), except for :class:`~pandas.DataFrame` inputs with `pairwise` - set to `True`. - - Function will return ``NaN`` for correlations of equal valued sequences; - this is the result of a 0/0 division error. - - When `pairwise` is set to `False`, only matching columns between `self` and - `other` will be used. - - When `pairwise` is set to `True`, the output will be a MultiIndex DataFrame - with the original index on the first level, and the `other` DataFrame - columns on the second level. - - In the case of missing elements, only complete pairwise observations - will be used. - - Examples - -------- - The below example shows a rolling calculation with a window size of - four matching the equivalent function call using :meth:`numpy.corrcoef`. - - >>> v1 = [3, 3, 3, 5, 8] - >>> v2 = [3, 4, 4, 4, 8] - >>> # numpy returns a 2X2 array, the correlation coefficient - >>> # is the number at entry [0][1] - >>> print(f"{np.corrcoef(v1[:-1], v2[:-1])[0][1]:.6f}") - 0.333333 - >>> print(f"{np.corrcoef(v1[1:], v2[1:])[0][1]:.6f}") - 0.916949 - >>> s1 = pd.Series(v1) - >>> s2 = pd.Series(v2) - >>> s1.rolling(4).corr(s2) - 0 NaN - 1 NaN - 2 NaN - 3 0.333333 - 4 0.916949 - dtype: float64 - - The below example shows a similar rolling calculation on a - DataFrame using the pairwise option. - - >>> matrix = np.array([[51., 35.], [49., 30.], [47., 32.],\ - [46., 31.], [50., 36.]]) - >>> print(np.corrcoef(matrix[:-1,0], matrix[:-1,1]).round(7)) - [[1. 0.6263001] - [0.6263001 1. ]] - >>> print(np.corrcoef(matrix[1:,0], matrix[1:,1]).round(7)) - [[1. 0.5553681] - [0.5553681 1. ]] - >>> df = pd.DataFrame(matrix, columns=['X','Y']) - >>> df - X Y - 0 51.0 35.0 - 1 49.0 30.0 - 2 47.0 32.0 - 3 46.0 31.0 - 4 50.0 36.0 - >>> df.rolling(4).corr(pairwise=True) - X Y - 0 X NaN NaN - Y NaN NaN - 1 X NaN NaN - Y NaN NaN - 2 X NaN NaN - Y NaN NaN - 3 X 1.000000 0.626300 - Y 0.626300 1.000000 - 4 X 1.000000 0.555368 - Y 0.555368 1.000000 - """ - ) - def corr(self, other=None, pairwise=None, **kwargs): if other is None: other = self._selected_obj From 593329e1a3fa60a59ba0a96200495c61817e1f6d Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Sat, 16 Jan 2021 15:59:43 -0800 Subject: [PATCH 06/23] Fix small typos in docstrings --- pandas/core/window/doc.py | 8 ++++---- pandas/core/window/ewm.py | 3 --- pandas/core/window/expanding.py | 28 ++++++++++++++-------------- pandas/core/window/rolling.py | 28 ++++++++++++++-------------- 4 files changed, 32 insertions(+), 35 deletions(-) diff --git a/pandas/core/window/doc.py b/pandas/core/window/doc.py index d254da8d7b4b2..1faa5ccdf72f5 100644 --- a/pandas/core/window/doc.py +++ b/pandas/core/window/doc.py @@ -7,7 +7,7 @@ doc_template = dedent( """ - "Calculate the {window_method} {aggregation_description}" + Calculate the {window_method} {aggregation_description} Parameters ---------- @@ -100,7 +100,7 @@ """ ) -window_apply_notes = dedent( +numba_notes = dedent( """ See :ref:`window.numba_engine` for extended documentation and performance considerations for the Numba engine. @@ -110,8 +110,8 @@ window_agg_numba_parameters = dedent( """ engine : str, default None - * ``'cython'`` : Runs rolling max through C-extensions from cython. - * ``'numba'`` : Runs rolling max through JIT compiled code from numba. + * ``'cython'`` : Runs the operation through C-extensions from cython. + * ``'numba'`` : Runs the operation through JIT compiled code from numba. * ``None`` : Defaults to ``'cython'`` or globally setting ``compute.use_numba`` .. versionadded:: 1.3.0 diff --git a/pandas/core/window/ewm.py b/pandas/core/window/ewm.py index f1ded67786573..ac7f9d734a4bc 100644 --- a/pandas/core/window/ewm.py +++ b/pandas/core/window/ewm.py @@ -370,9 +370,6 @@ def std(self, bias: bool = False, *args, **kwargs): examples="", ) def var(self, bias: bool = False, *args, **kwargs): - """ - Exponential weighted moving variance. - """ nv.validate_window_func("var", args, kwargs) window_func = window_aggregations.ewmcov window_func = partial( diff --git a/pandas/core/window/expanding.py b/pandas/core/window/expanding.py index 0839f0129b0a3..3f0e66b445e2a 100644 --- a/pandas/core/window/expanding.py +++ b/pandas/core/window/expanding.py @@ -11,9 +11,9 @@ _shared_docs, doc_template, kwargs_compat, + numba_notes, numpy_args_kwargs, window_agg_numba_parameters, - window_apply_notes, window_apply_parameters, ) from pandas.core.window.indexers import BaseIndexer, ExpandingIndexer, GroupbyIndexer @@ -171,7 +171,7 @@ def count(self): numpy_args_kwargs="", agg_method="apply", other_see_also="", - notes=window_apply_notes, + notes=numba_notes, examples="", ) def apply( @@ -200,7 +200,7 @@ def apply( numpy_args_kwargs=numpy_args_kwargs, agg_method="sum", other_see_also="", - notes="", + notes=numba_notes, examples="", ) def sum(self, *args, engine=None, engine_kwargs=None, **kwargs): @@ -210,12 +210,12 @@ def sum(self, *args, engine=None, engine_kwargs=None, **kwargs): @doc( doc_template, window_method="expanding", - aggregation_description="max", + aggregation_description="maximum", parameters=window_agg_numba_parameters, numpy_args_kwargs=numpy_args_kwargs, agg_method="max", other_see_also="", - notes="", + notes=numba_notes, examples="", ) def max(self, *args, engine=None, engine_kwargs=None, **kwargs): @@ -225,12 +225,12 @@ def max(self, *args, engine=None, engine_kwargs=None, **kwargs): @doc( doc_template, window_method="expanding", - aggregation_description="min", + aggregation_description="minimum", parameters="", numpy_args_kwargs=numpy_args_kwargs, agg_method="min", other_see_also="", - notes="", + notes=numba_notes, examples="", ) def min(self, *args, engine=None, engine_kwargs=None, **kwargs): @@ -245,7 +245,7 @@ def min(self, *args, engine=None, engine_kwargs=None, **kwargs): numpy_args_kwargs=numpy_args_kwargs, agg_method="mean", other_see_also="", - notes="", + notes=numba_notes, examples="", ) def mean(self, *args, engine=None, engine_kwargs=None, **kwargs): @@ -260,7 +260,7 @@ def mean(self, *args, engine=None, engine_kwargs=None, **kwargs): numpy_args_kwargs="", agg_method="median", other_see_also="", - notes="", + notes=numba_notes, examples="", ) def median(self, engine=None, engine_kwargs=None, **kwargs): @@ -320,11 +320,11 @@ def std(self, ddof: int = 1, *args, **kwargs): """ ), numpy_args_kwargs=numpy_args_kwargs, - agg_method="std", + agg_method="var", other_see_also="numpy.var : Equivalent method for Numpy array.", notes=dedent( """ - The default ``ddof`` of 1 used in :meth:`Series.std` is different + The default ``ddof`` of 1 used in :meth:`Series.var` is different than the default ``ddof`` of 0 in :func:`numpy.var`. A minimum of one period is required for the rolling calculation. @@ -363,8 +363,8 @@ def var(self, ddof: int = 1, *args, **kwargs): ), numpy_args_kwargs="", agg_method="sem", - other_see_also="A minimum of one period is required for the calculation.", - notes="", + other_see_also="", + notes="A minimum of one period is required for the calculation.", examples=dedent( """ >>> s = pd.Series([0, 1, 2, 3]) @@ -405,7 +405,7 @@ def skew(self, **kwargs): other_see_also="scipy.stats.kurtosis : Reference SciPy method.", notes=dedent( """ - A minimum of 4 periods is required for the calculation. + A minimum of four periods is required for the calculation. """ ), examples=dedent( diff --git a/pandas/core/window/rolling.py b/pandas/core/window/rolling.py index d388c62e2f650..fa502cbd2545f 100644 --- a/pandas/core/window/rolling.py +++ b/pandas/core/window/rolling.py @@ -60,9 +60,9 @@ doc_template, kwargs_compat, kwargs_scipy, + numba_notes, numpy_args_kwargs, window_agg_numba_parameters, - window_apply_notes, window_apply_parameters, ) from pandas.core.window.indexers import ( @@ -1430,7 +1430,7 @@ def count(self): numpy_args_kwargs="", agg_method="apply", other_see_also="", - notes=window_apply_notes, + notes=numba_notes, examples="", ) def apply( @@ -1453,7 +1453,7 @@ def apply( numpy_args_kwargs=numpy_args_kwargs, agg_method="sum", other_see_also="", - notes="", + notes=numba_notes, examples=dedent( """ Examples @@ -1511,12 +1511,12 @@ def sum(self, *args, engine=None, engine_kwargs=None, **kwargs): @doc( doc_template, window_method="rolling", - aggregation_description="max", + aggregation_description="maximum", parameters=window_agg_numba_parameters, numpy_args_kwargs=numpy_args_kwargs, agg_method="max", other_see_also="", - notes="", + notes=numba_notes, examples="", ) def max(self, *args, engine=None, engine_kwargs=None, **kwargs): @@ -1526,12 +1526,12 @@ def max(self, *args, engine=None, engine_kwargs=None, **kwargs): @doc( doc_template, window_method="rolling", - aggregation_description="min", + aggregation_description="minimum", parameters=window_agg_numba_parameters, numpy_args_kwargs=numpy_args_kwargs, agg_method="min", other_see_also="", - notes="", + notes=numba_notes, examples=dedent( """ Performing a rolling minimum with a window size of 3. @@ -1559,7 +1559,7 @@ def min(self, *args, engine=None, engine_kwargs=None, **kwargs): numpy_args_kwargs=numpy_args_kwargs, agg_method="mean", other_see_also="", - notes="", + notes=numba_notes, examples=dedent( """ The below examples will show rolling mean calculations with window sizes of @@ -1594,7 +1594,7 @@ def mean(self, *args, engine=None, engine_kwargs=None, **kwargs): numpy_args_kwargs="", agg_method="median", other_see_also="", - notes="", + notes=numba_notes, examples=dedent( """ Compute the rolling median of a series with a window size of 3. @@ -1666,11 +1666,11 @@ def std(self, ddof=1, *args, **kwargs): """ ), numpy_args_kwargs=numpy_args_kwargs, - agg_method="std", + agg_method="var", other_see_also="numpy.var : Equivalent method for Numpy array.", notes=dedent( """ - The default ``ddof`` of 1 used in :meth:`Series.std` is different + The default ``ddof`` of 1 used in :meth:`Series.var` is different than the default ``ddof`` of 0 in :func:`numpy.var`. A minimum of one period is required for the rolling calculation. @@ -1722,8 +1722,8 @@ def skew(self, **kwargs): ), numpy_args_kwargs="", agg_method="sem", - other_see_also="A minimum of one period is required for the calculation.", - notes="", + other_see_also="", + notes="A minimum of one period is required for the calculation.", examples=dedent( """ >>> s = pd.Series([0, 1, 2, 3]) @@ -1749,7 +1749,7 @@ def sem(self, ddof=1, *args, **kwargs): other_see_also="scipy.stats.kurtosis : Reference SciPy method.", notes=dedent( """ - A minimum of 4 periods is required for the calculation. + A minimum of four periods is required for the calculation. """ ), examples=dedent( From 1a2c07942c104d417ab9e5e188ef259362342d0c Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Sat, 16 Jan 2021 17:07:48 -0800 Subject: [PATCH 07/23] Move versionadded to notes --- pandas/core/window/rolling.py | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/pandas/core/window/rolling.py b/pandas/core/window/rolling.py index b49ef0f6bda46..e7102e0bb76b4 100644 --- a/pandas/core/window/rolling.py +++ b/pandas/core/window/rolling.py @@ -970,12 +970,12 @@ def mean(self, *args, **kwargs): @doc( doc_template, window_method="rolling", - aggregation_description="weighted window variance \n.. versionadded:: 1.0.0\n", + aggregation_description="weighted window variance", parameters=kwargs_scipy, numpy_args_kwargs="", agg_method="var", other_see_also="", - notes="", + notes=".. versionadded:: 1.0.0", examples="", ) def var(self, ddof: int = 1, *args, **kwargs): @@ -987,14 +987,12 @@ def var(self, ddof: int = 1, *args, **kwargs): @doc( doc_template, window_method="rolling", - aggregation_description=( - "weighted window standard deviation \n.. versionadded:: 1.0.0\n" - ), + aggregation_description="weighted window standard deviation", parameters="", numpy_args_kwargs=numpy_args_kwargs, agg_method="std", other_see_also="", - notes="", + notes=".. versionadded:: 1.0.0", examples="", ) def std(self, ddof: int = 1, *args, **kwargs): From d07c10079f26ec94e743fb4b8eaa2a3a0ef22409 Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Sat, 16 Jan 2021 18:03:12 -0800 Subject: [PATCH 08/23] try fixing count? --- pandas/core/window/expanding.py | 2 +- pandas/core/window/rolling.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/window/expanding.py b/pandas/core/window/expanding.py index 3f0e66b445e2a..f517ce51b9eb4 100644 --- a/pandas/core/window/expanding.py +++ b/pandas/core/window/expanding.py @@ -152,7 +152,7 @@ def aggregate(self, func, *args, **kwargs): @doc( doc_template, window_method="expanding", - aggregation_description="count of any non-NaN observations", + aggregation_description="count of non NaN observations", parameters="", numpy_args_kwargs="", agg_method="count", diff --git a/pandas/core/window/rolling.py b/pandas/core/window/rolling.py index e7102e0bb76b4..0d7b180f8c684 100644 --- a/pandas/core/window/rolling.py +++ b/pandas/core/window/rolling.py @@ -1377,7 +1377,7 @@ def aggregate(self, func, *args, **kwargs): @doc( doc_template, window_method="rolling", - aggregation_description="count of any non-NaN observations", + aggregation_description="count of non NaN observations", parameters="", numpy_args_kwargs="", agg_method="count", From e40916edcba5d3db09367ecc815177da88ab23f4 Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Sat, 16 Jan 2021 20:06:52 -0800 Subject: [PATCH 09/23] Capitalize summary name --- pandas/core/window/doc.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/window/doc.py b/pandas/core/window/doc.py index 1faa5ccdf72f5..18e55143e475b 100644 --- a/pandas/core/window/doc.py +++ b/pandas/core/window/doc.py @@ -24,8 +24,8 @@ -------- pandas.Series.{window_method} : Calling {window_method} with Series data. pandas.DataFrame.{window_method} : Calling {window_method} with DataFrames. - pandas.Series.{agg_method} : {agg_method} for Series. - pandas.DataFrame.{agg_method} : {agg_method} for DataFrame. + pandas.Series.{agg_method} : Aggregating {agg_method} for Series. + pandas.DataFrame.{agg_method} : Aggregating {agg_method} for DataFrame. {other_see_also} Notes From ec33dbc4b3462239f6bec70d29489eb4b948d31b Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Sun, 17 Jan 2021 16:31:55 -0800 Subject: [PATCH 10/23] Fix docstring validation errors --- pandas/core/window/doc.py | 12 +++--------- pandas/core/window/expanding.py | 11 ++++------- pandas/core/window/rolling.py | 15 +++++---------- 3 files changed, 12 insertions(+), 26 deletions(-) diff --git a/pandas/core/window/doc.py b/pandas/core/window/doc.py index 18e55143e475b..3e87d73fbc0f4 100644 --- a/pandas/core/window/doc.py +++ b/pandas/core/window/doc.py @@ -7,14 +7,11 @@ doc_template = dedent( """ - Calculate the {window_method} {aggregation_description} + Calculate the {window_method} {aggregation_description}. Parameters ---------- - {parameters} - - {numpy_args_kwargs} - + {parameters}{numpy_args_kwargs} Returns ------- Series or DataFrame @@ -27,15 +24,12 @@ pandas.Series.{agg_method} : Aggregating {agg_method} for Series. pandas.DataFrame.{agg_method} : Aggregating {agg_method} for DataFrame. {other_see_also} - Notes ----- {notes} - Examples -------- - {examples} - """ + {examples}""" ) numpy_args_kwargs = dedent( diff --git a/pandas/core/window/expanding.py b/pandas/core/window/expanding.py index f517ce51b9eb4..74c1a9336cae5 100644 --- a/pandas/core/window/expanding.py +++ b/pandas/core/window/expanding.py @@ -279,7 +279,7 @@ def median(self, engine=None, engine_kwargs=None, **kwargs): ), numpy_args_kwargs=numpy_args_kwargs, agg_method="std", - other_see_also="numpy.std : Equivalent method for Numpy array.", + other_see_also="numpy.std : Equivalent method for Numpy array.\n", notes=dedent( """ The default ``ddof`` of 1 used in :meth:`Series.std` is different @@ -321,7 +321,7 @@ def std(self, ddof: int = 1, *args, **kwargs): ), numpy_args_kwargs=numpy_args_kwargs, agg_method="var", - other_see_also="numpy.var : Equivalent method for Numpy array.", + other_see_also="numpy.var : Equivalent method for Numpy array.\n", notes=dedent( """ The default ``ddof`` of 1 used in :meth:`Series.var` is different @@ -388,7 +388,7 @@ def sem(self, ddof: int = 1, *args, **kwargs): parameters=kwargs_compat, numpy_args_kwargs=numpy_args_kwargs, agg_method="skew", - other_see_also="scipy.stats.skew : Third moment of a probability density.", + other_see_also="scipy.stats.skew : Third moment of a probability density.\n", notes="A minimum of three periods is required for the rolling calculation.", examples="", ) @@ -402,7 +402,7 @@ def skew(self, **kwargs): parameters=kwargs_compat, numpy_args_kwargs="", agg_method="kurt", - other_see_also="scipy.stats.kurtosis : Reference SciPy method.", + other_see_also="scipy.stats.kurtosis : Reference SciPy method.\n", notes=dedent( """ A minimum of four periods is required for the calculation. @@ -410,9 +410,6 @@ def skew(self, **kwargs): ), examples=dedent( """ - Examples - -------- - The example below will show a rolling calculation with a window size of four matching the equivalent function call using `scipy.stats`. diff --git a/pandas/core/window/rolling.py b/pandas/core/window/rolling.py index 0d7b180f8c684..caa0c3a3246e6 100644 --- a/pandas/core/window/rolling.py +++ b/pandas/core/window/rolling.py @@ -1454,8 +1454,6 @@ def apply( notes=numba_notes, examples=dedent( """ - Examples - -------- >>> s = pd.Series([1, 2, 3, 4, 5]) >>> s 0 1 @@ -1624,7 +1622,7 @@ def median(self, engine=None, engine_kwargs=None, **kwargs): ), numpy_args_kwargs=numpy_args_kwargs, agg_method="std", - other_see_also="numpy.std : Equivalent method for Numpy array.", + other_see_also="numpy.std : Equivalent method for Numpy array.\n", notes=dedent( """ The default ``ddof`` of 1 used in :meth:`Series.std` is different @@ -1665,7 +1663,7 @@ def std(self, ddof=1, *args, **kwargs): ), numpy_args_kwargs=numpy_args_kwargs, agg_method="var", - other_see_also="numpy.var : Equivalent method for Numpy array.", + other_see_also="numpy.var : Equivalent method for Numpy array.\n", notes=dedent( """ The default ``ddof`` of 1 used in :meth:`Series.var` is different @@ -1700,7 +1698,7 @@ def var(self, ddof=1, *args, **kwargs): parameters=kwargs_compat, numpy_args_kwargs=numpy_args_kwargs, agg_method="skew", - other_see_also="scipy.stats.skew : Third moment of a probability density.", + other_see_also="scipy.stats.skew : Third moment of a probability density.\n", notes="A minimum of three periods is required for the rolling calculation.", examples="", ) @@ -1721,7 +1719,7 @@ def skew(self, **kwargs): numpy_args_kwargs="", agg_method="sem", other_see_also="", - notes="A minimum of one period is required for the calculation.", + notes="A minimum of one period is required for the calculation.\n", examples=dedent( """ >>> s = pd.Series([0, 1, 2, 3]) @@ -1744,7 +1742,7 @@ def sem(self, ddof=1, *args, **kwargs): parameters=kwargs_compat, numpy_args_kwargs="", agg_method="kurt", - other_see_also="scipy.stats.kurtosis : Reference SciPy method.", + other_see_also="scipy.stats.kurtosis : Reference SciPy method.\n", notes=dedent( """ A minimum of four periods is required for the calculation. @@ -1752,9 +1750,6 @@ def sem(self, ddof=1, *args, **kwargs): ), examples=dedent( """ - Examples - -------- - The example below will show a rolling calculation with a window size of four matching the equivalent function call using `scipy.stats`. From f1716db4ba12b9aec4347ae15728e6eebedb12eb Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Sun, 17 Jan 2021 17:13:22 -0800 Subject: [PATCH 11/23] Fix docbuild warnings --- pandas/core/window/expanding.py | 2 +- pandas/core/window/rolling.py | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/pandas/core/window/expanding.py b/pandas/core/window/expanding.py index 74c1a9336cae5..fde83ad5b9989 100644 --- a/pandas/core/window/expanding.py +++ b/pandas/core/window/expanding.py @@ -153,7 +153,7 @@ def aggregate(self, func, *args, **kwargs): doc_template, window_method="expanding", aggregation_description="count of non NaN observations", - parameters="", + parameters="No parameters", numpy_args_kwargs="", agg_method="count", other_see_also="", diff --git a/pandas/core/window/rolling.py b/pandas/core/window/rolling.py index caa0c3a3246e6..543a15c4d0382 100644 --- a/pandas/core/window/rolling.py +++ b/pandas/core/window/rolling.py @@ -975,7 +975,7 @@ def mean(self, *args, **kwargs): numpy_args_kwargs="", agg_method="var", other_see_also="", - notes=".. versionadded:: 1.0.0", + notes=".. versionadded:: 1.0.0 \n", examples="", ) def var(self, ddof: int = 1, *args, **kwargs): @@ -992,7 +992,7 @@ def var(self, ddof: int = 1, *args, **kwargs): numpy_args_kwargs=numpy_args_kwargs, agg_method="std", other_see_also="", - notes=".. versionadded:: 1.0.0", + notes=".. versionadded:: 1.0.0 \n", examples="", ) def std(self, ddof: int = 1, *args, **kwargs): @@ -1378,7 +1378,7 @@ def aggregate(self, func, *args, **kwargs): doc_template, window_method="rolling", aggregation_description="count of non NaN observations", - parameters="", + parameters="No parameters", numpy_args_kwargs="", agg_method="count", other_see_also="", From d1d1ae3c6ce7abfb218858a370214fc889c63b1d Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Sun, 17 Jan 2021 20:00:25 -0800 Subject: [PATCH 12/23] More docstring validation fixes --- pandas/core/window/doc.py | 26 ++++++++++++++++++++++++++ pandas/core/window/expanding.py | 15 ++++++++------- pandas/core/window/rolling.py | 19 ++++++++++--------- 3 files changed, 44 insertions(+), 16 deletions(-) diff --git a/pandas/core/window/doc.py b/pandas/core/window/doc.py index 3e87d73fbc0f4..6bb7bd32482cb 100644 --- a/pandas/core/window/doc.py +++ b/pandas/core/window/doc.py @@ -120,3 +120,29 @@ .. versionadded:: 1.3.0 """ ) + +window_agg_numba_args_kwargs_parameters = dedent( + """ + *args + For function compatibility and will not have an effect on the result. + + engine : str, default None + * ``'cython'`` : Runs the operation through C-extensions from cython. + * ``'numba'`` : Runs the operation through JIT compiled code from numba. + * ``None`` : Defaults to ``'cython'`` or globally setting ``compute.use_numba`` + + .. versionadded:: 1.3.0 + + engine_kwargs : dict, default None + * For ``'cython'`` engine, there are no accepted ``engine_kwargs`` + * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil`` + and ``parallel`` dictionary keys. The values must either be ``True`` or + ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is + ``{'nopython': True, 'nogil': False, 'parallel': False}`` + + .. versionadded:: 1.3.0 + + **kwargs + For function compatibility and will not have an effect on the result. + """ +) diff --git a/pandas/core/window/expanding.py b/pandas/core/window/expanding.py index fde83ad5b9989..24f76077885e7 100644 --- a/pandas/core/window/expanding.py +++ b/pandas/core/window/expanding.py @@ -13,6 +13,7 @@ kwargs_compat, numba_notes, numpy_args_kwargs, + window_agg_numba_args_kwargs_parameters, window_agg_numba_parameters, window_apply_parameters, ) @@ -153,7 +154,7 @@ def aggregate(self, func, *args, **kwargs): doc_template, window_method="expanding", aggregation_description="count of non NaN observations", - parameters="No parameters", + parameters=kwargs_compat, numpy_args_kwargs="", agg_method="count", other_see_also="", @@ -211,8 +212,8 @@ def sum(self, *args, engine=None, engine_kwargs=None, **kwargs): doc_template, window_method="expanding", aggregation_description="maximum", - parameters=window_agg_numba_parameters, - numpy_args_kwargs=numpy_args_kwargs, + parameters=window_agg_numba_args_kwargs_parameters, + numpy_args_kwargs="", agg_method="max", other_see_also="", notes=numba_notes, @@ -226,8 +227,8 @@ def max(self, *args, engine=None, engine_kwargs=None, **kwargs): doc_template, window_method="expanding", aggregation_description="minimum", - parameters="", - numpy_args_kwargs=numpy_args_kwargs, + parameters=window_agg_numba_args_kwargs_parameters, + numpy_args_kwargs="", agg_method="min", other_see_also="", notes=numba_notes, @@ -241,8 +242,8 @@ def min(self, *args, engine=None, engine_kwargs=None, **kwargs): doc_template, window_method="expanding", aggregation_description="mean", - parameters=window_agg_numba_parameters, - numpy_args_kwargs=numpy_args_kwargs, + parameters=window_agg_numba_args_kwargs_parameters, + numpy_args_kwargs="", agg_method="mean", other_see_also="", notes=numba_notes, diff --git a/pandas/core/window/rolling.py b/pandas/core/window/rolling.py index 543a15c4d0382..be870b18279b6 100644 --- a/pandas/core/window/rolling.py +++ b/pandas/core/window/rolling.py @@ -62,6 +62,7 @@ kwargs_scipy, numba_notes, numpy_args_kwargs, + window_agg_numba_args_kwargs_parameters, window_agg_numba_parameters, window_apply_parameters, ) @@ -1378,7 +1379,7 @@ def aggregate(self, func, *args, **kwargs): doc_template, window_method="rolling", aggregation_description="count of non NaN observations", - parameters="No parameters", + parameters=kwargs_compat, numpy_args_kwargs="", agg_method="count", other_see_also="", @@ -1447,8 +1448,8 @@ def apply( doc_template, window_method="rolling", aggregation_description="sum", - parameters=window_agg_numba_parameters, - numpy_args_kwargs=numpy_args_kwargs, + parameters=window_agg_numba_args_kwargs_parameters, + numpy_args_kwargs="", agg_method="sum", other_see_also="", notes=numba_notes, @@ -1508,8 +1509,8 @@ def sum(self, *args, engine=None, engine_kwargs=None, **kwargs): doc_template, window_method="rolling", aggregation_description="maximum", - parameters=window_agg_numba_parameters, - numpy_args_kwargs=numpy_args_kwargs, + parameters=window_agg_numba_args_kwargs_parameters, + numpy_args_kwargs="", agg_method="max", other_see_also="", notes=numba_notes, @@ -1523,8 +1524,8 @@ def max(self, *args, engine=None, engine_kwargs=None, **kwargs): doc_template, window_method="rolling", aggregation_description="minimum", - parameters=window_agg_numba_parameters, - numpy_args_kwargs=numpy_args_kwargs, + parameters=window_agg_numba_args_kwargs_parameters, + numpy_args_kwargs="", agg_method="min", other_see_also="", notes=numba_notes, @@ -1551,8 +1552,8 @@ def min(self, *args, engine=None, engine_kwargs=None, **kwargs): doc_template, window_method="rolling", aggregation_description="mean", - parameters=window_agg_numba_parameters, - numpy_args_kwargs=numpy_args_kwargs, + parameters=window_agg_numba_args_kwargs_parameters, + numpy_args_kwargs="", agg_method="mean", other_see_also="", notes=numba_notes, From 77ce55c7dc1ff41ad7c55665ec6a8e0901a71222 Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Mon, 18 Jan 2021 10:51:06 -0800 Subject: [PATCH 13/23] Fix docstring for expanding sum --- pandas/core/window/expanding.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/window/expanding.py b/pandas/core/window/expanding.py index 24f76077885e7..8399723117f75 100644 --- a/pandas/core/window/expanding.py +++ b/pandas/core/window/expanding.py @@ -197,8 +197,8 @@ def apply( doc_template, window_method="expanding", aggregation_description="sum", - parameters=window_agg_numba_parameters, - numpy_args_kwargs=numpy_args_kwargs, + parameters=window_agg_numba_args_kwargs_parameters, + numpy_args_kwargs="", agg_method="sum", other_see_also="", notes=numba_notes, From db38e9b83c471bec2d594c2ca6daa6923af3c98b Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Tue, 19 Jan 2021 18:44:10 -0800 Subject: [PATCH 14/23] Refactor doc templating for rolling --- pandas/core/window/doc.py | 91 +++---- pandas/core/window/rolling.py | 455 ++++++++++++++++++++-------------- 2 files changed, 299 insertions(+), 247 deletions(-) diff --git a/pandas/core/window/doc.py b/pandas/core/window/doc.py index 6bb7bd32482cb..8951c50b7c99a 100644 --- a/pandas/core/window/doc.py +++ b/pandas/core/window/doc.py @@ -5,53 +5,50 @@ _shared_docs = dict(**_shared_docs) -doc_template = dedent( - """ - Calculate the {window_method} {aggregation_description}. - Parameters - ---------- - {parameters}{numpy_args_kwargs} - Returns - ------- +def create_section_header(header: str) -> str: + """Create numpydoc section header""" + return "\n".join((header, "-" * len(header))) + "\n" + + +template_header = "Calculate the {window_method} {aggregation_description}.\n\n" + +template_returns = dedent( + """ Series or DataFrame Return type is the same as the original object. + """ +).replace("\n", "", 1) - See Also - -------- +template_see_also = dedent( + """ pandas.Series.{window_method} : Calling {window_method} with Series data. pandas.DataFrame.{window_method} : Calling {window_method} with DataFrames. pandas.Series.{agg_method} : Aggregating {agg_method} for Series. pandas.DataFrame.{agg_method} : Aggregating {agg_method} for DataFrame. - {other_see_also} - Notes - ----- - {notes} - Examples - -------- - {examples}""" -) + """ +).replace("\n", "", 1) -numpy_args_kwargs = dedent( +args_compat = dedent( """ - *args, **kwargs - For Numpy compatibility and has no effect on the computed value. + *args + For Numpy compatibility and will not have an effect on the result. """ -) +).replace("\n", "", 1) -kwargs_scipy = dedent( +kwargs_compat = dedent( """ **kwargs - Keyword arguments to configure the ``Scipy`` weighted window type. + For Numpy compatibility and will not have an effect on the result. """ -) +).replace("\n", "", 1) -kwargs_compat = dedent( +kwargs_scipy = dedent( """ **kwargs - For function compatibility and will not have an effect on the result. + Keyword arguments to configure the ``Scipy`` weighted window type. """ -) +).replace("\n", "", 1) window_apply_parameters = dedent( """ @@ -92,13 +89,11 @@ kwargs : dict, default None Keyword arguments to be passed into func. """ -) +).replace("\n", "", 1) -numba_notes = dedent( - """ - See :ref:`window.numba_engine` for extended documentation and performance - considerations for the Numba engine. - """ +numba_notes = ( + "See :ref:`window.numba_engine` for extended documentation " + "and performance considerations for the Numba engine." ) window_agg_numba_parameters = dedent( @@ -119,30 +114,4 @@ .. versionadded:: 1.3.0 """ -) - -window_agg_numba_args_kwargs_parameters = dedent( - """ - *args - For function compatibility and will not have an effect on the result. - - engine : str, default None - * ``'cython'`` : Runs the operation through C-extensions from cython. - * ``'numba'`` : Runs the operation through JIT compiled code from numba. - * ``None`` : Defaults to ``'cython'`` or globally setting ``compute.use_numba`` - - .. versionadded:: 1.3.0 - - engine_kwargs : dict, default None - * For ``'cython'`` engine, there are no accepted ``engine_kwargs`` - * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil`` - and ``parallel`` dictionary keys. The values must either be ``True`` or - ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is - ``{'nopython': True, 'nogil': False, 'parallel': False}`` - - .. versionadded:: 1.3.0 - - **kwargs - For function compatibility and will not have an effect on the result. - """ -) +).replace("\n", "", 1) diff --git a/pandas/core/window/rolling.py b/pandas/core/window/rolling.py index be870b18279b6..ac81556a0e84f 100644 --- a/pandas/core/window/rolling.py +++ b/pandas/core/window/rolling.py @@ -57,12 +57,14 @@ from pandas.core.window.common import flex_binary_moment, zsqrt from pandas.core.window.doc import ( _shared_docs, - doc_template, + args_compat, + create_section_header, kwargs_compat, kwargs_scipy, numba_notes, - numpy_args_kwargs, - window_agg_numba_args_kwargs_parameters, + template_header, + template_returns, + template_see_also, window_agg_numba_parameters, window_apply_parameters, ) @@ -937,15 +939,16 @@ def aggregate(self, func, *args, **kwargs): agg = aggregate @doc( - doc_template, + template_header, + create_section_header("Parameters"), + kwargs_scipy, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, window_method="rolling", aggregation_description="weighted window sum", - parameters=kwargs_scipy, - numpy_args_kwargs="", agg_method="sum", - other_see_also="", - notes="", - examples="", ) def sum(self, *args, **kwargs): nv.validate_window_func("sum", args, kwargs) @@ -953,15 +956,16 @@ def sum(self, *args, **kwargs): return self._apply(window_func, name="sum", **kwargs) @doc( - doc_template, + template_header, + create_section_header("Parameters"), + kwargs_scipy, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, window_method="rolling", aggregation_description="weighted window mean", - parameters=kwargs_scipy, - numpy_args_kwargs="", agg_method="mean", - other_see_also="", - notes="", - examples="", ) def mean(self, *args, **kwargs): nv.validate_window_func("mean", args, kwargs) @@ -969,15 +973,17 @@ def mean(self, *args, **kwargs): return self._apply(window_func, name="mean", **kwargs) @doc( - doc_template, + template_header, + ".. versionadded:: 1.0.0 \n", + create_section_header("Parameters"), + kwargs_scipy, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, window_method="rolling", aggregation_description="weighted window variance", - parameters=kwargs_scipy, - numpy_args_kwargs="", agg_method="var", - other_see_also="", - notes=".. versionadded:: 1.0.0 \n", - examples="", ) def var(self, ddof: int = 1, *args, **kwargs): nv.validate_window_func("var", args, kwargs) @@ -986,15 +992,17 @@ def var(self, ddof: int = 1, *args, **kwargs): return self._apply(window_func, name="var", **kwargs) @doc( - doc_template, + template_header, + ".. versionadded:: 1.0.0 \n", + create_section_header("Parameters"), + kwargs_scipy, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, window_method="rolling", aggregation_description="weighted window standard deviation", - parameters="", - numpy_args_kwargs=numpy_args_kwargs, agg_method="std", - other_see_also="", - notes=".. versionadded:: 1.0.0 \n", - examples="", ) def std(self, ddof: int = 1, *args, **kwargs): nv.validate_window_func("std", args, kwargs) @@ -1376,15 +1384,13 @@ def aggregate(self, func, *args, **kwargs): agg = aggregate @doc( - doc_template, - window_method="rolling", - aggregation_description="count of non NaN observations", - parameters=kwargs_compat, - numpy_args_kwargs="", - agg_method="count", - other_see_also="", - notes="", - examples=dedent( + template_header, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + create_section_header("Examples"), + dedent( """ >>> s = pd.Series([2, 3, np.nan, 10]) >>> s.rolling(2).count() @@ -1406,7 +1412,10 @@ def aggregate(self, func, *args, **kwargs): 3 3.0 dtype: float64 """ - ), + ).replace("\n", "", 1), + window_method="rolling", + aggregation_description="count of non NaN observations", + agg_method="count", ) def count(self): if self.min_periods is None: @@ -1422,15 +1431,16 @@ def count(self): return super().count() @doc( - doc_template, + template_header, + create_section_header("Parameters"), + window_apply_parameters, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, window_method="rolling", aggregation_description="custom aggregation function", - parameters=window_apply_parameters, - numpy_args_kwargs="", agg_method="apply", - other_see_also="", - notes=numba_notes, - examples="", ) def apply( self, func, raw=False, engine=None, engine_kwargs=None, args=None, kwargs=None @@ -1445,15 +1455,19 @@ def apply( ) @doc( - doc_template, - window_method="rolling", - aggregation_description="sum", - parameters=window_agg_numba_args_kwargs_parameters, - numpy_args_kwargs="", - agg_method="sum", - other_see_also="", - notes=numba_notes, - examples=dedent( + template_header, + create_section_header("Parameters"), + args_compat, + window_agg_numba_parameters, + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + create_section_header("Notes"), + numba_notes, + create_section_header("Examples"), + dedent( """ >>> s = pd.Series([1, 2, 3, 4, 5]) >>> s @@ -1499,37 +1513,49 @@ def apply( 3 9.0 29.0 4 12.0 50.0 """ - ), + ).replace("\n", "", 1), + window_method="rolling", + aggregation_description="sum", + agg_method="sum", ) def sum(self, *args, engine=None, engine_kwargs=None, **kwargs): nv.validate_rolling_func("sum", args, kwargs) return super().sum(*args, engine=engine, engine_kwargs=engine_kwargs, **kwargs) @doc( - doc_template, + template_header, + create_section_header("Parameters"), + args_compat, + window_agg_numba_parameters, + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + create_section_header("Notes"), + numba_notes, window_method="rolling", aggregation_description="maximum", - parameters=window_agg_numba_args_kwargs_parameters, - numpy_args_kwargs="", agg_method="max", - other_see_also="", - notes=numba_notes, - examples="", ) def max(self, *args, engine=None, engine_kwargs=None, **kwargs): nv.validate_rolling_func("max", args, kwargs) return super().max(*args, engine=engine, engine_kwargs=engine_kwargs, **kwargs) @doc( - doc_template, - window_method="rolling", - aggregation_description="minimum", - parameters=window_agg_numba_args_kwargs_parameters, - numpy_args_kwargs="", - agg_method="min", - other_see_also="", - notes=numba_notes, - examples=dedent( + template_header, + create_section_header("Parameters"), + args_compat, + window_agg_numba_parameters, + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + create_section_header("Notes"), + numba_notes, + create_section_header("Examples"), + dedent( """ Performing a rolling minimum with a window size of 3. @@ -1542,22 +1568,29 @@ def max(self, *args, engine=None, engine_kwargs=None, **kwargs): 4 2.0 dtype: float64 """ - ), + ).replace("\n", "", 1), + window_method="rolling", + aggregation_description="minimum", + agg_method="min", ) def min(self, *args, engine=None, engine_kwargs=None, **kwargs): nv.validate_rolling_func("min", args, kwargs) return super().min(*args, engine=engine, engine_kwargs=engine_kwargs, **kwargs) @doc( - doc_template, - window_method="rolling", - aggregation_description="mean", - parameters=window_agg_numba_args_kwargs_parameters, - numpy_args_kwargs="", - agg_method="mean", - other_see_also="", - notes=numba_notes, - examples=dedent( + template_header, + create_section_header("Parameters"), + args_compat, + window_agg_numba_parameters, + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + create_section_header("Notes"), + numba_notes, + create_section_header("Examples"), + dedent( """ The below examples will show rolling mean calculations with window sizes of two and three, respectively. @@ -1577,22 +1610,28 @@ def min(self, *args, engine=None, engine_kwargs=None, **kwargs): 3 3.0 dtype: float64 """ - ), + ).replace("\n", "", 1), + window_method="rolling", + aggregation_description="mean", + agg_method="mean", ) def mean(self, *args, engine=None, engine_kwargs=None, **kwargs): nv.validate_rolling_func("mean", args, kwargs) return super().mean(*args, engine=engine, engine_kwargs=engine_kwargs, **kwargs) @doc( - doc_template, - window_method="rolling", - aggregation_description="median", - parameters=window_agg_numba_parameters, - numpy_args_kwargs="", - agg_method="median", - other_see_also="", - notes=numba_notes, - examples=dedent( + template_header, + create_section_header("Parameters"), + window_agg_numba_parameters, + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + create_section_header("Notes"), + numba_notes, + create_section_header("Examples"), + dedent( """ Compute the rolling median of a series with a window size of 3. @@ -1605,34 +1644,42 @@ def mean(self, *args, engine=None, engine_kwargs=None, **kwargs): 4 3.0 dtype: float64 """ - ), + ).replace("\n", "", 1), + window_method="rolling", + aggregation_description="median", + agg_method="median", ) def median(self, engine=None, engine_kwargs=None, **kwargs): return super().median(engine=engine, engine_kwargs=engine_kwargs, **kwargs) @doc( - doc_template, - window_method="rolling", - aggregation_description="standard deviation", - parameters=dedent( + template_header, + create_section_header("Parameters"), + dedent( """ ddof : int, default 1 Delta Degrees of Freedom. The divisor used in calculations is ``N - ddof``, where ``N`` represents the number of elements. """ - ), - numpy_args_kwargs=numpy_args_kwargs, - agg_method="std", - other_see_also="numpy.std : Equivalent method for Numpy array.\n", - notes=dedent( + ).replace("\n", "", 1), + args_compat, + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + "numpy.std : Equivalent method for Numpy array.\n", + create_section_header("Notes"), + dedent( """ The default ``ddof`` of 1 used in :meth:`Series.std` is different than the default ``ddof`` of 0 in :func:`numpy.std`. A minimum of one period is required for the rolling calculation. """ - ), - examples=dedent( + ).replace("\n", "", 1), + create_section_header("Examples"), + dedent( """ >>> s = pd.Series([5, 5, 6, 7, 5, 5, 5]) >>> s.rolling(3).std() @@ -1645,35 +1692,43 @@ def median(self, engine=None, engine_kwargs=None, **kwargs): 6 0.000000 dtype: float64 """ - ), + ).replace("\n", "", 1), + window_method="rolling", + aggregation_description="standard deviation", + agg_method="std", ) def std(self, ddof=1, *args, **kwargs): nv.validate_rolling_func("std", args, kwargs) return super().std(ddof=ddof, **kwargs) @doc( - doc_template, - window_method="rolling", - aggregation_description="variance", - parameters=dedent( + template_header, + create_section_header("Parameters"), + dedent( """ ddof : int, default 1 Delta Degrees of Freedom. The divisor used in calculations is ``N - ddof``, where ``N`` represents the number of elements. """ - ), - numpy_args_kwargs=numpy_args_kwargs, - agg_method="var", - other_see_also="numpy.var : Equivalent method for Numpy array.\n", - notes=dedent( + ).replace("\n", "", 1), + args_compat, + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + "numpy.var : Equivalent method for Numpy array.\n", + create_section_header("Notes"), + dedent( """ The default ``ddof`` of 1 used in :meth:`Series.var` is different than the default ``ddof`` of 0 in :func:`numpy.var`. A minimum of one period is required for the rolling calculation. """ - ), - examples=dedent( + ).replace("\n", "", 1), + create_section_header("Examples"), + dedent( """ >>> s = pd.Series([5, 5, 6, 7, 5, 5, 5]) >>> s.rolling(3).var() @@ -1686,42 +1741,53 @@ def std(self, ddof=1, *args, **kwargs): 6 0.000000 dtype: float64 """ - ), + ).replace("\n", "", 1), + window_method="rolling", + aggregation_description="variance", + agg_method="var", ) def var(self, ddof=1, *args, **kwargs): nv.validate_rolling_func("var", args, kwargs) return super().var(ddof=ddof, **kwargs) @doc( - doc_template, + template_header, + create_section_header("Parameters"), + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + "scipy.stats.skew : Third moment of a probability density.\n", + create_section_header("Notes"), + "A minimum of three periods is required for the rolling calculation.\n", window_method="rolling", aggregation_description="unbiased skewness", - parameters=kwargs_compat, - numpy_args_kwargs=numpy_args_kwargs, agg_method="skew", - other_see_also="scipy.stats.skew : Third moment of a probability density.\n", - notes="A minimum of three periods is required for the rolling calculation.", - examples="", ) def skew(self, **kwargs): return super().skew(**kwargs) @doc( - doc_template, - window_method="rolling", - aggregation_description="standard error of mean", - parameters=dedent( + template_header, + create_section_header("Parameters"), + dedent( """ ddof : int, default 1 Delta Degrees of Freedom. The divisor used in calculations is ``N - ddof``, where ``N`` represents the number of elements. """ - ), - numpy_args_kwargs="", - agg_method="sem", - other_see_also="", - notes="A minimum of one period is required for the calculation.\n", - examples=dedent( + ).replace("\n", "", 1), + args_compat, + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + create_section_header("Notes"), + "A minimum of one period is required for the calculation.\n", + create_section_header("Examples"), + dedent( """ >>> s = pd.Series([0, 1, 2, 3]) >>> s.rolling(2, min_periods=1).sem() @@ -1731,25 +1797,27 @@ def skew(self, **kwargs): 3 0.707107 dtype: float64 """ - ), + ).replace("\n", "", 1), + window_method="rolling", + aggregation_description="standard error of mean", + agg_method="sem", ) def sem(self, ddof=1, *args, **kwargs): return self.std(*args, **kwargs) / (self.count() - ddof).pow(0.5) @doc( - doc_template, - window_method="rolling", - aggregation_description="Fisher's definition of kurtosis without bias", - parameters=kwargs_compat, - numpy_args_kwargs="", - agg_method="kurt", - other_see_also="scipy.stats.kurtosis : Reference SciPy method.\n", - notes=dedent( - """ - A minimum of four periods is required for the calculation. - """ - ), - examples=dedent( + template_header, + create_section_header("Parameters"), + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + "scipy.stats.kurtosis : Reference SciPy method.\n", + create_section_header("Notes"), + "A minimum of four periods is required for the calculation.\n", + create_section_header("Examples"), + dedent( """ The example below will show a rolling calculation with a window size of four matching the equivalent function call using `scipy.stats`. @@ -1769,16 +1837,18 @@ def sem(self, ddof=1, *args, **kwargs): 4 3.999946 dtype: float64 """ - ), + ).replace("\n", "", 1), + window_method="rolling", + aggregation_description="Fisher's definition of kurtosis without bias", + agg_method="kurt", ) def kurt(self, **kwargs): return super().kurt(**kwargs) @doc( - doc_template, - window_method="rolling", - aggregation_description="quantile", - parameters=dedent( + template_header, + create_section_header("Parameters"), + dedent( """ quantile : float Quantile to compute. 0 <= quantile <= 1. @@ -1795,12 +1865,14 @@ def kurt(self, **kwargs): **kwargs For function compatibility and will not have an effect on the result. """ - ), - numpy_args_kwargs="", - agg_method="quantile", - other_see_also="", - notes="", - examples=dedent( + ).replace("\n", "", 1), + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + create_section_header("Examples"), + dedent( """ >>> s = pd.Series([1, 2, 3, 4]) >>> s.rolling(2).quantile(.4, interpolation='lower') @@ -1817,7 +1889,10 @@ def kurt(self, **kwargs): 3 3.5 dtype: float64 """ - ), + ).replace("\n", "", 1), + window_method="rolling", + aggregation_description="quantile", + agg_method="quantile", ) def quantile(self, quantile, interpolation="linear", **kwargs): return super().quantile( @@ -1827,10 +1902,9 @@ def quantile(self, quantile, interpolation="linear", **kwargs): ) @doc( - doc_template, - window_method="rolling", - aggregation_description="sample covariance", - parameters=dedent( + template_header, + create_section_header("Parameters"), + dedent( """ other : Series, DataFrame, or ndarray, optional If not supplied then will default to self and produce pairwise @@ -1845,45 +1919,50 @@ def quantile(self, quantile, interpolation="linear", **kwargs): ddof : int, default 1 Delta Degrees of Freedom. The divisor used in calculations is ``N - ddof``, where ``N`` represents the number of elements. - **kwargs - For function compatibility and will not have an effect on the result. """ - ), - numpy_args_kwargs="", + ).replace("\n", "", 1), + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + window_method="rolling", + aggregation_description="sample covariance", agg_method="cov", - other_see_also="", - notes="", - examples="", ) def cov(self, other=None, pairwise=None, ddof=1, **kwargs): return super().cov(other=other, pairwise=pairwise, ddof=ddof, **kwargs) @doc( - doc_template, - window_method="rolling", - aggregation_description="covariance", - parameters=dedent( + template_header, + create_section_header("Parameters"), + dedent( """ other : Series, DataFrame, or ndarray, optional - If not supplied then will default to self. + If not supplied then will default to self and produce pairwise + output. pairwise : bool, default None - Calculate pairwise combinations of columns within a - DataFrame. If `other` is not specified, defaults to `True`, - otherwise defaults to `False`. - Not relevant for :class:`~pandas.Series`. - **kwargs - For function compatibility and will not have an effect on the result. + If False then only matching columns between self and other will be + used and the output will be a DataFrame. + If True then all pairwise combinations will be calculated and the + output will be a MultiIndexed DataFrame in the case of DataFrame + inputs. In the case of missing elements, only complete pairwise + observations will be used. """ - ), - numpy_args_kwargs="", - agg_method="corr", - other_see_also=dedent( + ).replace("\n", "", 1), + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + dedent( """ cov : Similar method to calculate covariance. numpy.corrcoef : NumPy Pearson's correlation calculation. """ - ), - notes=dedent( + ).replace("\n", "", 1), + create_section_header("Notes"), + dedent( """ This function uses Pearson's definition of correlation (https://en.wikipedia.org/wiki/Pearson_correlation_coefficient). @@ -1905,8 +1984,9 @@ def cov(self, other=None, pairwise=None, ddof=1, **kwargs): In the case of missing elements, only complete pairwise observations will be used. """ - ), - examples=dedent( + ).replace("\n", "", 1), + create_section_header("Examples"), + dedent( """ The below example shows a rolling calculation with a window size of four matching the equivalent function call using :meth:`numpy.corrcoef`. @@ -1961,7 +2041,10 @@ def cov(self, other=None, pairwise=None, ddof=1, **kwargs): 4 X 1.000000 0.555368 Y 0.555368 1.000000 """ - ), + ).replace("\n", "", 1), + window_method="rolling", + aggregation_description="correlation", + agg_method="corr", ) def corr(self, other=None, pairwise=None, **kwargs): return super().corr(other=other, pairwise=pairwise, **kwargs) From 768cbb17db2ce1ce58983891330ed54b32eb410c Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Tue, 19 Jan 2021 20:15:29 -0800 Subject: [PATCH 15/23] Refactor expanding docstrings --- pandas/core/window/expanding.py | 343 +++++++++++++++++++------------- pandas/core/window/rolling.py | 2 - 2 files changed, 202 insertions(+), 143 deletions(-) diff --git a/pandas/core/window/expanding.py b/pandas/core/window/expanding.py index 8399723117f75..260322f0c6edb 100644 --- a/pandas/core/window/expanding.py +++ b/pandas/core/window/expanding.py @@ -9,11 +9,13 @@ from pandas.core.window.doc import ( _shared_docs, - doc_template, + args_compat, + create_section_header, kwargs_compat, numba_notes, - numpy_args_kwargs, - window_agg_numba_args_kwargs_parameters, + template_header, + template_returns, + template_see_also, window_agg_numba_parameters, window_apply_parameters, ) @@ -151,29 +153,29 @@ def aggregate(self, func, *args, **kwargs): agg = aggregate @doc( - doc_template, + template_header, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, window_method="expanding", aggregation_description="count of non NaN observations", - parameters=kwargs_compat, - numpy_args_kwargs="", agg_method="count", - other_see_also="", - notes="", - examples="", ) def count(self): return super().count() @doc( - doc_template, + template_header, + create_section_header("Parameters"), + window_apply_parameters, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, window_method="expanding", aggregation_description="custom aggregation function", - parameters=window_apply_parameters, - numpy_args_kwargs="", agg_method="apply", - other_see_also="", - notes=numba_notes, - examples="", ) def apply( self, @@ -194,102 +196,131 @@ def apply( ) @doc( - doc_template, + template_header, + create_section_header("Parameters"), + args_compat, + window_agg_numba_parameters, + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + create_section_header("Notes"), + numba_notes, window_method="expanding", aggregation_description="sum", - parameters=window_agg_numba_args_kwargs_parameters, - numpy_args_kwargs="", agg_method="sum", - other_see_also="", - notes=numba_notes, - examples="", ) def sum(self, *args, engine=None, engine_kwargs=None, **kwargs): nv.validate_expanding_func("sum", args, kwargs) return super().sum(*args, engine=engine, engine_kwargs=engine_kwargs, **kwargs) @doc( - doc_template, + template_header, + create_section_header("Parameters"), + args_compat, + window_agg_numba_parameters, + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + create_section_header("Notes"), + numba_notes, window_method="expanding", aggregation_description="maximum", - parameters=window_agg_numba_args_kwargs_parameters, - numpy_args_kwargs="", agg_method="max", - other_see_also="", - notes=numba_notes, - examples="", ) def max(self, *args, engine=None, engine_kwargs=None, **kwargs): nv.validate_expanding_func("max", args, kwargs) return super().max(*args, engine=engine, engine_kwargs=engine_kwargs, **kwargs) @doc( - doc_template, + template_header, + create_section_header("Parameters"), + args_compat, + window_agg_numba_parameters, + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + create_section_header("Notes"), + numba_notes, window_method="expanding", aggregation_description="minimum", - parameters=window_agg_numba_args_kwargs_parameters, - numpy_args_kwargs="", agg_method="min", - other_see_also="", - notes=numba_notes, - examples="", ) def min(self, *args, engine=None, engine_kwargs=None, **kwargs): nv.validate_expanding_func("min", args, kwargs) return super().min(*args, engine=engine, engine_kwargs=engine_kwargs, **kwargs) @doc( - doc_template, + template_header, + create_section_header("Parameters"), + args_compat, + window_agg_numba_parameters, + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + create_section_header("Notes"), + numba_notes, window_method="expanding", aggregation_description="mean", - parameters=window_agg_numba_args_kwargs_parameters, - numpy_args_kwargs="", agg_method="mean", - other_see_also="", - notes=numba_notes, - examples="", ) def mean(self, *args, engine=None, engine_kwargs=None, **kwargs): nv.validate_expanding_func("mean", args, kwargs) return super().mean(*args, engine=engine, engine_kwargs=engine_kwargs, **kwargs) @doc( - doc_template, + template_header, + create_section_header("Parameters"), + window_agg_numba_parameters, + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + create_section_header("Notes"), + numba_notes, window_method="expanding", aggregation_description="median", - parameters=window_agg_numba_parameters, - numpy_args_kwargs="", agg_method="median", - other_see_also="", - notes=numba_notes, - examples="", ) def median(self, engine=None, engine_kwargs=None, **kwargs): return super().median(engine=engine, engine_kwargs=engine_kwargs, **kwargs) @doc( - doc_template, - window_method="expanding", - aggregation_description="standard deviation", - parameters=dedent( + template_header, + create_section_header("Parameters"), + dedent( """ ddof : int, default 1 Delta Degrees of Freedom. The divisor used in calculations is ``N - ddof``, where ``N`` represents the number of elements. """ - ), - numpy_args_kwargs=numpy_args_kwargs, - agg_method="std", - other_see_also="numpy.std : Equivalent method for Numpy array.\n", - notes=dedent( + ).replace("\n", "", 1), + args_compat, + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + "numpy.std : Equivalent method for Numpy array.\n", + create_section_header("Notes"), + dedent( """ The default ``ddof`` of 1 used in :meth:`Series.std` is different than the default ``ddof`` of 0 in :func:`numpy.std`. A minimum of one period is required for the rolling calculation. """ - ), - examples=dedent( + ).replace("\n", "", 1), + create_section_header("Examples"), + dedent( """ >>> s = pd.Series([5, 5, 6, 7, 5, 5, 5]) @@ -303,35 +334,43 @@ def median(self, engine=None, engine_kwargs=None, **kwargs): 6 0.786796 dtype: float64 """ - ), + ).replace("\n", "", 1), + window_method="expanding", + aggregation_description="standard deviation", + agg_method="std", ) def std(self, ddof: int = 1, *args, **kwargs): nv.validate_expanding_func("std", args, kwargs) return super().std(ddof=ddof, **kwargs) @doc( - doc_template, - window_method="expanding", - aggregation_description="variance", - parameters=dedent( + template_header, + create_section_header("Parameters"), + dedent( """ ddof : int, default 1 Delta Degrees of Freedom. The divisor used in calculations is ``N - ddof``, where ``N`` represents the number of elements. """ - ), - numpy_args_kwargs=numpy_args_kwargs, - agg_method="var", - other_see_also="numpy.var : Equivalent method for Numpy array.\n", - notes=dedent( + ).replace("\n", "", 1), + args_compat, + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + "numpy.var : Equivalent method for Numpy array.\n", + create_section_header("Notes"), + dedent( """ The default ``ddof`` of 1 used in :meth:`Series.var` is different than the default ``ddof`` of 0 in :func:`numpy.var`. A minimum of one period is required for the rolling calculation. """ - ), - examples=dedent( + ).replace("\n", "", 1), + create_section_header("Examples"), + dedent( """ >>> s = pd.Series([5, 5, 6, 7, 5, 5, 5]) @@ -345,28 +384,35 @@ def std(self, ddof: int = 1, *args, **kwargs): 6 0.619048 dtype: float64 """ - ), + ).replace("\n", "", 1), + window_method="expanding", + aggregation_description="variance", + agg_method="var", ) def var(self, ddof: int = 1, *args, **kwargs): nv.validate_expanding_func("var", args, kwargs) return super().var(ddof=ddof, **kwargs) @doc( - doc_template, - window_method="expanding", - aggregation_description="standard error of mean", - parameters=dedent( + template_header, + create_section_header("Parameters"), + dedent( """ ddof : int, default 1 Delta Degrees of Freedom. The divisor used in calculations is ``N - ddof``, where ``N`` represents the number of elements. """ - ), - numpy_args_kwargs="", - agg_method="sem", - other_see_also="", - notes="A minimum of one period is required for the calculation.", - examples=dedent( + ).replace("\n", "", 1), + args_compat, + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + create_section_header("Notes"), + "A minimum of one period is required for the calculation.\n", + create_section_header("Examples"), + dedent( """ >>> s = pd.Series([0, 1, 2, 3]) @@ -377,39 +423,45 @@ def var(self, ddof: int = 1, *args, **kwargs): 3 0.745356 dtype: float64 """ - ), + ).replace("\n", "", 1), + window_method="expanding", + aggregation_description="standard error of mean", + agg_method="sem", ) def sem(self, ddof: int = 1, *args, **kwargs): return super().sem(ddof=ddof, **kwargs) @doc( - doc_template, + template_header, + create_section_header("Parameters"), + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + "scipy.stats.skew : Third moment of a probability density.\n", + create_section_header("Notes"), + "A minimum of three periods is required for the rolling calculation.\n", window_method="expanding", aggregation_description="unbiased skewness", - parameters=kwargs_compat, - numpy_args_kwargs=numpy_args_kwargs, agg_method="skew", - other_see_also="scipy.stats.skew : Third moment of a probability density.\n", - notes="A minimum of three periods is required for the rolling calculation.", - examples="", ) def skew(self, **kwargs): return super().skew(**kwargs) @doc( - doc_template, - window_method="expanding", - aggregation_description="Fisher's definition of kurtosis without bias", - parameters=kwargs_compat, - numpy_args_kwargs="", - agg_method="kurt", - other_see_also="scipy.stats.kurtosis : Reference SciPy method.\n", - notes=dedent( - """ - A minimum of four periods is required for the calculation. - """ - ), - examples=dedent( + template_header, + create_section_header("Parameters"), + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + "scipy.stats.kurtosis : Reference SciPy method.\n", + create_section_header("Notes"), + "A minimum of four periods is required for the calculation.\n", + create_section_header("Examples"), + dedent( """ The example below will show a rolling calculation with a window size of four matching the equivalent function call using `scipy.stats`. @@ -429,16 +481,18 @@ def skew(self, **kwargs): 4 4.999874 dtype: float64 """ - ), + ).replace("\n", "", 1), + window_method="expanding", + aggregation_description="Fisher's definition of kurtosis without bias", + agg_method="kurt", ) def kurt(self, **kwargs): return super().kurt(**kwargs) @doc( - doc_template, - window_method="expanding", - aggregation_description="quantile", - parameters=dedent( + template_header, + create_section_header("Parameters"), + dedent( """ quantile : float Quantile to compute. 0 <= quantile <= 1. @@ -452,15 +506,16 @@ def kurt(self, **kwargs): * higher: `j`. * nearest: `i` or `j` whichever is nearest. * midpoint: (`i` + `j`) / 2. - **kwargs - For function compatibility and will not have an effect on the result. """ - ), - numpy_args_kwargs="", + ).replace("\n", "", 1), + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + window_method="expanding", + aggregation_description="quantile", agg_method="quantile", - other_see_also="", - notes="", - examples="", ) def quantile( self, @@ -475,10 +530,9 @@ def quantile( ) @doc( - doc_template, - window_method="expanding", - aggregation_description="sample covariance", - parameters=dedent( + template_header, + create_section_header("Parameters"), + dedent( """ other : Series, DataFrame, or ndarray, optional If not supplied then will default to self and produce pairwise @@ -493,15 +547,16 @@ def quantile( ddof : int, default 1 Delta Degrees of Freedom. The divisor used in calculations is ``N - ddof``, where ``N`` represents the number of elements. - **kwargs - For function compatibility and will not have an effect on the result. """ - ), - numpy_args_kwargs="", + ).replace("\n", "", 1), + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + window_method="expanding", + aggregation_description="sample covariance", agg_method="cov", - other_see_also="", - notes="", - examples="", ) def cov( self, @@ -513,31 +568,35 @@ def cov( return super().cov(other=other, pairwise=pairwise, ddof=ddof, **kwargs) @doc( - doc_template, - window_method="rolling", - aggregation_description="covariance", - parameters=dedent( + template_header, + create_section_header("Parameters"), + dedent( """ other : Series, DataFrame, or ndarray, optional - If not supplied then will default to self. + If not supplied then will default to self and produce pairwise + output. pairwise : bool, default None - Calculate pairwise combinations of columns within a - DataFrame. If `other` is not specified, defaults to `True`, - otherwise defaults to `False`. - Not relevant for :class:`~pandas.Series`. - **kwargs - For function compatibility and will not have an effect on the result. + If False then only matching columns between self and other will be + used and the output will be a DataFrame. + If True then all pairwise combinations will be calculated and the + output will be a MultiIndexed DataFrame in the case of DataFrame + inputs. In the case of missing elements, only complete pairwise + observations will be used. """ - ), - numpy_args_kwargs="", - agg_method="corr", - other_see_also=dedent( + ).replace("\n", "", 1), + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + dedent( """ cov : Similar method to calculate covariance. numpy.corrcoef : NumPy Pearson's correlation calculation. """ - ), - notes=dedent( + ).replace("\n", "", 1), + create_section_header("Notes"), + dedent( """ This function uses Pearson's definition of correlation (https://en.wikipedia.org/wiki/Pearson_correlation_coefficient). @@ -559,8 +618,10 @@ def cov( In the case of missing elements, only complete pairwise observations will be used. """ - ), - examples="", + ).replace("\n", "", 1), + window_method="expanding", + aggregation_description="correlation", + agg_method="corr", ) def corr( self, diff --git a/pandas/core/window/rolling.py b/pandas/core/window/rolling.py index ac81556a0e84f..190ae26aacdcd 100644 --- a/pandas/core/window/rolling.py +++ b/pandas/core/window/rolling.py @@ -1862,8 +1862,6 @@ def kurt(self, **kwargs): * higher: `j`. * nearest: `i` or `j` whichever is nearest. * midpoint: (`i` + `j`) / 2. - **kwargs - For function compatibility and will not have an effect on the result. """ ).replace("\n", "", 1), kwargs_compat, From 0b443de2c4a75b105047cc9f68a0890d01c2ba19 Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Tue, 19 Jan 2021 20:22:22 -0800 Subject: [PATCH 16/23] Refactor ewm docstrings --- pandas/core/window/ewm.py | 106 ++++++++++++++++++++++---------------- 1 file changed, 63 insertions(+), 43 deletions(-) diff --git a/pandas/core/window/ewm.py b/pandas/core/window/ewm.py index b030ad9282dbe..8c5065cac6fb2 100644 --- a/pandas/core/window/ewm.py +++ b/pandas/core/window/ewm.py @@ -19,7 +19,15 @@ import pandas.core.common as common from pandas.core.util.numba_ import maybe_use_numba from pandas.core.window.common import flex_binary_moment, zsqrt -from pandas.core.window.doc import _shared_docs, doc_template, numpy_args_kwargs +from pandas.core.window.doc import ( + _shared_docs, + args_compat, + create_section_header, + kwargs_compat, + template_header, + template_returns, + template_see_also, +) from pandas.core.window.indexers import ( BaseIndexer, ExponentialMovingWindowIndexer, @@ -304,15 +312,17 @@ def aggregate(self, func, *args, **kwargs): agg = aggregate @doc( - doc_template, + template_header, + create_section_header("Parameters"), + args_compat, + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, window_method="ewm", aggregation_description="(exponential weighted moment) mean", - parameters="", - numpy_args_kwargs=numpy_args_kwargs, agg_method="mean", - other_see_also="", - notes="", - examples="", ) def mean(self, *args, **kwargs): nv.validate_window_func("mean", args, kwargs) @@ -334,20 +344,23 @@ def mean(self, *args, **kwargs): return self._apply(window_func) @doc( - doc_template, - window_method="ewm", - aggregation_description="(exponential weighted moment) standard deviation", - parameters=dedent( + template_header, + create_section_header("Parameters"), + dedent( """ bias : bool, default False Use a standard estimation bias correction. """ - ), - numpy_args_kwargs=numpy_args_kwargs, + ).replace("\n", "", 1), + args_compat, + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + window_method="ewm", + aggregation_description="(exponential weighted moment) standard deviation", agg_method="std", - other_see_also="", - notes="", - examples="", ) def std(self, bias: bool = False, *args, **kwargs): nv.validate_window_func("std", args, kwargs) @@ -356,20 +369,23 @@ def std(self, bias: bool = False, *args, **kwargs): vol = std @doc( - doc_template, - window_method="ewm", - aggregation_description="(exponential weighted moment) variance", - parameters=dedent( + template_header, + create_section_header("Parameters"), + dedent( """ bias : bool, default False Use a standard estimation bias correction. """ - ), - numpy_args_kwargs=numpy_args_kwargs, + ).replace("\n", "", 1), + args_compat, + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + window_method="ewm", + aggregation_description="(exponential weighted moment) variance", agg_method="var", - other_see_also="", - notes="", - examples="", ) def var(self, bias: bool = False, *args, **kwargs): nv.validate_window_func("var", args, kwargs) @@ -388,10 +404,9 @@ def var_func(values, begin, end, min_periods): return self._apply(var_func) @doc( - doc_template, - window_method="ewm", - aggregation_description="(exponential weighted moment) sample covarance", - parameters=dedent( + template_header, + create_section_header("Parameters"), + dedent( """ other : Series, DataFrame, or ndarray, optional If not supplied then will default to self and produce pairwise @@ -406,12 +421,15 @@ def var_func(values, begin, end, min_periods): bias : bool, default False Use a standard estimation bias correction. """ - ), - numpy_args_kwargs=numpy_args_kwargs, + ).replace("\n", "", 1), + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + window_method="ewm", + aggregation_description="(exponential weighted moment) sample covariance", agg_method="cov", - other_see_also="", - notes="", - examples="", ) def cov( self, @@ -447,10 +465,9 @@ def _get_cov(X, Y): ) @doc( - doc_template, - window_method="ewm", - aggregation_description="(exponential weighted moment) sample correlation", - parameters=dedent( + template_header, + create_section_header("Parameters"), + dedent( """ other : Series, DataFrame, or ndarray, optional If not supplied then will default to self and produce pairwise @@ -463,12 +480,15 @@ def _get_cov(X, Y): inputs. In the case of missing elements, only complete pairwise observations will be used. """ - ), - numpy_args_kwargs=numpy_args_kwargs, + ).replace("\n", "", 1), + kwargs_compat, + create_section_header("Returns"), + template_returns, + create_section_header("See Also"), + template_see_also, + window_method="ewm", + aggregation_description="(exponential weighted moment) sample correlation", agg_method="corr", - other_see_also="", - notes="", - examples="", ) def corr( self, From 32ee31fbe2734701a26f3d54a44e046d7f0cb172 Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Wed, 20 Jan 2021 17:45:24 -0800 Subject: [PATCH 17/23] Fix some local docstring warnings --- pandas/core/window/doc.py | 22 ++++++++++++---------- pandas/core/window/expanding.py | 26 +++++++++++++------------- pandas/core/window/rolling.py | 32 ++++++++++++++++---------------- 3 files changed, 41 insertions(+), 39 deletions(-) diff --git a/pandas/core/window/doc.py b/pandas/core/window/doc.py index 8951c50b7c99a..343156832d0ae 100644 --- a/pandas/core/window/doc.py +++ b/pandas/core/window/doc.py @@ -16,7 +16,7 @@ def create_section_header(header: str) -> str: template_returns = dedent( """ Series or DataFrame - Return type is the same as the original object. + Return type is the same as the original object.\n """ ).replace("\n", "", 1) @@ -25,28 +25,28 @@ def create_section_header(header: str) -> str: pandas.Series.{window_method} : Calling {window_method} with Series data. pandas.DataFrame.{window_method} : Calling {window_method} with DataFrames. pandas.Series.{agg_method} : Aggregating {agg_method} for Series. - pandas.DataFrame.{agg_method} : Aggregating {agg_method} for DataFrame. + pandas.DataFrame.{agg_method} : Aggregating {agg_method} for DataFrame.\n """ ).replace("\n", "", 1) args_compat = dedent( """ *args - For Numpy compatibility and will not have an effect on the result. + For Numpy compatibility and will not have an effect on the result.\n """ ).replace("\n", "", 1) kwargs_compat = dedent( """ **kwargs - For Numpy compatibility and will not have an effect on the result. + For Numpy compatibility and will not have an effect on the result.\n """ ).replace("\n", "", 1) kwargs_scipy = dedent( """ **kwargs - Keyword arguments to configure the ``Scipy`` weighted window type. + Keyword arguments to configure the ``Scipy`` weighted window type.\n """ ).replace("\n", "", 1) @@ -66,6 +66,7 @@ def create_section_header(header: str) -> str: objects instead. If you are just applying a NumPy reduction function this will achieve much better performance. + engine : str, default None * ``'cython'`` : Runs rolling apply through C-extensions from cython. * ``'numba'`` : Runs rolling apply through JIT compiled code from numba. @@ -79,21 +80,22 @@ def create_section_header(header: str) -> str: * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil`` and ``parallel`` dictionary keys. The values must either be ``True`` or ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is - ``{'nopython': True, 'nogil': False, 'parallel': False}`` and will be + ``{{'nopython': True, 'nogil': False, 'parallel': False}}`` and will be applied to both the ``func`` and the ``apply`` rolling aggregation. .. versionadded:: 1.0.0 args : tuple, default None Positional arguments to be passed into func. + kwargs : dict, default None - Keyword arguments to be passed into func. + Keyword arguments to be passed into func.\n """ ).replace("\n", "", 1) numba_notes = ( "See :ref:`window.numba_engine` for extended documentation " - "and performance considerations for the Numba engine." + "and performance considerations for the Numba engine.\n" ) window_agg_numba_parameters = dedent( @@ -110,8 +112,8 @@ def create_section_header(header: str) -> str: * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil`` and ``parallel`` dictionary keys. The values must either be ``True`` or ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is - ``{'nopython': True, 'nogil': False, 'parallel': False}`` + ``{{'nopython': True, 'nogil': False, 'parallel': False}}`` - .. versionadded:: 1.3.0 + .. versionadded:: 1.3.0\n """ ).replace("\n", "", 1) diff --git a/pandas/core/window/expanding.py b/pandas/core/window/expanding.py index 260322f0c6edb..11992557f78a5 100644 --- a/pandas/core/window/expanding.py +++ b/pandas/core/window/expanding.py @@ -300,7 +300,7 @@ def median(self, engine=None, engine_kwargs=None, **kwargs): """ ddof : int, default 1 Delta Degrees of Freedom. The divisor used in calculations - is ``N - ddof``, where ``N`` represents the number of elements. + is ``N - ddof``, where ``N`` represents the number of elements.\n """ ).replace("\n", "", 1), args_compat, @@ -308,15 +308,15 @@ def median(self, engine=None, engine_kwargs=None, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, "numpy.std : Equivalent method for Numpy array.\n", + template_see_also, create_section_header("Notes"), dedent( """ The default ``ddof`` of 1 used in :meth:`Series.std` is different than the default ``ddof`` of 0 in :func:`numpy.std`. - A minimum of one period is required for the rolling calculation. + A minimum of one period is required for the rolling calculation.\n """ ).replace("\n", "", 1), create_section_header("Examples"), @@ -350,7 +350,7 @@ def std(self, ddof: int = 1, *args, **kwargs): """ ddof : int, default 1 Delta Degrees of Freedom. The divisor used in calculations - is ``N - ddof``, where ``N`` represents the number of elements. + is ``N - ddof``, where ``N`` represents the number of elements.\n """ ).replace("\n", "", 1), args_compat, @@ -358,15 +358,15 @@ def std(self, ddof: int = 1, *args, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, "numpy.var : Equivalent method for Numpy array.\n", + template_see_also, create_section_header("Notes"), dedent( """ The default ``ddof`` of 1 used in :meth:`Series.var` is different than the default ``ddof`` of 0 in :func:`numpy.var`. - A minimum of one period is required for the rolling calculation. + A minimum of one period is required for the rolling calculation.\n """ ).replace("\n", "", 1), create_section_header("Examples"), @@ -400,7 +400,7 @@ def var(self, ddof: int = 1, *args, **kwargs): """ ddof : int, default 1 Delta Degrees of Freedom. The divisor used in calculations - is ``N - ddof``, where ``N`` represents the number of elements. + is ``N - ddof``, where ``N`` represents the number of elements.\n """ ).replace("\n", "", 1), args_compat, @@ -438,8 +438,8 @@ def sem(self, ddof: int = 1, *args, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, "scipy.stats.skew : Third moment of a probability density.\n", + template_see_also, create_section_header("Notes"), "A minimum of three periods is required for the rolling calculation.\n", window_method="expanding", @@ -456,8 +456,8 @@ def skew(self, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, "scipy.stats.kurtosis : Reference SciPy method.\n", + template_see_also, create_section_header("Notes"), "A minimum of four periods is required for the calculation.\n", create_section_header("Examples"), @@ -468,9 +468,9 @@ def skew(self, **kwargs): >>> arr = [1, 2, 3, 4, 999] >>> import scipy.stats - >>> print(f"{scipy.stats.kurtosis(arr[:-1], bias=False):.6f}") + >>> print(f"{{scipy.stats.kurtosis(arr[:-1], bias=False):.6f}}") -1.200000 - >>> print(f"{scipy.stats.kurtosis(arr, bias=False):.6f}") + >>> print(f"{{scipy.stats.kurtosis(arr, bias=False):.6f}}") 4.999874 >>> s = pd.Series(arr) >>> s.expanding(4).kurt() @@ -496,7 +496,7 @@ def kurt(self, **kwargs): """ quantile : float Quantile to compute. 0 <= quantile <= 1. - interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'} + interpolation : {{'linear', 'lower', 'higher', 'midpoint', 'nearest'}} This optional parameter specifies the interpolation method to use, when the desired quantile lies between two data points `i` and `j`: @@ -588,13 +588,13 @@ def cov( create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, dedent( """ cov : Similar method to calculate covariance. numpy.corrcoef : NumPy Pearson's correlation calculation. """ ).replace("\n", "", 1), + template_see_also, create_section_header("Notes"), dedent( """ diff --git a/pandas/core/window/rolling.py b/pandas/core/window/rolling.py index 190ae26aacdcd..372d5ff5edb9f 100644 --- a/pandas/core/window/rolling.py +++ b/pandas/core/window/rolling.py @@ -910,7 +910,7 @@ def calc(x): """ Examples -------- - >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6], "C": [7, 8, 9]}) + >>> df = pd.DataFrame({{"A": [1, 2, 3], "B": [4, 5, 6], "C": [7, 8, 9]}}) >>> df A B C 0 1 4 7 @@ -974,7 +974,7 @@ def mean(self, *args, **kwargs): @doc( template_header, - ".. versionadded:: 1.0.0 \n", + ".. versionadded:: 1.0.0 \n\n", create_section_header("Parameters"), kwargs_scipy, create_section_header("Returns"), @@ -993,7 +993,7 @@ def var(self, ddof: int = 1, *args, **kwargs): @doc( template_header, - ".. versionadded:: 1.0.0 \n", + ".. versionadded:: 1.0.0 \n\n", create_section_header("Parameters"), kwargs_scipy, create_section_header("Returns"), @@ -1355,7 +1355,7 @@ def _raise_monotonic_error(self): """ Examples -------- - >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6], "C": [7, 8, 9]}) + >>> df = pd.DataFrame({{"A": [1, 2, 3], "B": [4, 5, 6], "C": [7, 8, 9]}}) >>> df A B C 0 1 4 7 @@ -1368,7 +1368,7 @@ def _raise_monotonic_error(self): 1 3.0 9.0 15.0 2 5.0 11.0 17.0 - >>> df.rolling(2).agg({"A": "sum", "B": "min"}) + >>> df.rolling(2).agg({{"A": "sum", "B": "min"}}) A B 0 NaN NaN 1 3.0 4.0 @@ -1496,7 +1496,7 @@ def apply( For DataFrame, each sum is computed column-wise. - >>> df = pd.DataFrame({"A": s, "B": s ** 2}) + >>> df = pd.DataFrame({{"A": s, "B": s ** 2}}) >>> df A B 0 1 1 @@ -1667,8 +1667,8 @@ def median(self, engine=None, engine_kwargs=None, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, "numpy.std : Equivalent method for Numpy array.\n", + template_see_also, create_section_header("Notes"), dedent( """ @@ -1716,8 +1716,8 @@ def std(self, ddof=1, *args, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, "numpy.var : Equivalent method for Numpy array.\n", + template_see_also, create_section_header("Notes"), dedent( """ @@ -1757,8 +1757,8 @@ def var(self, ddof=1, *args, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, "scipy.stats.skew : Third moment of a probability density.\n", + template_see_also, create_section_header("Notes"), "A minimum of three periods is required for the rolling calculation.\n", window_method="rolling", @@ -1812,8 +1812,8 @@ def sem(self, ddof=1, *args, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, "scipy.stats.kurtosis : Reference SciPy method.\n", + template_see_also, create_section_header("Notes"), "A minimum of four periods is required for the calculation.\n", create_section_header("Examples"), @@ -1824,9 +1824,9 @@ def sem(self, ddof=1, *args, **kwargs): >>> arr = [1, 2, 3, 4, 999] >>> import scipy.stats - >>> print(f"{scipy.stats.kurtosis(arr[:-1], bias=False):.6f}") + >>> print(f"{{scipy.stats.kurtosis(arr[:-1], bias=False):.6f}}") -1.200000 - >>> print(f"{scipy.stats.kurtosis(arr[1:], bias=False):.6f}") + >>> print(f"{{scipy.stats.kurtosis(arr[1:], bias=False):.6f}}") 3.999946 >>> s = pd.Series(arr) >>> s.rolling(4).kurt() @@ -1852,7 +1852,7 @@ def kurt(self, **kwargs): """ quantile : float Quantile to compute. 0 <= quantile <= 1. - interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'} + interpolation : {{'linear', 'lower', 'higher', 'midpoint', 'nearest'}} This optional parameter specifies the interpolation method to use, when the desired quantile lies between two data points `i` and `j`: @@ -1952,13 +1952,13 @@ def cov(self, other=None, pairwise=None, ddof=1, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, dedent( """ cov : Similar method to calculate covariance. numpy.corrcoef : NumPy Pearson's correlation calculation. """ ).replace("\n", "", 1), + template_see_also, create_section_header("Notes"), dedent( """ @@ -1993,9 +1993,9 @@ def cov(self, other=None, pairwise=None, ddof=1, **kwargs): >>> v2 = [3, 4, 4, 4, 8] >>> # numpy returns a 2X2 array, the correlation coefficient >>> # is the number at entry [0][1] - >>> print(f"{np.corrcoef(v1[:-1], v2[:-1])[0][1]:.6f}") + >>> print(f"{{np.corrcoef(v1[:-1], v2[:-1])[0][1]:.6f}}") 0.333333 - >>> print(f"{np.corrcoef(v1[1:], v2[1:])[0][1]:.6f}") + >>> print(f"{{np.corrcoef(v1[1:], v2[1:])[0][1]:.6f}}") 0.916949 >>> s1 = pd.Series(v1) >>> s2 = pd.Series(v2) From 1fcc4951433c655e49d7e53e2f189727623c0831 Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Thu, 21 Jan 2021 10:21:40 -0800 Subject: [PATCH 18/23] Truncate empty string at the end --- pandas/core/window/ewm.py | 8 ++++---- pandas/core/window/expanding.py | 6 +++--- pandas/core/window/rolling.py | 10 +++++----- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/pandas/core/window/ewm.py b/pandas/core/window/ewm.py index c3da2979957c1..ec328d1f284fe 100644 --- a/pandas/core/window/ewm.py +++ b/pandas/core/window/ewm.py @@ -358,7 +358,7 @@ def mean(self, *args, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, + template_see_also[:-1], window_method="ewm", aggregation_description="(exponential weighted moment) standard deviation", agg_method="std", @@ -392,7 +392,7 @@ def vol(self, bias: bool = False, *args, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, + template_see_also[:-1], window_method="ewm", aggregation_description="(exponential weighted moment) variance", agg_method="var", @@ -436,7 +436,7 @@ def var_func(values, begin, end, min_periods): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, + template_see_also[:-1], window_method="ewm", aggregation_description="(exponential weighted moment) sample covariance", agg_method="cov", @@ -495,7 +495,7 @@ def _get_cov(X, Y): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, + template_see_also[:-1], window_method="ewm", aggregation_description="(exponential weighted moment) sample correlation", agg_method="corr", diff --git a/pandas/core/window/expanding.py b/pandas/core/window/expanding.py index 11992557f78a5..5d7ceca81d676 100644 --- a/pandas/core/window/expanding.py +++ b/pandas/core/window/expanding.py @@ -157,7 +157,7 @@ def aggregate(self, func, *args, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, + template_see_also[:-1], window_method="expanding", aggregation_description="count of non NaN observations", agg_method="count", @@ -172,7 +172,7 @@ def count(self): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, + template_see_also[:-1], window_method="expanding", aggregation_description="custom aggregation function", agg_method="apply", @@ -512,7 +512,7 @@ def kurt(self, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, + template_see_also[:-1], window_method="expanding", aggregation_description="quantile", agg_method="quantile", diff --git a/pandas/core/window/rolling.py b/pandas/core/window/rolling.py index 372d5ff5edb9f..922e0cdcc4414 100644 --- a/pandas/core/window/rolling.py +++ b/pandas/core/window/rolling.py @@ -962,7 +962,7 @@ def sum(self, *args, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, + template_see_also[:-1], window_method="rolling", aggregation_description="weighted window mean", agg_method="mean", @@ -980,7 +980,7 @@ def mean(self, *args, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, + template_see_also[:-1], window_method="rolling", aggregation_description="weighted window variance", agg_method="var", @@ -999,7 +999,7 @@ def var(self, ddof: int = 1, *args, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, + template_see_also[:-1], window_method="rolling", aggregation_description="weighted window standard deviation", agg_method="std", @@ -1437,7 +1437,7 @@ def count(self): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, + template_see_also[:-1], window_method="rolling", aggregation_description="custom aggregation function", agg_method="apply", @@ -1923,7 +1923,7 @@ def quantile(self, quantile, interpolation="linear", **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, + template_see_also[:-1], window_method="rolling", aggregation_description="sample covariance", agg_method="cov", From edcb1c33987513957c1bd8f0bc70f94d01aaa675 Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Thu, 21 Jan 2021 13:19:41 -0800 Subject: [PATCH 19/23] Remove trailing extra newline --- pandas/core/window/ewm.py | 2 +- pandas/core/window/expanding.py | 2 +- pandas/core/window/rolling.py | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/pandas/core/window/ewm.py b/pandas/core/window/ewm.py index ec328d1f284fe..2948216e200de 100644 --- a/pandas/core/window/ewm.py +++ b/pandas/core/window/ewm.py @@ -320,7 +320,7 @@ def aggregate(self, func, *args, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, + template_see_also[:-1], window_method="ewm", aggregation_description="(exponential weighted moment) mean", agg_method="mean", diff --git a/pandas/core/window/expanding.py b/pandas/core/window/expanding.py index 5d7ceca81d676..f37e921080a9e 100644 --- a/pandas/core/window/expanding.py +++ b/pandas/core/window/expanding.py @@ -553,7 +553,7 @@ def quantile( create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, + template_see_also[:-1], window_method="expanding", aggregation_description="sample covariance", agg_method="cov", diff --git a/pandas/core/window/rolling.py b/pandas/core/window/rolling.py index 922e0cdcc4414..b2ff1f6b04c9d 100644 --- a/pandas/core/window/rolling.py +++ b/pandas/core/window/rolling.py @@ -945,7 +945,7 @@ def aggregate(self, func, *args, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - template_see_also, + template_see_also[:-1], window_method="rolling", aggregation_description="weighted window sum", agg_method="sum", From 69f993c945a39ebfaeafd60379f4be6f911c9e5c Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Thu, 21 Jan 2021 13:22:31 -0800 Subject: [PATCH 20/23] Fix example for doctest --- pandas/core/window/rolling.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/window/rolling.py b/pandas/core/window/rolling.py index b2ff1f6b04c9d..df239a4ad521f 100644 --- a/pandas/core/window/rolling.py +++ b/pandas/core/window/rolling.py @@ -910,7 +910,7 @@ def calc(x): """ Examples -------- - >>> df = pd.DataFrame({{"A": [1, 2, 3], "B": [4, 5, 6], "C": [7, 8, 9]}}) + >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6], "C": [7, 8, 9]}) >>> df A B C 0 1 4 7 @@ -1355,7 +1355,7 @@ def _raise_monotonic_error(self): """ Examples -------- - >>> df = pd.DataFrame({{"A": [1, 2, 3], "B": [4, 5, 6], "C": [7, 8, 9]}}) + >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6], "C": [7, 8, 9]}) >>> df A B C 0 1 4 7 From 2b95970b6178ece55edf0b6d05accfbf60555459 Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Thu, 21 Jan 2021 15:29:45 -0800 Subject: [PATCH 21/23] Fix another agg docstring --- pandas/core/window/rolling.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/window/rolling.py b/pandas/core/window/rolling.py index df239a4ad521f..7f103dea89259 100644 --- a/pandas/core/window/rolling.py +++ b/pandas/core/window/rolling.py @@ -1368,7 +1368,7 @@ def _raise_monotonic_error(self): 1 3.0 9.0 15.0 2 5.0 11.0 17.0 - >>> df.rolling(2).agg({{"A": "sum", "B": "min"}}) + >>> df.rolling(2).agg({"A": "sum", "B": "min"}) A B 0 NaN NaN 1 3.0 4.0 From 6efdfec0c804e8ddc0c0c0998cadf3d75504592b Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Mon, 25 Jan 2021 13:19:44 -0800 Subject: [PATCH 22/23] Add ddof param to docs --- pandas/core/window/rolling.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/pandas/core/window/rolling.py b/pandas/core/window/rolling.py index e18beaa33e3e1..f0a38193f89c9 100644 --- a/pandas/core/window/rolling.py +++ b/pandas/core/window/rolling.py @@ -1955,6 +1955,9 @@ def cov(self, other=None, pairwise=None, ddof=1, **kwargs): output will be a MultiIndexed DataFrame in the case of DataFrame inputs. In the case of missing elements, only complete pairwise observations will be used. + ddof : int, default 1 + Delta Degrees of Freedom. The divisor used in calculations + is ``N - ddof``, where ``N`` represents the number of elements. """ ).replace("\n", "", 1), kwargs_compat, From 4fe4c650df6941c3a8bd7c997c0fef74ceeef0a6 Mon Sep 17 00:00:00 2001 From: Matthew Roeschke Date: Tue, 26 Jan 2021 12:20:58 -0800 Subject: [PATCH 23/23] Fix NumPy and SciPy references --- pandas/core/window/doc.py | 6 +++--- pandas/core/window/expanding.py | 4 ++-- pandas/core/window/rolling.py | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/pandas/core/window/doc.py b/pandas/core/window/doc.py index 343156832d0ae..7e3f7895c0125 100644 --- a/pandas/core/window/doc.py +++ b/pandas/core/window/doc.py @@ -32,21 +32,21 @@ def create_section_header(header: str) -> str: args_compat = dedent( """ *args - For Numpy compatibility and will not have an effect on the result.\n + For NumPy compatibility and will not have an effect on the result.\n """ ).replace("\n", "", 1) kwargs_compat = dedent( """ **kwargs - For Numpy compatibility and will not have an effect on the result.\n + For NumPy compatibility and will not have an effect on the result.\n """ ).replace("\n", "", 1) kwargs_scipy = dedent( """ **kwargs - Keyword arguments to configure the ``Scipy`` weighted window type.\n + Keyword arguments to configure the ``SciPy`` weighted window type.\n """ ).replace("\n", "", 1) diff --git a/pandas/core/window/expanding.py b/pandas/core/window/expanding.py index db8e5b3bf768d..f91441de41448 100644 --- a/pandas/core/window/expanding.py +++ b/pandas/core/window/expanding.py @@ -285,7 +285,7 @@ def median(self, engine=None, engine_kwargs=None, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - "numpy.std : Equivalent method for Numpy array.\n", + "numpy.std : Equivalent method for NumPy array.\n", template_see_also, create_section_header("Notes"), dedent( @@ -335,7 +335,7 @@ def std(self, ddof: int = 1, *args, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - "numpy.var : Equivalent method for Numpy array.\n", + "numpy.var : Equivalent method for NumPy array.\n", template_see_also, create_section_header("Notes"), dedent( diff --git a/pandas/core/window/rolling.py b/pandas/core/window/rolling.py index f0a38193f89c9..06302fd49feb9 100644 --- a/pandas/core/window/rolling.py +++ b/pandas/core/window/rolling.py @@ -1676,7 +1676,7 @@ def median(self, engine=None, engine_kwargs=None, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - "numpy.std : Equivalent method for Numpy array.\n", + "numpy.std : Equivalent method for NumPy array.\n", template_see_also, create_section_header("Notes"), dedent( @@ -1725,7 +1725,7 @@ def std(self, ddof=1, *args, **kwargs): create_section_header("Returns"), template_returns, create_section_header("See Also"), - "numpy.var : Equivalent method for Numpy array.\n", + "numpy.var : Equivalent method for NumPy array.\n", template_see_also, create_section_header("Notes"), dedent(