/gtars

name: gtars
description: Use Gtars for local genomic interval models and set algebra, overlaps and counts, consensus and coverage, tokenization, fragment processing, and refget/BEDbase planning across Python, Rust, and the CLI.
license: MIT
compatibility: Python bindings require Python 3.10+ and gtars 0.9.2. The Rust meta-crate and gtars-cli are 0.9.0 and require a Rust toolchain supporting Edition 2024; upstream declares no rust-version. Bundled audit CLIs use only Python 3.10+ standard library and are local/network-free. Remote constructors, pretrained tokenizers, refget, and BEDbase caching require explicit network and storage approval.
allowed-tools: Read Write Edit Bash Glob
metadata:
  version: "1.3"
  skill-author: K-Dense Inc.

Gtars

Gtars provides native Rust implementations, Python bindings, and a feature-gated `gtars` binary for genomic interval and reference-sequence work. Start with the bundled local inspectors; call upstream code only after the data contract, provenance, resource bounds, and side effects are explicit.

Verified snapshot (2026-07-23)

• Python: [`gtars==0.9.2`](https://pypi.org/project/gtars/), released

2026-06-17, `Requires-Python >=3.10`.

• Rust meta-crate: [`gtars=0.9.0`](https://crates.io/crates/gtars), released

2026-06-15. Its default feature set is empty.

• CLI crate/binary: [`gtars-cli=0.9.0`](https://crates.io/crates/gtars-cli);

the installed binary is named `gtars`.

• Direct refget crate: [`gtars-refget=0.9.1`](https://crates.io/crates/gtars-refget),

released 2026-06-17. `gtars=0.9.0` itself pins its component release set, which includes refget 0.9.0.

• Upstream intentionally versions workspace crates, Python bindings, and CLI

independently. Do not assume matching numbers mean matching artifacts.

• The published docs changelog stops at 0.5.1. API examples here were checked

against the 0.9.2 Python stubs/runtime and the `v0.9.0` CLI/Rust source.

The `license: MIT` field covers this skill. Published `gtars` crates declare MIT, while the GitHub repository currently displays BSD-2-Clause at the root; verify the exact artifact's license before redistribution.

Native-code trust gate and exact pins

The Python wheel contains a PyO3 native extension. Cargo installation compiles a native binary and can run dependency build scripts. Treat either path 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. GitHub's v0.9.0 binary release includes per-archive `.sha256` sidecars. 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 that review, create an isolated Python environment:

uv venv --python 3.11 .venv-gtars
uv pip install --dry-run --python .venv-gtars/bin/python "gtars==0.9.2"
uv pip install --python .venv-gtars/bin/python "gtars==0.9.2"
.venv-gtars/bin/python -c \
  "import gtars; assert gtars.__version__ == '0.9.2'; print(gtars.__version__)"

For the reviewed CLI source release:

cargo install gtars-cli --version 0.9.0 --locked
gtars --version
gtars --help

For a Rust project, pin the wrapper exactly and enable only required features:

[dependencies]
gtars = { version = "=0.9.0", default-features = false, features = [
  "core", "overlaprs", "uniwig", "tokenizers", "refget"
] }

Use `gtars-refget = "=0.9.1"` directly only when the newer direct component API is required and compatibility has been tested. Do not replace these pins with a Git branch or an unreviewed release.

Genomic data contract

Apply this contract before every operation:

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. Rename or liftover only as a separately reviewed transformation. 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. 5. **Strand:** BED6 uses `+`, `-`, or `.`. `Region.rest` retains trailing BED fields, but a file-backed Python `RegionSet` currently initializes its separate `strands` vector to `*`. 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.

Run the local validator first:

python3 -B scripts/bed_validator.py \
  --input data.bed.gz \
  --assembly GRCh38.p14 \
  --chrom-sizes GRCh38.p14.chrom.sizes \
  --require-sorted

Safe local workflow

1. Inventory local files, checksums, assembly, contig dictionary, coordinate system, strand policy, patient/replicate groups, and intended outputs. 2. Validate BED/fragments and estimate work. Pilot a small synthetic file. 3. Choose Python, CLI, or Rust from the documented surface; do not translate API names by guesswork. 4. Set hard limits for input bytes/records/files, threads/jobs, memory, temporary disk, output size, and wall time. 5. Run in a dedicated output directory. Refuse collisions unless overwrite was explicitly approved. 6. Revalidate out