8000 API: Introduce correction argument for np.var and np.std · numpy/numpy@a4aa82f · GitHub
[go: up one dir, main page]
Skip to content

Commit a4aa82f

Browse files
mtsokolmtsokol
committed
API: Introduce correction argument for np.var and np.std
1 parent b3d71f7 commit a4aa82f

File tree

5 files changed

+86
-19
lines changed

5 files changed

+86
-19
lines changed

‎doc/release/upcoming_changes/25169.new_feature.rst

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
``correction`` argument for `numpy.var` and `numpy.std`
2+
-------------------------------------------------------
3+
4+
``correction`` argument was added to `numpy.var` and `numpy.std`,
5+
which is an Array API compatible alias for ``ddof``.
6+
As both arguments serve the same purpose only one of them can be
7+
provided at the same time.

‎doc/source/reference/array_api.rst

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -186,10 +186,6 @@ functions to include additional keyword arguments from those required.
186186
- The definitions of ``rtol`` and ``rcond`` are the same, but their
187187
default values differ, making this **breaking**. See
188188
:ref:`array_api-linear-algebra-differences`.
189-
* - ``std`` and ``var``
190-
- ``correction``
191-
- ``ddof``
192-
-
193189
* - ``reshape``
194190
- ``shape``
195191
- ``newshape``

‎numpy/_core/fromnumeric.py

Lines changed: 33 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3513,13 +3513,13 @@ def mean(a, axis=None, dtype=None, out=None, keepdims=np._NoValue, *,
35133513

35143514

35153515
def _std_dispatcher(a, axis=None, dtype=None, out=None, ddof=None,
3516-
keepdims=None, *, where=None, mean=None):
3516+
keepdims=None, *, where=None, mean=None, correction=None):
35173517
return (a, where, out, mean)
35183518

35193519

