Add correction keyword argument to dpnp.std and dpnp.var (#2300)

The PR proposes to add `correction` keyword argument to statistics
functions, assuming `dpnp.std`, `dpnp.var`, `dpnp.nanstd`, `dpnp.nanvar`
functions and `dpnp.ndarray.std`, `dpnp.ndarray.var` methods.

The keyword is mandated according to python array API. The corresponding
muted tests are enabled in python array API compliance scope.

Also this PR adds improvements to the docstrings of functions from
statistics interface.

Author: antonwolfy

.github/workflows/array-api-skips.txt

@@ -29,7 +29,3 @@ array_api_tests/test_operators_and_elementwise_functions.py::test_clip
 # unexpected result is returned - unmute when dpctl-1986 is resolved
 array_api_tests/test_operators_and_elementwise_functions.py::test_asin
 array_api_tests/test_operators_and_elementwise_functions.py::test_asinh
-
-# missing 'correction' keyword argument
-array_api_tests/test_signatures.py::test_func_signature[std]
-array_api_tests/test_signatures.py::test_func_signature[var]

dpnp/dpnp_array.py

@@ -1732,6 +1732,7 @@ def std(
         *,
         where=True,
         mean=None,
+        correction=None,
     ):
         """
         Returns the standard deviation of the array elements, along given axis.
@@ -1741,7 +1742,15 @@ def std(
         """
 
         return dpnp.std(
-            self, axis, dtype, out, ddof, keepdims, where=where, mean=mean
+            self,
+            axis,
+            dtype,
+            out,
+            ddof,
+            keepdims,
+            where=where,
+            mean=mean,
+            correction=correction,
         )
 
     @property
@@ -1942,6 +1951,7 @@ def var(
         *,
         where=True,
         mean=None,
+        correction=None,
     ):
         """
         Returns the variance of the array elements, along given axis.
@@ -1951,7 +1961,15 @@ def var(
         """
 
         return dpnp.var(
-            self, axis, dtype, out, ddof, keepdims, where=where, mean=mean
+            self,
+            axis,
+            dtype,
+            out,
+            ddof,
+            keepdims,
+            where=where,
+            mean=mean,
+            correction=correction,
         )
 
 

dpnp/dpnp_iface_nanfunctions.py

@@ -113,15 +113,18 @@ def nanargmax(a, axis=None, out=None, *, keepdims=False):
         Input array.
     axis : {None, int}, optional
         Axis along which to operate. By default flattened input is used.
+
         Default: ``None``.
     out : {None, dpnp.ndarray, usm_ndarray}, optional
         If provided, the result will be inserted into this array. It should be
         of the appropriate shape and dtype.
+
         Default: ``None``.
     keepdims : {None, bool}, optional
         If this is set to ``True``, the axes which are reduced are left in the
         result as dimensions with size one. With this option, the result will
         broadcast correctly against the array.
+
         Default: ``False``.
 
     Returns
@@ -184,15 +187,18 @@ def nanargmin(a, axis=None, out=None, *, keepdims=False):
         Input array.
     axis : {None, int}, optional
         Axis along which to operate. By default flattened input is used.
+
         Default: ``None``.
     out : {None, dpnp.ndarray, usm_ndarray}, optional
         If provided, the result will be inserted into this array. It should be
         of the appropriate shape and dtype.
+
         Default: ``None``.
     keepdims : {None, bool}, optional
         If this is set to ``True``, the axes which are reduced are left in the
         result as dimensions with size one. With this option, the result will
         broadcast correctly against the array.
+
         Default: ``False``.
 
     Returns
@@ -257,19 +263,24 @@ def nancumprod(a, axis=None, dtype=None, out=None):
         Input array.
     axis : {None, int}, optional
         Axis along which the cumulative product is computed. The default
-        (``None``) is to compute the cumulative product over the flattened
-        array.
+        is to compute the cumulative product over the flattened array.
+
+        Default: ``None``.
     dtype : {None, dtype}, optional
         Type of the returned array and of the accumulator in which the elements
         are summed. If `dtype` is not specified, it defaults to the dtype of
         `a`, unless `a` has an integer dtype with a precision less than that of
         the default platform integer. In that case, the default platform
         integer is used.
+
+        Default: ``None``.
     out : {None, dpnp.ndarray, usm_ndarray}, optional
         Alternative output array in which to place the result. It must have the
         same shape and buffer length as the expected output but the type will
         be cast if necessary.
 
+        Default: ``None``.
+
     Returns
     -------
     out : dpnp.ndarray
@@ -321,19 +332,25 @@ def nancumsum(a, axis=None, dtype=None, out=None):
     a : {dpnp.ndarray, usm_ndarray}
         Input array.
     axis : {None, int}, optional
-        Axis along which the cumulative sum is computed. The default (``None``)
-        is to compute the cumulative sum over the flattened array.
+        Axis along which the cumulative sum is computed. The default is to
+        compute the cumulative sum over the flattened array.
+
+        Default: ``None``.
     dtype : {None, dtype}, optional
         Type of the returned array and of the accumulator in which the elements
         are summed. If `dtype` is not specified, it defaults to the dtype of
         `a`, unless `a` has an integer dtype with a precision less than that of
         the default platform integer. In that case, the default platform
         integer is used.
+
+        Default: ``None``.
     out : {None, dpnp.ndarray, usm_ndarray}, optional
         Alternative output array in which to place the result. It must have the
         same shape and buffer length as the expected output but the type will
         be cast if necessary.
 
+        Default: ``None``.
+
     Returns
     -------
     out : dpnp.ndarray
@@ -386,15 +403,19 @@ def nanmax(a, axis=None, out=None, keepdims=False, initial=None, where=True):
         Axis or axes along which maximum values must be computed. By default,
         the maximum value must be computed over the entire array. If a tuple
         of integers, maximum values must be computed over multiple axes.
+
         Default: ``None``.
     out : {None, dpnp.ndarray, usm_ndarray}, optional
         If provided, the result will be inserted into this array. It should
         be of the appropriate shape and dtype.
+
+        Default: ``None``.
     keepdims : {None, bool}, optional
         If ``True``, the reduced axes (dimensions) must be included in the
         result as singleton dimensions, and, accordingly, the result must be
         compatible with the input array. Otherwise, if ``False``, the reduced
         axes (dimensions) must not be included in the result.
+
         Default: ``False``.
 
     Returns
@@ -476,6 +497,7 @@ def nanmean(a, axis=None, dtype=None, out=None, keepdims=False, *, where=True):
         Axis or axes along which the arithmetic means must be computed. If
         a tuple of unique integers, the means are computed over multiple
         axes. If ``None``, the mean is computed over the entire array.
+
         Default: ``None``.
     dtype : {None, dtype}, optional
         Type to use in computing the mean. By default, if `a` has a
@@ -484,16 +506,22 @@ def nanmean(a, axis=None, dtype=None, out=None, keepdims=False, *, where=True):
         If `a` has a boolean or integral data type, the returned array
         will have the default floating point data type for the device
         where input array `a` is allocated.
+
+        Default: ``None``.
     out : {None, dpnp.ndarray, usm_ndarray}, optional
         Alternative output array in which to place the result. It must have
         the same shape as the expected output but the type (of the calculated
-        values) will be cast if necessary. Default: ``None``.
+        values) will be cast if necessary.
+
+        Default: ``None``.
     keepdims : {None, bool}, optional
         If ``True``, the reduced axes (dimensions) are included in the result
         as singleton dimensions, so that the returned array remains
         compatible with the input array according to Array Broadcasting
         rules. Otherwise, if ``False``, the reduced axes are not included in
