react-msaview-cli 8.2.0 → 8.4.0

package/README.md

@@ -7,7 +7,8 @@ The CLI has two groups of commands, and the second draws what the first writes:
 
 - **Annotate**: build a domain or exon GFF for an alignment, from InterPro's
   precomputed matches (`interpro`), a live InterProScan run (`interproscan`), or
-  a RefSeq transcript's exon model (`genestructure`).
+  a RefSeq transcript's exon model (`genestructure`), and relate rows to 3D
+  structures (`residue-mappings`).
 - **Render**: draw the alignment, its tree, and those annotations to a
   standalone SVG (`export-svg`). The command runs the web viewer's renderer
   headlessly, so the figure matches what the app shows.
@@ -16,9 +17,10 @@ The CLI has two groups of commands, and the second draws what the first writes:
 
 - NodeJS v22+
 
-`export-svg` and `interpro` need nothing else. `interproscan` needs a backend to
-scan with: the EBI web API (the default, no install), Docker, Singularity, or a
-local InterProScan (see [interproscan](#interproscan)).
+`export-svg`, `interpro` and `residue-mappings` need nothing else.
+`interproscan` needs a backend to scan with: the EBI web API (the default, no
+install), Docker, Singularity, or a local InterProScan (see
+[interproscan](#interproscan)).
 
 `export-svg` draws the alignment background as one embedded image when
 [@napi-rs/canvas](https://www.npmjs.com/package/@napi-rs/canvas) is present. The
@@ -73,9 +75,10 @@ react-msaview-cli export-svg --msa <file> [options]
 
 | Option                   | Description                                    | Default         |
 | ------------------------ | ---------------------------------------------- | --------------- |
+| `--spec <file.json>`     | View spec or snapshot (see below)              |                 |
 | `--msa <file>`           | MSA file (FASTA, Stockholm, Clustal, A3M, EMF) | _required_      |
 | `--tree <file>`          | Newick tree file                               |                 |
-| `--gff <file>`           | Domain or exon GFF (from the commands below)   |                 |
+| `--gff <file>`           | Domain or exon GFF, or InterProScan JSON       |                 |
 | `-o, --output <file>`    | Output SVG file path                           | `alignment.svg` |
 | `--color-scheme <name>`  | Color scheme                                   | `maeditor`      |
 | `--col-width <px>`       | Width of one alignment column                  | `12`            |
@@ -101,6 +104,20 @@ react-msaview-cli export-svg --msa kinases.aln --tracks conservation,position-ru
   -o kinases.svg
 ```
 
+### Layers
+
+`--spec` takes an `MsaView` snapshot or its shorthand as a JSON file, so any
+layer in [the layers reference](https://gmod.org/JBrowseMSA/layers) draws in the
+figure: column tracks, highlights, clades, row panels, encodings. A spec that
+sets `msa`, `tree`, or a filehandle's `uri` to a relative path reads it beside
+the spec file, and an `http(s)` one fetches it. `--msa` is then optional, and
+every flag given on the command line overrides the spec. The figure draws the
+tracks the app would show for the spec, unless `--tracks` names them.
+
+```bash
+react-msaview-cli export-svg --spec p53-view.json -o p53.svg
+```
+
 ### Sizing the figure
 
 `export-svg` draws the **entire** alignment unless `--viewport` asks for the
@@ -176,9 +193,12 @@ react-msaview-cli interpro <accessions.tsv> [options]
 ```
 
 The input is one accession per line, optionally followed by a tab- or
-space-separated row label. The command skips lines starting with `#`. It writes
-through the same GFF writer as `interproscan`, and adds a `#` header line naming
-the InterPro release the coordinates came from.
+space-separated row label. The command skips lines starting with `#`. It reads
+an isoform (`P04637-2`) or versioned (`P04637.4`) accession as the canonical one
+and warns, and stops before any request on an entry name (`P53_HUMAN`), a RefSeq
+id or anything else InterPro does not key by; run `interproscan` on those. It
+writes through the same GFF writer as `interproscan`, and adds a `#` header line
+naming the InterPro release the coordinates came from.
 
 | Option                | Description                                     | Default       |
 | --------------------- | ----------------------------------------------- | ------------- |
@@ -188,10 +208,13 @@ the InterPro release the coordinates came from.
 | `--format <name>`     | Force the `--msa` format instead of sniffing it |               |
 | `--no-cache`          | Re-fetch, ignoring the disk cache               | off           |
 
-InterPro computes matches on UniProt's canonical sequence, so on a row that is
-an isoform or a fragment the matches land on the wrong residues. With `--msa`,
-the CLI compares each row's ungapped length against the protein's and warns
-about any that differ. It also warns about any accession with no matches.
+InterPro computes matches on UniProt's canonical sequence. A label ending in
+`/start-end`, as Pfam and Stockholm name a fragment row (`P12931/84-145`), moves
+each match into the fragment's own positions and clips it to the fragment. On an
+isoform row the matches land on the wrong residues. With `--msa`, the CLI
+compares each row's ungapped length against the protein's, or against the
+range's for a fragment, and warns about any that differ. It also warns about any
+accession with no matches.
 
 ```bash
 react-msaview-cli interpro accessions.tsv -o domains.gff
@@ -212,6 +235,9 @@ the rest from disk. A failed run can therefore resume. The CLI retries with
 backoff, and if the API stays unreachable, the accessions it already fetched
 stay cached, so the next run fetches only the rest.
 
+When the release lookup fails, the CLI warns and reads the newest release in the
+cache, so a fully cached run needs no network.
+
 ### interproscan
 
 Run InterProScan on all sequences in an MSA file and output results as GFF3. Use
@@ -322,6 +348,54 @@ react-msaview-cli genestructure f12-cds.stock --gene F12 --ref human -o exons.gf
 react-msaview-cli genestructure aln.fa --transcript NM_000505.4 --ref human
 ```
 
+### residue-mappings
+
+Build the
+[`residueMappings` layer](https://github.com/GMOD/JBrowseMSA/blob/main/docs/layers.md#residuemappings),
+which tells the viewer which residue of a PDB chain or an AlphaFold model each
+residue of a row is. The output is `{"residueMappings": [...]}`, ready for the
+`residueMappings` prop, a `#data=` link, or the R and Python widgets.
+
+```bash
+react-msaview-cli residue-mappings --msa <file> --row <name> --accession <acc> \
+  (--pdb <id> --chain <id> | --alphafold) [-o mappings.json]
+react-msaview-cli residue-mappings --msa <file> --rows <tsv> [-o mappings.json]
+```
+
+| Option                    | Description                                             | Default |
+| ------------------------- | ------------------------------------------------------- | ------- |
+| `--msa <file>`            | Alignment holding the rows                              |         |
+| `--format <name>`         | Force the MSA format instead of sniffing it             |         |
+| `--rows <tsv>`            | `row`, `accession`, `structure` per line, tab-separated |         |
+| `--row <name>`            | One row, instead of `--rows`                            |         |
+| `--accession <acc>`       | The row's UniProtKB accession                           |         |
+| `--pdb <id> --chain <id>` | The PDB entry and its author chain                      |         |
+| `--alphafold`             | The AlphaFold DB model of the accession instead         |         |
+| `-o, --output <file>`     | Output JSON file                                        | stdout  |
+
+In `--rows`, the structure column is `6VXX:A` or `alphafold`, and a
+`row accession structure` header line is optional. A row may appear on several
+lines to map it onto several structures.
+
+For each row, the CLI first fetches the accession's sequence from UniProt and
+checks the row's ungapped residues against it. A row named `/start-end` has to
+match that slice of the protein, and every position in its mapping is a residue
+of the row. A mismatch stops the run with the row, the accession and the first
+residue where they differ.
+
+For a PDB chain, the segments come from the PDBe SIFTS mapping of the entry, and
+`unobserved` lists every position of the chain's entity outside PDBe's observed
+ranges. `asymId` is the `struct_asym_id` SIFTS gives for the author chain. For
+an AlphaFold model, the model numbers the protein from 1, so the mapping is one
+segment and has no `unobserved`.
+
+```console
+$ react-msaview-cli residue-mappings --msa spike.afa --row SARS-CoV-2 \
+    --accession P0DTC2 --pdb 6VXX --chain A -o mappings.json
+  SARS-CoV-2: P0DTC2 onto 6VXX chain A, row 14-1211 at 33-1230
+wrote mappings.json
+```
+
 ## Input formats
 
 The CLI sniffs the format from the file's content, not from its name. `--format`