binny.correlations.bin_combo_filter module#

Module for building and filtering bin-index combinations.

This module provides a small, user-facing wrapper for building collections of index pairs, triplets, or higher-order index tuples and filtering them using score summaries or curve-based metrics.

The intended use is to pass a shared coordinate grid and per-slot curve mappings once, then apply high-level filters without manually building per-position score maps or writing custom tuple metrics.

class binny.correlations.bin_combo_filter.BinComboFilter(*, z: NDArray[float64], curves: Sequence[Mapping[int, NDArray[float64]]], tuples: Sequence[tuple[int, ...]] | None = None)#

Bases: object

Builds and filters tuples using stored curves.

The filter stores a shared coordinate grid and one curve mapping per tuple position (slot). It also stores the current working list of index tuples.

The main workflow is:

  • build a tuple collection with set_topology()

  • apply one or more filters based on scores or overlap metrics

  • retrieve the resulting tuples with values()

Slot conventions follow tuple positions: slot 0 corresponds to the first index in a tuple, slot 1 to the second, and so on.

Creates a filter for curve-indexed tuple filtering.

Parameters:

  • z – Shared coordinate grid for all curve evaluations.

  • curves – Sequence of per-slot mappings from index to curve values. curves[p] supplies curves for tuple position p.

  • tuples – Optional initial tuple collection to filter. If omitted, the filter starts with an empty tuple list.

keep_if_curve_norm_threshold(*, threshold: float, compare: Literal['lt', 'le', 'gt', 'ge'] = 'ge', mode: Literal['all', 'any'] = 'all') → BinComboFilter#

Keeps tuples based on per-slot curve normalization thresholds.

This filter uses the integrated curve norm at each tuple position to exclude tuples that involve curves with very small integrated area.

With mode="all", every position must pass the threshold. With mode="any", at least one position must pass.

Parameters:

  • threshold – Reference value used for filtering.

  • compare – Comparison operator applied to each norm versus threshold.

  • mode – Whether to require all positions (“all”) or at least one (“any”).

Returns:

Self, to allow method chaining.

Raises:

  • ValueError – If the mode is not recognized, or norms do not cover the tuple positions or if the requested comparison relation is not supported.

  • KeyError – If a required index is not pr esent in the stored curves for a slot.

keep_if_metric(*, kernel: Callable[[...], float], threshold: float, compare: Literal['lt', 'le', 'gt', 'ge'] = 'le') → BinComboFilter#

Keeps tuples based on a user-supplied curve metric.

The provided kernel is treated as a curve-level metric evaluated on the curves selected by each tuple. Tuples are kept when the resulting value satisfies the chosen comparison against threshold.

Parameters:

  • kernel – Callable that maps N curves to a scalar metric value.

  • threshold – Reference value used for filtering.

  • compare – Comparison operator applied as value op threshold.

Returns:

Self, to allow method chaining.

Raises:

ValueError – If the requested comparison relation is not supported.

keep_if_overlap_coefficient(*, threshold: float, compare: Literal['lt', 'le', 'gt', 'ge'] = 'ge') → BinComboFilter#

Keeps tuples based on the overlap coefficient.

This filter computes the overlap coefficient for the curves selected by each tuple and keeps tuples that satisfy the chosen comparison against threshold.

Parameters:

  • threshold – Reference value used for filtering.

  • compare – Comparison operator applied as value op threshold.

Returns:

Self, to allow method chaining.

Raises:

ValueError – If the requested comparison relation is not supported.

keep_if_overlap_fraction(*, threshold: float, compare: Literal['lt', 'le', 'gt', 'ge'] = 'ge') → BinComboFilter#

Keeps tuples based on the minimum-overlap fraction.

This filter computes the normalized minimum-overlap fraction for the curves selected by each tuple and keeps tuples that satisfy the chosen comparison against threshold.

Parameters:

  • threshold – Reference value used for filtering.

  • compare – Comparison operator applied as value op threshold.

Returns:

Self, to allow method chaining.

Raises:

ValueError – If the requested comparison relation is not supported.

