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

densitty/__init__.py

@@ -0,0 +1,9 @@
+"""In-terminal 2-D histogram/density/heatmap plotting"""
+
+from .detect import densityplot2d, grid_heatmap, histplot2d, plot
+from .detect import GRAYSCALE, FADE_IN, RAINBOW, REV_RAINBOW
+from .axis import Axis
+from .plotting import Plot
+from .colorbar import make_colorbar
+from .binning import histogram2d
+from .smoothing import smooth2d

densitty/ansi.py

@@ -8,7 +8,6 @@ from typing import Optional, Sequence
 
 from .util import nearest
 
-
 RESET = "\033[0m"
 
 

densitty/axis.py

@@ -92,11 +92,15 @@ def gen_tick_values(value_range, tick_step):
         tick += tick_step
 
 
-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"""
+def positions_to_labels(
+    printed_positions: Sequence[Decimal], ticked_positions: Sequence[FloatLike], fmt: str
+) -> dict[FloatLike, str]:
+    """Given positions, construct a label dict mapping position to string to be printed there.
+    The first positions get a printed value, the second set get a blank, for a bare 'tick'"""
 
-    return {k: v if k in values_to_print else "" for k, v in labels.items()}
+    tick_dict = {p: "" for p in ticked_positions}
+    printed_dict = {p: fmt.format(p) for p in util.sanitize_decimals(printed_positions)}
+    return tick_dict | printed_dict
 
 
 def calc_min_step(
@@ -127,58 +131,62 @@ def calc_min_step(
     return bin_width * (2 + tick_space)
 
 
-def gen_label_subsets(positions: tuple, tick_step: Decimal) -> list[tuple]:
-    """Generate candidate label subsets based on tick step digit.
+def gen_position_subsets(positions: tuple, tick_step: Decimal) -> list[Sequence[Decimal]]:
+    """Generate candidate label position subsets based on tick step digit.
 
     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
+    # we want to pick different position subsets depending on whether we're advancing by
     # 1eX, 2eX, or 5eX:
-    label_subsets = []
+    position_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
+        # print on every fifth one, starting at 0..4
+        position_subsets += list(util.sanitize_decimals(positions[start::5]) for start in range(5))
+    elif step_digit == 5:
+        # print on every second one, starting at 0 or 1
+        position_subsets += list(util.sanitize_decimals(positions[start::2]) for start in range(2))
+    return position_subsets
 
 
-def label_ends_only(labels, positions, tick_step, bin_width, accomodate_values):
+def label_ends_only(positions, tick_step, bin_width, accomodate_values, fmt):
     """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
+        return positions_to_labels((positions[0], positions[-1]), positions, fmt)
+
+    end_positions = (positions[0], positions[-1])
+    ends_printed = tuple(positions_to_labels(end_positions, [], fmt).values())
 
-    half_len_a = len(labels[positions[0]]) // 2
-    half_len_b = (len(labels[positions[-1]]) + 1) // 2
+    half_len_first = len(ends_printed[0]) // 2
+    half_len_last = (len(ends_printed[1]) + 1) // 2
     space_available = math.floor(tick_step / bin_width)
 
-    if half_len_a + half_len_b <= space_available:
+    if half_len_first + half_len_last <= space_available:
         # We can fit values on the first and last ticks
-        return filter_labels(labels, (positions[0], positions[-1]))
+        return positions_to_labels(end_positions, positions, fmt)
 
     # Not enough space to print two values, so just print the first
