GMAP(1)

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

💖 NAME 💖

gmap — the Genomic Mapping and Alignment Program. that's it, that's the whole résumé. she maps genomes, she aligns sequences, she eats. 🧬👑

🌸 SYNOPSIS 🌸

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

okay so literally two ways to feed her: hand her the FASTA files directly, OR cat them and pipe them in. both are valid, both are cute. 🫶

✨ OPTIONS ✨

🎀 Input options (must include -d or -g) 🎀

no cap, you have to give her -d or -g. no genome = no alignment = sad girl hours. 😭
  • -D, --dir=directory — the Genome directory. the default (as specified by --with-gmapdb to the configure program) is /var/cache/gmap. that's where she's expecting your stuff to be. 💅
  • -d, --db=STRING — the Genome database. and listen, if the argument is '?' (yes, with the quotes), this command lists the available databases for you. so you can window-shop before committing. 🔥
  • -k, --kmer=INT — the kmer size to use in the genome database (allowed values: 16 or less). if you don't specify it, she'll go find the highest available kmer size in the genome database herself. self-sufficient queen. 👑
  • --sampling=INT — the sampling to use in the genome database. if you don't specify it, the program will find the smallest available sampling value in the genome database within the selected k-mer size. she handles it. 🦋
  • -g, --gseg=filename — user-supplied genomic segments. and if you give her multiple segments, then every query sequence gets aligned against every genomic segment. everybody meets everybody. it's giving networking event. 🌈
  • -1, --selfalign — align one sequence against itself, in FASTA format, via stdin. (super useful for getting the protein translation of a nucleotide sequence, iykyk) 💜
  • -2, --pairalign — align two sequences in FASTA format via stdin, where the first one is genomic and the second one is cDNA. order matters bestie!! 🎀
  • --cmdline=STRING,STRING — align these two sequences, provided right there on the command line. first one is genomic, second one is cDNA. same rule as above. 💖
  • --align-fraction=FLOAT — process only the given fraction of reads, selected at random. and if you pass both --align-fraction and --part, then --align-fraction takes precedence. she picks a winner, no drama. ✨
  • -q, --part=INT/INT — process only the i-th out of every n sequences, e.g. 0/100 or 99/100. super handy for distributing jobs to a computer farm. 🍓
  • --input-buffer-size=INT — the size of the input buffer. (the program reads this many sequences at a time for efficiency.) default is 1000. 🔥

🧚 Computation options 🧚

  • -B, --batch=INT — batch mode (default = 2). here's the menu:
                       Mode     Positions       Genome
                         0      mmap            mmap
                         1      mmap & preload  mmap
               (default) 2      mmap & preload  mmap & preload
                         3      allocate        mmap & preload
                         4      allocate        allocate
                         5      allocate        allocate     (same as 4)
