Release gtars v0.8.0

.gitignore

@@ -23,8 +23,31 @@ bin/
 /.idea/gtars.iml
 /gtars/tests/data/test1.bw
 
+.claude/
 .DS_Store
 .Rhistory
 tests/data/out/region_scoring_count.csv.gz
 /gtars-refget/tests/store_test/rgstore.json
 /gtars-refget/tests/store_test/sequences.rgsi
+
+# Large benchmark data and validation files
+tests/data/interval_ranges_benchmark/
+tests/data/partitions_benchmark/
+gtars-genomicdist/examples/benchmark_*.rs
+gtars-genomicdist/examples/partitions_demo.rs
+gtars-genomicdist/tests/
+*.annotation.gtf.gz
+tests/data/fasta/sacCer3.fa
+tests/data/fasta/sacCer3.rgsi
+gtars-r/tests/explore_sacCer3.*
+gtars-r/tests/smoketest_sacCer3.R
+gtars-r/tests/hg19.fa
+gtars-r/tests/hg19.fa.gz
+gtars-r/tests/benchmark_genomicdist.*
+gtars-r/tests/compare_genomicdist.*
+gtars-r/tests/tutorial_genomicdist.*
+gtars-r/tests/*.bed
+gtars-r/tests/*.html
+gtars-r/tests/export_reference_data.R
+gtars-r/tests/ref/
+gtars-r/tests/smoketest_set_operations.*

Cargo.toml

@@ -27,4 +27,5 @@ serde = { version = "1.0.203", features=["derive"] }
 flate2 = "1.1.2"
 indicatif = "0.18.0"
 serde_json = "1.0.135"
+bincode = "1.3.3"
 byteorder = "1.5.0"

Makefile

@@ -5,5 +5,8 @@ wasm:
 test:
 	cargo test --all --workspace -- --nocapture
 
+test-r:
+	bash gtars-r/test-r.sh
+
 fmt:
 	cargo fmt --all -- --check

README.md

@@ -65,7 +65,7 @@ print(__version__)
 
 ## Usage
 
-`gtars` provides several useful tools. There are 3 ways to use `gtars`. 
+`gtars` provides several useful tools. There are 3 ways to use `gtars`.
 
 ### 1. From Python
 
@@ -75,6 +75,56 @@ Using bindings, you can call some `gtars` functions from within Python.
 
 To see the available tools you can use from the CLI run `gtars --help`. To see the help for a specific tool, run `gtars <tool> --help`.
 
+Available subcommands:
+
+| Subcommand | Description |
+|---|---|
+| `genomicdist` | Compute genomic distribution statistics for a BED file |
+| `prep` | Pre-serialize GTF gene models or signal matrices to binary for fast loading |
+| `ranges` | Interval set algebra operations on BED files (reduce, trim, promoters, setdiff, pintersect, concat, union, jaccard) |
+| `consensus` | Compute consensus regions across multiple BED files |
+
+#### Preparing reference files
+
+Pre-compile reference files to binary for fast repeated loading. This is optional but recommended when running `genomicdist` repeatedly against the same references.
+
+```bash
+# Pre-compile a GTF gene model
+gtars prep --gtf gencode.v47.annotation.gtf.gz
+
+# Pre-compile an open signal matrix
+gtars prep --signal-matrix openSignalMatrix_hg38.txt
+```
+
+Output defaults to the input path with `.bin` appended (stripping `.gz` first). Use `-o` to specify a custom output path.
+
+#### Computing genomic distributions
+
+```bash
+gtars genomicdist \
+  --bed query.bed \
+  --gtf gencode.v47.annotation.gtf.bin \
+  --tss tss.bed \
+  --chrom-sizes hg38.chrom.sizes \
+  --signal-matrix openSignalMatrix_hg38.txt.bin \
+  --output result.json
+```
+
+All flags except `--bed` are optional. Omit any flag to skip that analysis:
+
+| Flag | Required | Description |
+|---|---|---|
+| `--bed` | yes | Input BED file |
+| `--gtf` | no | GTF/GTF.gz or pre-compiled `.bin` — enables partitions and TSS distances |
+| `--tss` | no | TSS BED file — overrides GTF-derived TSS for distance calculation |
+| `--chrom-sizes` | no | Chrom sizes file — enables expected partitions |
+| `--signal-matrix` | no | Signal matrix TSV or pre-compiled `.bin` — enables open chromatin enrichment |
+| `--bins` | no | Number of bins for region distribution (default: 250) |
+| `--promoter-upstream` | no | Upstream distance from TSS for promoter regions (default: 200) |
+| `--promoter-downstream` | no | Downstream distance from TSS for promoter regions (default: 2000) |
+| `--output` | no | Output JSON path (default: stdout) |
+| `--compact` | no | Compact JSON output (default: pretty-printed) |
+
 ### 3. As a rust library
 
 You can link `gtars` as a library in your rust project. To do so, add the following to your `Cargo.toml` file:
@@ -84,7 +134,8 @@ You can link `gtars` as a library in your rust project. To do so, add the follow
 gtars = { git = "https://github.com/databio/gtars/gtars" }
 ```
 
-we wall-off crates using features, so you will need to enable the features you want. For example, to use the `gtars` crate the overlap tool, you would do:
+We wall off crates using features, so you will need to enable the features you want. For example, to use the overlap tool:
+
 ```toml
 [dependencies]
 gtars = { git = "https://github.com/databio/gtars/gtars", features = ["overlaprs"] }

gtars-cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "gtars-cli"
-version = "0.7.0"
+version = "0.8.0"
 edition = "2024"
 description = "Performance critical tools for genomic interval analysis. This is the CLI"
 homepage = "https://github.com/databio/gtars"
@@ -22,11 +22,17 @@ anyhow = { workspace = true }
 gtars-scoring = { path = "../gtars-scoring", optional=true, version="0.5.1" }
 gtars-fragsplit = { path = "../gtars-fragsplit", optional=true, version="0.5.0" }
 gtars-igd = { path = "../gtars-igd", optional=true, version="0.5.1" }
-gtars-uniwig = { path = "../gtars-uniwig", optional=true, version="0.7.0" }
+gtars-uniwig = { path = "../gtars-uniwig", optional=true, version="0.8.0" }
 gtars-overlaprs = { path = "../gtars-overlaprs", optional = true, version="0.5.1" }
 gtars-bbcache = { path = "../gtars-bbcache", optional=true, version="0.5.3" }
+gtars-genomicdist = { path = "../gtars-genomicdist", optional=true, version="0.6.0" }
 gtars-core = { path = "../gtars-core", version="0.5.5", features=["bigbed", "http"] }
 
+# serialization
+serde = { workspace = true }
+serde_json = "1"
+bincode = { workspace = true }
+
 [[bin]]
 name = "gtars"
 path = "src/main.rs"
@@ -39,3 +45,4 @@ bbcache = ["dep:gtars-bbcache"]
 igd = ["dep:gtars-igd"]
 fragsplit = ["dep:gtars-fragsplit"]
 overlaprs = ["dep:gtars-overlaprs"]
+genomicdist = ["dep:gtars-genomicdist"]

gtars-cli/src/consensus/cli.rs

@@ -0,0 +1,28 @@
+use clap::{Arg, Command};
+
+pub const CONSENSUS_CMD: &str = "consensus";
+
+pub fn create_consensus_cli() -> Command {
+    Command::new(CONSENSUS_CMD)
+        .about("Compute consensus regions across multiple BED files. Outputs BED4 (chr, start, end, count).")
+        .arg(
+            Arg::new("beds")
+                .long("beds")
+                .required(true)
+                .num_args(2..)
+                .help("Two or more input BED files"),
+        )
+        .arg(
+            Arg::new("min-count")
+                .long("min-count")
+                .required(false)
+                .default_value("1")
+                .help("Minimum overlap count to include a region in output"),
+        )
+        .arg(
+            Arg::new("output")
+                .long("output")
+                .required(false)
+                .help("Output BED file (default: stdout)"),
+        )
+}

gtars-cli/src/consensus/handlers.rs

@@ -0,0 +1,70 @@
+use std::fs::File;
+use std::io::{self, Write};
+use std::path::Path;
+
+use anyhow::{Context, Result};
+use clap::ArgMatches;
+
+use gtars_core::models::RegionSet;
+use gtars_genomicdist::consensus::consensus;
+
+pub fn run_consensus(matches: &ArgMatches) -> Result<()> {
+    let bed_paths: Vec<&String> = matches
+        .get_many::<String>("beds")
+        .expect("--beds is required")
+        .collect();
+
+    let min_count: u32 = matches
+        .get_one::<String>("min-count")
+        .unwrap()
+        .parse()
+        .context("--min-count must be a positive integer")?;
+
+    let output_path = matches.get_one::<String>("output");
+
+    // Load all BED files
+    let sets: Vec<RegionSet> = bed_paths
+        .iter()
+        .map(|p| {
+            RegionSet::try_from(p.as_str())
+                .map_err(|e| anyhow::anyhow!("Failed to load BED file {}: {}", p, e))
+        })
+        .collect::<Result<Vec<_>>>()?;
+
+    eprintln!("Computing consensus across {} BED files...", sets.len());
+
+    let regions = consensus(&sets);
+
+    // Filter by min-count
+    let filtered: Vec<_> = regions
+        .iter()
+        .filter(|r| r.count >= min_count)
+        .collect();
+
+    eprintln!(
+        "{} consensus regions ({} after --min-count {} filter)",
+        regions.len(),
+        filtered.len(),
+        min_count,
+    );
+
+    match output_path {
+        Some(p) => {
+            let mut file = File::create(Path::new(p))
+                .with_context(|| format!("Failed to create output file: {}", p))?;
+            for r in &filtered {
+                writeln!(file, "{}\t{}\t{}\t{}", r.chr, r.start, r.end, r.count)?;
+            }
+            eprintln!("Output written to {}", p);
+        }
+        None => {
+            let stdout = io::stdout();
+            let mut out = stdout.lock();
+            for r in &filtered {
+                writeln!(out, "{}\t{}\t{}\t{}", r.chr, r.start, r.end, r.count)?;
+            }
+        }
+    }
+
+    Ok(())
+}

gtars-cli/src/consensus/mod.rs

@@ -0,0 +1,2 @@
+pub mod cli;
+pub mod handlers;

gtars-cli/src/genomicdist/cli.rs

@@ -0,0 +1,66 @@
+use clap::{Arg, Command, arg};
+
+pub const GENOMICDIST_CMD: &str = "genomicdist";
+
+pub fn create_genomicdist_cli() -> Command {
+    Command::new(GENOMICDIST_CMD)
+        .about("Compute genomic distribution statistics for a BED file.")
+        .arg(
+            arg!(--bed <BED>)
+                .required(true)
+                .help("Path to input BED file"),
+        )
+        .arg(
+            arg!(--gtf <GTF>)
+                .required(false)
+                .help("Path to GTF/GTF.gz gene model (enables partitions; also TSS distances if no --tss)"),
+        )
+        .arg(
+            arg!(--tss <TSS>)
+                .required(false)
+                .help("Path to TSS BED file (overrides GTF-derived TSS for distance calculation)"),
+        )
+        .arg(
+            Arg::new("chrom-sizes")
+                .long("chrom-sizes")
+                .required(false)
+                .help("Path to chrom.sizes file (enables expected partitions and promoter trimming)"),
+        )
+        .arg(
+            arg!(--output <OUTPUT>)
+                .required(false)
+                .help("Output JSON path (default: stdout)"),
+        )
+        .arg(
+            arg!(--bins <BINS>)
+                .required(false)
+                .default_value("250")
+                .help("Number of bins for region distribution"),
+        )
+        .arg(
+            Arg::new("signal-matrix")
+                .long("signal-matrix")
+                .required(false)
+                .help("Path to open signal matrix TSV (enables cell-type open chromatin enrichment)"),
+        )
+        .arg(
+            Arg::new("promoter-upstream")
+                .long("promoter-upstream")
+                .required(false)
+                .default_value("200")
+                .help("Upstream distance (bp) from TSS to define promoter regions"),
+        )
+        .arg(
+            Arg::new("promoter-downstream")
+                .long("promoter-downstream")
+                .required(false)
+                .default_value("2000")
+                .help("Downstream distance (bp) from TSS to define promoter regions"),
+        )
+        .arg(
+            Arg::new("compact")
+                .long("compact")
+                .action(clap::ArgAction::SetTrue)
+                .help("Compact JSON output (default: pretty-printed)"),
+        )
+}