GSNAPL(1)

📦
version 2025-07-31 · 3 versions
, in ubuntu resolute, ubuntu stonking

💖 GSNAPL(1) 💖

okay so bestie, welcome to the manual page for gsnapl — the Large Genome Short-read Nucleotide Alignment Program. no cap, this is the whole vibe. let's get into it.

✨ NAME ✨

gsnapl — Large Genome Short-read Nucleotide Alignment Program. that's it, that's the name. iconic.

✨ SYNOPSIS ✨

the way you run this? literally:

gsnap [OPTIONS...] <FASTA file>, or cat <FASTA file> | gmap [OPTIONS...]

periodt. that's the whole synopsis, bestie. 💅

✨ OPTIONS ✨

💅 Input options (must include -d)

okay so you must include -d here. like, it's not optional. no cap.

  • -D, --dir=directory — this is your genome directory. default (as specified by --with-gmapdb to the configure program) is /var/cache/gmap. so if you don't say anything, that's where it looks. 💖
  • -d, --db=STRING — your genome database. you literally cannot skip this one. must include. periodt.
  • --two-pass — two-pass mode, bestie. the sequences get processed first to identify splice sites and introns, and then aligned using this splicing info. it's giving extra careful. ✨
  • --use-localdb=INT — whether to use the local suffix arrays. these help with finding extensions to the ends of alignments when there's splicing or indels. 0=no, 1=yes if available (default). so default is yes if it can. 🦋

🌸 Transcriptome-guided options (optional)

these are optional, bestie. but if you have a transcriptome, they're kinda slay.

  • -C, --transcriptdir=directory — transcriptome directory. default is the value for --dir above. so it just follows that. 💅
  • -c, --transcriptdb=STRING — transcriptome database. give it a string. 🎀
  • --transcriptome-mode=STRING — okay so options are: assist, only, annotate (default). let me break it down:
    • assist means try transcriptome alignment first, but then use genomic alignment if nothing is found.
    • only means try transcriptome alignment only. no genomic fallback. periodt.
    • annotate means try only genomic alignment, and use the transcriptome only for annotation. this is the fastest option. in the other two options, annotation is also performed. so yeah, annotate is the speed demon. 🔥

🧬 Computation options

okay so these are the computation vibes. get ready.

  • -k, --kmer=INT — kmer size to use in genome database. allowed values: 16 or less. if not specified, the program will find the highest available kmer size in the genome database. so it's like, "i got you, bestie." 💜
  • --sampling=INT — sampling to use in genome database. if not specified, the program will find the smallest available sampling value in the genome database within selected k-mer size. it's lowkey doing the most for you. ✨
  • --align-fraction=FLOAT — process only the given fraction of reads, selected at random. if --align-fraction and --part are given, --align-fraction takes precedence. so it's the main character here. 👑
  • -q, --part=INT/INT — process only the i-th out of every n sequences. e.g., 0/100 or 99/100. useful for distributing jobs to a computer farm. so if you're running a farm, this is your bestie. 🚜
  • --input-buffer-size=INT — size of input buffer (program reads this many sequences at a time for efficiency). default 10000. so it's chunky but efficient. 💅
  • --barcode-length=INT — amount of barcode to remove from start of every read before alignment. default 0. so if you have barcodes, set this. 🎀
  • --endtrim-length=INT — amount of trim to remove from the end of every read before alignment. default 0. trim the ends, bestie. ✂️
  • --orientation=STRING — orientation of paired-end reads. allowed values: FR (fwd-rev, or typical Illumina; default), RF (rev-fwd, for circularized inserts), or FF (fwd-fwd, same strand), or 10X (single-cell where read 1 has barcode information; read 2 is rev). so many orientations, so little time. 🌈
  • --10x-whitelist=FILE — whitelist of 10X Genomics GEM bead barcodes, needed to perform correction of cellular barcodes. this file can be obtained at cellranger-x.y.z/lib/python/cellranger/barcodes (for Cell Ranger version >= 4) or cellranger-x.y.z/lib/cellranger-cs/x.y.z/lib/python/cellranger/barcodes (<= 3). so yeah, go grab that file. 🧬
  • --10x-well-position=INT — position of well information in the accession, when separated by colons. if set to 0, then no well information will be printed in the CB field (default: 4). so default is 4, but you can turn it off. 💅
  • --fastq-id-start=INT — starting position of identifier in FASTQ header, space-delimited (>= 1). so it's 1-indexed, bestie. no zero here. 🙈
  • --fastq-id-end=INT — ending position of identifier in FASTQ header, space-delimited (>= 1). same vibe. 💖