35203520
@array_function_dispatch(_std_dispatcher)
35213521
def std(a, axis=None, dtype=None, out=None, ddof=0, keepdims=np._NoValue, *,
3522-
where=np._NoValue, mean=np._NoValue):
3522+
where=np._NoValue, mean=np._NoValue, correction=0):
35233523
"""
35243524
Compute the standard deviation along the specified axis.
35253525
@@ -3567,14 +3567,20 @@ def std(a, axis=None, dtype=None, out=None, ddof=0, keepdims=np._NoValue, *,
35673567
35683568
.. versionadded:: 1.20.0
35693569
3570-
mean : array like, optional
3570+
mean : array_like, optional
35713571
Provide the mean to prevent its recalculation. The mean should have
35723572
a shape as if it was calculated with ``keepdims=True``.
35733573
The axis for the calculation of the mean should be the same as used in
35743574
the call to this std function.
35753575
35763576
.. versionadded:: 1.26.0
35773577
3578+
correction : int, optional
3579+
Array API compatible name for the ``ddof`` parameter. Only one of them
3580+
can be provided at the same time.
3581+
3582+
.. versionadded:: 2.0.0
3583+
35783584
Returns
35793585
-------
35803586
standard_deviation : ndarray, see dtype parameter above.
@@ -3666,6 +3672,14 @@ def std(a, axis=None, dtype=None, out=None, ddof=0, keepdims=np._NoValue, *,
36663672
if mean is not np._NoValue:
36673673
kwargs['mean'] = mean
36683674

3675+
if correction != 0:
3676+
if ddof != 0:
3677+
raise ValueError(
3678+
"ddof and correction can't be provided simultaneously."
3679+
)
3680+
else:
3681+
ddof = correction
3682+
36693683
if type(a) is not mu.ndarray:
36703684
try:
36713685
std = a.std
@@ -3679,13 +3693,13 @@ def std(a, axis=None, dtype=None, out=None, ddof=0, keepdims=np._NoValue, *,
36793693

36803694

36813695
def _var_dispatcher(a, axis=None, dtype=None, out=None, ddof=None,
3682-
keepdims=None, *, where=None, mean=None):
3696+
keepdims=None, *, where=None, mean=None, correction=None):
36833697
return (a, where, out, mean)
36843698

36853699

36863700
@array_function_dispatch(_var_dispatcher)
36873701
def var(a, axis=None, dtype=None, out=None, ddof=0, keepdims=np._NoValue, *,
3688-
where=np._NoValue, mean=np._NoValue):
3702+
where=np._NoValue, mean=np._NoValue, correction=0):
36893703
"""
36903704
Compute the variance along the specified axis.
36913705
@@ -3742,6 +3756,12 @@ def var(a, axis=None, dtype=None, out=None, ddof=0, keepdims=np._NoValue, *,
37423756
37433757
.. versionadded:: 1.26.0
37443758
3759+
correction : int, optional
3760+
Array API compatible name for the ``ddof`` parameter. Only one of them
3761+
can be provided at the same time.
3762+
3763+
.. versionadded:: 2.0.0
3764+
37453765
Returns
37463766
-------
37473767
variance : ndarray, see dtype parameter above
@@ -3832,6 +3852,14 @@ def var(a, axis=None, dtype=None, out=None, ddof=0, keepdims=np._NoValue, *,
38323852
if mean is not np._NoValue:
38333853
kwargs['mean'] = mean
38343854

3855+
if correction != 0:
3856+
if ddof != 0:
3857+
raise ValueError(
3858+
"ddof and correction can't be provided simultaneously."
3859+
)
3860+
else:
3861+
ddof = correction
3862+
38353863
if type(a) is not mu.ndarray:
38363864
try:
38373865
var = a.var

‎numpy/_core/fromnumeric.pyi

Lines changed: 30 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -941,54 +941,64 @@ def std(
941941
axis: None = ...,
942942
dtype: None = ...,
943943
out: None = ...,
944-
ddof: float = ...,
944+
ddof: int = ...,
945945
keepdims: Literal[False] = ...,
946946
*,
947947
where: _ArrayLikeBool_co = ...,
948+
mean: _ArrayLikeComplex_co = ...,
949+
correction: int = ...,
948950
) -> floating[Any]: ...
949951
@overload
950952
def std(
951953
a: _ArrayLikeComplex_co | _ArrayLikeObject_co,
952954
axis: None | _ShapeLike = ...,
953955
dtype: None = ...,
954956
out: None = ...,
955-
ddof: float = ...,
957+
ddof: int = ...,
956958
keepdims: bool = ...,
957959
*,
958960
where: _ArrayLikeBool_co = ...,
961+
mean: _ArrayLikeComplex_co | _ArrayLikeObject_co = ...,
962+
correction: int = ...,
959963
) -> Any: ...
960964
@overload
961965
def std(
962966
a: _ArrayLikeComplex_co | _ArrayLikeObject_co,
963967
axis: None = ...,
964968
dtype: _DTypeLike[_SCT] = ...,
965969
out: None = ...,
966-
ddof: float = ...,
970+
ddof: int = ...,
967971
keepdims: Literal[False] = ...,
968972
*,
969973
where: _ArrayLikeBool_co = ...,
974+
mean: _ArrayLikeComplex_co | _ArrayLikeObject_co = ...,
975+
correction: int = ...,
970976
) -> _SCT: ...
971977
@overload
972978
def std(
973979
a: _ArrayLikeComplex_co | _ArrayLikeObject_co,
974980
axis: None | _ShapeLike = ...,
975981
dtype: DTypeLike = ...,
976982
out: None = ...,
977-
ddof: float = ...,
983+
ddof: int = ...,
978984
keepdims: bool = ...,
979985
*,
980986
where: _ArrayLikeBool_co = ...,
987+
mean: _ArrayLikeComplex_co | _ArrayLikeObject_co = ...,
988+
correction: int = ...,
981989
) -> Any: ...
982990
@overload
983991
def std(
984992
a: _ArrayLikeComplex_co | _ArrayLikeObject_co,
985993
axis: None | _ShapeLike = ...,
986994
dtype: DTypeLike = ...,
987995
out: _ArrayType = ...,
988-
ddof: float = ...,
996+
ddof: int = ...,
989997
keepdims: bool = ...,
990998
*,
991999
where: _ArrayLikeBool_co = ...,
1000+
mean: _ArrayLikeComplex_co | _ArrayLikeObject_co = ...,
1001+
correction: int = ...,
9921002
) -> _ArrayType: ...
9931003

9941004
@overload
@@ -997,54 +1007,64 @@ def var(
9971007
axis: None = ...,
9981008
dtype: None = ...,
9991009
out: None = ...,
1000-
ddof: float = ...,
1010+
ddof: int = ...,
10011011
keepdims: Literal[False] = ...,
10021012
*,
10031013
where: _ArrayLikeBool_co = ...,
1014+
mean: _ArrayLikeComplex_co = ...,
1015+
correction: int = ...,
10041016
) -> floating[Any]: ...
10051017
@overload
10061018
def var(
10071019
a: _ArrayLikeComplex_co | _ArrayLikeObject_co,
10081020
axis: None | _ShapeLike = ...,
10091021
dtype: None = ...,
10101022
out: None = ...,
1011-
ddof: float = ...,
1023+
ddof: int = ...,
10121024
keepdims: bool = ...,
10131025
*,
10141026
where: _ArrayLikeBool_co = ...,
1027+
mean: _ArrayLikeComplex_co | _ArrayLikeObject_co = ...,
1028+
correction: int = ...,
10151029
) -> Any: ...
10161030
@overload
10171031
def var(
10181032
a: _ArrayLikeComplex_co | _ArrayLikeObject_co,
10191033
axis: None = ...,
10201034
dtype: _DTypeLike[_SCT] = ...,
10211035
out: None = ...,
1022-
ddof: float = ...,
1036+
ddof: int = ...,
10231037
keepdims: Literal[False] = ...,
10241038
*,
10251039
where: _ArrayLikeBool_co = ...,
1040+
mean: _ArrayLikeComplex_co | _ArrayLikeObject_co = ...,
1041+
correction: int = ...,
10261042
) -> _SCT: ...
10271043
@overload
10281044
def var(
10291045
a: _ArrayLikeComplex_co | _ArrayLikeObject_co,
10301046
axis: None | _ShapeLike = ...,
10311047
dtype: DTypeLike = ...,
10321048
out: None = ...,
1033-
ddof: float = ...,
1049+
ddof: int = ...,
10341050
keepdims: bool = ...,
10351051
*,
10361052
where: _ArrayLikeBool_co = ...,
1053+
mean: _ArrayLikeComplex_co | _ArrayLikeObject_co = ...,
1054+
correction: int = ...,
10371055
) -> Any: ...
10381056
@overload
10391057
def var(
10401058
a: _ArrayLikeComplex_co | _ArrayLikeObject_co,
10411059
axis: None | _ShapeLike = ...,
10421060
dtype: DTypeLike = ...,
10431061
out: _ArrayType = ...,
1044-
ddof: float = ...,
1062+
ddof: int = ...,
10451063
keepdims: bool = ...,
10461064
*,
10471065
where: _ArrayLikeBool_co = ...,
1066+
mean: _ArrayLikeComplex_co | _ArrayLikeObject_co = ...,
1067+
correction: int = ...,
10481068
) -> _ArrayType: ...
10491069

10501070
max = amax

‎numpy/_core/tests/test_numeric.py

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3084,6 +3084,22 @@ def test_ddof2(self):
30843084
assert_almost_equal(np.std(self.A, ddof=2)**2,
30853085
self.real_var * len(self.A) / (len(self.A) - 2))
30863086

3087+
def test_correction(self):
3088+
assert_almost_equal(
3089+
np.var(self.A, correction=1), np.var(self.A, ddof=1)
3090+
)
3091+
assert_almost_equal(
3092+
np.std(self.A, correction=1), np.std(self.A, ddof=1)
3093+
)
3094+
3095+
err_msg = "ddof and correction can't be provided simultaneously."
3096+
3097+
with assert_raises_regex(ValueError, err_msg):
3098+
np.var(self.A, ddof=1, correction=1)
3099+
3100+
with assert_raises_regex(ValueError, err_msg):
3101+
np.std(self.A, ddof=1, correction=1)
3102+
30873103
def test_out_scalar(self):
30883104
d = np.arange(10)
30893105
out = np.array(0.)

0 commit comments

Comments
 (0)
0