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

Commit d776e42

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

File tree

7 files changed

+135
-31
lines changed

7 files changed

+135
-31
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: 35 additions & 7 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
@@ -3547,7 +3547,7 @@ def std(a, axis=None, dtype=None, out=None, ddof=0, keepdims=np._NoValue, *,
35473547
Alternative output array in which to place the result. It must have
35483548
the same shape as the expected output but the type (of the calculated
35493549
values) will be cast if necessary.
3550-
ddof : int, optional
3550+
ddof : {int, float}, optional
35513551
Means Delta Degrees of Freedom. The divisor used in calculations
35523552
is ``N - ddof``, where ``N`` represents the number of elements.
35533553
By default `ddof` is zero.
@@ -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, float}, 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
@@ -3714,7 +3728,7 @@ def var(a, axis=None, dtype=None, out=None, ddof=0, keepdims=np._NoValue, *,
37143728
Alternate output array in which to place the result. It must have
37153729
the same shape as the expected output, but the type is cast if
37163730
necessary.
3717-
ddof : int, optional
3731+
ddof : {int, float}, optional
37183732
"Delta Degrees of Freedom": the divisor used in the calculation is
37193733
``N - ddof``, where ``N`` represents the number of elements. By
37203734
default `ddof` is zero.
@@ -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, float}, 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 | float = ...,
945945
keepdims: Literal[False] = ...,
946946
*,
947947
where: _ArrayLikeBool_co = ...,
948+
mean: _ArrayLikeComplex_co = ...,
949+
correction: int | float = ...,
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 | float = ...,
956958
keepdims: bool = ...,
957959
*,
958960
where: _ArrayLikeBool_co = ...,
961+
mean: _ArrayLikeComplex_co | _ArrayLikeObject_co = ...,
962+
correction: int | float = ...,
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 | float = ...,
967971
keepdims: Literal[False] = ...,
968972
*,
969973
where: _ArrayLikeBool_co = ...,
974+
mean: _ArrayLikeComplex_co | _ArrayLikeObject_co = ...,
975+
correction: int | float = ...,
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 | float = ...,
978984
keepdims: bool = ...,
979985
*,
980986
where: _ArrayLikeBool_co = ...,
987+
mean: _ArrayLikeComplex_co | _ArrayLikeObject_co = ...,
988+
correction: int | float = ...,
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 | float = ...,
989997
keepdims: bool = ...,
990998
*,
991999
where: _ArrayLikeBool_co = ...,
1000+
mean: _ArrayLikeComplex_co | _ArrayLikeObject_co = ...,
1001+
correction: int | float = ...,
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 | float = ...,
10011011
keepdims: Literal[False] = ...,
10021012
*,
10031013
where: _Ar F43B rayLikeBool_co = ...,
1014+
mean: _ArrayLikeComplex_co = ...,
1015+
correction: int | float = ...,
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 | float = ...,
10121024
keepdims: bool = ...,
10131025
*,
10141026
where: _ArrayLikeBool_co = ...,
1027+
mean: _ArrayLikeComplex_co | _ArrayLikeObject_co = ...,
1028+
correction: int | float = ...,
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 | float = ...,
10231037
keepdims: Literal[False] = ...,
10241038
*,
10251039
where: _ArrayLikeBool_co = ...,
1040+
mean: _ArrayLikeComplex_co | _ArrayLikeObject_co = ...,
1041+
correction: int | float = ...,
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 | float = ...,
10341050
keepdims: bool = ...,
10351051
*,
10361052
where: _ArrayLikeBool_co = ...,
1053+
mean: _ArrayLikeComplex_co | _ArrayLikeObject_co = ...,
1054+
correction: int | float = ...,
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 | float = ...,
10451063
keepdims: bool = ...,
10461064
*,
10471065
where: _ArrayLikeBool_co = ...,
1066+
mean: _ArrayLikeComplex_co | _ArrayLikeObject_co = ...,
1067+
correction: int | float = ...,
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