AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

gtars

Supports 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.

Original source
K-Dense-AI
License
MIT
Pinned revision
5f2bc0341354fd5590aef76a533ada1e1e5b4e62

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read k-dense-ai--gtars at revision 5f2bc0341354fd5590aef76a533ada1e1e5b4e62, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 7

references/cli.md

Command-line interface (gtars-cli==0.10.0)

Source-reviewed from the published 0.10.0 crate (commit 90141b6) on 2026-10-01. Commands below are illustrative templates; this audit did not compile the CLI. The package is gtars-cli; the installed binary is gtars.

Trust, installation, and features

Cargo installation compiles native code and may run transitive build scripts. Review the official crate/source, lock resolution, license, and build environment before:

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

If using a precompiled binary, verify that its version and checksum match the reviewed release before extraction or execution. The bundled artifact_inspector.py hashes/classifies an artifact without extracting or executing it.

Default CLI features are:

scoring uniwig bbcache igd fragsplit overlaprs genomicdist refget

To build a reduced binary:

cargo install gtars-cli --version 0.10.0 --locked \
  --no-default-features --features "overlaprs,genomicdist"

Feature availability controls subcommand availability. There is no 0.10.0 CLI tokenizers feature/subcommand. Do not copy an old --all-features binary's command assumptions into a reduced binary.

Global behavior

gtars --help
gtars --version
gtars <command> --help

Tagged source defines no global --threads, --memory-limit, --buffer-size, --verbose, --quiet, --strict, --continue-on-error, or --log-file options. Concurrency is command-specific.

Before every real command, run the exact installed --help. This reference is pinned to 0.10.0; unversioned web documentation can drift.

overlaprs

gtars overlaprs \
  --query query.bed \
  --universe universe.bed \
  --backend bits

Options:

  • -q/--query PATH (required);
  • -u/--universe PATH (required);
  • -e/--backend bits|ailist (handler default: bits);
  • --streaming is parsed but ignored by the v0.10.0 handler.

Output is BED3 universe-hit coordinates to stdout, one row per overlap. It is not a count table and does not retain query IDs. See overlap.md.

igd

Create from a folder of BED files:

gtars igd create \
  --filelist approved-bed-directory \
  --output index-directory \
  --dbname reference_index

Search with a BED/BED.GZ query:

gtars igd search \
  --database index-directory/reference_index.igd \
  --query query.bed

Current subcommands are create and search, not build, query, or count. The handler accepts a directory, a .txt file of paths, or -/stdin. Directory discovery includes every .bed or .gz file, so use a reviewed list when that would include unrelated gzip files. Create the output directory first. search --database needs the .igd file, not its parent directory. Output is per-database-file overlap counts plus a total, not row-aligned query matches.

uniwig

Batch BigWig:

gtars uniwig \
  --file sorted.bed.gz \
  --filetype bed \
  --chromref assembly.chrom.sizes \
  --smoothsize 5 \
  --stepsize 1 \
  --fileheader output/sample_ \
  --outputtype bw \
  --counttype core \
  --threads 4

BAM QC:

gtars uniwig bamqc \
  --input aligned.bam \
  --output bamqc.tsv \
  --threads 1

BED streaming adds --streaming and supports only WIG/bedGraph output. Read coverage.md for all flags, sorting/bounds, BAM behavior, and resource limits.

consensus

gtars consensus \
  --beds a.bed b.bed c.bed \
  --min-count 2 \
  --output consensus.bed
  • --beds requires at least two paths;
  • --min-count defaults to 1;
  • output defaults to stdout and is BED4 (chr start end count).

Consensus counts input sets overlapping a reduced union component; it is not per-base support segmentation. See overlap.md.

ranges

ranges exposes interval algebra:

gtars ranges reduce      --input BED [--output OUT]
gtars ranges trim        --input BED --chrom-sizes SIZES [--output OUT]
gtars ranges promoters   --input BED [--upstream 2000] [--downstream 200] [--output OUT]
gtars ranges setdiff     -a BED_A -b BED_B [--output OUT]
gtars ranges pintersect  -a BED_A -b BED_B [--output OUT]
gtars ranges concat      -a BED_A -b BED_B [--output OUT]
gtars ranges union       -a BED_A -b BED_B [--output OUT]
gtars ranges jaccard     -a BED_A -b BED_B
gtars ranges shift       --input BED --offset N [--output OUT]
gtars ranges flank       --input BED --width N [--start|--both] [--output OUT]
gtars ranges resize      --input BED --width N [--fix start|end|center] [--output OUT]
gtars ranges narrow      --input BED [--start N] [--end N] [--width N] [--output OUT]
gtars ranges disjoin     --input BED [--output OUT]
gtars ranges gaps        --input BED --chrom-sizes SIZES [--output OUT]
gtars ranges intersect   -a BED_A -b BED_B [--output OUT]

Operations without --output write to stdout. promoters is anchored on region starts in core behavior; do not assume strand-aware TSS handling.

fscoring fragment counts

File-by-peak matrix:

gtars fscoring "fragments/sample01.fragments.tsv.gz" consensus.bed \
  --mode chip \
  --output counts.csv.gz

Arguments are positional:

