added pdoc

Author: ceesb

.github/workflows/python-docs.yml

@@ -0,0 +1,49 @@
+name: website
+
+# build the documentation whenever there are new commits on main
+on:
+  push:
+    branches:
+      - main
+    # Alternative: only build for tags.
+    # tags:
+    #   - '*'
+
+# security: restrict permissions for CI jobs.
+permissions:
+  contents: read
+
+jobs:
+  # Build the documentation and upload the static HTML files as an artifact.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      # ADJUST THIS: install all dependencies (including pdoc)
+      - run: |
+            pip install pdoc
+            pip install -e .
+            pdoc incrementalstats -o docs
+            
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/
+
+  # Deploy the artifact to GitHub pages.
+  # This is a separate job so that only actions/deploy-pages has the necessary permissions.
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -1,42 +1,14 @@
-# Incremental stats
+# Install 
 
 `pip install incrementalstats`
 
-A few incremental 1st order statistics in numpy. Currently:
+# Stats
 
+This package implements a few incremental 1st order statistics in numpy. 
+
+Currently:
 - Correlation (Pearson)
 - Covariance
 - Variance
 - Mean
 - Welch-t
-
-## Setup a venv
-
-    mkdir venv
-    virtualenv -p `which python3` venv
-    source venv/bin/activate
-
-## Option 1: Checkout hackable project
-
-    python -m pip install --upgrade pip
-    git clone https://github.com/ceesb/python-incrementalstats
-    pip install -e python-incrementalstats
-    cd python-incrementalstats
-
-Now all the changes you make to this project source code are "live".
-
-## Option 2: Build a wheel
-
-    git clone https://github.com/ceesb/python-incrementalstats
-    cd python-incrementalstats
-    python -m build
-
-Now you can distribute or install the wheel created in the `dist` folder.
-
-    $ ls dist/
-    incrementalstats-0.0.1-py3-none-any.whl  incrementalstats-0.0.1.tar.gz
-    pip install dist/incrementalstats-0.0.1-py3-none-any.whl
-
-## Run the tests
-
-    python -m unittest

src/incrementalstats/__init__.py

@@ -1,3 +1,7 @@
+"""
+.. include:: ../../README.md
+"""
+
 from .mean_var import IncrementalMeanVariance
 from .covariance_correlation import IncrementalCovarianceCorrelation
 from .welcht import IncrementalWelcht

src/incrementalstats/covariance_correlation.py

@@ -26,7 +26,7 @@ class IncrementalCovarianceCorrelation:
     for row in range(nX):
         ic.update(m1[row,:], m2[row,:])
 
-    reference_covariance = (1 / (nX - 1)) * np.matmul((m1 - np.mean(m1, axis=0)).T, (m2 - np.mean(m2, axis=0)))
+    reference_covariance = (1 / (nX - 1)) * np.matmul((m1 - np.getMean()(m1, axis=0)).T, (m2 - np.getMean()(m2, axis=0)))
     reference_m1_stddev = np.std(m1, axis=0, ddof=1)
     reference_m2_stddev = np.std(m2, axis=0, ddof=1)
     reference_1_over_m1_stddev = (1 / numpy_m1_stddev).reshape(numpy_m1_stddev.size, 1)
@@ -41,57 +41,61 @@ class IncrementalCovarianceCorrelation:
 
     def __init__(self, nX, nY):
         """Initialize with the #columns for matrices A and B"""
-        self.nX = nX
-        self.nY = nY
-        self.imX = IncrementalMeanVariance(nX)
-        self.imY = IncrementalMeanVariance(nY)
-        self.cov = np.zeros((nX, nY), dtype=np.float64)
-        self.n = 0
+        self._nX = nX
+        self._nXY = nY
+        self._imX = IncrementalMeanVariance(nX)
+        self._imY = IncrementalMeanVariance(nY)
+        self._cov = np.zeros((nX, nY), dtype=np.float64)
+        self._n = 0
 
     def update(self, x, y):
         """Updates the covariance matrix with a single row of matrix A and a single row of matrix B"""
-        if len(x) != self.nX:
+        if len(x) != self._nX:
             raise Exception("wrong x length")
-        if len(y) != self.nY:
+        if len(y) != self._nXY:
             raise Exception("wrong y length")
 
-        self.n += 1
-        f = (self.n - 1) / self.n
+        self._n += 1
+        f = (self._n - 1) / self._n
 
