diff --git a/spec/API_specification/dataframe_api/column_object.py b/spec/API_specification/dataframe_api/column_object.py index 78a12adb..84b2e692 100644 --- a/spec/API_specification/dataframe_api/column_object.py +++ b/spec/API_specification/dataframe_api/column_object.py @@ -469,20 +469,47 @@ def mean(self, *, skip_nulls: bool = True) -> Scalar: dtypes. """ - def std(self, *, skip_nulls: bool = True) -> Scalar: + def std(self, *, correction: int | float = 1, skip_nulls: bool = True) -> Scalar: """ Reduction returns a scalar. Must be supported for numerical and datetime data types. Returns a float for numerical data types, and datetime (with the appropriate timedelta format string) for datetime dtypes. - """ - def var(self, *, skip_nulls: bool = True) -> Scalar: + Parameters + ---------- + correction + Degrees of freedom adjustment. Setting this parameter to a value other + than ``0`` has the effect of adjusting the divisor during the + calculation of the standard deviation according to ``N-correction``, + where ``N`` corresponds to the total number of elements over which + the standard deviation is computed. When computing the standard + deviation of a population, setting this parameter to ``0`` is the + standard choice (i.e., the provided column contains data + constituting an entire population). When computing the corrected + sample standard deviation, setting this parameter to ``1`` is the + standard choice (i.e., the provided column contains data sampled + from a larger population; this is commonly referred to as Bessel's + correction). Fractional (float) values are allowed. Default: ``1``. + skip_nulls + Whether to skip null values. + """ + + def var(self, *, correction: int | float = 1, skip_nulls: bool = True) -> Scalar: """ Reduction returns a scalar. Must be supported for numerical and datetime data types. Returns a float for numerical data types, and datetime (with the appropriate timedelta format string) for datetime dtypes. + + Parameters + ---------- + correction + Correction to apply to the result. For example, ``0`` for sample + standard deviation and ``1`` for population standard deviation. + See `Column.std` for a more detailed description. + skip_nulls + Whether to skip null values. """ def is_null(self) -> Column: diff --git a/spec/API_specification/dataframe_api/dataframe_object.py b/spec/API_specification/dataframe_api/dataframe_object.py index 6dc2c787..bbec16f8 100644 --- a/spec/API_specification/dataframe_api/dataframe_object.py +++ b/spec/API_specification/dataframe_api/dataframe_object.py @@ -684,15 +684,33 @@ def mean(self, *, skip_nulls: bool = True) -> DataFrame: """ ... - def std(self, *, skip_nulls: bool = True) -> DataFrame: + def std(self, *, correction: int | float = 1, skip_nulls: bool = True) -> DataFrame: """ Reduction returns a 1-row DataFrame. + + Parameters + ---------- + correction + Correction to apply to the result. For example, ``0`` for sample + standard deviation and ``1`` for population standard deviation. + See `Column.std` for a more detailed description. + skip_nulls + Whether to skip null values. """ ... - def var(self, *, skip_nulls: bool = True) -> DataFrame: + def var(self, *, correction: int | float = 1, skip_nulls: bool = True) -> DataFrame: """ Reduction returns a 1-row DataFrame. + + Parameters + ---------- + correction + Correction to apply to the result. For example, ``0`` for sample + standard deviation and ``1`` for population standard deviation. + See `Column.std` for a more detailed description. + skip_nulls + Whether to skip null values. """ ... diff --git a/spec/API_specification/dataframe_api/groupby_object.py b/spec/API_specification/dataframe_api/groupby_object.py index cfc7bc62..11a7b102 100644 --- a/spec/API_specification/dataframe_api/groupby_object.py +++ b/spec/API_specification/dataframe_api/groupby_object.py @@ -41,10 +41,10 @@ def median(self, *, skip_nulls: bool = True) -> "DataFrame": def mean(self, *, skip_nulls: bool = True) -> "DataFrame": ... - def std(self, *, skip_nulls: bool = True) -> "DataFrame": + def std(self, *, correction: int | float = 1, skip_nulls: bool = True) -> "DataFrame": ... - def var(self, *, skip_nulls: bool = True) -> "DataFrame": + def var(self, *, correction: int | float = 1, skip_nulls: bool = True) -> "DataFrame": ... def size(self) -> "DataFrame":