gtars – Coding skill for AI agents

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-10-01)

• Published Python wheel: [gtars==0.10.0](https://pypi.org/project/gtars/0.10.0/),

released 2026-09-05, Requires-Python >=3.10; local examples were exercised

on Python 3.12 with synthetic intervals, fragments, and FASTA.

• Rust meta-crate and CLI: [gtars=0.10.0](https://crates.io/crates/gtars/0.10.0)

and [gtars-cli=0.10.0](https://crates.io/crates/gtars-cli/0.10.0), released

2026-09-05. The binary is gtars; the wrapper's default feature set is empty.

Rust/CLI examples are source-reviewed templates, not compiled executions.

• Direct [gtars-refget=0.11.0](https://crates.io/crates/gtars-refget/0.11.0)

was released 2026-09-22. Its Rust list_sequences() now returns a Result.

The wrapper requests refget 0.10.x; keep Cargo.lock because component

dependencies use compatible ranges, not exact pins.

• A [gtars-python-v0.11.0 Git tag](https://github.com/databio/gtars/releases/tag/gtars-python-v0.11.0)

exists, but PyPI still publishes 0.10.0. Do not assume that Git tags, Python

packages, components, or CLI versions coincide.

• Published guides contain older examples. This review used the PyPI 0.10.0

source distribution/runtime, published CLI crate source, and current releases.

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.

Verify checksums from the exact release; do not reuse older binary archives.

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.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 source-reviewed CLI release (installation template, not run in this audit):

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

For a Rust project, this source-reviewed template pins the wrapper and enables

only required features; retain Cargo.lock for transitive versions:

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

Use gtars-refget = "=0.11.0" 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. 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.

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 output sorting, bounds, row counts, checksums, and provenance.

Current Python core

Imports are from submodules, not the gtars top level:

from gtars.models import Region, RegionSet

query = RegionSet.from_regions(
    [
        Region(chr="chr1", start=100, end=200, rest=None),
        Region(chr="chr1", start=300, end=400, rest=None),
    ],
    strands=["+", "-"],
)
universe = RegionSet.from_vectors(
    ["chr1", "chr1"],
    [150, 500],
    [350, 600],
)

counts = query.count_overlaps(universe)       # one count per query region
flags = query.any_overlaps(universe)          # one bool per query region
indices = query.find_overlaps(universe)       # indices into universe
pieces = query.intersect_all(universe)        # all intersection fragments
fraction = query.coverage(universe)           # fraction of query bp covered

RegionSet.sort() mutates and returns None. Set algebra includes reduce,

setdiff, pintersect (pairs by index), concat, union, jaccard,

coverage, overlap_coefficient, intersect_all, closest, cluster, and

gaps. Read references/python-api.md before relying on ordering or strand.

Consensus is a Python binding in a different module:

from gtars.genomic_distributions import consensus

rows = consensus([query, universe])
# rows: [{"chr": ..., "start": ..., "end": ..., "count": ...}, ...]

The [consensus algorithm in the 0.10.0 release](https://github.com/databio/gtars/blob/gtars-v0.10.0/gtars-genomicdist/src/consensus.rs)

counts input sets touching a merged union component, not support at every base.

For example, [0,10) and [5,15) yield [0,15) with count 2, although its

edges have one-set support. Do not describe a count-filtered consensus as

basewise replicate agreement; use a support-segmenting method when that is the

scientific requirement.

Signal-track generation is not exposed as gtars.uniwig in Python 0.10.0;

use the reviewed CLI or Rust API. RegionSet.coverage() is a base-pair set metric,

not a WIG/bigWig generator.

Coverage tracks, overlap counts, and consensus are separate analysis outputs.

Do not feed a smoothed signal into interval consensus or interpret a consensus

count as per-base support.

Tokenizers, fragments, and reference stores

Use only local constructors by default:

from gtars.models import RegionSet
from gtars.tokenizers import Tokenizer

tokenizer = Tokenizer.from_bed("reviewed-universe.bed")
regions = RegionSet("local-query.bed")
tokens = tokenizer.tokenize(regions)
encoding = tokenizer(regions)
ids = encoding["input_ids"]
assert tokenizer.vocab_size == len(tokenizer.get_vocab())

Tokenizer.from_pretrained(name) contacts Hugging Face and writes its cache when

the argument is not an existing local directory; it exposes no revision or cache

argument. Obtain explicit approval, fetch an immutable revision through a reviewed

mechanism, verify checksums, then pass the local snapshot directory. See

references/tokenizers.md.

Python 0.10.0 refget batch imports return ImportReport, not a list; read

`re

… (full content is in the download package)