keep_if_score_consistency(score1: Literal['peak', 'mean', 'median', 'width'], score2: Literal['peak', 'mean', 'median', 'width'], *, pos_a: int = 0, pos_b: int = 1, relation: Literal['lt', 'le', 'gt', 'ge'] = 'lt', mass: float = 0.68, mass2: float | None = None) → BinComboFilter#

Keeps tuples that satisfy the same ordering under two score choices.

For each tuple, evaluates two different score definitions and keeps the tuple only if the requested ordering between pos_a and pos_b holds for both scores.

This is useful when a robust ordering that is stable under alternative summaries is required, such as peak and mean locations.

Parameters:

  • score1 – First score definition used to summarize each curve.

  • score2 – Second score definition used to summarize each curve.

  • pos_a – First tuple position in the comparison.

  • pos_b – Second tuple position in the comparison.

  • relation – Comparison operator applied for both score definitions.

  • mass – Credible mass used when score1="width".

  • mass2 – Credible mass used when score2="width". If None, uses mass.

Returns:

Self, to allow method chaining.

Raises:

  • ValueError – If requested positions are not valid for the tuple collection or if the requested relation is not supported.

  • KeyError – If a required index is not present in the stored curves for a slot.

keep_if_score_difference(score: Literal['peak', 'mean', 'median', 'width'], *, pos_a: int = 0, pos_b: int = 1, min_diff: float | None = None, max_diff: float | None = None, mass: float = 0.68) → BinComboFilter#

Keeps tuples whose signed score difference lies within a window.

For each tuple, computes the signed score difference between positions pos_a and pos_b and keeps the tuple when the difference lies within the provided bounds (ignoring bounds set to None).

This supports directional selections such as keeping tuples where the score at one position is larger than the score at another.

Parameters:

  • score – Score definition used to reduce each curve to a scalar.

  • pos_a – First tuple position used in the difference.

  • pos_b – Second tuple position used in the difference.

  • min_diff – Optional minimum signed difference to enforce.

  • max_diff – Optional maximum signed difference to enforce.

  • mass – Credible mass used when score="width".

Returns:

Self, to allow method chaining.

Raises:

  • ValueError – If requested positions are not valid for the tuple collection.

  • KeyError – If a required index is not present in the stored curves for a slot.

keep_if_score_relation(score: Literal['peak', 'mean', 'median', 'width'], *, pos_a: int = 0, pos_b: int = 1, relation: Literal['lt', 'le', 'gt', 'ge'] = 'lt', mass: float = 0.68) → BinComboFilter#

Keeps tuples based on an ordering between two score values.

For each tuple, computes the requested score at positions pos_a and pos_b and keeps the tuple when the score at pos_b satisfies the requested relation relative to the score at pos_a.

Parameters:

  • score – Score definition used to reduce each curve to a scalar.

  • pos_a – First tuple position in the comparison.

  • pos_b – Second tuple position in the comparison.

  • relation – Comparison operator applied to the two score values.

  • mass – Credible mass used when score="width".

Returns:

Self, to allow method chaining.

Raises:

  • ValueError – If requested positions are not valid for the tuple collection or if the requested relation is not supported.

  • KeyError – If a required index is not present in the stored curves for a slot.

keep_if_score_separation(score: Literal['peak', 'mean', 'median', 'width'], *, pos_a: int = 0, pos_b: int = 1, min_sep: float | None = None, max_sep: float | None = None, absolute: bool = True, mass: float = 0.68) → BinComboFilter#

Keeps tuples whose score separation lies within a requested window.

For each tuple, computes the score difference between positions pos_a and pos_b and keeps the tuple when the separation lies within the provided bounds (ignoring bounds set to None).

Parameters:

  • score – Score definition used to reduce each curve to a scalar.

  • pos_a – First tuple position used in the separation.

  • pos_b – Second tuple position used in the separation.

  • min_sep – Optional minimum separation to enforce.

  • max_sep – Optional maximum separation to enforce.

  • absolute – If True, apply bounds to the absolute separation.

  • mass – Credible mass used when score="width".

Returns:

Self, to allow method chaining.

Raises:

  • ValueError – If requested positions are invalid or bounds are inconsistent.

  • KeyError – If a required index is not present in the stored curves for a slot.

