#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""A text-based simple histogram helper class."""
import math
-from numbers import Number
-from typing import Generic, Iterable, List, Optional, Tuple, TypeVar
+from dataclasses import dataclass
+from typing import Dict, Generic, Iterable, List, Optional, Tuple, TypeVar
+
+T = TypeVar("T", int, float)
+Bound = int
+Count = int
+
-T = TypeVar("T", bound=Number)
+@dataclass
+class BucketDetails:
+ """A collection of details about the internal histogram buckets."""
+
+ num_populated_buckets: int = 0
+ max_population: Optional[int] = None
+ last_bucket_start: Optional[int] = None
+ lowest_start: Optional[int] = None
+ highest_end: Optional[int] = None
+ max_label_width: Optional[int] = None
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[T, T]]):
- from math_utils import RunningMedian
- self.buckets = {}
+ def __init__(self, buckets: List[Tuple[Bound, Bound]]):
+ from math_utils import NumericPopulation
+
+ self.buckets: Dict[Tuple[Bound, Bound], Count] = {}
for start_end in buckets:
if self._get_bucket(start_end[0]) is not None:
raise Exception("Buckets overlap?!")
self.buckets[start_end] = 0
- self.sigma = 0
- self.median = RunningMedian()
- self.maximum = None
- self.minimum = None
- self.count = 0
+ self.sigma: float = 0.0
+ self.stats: NumericPopulation = NumericPopulation()
+ self.maximum: Optional[T] = None
+ self.minimum: Optional[T] = None
+ self.count: Count = 0
@staticmethod
def n_evenly_spaced_buckets(
- min_bound: T,
- max_bound: T,
- n: int,
- ) -> List[Tuple[T, T]]:
- ret = []
+ min_bound: T,
+ max_bound: T,
+ n: int,
+ ) -> List[Tuple[int, int]]:
+ ret: List[Tuple[int, int]] = []
stride = int((max_bound - min_bound) / n)
if stride <= 0:
raise Exception("Min must be < Max")
- for bucket_start in range(min_bound, max_bound, stride):
+ imax = math.ceil(max_bound)
+ imin = math.floor(min_bound)
+ for bucket_start in range(imin, imax, stride):
ret.append((bucket_start, bucket_start + stride))
return ret
- def _get_bucket(self, item: T) -> Optional[Tuple[T, T]]:
+ def _get_bucket(self, item: T) -> Optional[Tuple[int, int]]:
for start_end in self.buckets:
if start_end[0] <= item < start_end[1]:
return start_end
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:
all_true = all_true and self.add_item(item)
return all_true
- def __repr__(self,
- label_formatter='%10s') -> str:
- from text_utils import bar_graph
- max_population: Optional[int] = None
- for bucket in self.buckets:
- pop = self.buckets[bucket]
+ def get_bucket_details(self, label_formatter: str) -> BucketDetails:
+ details = BucketDetails()
+ for (start, end), pop in sorted(self.buckets.items(), key=lambda x: x[0]):
if pop > 0:
- last_bucket_start = bucket[0]
- if max_population is None or pop > max_population:
- max_population = pop
+ 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:
+ from text_utils import bar_graph
+
+ details = self.get_bucket_details(label_formatter)
txt = ""
- if max_population is None:
+ if details.num_populated_buckets == 0:
return txt
+ 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}): ' % (
+ details.lowest_start,
+ details.highest_end,
+ )
+ 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]):
- pop = self.buckets[bucket]
- 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)
bar = bar_graph(
- (pop / max_population),
- include_text = False,
- width = 58,
- left_end = "",
- right_end = "")
- label = f'{label_formatter}..{label_formatter}' % (start, end)
- txt += f'{label:20}: ' + bar + f"({pop/self.count*100.0:5.2f}% n={pop})\n"
- if start == last_bucket_start:
+ (pop / details.max_population),
+ include_text=False,
+ width=bar_width,
+ left_end="",
+ right_end="",
+ )
+ txt += label.rjust(details.max_label_width)
+ txt += bar
+ txt += f"({pop/self.count*100.0:5.2f}% n={pop})\n"
+ if start == details.last_bucket_start:
break
+ txt += '-' * width + '\n'
+ txt += sigma_label.rjust(details.max_label_width)
+ txt += ' ' * (bar_width - 2)
+ 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