pygeodesy 24.9.29__py2.py3-none-any.whl → 24.10.10__py2.py3-none-any.whl

pygeodesy/fstats.py

@@ -2,7 +2,8 @@
 # -*- coding: utf-8 -*-
 
 u'''Classes for I{running} statistics and regressions based on
-L{pygeodesy.Fsum}, precision floating point summation.
+L{pygeodesy.Fsum}, precision floating point summation and accurate
+multiplication.
 '''
 # make sure int/int division yields float quotient, see .basics
 from __future__ import division as _; del _  # PYCHOK semicolon
@@ -22,36 +23,35 @@ from pygeodesy.named import _name__, _Named, _NotImplemented, \
 # from pygeodesy.streprs import Fmt  # from .fmath
 
 __all__ = _ALL_LAZY.fstats
-__version__ = '24.09.28'
+__version__ = '24.10.08'
 
 
-def _2Floats(**xs):
+def _sampled(n, sample):
+    '''(INTERNAL) Return the sample or the entire count.
+    '''
+    return (n - 1) if sample and n > 0 else n
+
+
+def _Xs(**name_xs):
     '''(INTERNAL) Yield all C{xs} as C{float} or L{Fsum}.
     '''
-    name, xs = _xkwds_item2(xs)
+    name, xs = _xkwds_item2(name_xs)
     try:
-        i, x = None, xs
-        for i, x in enumerate(_xiterable(xs)):  # don't unravel Fsums
-            yield x._Fsum if _isFsum_2Tuple(x) else _2finite(x)
+        i, x = 0, xs
+        for i, x in enumerate(xs):  # don't unravel Fsums
+            yield x._Fsum if _isFsum_2Tuple(x) else x
     except Exception as X:
         raise _xsError(X, xs, i, x, name)
 
 
-def _sampled(n, sample):
-    '''(INTERNAL) Return the sample or the entire count.
-    '''
-    return (n - 1) if sample and n > 0 else n
-
-
 class _FstatsNamed(_Named):
     '''(INTERNAL) Base class.
     '''
     _n = 0
 
     def __add__(self, other):
-        '''Sum of this and an other instance or a C{scalar} or an
-           L{Fsum}, L{Fsum2Tuple} or
-           .
+        '''Sum of this and an other instance, a C{scalar}, an L{Fsum}
+           or L{Fsum2Tuple}.
         '''
         f  = self.copy(name=self.__add__.__name__)  # PYCHOK expected
         f += other
@@ -103,7 +103,7 @@ class _FstatsBase(_FstatsNamed):
     _Ms = ()
 
     def _copy(self, d, s):
-        '''(INTERNAL) Copy C{B{c} = B{s}}.
+        '''(INTERNAL) Copy C{B{d} = B{s}}.
         '''
         _xinstanceof(self.__class__, d=d, s=s)
         d._Ms = tuple(M.copy() for M in s._Ms)  # deep=False
@@ -124,8 +124,8 @@ class _FstatsBase(_FstatsNamed):
     def fmean(self, xs=None):
         '''Accumulate and return the current mean.
 
-           @kwarg xs: Iterable of additional values (each C{scalar} or
-                      an L{Fsum} or L{Fsum2Tuple} instance).
+           @kwarg xs: Iterable of additional values (each C{scalar},
+                      an L{Fsum} or L{Fsum2Tuple}).
 
            @return: Current, running mean (C{float}).
 
@@ -143,8 +143,8 @@ class _FstatsBase(_FstatsNamed):
     def fstdev(self, xs=None, **sample):
         '''Accumulate and return the current standard deviation.
 
-           @arg xs: Iterable of additional values (each C{scalar} or an
-                    L{Fsum} or L{Fsum2Tuple} instance).
+           @arg xs: Iterable of additional values (each C{scalar}, an L{Fsum}
+                    or L{Fsum2Tuple}).
            @kwarg sample: Use C{B{sample}=True} for the I{sample} deviation
                           instead of the I{population} deviation (C{bool}).
 
@@ -164,8 +164,8 @@ class _FstatsBase(_FstatsNamed):
     def fvariance(self, xs=None, **sample):
         '''Accumulate and return the current variance.
 
-           @arg xs: Iterable of additional values (each C{scalar} or an
-                    L{Fsum} or L{Fsum2Tuple} instance).
+           @arg xs: Iterable of additional values (each C{scalar}, an L{Fsum}
+                    or L{Fsum2Tuple}).
            @kwarg sample: Use C{B{sample}=True} for the I{sample} variance
                           instead of the I{population} variance (C{bool}).
 
@@ -238,8 +238,8 @@ class Fcook(_FstatsBase):
     def __init__(self, xs=None, **name):
         '''New L{Fcook} stats accumulator.
 