-        the returned array. Default: ``False``.
+        the returned array.
+
+        Default: ``False``.
 
     Returns
     -------
@@ -588,25 +616,29 @@ def nanmedian(a, axis=None, out=None, overwrite_input=False, keepdims=False):
         the array. If a sequence of axes, the array is first flattened along
         the given axes, then the median is computed along the resulting
         flattened axis.
+
         Default: ``None``.
     out : {None, dpnp.ndarray, usm_ndarray}, optional
         Alternative output array in which to place the result. It must have
         the same shape as the expected output but the type (of the calculated
         values) will be cast if necessary.
+
         Default: ``None``.
     overwrite_input : bool, optional
        If ``True``, then allow use of memory of input array `a` for
        calculations. The input array will be modified by the call to
        :obj:`dpnp.nanmedian`. This will save memory when you do not need to
        preserve the contents of the input array. Treat the input as undefined,
        but it will probably be fully or partially sorted.
+
        Default: ``False``.
     keepdims : bool, optional
         If ``True``, the reduced axes (dimensions) are included in the result
         as singleton dimensions, so that the returned array remains
         compatible with the input array according to Array Broadcasting
         rules. Otherwise, if ``False``, the reduced axes are not included in
         the returned array.
+
         Default: ``False``.
 
     Returns
@@ -687,15 +719,19 @@ def nanmin(a, axis=None, out=None, keepdims=False, initial=None, where=True):
         Axis or axes along which minimum values must be computed. By default,
         the minimum value must be computed over the entire array. If a tuple
         of integers, minimum values must be computed over multiple axes.