-    return filter_labels(labels, positions[0:1])
+    return positions_to_labels(end_positions[:1], positions, fmt)
 
 
-def find_fitting_subset(label_subsets, labels, tick_step, bin_width, accomodate_values):
+def find_fitting_subset(position_subsets, ticks_per_bin, accomodate_values, fmt):
     """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)
+    for position_subset in util.roundness_ordered(position_subsets):
+        if not accomodate_values:  # it doesn't matter what the printed widths are, it will fit
+            return position_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
+        printed_widths = (
+            len(label) for label in positions_to_labels(position_subset, [], fmt).values()
+        )
+        allowed_width = ticks_per_bin * 2 - 2
+        if max(printed_widths) <= allowed_width:
+            return position_subset
+    return tuple()
 
 
 def gen_full_labels(value_range: ValueRange, num_bins, accomodate_values, tick_space, fmt):
@@ -193,33 +201,31 @@ def gen_full_labels(value_range: ValueRange, num_bins, accomodate_values, tick_s
     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())
+        positions = tuple(gen_tick_values(value_range, cur_tick_step))
 
-        if len(labels) == 0:
+        if len(positions) == 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
+        if len(positions) == 1:
+            return positions_to_labels(positions, [], fmt)
 
-        label_subsets = gen_label_subsets(positions, cur_tick_step)
+        position_subsets = gen_position_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:
+        if max(len(subset) for subset in position_subsets) == 1:
             # Try to just label the ends:
-            return label_ends_only(labels, positions, cur_tick_step, bin_width, accomodate_values)
+            return label_ends_only(positions, cur_tick_step, bin_width, accomodate_values, fmt)
 
-        result = find_fitting_subset(
-            label_subsets, labels, cur_tick_step, bin_width, accomodate_values
+        best_subset = find_fitting_subset(
+            position_subsets, cur_tick_step / bin_width, accomodate_values, fmt
         )
-        if result is not None:
-            return result
+
+        if best_subset:
+            return positions_to_labels(best_subset, positions, fmt)
 
         cur_tick_step = pick_step_size(float(cur_tick_step) * 1.01)
 
@@ -256,7 +262,9 @@ class Axis:
     """Options for axis generation."""
 
     value_range: ValueRange  # can also specify as a tuple of (min, max)
-    labels: Optional[dict[float, str]] = None  # map axis value to label (plus tick) at that value
+    labels: Optional[dict[FloatLike, str]] = (
+        None  # map axis value to label (plus tick) at that value
+    )
     label_fmt: str = "{}"  # format for generated labels
     border_line: bool = False  # embed ticks in a horizontal X-axis or vertical Y-axis line
     values_are_edges: bool = False  # N+1 values, indicating boundaries between pixels, not centers
@@ -265,7 +273,7 @@ class Axis:
     def __init__(
         self,
         value_range: ValueRange | tuple[FloatLike, FloatLike],
-        labels: Optional[dict[float, str]] = None,
+        labels: Optional[dict[FloatLike, str]] = None,
         label_fmt: str = "{}",
         border_line: bool = False,
         values_are_edges: bool = False,
@@ -304,10 +312,12 @@ class Axis:
             if label_values and row_min <= label_values[0] <= row_max:
                 label_str = labels[label_values[0]]
 
-                offset_frac = (label_values[0] - row_min) / (row_max - row_min)
-                if offset_frac < 0.25 and self.fractional_tick_pos:
+                offset_frac = (float(label_values[0]) - float(row_min)) / float(row_max - row_min)
+                # Try to avoid our cutoffs being exactly where roundoff errors can pop up and
+                # cause inconsistent behavior. So 0.249 rather than 0.25, 0.751 rather than 0.75:
+                if offset_frac < 0.249 and self.fractional_tick_pos:
                     tick_char = "▔"
-                elif offset_frac > 0.75 and self.fractional_tick_pos:
+                elif offset_frac > 0.751 and self.fractional_tick_pos:
                     tick_char = "▁"
                 else:
                     tick_char = "─"
@@ -400,3 +410,19 @@ class Axis:
                 label_values = label_values[1:]  # pop that first label since we added it
 
         return "".join(tick_line), "".join(label_line)
+
+    def upscale(self, new_num_bins, multiplier):
+        """Adjust axis for an upscaled plot"""
+        if self.values_are_edges:
+            # upscaling doesn't move the axis edges. First edge of first bin is the same.
+            return
+        old_num_bins = new_num_bins // multiplier
+        old_bin_width = (self.value_range.max - self.value_range.min) / (old_num_bins - 1)
+        new_bin_width = old_bin_width / multiplier
+        # we used to have a value for the center of the first bin, but now that bin is
+        # 'multiplier' bins, and the value corresponds to the center of that _group_ of bins
+        # Find the offset between that group center, and the center of the new edge bin:
+        offset = new_bin_width * (multiplier - 1) / 2
+        self.value_range = util.make_value_range(
+            (self.value_range.min - offset, self.value_range.max + offset)
+        )

densitty/binning.py

@@ -10,8 +10,30 @@ from .axis import Axis
 from .util import FloatLike, ValueRange
 from .util import clamp, make_decimal, make_value_range, most_round, round_up_ish
 
+# Following MatPlotLib, the 'bins' argument for functions can be:
+#  int:                                             number of bins for both X and Y
+#  Sequence[FloatLike]:                             bin edges for both X and Y
+#  tuple(int, int):                                 number of bins for X, number of bins for Y
+#  tuple(Sequence[FloatLike], Sequence[FloatLike]): bin edges for X, bin edges for Y
 
-def bin_edges(
+CountArg = int
+EdgesArg = Sequence[FloatLike]
+# a type for the "for both X and Y" variants:
+SingleBinsArg = CountArg | EdgesArg
+
+# a type for the tuple (X,Y) variants:
+DoubleCountArg = tuple[CountArg, CountArg]
+DoubleEdgesArg = tuple[EdgesArg, EdgesArg]
+ExpandedBinsArg = DoubleCountArg | DoubleEdgesArg
+
+FullBinsArg = Optional[SingleBinsArg | ExpandedBinsArg]
+
+RangesArg = tuple[Optional[ValueRange], Optional[ValueRange]]
+
+DEFAULT_NUM_BINS = (10, 10)
+
+
+def bin_by_edges(
     points: Sequence[tuple[FloatLike, FloatLike]],
     x_edges: Sequence[FloatLike],
     y_edges: Sequence[FloatLike],
@@ -50,13 +72,34 @@ def calc_value_range(values: Sequence[FloatLike]) -> ValueRange:
 
     # 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)
-    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)
+    min_value = make_decimal(min(values))
+    max_value = make_decimal(max(values))
+
+    range_top = max_value + Decimal(
+        math.ulp(max_value)
+    )  # increase by smallest float-representable amount
+    return ValueRange(min_value, range_top)
+
+
+def align_value_range(vr: ValueRange, alignment_arg: FloatLike) -> ValueRange:
+    """Shift the provided ValueRange up or down to the specified alignment.
+    up/down choice based on which will shift it less"""
+    alignment = make_decimal(alignment_arg)
+    width = vr.max - vr.min
+    aligned_min = math.floor(vr.min / alignment) * alignment
+    aligned_max = math.ceil(vr.max / alignment) * alignment
+    shift_for_min = vr.min - aligned_min  # how far down did 'min' get shifted?
+    shift_for_max = aligned_max - vr.max  # how far up did 'max' get shifted?
+    if shift_for_min < shift_for_max:
+        return ValueRange(aligned_min, aligned_min + width)
+    return ValueRange(aligned_max - width, aligned_max)
+
+
+def force_value_range_width(vr: ValueRange, width: FloatLike) -> ValueRange:
+    """Return a ValueRange with specified width, centered on an existing ValueRange"""
+    half_width = make_decimal(width) / 2
+    midpoint = (vr.max + vr.min) / 2
+    return ValueRange(midpoint - half_width, midpoint + half_width)
 
 
 def segment_interval(
@@ -114,13 +157,18 @@ def segment_interval(
     return tuple(v for v in stepped_values if v <= last_edge)
 
 
-def edge_range(start: Decimal, end: Decimal, step: Decimal, align: bool):
-    """Similar to range/np.arange, but includes "end" in the output if appropriate"""
+def edge_range(rng: ValueRange, step_arg: FloatLike, align: bool):
+    """Generator providing values containing range, by step.
+    The first value will be rng.min, or rng.min rounded down to nearest 'step'
+    The last value will be equal to or larger than rng.max"""
+
+    step = make_decimal(step_arg)  # turn into decimal if it isn't already
     if align:
-        v = math.floor(start / step) * step
+        v = math.floor(rng.min / step) * step
     else:
-        v = start
-    while v < end + step:
+        v = rng.min
+
+    while v < (rng.max + step).next_minus():
         if align:
             yield round(v / step) * step
         else:
@@ -128,171 +176,103 @@ def edge_range(start: Decimal, end: Decimal, step: Decimal, align: bool):
         v += step
 
 
-def bin_with_size(
-    points: Sequence[tuple[FloatLike, FloatLike]],
-    bin_sizes: FloatLike | tuple[FloatLike, FloatLike],
-    ranges: Optional[tuple[ValueRange, ValueRange]] = None,
-    align=True,
-    drop_outside=True,
-    **axis_args,
-) -> tuple[Sequence[Sequence[int]], Axis, Axis]:
-    """Bin points into a 2-D histogram, given bin sizes
-
-    Parameters
-    ----------
-    points: Sequence of (X,Y) tuples: the points to bin
-    bin_sizes: float or tuple(float, float)
-                Size(s) of (X,Y) bins to partition into
-    ranges: Optional (ValueRange, ValueRange)
-                ((x_min, x_max), (y_min, y_max)) for the bins. Default: take from data.
-    align: bool (default: True)
-                Force bin edges to be at a multiple of the bin size
-    drop_outside: bool (default: True)
-                True: Drop any data points outside the ranges
-                False: Put any outside points in closest bin (i.e. edge bins include outliers)
-    axis_args: Extra arguments to pass through to Axis constructor
-
-    returns: Sequence[Sequence[int]], (x-)Axis, (y-)Axis
-    """
-
-    if ranges is None:
-        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 = 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, 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)
-
-    return (bin_edges(points, x_edges, y_edges, drop_outside=drop_outside), x_axis, y_axis)
+def make_edges(rng: ValueRange, step_arg: FloatLike, align: bool):
+    """Return the edges as from 'edge_range', as a tuple for convenience"""
+    return tuple(edge_range(rng, step_arg, align))
 
 
 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.
+    bins: FullBinsArg,
+) -> tuple[bool, DoubleCountArg, Optional[DoubleEdgesArg]]:
+    """Deal with 'bins' that may be
+    - None
+    - an integer indicating number of bins
+    - a list of edges/centers for the bins
+    - a 2-tuple of either of those
+    Returns a 3-tuple:
+      - specified/not-default (bool),
+      - 2-tuple of number of bins,
+      - optional 2-tuple of lists of edges/centers
     """
+    if bins is None:
+        return (False, DEFAULT_NUM_BINS, None)
     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
-
+        num_bins = (bins, bins)
+        bin_positions = None
+    elif len(bins) > 2:
+        # we were given a single list of bin edges
+        num = len(bins) - 1
+        num_bins = (num, num)
+        bin_positions = (bins, bins)
+    else:
+        if not isinstance(bins, tuple):
+            raise ValueError("Invalid 'bins' argument")
+        # we either have a tuple of int/int or Sequence/Sequence
+        if isinstance(bins[0], int):
+            num_bins = bins
+            bin_positions = None
+        else:
+            num_bins = (len(bins[0]) - 1, len(bins[1]) - 1)
+            bin_positions = bins
+    return True, num_bins, bin_positions
 
-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)
+def expand_bin_size_arg(
+    bin_size: Optional[FloatLike | tuple[FloatLike, FloatLike]],
+) -> Optional[tuple[FloatLike, FloatLike]]:
+    """If bin_size arg is not a 2-tuple, replicate it into one"""
+    if bin_size is None:
+        return None
+    if isinstance(bin_size, tuple):
+        return bin_size
+    return (bin_size, bin_size)
 
-    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 range_from_arg_or_data(range_arg, points):
+    """Return range arg if given, or calculate a range from the data"""
+    if range_arg:
+        return make_value_range(range_arg)
+    return calc_value_range(tuple(points))
 
 
-def histogram2d(
+def histogram2d(  # pylint: disable=too-many-arguments,too-many-positional-arguments,too-many-locals
     points: Sequence[tuple[FloatLike, FloatLike]],
-    bins: (
-        int
-        | tuple[int, int]
-        | Sequence[FloatLike]
-        | tuple[Sequence[FloatLike], Sequence[FloatLike]]
-    ) = 10,
-    ranges: Optional[tuple[Optional[ValueRange], Optional[ValueRange]]] = None,
+    bins: FullBinsArg = None,
+    ranges: Optional[RangesArg] = None,
+    bin_size: Optional[FloatLike | tuple[FloatLike, FloatLike]] = None,
     align=True,
     drop_outside=True,
     **axis_args,
 ) -> tuple[Sequence[Sequence[int]], Axis, Axis]:
-    """Bin points into a 2-D histogram, given number of bins, or bin edges
+    """Bin points into a 2-D histogram, given number of bins, bin edges, or bin sizes
+
+    Parameters can be combined in the following ways:
+    - bin_size with optional ranges
+    - bins (as edges) with no ranges
+    - bins (as count) with optional ranges
+    - bins (as count) + bin_size with no ranges: Fixed number and size of bins, centered on data
 
     Parameters
     ----------
     points: Sequence of (X,Y) tuples: the points to bin
-    bins: int or (int, int) or [float,...] or ([float,...], [float,...])
-                int: number of bins for both X & Y (default: 10)
+    bins: int or (int, int) or [float,...] or ([float,...], [float,...]) or None
+                int: number of bins for both X & Y
                 (int,int): number of bins in X, number of bins in Y
                 list[float]: bin edges for both X & Y
                 (list[float], list[float]): bin edges for X, bin edges for Y
+                None: defaults to DEFAULT_NUM_BINS if bin_size is not provided
     ranges: Optional (ValueRange, ValueRange)
                 ((x_min, x_max), (y_min, y_max)) for the bins if # of bins is provided
-                Default: take from data.
+                Cannot be specified with bins (as count) + bin_size, or bins (as edges)
+                Default if allowed: take from data
+    bin_size: Optional float or (float, float)
+                Size(s) of (X,Y) bins to partition into.
+                Cannot be combined with bins (as edges) since edge spacing already determines size.
+                float: bin size for both X & Y
+                (float, float): bin size for X, bin size for Y
     align: bool (default: True)
-                pick bin edges at 'round' values if # of bins is provided
+                pick bin edges at 'round' values if # of bins is provided, or force bin edges
+                to be at multiples of bin_size if bin_size is provided
     drop_outside: bool (default: True)
                 True: Drop any data points outside the ranges
                 False: Put any outside points in closest bin (i.e. edge bins include outliers)
@@ -301,11 +281,45 @@ def histogram2d(
     returns: Sequence[Sequence[int]], (x-)Axis, (y-)Axis
     """
 
