SSTT-visuals 0.1.0__tar.gz

sstt_visuals-0.1.0/LICENSE

@@ -0,0 +1,26 @@
+BSD 3-Clause License
+
+Copyright (c) 2025, Ant-Presentation-Vis contributors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from this
+   software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT or OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
+THE USE OR OTHER DEALINGS IN THE SOFTWARE.

sstt_visuals-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: SSTT-visuals
+Version: 0.1.0
+Summary: Visualization utilities for the Social Science Trust Taxonomy.
+Author-email: "Anthony E. D. Mobbs" <tony@mobbs.com.au>, "Redmond R. Scoble" <imashellio@gmail.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/AnthonyMobbs/SSTT-visuals
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: scipy>=1.10
+Requires-Dist: gmpy2>=2.1
+Dynamic: license-file
+
+# SSTT-visuals
+---
+
+## Installation
+
+Install the package with `pip`:
+
+```bash
+pip install SSTT-visuals
+```
+
+## Quick start
+
+### 1. Produce visualisations
+
+The `SSTTVisual()` function generates the visualisations used in [TBD]
+
+```python
+from SSTT_visuals.plot import SSTTVisual
+
+SSTTVisual("SSTT_visuals/wordGroupTest.json")
+```
+
+## Citation
+If you use SSTT_visuals in your research, please cite the original methodological validation paper:
+[TBD]
+
+## Core references
+TBD

sstt_visuals-0.1.0/README.md

@@ -0,0 +1,29 @@
+# SSTT-visuals
+---
+
+## Installation
+
+Install the package with `pip`:
+
+```bash
+pip install SSTT-visuals
+```
+
+## Quick start
+
+### 1. Produce visualisations
+
+The `SSTTVisual()` function generates the visualisations used in [TBD]
+
+```python
+from SSTT_visuals.plot import SSTTVisual
+
+SSTTVisual("SSTT_visuals/wordGroupTest.json")
+```
+
+## Citation
+If you use SSTT_visuals in your research, please cite the original methodological validation paper:
+[TBD]
+
+## Core references
+TBD

sstt_visuals-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "SSTT-visuals"
+version = "0.1.0"
+authors = [
+    { name="Anthony E. D. Mobbs", email="tony@mobbs.com.au" },
+    { name="Redmond R. Scoble", email="imashellio@gmail.com" },
+]
+description = "Visualization utilities for the Social Science Trust Taxonomy."
+readme = "README.md"
+requires-python = ">=3.13"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+license = "BSD-3-Clause"
+
+dependencies = [
+    "numpy>=1.24",
+    "matplotlib>=3.7",
+    "scipy>=1.10",
+    "gmpy2>=2.1",
+]
+
+[tool.setuptools.package-data]
+SSTT_visuals = ["*.json"]
+
+[project.urls]
+Homepage = "https://github.com/AnthonyMobbs/SSTT-visuals"

sstt_visuals-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sstt_visuals-0.1.0/src/SSTT_visuals/__init__.py

@@ -0,0 +1,5 @@
+"""SSTT visualisation helpers for scan-statistic and occupancy summaries."""
+
+from .plot import statisticsVisual
+
+__all__ = ["statisticsVisual"]

sstt_visuals-0.1.0/src/SSTT_visuals/clusterStats.py