+
         Default: ``None``.
     out : {None, dpnp.ndarray, usm_ndarray}, optional
         If provided, the result will be inserted into this array. It should
         be of the appropriate shape and dtype.
+
+        Default: ``None``.
     keepdims : {None, bool}, optional
         If ``True``, the reduced axes (dimensions) must be included in the
         result as singleton dimensions, and, accordingly, the result must be
         compatible with the input array. Otherwise, if ``False``, the reduced
         axes (dimensions) must not be included in the result.
+
         Default: ``False``.
 
     Returns
@@ -785,6 +821,7 @@ def nanprod(
     axis : {None, int or tuple of ints}, optional
         Axis or axes along which the product is computed. The default is to
         compute the product of the flattened array.
+
         Default: ``None``.
     dtype : {None, dtype}, optional
         The type of the returned array and of the accumulator in which the
@@ -793,17 +830,20 @@ def nanprod(
         the platform (u)intp. In that case, the default will be either (u)int32
         or (u)int64 depending on whether the platform is 32 or 64 bits. For
         inexact inputs, dtype must be inexact.
+
         Default: ``None``.
     out : {None, dpnp.ndarray, usm_ndarray}, optional
         Alternate output array in which to place the result. If provided, it
         must have the same shape as the expected output, but the type will be
         cast if necessary. The casting of NaN to integer
         can yield unexpected results.
+
         Default: ``None``.
     keepdims : {None, bool}, optional
         If ``True``, the axes which are reduced are left in the result as
         dimensions with size one. With this option, the result will broadcast
         correctly against the original `a`.
+
         Default: ``False``.
 
     Returns
@@ -878,6 +918,7 @@ def nansum(
     axis : {None, int or tuple of ints}, optional
         Axis or axes along which the sum is computed. The default is to compute
         the sum of the flattened array.
+
         Default: ``None``.
     dtype : {None, dtype}, optional
         The type of the returned array and of the accumulator in which the
@@ -886,17 +927,20 @@ def nansum(
         (u)intp. In that case, the default will be either (u)int32 or (u)int64
         depending on whether the platform is 32 or 64 bits. For inexact inputs,
         dtype must be inexact.
+
         Default: ``None``.
     out : {None, dpnp.ndarray, usm_ndarray}, optional
         Alternate output array in which to place the result. If provided, it
         must have the same shape as the expected output, but the type will be
         cast if necessary. The casting of NaN to integer can yield unexpected
         results.
+
         Default: ``None``.
     keepdims : {None, bool}, optional
         If this is set to ``True``, the axes which are reduced are left in the
         result as dimensions with size one. With this option, the result will
         broadcast correctly against the original `a`.
+
         Default: ``False``.
 
     Returns
@@ -966,6 +1010,7 @@ def nanstd(
     *,
     where=True,
     mean=None,
+    correction=None,
 ):
     """
     Compute the standard deviation along the specified axis,
@@ -1018,6 +1063,12 @@ def nanstd(
 
         Default: ``None``.
 
+    correction : {None, int, float}, optional
+        Array API compatible name for the `ddof` parameter. Only one of them
+        can be provided at the same time.
+
+        Default: ``None``.
+
     Returns
     -------
     out : dpnp.ndarray
@@ -1094,6 +1145,7 @@ def nanstd(
         keepdims=keepdims,
         where=where,
         mean=mean,
+        correction=correction,
     )
     return dpnp.sqrt(res, out=res)
 
@@ -1108,6 +1160,7 @@ def nanvar(
     *,
     where=True,
     mean=None,
+    correction=None,
 ):
     """
     Compute the variance along the specified axis, while ignoring NaNs.
@@ -1158,6 +1211,12 @@ def nanvar(
 
         Default: ``None``.
 
+    correction : {None, int, float}, optional
+        Array API compatible name for the `ddof` parameter. Only one of them
+        can be provided at the same time.
+
+        Default: ``None``.
+
     Returns
     -------
     out : dpnp.ndarray
@@ -1231,6 +1290,7 @@ def nanvar(
             ddof=ddof,
             keepdims=keepdims,
             where=where,
+            correction=correction,
         )
 
     if dtype is not None:
@@ -1243,6 +1303,13 @@ def nanvar(
         if not dpnp.issubdtype(out.dtype, dpnp.inexact):
             raise TypeError("If input is inexact, then out must be inexact.")
 
+    if correction is not None:
+        if ddof != 0:
+            raise ValueError(
+                "ddof and correction can't be provided simultaneously."
+            )
+        ddof = correction
+
     # Compute mean
     cnt = dpnp.sum(
         ~mask, axis=axis, dtype=dpnp.intp, keepdims=True, where=where