-    expanded_bins = bins_to_edges(expand_bins_arg(bins))
+    bins_specified, num_bins, bin_edges = expand_bins_arg(bins)
+
+    bin_sizes = expand_bin_size_arg(bin_size)
+    if ranges is None:
+        ranges = (None, None)
+
+    if bin_edges and any(ranges):
+        raise ValueError("Cannot specify both bin edges and plot range")
+    if bins_specified and bin_sizes and any(ranges):
+        # The number of bins and bin size imply a size of plot range, so this
+        # is overconstrained.
+        raise ValueError("Cannot specify number of bins and bin size and plot range")
+
+    x_range = range_from_arg_or_data(ranges[0], (x for x, _ in points))
+    y_range = range_from_arg_or_data(ranges[1], (y for _, y in points))
 
-    x_edges, y_edges = process_bin_args(points, expanded_bins, ranges, align, (0, 0))
+    if bins_specified and bin_sizes:
+        # range width must be num_bins * bin_sizes, so take the data's range
+        # and force the width, aligning as needed
+        x_range = force_value_range_width(x_range, num_bins[0] * bin_sizes[0])
+        if align:
+            x_range = align_value_range(x_range, bin_sizes[0])
+
+        y_range = force_value_range_width(y_range, num_bins[1] * bin_sizes[1])
+        if align:
+            y_range = align_value_range(y_range, bin_sizes[1])
+
+    # Handle different parameter combinations
+    if bin_edges:
+        x_edges, y_edges = bin_edges
+    else:
+        if bin_sizes:
+            x_edges = make_edges(x_range, bin_sizes[0], align)
+            y_edges = make_edges(y_range, bin_sizes[1], align)
+        else:
+            # Only number of bins provided, if that
+            x_edges = segment_interval(num_bins[0] + 1, x_range, align)
+            y_edges = segment_interval(num_bins[1] + 1, y_range, align)
 
     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)
-
-    return (bin_edges(points, x_edges, y_edges, drop_outside), x_axis, y_axis)
+    return (bin_by_edges(points, x_edges, y_edges, drop_outside), x_axis, y_axis)