Add binned summary statistic aggregation for genomic intervals — Closes #61

docs/dialect/aggregation-operators.rst

@@ -328,4 +328,128 @@ Related Operators
 ~~~~~~~~~~~~~~~~~
 
 - :ref:`CLUSTER <cluster-operator>` - Assign cluster IDs without merging
+- :ref:`RASTERIZE <rasterize-operator>` - Rasterize intervals onto a fixed bin grid
 - :ref:`INTERSECTS <intersects-operator>` - Test for overlap between specific pairs
+
+----
+
+.. _rasterize-operator:
+
+RASTERIZE
+---------
+
+Rasterize interval data onto a fixed-resolution bin grid, counting overlaps per bin.
+
+Description
+~~~~~~~~~~~
+
+The ``RASTERIZE`` operator tiles the genome into fixed-width bins and counts the number of intervals overlapping each bin. It generates a bin grid using ``generate_series`` and joins it against the source table to count overlapping features per bin.
+
+This is useful for:
+
+- Summarising feature density at a user-defined resolution
+- Creating fixed-resolution count tracks from interval data
+- Quick visualisation of interval pile-ups across the genome
+
+An interval that spans multiple bins is counted in each of the bins it overlaps, matching the ``bedtools coverage`` convention. As a result, the sum of bin counts is generally greater than the number of source intervals — bin counts answer "how many intervals touch this bin?", not "how are intervals partitioned across bins?".
+
+The operator works as an aggregate function, returning one row per bin with the bin coordinates and the count.
+
+.. note::
+
+   RASTERIZE depends on ``LATERAL`` plus ``generate_series`` for bin generation, which DuckDB and PostgreSQL both support. SQLite does not currently provide either primitive, so this operator is not yet available on the SQLite backend.
+
+.. note::
+
+   Only the ``count`` aggregation is supported in this release. Weighted summary statistics (mean, sum, min, max) over interval values raise non-trivial semantic questions when intervals span bin boundaries (full-value contribution vs. length-weighted vs. per-base depth) and are tracked as a follow-up.
+
+Syntax
+~~~~~~
+
+.. code-block:: sql
+
+   -- Count overlapping intervals per bin
+   SELECT RASTERIZE(interval, <bin_width>) FROM features
+
+   -- Named resolution parameter
+   SELECT RASTERIZE(interval, resolution := 500) FROM features
+
+Parameters
+~~~~~~~~~~
+
+**interval**
+   A genomic column.
+
+**resolution** *(required)*
+   Bin width in base pairs — must be a positive integer literal. Can be given as a positional or named parameter (``RASTERIZE(interval, 1000)`` or ``RASTERIZE(interval, resolution := 1000)``). Omitting it, or supplying a non-positive value, raises ``ValueError`` at transpile time.
+
+Return Value
+~~~~~~~~~~~~
+
+Returns one row per genomic bin:
+
+- ``chrom`` — Chromosome of the bin
+- ``start`` — Start position of the bin
+- ``end`` — End position of the bin
+- ``value`` — The count of intervals overlapping the bin (default alias; use ``AS`` to rename)
+
+Examples
+~~~~~~~~
+
+**Basic Count:**
+
+Count the number of features overlapping each 1 kb bin:
+
+.. code-block:: sql
+
+   SELECT RASTERIZE(interval, 1000)
+   FROM features
+
+**Named Alias:**
+
+.. code-block:: sql
+
+   SELECT RASTERIZE(interval, 1000) AS depth
+   FROM reads
+
+**With WHERE Filter:**
+
+Assuming the source table includes a ``score`` column, count high-scoring features per bin:
+
+.. code-block:: sql
+
+   SELECT RASTERIZE(interval, 1000) AS depth
+   FROM features
+   WHERE score > 10
+
+Supported FROM clauses
+~~~~~~~~~~~~~~~~~~~~~~
+
+``RASTERIZE`` requires a ``FROM`` clause that references a table or named CTE. Inline subqueries (``FROM (SELECT ...) AS sub``) and ``VALUES`` clauses are not supported — wrap the derivation in a ``WITH`` clause and select ``RASTERIZE(...)`` from the CTE by name:
+
+.. code-block:: sql
+
+   -- Not supported: inline subquery in FROM
+   SELECT RASTERIZE(interval, 1000)
+   FROM (SELECT * FROM features WHERE score > 50) AS filtered
+
+   -- Supported: same derivation wrapped in a CTE
+   WITH filtered AS (
+       SELECT * FROM features WHERE score > 50
+   )
+   SELECT RASTERIZE(interval, 1000) FROM filtered
+
+Any ``WITH`` clauses you declare are preserved alongside the internal ``__giql_bins`` CTE in the transpiled SQL.
+
+Performance Notes
+~~~~~~~~~~~~~~~~~
+
+- The operator creates one bin per chromosome per step, so smaller resolutions produce more rows
+- A ``LEFT JOIN`` ensures bins with zero coverage are included in the output
+- For very large genomes, consider restricting the query with a ``WHERE`` clause on chromosome
+
+Related Operators
+~~~~~~~~~~~~~~~~~
+
+- :ref:`MERGE <merge-operator>` - Combine overlapping intervals into single regions
+- :ref:`CLUSTER <cluster-operator>` - Assign cluster IDs to overlapping intervals

