feat: Add coverage method (#112)

* feat: Coverage

* Add coverage tests

* LaztFrame alias

* chore: Version bump

* chore: Docs update

Author: mwiewior

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "polars_bio"
-version = "0.7.4"
+version = "0.8.0"
 edition = "2021"
 
 [lib]

Cargo.toml

@@ -31,13 +31,17 @@ It provides a DataFrame API for genomics data and is designed to be blazing fast
 
 ![count-overlaps-single.png](docs/assets/count-overlaps-single.png)
 
+![coverage-single.png](docs/assets/coverage-single.png)
+
 ## Parallel performance 🏃‍🏃‍
 ![overlap-parallel.png](docs/assets/overlap-parallel.png)
 
 ![overlap-parallel.png](docs/assets/nearest-parallel.png)
 
 ![count-overlaps-parallel.png](docs/assets/count-overlaps-parallel.png)
 
+![coverage-parallel.png](docs/assets/coverage-parallel.png)
+
 
 
 Read the [documentation](https://biodatageeks.github.io/polars-bio/)

README.md

@@ -10,7 +10,7 @@
 | cluster                                            | :white_check_mark: |                    | :white_check_mark: | :white_check_mark: |                    |                    |
 | [merge](api.md#polars_bio.merge)                   | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |                    | :white_check_mark: |
 | complement                                         | :white_check_mark: | :construction:     |                    | :white_check_mark: | :white_check_mark: |                    |
-| coverage                                           | :white_check_mark: |                    | :white_check_mark: | :white_check_mark: |                    | :white_check_mark: |
+| [coverage](api.md#polars_bio.coverage)             | :white_check_mark: |  :white_check_mark:                  | :white_check_mark: | :white_check_mark: |                    | :white_check_mark: |
 | [expand](api.md#polars_bio.LazyFrame.expand)       | :white_check_mark: | :white_check_mark:     | :white_check_mark: | :white_check_mark: |                    | :white_check_mark: |
 | [sort](api.md#polars_bio.LazyFrame.sort_bedframe)  | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |                    | :white_check_mark: |
 | [read_table](api.md#polars_bio.read_table)         | :white_check_mark: | :white_check_mark: | :white_check_mark: | :white_check_mark: |                    | :white_check_mark: |

docs/assets/coverage-parallel.png

@@ -21,24 +21,16 @@
    "id": "62a7b57c30bf54e2",
    "metadata": {
     "ExecuteTime": {
-     "end_time": "2025-03-05T16:41:54.268168Z",
-     "start_time": "2025-03-05T16:41:53.664194Z"
+     "end_time": "2025-03-07T10:02:23.527490Z",
+     "start_time": "2025-03-07T10:02:23.525921Z"
     }
    },
    "source": [
     "import polars_bio as pb\n",
     "import polars as pl"
    ],
-   "outputs": [
-    {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "INFO:polars_bio:Creating BioSessionContext\n"
-     ]
-    }
-   ],
-   "execution_count": 2
+   "outputs": [],
+   "execution_count": 8
   },
   {
    "cell_type": "code",
@@ -646,34 +638,34 @@
   {
    "metadata": {
     "ExecuteTime": {
-     "end_time": "2025-02-28T11:52:12.169029Z",
-     "start_time": "2025-02-28T11:52:12.167384Z"
+     "end_time": "2025-03-07T10:02:16.509828Z",
+     "start_time": "2025-03-07T10:02:16.507744Z"
     }
    },
    "cell_type": "code",
    "source": "gcs_vcf_path = \"gs://genomics-public-data/platinum-genomes/vcf/NA12878_S1.genome.vcf\"",
    "id": "31f0f3d0974245bd",
    "outputs": [],
-   "execution_count": 16
+   "execution_count": 5
   },
   {
    "metadata": {
     "ExecuteTime": {
-     "end_time": "2025-02-28T11:52:13.441345Z",
-     "start_time": "2025-02-28T11:52:13.439461Z"
+     "end_time": "2025-03-07T10:02:19.374881Z",
+     "start_time": "2025-03-07T10:02:19.372753Z"
     }
    },
    "cell_type": "code",
    "source": "info_fields=[\"AC\", \"AF\"]",
    "id": "816c419b3b45ee44",
    "outputs": [],
-   "execution_count": 17
+   "execution_count": 6
   },
   {
    "metadata": {
     "ExecuteTime": {
-     "end_time": "2025-02-28T11:52:17.666747Z",
-     "start_time": "2025-02-28T11:52:16.365292Z"
+     "end_time": "2025-03-07T10:02:52.904221Z",
+     "start_time": "2025-03-07T10:02:41.364349Z"
     }
    },
    "cell_type": "code",
@@ -713,12 +705,12 @@
        "<small>shape: (3, 10)</small><table border=\"1\" class=\"dataframe\"><thead><tr><th>chrom</th><th>start</th><th>end</th><th>id</th><th>ref</th><th>alt</th><th>qual</th><th>filter</th><th>ac</th><th>af</th></tr><tr><td>str</td><td>u32</td><td>u32</td><td>str</td><td>str</td><td>str</td><td>f64</td><td>str</td><td>list[i32]</td><td>list[f32]</td></tr></thead><tbody><tr><td>&quot;chrM&quot;</td><td>1</td><td>1</td><td>&quot;&quot;</td><td>&quot;G&quot;</td><td>&quot;&quot;</td><td>0.0</td><td>&quot;PASS&quot;</td><td>null</td><td>null</td></tr><tr><td>&quot;chrM&quot;</td><td>2</td><td>72</td><td>&quot;&quot;</td><td>&quot;A&quot;</td><td>&quot;&quot;</td><td>0.0</td><td>&quot;PASS&quot;</td><td>null</td><td>null</td></tr><tr><td>&quot;chrM&quot;</td><td>73</td><td>73</td><td>&quot;&quot;</td><td>&quot;G&quot;</td><td>&quot;A&quot;</td><td>8752.780273</td><td>&quot;TruthSensitivityTranche99.90to…</td><td>[2]</td><td>[1.0]</td></tr></tbody></table></div>"
       ]
      },
-     "execution_count": 18,
+     "execution_count": 9,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
-   "execution_count": 18
+   "execution_count": 9
   },
   {
    "metadata": {},

docs/assets/coverage-single.png

@@ -7,12 +7,16 @@
 
 ![count-overlaps-single.png](assets/count-overlaps-single.png)
 
+![coverage-single.png](assets/coverage-single.png)
+
 ## Parallel performance 🏃‍🏃‍
 ![overlap-parallel.png](assets/overlap-parallel.png)
 
 ![overlap-parallel.png](assets/nearest-parallel.png)
 
 ![count-overlaps-parallel.png](assets/count-overlaps-parallel.png)
+
+![coverage-parallel.png](assets/coverage-parallel.png)
 ## Benchmarks 🧪
 ### Detailed results shortcuts 👨‍🔬
 - [Binary operations](#binary-operations)

docs/features.md

@@ -14,7 +14,7 @@
     sql,
 )
 from .polars_ext import PolarsRangesOperations as LazyFrame
-from .range_op import FilterOp, count_overlaps, merge, nearest, overlap
+from .range_op import FilterOp, count_overlaps, coverage, merge, nearest, overlap
 from .range_viz import visualize_intervals
 
 POLARS_BIO_MAX_THREADS = "datafusion.execution.target_partitions"
@@ -26,6 +26,7 @@
     "nearest",
     "merge",
     "count_overlaps",
+    "coverage",
     "ctx",
     "FilterOp",
     "visualize_intervals",

docs/notebooks/cookbook.ipynb

@@ -222,3 +222,18 @@ def expand(
         if midsk in schema:
             df = df.drop(midsk)
         return df
+
+    def coverage(
+        self,
+        other_df: pl.LazyFrame,
+        cols1=["chrom", "start", "end"],
+        cols2=["chrom", "start", "end"],
+        suffixes: tuple[str, str] = ("_1", "_2"),
+    ) -> pl.LazyFrame:
+        """
+        !!! note
+            Alias for [coverage](api.md#polars_bio.coverage)
+        """
+        return pb.coverage(
+            self._ldf, other_df, cols1=cols1, cols2=cols2, suffixes=suffixes
+        )