Add correction keyword to std/var functions

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

@@ -966,6 +966,7 @@ def nanstd(
     *,
     where=True,
     mean=None,
+    correction=None,
 ):
     """
     Compute the standard deviation along the specified axis,
@@ -1018,6 +1019,12 @@ def nanstd(
 
         Default: ``None``.
 
+    correction : {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 +1101,7 @@ def nanstd(
         keepdims=keepdims,
         where=where,
         mean=mean,
+        correction=correction,
     )
     return dpnp.sqrt(res, out=res)
 
@@ -1108,6 +1116,7 @@ def nanvar(
     *,
     where=True,
     mean=None,
+    correction=None,
 ):
     """
     Compute the variance along the specified axis, while ignoring NaNs.
@@ -1158,6 +1167,12 @@ def nanvar(
 
         Default: ``None``.
 
+    correction : {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 +1246,7 @@ def nanvar(
             ddof=ddof,
             keepdims=keepdims,
             where=where,
+            correction=correction,
         )
 
     if dtype is not None:
@@ -1243,6 +1259,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

dpnp/dpnp_iface_statistics.py

@@ -1201,6 +1201,7 @@ def std(
     *,
     where=True,
     mean=None,
+    correction=None,
 ):
     r"""
     Compute the standard deviation along the specified axis.
@@ -1253,6 +1254,12 @@ def std(
 
         Default: ``None``.
 
+    correction : {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
@@ -1344,6 +1351,13 @@ def std(
     dpnp.check_supported_arrays_type(a)
     dpnp.check_limitations(where=where)
 
+    if correction is not None:
+        if ddof != 0:
+            raise ValueError(
+                "ddof and correction can't be provided simultaneously."
+            )
+        ddof = correction
+
     if not isinstance(ddof, (int, float)):
         raise TypeError(
             f"An integer or float is required, but got {type(ddof)}"
@@ -1382,6 +1396,7 @@ def var(
     *,
     where=True,
     mean=None,
+    correction=None,
 ):
     r"""
     Compute the variance along the specified axis.
@@ -1433,6 +1448,12 @@ def var(
 
         Default: ``None``.
 
+    correction : {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
@@ -1518,6 +1539,13 @@ def var(
     dpnp.check_supported_arrays_type(a)
     dpnp.check_limitations(where=where)
 
+    if correction is not None:
+        if ddof != 0:
+            raise ValueError(
+                "ddof and correction can't be provided simultaneously."
+            )
+        ddof = correction
+
     if not isinstance(ddof, (int, float)):
         raise TypeError(
             f"An integer or float is required, but got {type(ddof)}"

dpnp/tests/test_nanfunctions.py

@@ -9,6 +9,7 @@
     assert_array_equal,
     assert_equal,
     assert_raises,
+    assert_raises_regex,
 )
 
 import dpnp
@@ -24,6 +25,7 @@
     numpy_version,
 )
 from .third_party.cupy import testing
+from .third_party.cupy.testing import with_requires
 
 
 class TestNanArgmaxNanArgmin:
@@ -750,6 +752,28 @@ def test_mean_keyword(self, dtype, axis, keepdims):
         )
         assert_dtype_allclose(result, expected)
 
+    @with_requires("numpy>=2.0")
+    def test_correction(self):
+        a = numpy.array([127, 39, 93, 87, 46])
+        ia = dpnp.array(a)
+
+        expected = getattr(numpy, self.func)(a, correction=0.5)
+        result = getattr(dpnp, self.func)(ia, correction=0.5)
+        assert_dtype_allclose(result, expected)
+
+    @with_requires("numpy>=2.0")
+    @pytest.mark.parametrize("xp", [dpnp, numpy])
+    def test_both_ddof_correction_are_set(self, xp):
+        a = xp.array(5)
+
+        err_msg = "ddof and correction can't be provided simultaneously."
+
+        with assert_raises_regex(ValueError, err_msg):
+            getattr(xp, self.func)(a, ddof=0.5, correction=0.5)
+
+        with assert_raises_regex(ValueError, err_msg):
+            getattr(xp, self.func)(a, ddof=1, correction=0)
+
     def test_error(self):
         ia = dpnp.arange(5, dtype=dpnp.float32)
         ia[0] = dpnp.nan

dpnp/tests/test_statistics.py

@@ -5,6 +5,7 @@
 from numpy.testing import (
     assert_allclose,
     assert_array_equal,
+    assert_raises_regex,
 )
 
 import dpnp
@@ -763,6 +764,28 @@ def test_scalar(self):
         result = getattr(ia, self.func)()
         assert_dtype_allclose(result, expected)
 
+    @with_requires("numpy>=2.0")
+    def test_correction(self):
+        a = numpy.array([1, -1, 1, -1])
+        ia = dpnp.array(a)
+
+        expected = getattr(a, self.func)(correction=1)
+        result = getattr(ia, self.func)(correction=1)
+        assert_dtype_allclose(result, expected)
+
+    @with_requires("numpy>=2.0")
+    @pytest.mark.parametrize("xp", [dpnp, numpy])
+    def test_both_ddof_correction_are_set(self, xp):
+        a = xp.array([1, -1, 1, -1])
+
+        err_msg = "ddof and correction can't be provided simultaneously."
+
+        with assert_raises_regex(ValueError, err_msg):
+            getattr(xp, self.func)(a, ddof=1, correction=0)
+
+        with assert_raises_regex(ValueError, err_msg):
+            getattr(xp, self.func)(a, ddof=1, correction=1)
+
     def test_error(self):
         ia = dpnp.arange(5)
         # where keyword is not implemented

pyproject.toml

@@ -18,7 +18,7 @@ exclude-protected = ["_create_from_usm_ndarray"]
 max-args = 11
 max-positional-arguments = 9
 max-locals = 30
-max-branches = 15
+max-branches = 16
 max-returns = 8
 
 [tool.pylint.format]