Fix histogram

Author: Евгений Блинов

microbenchmark/_render.py

@@ -3,6 +3,19 @@
 import shutil
 from collections.abc import Sequence
 
+_BLOCKS = ' ▁▂▃▄▅▆▇█'
+
+
+def _format_duration(t: float) -> str:
+    """Format *t* seconds into a compact human-readable string."""
+    if t >= 1.0:
+        return f'{t:.3f}s'
+    if t >= 1e-3:
+        return f'{t * 1e3:.2f}ms'
+    if t >= 1e-6:
+        return f'{t * 1e6:.2f}\u03bcs'
+    return f'{t * 1e9:.2f}ns'
+
 
 def terminal_width() -> int:
     """Return the current terminal width, clamped to a minimum of 20."""
@@ -77,22 +90,58 @@ def pad_inner_line(line: str) -> str:
     return result
 
 
+def histogram_bounds(durations: Sequence[float]) -> tuple[float, float]:
+    """Return ``(lo, hi)`` bounds for a histogram: minimum and p99 value.
+
+    The p99 clip prevents extreme outliers from compressing the bulk of the
+    distribution into the leftmost column.
+
+    Args:
+        durations: Sequence of per-call timings in seconds.
+    """
+    sorted_durs = sorted(durations)
+    lo = sorted_durs[0]
+    p99_idx = min(len(sorted_durs) - 1, int(len(sorted_durs) * 0.99))
+    return lo, sorted_durs[p99_idx]
+
+
+def draw_histogram_axis(lo: float, hi: float, width: int) -> str:
+    """Return a single-line x-axis label for a histogram with bounds *lo*/*hi*.
+
+    The minimum value is left-aligned; the p99 clip value is right-aligned.
+    Both are formatted with auto-selected time units (ns / μs / ms / s).
+
+    Args:
+        lo: Minimum value displayed on the x-axis.
+        hi: Maximum value (p99 clip point) displayed on the x-axis.
+        width: Total width of the label in characters.
+    """
+    if width < 1:
+        return ''
+    left = _format_duration(lo)
+    right = _format_duration(hi) + ' (p99)'
+    if len(left) + 1 + len(right) > width:
+        return left[:width]
+    spaces = width - len(left) - len(right)
+    return left + ' ' * spaces + right
+
+
 def draw_histogram(durations: Sequence[float], width: int, height: int) -> list[str]:
     """Render an ASCII bar chart of *durations* as a ``height`` x ``width`` grid.
 
-    The output is ``width`` characters wide and ``height`` rows tall.  Filled
-    cells use ``'█'``; empty cells use ``' '``.  Returns an empty list when any
-    dimension is zero/negative or when *durations* is empty.
+    The output is ``width`` characters wide and ``height`` rows tall.  Each
+    cell uses one of the Unicode block characters ``' ▁▂▃▄▅▆▇█'`` so bar
+    heights are resolved at 1/8-row precision, giving smooth transitions
+    between adjacent buckets.  Returns an empty list when any dimension is
+    zero/negative or when *durations* is empty.
 
     Internally the data is bucketed into at most 20 bins regardless of
     *width*.  Each bin is then rendered as ``width // n_buckets`` characters
-    wide.  This prevents timer-quantisation artefacts (where most measurements
-    snap to a handful of discrete nanosecond values) from producing a single
-    column spike with stray isolated pixels elsewhere.
+    wide.  This prevents timer-quantisation artefacts from producing a single
+    spike with stray isolated pixels.
 
-    The x-axis upper bound is clipped to the p99 value to prevent extreme
-    outliers from compressing the bulk of the distribution.  Values above the
-    p99 clip point are omitted from buckets.
+    The x-axis upper bound is clipped to the p99 value via
+    :func:`histogram_bounds`.  Values above the clip point are omitted.
 
     When all values are identical (``hi == lo``), the middle bin is drawn
     full-height and all others are left empty.
@@ -105,14 +154,10 @@ def draw_histogram(durations: Sequence[float], width: int, height: int) -> list[
     if width < 1 or height < 1 or len(durations) == 0:
         return []
 
-    sorted_durs = sorted(durations)
-    lo = sorted_durs[0]
-    p99_idx = min(len(sorted_durs) - 1, int(len(sorted_durs) * 0.99))
-    hi = sorted_durs[p99_idx]
+    lo, hi = histogram_bounds(durations)
 
-    # Cap the number of data buckets at 20 so that each bucket spans a
-    # visible fraction of the output width and adjacent quantised values are
-    # merged into the same bar.
+    # Cap the number of data buckets at 20 so that adjacent quantised timer
+    # values are merged into the same wider bar.
     n_buckets = min(width, 20)
     counts = [0] * n_buckets
 
@@ -127,16 +172,22 @@ def draw_histogram(durations: Sequence[float], width: int, height: int) -> list[
             counts[idx] += 1
 
     max_count = max(counts)
-    bar_heights = [
-        round(c / max_count * height) if c > 0 else 0
+    bar_heights_float = [
+        c / max_count * height if c > 0 else 0.0
         for c in counts
     ]
 
     rows: list[str] = []
     for row in range(height - 1, -1, -1):
-        line = ''.join(
-            '█' if bar_heights[col * n_buckets // width] > row else ' '
-            for col in range(width)
-        )
-        rows.append(line)
+        line_chars: list[str] = []
+        for col in range(width):
+            bh = bar_heights_float[col * n_buckets // width]
+            if bh >= row + 1:
+                line_chars.append('█')
+            elif bh > row:
+                frac = bh - row
+                line_chars.append(_BLOCKS[max(1, min(8, round(frac * 8)))])
+            else:
+                line_chars.append(' ')
+        rows.append(''.join(line_chars))
     return rows

microbenchmark/scenario.py

@@ -9,7 +9,13 @@
 from printo.reprs import superrepr
 from sigmatch import SignatureMismatchError
 
-from microbenchmark._render import draw_box, draw_histogram, terminal_width
+from microbenchmark._render import (
+    draw_box,
+    draw_histogram,
+    draw_histogram_axis,
+    histogram_bounds,
+    terminal_width,
+)
 from microbenchmark.arguments import arguments as Arguments  # noqa: N812
 from microbenchmark.benchmark_result import BenchmarkResult
 
@@ -105,8 +111,11 @@ def cli(self, argv: list[str] | None = None) -> None:
         width = terminal_width()
         lines = _render_result(result)
         if cli_args.histogram:
+            hist_width = width - 4
             lines.append('')
-            lines.extend(draw_histogram(list(result.durations), width - 4, 8))
+            lines.extend(draw_histogram(list(result.durations), hist_width, 8))
+            lo, hi = histogram_bounds(result.durations)
+            lines.append(draw_histogram_axis(lo, hi, hist_width))
         box = draw_box(lines, width)
         sys.stdout.write('\n'.join(box) + '\n')
 

microbenchmark/scenario_group.py

@@ -3,7 +3,14 @@
 import argparse
 import sys
 
-from microbenchmark._render import draw_box, draw_histogram, draw_nested, terminal_width
+from microbenchmark._render import (
+    draw_box,
+    draw_histogram,
+    draw_histogram_axis,
+    draw_nested,
+    histogram_bounds,
+    terminal_width,
+)
 from microbenchmark.benchmark_result import BenchmarkResult
 from microbenchmark.scenario import Scenario, _render_result
 
@@ -51,8 +58,11 @@ def cli(self, argv: list[str] | None = None) -> None:
             results.append(result)
             lines = _render_result(result)
             if cli_args.histogram:
+                hist_width = inner_width - 4
                 lines.append('')
-                lines.extend(draw_histogram(list(result.durations), inner_width - 4, 8))
+                lines.extend(draw_histogram(list(result.durations), hist_width, 8))
+                lo, hi = histogram_bounds(result.durations)
+                lines.append(draw_histogram_axis(lo, hi, hist_width))
             inner_blocks.append(draw_box(lines, inner_width))
 
         nested = draw_nested(inner_blocks, [], width)

tests/typing/test_render_types.py

@@ -2,7 +2,14 @@
 
 import pytest
 
-from microbenchmark._render import draw_box, draw_histogram, draw_nested, terminal_width
+from microbenchmark._render import (
+    draw_box,
+    draw_histogram,
+    draw_histogram_axis,
+    draw_nested,
+    histogram_bounds,
+    terminal_width,
+)
 
 
 @pytest.mark.mypy_testing
@@ -27,3 +34,15 @@ def test_draw_nested_returns_list_of_str():
 def test_draw_histogram_returns_list_of_str():
     result = draw_histogram([0.001, 0.002], 10, 4)
     reveal_type(result)  # N: Revealed type is "builtins.list[builtins.str]"
+
+
+@pytest.mark.mypy_testing
+def test_histogram_bounds_returns_tuple():
+    result = histogram_bounds([0.001, 0.002])
+    reveal_type(result)  # N: Revealed type is "tuple[builtins.float, builtins.float]"
+
+
+@pytest.mark.mypy_testing
+def test_draw_histogram_axis_returns_str():
+    result = draw_histogram_axis(0.000005, 0.000006, 40)
+    reveal_type(result)  # N: Revealed type is "builtins.str"

tests/units/test_render.py

@@ -6,7 +6,14 @@
 import sys
 import textwrap
 
-from microbenchmark._render import draw_box, draw_histogram, draw_nested, terminal_width
+from microbenchmark._render import (
+    draw_box,
+    draw_histogram,
+    draw_histogram_axis,
+    draw_nested,
+    histogram_bounds,
+    terminal_width,
+)
 
 _UTF8_ENV = {**os.environ, 'PYTHONUTF8': '1'}
 
@@ -253,6 +260,100 @@ def fake_timer():
     assert proc.stdout.count('╰') >= 3
 
 
+# ---------------------------------------------------------------------------
+# histogram_bounds
+# ---------------------------------------------------------------------------
+
+
+def test_histogram_bounds_returns_tuple():
+    lo, hi = histogram_bounds([0.001, 0.002, 0.003])
+
+    assert isinstance(lo, float)
+    assert isinstance(hi, float)
+
+
+def test_histogram_bounds_lo_is_min():
+    lo, _ = histogram_bounds([0.003, 0.001, 0.002])
+
+    assert lo == 0.001
+
+
+def test_histogram_bounds_hi_is_p99():
+    # 200 values; p99_idx = int(200 * 0.99) = 198 → sorted[198]
+    durs = [i * 0.001 for i in range(1, 201)]
+    _, hi = histogram_bounds(durs)
+
+    assert hi == durs[198]
+
+
+def test_histogram_bounds_single_value():
+    lo, hi = histogram_bounds([0.005])
+
+    assert lo == hi == 0.005
+
+
+# ---------------------------------------------------------------------------
+# draw_histogram_axis
+# ---------------------------------------------------------------------------
+
+
+def test_draw_histogram_axis_returns_str():
+    result = draw_histogram_axis(0.000005, 0.000006, 40)
+
+    assert isinstance(result, str)
+
+
+def test_draw_histogram_axis_width_matches():
+    width = 40
+    result = draw_histogram_axis(0.000005, 0.000006, width)
+
+    assert len(result) == width
+
+
+def test_draw_histogram_axis_contains_left_label():
+    result = draw_histogram_axis(0.000005, 0.000006, 40)
+
+    assert '5.00\u03bcs' in result
+
+
+def test_draw_histogram_axis_contains_right_label():
+    result = draw_histogram_axis(0.000005, 0.000006, 40)
+
+    assert 'p99' in result
+    assert '6.00\u03bcs' in result
+
+
+def test_draw_histogram_axis_units_ns():
+    result = draw_histogram_axis(1e-10, 2e-10, 40)
+
+    assert 'ns' in result
+
+
+def test_draw_histogram_axis_units_ms():
+    result = draw_histogram_axis(0.001, 0.002, 40)
+
+    assert 'ms' in result
+
+
+def test_draw_histogram_axis_units_s():
+    result = draw_histogram_axis(1.5, 2.0, 40)
+
+    assert 's' in result
+
+
+def test_draw_histogram_axis_zero_width_returns_empty():
+    result = draw_histogram_axis(0.000005, 0.000006, 0)
+
+    assert result == ''
+
+
+def test_draw_histogram_axis_truncates_when_too_narrow():
+    # width smaller than left label + space + right label → fallback to left only
+    result = draw_histogram_axis(0.000005, 0.000006, 5)
+
+    assert len(result) == 5
+
+
 # ---------------------------------------------------------------------------
 # draw_histogram
 # ---------------------------------------------------------------------------
@@ -338,12 +439,25 @@ def test_draw_histogram_all_equal_height_matches():
     assert all(len(row) == 11 for row in result)
 
 
-def test_draw_histogram_only_block_or_space():
+def test_draw_histogram_only_valid_chars():
+    # Cells may be full block, one of seven partial-fill blocks, or space.
     result = draw_histogram([0.001, 0.002, 0.003], 10, 4)
+    valid = set(' \u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588')
 
     for row in result:
         for ch in row:
-            assert ch in ('█', ' ')
+            assert ch in valid
+
+
+def test_draw_histogram_partial_blocks_appear():
+    # With non-equal bucket counts the tallest bar fills height=5 rows and a
+    # shorter bar gets a fractional top row rendered as a partial block.
+    # counts → [4, 0, ..., 0, 3]: height_float for bucket-9 = 3/4 * 5 = 3.75
+    result = draw_histogram([0.001] * 4 + [0.003] * 3, 10, 5)
+    all_text = ''.join(result)
+    partial = '\u2581\u2582\u2583\u2584\u2585\u2586\u2587'
+
+    assert any(ch in partial for ch in all_text)
 
 
 def test_draw_histogram_strings_in_list():