-           @arg xs: Iterable of additional values (each C{scalar} or
-                    an L{Fsum} or L{Fsum2Tuple} instance).
+           @arg xs: Iterable of additional values (each C{scalar}, an
+                    L{Fsum} or L{Fsum2Tuple}).
            @kwarg name: Optional C{B{name}=NN} (C{str}).
 
            @see: Method L{Fcook.fadd}.
@@ -254,8 +254,8 @@ class Fcook(_FstatsBase):
         '''Add B{C{other}} to this L{Fcook} instance.
 
            @arg other: An L{Fcook} instance or value or iterable
-                       of values (each C{scalar} or an L{Fsum}
-                       or L{Fsum2Tuple} instance).
+                       of values (each C{scalar}, an L{Fsum} or
+                       L{Fsum2Tuple}).
 
            @return: This instance, updated (L{Fcook}).
 
@@ -311,8 +311,8 @@ class Fcook(_FstatsBase):
     def fadd(self, xs, sample=False):
         '''Accumulate and return the current count.
 
-           @arg xs: Iterable of additional values (each C{scalar} or an
-                    L{Fsum} or L{Fsum2Tuple} instance).
+           @arg xs: Iterable of additional values (each C{scalar}, an
+                    L{Fsum} or L{Fsum2Tuple}).
            @kwarg sample: Use C{B{sample}=True} for the I{sample} count
                           instead of the I{population} count (C{bool}).
 
@@ -330,7 +330,7 @@ class Fcook(_FstatsBase):
         n = self._n
         if xs:
             M1, M2, M3, M4 = self._Ms
-            for x in _2Floats(xs=xs):  # PYCHOK yield
+            for x in _Xs(xs=xs):  # PYCHOK yield
                 n1 = n
                 n += 1
                 D  = x - M1
@@ -364,7 +364,7 @@ class Fcook(_FstatsBase):
         '''Accumulate and compute the current U{Jarque-Bera
            <https://WikiPedia.org/wiki/Jarque–Bera_test>} normality.
 
-           @kwarg xs: Iterable of additional values (each C{scalar} or an
+           @kwarg xs: Iterable of additional values (each C{scalar}, an
                       L{Fsum} or L{Fsum2Tuple}).
            @kwarg excess: Apply the I{excess} kurtosis (C{bool}), default.
            @kwarg sample: Use C{B{sample}=False} for the I{population}
@@ -387,8 +387,8 @@ class Fcook(_FstatsBase):
     def fkurtosis(self, xs=None, excess=True, **sample):
         '''Accumulate and return the current kurtosis.
 
-           @arg xs: Iterable of additional values (each C{scalar} or an
-                    L{Fsum} or L{Fsum2Tuple} instance).
+           @arg xs: Iterable of additional values (each C{scalar}, an L{Fsum}
+                    or L{Fsum2Tuple}).
            @kwarg excess: Return the I{excess} kurtosis (C{bool}), default.
            @kwarg sample: Use C{B{sample}=True} for the I{sample} kurtosis
                           instead of the I{population} kurtosis (C{bool}).
@@ -413,8 +413,8 @@ class Fcook(_FstatsBase):
     def fmedian(self, xs=None):
         '''Accumulate and return the current median.
 
-           @arg xs: Iterable of additional values (each C{scalar} or an
-                    L{Fsum} or L{Fsum2Tuple} instance).
+           @arg xs: Iterable of additional values (each C{scalar}, an L{Fsum} or
+                    L{Fsum2Tuple}).
 
            @return: Current, running median (C{float}).
 
@@ -435,8 +435,8 @@ class Fcook(_FstatsBase):
     def fskewness(self, xs=None, **sample):
         '''Accumulate and return the current skewness.
 
-           @arg xs: Iterable of additional values (each C{scalar} or an
-                    L{Fsum} or L{Fsum2Tuple} instance).
+           @arg xs: Iterable of additional values (each C{scalar}, an L{Fsum}
+                    or L{Fsum2Tuple}).
            @kwarg sample: Use C{B{sample}=True} for the I{sample} skewness
                           instead of the I{population} skewness (C{bool}).
 
