GMAPL(1)

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

GMAPL(1) — the glow-up edition 💅

okay bestie, buckle UP, because this is gmapl from the User Commands section, and it's a whole entire mood. It's the Large Genome Mapping and Alignment Program. Yes, capital L, capital G, capital M, capital A, capital P, capital L energy. Let's get into it 🧚

✨ NAME ✨

gmapl — Large Genome Mapping and Alignment Program 🗺️

✨ SYNOPSIS ✨

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

Like, you can either hand it your FASTA files directly, or you can cat them and pipe them straight into gmap's little stdin mouth. both are valid, both are iconic 🫶

✨ OPTIONS ✨

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

ngl this is the "you literally cannot skip this part" section. pick -d or -g, no cap.

  • -D, --dir=directory — where your genome directory lives. the default (as specified by --with-gmapdb to the configure program) is /var/cache/gmap
  • -d, --db=STRING — your genome database. and here's a cute trick: if the argument is '?' (with the quotes, bestie, the quotes matter), this command lists all the available databases for you. free window shopping ✨
  • -k, --kmer=INT — the kmer size to use in the genome database (allowed values: 16 or less). if you don't specify it, the program will find the highest available kmer size in the genome database all by itself. self-sufficient king 👑
  • --sampling=INT — the sampling to use in the genome database. if not specified, the program will find the smallest available sampling value in the genome database within the selected k-mer size
  • -g, --gseg=filename — user-supplied genomic segments. heads up: if multiple segments are provided, then every query sequence is aligned against every genomic segment
  • -1, --selfalign — align one sequence against itself in FASTA format via stdin. (useful for getting protein translation of a nucleotide sequence — cute, right?)
  • -2, --pairalign — align two sequences in FASTA format via stdin, first one being genomic and second one being cDNA
  • --cmdline=STRING,STRING — align these two sequences provided on the command line, first one being genomic and second one being cDNA
  • --align-fraction=FLOAT — process only the given fraction of reads, selected at random. and if --align-fraction and --part are given, --align-fraction takes precedence (it's the main character, sorry --part)
  • -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). spreading the workload, we love a delegator 🍓
  • --input-buffer-size=INT — size of input buffer (program reads this many sequences at a time for efficiency) (default 1000)

🔥 Computation options 🔥