Examples, bestie:

@HWUSI-EAS100R:6:73:941:1973#0/1
       start=1, end=1 (default) => identifier is
       HWUSI-EAS100R:6:73:941:1973#0

@SRR001666.1 071112_SLXA-EAS1_s_7:5:1:817:345 length=36
       start=1, end=1  => identifier is SRR001666.1 start=2, end=2  =>
       identifier is 071112_SLXA-EAS1_s_7:5:1:817:345 start=1, end=2  =>
       identifier is SRR001666.1 071112_SLXA-EAS1_s_7:5:1:817:345

so you can see how the start and end positions pick out parts of the header. it's giving precise. ✨

  • --force-single-end — when multiple FASTQ files are provided on the command line, GSNAP assumes they are matching paired-end files. this flag treats each file as single-end. so if you're like "no, they're single", use this. 🦋
  • --filter-chastity=STRING — skips reads marked by the Illumina chastity program. expecting a string after the accession having a 'Y' after the first colon, like this:
@accession 1:Y:0:CTTGTA

where the 'Y' signifies filtering by chastity. values: off (default), either, both. for 'either', a 'Y' on either end of a paired-end read will be filtered. for 'both', a 'Y' is required on both ends of a paired-end read (or on the only end of a single-end read). so it's like a little filter, bestie. 💅

  • --allow-pe-name-mismatch — allows accession names of reads to mismatch in paired-end files. so if they don't match, it's fine. no cap. 🎀
  • --interleaved — input is in interleaved format (one read per line, tab-delimited. yes, the parenthesis is not closed in the original. we keep it exactly. so it's giving unclosed parenthesis. iconic. 💀
  • --gunzip — uncompress gzipped input files. so if you have .gz, this does the thing. 🔥
  • --bunzip2 — uncompress bzip2-compressed input files. same but for bzip2. 💜

🧬 Computation options

okay so there's another computation options section. yes, bestie, the original has it twice. we keep it. periodt.

  • -B, --batch=INT — batch mode (default = 5). here's the table of modes:
       0      allocate      mmap            mmap            allocate
              mmap                  mmap

       1      allocate      mmap & preload  mmap            allocate
              mmap & preload        mmap

       2      allocate      mmap & preload  mmap & preload  allocate
              mmap & preload        mmap

       3      allocate      allocate        mmap & preload  allocate
              allocate              mmap

       4      allocate      allocate        allocate        allocate
              allocate              mmap

       (default)
              5   allocate      allocate        allocate        allocate
              allocate              allocate
Note: For a single sequence, all data structures use mmap. A batch level of 5 means the same as 4, and is kept only for backward compatibility.

so yeah, 5 is basically 4, but for the OGs. 💅

  • --use-shared-memory=INT — if 1, then allocated memory is shared among all processes on this node. if 0 (default), then each process has private allocated memory. so you can share the love, or not. 🫶
  • --preload-shared-memory — load files indicated by --batch mode into shared memory for use by other GMAP/GSNAP processes on this node, and then exit. ignore any input files. so it's a one-and-done vibe. ✨
  • --unload-shared-memory — unload files indicated by --batch mode into shared memory, or allow them to be unloaded when existing GMAP/GSNAP processes on this node are finished with them. ignore any input files. so it's the cleanup crew. 🧹
  • -m, --max-mismatches=FLOAT — maximum number of mismatches allowed. if not specified, then GSNAP tries to find the best possible match in the genome. if specified between 0.0 and 1.0, then treated as a fraction of each read length. otherwise, treated as an integral number of mismatches (including indel and splicing penalties). default is 0.3. so default is 0.3, which is a fraction. slay. 🔥
  • --query-unk-mismatch=INT — whether to count unknown (N) characters in the query as a mismatch (0=no (default), 1=yes). so default is no. 💅
  • --genome-unk-mismatch=INT — whether to count unknown (N) characters in the genome as a mismatch (0=no, 1=yes). if --use-mask is specified, default is no, otherwise yes. so it depends on the mask. 🎭
  • --maxsearch=INT — maximum number of alignments to find (default 1000). should be larger than --npaths, which is the number to report. keeping this number large will allow for random selection among multiple alignments. reducing this number can speed up the program. so if you want speed, lower it. but you might lose the random selection vibe. 🌈
  • --indel-endlength=INT — minimum length at end required for indel alignments (default 4). so indels need a little length at the end. 💜
  • --max-insertions=INT — maximum number of insertions allowed (default 6). so up to 6. 🍓
  • --max-deletions=INT — maximum number of deletions allowed (default 9). so up to 9. 💀
  • -M, --suboptimal-levels=INT — report suboptimal hits beyond best hit (default 0). all hits with best score plus suboptimal-levels are reported. > Note: Not currently implemented. so it's like, a vibe, but not yet real. 🙈
  • -a, --adapter-strip=STRING — method for removing adapters from reads. currently allowed values: off, paired. default is "off". to turn on, specify "paired", which removes adapters from paired-end reads if they appear to be present. so it's like, "are you there, adapter?" and then it strips. 💅
  • -e, --use-mask=STRING — use genome containing masks (e.g. for non-exons) for scoring preference. so it's like a preference thing. 🎀
  • -V, --snpsdir=STRING — directory for SNPs index files (created using snpindex). default is location of genome index files specified using -D and -d. so if you don't specify, it follows those. 🧬
  • -v, --use-snps=STRING — use database containing known SNPs (in <STRING>.iit, built previously using snpindex) for tolerance to SNPs. so it's like, "i tolerate SNPs." 💖
  • --cmetdir=STRING — directory for methylcytosine index files (created using cmetindex). default is location of genome index files specified using -D, -V, and -d. so it follows those. 🧪
  • --atoidir=STRING — directory for A-to-I RNA editing index files (created using atoiindex). default is location of genome index files specified using -D, -V, and -d. so same vibe. ✨
  • --mode=STRING — alignment mode: standard (default), cmet-stranded, cmet-nonstranded, atoi-stranded, atoi-nonstranded, ttoc-stranded, or ttoc-nonstranded. non-standard modes requires you to have previously run the cmetindex or atoiindex programs (which also cover the ttoc modes) on the genome. so you gotta do the prep work first, bestie. 💅
  • -t, --nthreads=INT — number of worker threads. so you can parallelize. slay. 🔥

🧬 Splicing options for DNA-Seq

  • --find-dna-chimeras=INT — look for distant splicing involving poor splice sites (0=no, 1=yes). if not specified, then default is to be on unless only known splicing is desired (--use-splicing is specified and --novelsplicing is off). so it's like, on by default unless you're being strict. 🧬

🧬 Splicing options for RNA-Seq

  • -N, --novelsplicing=INT — look for novel splicing (0=no (default), 1=yes). so default is no. but you can turn it on. ✨
  • --splicingdir=STRING — directory for splicing involving known sites or known introns, as specified by the -s or --use-splicing flag. default is directory computed from -D and -d flags. > Note: can just give full pathname to the -s flag instead. so you have options. 💅
  • -s, --use-splicing=STRING — look for splicing involving known sites or known introns (in <STRING>.iit), at short or long distances. see README instructions for the distinction between known sites and known introns. so yeah, read the README for the tea. 📖
  • --splices-noeval — bestie, this one says do not go evaluating splices for probability or intron length, okay? Just trust the sequence alignment and nothing else. no vibes, only alignments 💅
  • --splices-dump=FILE — spills all the splice junction tea into FILE, in the exact same format as STAR plus MaxEnt probabilities for the two intron positions. ⚠️ heads up though: in this dump file, the annotation column is reserved strictly for known introns — novel introns that passed some criterion from a first pass do not get in there, periodt.
  • --splices-exclude-known — in the file you made with --splices-dump, exclude all known introns. bye known introns 👋
  • -w, --localsplicedist=INT — the definition of a local novel splicing event (default 200000). it's giving "how far is too far" 🌸
  • --merge-distant-samechr — report distant splices on the same chromosome as a single splice, if possible. you get a single SAM line instead of two SAM lines — which is also what happens for translocations, inversions, and scramble events. iconic behavior honestly 🔥

💖 Options for paired-end reads 💖

  • --pairmax-dna=INT — max total genomic length for DNA-Seq paired reads, or other reads without splicing (default 2000). used if -N or -s is not specified. this value is also used for circular chromosomes when splicing in linear chromosomes is allowed 🧬
  • --pairmax-rna=INT — max total genomic length for RNA-Seq paired reads, or other reads that could have a splice (default 200000). used if -N or -s is specified. should probably match the value for -w, --localsplicedist — like, match them, bestie 🫶
  • --resolve-inner=INT — whether to resolve soft-clipping on the insides of paired-end reads (default 1)
  • --pairexpect=INT — expected paired-end length, used for resolving soft-clipping on the insides of paired-end reads, and for pairing DNA-seq reads (default 200)
  • --pairdev=INT — allowable deviation from expected paired-end length, used for resolving soft-clipping on the insides of paired-end reads (default 100).
  • --pass1-min-support=INT — threshold read support for learning an intron during pass 1 of --two-pass mode (default 20)

✨ Options for quality scores ✨

  • --quality-protocol=STRING — protocol for input quality scores. allowed values:
    • illumina (ASCII 64-126) (equivalent to -J 64 -j -31)
    • sanger (ASCII 33-126) (equivalent to -J 33 -j 0)

Default is sanger (no quality print shift). SAM output files should have quality scores in sanger protocol. 🌈

Or you can customize this behavior with these flags:

  • -J, --quality-zero-score=INT — FASTQ quality scores are zero at this ASCII value (default is 33 for sanger protocol; for Illumina, select 64)
  • -j, --quality-print-shift=INT — shift FASTQ quality scores by this amount in output (default is 0 for sanger protocol; to change Illumina input to Sanger output, select -31)

🎀 Output options 🎀

  • -n, --npaths=INT — maximum number of paths to print (default 100).
  • -Q, --quiet-if-excessive — if more than the maximum number of paths are found, then nothing is printed. silence, but make it a feature 💀
  • -O, --ordered — print output in the same order as input (relevant only if there is more than one worker thread)
  • --show-refdiff — for GSNAP output in SNP-tolerant alignment, shows all differences relative to the reference genome as lower case (otherwise, it shows all differences relative to both the reference and alternate genome)
  • --clip-overlap — for paired-end reads whose alignments overlap, clip the overlapping region. ✂️
  • --merge-overlap — for paired-end reads whose alignments overlap, merge the two ends into a single end (beta implementation — so like, be nice to it, it's trying 🙈)
  • --print-snps — print detailed information about SNPs in reads (works only if -v also selected) (not fully implemented yet — baby steps, bestie)
  • --failsonly — print only failed alignments, those with no results 😭
  • --nofails — exclude printing of failed alignments
  • --only-concordant — print only concordant alignments (concordant_uniq, concordant_mult, concordant_circular)
  • --omit-concordant-uniq — do not print any concordant_uniq alignments
  • --omit-concordant-mult — do not print any concordant_mult alignments
  • --omit-softclipped — do not allow any alignments with soft clips
  • --only-tr-consistent — print only alignments with consistent transcripts (XX field present, identical if paired-end)
  • -A, --format=STRING — another format type, other than default. currently implemented: sam, m8 (BLAST tabular format)
  • --split-output=STRING — basename for multiple-file output, separately for nomapping, halfmapping_uniq, halfmapping_mult, unpaired_uniq, unpaired_mult, paired_uniq, paired_mult, concordant_uniq, and concordant_mult results. so many files. so much organization. slay 🗂️
  • -o, --output-file=STRING — file name for a single stream of output results.
  • --failed-input=STRING — print completely failed alignments as input FASTA or FASTQ format, to the given file, appending .1 or .2, for paired-end data. if the --split-output flag is also given, this file is generated in addition to the output in the .nomapping file.
  • --append-output — when --split-output or --failed-input is given, this flag will append output to the existing files. otherwise, the default is to create new files.
  • --order-among-best=STRING — among alignments tied with the best score, order those alignments in this order. allowed values: genomic, random (default)
  • --output-buffer-size=INT — buffer size, in queries, for the output thread (default 1000). when the number of results to be printed exceeds this size, worker threads wait until the backlog is cleared. like a queue at the club fr fr 🫶

👑 Options for SAM output 👑

  • --no-sam-headers — do not print headers beginning with '@'
  • --add-paired-nomappers — add nomapper lines as needed to make all paired-end results alternate between first end and second end
  • --paired-flag-means-concordant=INT — whether the paired bit in the SAM flags means concordant only (1) or paired plus concordant (0, default)
  • --sam-headers-batch=INT — print headers only for this batch, as specified by -q
  • --sam-hardclip-use-S — use S instead of H for hardclips
  • --sam-use-0M=INT — if 1 (default), then insert 0M in CIGAR between adjacent indels and introns. If 0, do not allow 0M. Picard disallows 0M, but other tools may require it
  • --sam-extended-cigar — use extended CIGAR format (using X and = symbols instead of M, to indicate matches and mismatches, respectively)
  • --sam-multiple-primaries — allows multiple alignments to be marked as primary if they have equally good mapping scores
  • --sam-sparse-secondaries — for secondary alignments (in multiple mappings), uses '*' for SEQ and QUAL fields, to give smaller file sizes. However, the output will give warnings in Picard to give warnings and may not work with downstream tools. ⚠️ smaller files, bigger problems, no cap
  • --force-xs-dir — for RNA-Seq alignments, disallows XS:A:? when the sense direction is unclear, and replaces this value arbitrarily with XS:A:+. may be useful for some programs, such as Cufflinks, that cannot handle XS:A:?. However, if you use this flag, the reported value of XS:A:+ in these cases will not be meaningful. 🚨 read that twice, bestie
  • --md-report-snps — in MD string, when known SNPs are given by the -v flag, prints difference nucleotides when they differ from reference but match a known alternate allele
  • --no-soft-clips — does not allow soft clips at ends. mismatches will be counted over the entire query
  • --extend-soft-clips — extends alignments through soft clipped regions. CIGAR string and coordinates will be revised, but mismatches and the MD string will reflect the clipped CIGAR
  • --action-if-cigar-error — action to take if there is a disagreement between CIGAR length and sequence length. allowed values: ignore, warning (default), noprint, abort. note that the noprint option does not print the CIGAR string at all if there is an error, so it may break a SAM parser 💀
  • --read-group-id=STRING — value to put into read-group id (RG-ID) field
  • --read-group-name=STRING — value to put into read-group name (RG-SM) field
  • --read-group-library=STRING — value to put into read-group library (RG-LB) field
  • --read-group-platform=STRING — value to put into read-group library (RG-PL) field

🌸 Help options 🌸

  • --check — check compiler assumptions
  • --version — show version
  • --help — show this help message

Other tools of the GMAP suite are located in /usr/lib/gmap 🦋

and that's the whole page, bestie — you ate 💅 this was gsnapl version 2025-07-31+ds-1, from October 2025, and honestly? iconic. go align something gorgeous 🫶✨

📦 where this page comes from