docs/dialect/index.rst

@@ -95,6 +95,9 @@ Combine and cluster genomic intervals.
    * - :ref:`MERGE <merge-operator>`
      - Combine overlapping intervals into unified regions
      - ``SELECT MERGE(interval) FROM features``
+   * - :ref:`RASTERIZE <rasterize-operator>`
+     - Rasterize intervals onto a fixed bin grid with per-bin counts
+     - ``SELECT RASTERIZE(interval, 1000) FROM features``
 
 See :doc:`aggregation-operators` for detailed documentation.
 

docs/recipes/index.rst

@@ -19,6 +19,10 @@ Recipe Categories
    Clustering overlapping intervals, distance-based clustering,
    merging intervals, and aggregating cluster statistics.
 
+:doc:`rasterize`
+   Rasterizing intervals onto a fixed bin grid: per-bin counts,
+   strand-specific counts, normalisation, and 5' end counting.
+
 :doc:`advanced`
    Multi-range matching, complex filtering with joins, aggregate statistics,
    window expansions, and multi-table queries.

docs/recipes/rasterize.rst

@@ -0,0 +1,145 @@
+Rasterize
+=========
+
+This section covers patterns for projecting interval data onto a fixed-resolution bin grid using GIQL's ``RASTERIZE`` operator.
+
+Basic Usage
+-----------
+
+Rasterized counts underpin most genome-wide signal summaries — read-pileup plots for ChIP-seq, exon-level depth in RNA-seq, and peak-density overviews across megabases. The recipes below start from a canonical per-bin count and build toward more specialised variants.
+
+Count Overlapping Features
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Count the number of features overlapping each 1 kb bin across the genome:
+
+.. code-block:: sql
+
+   SELECT RASTERIZE(interval, 1000) AS depth
+   FROM features
+
+**Sample output:**
+
+.. code-block:: text
+
+   ┌────────┬────────┬────────┬───────┐
+   │ chrom  │ start  │  end   │ depth │
+   ├────────┼────────┼────────┼───────┤
+   │ chr1   │      0 │   1000 │     3 │
+   │ chr1   │   1000 │   2000 │     1 │
+   │ chr1   │   2000 │   3000 │     0 │
+   │ ...    │    ... │    ... │   ... │
+   └────────┴────────┴────────┴───────┘
+
+Each row represents one genomic bin. Bins with no overlapping features appear with a count of zero. An interval that spans more than one bin is counted in each bin it overlaps (the ``bedtools coverage`` convention), so the sum of bin counts is generally greater than the number of source intervals.
+
+**Use case:** Compute read depth or feature density at a fixed resolution.
+
+Custom Bin Size
+~~~~~~~~~~~~~~~
+
+Use a finer resolution of 100 bp:
+
+.. code-block:: sql
+
+   SELECT RASTERIZE(interval, 100) AS depth
+   FROM reads
+
+**Use case:** High-resolution count tracks for visualisation.
+
+Named Resolution Parameter
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The resolution can also be supplied by name:
+
+.. code-block:: sql
+
+   SELECT RASTERIZE(interval, resolution := 500) AS depth
+   FROM features
+
+Both ``:=`` and ``=>`` are accepted for named parameters.
+
+.. note::
+
+   Weighted summary statistics (mean, sum, min, max over interval values, with bin-boundary-aware weighting) are not yet implemented. See the project tracker for the follow-up.
+
+Filtered Rasterization
+----------------------
+
+Strand-Specific Counts
+~~~~~~~~~~~~~~~~~~~~~~
+
+Compute per-bin counts for each strand separately by filtering:
+
+.. code-block:: sql
+
+   -- Plus strand
+   SELECT RASTERIZE(interval, 1000) AS depth
+   FROM features
+   WHERE strand = '+'
+
+.. code-block:: sql
+
+   -- Minus strand
+   SELECT RASTERIZE(interval, 1000) AS depth
+   FROM features
+   WHERE strand = '-'
+
+**Use case:** Strand-specific signal tracks for RNA-seq or stranded assays.
+
+High-Scoring Features
+~~~~~~~~~~~~~~~~~~~~~
+
+Restrict counts to features above a quality threshold:
+
+.. code-block:: sql
+
+   SELECT RASTERIZE(interval, 1000) AS depth
+   FROM features
+   WHERE score > 10
+
+5' End Counting
+~~~~~~~~~~~~~~~
+
+To count only the 5' ends of features (e.g. TSS or read starts), first
+create a view or CTE that trims each interval to its 5' end, then apply
+``RASTERIZE``:
+
+.. code-block:: sql
+
+   WITH five_prime AS (
+       SELECT chrom, "start", "start" + 1 AS "end"
+       FROM features
+       WHERE strand = '+'
+       UNION ALL
+       SELECT chrom, "end" - 1 AS "start", "end"
+       FROM features
+       WHERE strand = '-'
+   )
+   SELECT RASTERIZE(interval, 1000) AS tss_count
+   FROM five_prime
+
+Normalised Counts
+-----------------
+
+RPM Normalisation
+~~~~~~~~~~~~~~~~~
+
+Normalise bin counts to reads per million (RPM) by dividing by the total
+number of reads:
+
+.. code-block:: sql
+
+   WITH bins AS (
+       SELECT RASTERIZE(interval, 1000) AS depth
+       FROM reads
+   ),
+   total AS (
+       SELECT COUNT(*) AS n FROM reads
+   )
+   SELECT
+       bins.chrom,
+       bins.start,
+       bins.end,
+       bins.depth * 1000000.0 / total.n AS rpm
+   FROM bins, total

