X-Git-Url: https://wannabe.guru.org/gitweb/?a=blobdiff_plain;f=histogram.py;h=86d0493dc57e32056c4eb04ec4499992d365e542;hb=02302bbd9363facb59c4df2c1f4013087702cfa6;hp=d45e93f328185f869c2b3af4cc832db280d14428;hpb=a4bf4d05230474ad14243d67ac7f8c938f670e58;p=python_utils.git

diff --git a/histogram.py b/histogram.py
index d45e93f..86d0493 100644
--- a/histogram.py
+++ b/histogram.py
@@ -1,7 +1,12 @@
 #!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+# © Copyright 2021-2022, Scott Gasch
+
+"""A text-based simple histogram helper class."""
 
 import math
-from numbers import Number
+from dataclasses import dataclass
 from typing import Dict, Generic, Iterable, List, Optional, Tuple, TypeVar
 
 T = TypeVar("T", int, float)
@@ -9,13 +14,46 @@ Bound = int
 Count = int
 
 
+@dataclass
+class BucketDetails:
+    """A collection of details about the internal histogram buckets."""
+
+    num_populated_buckets: int = 0
+    """Count of populated buckets"""
+
+    max_population: Optional[int] = None
+    """The max population in a bucket currently"""
+
+    last_bucket_start: Optional[int] = None
+    """The last bucket starting point"""
+
+    lowest_start: Optional[int] = None
+    """The lowest populated bucket's starting point"""
+
+    highest_end: Optional[int] = None
+    """The highest populated bucket's ending point"""
+
+    max_label_width: Optional[int] = None
+    """The maximum label width (for display purposes)"""
+
+
 class SimpleHistogram(Generic[T]):
+    """A simple histogram."""
+
     # Useful in defining wide open bottom/top bucket bounds:
     POSITIVE_INFINITY = math.inf
     NEGATIVE_INFINITY = -math.inf
 
     def __init__(self, buckets: List[Tuple[Bound, Bound]]):
-        from math_utils import RunningMedian
+        """C'tor.
+
+        Args:
+            buckets: a list of [start..end] tuples that define the
+                buckets we are counting population in.  See also
+                :meth:`n_evenly_spaced_buckets` to generate these
+                buckets more easily.
+        """
+        from math_utils import NumericPopulation
 
         self.buckets: Dict[Tuple[Bound, Bound], Count] = {}
         for start_end in buckets:
@@ -23,7 +61,7 @@ class SimpleHistogram(Generic[T]):
                 raise Exception("Buckets overlap?!")
             self.buckets[start_end] = 0
         self.sigma: float = 0.0
-        self.median: RunningMedian = RunningMedian()
+        self.stats: NumericPopulation = NumericPopulation()
         self.maximum: Optional[T] = None
         self.minimum: Optional[T] = None
         self.count: Count = 0
@@ -34,6 +72,17 @@ class SimpleHistogram(Generic[T]):
         max_bound: T,
         n: int,
     ) -> List[Tuple[int, int]]:
+        """A helper method for generating the buckets argument to
+        our c'tor provided that you want N evenly spaced buckets.
+
+        Args:
+            min_bound: the minimum possible value
+            max_bound: the maximum possible value
+            n: how many buckets to create
+
+        Returns:
+            A list of bounds that define N evenly spaced buckets
+        """
         ret: List[Tuple[int, int]] = []
         stride = int((max_bound - min_bound) / n)
         if stride <= 0:
@@ -45,19 +94,30 @@ class SimpleHistogram(Generic[T]):
         return ret
 
     def _get_bucket(self, item: T) -> Optional[Tuple[int, int]]:
+        """Given an item, what bucket is it in?"""
         for start_end in self.buckets:
             if start_end[0] <= item < start_end[1]:
                 return start_end
         return None
 
     def add_item(self, item: T) -> bool:
+        """Adds a single item to the histogram (reculting in us incrementing
+        the population in the correct bucket.
+
+        Args:
+            item: the item to be added
+
+        Returns:
+            True if the item was successfully added or False if the item
+            is not within the bounds established during class construction.
+        """
         bucket = self._get_bucket(item)
         if bucket is None:
             return False
         self.count += 1
         self.buckets[bucket] += 1
         self.sigma += item
-        self.median.add_number(item)
+        self.stats.add_number(item)
         if self.maximum is None or item > self.maximum:
             self.maximum = item
         if self.minimum is None or item < self.minimum:
@@ -65,72 +125,91 @@ class SimpleHistogram(Generic[T]):
         return True
 
     def add_items(self, lst: Iterable[T]) -> bool:
+        """Adds a collection of items to the histogram and increments
+        the correct bucket's population for each item.
+
+        Args:
+            lst: An iterable of items to be added
+
+        Returns:
+            True if all items were added successfully or False if any
+            item was not able to be added because it was not within the
+            bounds established at object construction.
+        """
         all_true = True
         for item in lst:
             all_true = all_true and self.add_item(item)
         return all_true
 
