densitty 0.8.2__py3-none-any.whl → 0.9.0__py3-none-any.whl

densitty/axis.py

@@ -4,15 +4,10 @@ import dataclasses
 from decimal import Decimal
 import itertools
 import math
-from typing import Optional
+from typing import Optional, Sequence
 
-from . import lineart
-from .util import FloatLike, ValueRange, pick_step_size
-
-MIN_X_TICKS_PER_LABEL = 4
-MIN_Y_TICKS_PER_LABEL = 2
-DEFAULT_X_COLS_PER_TICK = 4
-DEFAULT_Y_ROWS_PER_TICK = 2
+from . import lineart, util
+from .util import FloatLike, ValueRange
 
 
 @dataclasses.dataclass
@@ -31,16 +26,63 @@ x_border = {False: BorderChars(" ", " ", " "), True: BorderChars("╶", "─", "
 # Helper functions used by the Axis class below
 
 
-def add_label(line: list[str], label: str, ctr_pos: int):
+def pick_step_size(lower_bound) -> Decimal:
+    """Try to pick a step size that gives nice round values for step positions."""
+    if lower_bound <= 0:
+        raise ValueError("pick_step_size called with 0 or negative value")
+
+    _, frac, exp = util.sfrexp10(lower_bound)  # 0.1 <= frac < 1.0
+
+    # round up to an appropriate "round" value that starts with 1/2/5
+    if frac <= Decimal("0.2"):
+        out = Decimal((0, (2,), exp - 1))
+    elif frac <= Decimal("0.5"):
+        out = Decimal((0, (5,), exp - 1))
+    else:
+        out = Decimal((0, (1,), exp))
+
+    if out >= 10:
+        # this will be printed as 1E1 or such. Give it more significant figures so
+        # it is printed as an integer:
+        return out.quantize(1)
+    return out
+
+
+def add_x_label(line: list[str], label: str, ctr_pos: FloatLike):
     """Adds the label string to the output line, centered at specified position
     The output line is a list of single-character strings, to make this kind of thing
     straightforward"""
     width = len(label)
-    start_col = max(ctr_pos - width // 2, 0)
+    start_col = int(max(float(ctr_pos) + 0.49 - width / 2, 0))
     end_col = start_col + width
     line[start_col:end_col] = list(label)
 
 
+def add_x_tick(line: list[str], start_pos: float, left_margin: int, num_cols: int):
+    """Adds a (possibly fractional) tick to the output line, centered at specified position"""
+    base_idx = int(start_pos)
+    fractional_pos = start_pos - base_idx
+    margined_idx = base_idx + left_margin
+    if 0.25 <= fractional_pos <= 0.75:
+        # add a tick in the center of the appropriate bin
+        line[margined_idx] = lineart.merge_chars("│", line[margined_idx])
+        return
+    if fractional_pos < 0.25:
+        left_idx = max(margined_idx - 1, 0)
+    else:
+        left_idx = margined_idx
+
+    if base_idx == 0:
+        line[left_idx] = lineart.merge_chars("│", line[left_idx])
+    else:
+        line[left_idx] = "╱"
+
+    if base_idx >= num_cols - 1:
+        line[left_idx + 1] = lineart.merge_chars("│", line[left_idx + 1])
+    else:
+        line[left_idx + 1] = "╲"
+
+
 def gen_tick_values(value_range, tick_step):
     """Produce tick values in the specified range. Basically numpy.arange"""
 
@@ -50,29 +92,136 @@ def gen_tick_values(value_range, tick_step):
         tick += tick_step
 
 
-def gen_labels(
-    value_range: ValueRange, num_ticks, min_ticks_per_label, fmt, label_end_ticks=False
+def filter_labels(labels: dict, values_to_print: Sequence):
+    """Remove printed value with empty string (just a tick) for any
+    labels that aren't in values_to_print"""
+
+    return {k: v if k in values_to_print else "" for k, v in labels.items()}
+
+
+def calc_min_step(
+    value_range: ValueRange,
+    bin_width: FloatLike,
+    accomodate_values: bool,
+    tick_space: int,
+    fmt: str,
 ):
-    """Generate positions for labels (plain ticks & ticks with value)"""
-    tick_step, label_step = pick_step_size(value_range, num_ticks, min_ticks_per_label)
+    """Calculate minimum step size for tick placement.
 
-    ticks = list(gen_tick_values(value_range, tick_step))
-    label_values = list(gen_tick_values(value_range, label_step))
-    if label_end_ticks or len(label_values) <= 2:
-        # ensure that first & last ticks have labels:
-        if label_values[0] != ticks[0]:
-            label_values = ticks[:1] + label_values
-        if label_values[-1] != ticks[-1]:
-            label_values += ticks[-1:]
+    When accomodate_values is True, considers the width of printed labels.
+    Otherwise, only considers tick spacing requirements.
+    """
+    if accomodate_values:
+        # find a representative printed label width to use for basic calculations
+        test_tick_step = pick_step_size((value_range.max - value_range.min) / 5)
+        test_values_printed = tuple(
+            fmt.format(value) for value in gen_tick_values(value_range, test_tick_step)
+        )
+        widths_in_bins = tuple(len(p) for p in test_values_printed)
+        # get the 3'd lowest width, or highest if there are less than 3 due to tick-step roundup:
+        example_width = sorted(widths_in_bins)[:3][-1]
+        min_printed_step = (example_width + 1) * bin_width
+        # If the printed labels are small (single-digit), the ticks themselves might be the
+        # limiting factor, especially if they are X-axis fractional ticks like "/\"
+        return max(min_printed_step, bin_width * (2 + tick_space * 2))
+    return bin_width * (2 + tick_space)
 
-    # sanity: if all but one ticks have labels, just label them all
-    if len(label_values) >= len(ticks) - 1:
-        label_values = ticks
 
-    ticks_only = {value: "" for value in ticks}
-    labeled_ticks = {value: fmt.format(value) for value in label_values}
+def gen_label_subsets(positions: tuple, tick_step: Decimal) -> list[tuple]:
+    """Generate candidate label subsets based on tick step digit.
 
-    return ticks_only | labeled_ticks
+    For tick steps starting with 1 or 2: generates every-5th subsets (5 variants).
+    For tick steps starting with 5: generates every-2nd subsets (2 variants).
+    """
+    step_digit = tick_step.as_tuple().digits[0]  # leading digit of tick step: 1, 2, or 5
+
+    # we want to pick different label subsets depending on whether we're advancing by
+    # 1eX, 2eX, or 5eX:
+    label_subsets = []
+    if step_digit in (1, 2):
+        # print on every fifth label, starting at 0..4
+        label_subsets += list(positions[start::5] for start in range(5))
+    elif step_digit in (1, 5):
+        # print on every second label, starting at 0 or 1
+        label_subsets += list(positions[start::2] for start in range(2))
+    return label_subsets
+
+
+def label_ends_only(labels, positions, tick_step, bin_width, accomodate_values):
+    """See if printing just the labels for the first and last ticks will fit"""
+
+    if not accomodate_values:
+        # For Y axis / we don't care about printed widths
+        return labels
+
+    half_len_a = len(labels[positions[0]]) // 2
+    half_len_b = (len(labels[positions[-1]]) + 1) // 2
+    space_available = math.floor(tick_step / bin_width)
+
+    if half_len_a + half_len_b <= space_available:
+        # We can fit values on the first and last ticks
+        return filter_labels(labels, (positions[0], positions[-1]))
+
+    # Not enough space to print two values, so just print the first
+    return filter_labels(labels, positions[0:1])
+
+
+def find_fitting_subset(label_subsets, labels, tick_step, bin_width, accomodate_values):
+    """Find roundest label subset that fits within space constraints"""
+    for label_subset in util.roundness_ordered(label_subsets):
+        if not accomodate_values:
+            return filter_labels(labels, label_subset)
+        # We're printing at most one value for every 2 ticks, so just make sure
+        # that the printed values will not run over the adjacent ticks' area
+        # Given the initial min_step logic, this will likely always be true
+        allowed_width = tick_step / bin_width * 2 - 2
+        max_printed_width = max(len(labels[k]) for k in label_subset)
+        if max_printed_width <= allowed_width:
+            return filter_labels(labels, label_subset)
+    return None
+
+
+def gen_full_labels(value_range: ValueRange, num_bins, accomodate_values, tick_space, fmt):
+    """Generate positions for labels (plain ticks & ticks with value)"""
+    bin_width = (value_range.max - value_range.min) / num_bins
+
+    if bin_width <= 0:
+        # we don't have a sensible range for the axis values, so just have empty ticks
+        return {}
+
+    min_step = calc_min_step(value_range, bin_width, accomodate_values, tick_space, fmt)
+    cur_tick_step = pick_step_size(min_step)
+
+    while True:
+        labels = {
+            value: fmt.format(value) for value in gen_tick_values(value_range, cur_tick_step)
+        }
+        positions = tuple(labels.keys())
+
+        if len(labels) == 0:
+            # No suitable ticks/labels.
+            if accomodate_values:
+                # Printed value labels won't fit, try without them
+                return gen_full_labels(value_range, num_bins, False, tick_space, "")
+            # Nothing fits
+            return {}
+        if len(labels) == 1:
+            return labels
+
+        label_subsets = gen_label_subsets(positions, cur_tick_step)
+
+        # Check to see if all generated label subsets only have a single entry
+        if max(len(subset) for subset in label_subsets) == 1:
+            # Try to just label the ends:
+            return label_ends_only(labels, positions, cur_tick_step, bin_width, accomodate_values)
+
+        result = find_fitting_subset(
+            label_subsets, labels, cur_tick_step, bin_width, accomodate_values
+        )
+        if result is not None:
+            return result
+
+        cur_tick_step = pick_step_size(float(cur_tick_step) * 1.01)
 
 
 def calc_edges(value_range, num_bins, values_are_edges):
@@ -88,7 +237,7 @@ def calc_edges(value_range, num_bins, values_are_edges):
     values_are_edges: bool
                  Indicates that value_range specifies outside edges rather than bin centers
     """
-    if values_are_edges:
+    if values_are_edges or num_bins == 1:
         bin_delta = (value_range.max - value_range.min) / num_bins
         first_bin_min = value_range.min
     else:
@@ -137,10 +286,11 @@ class Axis:
     def _unjustified_y_axis(self, num_rows: int):
         """Returns the Y axis string for each line of the plot"""
         if self.labels is None:
-            labels = gen_labels(
+            labels = gen_full_labels(
                 self.value_range,
-                num_rows // DEFAULT_Y_ROWS_PER_TICK,
-                MIN_Y_TICKS_PER_LABEL,
+                num_rows,
+                False,
+                0,
                 self.label_fmt,
             )
         else:
@@ -215,14 +365,9 @@ class Axis:
         left_margin: int
                      chars to the left of leftmost data col. May have Labels/border-line.
         """
-
         if self.labels is None:
-            labels = gen_labels(
-                self.value_range,
-                num_cols // DEFAULT_X_COLS_PER_TICK,
-                MIN_X_TICKS_PER_LABEL,
-                self.label_fmt,
-            )
+            tick_space = 1 if self.fractional_tick_pos else 0
+            labels = gen_full_labels(self.value_range, num_cols, True, tick_space, self.label_fmt)
         else:
             labels = self.labels
 
@@ -242,23 +387,15 @@ class Axis:
         for col_idx, (col_min, col_max) in enumerate(bins):
             # use Decimal.next_plus to accomodate rounding error/truncation
             if label_values and col_min <= label_values[0] <= col_max.next_plus():
-                add_label(label_line, labels[label_values[0]], col_idx + left_margin)
-                tick_idx = left_margin + col_idx
-                offset_frac = (label_values[0] - col_min) / (col_max - col_min)
-                if self.fractional_tick_pos and offset_frac < 0.25:
-                    if col_idx == 0:
-                        tick_line[tick_idx - 1] = lineart.merge_chars("│", tick_line[tick_idx - 1])
-                    else:
-                        tick_line[tick_idx - 1] = "╱"
-                    tick_line[tick_idx] = "╲"
-                elif self.fractional_tick_pos and offset_frac > 0.75:
-                    tick_line[tick_idx] = "╱"
-                    if col_idx < num_cols - 1:
-                        tick_line[tick_idx + 1] = "╲"
-                    else:
-                        tick_line[tick_idx + 1] = lineart.merge_chars("│", tick_line[tick_idx + 1])
+                if self.fractional_tick_pos:
+                    offset_frac = (label_values[0] - col_min) / (col_max - col_min)
                 else:
-                    tick_line[tick_idx] = lineart.merge_chars("│", tick_line[tick_idx])
+                    offset_frac = 0.5  # not doing fractional tick positioning == center the tick
+
+                add_x_tick(tick_line, col_idx + offset_frac, left_margin, num_cols)
+                add_x_label(
+                    label_line, labels[label_values[0]], col_idx + left_margin + offset_frac
+                )
 
                 label_values = label_values[1:]  # pop that first label since we added it
 

densitty/binning.py

@@ -3,11 +3,12 @@
 import math
 from bisect import bisect_right
 from decimal import Decimal
+from fractions import Fraction
 from typing import Optional, Sequence
 
 from .axis import Axis
 from .util import FloatLike, ValueRange
-from .util import clamp, decimal_value_range, most_round, round_up_ish
+from .util import clamp, make_decimal, make_value_range, most_round, round_up_ish
 
 
 def bin_edges(
@@ -45,17 +46,21 @@ def calc_value_range(values: Sequence[FloatLike]) -> ValueRange:
     """Calculate a value range from data values"""
     if not values:
         # Could raise an exception here, but for now just return _something_
-        return ValueRange(0, 1)
+        return make_value_range((0, 1))
 
     # bins are closed on left and open on right: i.e. left_edge <= values < right_edge
     # so, the right-most bin edge needs to be larger than the largest data value:
     max_value = max(values)
-    range_top = max_value + math.ulp(max_value)  # increase by smallest representable amount
-    return ValueRange(min(values), range_top)
+    min_value = min(values)
+    data_value_range = make_value_range((min_value, max_value))
+    range_top = data_value_range.max + Decimal(
+        math.ulp(data_value_range.max)
+    )  # increase by smallest representable amount
+    return ValueRange(data_value_range.min, range_top)
 
 
-def pick_edges(
-    num_bins: int,
+def segment_interval(
+    num_outputs: int,
     value_range: ValueRange,
     align=True,
 ) -> Sequence[FloatLike]:
@@ -64,43 +69,52 @@ def pick_edges(
     Parameters
     ----------
     values: Sequence of data values
-    num_bins: int
-              Number of bins to partition into
+    num_outputs: int
+              Number of output values
     value_range: ValueRange
-              Min/Max of the values to be binned
+              Min/Max of the output values
     align: bool
               Adjust the range somewhat to put bin size & edges on "round" values
     """
-    value_range = decimal_value_range(value_range)  # coerce into Decimal if not already
+    value_range = make_value_range(value_range)  # coerce into Decimal if not already
+    assert isinstance(value_range.min, Decimal)  # make the type-checker happy
+    assert isinstance(value_range.max, Decimal)
+    num_steps = num_outputs - 1
 
-    min_step_size = (value_range.max - value_range.min) / num_bins
+    min_step_size = (value_range.max - value_range.min) / num_steps
     if align:
         step_size = round_up_ish(min_step_size)
-        first_edge = math.floor(Decimal(value_range.min) / step_size) * step_size
-        if first_edge + num_bins * step_size < value_range.max:
+        first_edge = math.floor(Fraction(value_range.min) / step_size) * step_size
+        if first_edge + num_steps * step_size < value_range.max:
             # Uh oh: even though we rounded up the bin size, shifting the first edge
             # down to a multiple has shifted the last edge down too far. Bump up the step size:
-            step_size = round_up_ish(step_size * Decimal(1.015625))
-            first_edge = math.floor(Decimal(value_range.min) / step_size) * step_size
+            step_size = round_up_ish(step_size * Fraction(65, 64))
+            first_edge = math.floor(Fraction(value_range.min) / step_size) * step_size
         # we now have a round step size, and a first edge that the highest possible multiple of it
         # Test to see if any lower multiples of it will still include the whole ranges,
         # and be "nicer" i.e. if data is all in 1.1..9.5 range with 10 bins, we now have bins
         # covering 1-11, but could have 0-10
-        last_edge = first_edge + step_size * num_bins
-        num_trials = int((last_edge - value_range.max) // step_size + 1)
-        offsets = (step_size * i for i in range(num_trials))
-        edge_pairs = ((first_edge - offset, last_edge - offset) for offset in offsets)
-        first_edge = most_round(edge_pairs)[0]
-
+        last_edge = first_edge + step_size * num_steps
+        edge_pairs = []
+        max_step_slop = int((last_edge - Fraction(value_range.max)) // step_size)
+        for step_shift in range(-max_step_slop, 1):
+            for end_step_shift in range(-max_step_slop, step_shift + 1):
+                edge_pairs += [
+                    (first_edge + step_shift * step_size, last_edge + end_step_shift * step_size)
+                ]
+        first_edge, last_edge = most_round(edge_pairs)
     else:
         step_size = min_step_size
         first_edge = value_range.min
+        last_edge = value_range.max
+
+    stepped_values = tuple(first_edge + step_size * i for i in range(num_outputs))
 
-    num_edges = num_bins + 1
-    return tuple(first_edge + step_size * i for i in range(num_edges))
+    # The values may have overrun the end of the desired output range. Trim if so:
+    return tuple(v for v in stepped_values if v <= last_edge)
 
 
-def edge_range(start: FloatLike, end: FloatLike, step: FloatLike, align: bool):
+def edge_range(start: Decimal, end: Decimal, step: Decimal, align: bool):
     """Similar to range/np.arange, but includes "end" in the output if appropriate"""
     if align:
         v = math.floor(start / step) * step
@@ -145,14 +159,14 @@ def bin_with_size(
         x_range = calc_value_range(tuple(x for x, _ in points))
         y_range = calc_value_range(tuple(y for _, y in points))
     else:
-        x_range, y_range = ValueRange(*ranges[0]), ValueRange(*ranges[1])
+        x_range, y_range = make_value_range(ranges[0]), make_value_range(ranges[1])
 
     if not isinstance(bin_sizes, tuple):
         # given just a single bin size: replicate it for both axes:
         bin_sizes = (bin_sizes, bin_sizes)
 
-    x_edges = tuple(edge_range(x_range.min, x_range.max, bin_sizes[0], align))
-    y_edges = tuple(edge_range(y_range.min, y_range.max, bin_sizes[1], align))
+    x_edges = tuple(edge_range(x_range.min, x_range.max, make_decimal(bin_sizes[0]), align))
+    y_edges = tuple(edge_range(y_range.min, y_range.max, make_decimal(bin_sizes[1]), align))
 
     x_axis = Axis(x_range, values_are_edges=True, **axis_args)
     y_axis = Axis(y_range, values_are_edges=True, **axis_args)
@@ -160,6 +174,97 @@ def bin_with_size(
     return (bin_edges(points, x_edges, y_edges, drop_outside=drop_outside), x_axis, y_axis)
 
 
+def expand_bins_arg(
+    bins: (
+        int
+        | tuple[int, int]
+        | Sequence[FloatLike]
+        | tuple[Sequence[FloatLike], Sequence[FloatLike]]
+    ),
+) -> tuple[int, int] | tuple[Sequence[FloatLike], Sequence[FloatLike]]:
+    """Deal with 'bins' argument that is meant to apply to both axes"""
+    if isinstance(bins, int):
+        # we were given a single # of bins
+        return (bins, bins)
+
+    if len(bins) > 2:
+        # we were given a single list of bin edges: replicate it
+        return (bins, bins)
+
+    # Flagged by type-checker: 'bins' could conceivably be a Sequence of len 1 or 2
+    if not isinstance(bins, tuple):
+        raise ValueError("Invalid 'bins' argument")
+
+    # We got a tuple of int/int or of Sequence/Sequence: return it
+    return bins
+
+
+def bins_to_edges(
+    bins: tuple[int, int] | tuple[Sequence[FloatLike], Sequence[FloatLike]],
+) -> tuple[int, int] | tuple[Sequence[FloatLike], Sequence[FloatLike]]:
+    """Number of edges = number of bins + 1. 'bins' argument may be # of bins,
+    or a collection of edges. Only add 1 in the former case.
+    """
+    if isinstance(bins[0], int):
+        return (bins[0] + 1, bins[1] + 1)
+    return bins
+
+
+def find_range(points: Sequence[FloatLike], padding: FloatLike) -> ValueRange:
+    """Calculate a range if none is provided, then produce segment values"""
+
+    range_unpadded = calc_value_range(points)
+    range_padding = make_decimal(padding)
+    return ValueRange(range_unpadded.min - range_padding, range_unpadded.max + range_padding)
+
+
+def segment_one_dim_if_needed(
+    points: Sequence[FloatLike],
+    bins: int | Sequence[FloatLike],
+    out_range: Optional[ValueRange],
+    align: bool,
+    padding: FloatLike,
+) -> Sequence[FloatLike]:
+    """Helper function for processing 'bins' argument:
+    If 'bins' argument is a number of bins, find equally spaced values in the range.
+    If not given a range, compute it first.
+    """
+    if isinstance(bins, int):
+        # we were given the number of bins for X or Y. Calculate the edges/centers:
+        if out_range is None:
+            out_range = find_range(points, padding)
+        return segment_interval(bins, out_range, align)
+
+    # we were given the bin edges/centers already
+    if out_range is not None:
+        raise ValueError("Both bin edges and bin ranges provided, pick one or the other")
+    return bins
+
+
+def process_bin_args(
+    points: Sequence[tuple[FloatLike, FloatLike]],
+    bins: tuple[int, int] | tuple[Sequence[FloatLike], Sequence[FloatLike]],
+    ranges: Optional[tuple[Optional[ValueRange], Optional[ValueRange]]],
+    align: bool,
+    padding: tuple[FloatLike, FloatLike],
+) -> tuple[Sequence[FloatLike], Sequence[FloatLike]]:
+    """Utility function to process the various types that a 'bins' argument might be
+    bins, ranges, align: as for histogram2d
+    """
+
+    if ranges is None:
+        ranges = (None, None)
+
+    x_edges = segment_one_dim_if_needed(
+        tuple(x for x, _ in points), bins[0], ranges[0], align, padding[0]
+    )
+    y_edges = segment_one_dim_if_needed(
+        tuple(y for _, y in points), bins[1], ranges[1], align, padding[1]
+    )
+
+    return x_edges, y_edges
+
+
 def histogram2d(
     points: Sequence[tuple[FloatLike, FloatLike]],
     bins: (
@@ -196,43 +301,9 @@ def histogram2d(
     returns: Sequence[Sequence[int]], (x-)Axis, (y-)Axis
     """
 
-    if isinstance(bins, int):
-        # we were given a single # of bins
-        bins = (bins, bins)
-
-    if isinstance(bins, Sequence) and len(bins) > 2:
-        # we were given a single list of bin edges: replicate it
-        bins = (bins, bins)
+    expanded_bins = bins_to_edges(expand_bins_arg(bins))
 
-    if isinstance(bins[0], int):
-        # we were given the number of bins for X. Calculate the edges:
-        if ranges is None or ranges[0] is None:
-            x_range = calc_value_range(tuple(x for x, _ in points))
-        else:
-            x_range = ValueRange(*ranges[0])
-
-        x_edges = pick_edges(bins[0], x_range, align)
-    else:
-        # we were given the bin edges already
-        if ranges is not None and ranges[0] is not None:
-            raise ValueError("Both bin edges and bin ranges provided, pick one or the other")
-        assert isinstance(bins[0], Sequence)
-        x_edges = bins[0]
-
-    if isinstance(bins[1], int):
-        # we were given the number of bins. Calculate the edges:
-        if ranges is None or ranges[1] is None:
-            y_range = calc_value_range(tuple(y for _, y in points))
-        else:
-            y_range = ValueRange(*ranges[1])
-
-        y_edges = pick_edges(bins[1], y_range, align)
-    else:
-        # we were given the bin edges already
-        if ranges is not None and ranges[1] is not None:
-            raise ValueError("Both bin edges and bin ranges provided, pick one or the other")
-        assert isinstance(bins[1], Sequence)
-        y_edges = bins[1]
+    x_edges, y_edges = process_bin_args(points, expanded_bins, ranges, align, (0, 0))
 
     x_axis = Axis((x_edges[0], x_edges[-1]), values_are_edges=True, **axis_args)
     y_axis = Axis((y_edges[0], y_edges[-1]), values_are_edges=True, **axis_args)