pyproject.toml

@@ -57,6 +57,9 @@ path = "build-hooks/metadata.py"
 
 [tool.pytest.ini_options]
 addopts = "--cov --cov-config=.coveragerc"
+markers = [
+    "integration: tests exercising real bedtools subprocesses and DuckDB I/O",
+]
 
 [tool.ruff]
 line-length = 89

src/giql/dialect.py

@@ -13,6 +13,7 @@
 
 from giql.expressions import Contains
 from giql.expressions import GIQLCluster
+from giql.expressions import GIQLRasterize
 from giql.expressions import GIQLDistance
 from giql.expressions import GIQLMerge
 from giql.expressions import GIQLNearest
@@ -54,6 +55,7 @@ class Parser(Parser):
         FUNCTIONS = {
             **Parser.FUNCTIONS,
             "CLUSTER": GIQLCluster.from_arg_list,
+            "RASTERIZE": GIQLRasterize.from_arg_list,
             "MERGE": GIQLMerge.from_arg_list,
             "DISTANCE": GIQLDistance.from_arg_list,
             "NEAREST": GIQLNearest.from_arg_list,

src/giql/expressions.py

@@ -142,6 +142,33 @@ def from_arg_list(cls, args):
         return cls(**kwargs)
 
 
+class GIQLRasterize(exp.Func):
+    """RASTERIZE aggregate function that projects intervals onto a fixed bin grid.
+
+    Tiles the genome into fixed-width bins and counts the number of
+    overlapping intervals per bin (bedtools-coverage convention: an
+    interval that spans multiple bins is counted in each of them).
+
+    Examples:
+        RASTERIZE(interval, 1000)
+        RASTERIZE(interval, resolution := 1000)
+    """
+
+    arg_types = {
+        "this": True,  # genomic column
+        "resolution": True,  # bin width (positional or named)
+    }
+
+    @classmethod
+    def from_arg_list(cls, args):
+        kwargs, positional_args = _split_named_and_positional(args)
+        if len(positional_args) > 0:
+            kwargs["this"] = positional_args[0]
+        if len(positional_args) > 1:
+            kwargs["resolution"] = positional_args[1]
+        return cls(**kwargs)
+
+
 class GIQLDistance(exp.Func):
     """DISTANCE function for calculating genomic distances between intervals.