Overlap Filter

Filter an IntervalTrack by geometric overlap with a label track. Supports keep mode (retain overlapping regions) and exclude mode (retain non-overlapping regions), with optional state matching on label names.

from seqchain.recipes.filter import filter_by_overlap

# Keep only guides in closed chromatin
closed_guides = filter_by_overlap(guide_track, chromatin_track, state="closed")

# Exclude guides near promoters
non_promoter = filter_by_overlap(guide_track, promoter_track, exclude=True)

filter

Forwarding stub — implementation moved to _draft/.

filter_by_overlap

filter_by_overlap(query_track: IntervalTrack, label_track: IntervalTrack, *, state: str | None = None, exclude: bool = False) -> IntervalTrack

Filter regions by spatial overlap with labeled regions.

Iterates every region in query_track, queries label_track for overlapping label regions, and keeps (or excludes) the query region based on whether a matching overlap exists.

Parameters:

Name	Type	Description	Default
query_track	IntervalTrack	The track whose regions are tested.	required
label_track	IntervalTrack	Track whose regions serve as the filter.	required
state	str | None	If given, only label regions whose name matches this value count as overlaps. None means any label region counts (pure geometric overlap).	None
exclude	bool	If True, return regions that do not overlap any matching label. Defaults to False (keep mode).	False

Returns:

Type	Description
IntervalTrack	A new IntervalTrack with the same name as query_track,
IntervalTrack	containing only regions that pass the filter.

Examples:

>>> result = filter_by_overlap(guides, chromatin, state="closed")

Source code in src/seqchain/recipes/_draft/filter.py

def filter_by_overlap(
    query_track: IntervalTrack,
    label_track: IntervalTrack,
    *,
    state: str | None = None,
    exclude: bool = False,
) -> IntervalTrack:
    """Filter regions by spatial overlap with labeled regions.

    Iterates every region in *query_track*, queries *label_track* for
    overlapping label regions, and keeps (or excludes) the query region
    based on whether a matching overlap exists.

    Args:
        query_track: The track whose regions are tested.
        label_track: Track whose regions serve as the filter.
        state: If given, only label regions whose ``name`` matches
            this value count as overlaps.  ``None`` means any label
            region counts (pure geometric overlap).
        exclude: If ``True``, return regions that do *not* overlap
            any matching label.  Defaults to ``False`` (keep mode).

    Returns:
        A new `IntervalTrack` with the same name as *query_track*,
        containing only regions that pass the filter.

    Examples:
        >>> result = filter_by_overlap(guides, chromatin, state="closed")
    """
    kept = []
    for region in query_track:
        hits = list(label_track.regions(region.chrom, region.start, region.end))
        if state is None:
            has_overlap = len(hits) > 0
        else:
            has_overlap = any(r.name == state for r in hits)
        if has_overlap != exclude:
            kept.append(region)

    return IntervalTrack(query_track, kept)