GMAP_BUILD(1)

💖 gmap_build — the manual, section 1 (User Commands) 💖

hi bestie 🫶 you found the gmap_build page, and honestly? iconic of you. this is the User Commands section of the manual, and we're gonna get you fully set up. no cap.

---

✨ NAME ✨

gmap_build — the tool that builds genome databases for GMAP or GSNAP 🧬💅

---

🌸 SYNOPSIS 🌸

gmap_build [options...] -d <genome> [-c <transcriptome> -T <transcript_fasta>] <genome_fasta_files>

---

🦋 DESCRIPTION 🦋

so here's the vibe: gmap_build builds a gmap database for a genome, and that database is what GMAP or GSNAP will use later. it's part of the GMAP package, version 2025-07-31. ⭐

you can name <genome> and <transcriptome> literally whatever you want, bestie — no rules, main character energy, your call. just remember you'll be using those exact same names later when you do your alignments with GMAP or GSNAP, so don't get cute and forget them. 🙈

💡 note: if you're adding a transcriptome to a genome you already built, then there's no need to specify the genome_fasta_files at all. that's the whole trick — it's how you tack transcriptome info onto an existing genome database without redoing everything. slay.

---

👑 OPTIONS 👑

• -D, --genomedir=STRING — where to install it, i.e. the destination directory. defaults to the gmapdb directory that was specified at configure time. 🎀
• -d, --genomedb=STRING — the genome name. this one is required, so like… don't skip it. 💀
• -n, --names=STRING — swap in substitute names for your contigs, handed over in a file. this file can come in two formats:
  1. a file with one column per line, where each line corresponds to a FASTA file, in the order given to gmap_build. the chromosome name for each FASTA file gets replaced with the chromosome name you want from the file. every chromosome in the FASTA must have a corresponding line in the file. this is lowkey perfect if you want to rename chromosomes using some systematic numbering pattern. 🔢
  2. a file with two columns per line, separated by white space. column 1 is the original FASTA chromosome name, column 2 is the chromosome name you want instead.

what format 2 actually means depends on whether --limit-to-names is specified. if it is, the genome build will be limited to just those chromosomes listed in this file. if it isn't, then every chromosome in the FASTA file gets included, but only the ones in this file get re-named — which is a super easy way to change just a few chromosome names. 🧚

this file can be combined with the --sort=names option, and in that case the order of chromosomes is exactly the order given in the file. when you do that, every chromosome has to be listed in the file, and for any chromosome names you don't want changed, column 2 can just be blank (or the same as column 1). heads up though: a blank column 2 is allowed only when you specify --sort=names, because otherwise the program can't tell the difference between a 1-column and a 2-column names file. ⚠️

• -L, --limit-to-names — decides whether to limit the genome build to just the lines listed in the --names file. pair this option with a --names file to limit a genome build to certain chromosomes — either a file that renames chromosomes, or one that lists the same names in both columns for the chromosomes you want. ✨
• -k, --kmer=INT — the k-mer value for the genomic index. allowed: 15 or less. default is 15. 🔥
• -q INT — sampling interval for the genome. allowed: 1-3, default 3.
• -s, --sort=STRING — sort chromosomes using the given method:
  • none — use chromosomes as found in the FASTA file(s) (default)
  • alpha — sort chromosomes alphabetically (chr10 before chr 1)
  • numeric-alpha — chr1, chr1U, chr2, chrM, chrU, chrX, chrY
  • chrom — chr1, chr2, chrM, chrX, chrY, chr1U, chrU
  • names — sort chromosomes based on the file provided to the --names flag
• -g, --gunzip — your files are gzipped, so each one needs to be gunzipped first. 🗜️
• -E, --fasta-pipe=STRING — interpret the argument as a command, instead of as a list of FASTA files. 💫
• -Q, --fastq — the files are in FASTQ format.
• -R, --revcomp — reverse complement all contigs. 🔄
• -w INT — wait (sleep) this many seconds after each step. default 2.
• -o, --circular=STRING — circular chromosomes. give it either a list of chromosomes separated by a comma, or a filename containing circular chromosomes, one per line. if you're using the --names feature, then you should use the substitute name of the chromosome here, not the original name. (NOTE: this behavior is different from previous versions, and starts with version 2020-10-20.) 🌀
• -2, --altscaffold=STRING — file with alt scaffold info, listing alternate scaffolds, one per line, tab-delimited, with these fields: (1) alt_scaf_acc, (2) parent_name, (3) orientation, (4) alt_scaf_start, (5) alt_scaf_stop, (6) parent_start, (7) parent_end. 📋
• -e, --nmessages=INT — maximum number of messages (warnings, contig reports) to report. default 50.
• --sarray=INT — whether to build the suffix array: 0=no (default), 1=yes.

---

🌈 Options for older genome formats 🌈

• -M, --mdflag=STRING — use an MD file from NCBI for mapping contigs to chromosomal coordinates.

---

💜 Options for transcriptome-guided alignment 💜

• -C, --transcriptomedir=STRING — destination directory for installation. defaults to the gmapdb directory specified at configure time.
• -c, --transcriptomedb=STRING — transcriptome name, plus one of these four flags:
• --gtf=FILE — GTF file containing transcripts
• --gff3=FILE — GFF3 file containing transcripts
• -G, --genes=FILE — genes file containing transcripts
• -T, --transcripts=FILE — FASTA file containing transcripts
• -t, --nthreads=INT — number of threads for GMAP alignment of transcripts to genome (default 8). applies if the --transcripts option is given. 🧵

---

other tools of the GMAP suite are located in /usr/lib/gmap 📁

---

and that's the whole page, bestie!! 🎀 go build something gorgeous. this was gmap_build version 2025-07-31+ds-1, from October 2025 — mwah, catch you on the next manpage 💖✨🦋