@@ -526,8 +526,7 @@ class Fwelford(_FstatsBase):
     def __init__(self, xs=None, **name):
         '''New L{Fwelford} stats accumulator.
 
-           @arg xs: Iterable of initial values (each C{scalar} or an
-                    L{Fsum} or L{Fsum2Tuple} instance).
+           @arg xs: Iterable of initial values (each C{scalar}, an L{Fsum} or L{Fsum2Tuple}).
            @kwarg name: Optional C{B{name}=NN} (C{str}).
 
            @see: Method L{Fwelford.fadd}.
@@ -541,9 +540,9 @@ class Fwelford(_FstatsBase):
     def __iadd__(self, other):
         '''Add B{C{other}} to this L{Fwelford} instance.
 
-           @arg other: An L{Fwelford} or L{Fcook} instance or value
-                       or an iterable of values (each C{scalar} or
-                       an L{Fsum} or L{Fsum2Tuple} instance).
+           @arg other: An L{Fwelford} or L{Fcook} instance or value or an
+                       iterable of values (each C{scalar}, an L{Fsum} or
+                       L{Fsum2Tuple}).
 
            @return: This instance, updated (L{Fwelford}).
 
@@ -590,8 +589,8 @@ class Fwelford(_FstatsBase):
     def fadd(self, xs, sample=False):
         '''Accumulate and return the current count.
 
-           @arg xs: Iterable of additional values (each C{scalar} or an
-                    L{Fsum} or L{Fsum2Tuple} instance).
+           @arg xs: Iterable of additional values (each C{scalar}, an
+                    L{Fsum} or L{Fsum2Tuple}).
            @kwarg sample: Use C{B{sample}=True} for the I{sample} count
                           instead of the I{population} count (C{bool}).
 
@@ -606,7 +605,7 @@ class Fwelford(_FstatsBase):
         n = self._n
         if xs:
             M, S = self._Ms
-            for x in _2Floats(xs=xs):  # PYCHOK yield
+            for x in _Xs(xs=xs):  # PYCHOK yield
                 n += 1
                 D  = x - M
                 M += D / n
@@ -625,10 +624,10 @@ class Flinear(_FstatsNamed):
     def __init__(self, xs=None, ys=None, Fstats=Fwelford, **name):
         '''New L{Flinear} regression accumulator.
 
-           @kwarg xs: Iterable of initial C{x} values (each C{scalar} or
-                      an L{Fsum} or L{Fsum2Tuple} instance).
-           @kwarg ys: Iterable of initial C{y} values (each C{scalar} or
-                      an L{Fsum} or L{Fsum2Tuple} instance).
+           @kwarg xs: Iterable of initial C{x} values (each C{scalar},
+                      an L{Fsum} or L{Fsum2Tuple}).
+           @kwarg ys: Iterable of initial C{y} values (each C{scalar},
+                      an L{Fsum} or L{Fsum2Tuple}).
            @kwarg Fstats: Class for C{xs} and C{ys} values (L{Fcook} or
                           L{Fwelford}).
            @kwarg name: Optional C{B{name}=NN} (C{str}).
@@ -704,10 +703,10 @@ class Flinear(_FstatsNamed):
     def fadd(self, xs, ys, sample=False):
         '''Accumulate and return the current count.
 
-           @arg xs: Iterable of additional C{x} values (each C{scalar}
-                    or an L{Fsum} or L{Fsum2Tuple} instance).
-           @arg ys: Iterable of additional C{y} values (each C{scalar}
-                    or an L{Fsum} or L{Fsum2Tuple} instance).
+           @arg xs: Iterable of additional C{x} values (each C{scalar},
+                    an L{Fsum} or L{Fsum2Tuple}).
+           @arg ys: Iterable of additional C{y} values (each C{scalar},
+                    an L{Fsum} or L{Fsum2Tuple}).
            @kwarg sample: Use C{B{sample}=True} for the I{sample} count
                           instead of the I{population} count (C{bool}).
 
@@ -724,7 +723,7 @@ class Flinear(_FstatsNamed):
             S = self._S
             X = self._X
             Y = self._Y
-            for x, y in _zip(_2Floats(xs=xs), _2Floats(ys=ys)):  # PYCHOK strict=True
+            for x, y in _zip(_Xs(xs=xs), _Xs(ys=ys)):  # PYCHOK strict=True
                 n1 = n
                 n += 1
                 if n1 > 0:
@@ -738,8 +737,7 @@ class Flinear(_FstatsNamed):
         '''Accumulate and return the current count.
 
            @arg x_ys: Individual, alternating C{x, y, x, y, ...} values
-                      (each C{scalar} or an L{Fsum} or L{Fsum2Tuple}
-                      instance).
+                      (each C{scalar}, an L{Fsum} or L{Fsum2Tuple}).
 
            @see: Method C{Flinear.fadd} for further details.
         '''