-        mfX = (x - self.imX.mean) * f
-        mfY = y - self.imY.mean
+        mfX = (x - self._imX.getMean()) * f
+        mfY = y - self._imY.getMean()
 
-        self.cov += np.tensordot(mfX, mfY, axes=0)
+        self._cov += np.tensordot(mfX, mfY, axes=0)
 
-        self.imX.update(x)
-        self.imY.update(y)
+        self._imX.update(x)
+        self._imY.update(y)
 
     def add(self, x: IncrementalCovarianceCorrelation):
         """Merges another object of IncrementalCovarianceCorrelation into this co-variance matrix. This is useful in
         parallelized computations, where different nodes compute co-variances over different
         ranges of rows"""
-        n = self.n + x.n
-        f = (self.n * x.n ** 2 + x.n * self.n ** 2) / (n ** 2)
+        n = self._n + x._n
+        f = (self._n * x._n ** 2 + x._n * self._n ** 2) / (n ** 2)
 
-        deltaX = self.imX.mean - x.imX.mean
+        deltaX = self._imX.getMean() - x._imX.getMean()
         deltaX = deltaX.reshape(deltaX.size, 1) * f
 
-        deltaY = self.imY.mean - x.imY.mean
+        deltaY = self._imY.getMean() - x._imY.getMean()
         deltaY = deltaY.reshape(1, deltaY.size)
 
-        self.cov += x.cov + deltaX * deltaY
-        self.n = n
-        self.imX.add(x.imX)
-        self.imY.add(x.imY)
+        self._cov += x._cov + deltaX * deltaY
+        self._n = n
+        self._imX.add(x._imX)
+        self._imY.add(x._imY)
 
     def getCovariance(self):
         """Returns the scaled co-variance matrix with 1 degree of freedom"""
-        return 1 / (self.n - 1) * self.cov
+        return 1 / (self._n - 1) * self._cov
 
     def getCorrelation(self):
         """Returns Pearson's correlation matrix"""
-        sX = 1 / np.sqrt(self.imX.getVariance())
+        sX = 1 / np.sqrt(self._imX.getVariance())
         sX = sX.reshape(sX.size, 1)
-        sY = 1 / np.sqrt(self.imY.getVariance())
+        sY = 1 / np.sqrt(self._imY.getVariance())
         sY = sY.reshape(1, sY.size)
-        return 1 / (self.n - 1) * self.cov * sX * sY
+        return 1 / (self._n - 1) * self._cov * sX * sY
+
+    def getN(self):
+        """Number of observations"""
+        return self._n

src/incrementalstats/mean_var.py

@@ -23,8 +23,8 @@ class IncrementalMeanVariance:
     for row in range(nX):
         im.update(m[row,:])
 