+    def _get_bucket_details(self, label_formatter: str) -> BucketDetails:
+        """Get the details about one bucket."""
+        details = BucketDetails()
+        for (start, end), pop in sorted(self.buckets.items(), key=lambda x: x[0]):
+            if pop > 0:
+                details.num_populated_buckets += 1
+                details.last_bucket_start = start
+                if details.max_population is None or pop > details.max_population:
+                    details.max_population = pop
+                if details.lowest_start is None or start < details.lowest_start:
+                    details.lowest_start = start
+                if details.highest_end is None or end > details.highest_end:
+                    details.highest_end = end
+                label = f'[{label_formatter}..{label_formatter}): ' % (start, end)
+                label_width = len(label)
+                if details.max_label_width is None or label_width > details.max_label_width:
+                    details.max_label_width = label_width
+        return details
+
     def __repr__(self, *, width: int = 80, label_formatter: str = '%d') -> str:
+        """Returns a pretty (text) representation of the histogram and
+        some vital stats about the population in it (min, max, mean,
+        median, mode, stdev, etc...)
+        """
         from text_utils import bar_graph
 
+        details = self._get_bucket_details(label_formatter)
         txt = ""
-        max_population: Optional[int] = None
-        for bucket in self.buckets:
-            pop = self.buckets[bucket]
-            if pop > 0:
-                last_bucket_start = bucket[0]  # beginning of range
-            if max_population is None or pop > max_population:
-                max_population = pop  # bucket with max items
-        if max_population is None:
+        if details.num_populated_buckets == 0:
             return txt
-
-        max_label_width: Optional[int] = None
-        lowest_start: Optional[int] = None
-        highest_end: Optional[int] = None
-        for bucket in sorted(self.buckets, key=lambda x: x[0]):
-            start = bucket[0]
-            if lowest_start is None:
-                lowest_start = start
-            end = bucket[1]
-            if highest_end is None or end > highest_end:
-                highest_end = end
-            label = f'[{label_formatter}..{label_formatter}): ' % (start, end)
-            label_width = len(label)
-            if max_label_width is None or label_width > max_label_width:
-                max_label_width = label_width
-            if start == last_bucket_start:
-                break
-        assert max_label_width
-        assert lowest_start
-        assert highest_end
-
+        assert details.max_label_width is not None
+        assert details.lowest_start is not None
+        assert details.highest_end is not None
+        assert details.max_population is not None
         sigma_label = f'[{label_formatter}..{label_formatter}): ' % (
-            lowest_start,
-            highest_end,
+            details.lowest_start,
+            details.highest_end,
         )
-        if len(sigma_label) > max_label_width:
-            max_label_width = len(sigma_label)
-        bar_width = width - (max_label_width + 16)
+        if len(sigma_label) > details.max_label_width:
+            details.max_label_width = len(sigma_label)
+        bar_width = width - (details.max_label_width + 17)
 
-        for bucket in sorted(self.buckets, key=lambda x: x[0]):
-            start = bucket[0]
-            end = bucket[1]
+        for (start, end), pop in sorted(self.buckets.items(), key=lambda x: x[0]):
+            if start < details.lowest_start:
+                continue
             label = f'[{label_formatter}..{label_formatter}): ' % (start, end)
-            pop = self.buckets[bucket]
             bar = bar_graph(
-                (pop / max_population),
+                (pop / details.max_population),
                 include_text=False,
                 width=bar_width,
                 left_end="",
                 right_end="",
             )
-            txt += label.rjust(max_label_width)
+            txt += label.rjust(details.max_label_width)
             txt += bar
             txt += f"({pop/self.count*100.0:5.2f}% n={pop})\n"
-            if start == last_bucket_start:
+            if start == details.last_bucket_start:
                 break
         txt += '-' * width + '\n'
-        txt += sigma_label.rjust(max_label_width)
+        txt += sigma_label.rjust(details.max_label_width)
         txt += ' ' * (bar_width - 2)
-        txt += f'Σ=(100.00% n={self.count})\n'
+        txt += f'     pop(Σn)={self.count}\n'
+        txt += ' ' * (bar_width + details.max_label_width - 2)
+        txt += f'     mean(x̄)={self.stats.get_mean():.3f}\n'
+        txt += ' ' * (bar_width + details.max_label_width - 2)
+        txt += f' median(p50)={self.stats.get_median():.3f}\n'
+        txt += ' ' * (bar_width + details.max_label_width - 2)
+        txt += f'    mode(Mo)={self.stats.get_mode()[0]:.3f}\n'
+        txt += ' ' * (bar_width + details.max_label_width - 2)
+        txt += f'    stdev(σ)={self.stats.get_stdev():.3f}\n'
+        txt += '\n'
         return txt