hmmbuild(1)

📦
version 3.4 · 3 versions
, in debian trixie, nixos 26.05, nixpkgs unstable, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ hmmbuild ✨ — the HMMER Manual, bestie edition 💖

okay so you opened the HMMER manual, you found hmmbuild, and now you're here. welcome. this is the whole page, nothing skipped, just with the vibes turned all the way up 🫶

🌸 NAME 🌸

hmmbuild — construct profiles from multiple sequence alignments

🦋 SYNOPSIS 🦋

hmmbuild [options] hmmfile msafile

💅 DESCRIPTION 💅

okay so the whole gig is this: for each multiple sequence alignment in msafile, hmmbuild builds a profile HMM and saves it to a new file, hmmfile. that's it. that's the job. iconic honestly 👑

msafile can be - (a dash, yes literally just a dash) — and that means it reads the input from stdin instead of from an actual file. slay, piping.

msafile? no problem. but hmmfile can not be - (stdout). nope. not happening. because sending the HMM file to stdout would beef with the other text output the program is already printing there. two things can't share the aux, bestie 😭

🌈 OPTIONS 🌈

  • -h — help! prints a brief reminder of command line usage plus every available option. the little "wait what were the flags again" button.
  • -n <s> — name the new profile <s>. the default is to use the name of the alignment (if one is present in the msafile, or, failing that, the name of the hmmfile). > heads up: if msafile contains more than one alignment, -n doesn't work, and every alignment must have a name annotated in the msafile (as in Stockholm #=GF ID annotation). so like, one name for many alignments? no ma'am.
  • -o <f> — send the summary output to file <f> instead of to stdout. redirect that gossip.
  • -O <f> — after each model is constructed, resave annotated, possibly modified source alignments to a file <f> in Stockholm format. the alignments get annotated with a reference annotation line indicating which columns were assigned as consensus, and the sequences get annotated with what relative sequence weights were assigned. > some residues of the alignment may have been shifted to accommodate restrictions of the Plan7 profile architecture, which disallows transitions between insert and delete states. so yeah, positions can move. that's on purpose. not a bug 💀

🧬 OPTIONS FOR SPECIFYING THE ALPHABET 🧬

  • --amino — assert that the sequences in msafile are protein, bypassing alphabet autodetection. you're telling it, not asking it.
  • --dna — assert that the sequences in msafile are DNA, bypassing alphabet autodetection.
  • --rna — assert that the sequences in msafile are RNA, bypassing alphabet autodetection.

🎀 OPTIONS CONTROLLING PROFILE CONSTRUCTION 🎀

these options control how consensus columns are defined in an alignment. this is the "which columns are even real" conversation.

  • --fast — define consensus columns as those that have a fraction >= symfrac of residues as opposed to gaps. (see below for the --symfrac option.) this is the default. ✨
  • --hand — define consensus columns in the next profile using reference annotation to the multiple alignment. this lets you define any consensus columns you like. you're the boss, you're the main character, you decide.
  • --symfrac <x> — define the residue fraction threshold necessary to define a consensus column when using the --fast option. the default is 0.5. the symbol fraction in each column is calculated after taking relative sequence weighting into account, and ignoring gap characters corresponding to ends of sequence fragments (as opposed to internal insertions/deletions). setting this to 0.0 means that every alignment column will be assigned as consensus, which may be useful in some cases. setting it to 1.0 means that only columns that include 0 gaps (internal insertions/deletions) will be assigned as consensus.
  • --fragthresh <x> — okay so we only want to count terminal gaps as deletions if the aligned sequence is known to be full-length, not if it's a fragment (for instance, because only part of it was sequenced). HMMER uses a simple rule to infer fragments: if the range of a sequence in the alignment (the number of alignment columns between the first and last positions of the sequence) is less than or equal to a fraction <x> times the alignment length in columns, then the sequence is handled as a fragment. the default is 0.5. setting --fragthresh 0 will define no (nonempty) sequence as a fragment — you might want to do this if you know you've got a carefully curated alignment of full-length sequences. setting --fragthresh 1 will define all sequences as fragments — you might want to do this if you know your alignment is entirely composed of fragments, such as translated short reads in metagenomic shotgun data.

🫶 OPTIONS CONTROLLING RELATIVE WEIGHTS 🫶