-    reference_mean = m.mean(axis=0)
-    reference_variance = m.var(axis=0, ddof=1)
+    reference_mean = m._mean(axis=0)
+    reference_variance = m._var(axis=0, ddof=1)
     assert np.allclose(im.getMean(), reference_mean)
     assert np.allclose(im.getVariance(), reference_variance)
     ```
@@ -35,40 +35,44 @@ def __init__(self, ncolumns):
         """Initialize with the #columns of the hypothetical matrix M over
         which we will compute the mean / variance"""
         nX = ncolumns
-        self.nX = nX
-        self.mean = np.zeros(nX, dtype=np.float64)
-        self.var = np.zeros(nX, dtype=np.float64)
-        self.n = 0
+        self._nX = nX
+        self._mean = np.zeros(nX, dtype=np.float64)
+        self._var = np.zeros(nX, dtype=np.float64)
+        self._n = 0
 
     def add(self, other: IncrementalMeanVariance):
         """Merges another object of IncrementalMeanVariance into this mean/variance. This is useful in
         parallelized computations, where different nodes compute mean/variance over different
         ranges of rows"""
         x = other
-        n = self.n + x.n
-        delta = x.mean - self.mean
-        self.mean += x.n * (delta / n)
-        self.var += x.var + self.n * x.n * delta ** 2 / n
-        self.n = n
+        n = self._n + x._n
+        delta = x._mean - self._mean
+        self._mean += x._n * (delta / n)
+        self._var += x._var + self._n * x._n * delta ** 2 / n
+        self._n = n
 
     def update(self, row):
         x = row
         """Updates the mean/variance with a single row. """
-        if len(x) != self.nX:
+        if len(x) != self._nX:
             raise Exception("wrong length")
 
-        self.n += 1
-        y1 = x - self.mean
-        self.mean += y1 / self.n
-        y2 = x - self.mean
-        self.var += y1 * y2
+        self._n += 1
+        y1 = x - self._mean
+        self._mean += y1 / self._n
+        y2 = x - self._mean
+        self._var += y1 * y2
 
     def getMean(self):
         """Returns the current mean"""
-        return self.mean.copy()
+        return self._mean.copy()
 
     def getVariance(self):
         """Returns the current variance"""
-        if self.n < 2:
+        if self._n < 2:
             raise Exception("not enough data")
-        return 1/(self.n - 1) * self.var
+        return 1/(self._n - 1) * self._var
+
+    def getN(self):
+        """Number of observations"""
+        return self._n

src/incrementalstats/welcht.py

@@ -1,50 +1,51 @@
-# function tval(m1, m2, v1, v2, n1, n2)
-#     x = (m1 - m2) / sqrt((v1 / n1) + (v2 / n2) + eps(0.0))
-#     if isnan(x)
-#         return 0.0
-#     else
-#         return x
-#     end
-# end
-
-
 from __future__ import annotations
 import numpy as np
 
 from .mean_var import IncrementalMeanVariance
 
 class IncrementalWelcht:
     """
-    Incremental Welch-t between 2 groups
+    Incremental Welch-t between 2 groups (0 and not 0)
     """
 
     def __init__(self, nsamples):
         """Initialize with the #samples we're computing Welch-t over"""
         nX = nsamples
-        self.mv0 = IncrementalMeanVariance(nX)
-        self.mv1 = IncrementalMeanVariance(nX)
-        self.n = 0
+        self._mv0 = IncrementalMeanVariance(nX)
+        self._mv1 = IncrementalMeanVariance(nX)
+        self._n = 0
 
     def add(self, other: IncrementalWelcht):
-        self.mv0.add(other.mv0)
-        self.mv1.add(other.mv1)
+        """Merges another object of IncrementalWelcht into this object. This is useful in
+            parallelized computations, where different nodes compute Welcht-t over different
+            ranges of rows"""
+        self._mv0.add(other.mv0)
+        self._mv1.add(other.mv1)
 
     def update(self, group, row):
+        """Updates the Welch-t state with a group id (0 or not 0) and a single row of samples"""
         if group == 0:
-            self.mv0.update(row)
+            self._mv0.update(row)
         else:
-            self.mv1.update(row)
+            self._mv1.update(row)
 
     def getWelcht(self):
-        m0 = self.mv0.getMean()
-        v0 = self.mv0.getVariance()
-        n0 = self.mv0.n
-        m1 = self.mv1.getMean()
-        v1 = self.mv1.getVariance()
-        n1 = self.mv1.n
+        """Returns the Welch-t statistic. NaNs are zero'd and a small factor is added in the 
+        denominator to prevent infinities"""
+        m0 = self._mv0.getMean()
+        v0 = self._mv0.getVariance()
+        n0 = self._mv0.getN()
+        m1 = self._mv1.getMean()
+        v1 = self._mv1.getVariance()
+        n1 = self._mv1.getN()
 
         x = (m0 - m1) / np.sqrt((v0 / n0) + (v1 / n1) + 1e-12)
 
         x = np.nan_to_num(x, copy = False)
 
         return x
+
+    def getN(self):
+        """Number of observations"""
+        return self._mv0.getN() + self._mv1.getN()
+

tests/test_incremental_stats.py

@@ -64,10 +64,10 @@ def testCorrectness(self):
         self.assertTrue(np.allclose(ic1.getCovariance(), numpy_covariance))
         self.assertTrue(np.allclose(ic1.getCorrelation(), numpy_correlation))
 
-        self.assertTrue(np.allclose(ic1.imX.getMean(), ic.imX.getMean()))
-        self.assertTrue(np.allclose(ic1.imY.getMean(), ic.imY.getMean()))
-        self.assertTrue(np.allclose(ic1.imX.getVariance(), ic.imX.getVariance()))
-        self.assertTrue(np.allclose(ic1.imY.getVariance(), ic.imY.getVariance()))
+        self.assertTrue(np.allclose(ic1._imX.getMean(), ic._imX.getMean()))
+        self.assertTrue(np.allclose(ic1._imY.getMean(), ic._imY.getMean()))
+        self.assertTrue(np.allclose(ic1._imX.getVariance(), ic._imX.getVariance()))
+        self.assertTrue(np.allclose(ic1._imY.getVariance(), ic._imY.getVariance()))
 
 if __name__ == "__main__":
     unittest.main(verbosity=2)