this is where the math girlies live. stay with me.

  • -B, --batch=INT — batch mode (default = 2)
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. If mmap not available and allocate not chosen, then will use fileio (very slow). 💀 very slow is a warning, bestie.
  • --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
  • --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. 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. 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 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. respectfully forcing the issue 💅
  • --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 — amount of unaligned sequence that triggers search for the remaining sequence (default 30). enables alignment of chimeric reads, and may help with some non-chimeric reads. to turn off, set to zero
  • --no-chimeras — turns off finding of chimeras. same effect as --chimera-margin=0
  • -t, --nthreads=INT — number of worker threads. go parallel, bestie 🌈
  • -c, --chrsubset=string — limit search to given chromosome
  • --strand=STRING — genome strand to try aligning to (plus, minus, or both 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
  • --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, opening penalty for indel
  • --indel-extend — in dynamic programming, extension penalty for indel. values for --indel-open and --indel-extend should be in [-127,-1]. if value is < -127, then will use -127 instead. if --indel-open and --indel-extend are not specified, values are chosen adaptively, based on the differences between the query and reference
  • --cmetdir=STRING — directory for methylcytosine index files (created using cmetindex) (default is 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 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. non-standard modes requires you to have previously run the cmetindex or atoiindex programs (which also cover the ttoc modes) on the genome. so like, do your homework first 📚
  • -p, --prunelevel — pruning level: 0=no pruning (default), 1=poor seqs, 2=repetitive seqs, 3=poor and repetitive

🎀 Output types 🎀

pick your aesthetic, bestie.

  • -S, --summary — show summary of alignments only
  • -A, --align — show alignments
  • -3, --continuous — show alignment in three continuous lines
  • -4, --continuous-by-exon — show 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 protein sequence (cDNA)
  • -Q, --protein_gen — print protein sequence (genomic)
  • -f, --format=INT — other format for output (also note the -A and -S options and other options listed under Output types):
    • 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 🌸

the finishing touches ✨

  • -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 be 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 treated as a fraction of the score of the best alignment (matches minus penalties for mismatches and indels). otherwise, treated as an integer number to be subtracted from the score of the best alignment. default value is 0.50.

  • -O, --ordered — print output in same order as input (relevant only if there is more than one worker thread)
  • -5, --md5 — print MD5 checksum for each query sequence
  • -o, --chimera-overlap — overlap to show, if any, at chimera breakpoint
  • --failsonly — print only failed alignments, those with no results. sad girl hours 😭
  • --nofails — exclude printing of failed alignments
  • -V, --snpsdir=STRING — directory for SNPs index files (created using snpindex) (default is location of genome index files specified using -D and -d)
  • -v, --use-snps=STRING — use database containing known SNPs (in <STRING>.iit, built previously using snpindex) for tolerance to SNPs
  • --split-output=STRING — the basename for multi-file output, and bestie it's separate for each of nomapping, uniq, mult, (and chimera, if --chimera-margin is selected). So like, one base name, many little files, slay.
  • --failed-input=STRING — alignments that completely failed? Send them to this file in input FASTA or FASTQ format. And if you also passed --split-output, this file gets made in addition to the output in the .nomapping file. Two files, no drama.
  • --append-output — when --split-output or --failedinput is in play, this flag appends to the files that already exist instead of doing the default thing, which is creating brand new ones. Default = fresh files.
  • --output-buffer-size=INT — buffer size for the output thread, measured in queries (default 1000). When the number of results waiting to print goes over this, the worker threads literally just wait until the backlog clears. It's giving traffic jam energy.
  • --translation-code=INT — the genetic code used for translating codons into amino acids and computing CDS. Integer value (default=1) corresponds to an available code at http://www.ncbi.nlm.nih.gov/Taxonomy/Utils/wprintgc.cgi. Go look it up, it's right there.
  • --alt-start-codons — also use the alternate initiation codons shown on that Web site above. By default, without this option, only ATG counts as an initiation codon. Just ATG, periodt.
  • -F, --fulllength — assume a full-length protein, starting with Met. 👑
  • -a, --cdsstart=INT — translate codons starting from the given nucleotide (1-based).
  • -T, --truncate — truncate the alignment around the full-length protein, Met to Stop. And heads up: it implies the -F flag. Implied, not optional.
  • -Y, --tolerant — translates cDNA with corrections for frameshifts. Forgiving queen. 🫶

🎀 Options for GFF3 output 🎀

  • --gff3-add-separators=INT — whether to add 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 literally need this, but ngl it deviates from the GFF3 specification. Values: 0 (no, default), 1 (yes).
  • --gff3-fasta-annotation=INT — whether to pull annotation from the FASTA header into 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 — insert 0M in the CIGAR between adjacent insertions and deletions. Picard requires this, but it can cause errors in other tools. Pick your fighter.
  • --sam-extended-cigar — use extended CIGAR format (using X and = symbols instead of M, to indicate matches and mismatches, respectively. Yes that's how the original reads, bestie, I'm not editing it. 💅
  • --sam-flipped — flip 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. Role reversal, iconic.
  • --force-xs-dir — for RNA-Seq alignments, this 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. > Not meaningful, fr fr. Don't read into it.
  • --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. Cute lowercase energy for the legit ones only.
  • --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. And note: the noprint option does not print the CIGAR string at all if there is an error, so it may break a SAM parser. You've been warned.
  • --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). Math, but make it fashion. 💅

🦋 External map file options 🦋

  • *-M, --mapdir=directory* — map directory.
  • *-m, --map=iitfile* — map file. And if the argument is '?' (with the quotes), this lists the available map files. Free menu, bestie.
  • -e, --mapexons — map each exon separately.
  • -b, --mapboth — report hits from both strands of the genome. Both. Greedy in the best way.
  • -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 the alignment.
  • --nomargin — no left margin in GMAP standard output (with the -A flag).
  • -I, --invertmode=INT — mode for alignments to the 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 the intron (default 3).
  • -l, --wraplength=INT — wrap length for the 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. > Chimeras don't care about your 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. Same deal, same chimeras.

🎀 Help options 🎀

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

Other tools of GMAP suite are located in /usr/lib/gmap. Go explore, they're all in there.

And that's a wrap on GMAPL(1), bestie. This lovely page comes from source/version gmapl 2025-07-31+ds-1, dated October 2025 — go off, documentation 💖

📦 where this page comes from