diff --git a/ci/code_checks.sh b/ci/code_checks.sh index f93e87074d650..bae50bc985573 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -228,7 +228,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then -i "pandas.Series.to_markdown SA01" \ -i "pandas.Series.to_string SA01" \ -i "pandas.Series.update PR07,SA01" \ - -i "pandas.Series.var PR01,RT03,SA01" \ -i "pandas.Timedelta PR07,SA01" \ -i "pandas.Timedelta.as_unit SA01" \ -i "pandas.Timedelta.asm8 SA01" \ diff --git a/pandas/core/series.py b/pandas/core/series.py index 97a53650ec5ff..cd306cc5c0dab 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -6720,7 +6720,6 @@ def sem( ) @deprecate_nonkeyword_arguments(version="3.0", allowed_args=["self"], name="var") - @doc(make_doc("var", ndim=1)) def var( self, axis: Axis | None = None, @@ -6729,6 +6728,75 @@ def var( numeric_only: bool = False, **kwargs, ): + """ + Return unbiased variance over requested axis. + + Normalized by N-1 by default. This can be changed using the ddof argument. + + Parameters + ---------- + axis : {index (0)} + For `Series` this parameter is unused and defaults to 0. + + .. warning:: + + The behavior of DataFrame.var with ``axis=None`` is deprecated, + in a future version this will reduce over both axes and return a scalar + To retain the old behavior, pass axis=0 (or do not pass axis). + + skipna : bool, default True + Exclude NA/null values. If an entire row/column is NA, the result + will be NA. + ddof : int, default 1 + Delta Degrees of Freedom. The divisor used in calculations is N - ddof, + where N represents the number of elements. + numeric_only : bool, default False + Include only float, int, boolean columns. Not implemented for Series. + **kwargs : + Additional keywords passed. + + Returns + ------- + scalar or Series (if level specified) + Unbiased variance over requested axis. + + See Also + -------- + numpy.var : Equivalent function in NumPy. + Series.std : Returns the standard deviation of the Series. + DataFrame.var : Returns the variance of the DataFrame. + DataFrame.std : Return standard deviation of the values over + the requested axis. + + Examples + -------- + >>> df = pd.DataFrame( + ... { + ... "person_id": [0, 1, 2, 3], + ... "age": [21, 25, 62, 43], + ... "height": [1.61, 1.87, 1.49, 2.01], + ... } + ... ).set_index("person_id") + >>> df + age height + person_id + 0 21 1.61 + 1 25 1.87 + 2 62 1.49 + 3 43 2.01 + + >>> df.var() + age 352.916667 + height 0.056367 + dtype: float64 + + Alternatively, ``ddof=0`` can be set to normalize by N instead of N-1: + + >>> df.var(ddof=0) + age 264.687500 + height 0.042275 + dtype: float64 + """ return NDFrame.var( self, axis=axis,