HMMER uses an ad hoc sequence weighting algorithm to downweight closely related sequences and upweight distantly related ones. this has the effect of making models less biased by uneven phylogenetic representation. for example, two identical sequences would typically each receive half the weight that one sequence would. so like, no cliques dominating the group chat. these options control which algorithm gets used.

  • --wpb — use the Henikoff position-based sequence weighting scheme [Henikoff and Henikoff, J. Mol. Biol. 243:574, 1994]. this is the default. 👑
  • --wgsc — use the Gerstein/Sonnhammer/Chothia weighting algorithm [Gerstein et al, J. Mol. Biol. 235:1067, 1994].
  • --wblosum — use the same clustering scheme that was used to weight data in calculating BLOSUM substitution matrices [Henikoff and Henikoff, Proc. Natl. Acad. Sci 89:10915, 1992]. sequences are single-linkage clustered at an identity threshold (default 0.62; see --wid) and within each cluster of c sequences, each sequence gets relative weight 1/c.
  • --wnone — no relative weights. all sequences are assigned uniform weight. everybody equal, everybody gets a gold star ⭐
  • --wid <x> — sets the identity threshold used by single-linkage clustering when using --wblosum. invalid with any other weighting scheme. default is 0.62.

💜 OPTIONS CONTROLLING EFFECTIVE SEQUENCE NUMBER 💜

after relative weights are determined, they are normalized to sum to a total effective sequence number, eff_nseq. this number may be the actual number of sequences in the alignment, but it is almost always smaller than that. the default entropy weighting method (--eent) reduces the effective sequence number to reduce the information content (relative entropy, or average expected score on true homologs) per consensus position. the target relative entropy is controlled by a two-parameter function, where the two parameters are settable with --ere and --esigma.

  • --eent — adjust effective sequence number to achieve a specific relative entropy per position (see --ere). this is the default.
  • --eclust — set effective sequence number to the number of single-linkage clusters at a specific identity threshold (see --eid). > this option is not recommended; it's for experiments evaluating how much better --eent is. it's giving "control group" energy, not "recommended settings" energy.
  • --enone — turn off effective sequence number determination and just use the actual number of sequences. one reason you might want to do this is to try to maximize the relative entropy/position of your model, which may be useful for short models.
  • --eset <x> — explicitly set the effective sequence number for all models to <x>.
  • --ere <x> — set the minimum relative entropy/position target to <x>. requires --eent. default depends on the sequence alphabet. for protein sequences, it is 0.59 bits/position; for nucleotide sequences, it is 0.45 bits/position.
  • --esigma <x> — sets the minimum relative entropy contributed by an entire model alignment, over its whole length. this has the effect of making short models have higher relative entropy per position than --ere alone would give. the default is 45.0 bits.
  • --eid <x> — sets the fractional pairwise identity cutoff used by single linkage clustering with the --eclust option. the default is 0.62.

🌟 OPTIONS CONTROLLING PRIORS 🌟

by default, weighted counts are converted to mean posterior probability parameter estimates using mixture Dirichlet priors. default mixture Dirichlet prior parameters for protein models and for nucleic acid (RNA and DNA) models are built in. the following options allow you to override the default priors. built-in defaults? adorable. let's override them anyway 💅

  • --pnone — don't use any priors. probability parameters will simply be the observed frequencies, after relative sequence weighting.
  • --plaplace — use a Laplace +1 prior in place of the default mixture Dirichlet prior.

🍓 OPTIONS CONTROLLING SINGLE SEQUENCE SCORING 🍓

