pragmastat 3.1.6__tar.gz

pragmastat-3.1.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andrey Akinshin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE 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.

pragmastat-3.1.6/MANIFEST.in

@@ -0,0 +1,3 @@
+include src/*.c
+include README.md
+include LICENSE

pragmastat-3.1.6/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: pragmastat
+Version: 3.1.6
+Summary: Pragmastat: Pragmatic Statistical Toolkit
+Author: Andrey Akinshin
+License-Expression: MIT
+Project-URL: Homepage, https://pragmastat.dev
+Project-URL: Repository, https://github.com/AndreyAkinshin/pragmastat
+Project-URL: DOI, https://doi.org/10.5281/zenodo.17236778
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Dynamic: license-file
+
+# Pragmastat Python Implementation
+
+[![DOI](https://zenodo.org/badge/doi/10.5281/zenodo.17236778.svg)](https://doi.org/10.5281/zenodo.17236778)
+
+A Python implementation of the Pragmastat statistical toolkit, providing robust statistical estimators for reliable analysis of real-world data.
+
+## Installation
+
+```bash
+pip install pragmastat
+```
+
+## Requirements
+
+- Python >= 3.8
+- NumPy >= 1.20
+
+## Usage
+
+```python
+from pragmastat import center, spread, rel_spread, shift, ratio, avg_spread, disparity
+
+# Basic estimators
+x = [1, 2, 3, 4, 5]
+print(f"Center: {center(x)}")
+print(f"Spread: {spread(x)}")
+print(f"RelSpread: {rel_spread(x)}")
+
+# Comparison estimators
+y = [3, 4, 5, 6, 7]
+print(f"Shift: {shift(x, y)}")
+print(f"Ratio: {ratio(x, y)}")
+print(f"AvgSpread: {avg_spread(x, y)}")
+print(f"Disparity: {disparity(x, y)}")
+```
+
+## Estimators
+
+### Single-sample estimators
+
+- `center(x)`: Hodges-Lehmann estimator - median of all pairwise averages
+- `spread(x)`: Shamos estimator - median of all pairwise absolute differences
+- `rel_spread(x)`: Relative spread - spread divided by absolute center
+
+### Two-sample estimators
+
+- `shift(x, y)`: Hodges-Lehmann shift estimator - median of all pairwise differences
+- `ratio(x, y)`: Median of all pairwise ratios
+- `avg_spread(x, y)`: Weighted average of spreads
+- `disparity(x, y)`: Normalized shift - shift divided by average spread
+
+## Features
+
+- Robust to outliers
+- Supports both Python lists and NumPy arrays
+- Type hints with numpy.typing
+- Efficient vectorized NumPy operations
+
+## License
+
+MIT

pragmastat-3.1.6/README.md

@@ -0,0 +1,61 @@
+# Pragmastat Python Implementation
+
+[![DOI](https://zenodo.org/badge/doi/10.5281/zenodo.17236778.svg)](https://doi.org/10.5281/zenodo.17236778)
+
+A Python implementation of the Pragmastat statistical toolkit, providing robust statistical estimators for reliable analysis of real-world data.
+
+## Installation
+
+```bash
+pip install pragmastat
+```
+
+## Requirements
+
+- Python >= 3.8
+- NumPy >= 1.20
+
+## Usage
+
+```python
+from pragmastat import center, spread, rel_spread, shift, ratio, avg_spread, disparity
+
+# Basic estimators
+x = [1, 2, 3, 4, 5]
+print(f"Center: {center(x)}")
+print(f"Spread: {spread(x)}")
+print(f"RelSpread: {rel_spread(x)}")
+
+# Comparison estimators
+y = [3, 4, 5, 6, 7]
+print(f"Shift: {shift(x, y)}")
+print(f"Ratio: {ratio(x, y)}")
+print(f"AvgSpread: {avg_spread(x, y)}")
+print(f"Disparity: {disparity(x, y)}")
+```
+
+## Estimators
+
+### Single-sample estimators
+
+- `center(x)`: Hodges-Lehmann estimator - median of all pairwise averages
+- `spread(x)`: Shamos estimator - median of all pairwise absolute differences
+- `rel_spread(x)`: Relative spread - spread divided by absolute center
+
+### Two-sample estimators
+
+- `shift(x, y)`: Hodges-Lehmann shift estimator - median of all pairwise differences
+- `ratio(x, y)`: Median of all pairwise ratios
+- `avg_spread(x, y)`: Weighted average of spreads
+- `disparity(x, y)`: Normalized shift - shift divided by average spread
+
+## Features
+
+- Robust to outliers
+- Supports both Python lists and NumPy arrays
+- Type hints with numpy.typing
+- Efficient vectorized NumPy operations
+
+## License
+
+MIT

pragmastat-3.1.6/examples/demo.py

@@ -0,0 +1,51 @@
+from pragmastat import center, spread, rel_spread, shift, ratio, avg_spread, disparity
+
+
+def main():
+    x = [0, 2, 4, 6, 8]
+    print(center(x))  # 4
+    print(center([v + 10 for v in x]))  # 14
+    print(center([v * 3 for v in x]))  # 12
+
+    print(spread(x))  # 4
+    print(spread([v + 10 for v in x]))  # 4
+    print(spread([v * 2 for v in x]))  # 8
+
+    print(rel_spread(x))  # 1
+    print(rel_spread([v * 5 for v in x]))  # 1
+
+    y = [10, 12, 14, 16, 18]
+    print(shift(x, y))  # -10
+    print(shift(x, x))  # 0
+    print(shift([v + 7 for v in x], [v + 3 for v in y]))  # -6
+    print(shift([v * 2 for v in x], [v * 2 for v in y]))  # -20
+    print(shift(y, x))  # 10
+
+    x = [1, 2, 4, 8, 16]
+    y = [2, 4, 8, 16, 32]
+    print(ratio(x, y))  # 0.5
+    print(ratio(x, x))  # 1
+    print(ratio([v * 2 for v in x], [v * 5 for v in y]))  # 0.2
+
+    x = [0, 3, 6, 9, 12]
+    y = [0, 2, 4, 6, 8]
+    print(spread(x))  # 6
+    print(spread(y))  # 4
+
+    print(avg_spread(x, y))  # 5
+    print(avg_spread(x, x))  # 6
+    print(avg_spread([v * 2 for v in x], [v * 3 for v in x]))  # 15
+    print(avg_spread(y, x))  # 5
+    print(avg_spread([v * 2 for v in x], [v * 2 for v in y]))  # 10
+
+    print(shift(x, y))  # 2
+    print(avg_spread(x, y))  # 5
+
+    print(disparity(x, y))  # 0.4
+    print(disparity([v + 5 for v in x], [v + 5 for v in y]))  # 0.4
+    print(disparity([v * 2 for v in x], [v * 2 for v in y]))  # 0.4
+    print(disparity(y, x))  # -0.4
+
+
+if __name__ == "__main__":
+    main()

pragmastat-3.1.6/pragmastat/__init__.py

@@ -0,0 +1,21 @@
+from .estimators import (
+    center,
+    spread,
+    rel_spread,
+    shift,
+    ratio,
+    avg_spread,
+    disparity
+)
+
+__all__ = [
+    'center',
+    'spread',
+    'rel_spread',
+    'shift',
+    'ratio',
+    'avg_spread',
+    'disparity'
+]
+
+__version__ = '3.1.6'

pragmastat-3.1.6/pragmastat/estimators.py

@@ -0,0 +1,71 @@
+from typing import Sequence, Union
+import numpy as np
+from numpy.typing import NDArray
+from .fast_center import _fast_center
+from .fast_spread import _fast_spread
+
+
+def center(x: Union[Sequence[float], NDArray]) -> float:
+    x = np.asarray(x)
+    n = len(x)
+    if n == 0:
+        raise ValueError("Input array cannot be empty")
+    # Use fast O(n log n) algorithm
+    return _fast_center(x.tolist())
+
+
+def spread(x: Union[Sequence[float], NDArray]) -> float:
+    x = np.asarray(x)
+    n = len(x)
+    if n == 0:
+        raise ValueError("Input array cannot be empty")
+    if n == 1:
+        return 0.0
+    # Use fast O(n log n) algorithm
+    return _fast_spread(x.tolist())
+
+
+def rel_spread(x: Union[Sequence[float], NDArray]) -> float:
+    center_val = center(x)
+    if center_val == 0:
+        raise ValueError("RelSpread is undefined when Center equals zero")
+    return spread(x) / abs(center_val)
+
+
+def shift(x: Union[Sequence[float], NDArray], y: Union[Sequence[float], NDArray]) -> float:
+    x = np.asarray(x)
+    y = np.asarray(y)
+    if len(x) == 0 or len(y) == 0:
+        raise ValueError("Input arrays cannot be empty")
+    pairwise_shifts = np.subtract.outer(x, y)
+    return float(np.median(pairwise_shifts))
+
+
+def ratio(x: Union[Sequence[float], NDArray], y: Union[Sequence[float], NDArray]) -> float:
+    x = np.asarray(x)
+    y = np.asarray(y)
+    if len(x) == 0 or len(y) == 0:
+        raise ValueError("Input arrays cannot be empty")
+    if np.any(y <= 0):
+        raise ValueError("All values in y must be strictly positive")
+    pairwise_ratios = np.divide.outer(x, y)
+    return float(np.median(pairwise_ratios))
+
+
+def avg_spread(x: Union[Sequence[float], NDArray], y: Union[Sequence[float], NDArray]) -> float:
+    x = np.asarray(x)
+    y = np.asarray(y)
+    n = len(x)
+    m = len(y)
+    if n == 0 or m == 0:
+        raise ValueError("Input arrays cannot be empty")
+    spread_x = spread(x)
+    spread_y = spread(y)
+    return (n * spread_x + m * spread_y) / (n + m)
+
+
+def disparity(x: Union[Sequence[float], NDArray], y: Union[Sequence[float], NDArray]) -> float:
+    avg_spread_val = avg_spread(x, y)
+    if avg_spread_val == 0:
+        return float('inf')
+    return shift(x, y) / avg_spread_val

pragmastat-3.1.6/pragmastat/fast_center.py

@@ -0,0 +1,215 @@
+"""Fast O(n log n) implementation of the Center (Hodges-Lehmann) estimator.
+
+Based on Monahan's Algorithm 616 (1984).
+"""
+
+from typing import List
+import random
+import numpy as np
+
+# Try to import the C implementation, fall back to pure Python if unavailable
+try:
+    from . import _fast_center_c
+    _HAS_C_EXTENSION = True
+except ImportError:
+    _HAS_C_EXTENSION = False
+
+
+def _fast_center_python(values: List[float]) -> float:
+    """
+    Pure Python implementation of fast center estimator.
+
+    Compute the median of all pairwise averages (xi + xj)/2 efficiently.
+
+    Time complexity: O(n log n) expected
+    Space complexity: O(n)
+
+    Args:
+        values: A list of numeric values
+
+    Returns:
+        The center estimate (Hodges-Lehmann estimator)
+    """
+    n = len(values)
+    if n == 0:
+        raise ValueError("Input array cannot be empty")
+    if n == 1:
+        return values[0]
+    if n == 2:
+        return (values[0] + values[1]) / 2
+
+    # Sort the values
+    sorted_values = sorted(values)
+
+    # Calculate target median rank(s) among all pairwise sums
+    total_pairs = n * (n + 1) // 2
+    median_rank_low = (total_pairs + 1) // 2  # 1-based rank
+    median_rank_high = (total_pairs + 2) // 2
+
+    # Initialize search bounds for each row (1-based indexing)
+    left_bounds = [i + 1 for i in range(n)]  # Row i pairs with columns [i+1..n]
+    right_bounds = [n for i in range(n)]
+
+    # Start with a good pivot: sum of middle elements
+    pivot = sorted_values[(n - 1) // 2] + sorted_values[n // 2]
+    active_set_size = total_pairs
+    previous_count = 0
+
+    while True:
+        # === PARTITION STEP ===
+        # Count pairwise sums less than current pivot
+        count_below_pivot = 0
+        current_column = n
+        partition_counts = []
+
+        for row in range(1, n + 1):  # 1-based
+            # Move left from current column until we find sums < pivot
+            while current_column >= row and sorted_values[row - 1] + sorted_values[current_column - 1] >= pivot:
+                current_column -= 1
+
+            # Count elements in this row that are < pivot
+            elements_below = max(0, current_column - row + 1)
+            partition_counts.append(elements_below)
+            count_below_pivot += elements_below
+
+        # === CONVERGENCE CHECK ===
+        if count_below_pivot == previous_count:
+            # No progress - use midrange strategy
+            min_active_sum = float('inf')
+            max_active_sum = float('-inf')
+
+            for i in range(n):
+                if left_bounds[i] > right_bounds[i]:
+                    continue
+
+                row_value = sorted_values[i]
+                smallest_in_row = sorted_values[left_bounds[i] - 1] + row_value
+                largest_in_row = sorted_values[right_bounds[i] - 1] + row_value
+
+                min_active_sum = min(min_active_sum, smallest_in_row)
+                max_active_sum = max(max_active_sum, largest_in_row)
+
+            pivot = (min_active_sum + max_active_sum) / 2
+            if pivot <= min_active_sum or pivot > max_active_sum:
+                pivot = max_active_sum
+
+            if min_active_sum == max_active_sum or active_set_size <= 2:
+                return pivot / 2
+
+            continue
+
+        # === TARGET CHECK ===
+        at_target_rank = (count_below_pivot == median_rank_low or
+                         count_below_pivot == median_rank_high - 1)
+
+        if at_target_rank:
+            # Find boundary values
+            largest_below_pivot = float('-inf')
+            smallest_at_or_above_pivot = float('inf')
+
+            for i in range(n):
+                count_in_row = partition_counts[i]
+                row_value = sorted_values[i]
+                total_in_row = n - i
+
+                # Find largest sum in this row that's < pivot
+                if count_in_row > 0:
+                    last_below_index = i + count_in_row
+                    last_below_value = row_value + sorted_values[last_below_index - 1]
+                    largest_below_pivot = max(largest_below_pivot, last_below_value)
+
+                # Find smallest sum in this row that's >= pivot
+                if count_in_row < total_in_row:
+                    first_at_or_above_index = i + count_in_row + 1
+                    first_at_or_above_value = row_value + sorted_values[first_at_or_above_index - 1]
+                    smallest_at_or_above_pivot = min(smallest_at_or_above_pivot, first_at_or_above_value)
+
+            # Calculate final result
+            if median_rank_low < median_rank_high:
+                # Even total: average the two middle values
+                return (smallest_at_or_above_pivot + largest_below_pivot) / 4
+            else:
+                # Odd total: return the single middle value
+                need_largest = (count_below_pivot == median_rank_low)
+                return (largest_below_pivot if need_largest else smallest_at_or_above_pivot) / 2
+
+        # === UPDATE BOUNDS ===
+        if count_below_pivot < median_rank_low:
+            # Too few values below pivot - search higher
+            for i in range(n):
+                left_bounds[i] = i + partition_counts[i] + 1
+        else:
+            # Too many values below pivot - search lower
+            for i in range(n):
+                right_bounds[i] = i + partition_counts[i]
+
+        # === PREPARE NEXT ITERATION ===
+        previous_count = count_below_pivot
+
+        # Recalculate active set size
+        active_set_size = sum(max(0, right_bounds[i] - left_bounds[i] + 1) for i in range(n))
+
+        # Choose next pivot
+        if active_set_size > 2:
+            # Use randomized row median strategy
+            target_index = random.randint(0, active_set_size - 1)
+            cumulative_size = 0
+            selected_row = 0
+
+            for i in range(n):
+                row_size = max(0, right_bounds[i] - left_bounds[i] + 1)
+                if target_index < cumulative_size + row_size:
+                    selected_row = i
+                    break
+                cumulative_size += row_size
+
+            # Use median element of the selected row as pivot
+            median_column_in_row = (left_bounds[selected_row] + right_bounds[selected_row]) // 2
+            pivot = sorted_values[selected_row] + sorted_values[median_column_in_row - 1]
+        else:
+            # Few elements remain - use midrange strategy
+            min_remaining_sum = float('inf')
+            max_remaining_sum = float('-inf')
+
+            for i in range(n):
+                if left_bounds[i] > right_bounds[i]:
+                    continue
+
+                row_value = sorted_values[i]
+                min_in_row = sorted_values[left_bounds[i] - 1] + row_value
+                max_in_row = sorted_values[right_bounds[i] - 1] + row_value
+
+                min_remaining_sum = min(min_remaining_sum, min_in_row)
+                max_remaining_sum = max(max_remaining_sum, max_in_row)
+
+            pivot = (min_remaining_sum + max_remaining_sum) / 2
+            if pivot <= min_remaining_sum or pivot > max_remaining_sum:
+                pivot = max_remaining_sum
+
+            if min_remaining_sum == max_remaining_sum:
+                return pivot / 2
+
+
+def _fast_center(values: List[float]) -> float:
+    """
+    Compute the median of all pairwise averages (xi + xj)/2 efficiently.
+
+    Internal implementation - not part of public API.
+    Uses C implementation if available, falls back to pure Python.
+
+    Time complexity: O(n log n) expected
+    Space complexity: O(n)
+
+    Args:
+        values: A list of numeric values
+
+    Returns:
+        The center estimate (Hodges-Lehmann estimator)
+    """
+    if _HAS_C_EXTENSION:
+        # Convert to numpy array and use C implementation
+        arr = np.asarray(values, dtype=np.float64)
+        return _fast_center_c.fast_center_c(arr)
+    else:
+        # Fall back to pure Python implementation
+        return _fast_center_python(values)