Hmmrank coordinates

AGENTS.md

@@ -92,9 +92,9 @@ additional entries for `ch_phyloplace_data`, which is finally passed into
 `FASTA_NEWICK_EPANG_GAPPA`.
 
 **`subworkflows/nf-core/fasta_hmmsearch_rank_fastas`**: runs `HMMER_HMMSEARCH` per
-profile/fasta pair, ranks hits across all profiles with `HMMER_HMMRANK` (this pipeline's own
-module — resolves cases where a sequence would match multiple profiles), keeps only rank-1
-hits per profile, and extracts those sequences per-profile with `SEQTK_SUBSEQ`.
+profile/fasta pair, ranks hits across all profiles with `HMMER_HMMRANK` (vendored from
+nf-core/modules — resolves cases where a sequence would match multiple profiles), keeps only
+rank-1 hits per profile, and extracts those sequences per-profile with `SEQTK_SUBSEQ`.
 
 **`subworkflows/nf-core/fasta_newick_epang_gappa`** is the core placement subworkflow and the
 most complex part of the pipeline. It branches the incoming channel three ways by
@@ -120,12 +120,18 @@ All three branches converge into one `ch_epang_query` channel keyed by
 file was supplied — joined back in from the original data channel), and
 `GAPPA_EXAMINEHEATTREE` (SVG heat tree).
 
-**Local vs nf-core modules/subworkflows**: `modules/local/hmmer/hmmextract` and both
-subworkflows under `subworkflows/nf-core/` (`fasta_hmmsearch_rank_fastas`,
-`fasta_newick_epang_gappa`) are pipeline-specific despite one pair living under the
-`nf-core/` subworkflow directory name — everything else under `modules/nf-core/` and
-`subworkflows/nf-core/utils_*` is vendored, unmodified nf-core community code and should be
-updated via `nf-core modules update` / `nf-core subworkflows update`, not edited by hand.
+**Local vs nf-core modules/subworkflows**: the only pipeline-local components are
+`modules/local/hmmer/hmmextract` and `subworkflows/local/utils_nfcore_phyloplace_pipeline`.
+Everything under `modules/nf-core/` and `subworkflows/nf-core/` is vendored nf-core community
+code, tracked in `modules.json`, and must be changed upstream in nf-core/modules and pulled in
+with `nf-core modules update` / `nf-core subworkflows update` rather than edited by hand.
+
+That includes `fasta_hmmsearch_rank_fastas`, `fasta_newick_epang_gappa` and `hmmer/hmmrank`,
+which are easy to mistake for local code: they originated here and are still maintained by
+this pipeline's author, but they live in nf-core/modules like any other vendored component.
+`hmmer/hmmrank` and `fasta_hmmsearch_rank_fastas` are also vendored by nf-core/ampliseq, so
+changes to them have to stay backwards compatible — new inputs need to be optional, and the
+existing output columns cannot be renamed or reordered.
 
 ## Template syncs and module updates
 

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### `Added`
 
+    - [#72](https://github.com/nf-core/phyloplace/pull/72) - Alignment coordinates, lengths and coverage for each hit in the ranked `hmmsearch` summary, when `--save_domtblout` is set ([#70](https://github.com/nf-core/phyloplace/issues/70)) (by @erikrikarddaniel)
     - [#71](https://github.com/nf-core/phyloplace/pull/71) - New `--save_domtblout` option, saving hmmsearch's per-domain hit table in "search and place" mode ([#69](https://github.com/nf-core/phyloplace/issues/69)) (by @erikrikarddaniel)
 
 ### `Fixed`

docs/output.md

@@ -48,7 +48,16 @@ The MAFFT alignment strategy keeps the structure of the original reference align
   - `*.domtbl.gz`: Per-domain hit table (`--domtblout`) for individual `hmmsearch` runs in "search and place" mode, only written when `--save_domtblout` is set.
     Unlike the per-sequence table, this one carries alignment coordinates for each domain, which are needed to work out profile coverage or to find genes split over several ORFs.
   - `*.txt.gz`: Standard, human-readable, format results for individual `hmmsearch` runs in "search and place" mode
-  - `*.hmmrank.tsv.gz`: Summarised `hmmsearch` results
+  - `*.hmmrank.tsv.gz`: Summarised `hmmsearch` results, one row per sequence and profile, ranking the profiles that matched each sequence.
+    When `--save_domtblout` is set, each row also carries the lengths of the sequence (`tlen`) and the profile (`qlen`), plus four columns for each of the three coordinate sets HMMER reports: `hmm` (position in the profile), `ali` (the aligned part of the sequence) and `env` (the wider region the alignment is likely to lie within).
+    For a set `x`, `x_from` and `x_to` are the outer bounds of the match, while `x_len` is how much of that span the sequence's domains actually cover, so a hit whose domains are scattered has an `x_len` well below `x_to - x_from`.
+    `x_n_islands` counts the separate stretches that coverage falls into: 1 for a single continuous match, more when the domains are broken up.
+    The two lengths are the denominators for coverage, each belonging to a different coordinate set: `hmm` positions are in the profile, so `hmm_len / qlen` is the proportion of the profile a hit covers, while `ali` and `env` positions are in the sequence, so `ali_len / tlen` is the proportion of the sequence the alignment takes up (`env_len / tlen` for the looser envelope).
+    Mixing them, say `hmm_len / tlen`, compares a profile position against a sequence length and means nothing.
+    For the profile, `hmm_from - 1` and `qlen - hmm_to` also tell you how much is missing from each of its ends.
+    Coverage counts every domain HMMER reported, however weak on its own; which sequences are reported at all is still decided by the full-sequence scores, exactly as when the coordinates are not requested.
+    A sequence is reported at all on the per-sequence threshold, whereas a domain has to clear the per-domain one, so a hit can be ranked here with no domain records behind it at all.
+    Those rows carry `NA` in every column above, which is deliberate: an empty value is the clearest signal that `hmmsearch` reported no domains for the hit, and it keeps such rows distinguishable from ones whose coordinates were genuinely computed.
 
 </details>
 

docs/usage.md

@@ -78,6 +78,7 @@ Add `--save_domtblout` to also write the per-domain table, as one gzipped `*.dom
 ```
 
 The per-domain table is the only output that carries alignment coordinates, so it is what you need to work out how much of a profile a hit covers, or to find a gene split over several adjacent ORFs where no single ORF covers enough of the profile to be classified on its own.
+Setting the flag also adds coordinate and length columns to the ranked summary in `*.hmmrank.tsv.gz`, which is usually the easier place to read them off; see [output.md](output.md) for what each column means.
 
 ## Running the pipeline
 

modules.json

@@ -57,7 +57,7 @@
                     },
                     "hmmer/hmmrank": {
                         "branch": "master",
-                        "git_sha": "f2bed902e13076698e7d59d1fedf5c083f6f17c0",
+                        "git_sha": "0d22d061e16d1e1b91728d62aaf52d328bd50181",
                         "installed_by": ["fasta_hmmsearch_rank_fastas"]
                     },
                     "hmmer/hmmsearch": {
@@ -86,7 +86,7 @@
                 "nf-core": {
                     "fasta_hmmsearch_rank_fastas": {
                         "branch": "master",
-                        "git_sha": "56521ad3d62f3bcc12285fe4b62ea2d574433090",
+                        "git_sha": "106170c99010f5429b24c610f2da528e47ca3276",
                         "installed_by": ["subworkflows"]
                     },
                     "fasta_newick_epang_gappa": {