{"id":"gtars","name":"gtars","summary":"Gtarsは局所ゲノム区間モデルや、Python、Rust、CLI全体で代数、重なりとカウント、コンセンサスとカバレッジ、トークン化、フラグメント処理、refget/BEDbaseの計画に使います。","body":"# Gtars\n\nGtars provides native Rust implementations, Python bindings, and a feature-gated\n`gtars` binary for genomic interval and reference-sequence work. Start with the\nbundled local inspectors; call upstream code only after the data contract,\nprovenance, resource bounds, and side effects are explicit.\n\n## Verified snapshot (2026-07-23)\n\n- Python: [`gtars==0.9.2`](https://pypi.org/project/gtars/), released\n  2026-06-17, `Requires-Python >=3.10`.\n- Rust meta-crate: [`gtars=0.9.0`](https://crates.io/crates/gtars), released\n  2026-06-15. Its default feature set is empty.\n- CLI crate/binary: [`gtars-cli=0.9.0`](https://crates.io/crates/gtars-cli);\n  the installed binary is named `gtars`.\n- Direct refget crate: [`gtars-refget=0.9.1`](https://crates.io/crates/gtars-refget),\n  released 2026-06-17. `gtars=0.9.0` itself pins its component release set, which\n  includes refget 0.9.0.\n- Upstream intentionally versions workspace crates, Python bindings, and CLI\n  independently. Do not assume matching numbers mean matching artifacts.\n- The published docs changelog stops at 0.5.1. API examples here were checked\n  against the 0.9.2 Python stubs/runtime and the `v0.9.0` CLI/Rust source.\n\nThe `license: MIT` field covers this skill. Published `gtars` crates declare MIT,\nwhile the GitHub repository currently displays BSD-2-Clause at the root; verify\nthe exact artifact's license before redistribution.\n\n## Native-code trust gate and exact pins\n\nThe Python wheel contains a PyO3 native extension. Cargo installation compiles a\nnative binary and can run dependency build scripts. Treat either path as code\nexecution:\n\n1. Confirm the official PyPI/crates.io/GitHub owner and immutable version.\n2. Review filenames, platform tags, release provenance, license, and SHA-256.\n   GitHub's v0.9.0 binary release includes per-archive `.sha256` sidecars.\n3. Never run an untrusted prebuilt binary, wheel, source tree, Cargo build script,\n   or archive installer. Use isolation and CPU/RAM/disk/time limits.\n4. Keep a lockfile and artifact hashes with the analysis manifest.\n\nAfter that review, create an isolated Python environment:\n\n```bash\nuv venv --python 3.11 .venv-gtars\nuv pip install --dry-run --python .venv-gtars/bin/python \"gtars==0.9.2\"\nuv pip install --python .venv-gtars/bin/python \"gtars==0.9.2\"\n.venv-gtars/bin/python -c \\\n  \"import gtars; assert gtars.__version__ == '0.9.2'; print(gtars.__version__)\"\n```\n\nFor the reviewed CLI source release:\n\n```bash\ncargo install gtars-cli --version 0.9.0 --locked\ngtars --version\ngtars --help\n```\n\nFor a Rust project, pin the wrapper exactly and enable only required features:\n\n```toml\n[dependencies]\ngtars = { version = \"=0.9.0\", default-features = false, features = [\n  \"core\", \"overlaprs\", \"uniwig\", \"tokenizers\", \"refget\"\n] }\n```\n\nUse `gtars-refget = \"=0.9.1\"` directly only when the newer direct component API is\nrequired and compatibility has been tested. Do not replace these pins with a Git\nbranch or an unreviewed release.\n\n## Genomic data contract\n\nApply this contract before every operation:\n\n1. **Coordinates:** BED intervals are 0-based and half-open: `[start, end)`.\n   Require `0 <= start < end <= contig_length`. Gtars coordinates are `u32`, so\n   reject values above `4,294,967,295`.\n2. **Assembly:** record an assembly accession/version and the SHA-256 of the exact\n   chromosome-sizes or refget sequence-collection metadata. Never infer assembly\n   from filenames or `chr` prefixes.\n3. **Contigs:** compare names exactly. `1` and `chr1`, alternate loci, decoys, and\n   mitochondrial aliases are not interchangeable. Rename or liftover only as a\n   separately reviewed transformation.\n4. **Sorting:** preserve the original file, then sort a copy by chromosome-sizes\n   order and numeric start/end when the operation requires it. Python\n   `RegionSet(path)` currently sorts lexicographically by contig and start while\n   loading; do not rely on original row order afterward.\n5. **Strand:** BED6 uses `+`, `-`, or `.`. `Region.rest` retains trailing BED\n   fields, but a file-backed Python `RegionSet` currently initializes its separate\n   `strands` vector to `*`. Several set operations drop strand. Preserve and\n   validate strand externally when it is scientifically meaningful.\n6. **Duplicates/adjacency:** choose policies explicitly. `reduce()` and consensus\n   merge overlapping **and adjacent** intervals; ordinary half-open overlap does\n   not treat `[0,10)` and `[10,20)` as overlapping.\n\nRun the local validator first:\n\n```bash\npython3 -B scripts/bed_validator.py \\\n  --input data.bed.gz \\\n  --assembly GRCh38.p14 \\\n  --chrom-sizes GRCh38.p14.chrom.sizes \\\n  --require-sorted\n```\n\n## Safe local workflow\n\n1. Inventory local files, checksums, assembly, contig dictionary, coordinate\n   system, strand policy, patient/replicate groups, and intended outputs.\n2. Validate BED/fragments and estimate work. Pilot a small synthetic file.\n3. Choose Python, CLI, or Rust from the documented surface; do not translate API\n   names by guesswork.\n4. Set hard limits for input bytes/records/files, threads/jobs, memory, temporary\n   disk, output size, and wall time.\n5. Run in a dedicated output directory. Refuse collisions unless overwrite was\n   explicitly approved.\n6. Revalidate output sorting, bounds, row counts, checksums, and provenance.\n\n## Current Python core\n\nImports are from submodules, not the `gtars` top level:\n\n```python\nfrom gtars.models import Region, RegionSet\n\nquery = RegionSet.from_regions(\n    [\n        Region(chr=\"chr1\", start=100, end=200, rest=None),\n        Region(chr=\"chr1\", start=300, end=400, rest=None),\n    ],\n    strands=[\"+\", \"-\"],\n)\nuniverse = RegionSet.from_vectors(\n    [\"chr1\", \"chr1\"],\n    [150, 500],\n    [350, 600],\n)\n\ncounts = query.count_overlaps(universe)       # one count per query region\nflags = query.any_overlaps(universe)          # one bool per query region\nindices = query.find_overlaps(universe)       # indices into universe\npieces = query.intersect_all(universe)        # all intersection fragments\nfraction = query.coverage(universe)           # fraction of query bp covered\n```\n\n`RegionSet.sort()` mutates and returns `None`. Set algebra includes `reduce`,\n`setdiff`, `pintersect` (pairs by index), `concat`, `union`, `jaccard`,\n`coverage`, `overlap_coefficient`, `intersect_all`, `closest`, `cluster`, and\n`gaps`. Read `references/python-api.md` before relying on ordering or strand.\n\nConsensus is a Python binding in a different module:\n\n```python\nfrom gtars.genomic_distributions import consensus\n\nrows = consensus([query, universe])\n# rows: [{\"chr\": ..., \"start\": ..., \"end\": ..., \"count\": ...}, ...]\n```\n\nSignal-track generation is **not** exposed as `gtars.uniwig` in Python 0.9.2;\nuse the reviewed CLI or Rust API. `RegionSet.coverage()` is a base-pair set metric,\nnot a WIG/bigWig generator.\n\n## Tokenizers, fragments, and reference stores\n\nUse only local constructors by default:\n\n```python\nfrom gtars.models import RegionSet\nfrom gtars.tokenizers import Tokenizer\n\ntokenizer = Tokenizer.from_bed(\"reviewed-universe.bed\")\nregions = RegionSet(\"local-query.bed\")\ntokens = tokenizer.tokenize(regions)\nencoding = tokenizer(regions)\nids = encoding[\"input_ids\"]\n```\n\n`Tokenizer.from_pretrained(name)` contacts Hugging Face and writes its cache when\nthe argument is not an existing local directory; it exposes no revision or cache\nargument. Obtain explicit approval, fetch an immutable revision through a reviewed\nmechanism, verify checksums, then pass the local snapshot directory. See\n`references/tokenizers.md`.\n\nFor refget, prefer `RefgetStore.in_memory()` or `RefgetStore.open_local(path)`.\n`open_remote(cache_path, remote_url)` contacts a remote service, creates/uses a\nlocal cache, and performs on-demand range reads. See `references/refget.md`.\n\n## Network and cache gate\n\nNo download or cache write is implicit in this skill. Before any network-capable\nupstream call:\n\n- obtain explicit user approval for the exact host, endpoint, data, and cache;\n- allowlist HTTPS hosts and reject unreviewed redirects;\n- record immutable revision/identifier, retrieval time, expected SHA-256 and\n  domain digest, assembly accession, size quota, and provenance;\n- disclose sensitive BED coordinates, barcodes, sample labels, and reference\n  choices that could leave the approved environment;\n- validate downloaded content as untrusted before using it.\n\nImportant side effects:\n\n- `RegionSet(path)` has HTTP support; a nonexistent local string may be treated as\n  a URL. Check that the local path exists before construction.\n- `Tokenizer.from_pretrained` may download `universe.bed.gz` into the Hugging Face\n  cache.\n- `RefgetStore.on_disk` creates/writes a store. `open_remote` loads remote metadata\n  and enables persistence by default.\n- `gtars bbcache` creates cache directories even when constructing the client.\n  Cache/download commands use `BBCLIENT_CACHE` (default `~/.bbcache`) and\n  `BEDBASE_API` (default `https://api.bedbase.org`).\n\n## Sensitive metadata and leakage\n\nGenomic intervals, rare loci, barcodes, sample names, phenotypes, and assembly\nchoices can be identifying. Keep full paths and raw coordinates out of logs;\ndefault bundled reports redact paths and emit only counts/checksums.\n\nFreeze splits by patient/donor first, then keep all technical and biological\nreplicates in the same split. Fit consensus sets, universes, tokenizers, scaling,\nthresholds, and QC rules on training data only. Do not create a universe from all\nsamples and then split: that leaks validation/test locus support. Record excluded\nsamples and replicate aggregation separately.\n\n## Bundled deterministic CLIs\n\nAll six helpers reject URLs, traversal, symlinks, and special files; apply byte,\nrecord, file, coordinate, and worker caps; use no network or gtars import; and\nwrite no output files. Plans contain fixed argv templates and never launch them.\n\n```bash\npython3 -B scripts/bed_validator.py --help\npython3 -B scripts/execution_plan.py --help\npython3 -B scripts/tokenizer_manifest.py --help\npython3 -B scripts/refget_digest_plan.py --help\npython3 -B scripts/coverage_preflight.py --help\npython3 -B scripts/artifact_inspector.py --help\n```\n\nRun synthetic tests without bytecode:\n\n```bash\nPYTHONDONTWRITEBYTECODE=1 python3 -B -m unittest discover \\\n  -s tests/gtars -p 'test_*.py' -v\n```\n\n## Migration traps removed in 1.1\n\nDo not use stale examples containing `gtars.RegionSet`,\n`RegionSet.from_bed`, `TreeTokenizer`, `gtars.igd.build_index`,\n`gtars.uniwig.coverage_from_bed`, `gtars.RefgetStore`, global\n`set_option`/`set_log_level`, `parallel_apply`, or invented exception classes.\nCLI forms such as `uniwig generate`, `igd build`, `scoring score`, and\n`fragsplit cluster-split` are also stale for 0.9.0.\n\nUpstream's published docs and stubs have some drift (for example the older\n`GlobalRefgetStore` tutorial and incomplete 0.9.2 stubs). Prefer installed\nsignature smoke tests plus immutable tagged source when they conflict.\n\n## Bundled references\n\nThese are the only six bundled references; all links are local and present:\n\n- `references/python-api.md` — exact Python 0.9.2 imports and behavior\n- `references/overlap.md` — overlap/count/set algebra and consensus semantics\n- `references/coverage.md` — uniwig, bigWig, coverage, sorting, and resources\n- `references/tokenizers.md` — tokenizer/universe and fragment compatibility\n- `references/refget.md` — digests, stores, BEDbase, network/cache controls\n- `references/cli.md` — CLI 0.9.0 commands, features, and migrations","author":"@K-Dense-AI","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/K-Dense-AI/scientific-agent-skills/tree/main/skills/gtars","license":"MIT","category":"document","lang":"en","tokens":2868,"stars":0,"calls30d":2,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"references/cli.md","size":9887,"sha256":"997e9157a1fff63fd731432e452a2a3d4bce8e3b64b22fd3c4f430d3676f65de"},{"path":"references/coverage.md","size":7721,"sha256":"95256712e04bb5f4be657044081fdb0925494156bba37a6ae9caca4389ea7317"},{"path":"references/overlap.md","size":7450,"sha256":"669af0b0a355fbd7463df990e140bff1535a0f08e2e30199e30b2b3e5bc6cfe4"},{"path":"references/python-api.md","size":9588,"sha256":"f8a0de9e8bcb9b30ef2c69f2e712650c0afe4cf5b9fbf62c81d87a460393b96e"},{"path":"references/refget.md","size":10540,"sha256":"6138a746ce372e4c94658565e78eb93c09d865fb03a6c31bf1df8d6ff84a8e63"},{"path":"references/tokenizers.md","size":8238,"sha256":"7967314a038531f0ac1e5b916cddc2cad4933416ce573511862a29d32baa5429"},{"path":"scripts/artifact_inspector.py","size":10846,"sha256":"ac7d631fac18addee45732e148654e8a84cd439c2a5b834c98834fc9bc70ccfc"},{"path":"scripts/bed_validator.py","size":5432,"sha256":"1ab6f216a7a3047a8b0612990e7485dfe147c96a14d7c54153bde0f7ee47e791"},{"path":"scripts/_common.py","size":14970,"sha256":"9c12a0951f7006ee1ad959a0933e3b5ac8a53de121ca125e96f60d71ec0769f2"},{"path":"scripts/coverage_preflight.py","size":8273,"sha256":"7462afe4b85c4b71cdc23c38f0f098e2e25f5899f2d361bc12437deb6926a417"},{"path":"scripts/execution_plan.py","size":11927,"sha256":"4ef4bd4dbfb6ad15dbcc76d3ca111d5152f2e4c7c4e440fcead13d1e0d9b2496"},{"path":"scripts/__init__.py","size":57,"sha256":"ad3f0f0e13877aa22ac08ee94dca3c1a353a0c43b9a6e516a653698881e6970d"},{"path":"scripts/refget_digest_plan.py","size":10925,"sha256":"c804bfa7796c6b8a39a73928a9dde274df6073ccce4d7c2aab7f57725d3dd299"},{"path":"scripts/tokenizer_manifest.py","size":8558,"sha256":"b756121edd2bc9652edb6c4242a33bdef33de3550183cf6cf8d23733817b896a"}],"requires":{"mcp":[],"tools":["Read Write Edit Bash Glob"]},"safety":{"flags":[{"code":"net.endpoints","kind":"exfiltration","excerpt":"api.bedbase.org, crates.io, docs.bedbase.org, docs.rs, ga4gh.github.io, genome.ucsc.edu","message":"bundled scripts reach 6 external host(s)","severity":"warn"}],"scannedAt":"2026-08-22","hasScripts":true,"networkEndpoints":["api.bedbase.org","crates.io","docs.bedbase.org","docs.rs","ga4gh.github.io","genome.ucsc.edu"]}}