@@ -0,0 +1,298 @@
+"""
+Two goodness-of-fit tests against the null hypothesis that a 5x5 array of
+nonnegative-integer counts arises from N i.i.d. uniform draws over the 25
+cells (equivalently: the count vector is Multinomial(N, p=1/25 each)).
+
+1. occupancy_test:  T = number of empty cells. Reports P(T >= t_obs), exact.
+2. scan_statistic_test: Q = min over "2-by-n" rectangles of the rectangle's
+   own upper-tail binomial p-value. Reports P(Q <= q_obs) via simulation,
+   since the exact null distribution of a minimum over overlapping,
+   dependent windows has no tractable closed form.
+"""
+
+from fractions import Fraction
+from math import comb
+
+import scipy.stats as stats
+
+from .mos import normal_isf_asymptotic
+
+import numpy as np
+from scipy.stats import binom
+
+GRID_SIZE = 5
+CENTER = (GRID_SIZE // 2, GRID_SIZE // 2)  # (2, 2), zero-indexed
+
+
+# ---------------------------------------------------------------------------
+# Test 1: Occupancy test
+# ---------------------------------------------------------------------------
+
+def _surjections(n: int, j: int) -> int:
+    """Number of surjective functions from an n-set onto a j-set, via
+    inclusion-exclusion. Surj(n, 0) = 1 iff n == 0 (handled naturally by the
+    formula since 0**0 = 1 in Python)."""
+    total = 0
+    for i in range(j + 1):
+        total += (-1) ** i * comb(j, i) * (j - i) ** n
+    return total
+
+
+def occupancyStatisticTest(data: np.ndarray):
+    """
+    Exact p-value P(T >= t_obs) for the occupancy test, where T is the
+    number of empty cells among the m = 25 cells of `data`, under the null
+    that N = sum(data) observations are i.i.d. uniform over the 25 cells.
+
+    Returns the p-value (float).
+    """
+    data = np.asarray(data)
+    if data.shape != (GRID_SIZE, GRID_SIZE):
+        raise ValueError(f"expected a {GRID_SIZE}x{GRID_SIZE} array")
+
+    m = data.size            # 25 boxes
+    n = int(data.sum())      # total balls
+    t_obs = int(np.sum(data == 0))
+
+    p_tail = Fraction(0)
+    for k in range(t_obs, m + 1):
+        j = m - k  # number of "occupied" boxes required among the chosen k... 
+        # careful: k here is the number of EMPTY boxes, so m-k boxes must
+        # all be nonempty -> surjection of n balls onto (m-k) boxes
+        occupied = m - k
+        surj = _surjections(n, occupied)
+        p_tail += Fraction(comb(m, k) * surj, m ** n)
+
+    p_value = float(p_tail)
+    if p_value <= 0: 
+        z_score = normal_isf_asymptotic(p_tail)
+        lp = None
+    else:
+        z_score = stats.norm.isf(p_value)
+        lp = -np.log(p_value)
+    return (p_value, z_score, lp)
+
+
+# ---------------------------------------------------------------------------
+# Test 2: Scan statistic test
+# ---------------------------------------------------------------------------
+
+def _enumerate_rectangles(size: int = GRID_SIZE, center=CENTER):
+    """
+    All axis-aligned rectangles with one side exactly length 2 and the other
+    side length 2..size (both orientations: 2-tall / n-wide, and n-tall /
+    2-wide, with n >= 2 so both dimensions are at least 2), excluding any
+    rectangle that contains `center`.
+ 
+    Returns a list of (r0, r1, c0, c1, flat_indices, p) tuples where
+    (r0..r1, c0..c1) are inclusive cell ranges, flat_indices is the list of
+    flattened (row-major) cell indices in the rectangle, and p = ncells/25
+    is the null probability mass covered by the rectangle.
+    """
+    rects = set()
+ 
+    for w in range(2, size + 1):
+        h = 2
+        for r0 in range(size - h + 1):
+            for c0 in range(size - w + 1):
+                r1, c1 = r0 + h - 1, c0 + w - 1
+                if r0 <= center[0] <= r1 and c0 <= center[1] <= c1:
+                    continue
+                rects.add((r0, r1, c0, c1))
+ 
+    for h in range(2, size + 1):
+        w = 2
+        for r0 in range(size - h + 1):
+            for c0 in range(size - w + 1):
+                r1, c1 = r0 + h - 1, c0 + w - 1
+                if r0 <= center[0] <= r1 and c0 <= center[1] <= c1:
+                    continue
+                rects.add((r0, r1, c0, c1))
+ 
+    rect_info = []
+    for (r0, r1, c0, c1) in sorted(rects):
+        idx = [r * size + c for r in range(r0, r1 + 1) for c in range(c0, c1 + 1)]
+        p = len(idx) / (size * size)
+        rect_info.append((r0, r1, c0, c1, idx, p))
+    return rect_info
+ 
+ 
+# These are the two composite regions in grid coordinates. Each tuple keeps
+# the normal rectangle fields, followed by the cells in the union and the
+# component rectangles used by the plotter for highlighting.
+_SPECIAL_COMPOSITE_RECTS = [
+    (
+        0, 4, 0, 2,
+        [0, 1, 5, 6, 10, 11, 15, 16, 17, 20, 21, 22],
+        12 / 25,
+        ((3, 4, 0, 2), (0, 2, 0, 1)),
+    ),
+    (
+        0, 4, 2, 4,
+        [2, 3, 4, 7, 8, 9, 13, 14, 18, 19, 23, 24],
+        12 / 25,
+        ((0, 1, 2, 4), (2, 4, 3, 4)),
+    ),
+]
+
+
+_RECTS = _enumerate_rectangles() + _SPECIAL_COMPOSITE_RECTS
+ 
+
+def _compute_Q(flat_counts: np.ndarray, n_total: int) -> float:
+    """flat_counts: 1D array of length 25 (row-major). Returns Q = min_r q_r."""
+    q_min = 1.0
+    min_rect = None
+    for rect in _RECTS:
+        idx = rect[4]
+        p = rect[5]
+        s = flat_counts[idx].sum()
+        q_r = binom.sf(s - 1, n_total, p)  # P(X >= s)
+        if q_r < q_min:
+            q_min = q_r
+            min_rect = rect
+    return q_min, min_rect
+
+
+def _compute_Q_batch(flat_counts_batch: np.ndarray, n_total: int) -> np.ndarray:
+    """Vectorised version: flat_counts_batch has shape (n_sims, 25)."""
+    n_sims = flat_counts_batch.shape[0]
+    q_min = np.ones(n_sims)
+    for rect in _RECTS:
+        idx = rect[4]
+        p = rect[5]
+        s = flat_counts_batch[:, idx].sum(axis=1)
+        q_r = binom.sf(s - 1, n_total, p)
+        np.minimum(q_min, q_r, out=q_min)
+    return q_min
+
+
+def scanStatisticTest(data, n_sims: int = 2000000, random_state=None, return_rect: bool = False):
+    """
+    Monte Carlo p-value P(Q <= q_obs) for the scan statistic test.
+
+    Q = min over all valid "2-by-n" rectangles r of q_r, where q_r is the
+    upper-tail binomial probability P(count in r >= observed count in r)
+    under the null that N = sum(data) observations are i.i.d. uniform over
+    the 25 cells.
+
+    Returns the p-value, z-score, log-p-value, q_obs, and optionally the
+    rectangle with the minimum q-value.
+    """
+    data = np.asarray(data)
+    if data.shape != (GRID_SIZE, GRID_SIZE):
+        raise ValueError(f"expected a {GRID_SIZE}x{GRID_SIZE} array")
+
+    n_total = int(data.sum())
+    flat_obs = data.reshape(-1)
+    q_obs, min_rect = _compute_Q(flat_obs, n_total)
+
+    if n_total == 0:
+        # Every rectangle sum is trivially 0 >= 0, so q_r = 1 for all r,
+        # Q = 1 always, under the null too -> degenerate p-value of 1.
+        result = (q_obs, 1.0)
+        if return_rect:
+            return (1.0, 0.0, 0.0, q_obs, min_rect)
+        return result
+
+    rng = np.random.default_rng(random_state)
+    flat_p = np.full(GRID_SIZE * GRID_SIZE, 1.0 / (GRID_SIZE * GRID_SIZE))
+    sims = rng.multinomial(n_total, flat_p, size=n_sims)  # shape (n_sims, 25)
+
+    q_sims = _compute_Q_batch(sims, n_total)
+    p_value = float(np.mean(q_sims <= q_obs))
+
+    z_score = stats.norm.isf(p_value)
+    lp = np.inf if p_value == 0 else -np.log(p_value)
+
+    if return_rect:
+        return (p_value, z_score, lp, q_obs, min_rect)
+    return (p_value, z_score, lp, q_obs)
+
+def _min_tail_prob_at_least_as_extreme(n_total: int, p: float, q_threshold: float) -> float:
+    """
+    For S ~ Binomial(n_total, p), let q(s) = P(S >= s) be the upper-tail
+    p-value function (non-increasing, right-continuous step function of s).
+    Returns P(q(S) <= q_threshold), exactly, with no simulation: this is
+    just sf(s* - 1) where s* is the smallest integer count whose own tail
+    probability already drops to or below q_threshold.
+    """
+    s_values = np.arange(0, n_total + 1)
+    tail = binom.sf(s_values - 1, n_total, p)  # monotone non-increasing in s
+    mask = tail <= q_threshold
+    if not mask.any():
+        return 0.0
+    s_star = int(s_values[mask][0])
+    return float(binom.sf(s_star - 1, n_total, p))
+
+
+def scanStatisticTestBonferroni(data: np.ndarray, return_rect: bool = False):
+    """
+    Exact (analytic, no simulation) UPPER BOUND on P(Q <= q_obs), via the
+    union bound over the fixed set of 38 rectangles:
+
+        P(Q <= q) = P(exists r: q_r <= q) <= sum_r P(q_r <= q)
+
+    Unlike the Monte Carlo version, this has no floor on how small a
+    p-value it can report -- useful when the true p-value is far smaller
+    than 1/n_sims. It is conservative: the true p-value is <= this bound.
+
+    Returns (bound, z_score, lp, q_obs) by default, or includes the
+    rectangle with the minimum q-value when return_rect=True.
+    """
+    data = np.asarray(data)
+    if data.shape != (GRID_SIZE, GRID_SIZE):
+        raise ValueError(f"expected a {GRID_SIZE}x{GRID_SIZE} array")
+
+    n_total = int(data.sum())
+    flat_obs = data.reshape(-1)
+    q_obs, min_rect = _compute_Q(flat_obs, n_total)
+
+    if n_total == 0:
+        raise ValueError("cannot compute scan statistic for empty data (n_total=0)")
+
+    bound = 0.0
+    for rect in _RECTS:
+        p = rect[5]
+        bound += _min_tail_prob_at_least_as_extreme(n_total, p, q_obs)
+    bound = min(bound, 1.0)  # a union bound can nominally exceed 1
+
+    z_score = stats.norm.isf(bound)
+    lp = np.inf if bound == 0 else -np.log(bound)
+    if return_rect:
+        return (bound, z_score, lp, q_obs, min_rect)
+    return (bound, z_score, lp, q_obs)
+
+# ---------------------------------------------------------------------------
+# Demo
+# ---------------------------------------------------------------------------
+
+# if __name__ == "__main__":
+    # rng = np.random.default_rng(0)
+
+    # # Example: 40 observations thrown uniformly at random (should look "null-ish")
+    # example = rng.multinomial(40, np.full(25, 1 / 25)).reshape(5, 5)
+    # print("Example data:\n", example)
+
+    # t_obs = int(np.sum(example == 0))
+    # p_occ = occupancyStatisticTest(example)
+    # print(f"\nOccupancy test: t_obs = {t_obs}, P(T >= t_obs) = {p_occ:.4f}")
+
+    # q_obs, p_scan = scanStatisticTest(example, n_sims=2000000, random_state=1)
+    # print(f"Scan statistic test: q_obs = {q_obs:.4f}, P(Q <= q_obs) = {p_scan:.4f}")
+
+    # # Example designed to trip the tests: a clustered/skewed pattern
+    # skewed = np.array([
+    #     [10, 10, 0, 0, 0],
+    #     [10, 10, 0, 0, 0],
+    #     [0,  0,  0, 0, 0],
+    #     [0,  0,  0, 0, 0],
+    #     [0,  0,  0, 0, 0],
+    # ])
+    # print("\nSkewed data:\n", skewed)
+    # t_obs2 = int(np.sum(skewed == 0))
+    # p_occ2 = occupancy_test(skewed)
+    # print(f"\nOccupancy test: t_obs = {t_obs2}, P(T >= t_obs) = {p_occ2:.6f}")
+
+    # q_obs2, p_scan2 = scan_statistic_test(skewed, n_sims=20000, random_state=1)
+    # print(f"Scan statistic test: q_obs = {q_obs2:.6f}, P(Q <= q_obs) = {p_scan2:.6f}")