domains / science / genomic-interval-analysis / gtars

gtars

Skill card

combined

The K-Dense-AI copy is a rigorous, version-pinned audit and trust-gate procedure (exact 0.10.0 pins, SHA-256 verification, coordinate/strand/assembly data contract, and a local validator). The other three copies (Vibe-Skills, medical-research-skills, and OpenClaw-Medical-Skills) are high-level usage guides that provide the actual API and CLI workflows (overlap, coverage, tokenization, refget, fragment processing) but lack the safety and data-integrity constraints. The Vibe-Skills and OpenClaw copies are nearly identical and contain a typo in the Python install command (`uv uv pip install`), while the medical-research-skills copy is a summarized version of the same guide. Because the K-Dense copy lacks the practical API examples and the other copies lack the critical safety and data-contract steps, crowning one would hide a real alternative procedure.

Repositories

Other copies

Combined skill

---
name: gtars
description: High-performance toolkit for genomic interval analysis in Rust with Python bindings. Use for genomic regions, BED files, coverage tracks, overlap detection, tokenization for ML, or fragment analysis.
license: MIT
---

# Gtars: Genomic Tools and Algorithms in Rust

## Overview
Gtars is a high-performance Rust toolkit for manipulating, analyzing, and processing genomic interval data. It provides specialized tools for overlap detection, coverage analysis, tokenization for machine learning, and reference sequence management.

## Safety and Data Contract
Before any operation, apply this contract:
1. **Coordinates:** BED intervals are 0-based and half-open: `[start, end)`. Require `0 <= start < end <= contig_length`. Gtars coordinates are `u32`, so reject values above `4,294,967,295`.
2. **Assembly:** record an assembly accession/version and the SHA-256 of the exact chromosome-sizes or refget sequence-collection metadata. Never infer assembly from filenames or `chr` prefixes.
3. **Contigs:** compare names exactly. `1` and `chr1`, alternate loci, decoys, and mitochondrial aliases are not interchangeable.
4. **Sorting:** preserve the original file, then sort a copy by chromosome-sizes order and numeric start/end when the operation requires it. Python `RegionSet(path)` currently sorts lexicographically by contig and start while loading; do not rely on original row order afterward. Construction does not merge overlapping intervals; call `reduce()` explicitly when that is intended.
5. **Strand:** BED6 uses `+`, `-`, or `.`. `Region.rest` retains trailing BED fields, but a file-backed Python `RegionSet` currently initializes its separate `strands` vector to `*`. `sort()` reorders regions without reordering that vector, and several set operations drop strand. Preserve and validate strand externally when it is scientifically meaningful.
6. **Duplicates/adjacency:** choose policies explicitly. `reduce()` and consensus merge overlapping **and adjacent** intervals; ordinary half-open overlap does not treat `[0,10)` and `[10,20)` as overlapping.

## Installation and Trust Gate
The Python wheel contains a PyO3 native extension. Treat installation as code execution:
1. Confirm the official PyPI/crates.io/GitHub owner and immutable version.
2. Review filenames, platform tags, release provenance, license, and SHA-256. Verify checksums from the exact release.
3. Never run an untrusted prebuilt binary, wheel, source tree, Cargo build script, or archive installer. Use isolation and CPU/RAM/disk/time limits.
4. Keep a lockfile and artifact hashes with the analysis manifest.

After review, create an isolated Python environment:
```bash
uv venv --python 3.11 .venv-gtars
uv pip install --dry-run --python .venv-gtars/bin/python "gtars==0.10.0"
uv pip install --python .venv-gtars/bin/python "gtars==0.10.0"
.venv-gtars/bin/python -c "import gtars; assert gtars.__version__ == '0.10.0'; print(gtars.__version__)"
```

For the CLI (source-reviewed template):
```bash
cargo install gtars-cli --version 0.10.0 --locked
gtars --version
gtars --help
```

For a Rust project, pin the wrapper and enable only required features:
```toml
[dependencies]
gtars = { version = "=0.10.0", default-features = false, features = [
  "core", "overlaprs", "uniwig", "tokenizers", "refget"
] }
```

## Core Capabilities and Workflows

### 1. Overlap Detection and IGD Indexing
Efficiently detect overlaps between genomic intervals using the Integrated Genome Database (IGD) data structure.

**Quick example:**
```python
import gtars

# Load two region sets
peaks = gtars.RegionSet.from_bed("chip_peaks.bed")
promoters = gtars.RegionSet.from_bed("promoters.bed")

# Find overlaps
overlapping_peaks = peaks.filter_overlapping(promoters)

# Export results
overlapping_peaks.to_bed("peaks_in_promoters.bed")
```

### 2. Coverage Track Generation
Generate coverage tracks from sequencing data with the uniwig module.

**Quick example:**
```bash
# Generate WIG coverage at a given resolution
gtars uniwig generate --input atac_fragments.bed --output coverage.wig --resolution 10

# Generate BigWig coverage for genome browser visualization
gtars uniwig generate --input atac_fragments.bed --output coverage.bw --format bigwig
```

### 3. Genomic Tokenization
Convert genomic regions into discrete tokens for machine learning applications.

**Quick example:**
```python
from gtars.tokenizers import TreeTokenizer
import gtars

# Load regions and build a tokenizer from BED
regions = gtars.RegionSet.from_bed("training_peaks.bed")
tokenizer = TreeTokenizer.from_bed_file("training_peaks.bed")

# Tokenize each region into a discrete representation
tokens = [tokenizer.tokenize(r.chromosome, r.start, r.end) for r in regions]
print(tokens[:5])
```

### 4. Reference Sequence Management
Handle reference genome sequences and compute digests following the GA4GH refget protocol.

**Quick example:**
```python
# Load reference and extract sequences
store = gtars.RefgetStore.from_fasta("hg38.fa")
sequence = store.get_subsequence("chr1", 1000, 2000)
```

### 5. Fragment Processing
Split and analyze fragment files, particularly useful for single-cell genomics data.

**Quick example:**
```bash
# Split fragments by clusters
gtars fragsplit cluster-split --input fragments.tsv --clusters clusters.txt --output-dir ./by_cluster/
```

### 6. Fragment Scoring
Score fragment overlaps against reference datasets.

**Quick example:**
```bash
# Score fragments against reference
gtars scoring score --fragments fragments.bed --reference reference.bed --output scores.txt
```

## Python vs CLI Usage
**Use Python API when:**
- Integrating with analysis pipelines
- Need programmatic control
- Working with complex data structures

**Use CLI when:**
- Batch processing large files
- Shell scripting workflows
- Quick one-off analyses