Merge pull request #1646 from scipy:1.18/stats/lmoment-distribution-method

👽️ `stats.ContinuousDistribution.lmoment`: new method

Author: jorenham

.mypyignore

@@ -21,11 +21,6 @@ scipy\.stats\.(_new_distributions\.)?Normal\.__new__
 # TODO: 1.18.0rc1
 
 scipy.stats._bws_test.bws_test
-scipy.stats._distribution_infrastructure.Mixture.lmoment
-scipy.stats._distribution_infrastructure.OrderStatisticDistribution._n_domain
-scipy.stats._distribution_infrastructure.OrderStatisticDistribution._r_domain
-scipy.stats._distribution_infrastructure.UnivariateDistribution.lmoment
-scipy.stats._probability_distribution._ProbabilityDistribution.lmoment
 
 scipy.stats._morestats.ansari
 scipy.stats._morestats.boxcox

scipy-stubs/stats/_distribution_infrastructure.pyi

@@ -29,7 +29,7 @@ import optype.numpy as onp
 import optype.numpy.compat as npc
 
 from ._distn_infrastructure import rv_continuous
-from ._probability_distribution import _ProbabilityDistribution
+from ._probability_distribution import _LMomentMethod, _ProbabilityDistribution
 from ._qmc import QMCEngine
 
 __all__ = ["Mixture", "abs", "exp", "log", "make_distribution", "order_statistic", "truncate"]