by default, if a query is a single sequence from a file in fasta format, hmmbuild constructs a search model from that sequence and a standard 20x20 substitution matrix for residue probabilities, along with two additional parameters for position-independent gap open and gap extend probabilities. these options allow the default single-sequence scoring parameters to be changed, and for single-sequence scoring options to be applied to a single sequence coming from an aligned format.

  • --singlemx — if a single sequence query comes from a multiple sequence alignment file, such as in stockholm format, the search model is by default constructed as is typically done for multiple sequence alignments. this option forces hmmbuild to use the single-sequence method with substitution score matrix.
  • --mx <s> — obtain residue alignment probabilities from the built-in substitution matrix named <s>. several standard matrices are built-in, and do not need to be read from files. the matrix name <s> can be PAM30, PAM70, PAM120, PAM240, BLOSUM45, BLOSUM50, BLOSUM62, BLOSUM80, BLOSUM90, or DNA1. only one of the --mx and --mxfile options may be used.
  • --mxfile <mxfile> — obtain residue alignment probabilities from the substitution matrix in file <mxfile>. the default score matrix is BLOSUM62 for protein sequences, and DNA1 for nucleotide sequences (these matrices are internal to HMMER and do not need to be available as a file). the format of a substitution matrix <mxfile> is the standard format accepted by BLAST, FASTA, and other sequence analysis software. see ftp.ncbi.nlm.nih.gov/blast/matrices/ for example files. (the only exception: we require matrices to be square, so for DNA, use files like NCBI's NUC.4.4, not NUC.4.2.)
  • --popen <x> — set the gap open probability for a single sequence query model to <x>. the default is 0.02. <x> must be >= 0 and < 0.5.
  • --pextend <x> — set the gap extend probability for a single sequence query model to <x>. the default is 0.4. <x> must be >= 0 and < 1.0.

okay that's part one, bestie — there's more coming, don't go anywhere 🦋

🎀 OPTIONS CONTROLLING E-VALUE CALIBRATION 🎀

okay so bestie, the location parameters for the expected score distributions for MSV filter scores, Viterbi filter scores, and Forward scores require three short random sequence simulations. that's literally the whole lore here. no cap. ✨

  • --EmL <n> — sets the sequence length in simulation that estimates the location parameter mu for MSV filter E-values. Default is 200.
  • --EmN <n> — sets the number of sequences in simulation that estimates the location parameter mu for MSV filter E-values. Default is 200.
  • --EvL <n> — sets the sequence length in simulation that estimates the location parameter mu for Viterbi filter E-values. Default is 200.
  • --EvN <n> — sets the number of sequences in simulation that estimates the location parameter mu for Viterbi filter E-values. Default is 200.
  • --EfL <n> — sets the sequence length in simulation that estimates the location parameter tau for Forward E-values. Default is 100.
  • --EfN <n> — sets the number of sequences in simulation that estimates the location parameter tau for Forward E-values. Default is 200.
  • --Eft <x> — sets the tail mass fraction to fit in the simulation that estimates the location parameter tau for Forward E-values. Default is 0.04.

🌈 OTHER OPTIONS 🌈

these are the side-quest knobs, the extra little switches, the main character options that didn't fit anywhere else. let's get into it. 🫶

  • --cpu <n> — Set the number of parallel worker threads to <n>. On multicore machines, the default is 2. You can also control this number by setting an environment variable, HMMER_NCPU. There is also a master thread, so the actual number of threads that HMMER spawns is <n>+1.
This option is not available if HMMER was compiled with POSIX threads support turned off.
  • --informat <s> — Assert that input msafile is in alignment format <s>, bypassing format autodetection. Common choices for <s> include: stockholm, a2m, afa, psiblast, clustal, phylip. For more information, and for codes for some less common formats, see main documentation. The string <s> is case-insensitive (a2m or A2M both work).
  • --seed <n> — Seed the random number generator with <n>, an integer >= 0. If <n> is nonzero, any stochastic simulations will be reproducible; the same command will give the same results. If <n> is 0, the random number generator is seeded arbitrarily, and stochastic simulations will vary from run to run of the same command. The default seed is 42.
  • --w_beta <x> — Window length tail mass. The upper bound, W, on the length at which nhmmer expects to find an instance of the model is set such that the fraction of all sequences generated by the model with length >= W is less than <x>. The default is 1e-7.
  • --w_length <n> — Override the model instance length upper bound, W, which is otherwise controlled by --w_beta. It should be larger than the model length. The value of W is used deep in the acceleration pipeline, and modest changes are not expected to impact results (though larger values of W do lead to longer run time).
  • --mpi — Run as a parallel MPI program. Each alignment is assigned to an MPI worker node for construction. (Therefore, the maximum parallelization cannot exceed the number of alignments in the input msafile.) This is useful when building large profile libraries. This option is only available if optional MPI capability was enabled at compile-time.
  • --stall — For debugging MPI parallelization: arrest program execution immediately after start, and wait for a debugger to attach to the running process and release the arrest.
  • --maxinsertlen <n> — Restrict insert length parameterization such that the expected insert length at each position of the model is no more than <n>.

🦋 SEE ALSO 🦋

See hmmer(1) for a master man page with a list of all the individual man pages for programs in the HMMER package.

For complete documentation, see the user guide that came with your HMMER distribution (Userguide.pdf); or see the HMMER web page (http://hmmer.org/).

go read more if you're obsessed like me, iykyk. 💖

Copyright (C) 2023 Howard Hughes Medical Institute. Freely distributed under the BSD open source license.

For additional information on copyright and licensing, see the file called COPYRIGHT in your HMMER source distribution, or see the HMMER web page (http://hmmer.org/).

legal bestie moment, but make it slay. 💅

👑 AUTHOR 👑

http://eddylab.org

the plug. the icon. the moment. 🌟

and that's the whole entire hmmbuild(1) page, bestie — HMMER 3.4, Aug 2023, periodt 💅✨🦋

📦 where this page comes from