Note: for a single sequence, all data structures use mmap. and if mmap is not available and allocate was not chosen, then she'll use fileio — which is very slow. like, painfully. 😭
  • --use-shared-memory=INT — if 1, then the allocated memory is shared among all processes on this node. if 0 (the default), then each process has its own private allocated memory. sharing is caring, but only if you opt in. 💅
  • --nosplicing — turns off splicing. (useful for aligning genomic sequences onto a genome.) 🦋
  • --max-deletionlength=INT — max length for a deletion (default 30). above this size, a genomic gap will be considered an intron rather than a deletion. and if the genomic gap is less than --max-deletionlength and greater than --min-intronlength, a known splice site or splice site probabilities of 0.80 on both sides will be reported as an intron. 🎀
  • --min-intronlength=INT — min length for one internal intron (default 9). below this size, a genomic gap will be considered a deletion rather than an intron. and if the genomic gap is less than --max-deletionlength and greater than --min-intronlength, a known splice site or splice site probabilities of 0.80 on both sides will be reported as an intron. 💜
  • --max-intronlength-middle=INT — max length for one internal intron (default 500000). 📌 note: for backward compatibility, the -K or --intronlength flag will set both --max-intronlength-middle and --max-intronlength-ends. also see --split-large-introns below. 🌸
  • --max-intronlength-ends=INT — max length for the first or last intron (default 10000). 📌 note: for backward compatibility, the -K or --intronlength flag will set both --max-intronlength-middle and --max-intronlength-ends. ✨
  • --split-large-introns — sometimes GMAP will exceed the value for --max-intronlength-middle, if it finds a good single alignment. however, you can force GMAP to split such alignments by using this flag. she needs a little push sometimes. 💅
  • --end-trimming-score=INT — trim ends if the alignment score is below this value, where a match scores +1 and a mismatch scores -3. the value should be 0 (default) or negative. a negative allows some mismatches at the ends of the alignment. 🔥
  • --trim-end-exons=INT — trim end exons with fewer than the given number of matches (in nt, default 12). 🎀
  • -w, --localsplicedist=INT — max length for known splice sites at ends of sequence (default 2000000). 🦋
  • -L, --totallength=INT — max total intron length (default 2400000). 💜
  • -x, --chimera-margin=INT — the amount of unaligned sequence that triggers a search for the remaining sequence (default 30). this enables alignment of chimeric reads, and may help with some non-chimeric reads too. to turn it off, set it to zero. 🍓
  • --no-chimeras — turns off finding of chimeras. same effect as --chimera-margin=0. ✨
  • -t, --nthreads=INT — number of worker threads. more threads, more power. 🌈
  • -c, --chrsubset=string — limit the search to the given chromosome. 🎀
  • --strand=STRING — the genome strand to try aligning to (plus, minus, or both — that's the default). 💅
  • -z, --direction=STRING — cDNA direction (sense_force, antisense_force, sense_filter, antisense_filter, or auto (default)). 👑
  • --canonical-mode=INT — reward for canonical and semi-canonical introns: 0 = low reward, 1 = high reward (default), 2 = low reward for high-identity sequences and high reward otherwise. ✨
  • --cross-species — use a more sensitive search for canonical splicing, which helps especially for cross-species alignments and other difficult cases. for when your sequences are from two different worlds. 🌍💖
  • --allow-close-indels=INT — allow an insertion and deletion close to each other (0 = no, 1 = yes (default), 2 = only for high-quality alignments). 🦋
  • --microexon-spliceprob=FLOAT — allow microexons only if one of the splice site probabilities is greater than this value (default 0.95). 🎀
  • --indel-open — in dynamic programming, the opening penalty for indel. 💜
  • --indel-extend — in dynamic programming, the extension penalty for indel. values for --indel-open and --indel-extend should be in [-127,-1]. if a value is < -127, then it will use -127 instead. and if --indel-open and --indel-extend are not specified, the values are chosen adaptively, based on the differences between the query and reference. she's adaptive like that. ✨
  • --cmetdir=STRING — directory for methylcytosine index files (created using cmetindex). (default is the location of genome index files specified using -D, -V, and -d.) 🌸
  • --atoidir=STRING — directory for A-to-I RNA editing index files (created using atoiindex). (default is the location of genome index files specified using -D, -V, and -d.) 🦋
  • --mode=STRING — alignment mode: standard (default), cmet-stranded, cmet-nonstranded, atoi-stranded, atoi-nonstranded, ttoc-stranded, or ttoc-nonstranded. ⚠️ the non-standard modes require you to have previously run the cmetindex or atoiindex programs (which also cover the ttoc modes) on the genome. no skipping steps bestie!! 😭
  • -p, --prunelevel — pruning level: 0 = no pruning (default), 1 = poor seqs, 2 = repetitive seqs, 3 = poor and repetitive. 💅

👑 Output types 👑

  • -S, --summary — show a summary of alignments only. 🎀
  • -A, --align — show alignments. ✨
  • -3, --continuous — show the alignment in three continuous lines. 💖
  • -4, --continuous-by-exon — show the alignment in three lines per exon. 🦋
  • -E, --exons=STRING — print exons ("cdna" or "genomic"). will also print introns with "cdna+introns" or "genomic+introns". 🌸
  • -P, --protein_dna — print the protein sequence (cDNA). 🍓
  • -Q, --protein_gen — print the protein sequence (genomic). 💜
  • -f, --format=INT — another format for output (also peep the -A and -S options and the other options listed under Output types). the lineup is:
    • mask_introns
    • mask_utr_introns
    • psl (or 1) = PSL (BLAT) format
    • gff3_gene (or 2) = GFF3 gene format
    • gff3_match_cdna (or 3) = GFF3 cDNA_match format
    • gff3_match_est (or 4) = GFF3 EST_match format
    • splicesites (or 6) = splicesites output (for GSNAP splicing file)
    • introns = introns output (for GSNAP splicing file)
    • map_exons (or 7) = IIT FASTA exon map format
    • map_ranges (or 8) = IIT FASTA range map format
    • coords (or 9) = coords in table format
    • sampe = SAM format (setting paired_read bit in flag)
    • samse = SAM format (without setting paired_read bit)
    • bedpe = indels and gaps in BEDPE format

💅 Output options 💅

  • -n, --npaths=INT — maximum number of paths to show (default 5). 📌 if set to 1, GMAP will not report chimeric alignments, since those imply two paths. if you want a single alignment plus chimeric alignments, then set this to 0. 🎀
  • --suboptimal-score=FLOAT — report only paths whose score is within this value of the best path. if specified between 0.0 and 1.0, then it's treated as a fraction of the score of the best alignment (matches minus penalties for mismatches and indels). otherwise, it's treated as an integer number to be subtracted from the score of the best alignment. the default value is 0.50. ✨
  • -O, --ordered — print output in the same order as the input. (only relevant if there's more than one worker thread, so like... multitaskers only.) 🦋
  • -5, --md5 — print the MD5 checksum for each query sequence. 🔥
  • -o, --chimera-overlap — the overlap to show, if any, at the chimera breakpoint. 💜
  • --failsonly — print only the failed alignments, meaning those with no results. 😭
  • --nofails — exclude printing of failed alignments. 🙈
  • -V, --snpsdir=STRING — directory for SNPs index files (created using snpindex). (default is the location of genome index files specified using -D and -d.) 🌸
  • -v, --use-snps=STRING — use a database containing known SNPs (in <STRING>.iit, built previously using snpindex) for tolerance to SNPs. 🧬
  • --split-output=STRING — basename for multiple-file output, separately for nomapping, uniq, mult, (and chimera, if --chimera-margin is selected). 👑

okay that's part 1 and she is not done yet, there's more coming bestie, don't go anywhere 💖✨

  • --failed-input=STRING — sends every completely failed alignment out to the file you name, as input FASTA or FASTQ format. And if you also passed --split-output? Then this file gets generated on top of whatever lands in the .nomapping file. bestie gets both 💅
  • --append-output — when --split-output or --failedinput is in play, this flag makes the output get appended to files that already exist. Without it, default behaviour is to make brand-new files every time.
  • --output-buffer-size=INT — buffer size, counted in queries, for the output thread (default 1000). Once the pile of results waiting to be printed goes over this size, the worker threads just… wait 🫶 until the backlog clears.
  • --translation-code=INT — the genetic code used to translate codons into amino acids and to compute CDS. Integer value (default 1) lines up with one of the codes listed at http://www.ncbi.nlm.nih.gov/Taxonomy/Utils/wprintgc.cgi.
  • --alt-start-codons — also uses those alternate initiation codons shown at that same website. By default, with this option off, only ATG counts as an initiation codon. no ATG no start, periodt.
  • -F, --fulllength — assumes a full-length protein, starting with Met.
  • -a, --cdsstart=INT — translates codons starting from the given nucleotide (1-based).
  • -T, --truncate — truncates the alignment around the full-length protein, Met to Stop. Implies -F.
  • -Y, --tolerant — translates cDNA with corrections for frameshifts. she's forgiving like that 💖

✨ Options for GFF3 output ✨

  • --gff3-add-separators=INT — whether to drop a ### separator after each query sequence. Values: 0 (no), 1 (yes, default).
  • --gff3-swap-phase=INT — whether to swap phase (0 => 0, 1 => 2, 2 => 1) in gff3_gene format. Some analysis programs need this, but it deviates from the GFF3 specification. Values: 0 (no, default), 1 (yes).
  • --gff3-fasta-annotation=INT — whether to include annotation from the FASTA header in the GFF3 output. Values: 0 (default): do not include.

1: wrap all annotation as Annot="<header>"

2: include key=value pairs, replacing brackets with quotation marks, and replacing spaces between key=value pairs with semicolons.

  • --gff3-cds=STRING — whether to use cDNA or genomic translation for the CDS coordinates. Values: cdna (default), genomic.

🌸 Options for SAM output 🌸

  • --no-sam-headers — do not print headers that begin with @.
  • --sam-use-0M — inserts 0M in the CIGAR between adjacent insertions and deletions. Picard requires it, but it can cause errors in other tools. pick your fighter 😭
  • --sam-extended-cigar — use the extended CIGAR format (using X and = symbols instead of M, to indicate matches and mismatches, respectively).
  • --sam-flipped — flips the query and genomic positions in the SAM output. Potentially useful with the -g flag when short reads are picked as query sequences and longer reads are picked as genomic sequences.
  • --force-xs-dir — for RNA-Seq alignments, disallows XS:A:? when the sense direction is unclear, and replaces that value arbitrarily with XS:A:+. May be useful for some programs, like Cufflinks, that can't handle XS:A:?. However — if you use this flag, the reported XS:A:+ in those cases will not be meaningful. 🫠
  • --md-lowercase-snp — in the MD string, when known SNPs are given by the -v flag, prints difference nucleotides as lower-case when they differ from the reference but match a known alternate allele.
  • --action-if-cigar-error — the action to take if there's a disagreement between CIGAR length and sequence length. Allowed values: ignore, warning (default), noprint, abort. Heads up: the noprint option doesn't print the CIGAR string at all if there's an error, so it may break a SAM parser 💀
  • --read-group-id=STRING — value to put into the read-group id (RG-ID) field.
  • --read-group-name=STRING — value to put into the read-group name (RG-SM) field.
  • --read-group-library=STRING — value to put into the read-group library (RG-LB) field.
  • --read-group-platform=STRING — value to put into the read-group library (RG-PL) field.

🎀 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 specify the print shift with this flag:

  • -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).

🦋 External map file options 🦋

  • -M, --mapdir=directory — map directory.
  • -m, --map=iitfile — map file. If the argument is '?' (with the quotes), this lists available map files.
  • -e, --mapexons — map each exon separately.
  • -b, --mapboth — report hits from both strands of genome.
  • -u, --flanking=INT — show flanking hits (default 0).
  • --print-comment — show the comment line for each hit.

💜 Alignment output options 💜

  • --nolengths — no intron lengths in alignment.
  • --nomargin — no left margin in GMAP standard output (with the -A flag).
  • -I, --invertmode=INT — mode for alignments to genomic (-) strand:

0 = don't invert the cDNA (default)

1 = invert cDNA and print genomic (-) strand

2 = invert cDNA and print genomic (+) strand

  • -i, --introngap=INT — nucleotides to show on each end of intron (default 3).
  • -l, --wraplength=INT — wrap length for alignment (default 50).

🌈 Filtering output options 🌈

  • --min-trimmed-coverage=FLOAT — do not print alignments with trimmed coverage less than this value (default 0.0, which means no filtering). Note that chimeric alignments will be output regardless of this filter.
  • --min-identity=FLOAT — do not print alignments with identity less than this value (default 0.0, which means no filtering). Note that chimeric alignments will be output regardless of this filter.

👑 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 💖 this one's from gmap 2025-07-31+ds-1, dated October 2025, and it's the GMAP(1) manual — go read your alignments, you absolute icon 🫶✨

📦 where this page comes from