keep_if_width_ratio(*, pos_a: int = 0, pos_b: int = 1, max_ratio: float = 2.0, symmetric: bool = True, mass: float = 0.68) → BinComboFilter#

Keeps tuples whose width values are compatible across two positions.

This filter compares per-index width-like scores between two tuple positions and keeps tuples where the ratio does not exceed max_ratio. When symmetric=True, the ratio is treated symmetrically between the two positions.

Parameters:

  • pos_a – First tuple position in the comparison.

  • pos_b – Second tuple position in the comparison.

  • max_ratio – Maximum allowed ratio between widths.

  • symmetric – If True, enforce ratio symmetry between positions.

  • mass – Credible mass used to define widths.

Returns:

Self, to allow method chaining.

Raises:

  • ValueError – If requested positions are invalid or max_ratio is not meaningful.

  • KeyError – If a required index is not present in the stored curves for a slot.

select(spec: Mapping[str, Any]) → BinComboFilter#

Apply a YAML-friendly selection spec (topology + ordered filters).

Informal spec schema:

spec:
  topology: {name: <TopologyName>, keys?: ...}
  filters:
    - {name: overlap_fraction, threshold: float, compare?: lt/le/gt/ge}
    - {name: overlap_coefficient, threshold: float, compare?: ...}
    - {name: score_relation, score: peak/mean/median/width,
       pos_a?: int, pos_b?: int, relation?: ...}
    - {name: score_separation, score: ..., min_sep?: float,
       max_sep?: float, absolute?: bool, ...}
    - {name: score_difference, score: ..., min_diff?: float,
       max_diff?: float, ...}
    - {name: score_consistency, score1: ..., score2: ...,
       relation?: ..., ...}
    - {name: width_ratio, max_ratio?: float, symmetric?: bool,
       pos_a?: int, pos_b?: int, ...}
    - {name: curve_norm_threshold, threshold: float, compare?: ...,
       mode?: all/any}
    - {name: metric, metric: <kernel_name>, threshold: float,
       compare?: ...}
Parameters:

spec – Mapping containing an optional topology block and an optional ordered list of filter blocks.

Returns:

Self, for chaining.

Raises:

  • TypeError – If spec or one of its subentries has the wrong type.

  • KeyError – If a requested filter name or metric kernel is unknown.

  • ValueError – If a requested comparison or ordering relation is not

  • supported. –

set_topology(name: Literal['pairs_all', 'pairs_upper_triangle', 'pairs_lower_triangle', 'pairs_diagonal', 'pairs_off_diagonal', 'pairs_cartesian', 'tuples_all', 'tuples_nondecreasing', 'tuples_diagonal', 'tuples_cartesian'], *args, **kwargs) → BinComboFilter#

Builds and stores a tuple collection using a named topology.

This replaces the current tuple list with the tuples generated by the chosen topology.

Most topology builders require explicit key lists. For convenience, if no positional arguments are provided, this method will infer the required key inputs from the stored per-slot curve mappings:

  • for within-set pair builders (e.g. “pairs_upper_triangle”), uses the keys from slot 0

  • for “pairs_cartesian”, uses keys from slots 0 and 1

  • for r-tuple builders that take a single key set (e.g. “tuples_all”), uses slot-0 keys and sets r = number of curve slots

  • for “tuples_cartesian”, uses keys from every slot

Parameters:

  • name – Name of a supported topology builder.

  • *args – Positional arguments forwarded to the chosen topology. If omitted, appropriate defaults are inferred from stored curves as described above.

  • **kwargs – Keyword arguments forwarded to the chosen topology. Some defaults may be inserted when args are omitted (e.g. r for “tuples_nondecreasing”).

Returns:

Self, to allow method chaining.

Raises:

  • KeyError – If name is not a supported topology identifier.

  • ValueError – If the chosen topology rejects the provided arguments, or if the requested topology cannot be inferred from stored curves (e.g. “pairs_cartesian” with fewer than 2 curve slots).

values() → list[tuple[int, ...]]#

Returns the current filtered tuple list.

Returns:

A list of index tuples representing the current filtered result.