gtars fscoring <fragments> <consensus> [--mode atac|chip] [--output PATH]
  • fragments is interpreted by FragmentFileGlob; a single explicit local file is safest. Shell globs can expose unintended files, while quoted globs are expanded by the library.
  • default mode is atac;
  • default output is fscoring.csv.gz;
  • the shown chip mode uses fragment-body overlap semantics, one increment per row/peak overlap; it ignores the fifth fragment-support count;
  • do not use the default atac mode for scientific results in this pin. The CLI's locked gtars-scoring 0.5.2 constructs its right-cut query as [fragment.end - 5, fragment.end - 6), an invalid reversed interval; small coordinates can also underflow unsigned arithmetic. This is a source-confirmed correctness issue, not a validated ATAC count implementation. The planner refuses to approve this mode. Use a separately validated cut-site workflow if ATAC insertion counts are required; selecting chip changes the measurement.

Sparse barcode mode:

gtars fscoring sample.fragments.tsv.gz consensus.bed \
  --barcode \
  --output output/sample01

This writes:

output/sample01_matrix.mtx.gz
output/sample01_barcodes.tsv.gz
output/sample01_features.tsv.gz

Barcode mode ignores --mode: it counts whole-fragment overlaps, increments once per row, and ignores the fifth support count. It keeps only barcodes having an overlap. The matrix is cells by peaks, with lexicographically sorted barcodes and 1-based Matrix Market coordinates. Feature labels are synthetic peak_0, peak_1, etc.; retain a separate coordinate table in the constructor's sorted consensus order, and reject duplicate consensus intervals. Do not feed it into a reader assuming the common peaks-by-cells orientation without transposing.

The fragment file must carry valid coordinates and barcodes. Do not expose raw barcodes in logs or reports; cap cells, peaks, nonzeros, memory, and output.

pb pseudobulk splitting

The current command name is pb, not fragsplit:

gtars pb sample.fragments.tsv.gz barcode_to_cluster.tsv \
  --output pseudobulk-output

Positional arguments are fragments then mapping; default output is out/. This writes cluster-specific files. Validate mapping uniqueness, unknown barcodes, safe cluster names, output collisions, file-count bounds, and patient split policy first.

genomicdist

Minimal call:

gtars genomicdist \
  --bed regions.bed \
  --chrom-sizes assembly.chrom.sizes \
  --bins 250 \
  --output distribution.json

Optional inputs/features:

  • --gtf GTF for partitions and derived TSS distances;
  • --tss BED to override GTF-derived TSS;
  • --signal-matrix TSV;
  • --fasta FASTA|FAB for GC content;
  • --dinucl-freq and --dinucl-raw-counts;
  • --ignore-unk-chroms;
  • --promoter-upstream, --promoter-downstream;
  • --compact.

Supplying chromosome sizes makes region-distribution bins comparable across files and enables bounds-related operations. Omitting them derives scale from observed ends and is unsuitable for cross-file comparison.

prep

gtars prep --gtf genes.gtf.gz [--output genes.gda]
gtars prep --signal-matrix matrix.tsv.gz [--output matrix.bin]
gtars prep --fasta reference.fa [--output reference.fab]

prep serializes local inputs into Gtars-specific binary formats. Treat these artifacts as versioned native data: hash inputs/outputs, record 0.10.0, reject untrusted serialized files, and bound expansion/memory.

refget

gtars refget build reference.fa reference-alt.fa.gz \
  --output refget-store \
  --jobs 1

Other options include --file-list/-f, --raw, --force, --collection-alias NAMESPACE:ALIAS (one FASTA only), and --lock-timeout SECONDS (default 1800; 0 waits indefinitely). --jobs 0 means automatic concurrency. Version 0.10.0 also provides:

gtars refget lock-status refget-store
gtars refget export --store refget-store --collection local:reference \
  --names chr1 --output chr1.fa.gz --line-width 80

Export accepts a digest or collection alias; without --collection the store must contain exactly one collection. It loads the selected sequence bytes into RAM and overwrites the output path; bound selection and check output collisions. .gz enables gzip and line width 0 disables wrapping. --force-alias overwrites conflicting aliases; --force-unlock bypasses a writer lock and must never be used to solve normal contention from a live process. There are no digest, verify, or remote-query subcommands. See refget.md.

bbcache

gtars bbcache cache-bed       --identifier VALUE [--cache-folder DIR]
gtars bbcache cache-bedset    --identifier VALUE [--cache-folder DIR]
gtars bbcache seek            --identifier VALUE [--cache-folder DIR]
gtars bbcache inspect-bedfiles                 [--cache-folder DIR]
gtars bbcache inspect-bedsets                  [--cache-folder DIR]
gtars bbcache rm              --identifier VALUE [--cache-folder DIR]

Client construction creates cache directories. Cache/download calls can contact BEDbase or arbitrary URL hosts and write SQLite/cache files. rm deletes local content. The tagged source has a likely ID-only download mismatch described in refget.md; do not guess a workaround.

Threading and resource controls

There is no global thread flag:

  • batch uniwig --threads/-p defaults to 6;
  • uniwig bamqc --threads/-t defaults to 1; values above 1 need a BAM index;
  • refget build --jobs/-j defaults to 0 (auto);
  • other commands expose no documented thread setting.

Set command-specific values explicitly. Also bound input bytes/records/files, glob matches, hit pairs/nonzeros, stdout, memory, temporary disk, cache, and wall time externally.

Safe dry-run planning

python3 -B scripts/execution_plan.py --help
python3 -B scripts/coverage_preflight.py --help

These helpers produce fixed argv templates only. They do not invoke gtars, expand globs, download data, create caches, or write outputs.

Removed stale command forms

Do not use:

gtars igd build/query/count
gtars overlaprs overlap/count/filter/subtract
gtars uniwig generate
gtars scoring score/batch
gtars fragsplit split/cluster-split/filter
gtars refget digest/verify
gtars --threads/--memory-limit/--verbose

Official sources (accessed 2026-10-01)