react-msaview-cli 9.0.0 → 9.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +111 -68
- package/dist/index.js +30856 -26926
- package/package.json +9 -8
package/README.md
CHANGED
|
@@ -10,14 +10,15 @@ The CLI has two groups of commands, and the second draws what the first writes:
|
|
|
10
10
|
a RefSeq transcript's exon model (`genestructure`), and relate rows to 3D
|
|
11
11
|
structures (`residue-mappings`).
|
|
12
12
|
- **Render**: draw the alignment, its tree, and those annotations to a
|
|
13
|
-
standalone SVG (`export-svg`). The command runs the web viewer's
|
|
14
|
-
headlessly, so the figure matches what the app shows.
|
|
13
|
+
standalone SVG, PNG or PDF (`export-svg`). The command runs the web viewer's
|
|
14
|
+
renderer headlessly, so the figure matches what the app shows.
|
|
15
15
|
|
|
16
16
|
## Prerequisites
|
|
17
17
|
|
|
18
18
|
- NodeJS v22+
|
|
19
19
|
|
|
20
|
-
`export-svg`, `interpro` and `residue-mappings` need nothing else
|
|
20
|
+
`export-svg`, `interpro` and `residue-mappings` need nothing else, except that
|
|
21
|
+
`export-svg` writes PNG and PDF through `rsvg-convert` from librsvg.
|
|
21
22
|
`interproscan` needs a backend to scan with: the EBI web API (the default, no
|
|
22
23
|
install), Docker, Singularity, or a local InterProScan (see
|
|
23
24
|
[interproscan](#interproscan)).
|
|
@@ -73,23 +74,31 @@ GPCR examples in
|
|
|
73
74
|
react-msaview-cli export-svg --msa <file> [options]
|
|
74
75
|
```
|
|
75
76
|
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
|
79
|
-
|
|
|
80
|
-
| `--
|
|
81
|
-
| `--
|
|
82
|
-
|
|
|
83
|
-
| `--
|
|
84
|
-
| `--
|
|
85
|
-
| `--
|
|
86
|
-
|
|
|
87
|
-
| `--
|
|
88
|
-
| `--
|
|
89
|
-
| `--
|
|
90
|
-
| `--
|
|
91
|
-
| `--
|
|
92
|
-
| `--
|
|
77
|
+
<!-- options:export-svg -->
|
|
78
|
+
|
|
79
|
+
| Option | Description | Default |
|
|
80
|
+
| ------------------------ | ------------------------------------------------------------------------------------------------------ | --------------------------------- |
|
|
81
|
+
| `--spec <file.json>` | View spec or snapshot, with any layer from docs/layers.md; the flags below override it | |
|
|
82
|
+
| `--props <file.json>` | MSAViewer props as the R and Python widgets send them, in place of `--spec` | |
|
|
83
|
+
| `--msa <file>` | MSA file (FASTA, Stockholm, Clustal, A3M, EMF); required without `--spec` or `--props` | |
|
|
84
|
+
| `--format <name>` | Force the MSA format (stockholm, fasta, a3m, clustal, emf) instead of sniffing it | |
|
|
85
|
+
| `--tree <file>` | Newick tree file | |
|
|
86
|
+
| `--gff <file>` | Domain or exon GFF, or InterProScan JSON | |
|
|
87
|
+
| `-o, --output <file>` | Output file; `.svg`, `.png` or `.pdf` picks the format, and PNG and PDF need rsvg-convert from librsvg | `alignment.svg` |
|
|
88
|
+
| `--scale <n>` | Pixels per SVG unit in a PNG | `2` |
|
|
89
|
+
| `--color-scheme <name>` | Color scheme | `maeditor` |
|
|
90
|
+
| `--theme <light\|dark>` | Page and text colors | the `--props` theme, else `light` |
|
|
91
|
+
| `--width <px>` | Viewport width, which sets the tree area | `1200` |
|
|
92
|
+
| `--height <px>` | Viewport height | `600` |
|
|
93
|
+
| `--tree-area-width <px>` | Tree panel width in pixels | fit to the labels |
|
|
94
|
+
| `--col-width <px>` | Width of one alignment column | `12` |
|
|
95
|
+
| `--row-height <px>` | Height of one alignment row | `16` |
|
|
96
|
+
| `--tracks <list>` | Tracks to draw above the alignment, by id (`conservation,position-ruler`), or `all` | none |
|
|
97
|
+
| `--viewport` | Draw the `--width` x `--height` viewport at the top left instead of the entire alignment | |
|
|
98
|
+
| `--minimap` | Include the minimap bar (`--viewport` only) | |
|
|
99
|
+
| `--force` | Export past the 500,000-letter limit, where the export can run out of memory | |
|
|
100
|
+
|
|
101
|
+
<!-- /options -->
|
|
93
102
|
|
|
94
103
|
### Tracks
|
|
95
104
|
|
|
@@ -159,9 +168,11 @@ react-msaview-cli export-svg --msa gpcrs.fa \
|
|
|
159
168
|
`cinema`, and the `jalview_*` family (`jalview_zappo`, `jalview_taylor`,
|
|
160
169
|
`jalview_hydrophobicity`, `jalview_buried`, `jalview_prophelix`,
|
|
161
170
|
`jalview_propstrand`, `jalview_propturn`) color each residue by identity. The
|
|
162
|
-
|
|
163
|
-
`
|
|
164
|
-
|
|
171
|
+
three `_dynamic` schemes, `clustalx_protein_dynamic`, `percent_identity_dynamic`
|
|
172
|
+
and `blosum62_dynamic`, color each residue by the composition of its column, so
|
|
173
|
+
conserved columns stand out by color. `blosum62_dynamic` shades each residue by
|
|
174
|
+
its mean BLOSUM62 similarity to the rest of its column, so a conservative
|
|
175
|
+
substitution reads darker than a radical one. `nucleotide`, `clustalx_dna`,
|
|
165
176
|
`jbrowse_dna` and `rainbow_dna` are for DNA; `none` turns background color off.
|
|
166
177
|
|
|
167
178
|
### Output
|
|
@@ -169,14 +180,22 @@ so conserved columns stand out by color. `nucleotide`, `clustalx_dna`,
|
|
|
169
180
|
The SVG grows with the alignment: a 10-row by 856-column figure is about 700KB.
|
|
170
181
|
The background is one embedded image where @napi-rs/canvas is installed, and a
|
|
171
182
|
rectangle per cell where it is not. The letters, the tree and the annotations
|
|
172
|
-
are vector either way.
|
|
183
|
+
are vector either way.
|
|
184
|
+
|
|
185
|
+
An `-o` ending in `.png` or `.pdf` converts the SVG with `rsvg-convert` from
|
|
186
|
+
librsvg (`apt install librsvg2-bin`, `brew install librsvg`). A PDF keeps the
|
|
187
|
+
letters, the tree and the annotations vector. `--scale` sets the pixels per SVG
|
|
188
|
+
unit of a PNG, 2 by default:
|
|
173
189
|
|
|
174
190
|
```bash
|
|
175
|
-
|
|
176
|
-
|
|
191
|
+
react-msaview-cli export-svg --msa kinases.aln --tree kinases.nwk -o kinases.pdf
|
|
192
|
+
react-msaview-cli export-svg --msa kinases.aln --scale 4 -o kinases.png
|
|
177
193
|
```
|
|
178
194
|
|
|
179
|
-
The same input gives the same bytes, so CI can regenerate a
|
|
195
|
+
The same input gives the same bytes on one machine, so CI can regenerate a
|
|
196
|
+
figure and diff it. With @napi-rs/canvas installed, the export measures labels
|
|
197
|
+
with that machine's fonts, so the tree area can come out a few pixels wider or
|
|
198
|
+
narrower on another machine.
|
|
180
199
|
|
|
181
200
|
## Annotating
|
|
182
201
|
|
|
@@ -200,13 +219,17 @@ id or anything else InterPro does not key by; run `interproscan` on those. It
|
|
|
200
219
|
writes through the same GFF writer as `interproscan`, and adds a `#` header line
|
|
201
220
|
naming the InterPro release the coordinates came from.
|
|
202
221
|
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
|
206
|
-
|
|
|
207
|
-
|
|
|
208
|
-
| `--
|
|
209
|
-
| `--
|
|
222
|
+
<!-- options:interpro -->
|
|
223
|
+
|
|
224
|
+
| Option | Description | Default |
|
|
225
|
+
| --------------------- | ----------------------------------------------------------------------------------- | ------------- |
|
|
226
|
+
| `-o, --output <file>` | Output GFF file | `domains.gff` |
|
|
227
|
+
| `--database <name>` | InterPro member database to read | `pfam` |
|
|
228
|
+
| `--msa <file>` | Alignment the GFF is for; the CLI checks each row's ungapped length against UniProt | |
|
|
229
|
+
| `--format <name>` | Force the `--msa` format instead of sniffing it | |
|
|
230
|
+
| `--no-cache` | Re-fetch every accession, ignoring the disk cache | |
|
|
231
|
+
|
|
232
|
+
<!-- /options -->
|
|
210
233
|
|
|
211
234
|
InterPro computes matches on UniProt's canonical sequence. A label ending in
|
|
212
235
|
`/start-end`, as Pfam and Stockholm name a fragment row (`P12931/84-145`), moves
|
|
@@ -248,19 +271,23 @@ proteins, or anything else InterPro has not scanned.
|
|
|
248
271
|
react-msaview-cli interproscan <input-msa> [options]
|
|
249
272
|
```
|
|
250
273
|
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
|
254
|
-
|
|
|
255
|
-
|
|
|
256
|
-
| `--
|
|
257
|
-
| `--docker
|
|
258
|
-
| `--singularity
|
|
259
|
-
| `--
|
|
260
|
-
| `--
|
|
261
|
-
| `--
|
|
262
|
-
| `--
|
|
263
|
-
| `--
|
|
274
|
+
<!-- options:interproscan -->
|
|
275
|
+
|
|
276
|
+
| Option | Description | Default |
|
|
277
|
+
| ----------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
|
|
278
|
+
| `-o, --output <file>` | Output GFF file | `domains.gff` |
|
|
279
|
+
| `--local` | Run a local InterProScan installation instead of the EBI API | |
|
|
280
|
+
| `--docker` | Run InterProScan in the `interpro/interproscan` Docker image | |
|
|
281
|
+
| `--singularity` | Run InterProScan in a Singularity/Apptainer container | |
|
|
282
|
+
| `--docker-image <image>` | Docker image to run | `interpro/interproscan:5.78-109.0` |
|
|
283
|
+
| `--singularity-image <image>` | Singularity image to run | `docker://interpro/interproscan:5.78-109.0` |
|
|
284
|
+
| `--interproscan-path <path>` | Path to a local interproscan.sh | `interproscan.sh` |
|
|
285
|
+
| `--interproscan-data <dir>` | Host directory holding the member database `data/` to mount into the container, which the image ships without | |
|
|
286
|
+
| `--programs <list>` | Comma-separated programs in the EBI API's naming; the container and local backends get the InterProScan 5 names | `PfamA,CDD` |
|
|
287
|
+
| `--format <name>` | Force the MSA format (stockholm, fasta, a3m, clustal, emf) instead of sniffing it | |
|
|
288
|
+
| `--email <email>` | Email for the EBI API, which only EBI runs send | `user@example.com` |
|
|
289
|
+
|
|
290
|
+
<!-- /options -->
|
|
264
291
|
|
|
265
292
|
By default (no backend flag) the CLI submits sequences to the EBI InterProScan
|
|
266
293
|
REST API one at a time. `--local`, `--docker`, and `--singularity` run
|
|
@@ -331,14 +358,19 @@ shorter on that row and stays in the same columns as the rest. The reference row
|
|
|
331
358
|
must be the transcript's coding sequence; the CLI warns if its length doesn't
|
|
332
359
|
match.
|
|
333
360
|
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
|
337
|
-
|
|
|
338
|
-
| `--gene
|
|
339
|
-
| `--
|
|
340
|
-
| `--
|
|
341
|
-
|
|
|
361
|
+
<!-- options:genestructure -->
|
|
362
|
+
|
|
363
|
+
| Option | Description | Default |
|
|
364
|
+
| --------------------- | --------------------------------------------------------------------------------- | ------------------- |
|
|
365
|
+
| `--gene <symbol>` | Gene symbol to look up in RefSeq (e.g. `F12`) | |
|
|
366
|
+
| `--taxon <name\|id>` | Taxon for `--gene` | `human` |
|
|
367
|
+
| `--gene-id <id>` | NCBI GeneID, instead of `--gene` | |
|
|
368
|
+
| `--transcript <acc>` | Specific transcript accession | MANE/RefSeq Select |
|
|
369
|
+
| `--ref <rowname>` | Reference row, which must be the transcript's CDS | first row |
|
|
370
|
+
| `--format <name>` | Force the MSA format (stockholm, fasta, a3m, clustal, emf) instead of sniffing it | |
|
|
371
|
+
| `-o, --output <file>` | Output GFF file | `genestructure.gff` |
|
|
372
|
+
|
|
373
|
+
<!-- /options -->
|
|
342
374
|
|
|
343
375
|
```bash
|
|
344
376
|
## F12 coding alignment -> 14-exon overlay (MANE Select transcript, human row)
|
|
@@ -362,16 +394,21 @@ react-msaview-cli residue-mappings --msa <file> --row <name> --accession <acc> \
|
|
|
362
394
|
react-msaview-cli residue-mappings --msa <file> --rows <tsv> [-o mappings.json]
|
|
363
395
|
```
|
|
364
396
|
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
|
368
|
-
|
|
|
369
|
-
| `--
|
|
370
|
-
| `--
|
|
371
|
-
| `--
|
|
372
|
-
| `--
|
|
373
|
-
| `--
|
|
374
|
-
|
|
|
397
|
+
<!-- options:residue-mappings -->
|
|
398
|
+
|
|
399
|
+
| Option | Description | Default |
|
|
400
|
+
| --------------------- | ------------------------------------------------------------------------------------------------------- | ------- |
|
|
401
|
+
| `--msa <file>` | Alignment holding the rows (required) | |
|
|
402
|
+
| `--format <name>` | Force the MSA format (stockholm, fasta, a3m, clustal, emf) instead of sniffing it | |
|
|
403
|
+
| `--rows <tsv>` | `row`, `accession`, `structure` per line, tab-separated, where the structure is `6VXX:A` or `alphafold` | |
|
|
404
|
+
| `--row <name>` | One row, instead of `--rows` | |
|
|
405
|
+
| `--accession <acc>` | The row's UniProtKB accession | |
|
|
406
|
+
| `--pdb <id>` | The PDB entry to map the row onto | |
|
|
407
|
+
| `--chain <id>` | The `--pdb` entry's author chain | |
|
|
408
|
+
| `--alphafold` | Map the row onto the AlphaFold DB model of the accession instead | |
|
|
409
|
+
| `-o, --output <file>` | Output JSON file | stdout |
|
|
410
|
+
|
|
411
|
+
<!-- /options -->
|
|
375
412
|
|
|
376
413
|
In `--rows`, the structure column is `6VXX:A` or `alphafold`, and a
|
|
377
414
|
`row accession structure` header line is optional. A row may appear on several
|
|
@@ -442,9 +479,9 @@ Done!
|
|
|
442
479
|
The web viewer, the React component and the R package all load the file the CLI
|
|
443
480
|
writes.
|
|
444
481
|
|
|
445
|
-
In the web viewer, select it in the import form's **
|
|
446
|
-
|
|
447
|
-
|
|
482
|
+
In the web viewer, select it in the import form's **Annotations** field, or open
|
|
483
|
+
it over a loaded alignment with **File > Open annotation file…**, which also
|
|
484
|
+
accepts the JSON an InterProScan run returns.
|
|
448
485
|
|
|
449
486
|
In the React component, pass it inline as the `gff` prop:
|
|
450
487
|
|
|
@@ -483,6 +520,12 @@ formats above.
|
|
|
483
520
|
half the row height, the residue letters stop drawing, and they account for most
|
|
484
521
|
of the file size.
|
|
485
522
|
|
|
523
|
+
**The export refuses to draw the entire alignment.** Each residue letter is an
|
|
524
|
+
SVG element, and an alignment of 500 rows by 1000 columns takes 3.4GB to export.
|
|
525
|
+
Past 500,000 letters the CLI stops with an error unless `--force` is given. A
|
|
526
|
+
`--col-width` below 5 or a `--row-height` below 8 draws the same alignment with
|
|
527
|
+
no letters, and `--viewport` draws one window of it.
|
|
528
|
+
|
|
486
529
|
## Uses
|
|
487
530
|
|
|
488
531
|
[msa-parsers](https://github.com/GMOD/JBrowseMSA/tree/main/packages/msa-parsers)
|