@@ -61,15 +61,15 @@ _DistT_co = TypeVar("_DistT_co", bound=_Dist[tuple[int, ...]], default=Univariat
 
 _AxesT = TypeVar("_AxesT", bound=_Axes, default=Any)
 
-_ParameterEndpoint: TypeAlias = onp.ToFloat | Callable[..., onp.ToFloat] | str
-_ParameterTuple: TypeAlias = tuple[_ParameterEndpoint, _ParameterEndpoint]
+type _ParameterEndpoint = onp.ToFloat | Callable[..., onp.ToFloat] | str
+type _ParameterTuple = tuple[_ParameterEndpoint, _ParameterEndpoint]
 
 # NOTE: `TypedDict` with `NotRequired` cannot be used, because `NotRequired` does not
 # mean "not required": Other `TypedDict` MUST also include them to be assignable,
 # so a `NotRequired` value is REQUIRED. Absolutely ridiculous...
 # https://typing.python.org/en/latest/spec/typeddict.html#id4
-_ParameterDict: TypeAlias = Mapping[str, tuple[Any, ...]]
-_ParameterSpec: TypeAlias = _ParameterDict | _ParameterTuple
+type _ParameterDict = Mapping[str, tuple[Any, ...]]
+type _ParameterSpec = _ParameterDict | _ParameterTuple
 
 @type_check_only
 class _DuckDistributionBase(Protocol[_Tss]):
@@ -494,6 +494,10 @@ class _BaseDistribution(_ProbabilityDistribution[_XT_co], Generic[_XT_co, _Shape
         method: _SMomentMethod | None = None,
     ) -> _FloatND[_ShapeT1]: ...
 
+    #
+    @override
+    def lmoment(self, /, order: int = 1, *, standardize: bool = True, method: _LMomentMethod | None = None) -> np.float64: ...  # pyright: ignore[reportIncompatibleMethodOverride] # pyrefly:ignore[bad-override] # ty:ignore[invalid-method-override]
+
     #
     @override
     @overload
@@ -1235,6 +1239,8 @@ class UnivariateDistribution(_BaseDistribution[_XT_co], Generic[_XT_co, _ShapeT0
         t: tuple[_PlotQuantity, onp.ToJustFloat, onp.ToJustFloat] | None = None,
         ax: _AxesT | None = None,
     ) -> _AxesT: ...
+
+    #
     def __neg__(self, /) -> _LinDist[Self, _FloatT_co, _ShapeT_co]: ...
     def __abs__(self, /) -> _FoldDist[Self, _FloatT_co, _ShapeT_co]: ...
 
@@ -1425,10 +1431,10 @@ class TruncatedDistribution(_TransDist[_DistT_co, _Float, _ShapeT_co], Generic[_
 
 # always float64 or longdouble
 class OrderStatisticDistribution(_TransDist[_DistT_co, _OutFloat, _ShapeT_co], Generic[_DistT_co, _ShapeT_co]):
-    # these should actually be integral; but the `_IntegerDomain` isn't finished yet
-    _r_domain: ClassVar[_RealInterval] = ...
+    _r_domain: ClassVar[_IntegerInterval] = ...
     _r_param: ClassVar[_RealParameter] = ...
-    _n_domain: ClassVar[_RealInterval] = ...
+
+    _n_domain: ClassVar[_IntegerInterval] = ...
     _n_param: ClassVar[_RealParameter] = ...
 
     @overload
@@ -1524,6 +1530,10 @@ class Mixture(_BaseDistribution[_FloatT_co, _0D], Generic[_FloatT_co]):
     @override
     def kurtosis(self, /, *, method: _SMomentMethod | None = None) -> _OutFloat: ...  # pyright: ignore[reportIncompatibleMethodOverride] # ty: ignore[invalid-method-override]
 
+    # always raises NotImplementedError`
+    @override
+    def lmoment(self, order: int = 1, *, standardize: bool = False, method: _LMomentMethod | None = None) -> Never: ...
+
 ###
 
 # still waiting on the intersection type PEP...

scipy-stubs/stats/_probability_distribution.pyi

@@ -1,6 +1,6 @@
 import abc
 import types
-from typing import Any, Generic, Literal as L, TypeAlias, overload
+from typing import Any, Generic, Literal as L, overload
 from typing_extensions import TypeVar
 
 import numpy as np
@@ -11,22 +11,23 @@ from ._qmc import QMCEngine
 
 _XT_co = TypeVar("_XT_co", bound=npc.number, default=np.float64, covariant=True)
 
-_MedianMethod: TypeAlias = L["formula", "icdf"] | None
-_ModeMethod: TypeAlias = L["formula", "optimization"] | None
-_SampleMethod: TypeAlias = L["formula", "inverse_transform"] | None
-_RMomentMethod: TypeAlias = L["formula", "transform", "quadrature", "cache"] | None
-_CMomentMethod: TypeAlias = L["formula", "transform", "quadrature", "cache", "normalize"] | None
-_SMomentMethod: TypeAlias = L["formula", "transform", "general", "cache", "normalize"] | None
-_EntropyMethod: TypeAlias = L["formula", "logexp", "quadrature"] | None
-_PXFMethod: TypeAlias = L["formula", "logexp"] | None
-_CDFMethod: TypeAlias = L["formula", "logexp", "complement", "quadrature", "subtraction"] | None
-_CCDFMethod: TypeAlias = L["formula", "logexp", "complement", "quadrature", "addition"] | None
-_ICDFMethod: TypeAlias = L["formula", "complement", "inversion"] | None
+type _MedianMethod = L["formula", "icdf"] | None
+type _ModeMethod = L["formula", "optimization"] | None
+type _SampleMethod = L["formula", "inverse_transform"] | None
+type _RMomentMethod = L["formula", "transform", "quadrature", "cache"] | None
+type _CMomentMethod = L["formula", "transform", "quadrature", "cache", "normalize"] | None
+type _SMomentMethod = L["formula", "transform", "general", "cache", "normalize"] | None
+type _LMomentMethod = L["formula", "general", "order_statistics", "quadrature_icdf", "cache"]
+type _EntropyMethod = L["formula", "logexp", "quadrature"] | None
+type _PXFMethod = L["formula", "logexp"] | None
+type _CDFMethod = L["formula", "logexp", "complement", "quadrature", "subtraction"] | None
+type _CCDFMethod = L["formula", "logexp", "complement", "quadrature", "addition"] | None
+type _ICDFMethod = L["formula", "complement", "inversion"] | None
 
-_Float: TypeAlias = np.float64 | np.longdouble
-_Complex: TypeAlias = np.complex128 | np.clongdouble
-_FloatND: TypeAlias = onp.ArrayND[_Float]
-_ToFloat0ND: TypeAlias = onp.ToFloat | onp.ToFloatND
+type _Float = np.float64 | np.longdouble
+type _Complex = np.complex128 | np.clongdouble
+type _FloatND = onp.ArrayND[_Float]
+type _ToFloat0ND = onp.ToFloat | onp.ToFloatND
 
 ###
 
@@ -69,6 +70,10 @@ class _ProbabilityDistribution(Generic[_XT_co], metaclass=abc.ABCMeta):
     @abc.abstractmethod
     def moment(self, /, order: onp.ToInt, kind: L["standardized"], *, method: _SMomentMethod) -> _Float | _FloatND: ...
 
+    # The `kind` param here is wrong: https://github.com/scipy/scipy/pull/25243
+    @abc.abstractmethod
+    def lmoment(self, /, order: int, kind: bool, *, method: _LMomentMethod | None) -> _Float | _FloatND: ...
+
     #
     @abc.abstractmethod
     def entropy(self, /, *, method: _EntropyMethod) -> _Float | _FloatND: ...