19406b4ab279b704b09212e193258cffc52eb18a
[jalview.git] / help / help / html / features / clarguments-basic.html
1 <html>
2 <!--
3  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
4  * Copyright (C) $$Year-Rel$$ The Jalview Authors
5  * 
6  * This file is part of Jalview.
7  * 
8  * Jalview is free software: you can redistribute it and/or
9  * modify it under the terms of the GNU General Public License 
10  * as published by the Free Software Foundation, either version 3
11  * of the License, or (at your option) any later version.
12  *  
13  * Jalview is distributed in the hope that it will be useful, but 
14  * WITHOUT ANY WARRANTY; without even the implied warranty 
15  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
16  * PURPOSE.  See the GNU General Public License for more details.
17  * 
18  * You should have received a copy of the GNU General Public License
19  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
20  * The Jalview Authors are detailed in the 'AUTHORS' file.
21  -->
22 <title>Jalview Command Line Arguments: basic usage</title>
23 <body>
24
25   <h1>Jalview Command Line Arguments: basic usage</h1>
26
27   <p>
28   <a href="clarguments.html">Jalview Command Line Arguments: summary</a>
29   <br/>
30   <a href="clarguments-intro.html">Jalview Command Line Arguments: introduction</a>
31   <br/>
32   Jalview Command Line Arguments: basic usage
33   <br/>
34   <a href="clarguments-advanced.html">Jalview Command Line Arguments: advanced usage</a>
35   <br/>
36   <a href="clarguments-argfiles.html">Jalview Command Line Arguments: argfiles</a>
37   </p>
38
39   <hr/>
40
41   <ul>
42   <li><a href="#openingalignments">Opening alignments</a></li>
43   <li><a href="#alignmentoptions">Alignment options</a></li>
44   <li><a href="#adding3dstructures">Adding 3D structures</a></li>
45   <li><a href="#outputtingalignmentfiles">Outputting/converting alignment files and images</a></li>
46   <li><a href="#filenamesubstitutionsandbatchprocessing">Filename substitutions and batch processing</a></li>
47   </ul>
48
49   <h2><a name="openingalignments"></a>Opening alignments (<code>--open</code>, <code>--append</code>, <code>--new</code>)</h2>
50
51   <p>
52   To simply open one or more alignment files in different windows just put the filenames as the first arguments:
53   <pre>
54   jalview filename1 filename2 ...
55   </pre>
56   </p>
57
58   <p>
59   You can use shell-expanded wildcards:
60   <pre>
61   jalview this/filename* that/filename* other/filename*
62   </pre>
63   and URLs:
64   <pre>
65   jalview https://rest.uniprot.org/uniprotkb/P00221.fasta
66   </pre>
67   </p>
68
69   <p>
70   (Using initial filenames is the same as using the <code>--open</code> argument, and further arguments can be used
71   after the initial filenames.)
72   </p>
73
74   <h3><a name="open"></a><code>--open</code></h3>
75
76   <p>
77   Use the <code>--open</code> argument to open alignment files each in their own window.
78   </p>
79
80   <p>
81   The following are equivalent:
82   <pre>
83   jalview --open filename1 filename2 ...
84
85   jalview --open filename*
86
87   jalview --open filename1 --open filename2 --open ...
88
89   jalview filename1 filename2 ...
90   </pre>
91   </p>
92
93   <p>
94   Similarly you can open URLs:
95   <pre>
96   jalview --open https://rest.uniprot.org/uniprotkb/P00221.fasta
97   </pre>
98   </p>
99
100   <h3><a name="append"></a><code>--append</code></h3>
101
102   <p>
103   To append several alignment files together use:
104   <pre>
105   jalview --open filename1.fa --append filename2.fa filename3.fa
106   </pre>
107   or, if you haven't previously used <code>--open</code> then you can use --append to open one new window and keep appending each set of alignments:
108   <pre>
109   jalview --append these/filename*.fa --append more/filename*.fa
110
111   jalview --append https://rest.uniprot.org/uniprotkb/P00221.fasta https://www.uniprot.org/uniprotkb/A0A0K9QVB3/entry
112   </pre>
113   </p>
114
115   <p>
116   <strong>Note</strong> that whilst you can include a Jalview Project File (<code>.jvp</code>) as an <code>--append</code> value, the items in the file will always open in their original windows and not append to another.
117   </p>
118
119   <h3><a name="new"></a><code>--new</code></h3>
120
121   <p>
122   To append different sets of alignment files in different windows, use <code>--new</code> to move on to a new alignment window:
123   <pre>
124   jalview --append these/filename*.fa --new --append other/filename*.fa
125   </pre>
126   </p>
127
128   <p>
129   <code>--open</code> is like using <code>--new --append</code> applied to every filename/URL given to <code>--open</code>
130   </p>
131
132
133   <h2><a name="alignmentoptions"></a>Alignment options (<code>--colour</code>, <code>--wrap</code>, <code>--showannotations</code>, <code>--title</code>)</h2>
134
135   <h3><a name="colour"></a><code>--colour</code></h3>
136
137   <p>
138   You can specify a residue/base colouring for the alignment using the <code>--colour</code> option (note spelling -- Jalview is made in Scotland!):
139   <pre>
140   jalview --open examples/uniref50.fa --colour gecos-flower
141   </pre>
142   There are several colour schemes that you can use.  See the <a href="../colourSchemes/index.html">page on Colour Schemes</a> for details.
143   The names to use on the command line for colour schemes are:
144   </p>
145   <p>
146   <code>clustal</code>,
147   <br/>
148   <code>blosum62</code>,
149   <br/>
150   <code>pc-identity</code>,
151   <br/>
152   <code>zappo</code>,
153   <br/>
154   <code>taylor</code>,
155   <br/>
156   <code>gecos-flower</code>,
157   <br/>
158   <code>gecos-blossom</code>,
159   <br/>
160   <code>gecos-sunset</code>,
161   <br/>
162   <code>gecos-ocean</code>,
163   <br/>
164   <code>hydrophobic</code>,
165   <br/>
166   <code>helix-propensity</code>,
167   <br/>
168   <code>strand-propensity</code>,
169   <br/>
170   <code>turn-propensity</code>,
171   <br/>
172   <code>buried-index</code>,
173   <br/>
174   <code>nucleotide</code>,
175   <br/>
176   <code>nucleotide-ambiguity</code>,
177   <br/>
178   <code>purine-pyrimidine</code>,
179   <br/>
180   <code>rna-helices</code>,
181   <br/>
182   <code>t-coffee-scores</code>,
183   <br/>
184   <code>sequence-id</code>
185   </p>
186
187   <h3><a name="wrap"></a><code>--wrap</code></h3>
188   <p>
189   An alignment should open with your usual preferences stored in the <code>.jalview_properties</code> file.  To open an alignment with the sequences (definitely) wrapped, following your <code>--open</code> (or first <code>--append</code>) argument use the argument <code>--wrap</code>:
190   <pre>
191   jalview --open examples/uniref50.fa --wrap
192   </pre>
193   To ensure an alignment is not wrapped use <code>--nowrap</code>:
194   <pre>
195   jalview --open examples/uniref50.fa --nowrap
196   </pre>
197   </p>
198
199   <h3><a name="showannotations"></a><code>--showannotations</code> / <code>--noshowannotations</code></h3>
200
201   <p>
202   You can specify whether the currently opened alignment window should show alignment annotations (e.g. Conservation, Quality, Consensus...) or not with either <code>--showannotations</code> or <code>--noshowannotations</code>.  If you don't specify then your saved preference will be used.
203   <pre>
204   jalview --open examples/uniref50.fa --noshowannotations
205   </pre>
206   </p>
207
208   <h3><a name="title"></a><code>--title</code></h3>
209
210   <p>
211   If you would like to give the alignment window a specific title you can do so with the <code>--title</code> option:
212   <pre>
213   jalview --open examples/uniref50.fa --title "My example alignment"
214   </pre>
215   </p>
216
217
218
219
220   <h2><a name="adding3dstructures"></a>Adding 3D structures (<code>--structure</code>, <code>--seqid</code>, <code>--structureviewer</code>, <code>--paematrix</code>, <code>--tempfac</code>, <code>--showssannotations</code>)</h2>
221
222   <p>
223   </p>
224
225   <h3><a name="structure"></a><code>--structure</code></h3>
226
227   <p>
228   You can add a 3D structure file to a sequence in the current alignment window with the <code>--structure</code> option:
229   <pre>
230   jalview --open examples/uniref50.fa --structure examples/AlphaFold/AF-P00221-F1-model_v4.pdb
231   </pre>
232   By default this attaches to the first sequence in the alignment but most likely you will want to attach it to a specific sequence.
233   </p>
234
235   <h3><a name="seqid"></a><code>--seqid</code></h3>
236
237   <p>
238   The easiest way to specify a sequence ID for your structure is to follow the <code>--structure</code> argument with a <code>--seqid</code> argument with a value of a sequence ID in the alignment.  This does of course require some knowledge of the sequences in the alignment files
239   that have been opened.
240   <br/>
241   Alternatively you can specify a <em>sub-value</em> with the <code>--structure</code> argument value.  You do this by preceding the value with square brackets and <code>seqid=SequenceId</code>,
242   like this:
243   <pre>
244   jalview --open examples/uniref50.fa --structure [seqid=FER1_SPIOL]examples/AlphaFold/AF-P00221-F1-model_v4.pdb
245   </pre>
246   which is equivalent to
247   <pre>
248   jalview --open examples/uniref50.fa --structure examples/AlphaFold/AF-P00221-F1-model_v4.pdb --seqid FER1_SPIOL
249   </pre>
250   </p>
251
252   <p>
253   The sub-value <code>seqid=FER1_SPIOL</code> takes precedence over the following argument <code>--seqid FER1_SPIOL</code> if you accidentally specify both (in which case the argument will probably be completely unused).
254   </p>
255
256   <p>
257   If you don't know the sequence IDs but do know the position of the sequence in the alignment, you can also specify an <em>INDEX</em>
258   in the sub-values to indicate which sequence in the alignment to attach the sequence to (although this is less precise).  This is a zero-indexed value, so to specify the eighth sequence in the alignment use:
259   <pre>
260   jalview --open examples/uniref50.fa --structure [7]examples/AlphaFold/AF-P00221-F1-model_v4.pdb
261   </pre>
262
263   <p>
264   Remember that you might need to escape any spaces in the sequence ID or enclose the ID in quotation marks.
265   </p>
266
267   <h3><a name="structureviewer"></a><code>--structureviewer</code></h3>
268
269   <p>
270   You can specify which structure viewer (or none) to use to open the structure using either the <code>--structureviewer</code> argument or the <code>structureviewer</code> sub-value.  Multiple sub-values can be specified together, separated by a comma ','.  Possible values for the <code>structureviewer</code> are:
271   <br/>
272   <code>none</code>,
273   <br/>
274   <code>jmol</code>,
275   <br/>
276   <code>chimera</code>,
277   <br/>
278   <code>chimerax</code>,
279   <br/>
280   <code>pymol</code>.
281   </p>
282   <p>
283   <code>none</code> and <code>jmol</code> will always be available, but to use the others you must have the appropriate software already set up on your computer and in Jalview.  See the page <a href="../features/viewingpdbs.html">Discovering and Viewing PDB and 3D-Beacons structures</a> for more details.
284   <pre>
285   jalview --open examples/uniref50.fa --structure [seqid=FER1_SPIOL,structureviewer=none]examples/AlphaFold/AF-P00221-F1-model_v4.pdb
286   </pre>
287   or, if you prefer
288   <pre>
289   jalview --open examples/uniref50.fa --structure examples/AlphaFold/AF-P00221-F1-model_v4.pdb --seqid FER1_SPIOL --structureviewer none
290   </pre>
291   </p>
292
293   <h3><a name="paematrix"></a><code>--paematrix</code></h3>
294
295   <p>
296   If you are opening a structure file that has a PAE matrix (provided as a JSON file), such as from an AlphaFold model or an nf-core pipeline, you can add the PAE matrix as an annotation by following the <code>--structure</code> argument with a <code>--paematrix</code> argument with the filename.  You can also specify a <code>paematrix=filename</code> sub-value.
297   <pre>
298   jalview --open examples/uniref50.fa --structure [seqid=FER1+SPIOL,structureviewer=pymol]examples/AlphaFold/AF-P00221-F1-model_v4.pdb --paematrix examples/AlphaFold/AF-P00221-F1-predicted_aligned_error_v4.json
299   </pre>
300   </p>
301
302   <h3><a name="tempfac"></a><code>--tempfac</code></h3>
303
304   <p>
305   Structure files may have a temperature factor associated with the structure component positions.  If the temperature factor is a pLDDT confidence score, such as with an AlphaFold model, you can specify this by using a following argument of <code>--tempfac</code> with a value of <code>plddt</code>.  This will enable standard pLDDT colouring of the temperature factor annotation.  Valid values are:
306   <code>default</code>,
307   <code>plddt</code>.
308   More types of temperature factor may be added in future releases of Jalview.
309   <br/>
310   The value can also be specified as a sub-value:
311   <pre>
312   jalview --open examples/uniref50.fa --structure [seqid=FER1+SPIOL,structureviewer=jmol,tempfac=plddt]examples/AlphaFold/AF-P00221-F1-model_v4.pdb
313   </pre>
314   which is equivalent to
315   <pre>
316   jalview --open examples/uniref50.fa --structure examples/AlphaFold/AF-P00221-F1-model_v4.pdb --tempfac plddt --seqid FER1+SPIOL
317    --structureviewer jmol
318   </pre>
319
320   </p>
321
322   <!-- notempfac not yet working. undocumented until then -->
323
324   <h3><a name="showssannotations"></a><code>--showssannotations</code> / <code>--noshowssannotations</code></h3>
325
326   <p>
327   You can specify whether the currently opened alignment window should show secondary structure annotations or not with either <code>--showssannotations</code> or <code>--noshowssannotations</code>.  If you don't specify then your saved preference will be used.
328   <pre>
329   jalview --open examples/uniref50.fa --structure examples/AlphaFold/AF-P00221-F1-model_v4.pdb --noshowssannotations
330   </pre>
331   or you can use a sub-value modifier:
332   <pre>
333   jalview --open examples/uniref50.fa --structure [noshowssannotations]examples/AlphaFold/AF-P00221-F1-model_v4.pdb
334   </pre>
335   </p>
336
337   <h2><a name="outputtingalignmentfiles"></a>Outputting/converting alignment files and images (<code>--output</code>, <code>--format</code>, <code>--image</code>, <code>--type</code>, <code>--textrenderer</code>, <code>--scale</code>, <code>--backups</code>, <code>--overwrite</code>)</h2>
338
339   <p>
340   You can save an alignment as an alignment file, or exported as an image, in different formats.  Jalview's alignment output formats are:
341   fasta,
342   pfam,
343   stockholm,
344   pir,
345   blc,
346   amsa,
347   json,
348   pileup,
349   msf,
350   clustal,
351   phylip,
352   jalview.
353   </p>
354   <p>
355   Alignments can be exported as an image in formats EPS, SVG, HTML, BioJSON (vector formats) or PNG (bitmap format).
356   </p>
357   <p>
358   In vector formats you can specify whether text should be rendered as text (which may have font changes, but will produce a smaller and more usable file) or as lineart (which will retain exact appearance of text, but will be less easy to edit or use to copy text).
359   </p>
360   <p>
361   In bitmap formats (currently only PNG, but what else would you want?!) you can specify a scaling factor to improve the resolution of the output image.
362   </p>
363
364   <h3><a name="output"></a><code>--output</code></h3>
365
366   <p>
367   To save the open alignment in a new alignment file use <code>--output filename</code>.  The format for the file can be found from the extension of <code>filename</code>, or if you are using a non-standard extension you can use a following <code>--format</code> argument, or specify it as a sub-value modifier.
368   </p>
369   <p>
370   Recognised formats and their recognised extensions are:
371   <br/>
372   <code>fasta</code> (<code>fa, fasta, mfa, fastq</code>),
373   <br/>
374   <code>pfam</code> (<code>pfam</code>),
375   <br/>
376   <code>stockholm</code> (<code>sto, stk</code>),
377   <br/>
378   <code>pir</code> (<code>pir</code>),
379   <br/>
380   <code>blc</code> (<code>blc</code>),
381   <br/>
382   <code>amsa</code> (<code>amsa</code>),
383   <br/>
384   <code>json</code> (<code>json</code>),
385   <br/>
386   <code>pileup</code> (<code>pileup</code>),
387   <br/>
388   <code>msf</code> (<code>msf</code>),
389   <br/>
390   <code>clustal</code> (<code>aln</code>),
391   <br/>
392   <code>phylip</code> (<code>phy</code>),
393   <br/>
394   <code>jalview</code> (<code>jvp, jar</code>).
395   <p>
396   For example, to open a FASTA file, append another FASTA file and then save the concatenation as a Stockholm file, do
397   <pre>
398   jalview --open alignment1.fa --append alignment2.fa --output bothalignments.stk
399   </pre>
400   or
401   <pre>
402   jalview --append alignment*.fa --output bigballofstring.txt --format stockholm
403   </pre>
404   or
405   <pre>
406   jalview --append alignment*.fa --output [format=stockholm]bigballofstring.txt
407   </pre>
408   </p>
409
410   <h3><a name="format"></a><code>--format</code></h3>
411
412   <p>
413   To specify the format of the output file (if using an unrecognised file extension) use the <code>--format</code> argument to specify a value (see above).  A sub-value modifier on the <code>--output</code> value can also be used.
414   </p>
415
416   <h3><a name="image"></a><code>--image</code></h3>
417   To export the open alignment window as an image, use the <code>--image</code> argument, which will give an image of the alignment and annotations as it appears (or would appear if not in <code>--headless</code> mode) in the alignment window if it was large enough for the whole alignment, including colour choice and features.
418   <p>
419   <pre>
420   jalview --open examples/plantfdx.fa --colour gecos-blossom --features examples/plantfdx.features --annotations examples/plantfdx.annotations --image plantfdx.png --headless
421   </pre>
422   </p>
423
424   <p>
425   This by default produces a PNG image of screen or webpage resolution, which you may want to improve upon.  There are two ways of doing this with Jalview: increasing the scale of the PNG image, or using a vector based image format (EPS, SVG, HTML).
426   <p>
427
428   <h3><a name="bitmap"></a>Bitmap image types (<code>png</code>)</h3>
429
430   <p>
431   Bitmap images are composed of an array of pixels.  Bitmap images with a low resolution that are blown up to a larger size appear "blocky", so it is important to get the resolution for your purpose correct.  Older screens only require a modest resolution, whilst newer HiDPI screens look better with a higher resolution.  For print you will want an even higher resolution although in this case you would probably want to use a vector image format.  In general creating a bitmap image that has a large resolution means you can scale the image down if needed, although if you are running a batch process this will take more time and resources.
432   </p>
433   <p>
434   Jalview only produces a PNG bitmap image type.  This is a high-colour lossless format which can also use lossless compression so is suitable for alignment figures.
435   </p>
436   <p>
437   Let's increase the resolution of the PNG image:
438   </p>
439
440   <h3><a name="scale"></a><code>--scale</code></h3>
441
442   <p>
443   We can increase the size of the PNG image by a factor of <em>S</em> by following the <code>--image</code> argument with a <code>--scale <em>S</em></code> argument and value.  The value doesn't have to be an integer and should be given as an integer or floating point formatted number, e.g.
444   <pre>
445   jalview --open examples/uniref50.fa --colour gecos-ocean --image mypic.png --scale 5.5 --headless
446   </pre>
447   which will produce a PNG image 5.5 times larger (and more detailed) than without the <code>--scale</code> argument.
448   </p>
449   <p>
450   However, since you won't necessarily already know the size of an alignment's exported image you can specify either an exact width or height (in pixels) with either one of the
451   <code>--width</code> and <code>--height</code> arguments:
452
453   <h3><a name="width"></a><code>--width</code></h3>
454
455   <p>
456   Specify an exact width of an exported PNG image with <code>--width</code>:
457   <pre>
458   jalview --headless --open https://www.ebi.ac.uk/interpro/api/entry/pfam/PF03760/?annotation=alignment%3Aseed --noshowannotations --colour gecos-sunset --image wallpaper.png --width 3840
459   </pre>
460   </p>
461
462   <h3><a name="height"></a><code>--height</code></h3>
463
464   <p>
465   Alternatively specify an exact height with the <code>--height</code> argument:
466   <pre>
467   jalview --headless --open https://www.ebi.ac.uk/interpro/api/entry/pfam/PF03760/?annotation=alignment%3Aseed --noshowannotations --colour gecos-ocean --image wallpaper.png --height 2160
468   </pre>
469   </p>
470
471   <p>
472   You can specify two or all of <code>--scale</code>, <code>--width</code> and <code>--height</code> as limits to the size of the image (think of one or two bounding boxes) and the one which produces the smallest scale of image is used.  You can also specify each of these as sub-value modifiers to the <code>--image</code> value:
473   <pre>
474   jalview --headless --open https://www.ebi.ac.uk/interpro/api/entry/pfam/PF03760/?annotation=alignment%3Aseed --noshowannotations --colour gecos-flower --image [scale=0.25,width=320,height=240]thumbnail.png
475   </pre>
476   </p>
477
478   <p>
479   Next we look at vector image formats, which maintain detail at all resolutions.
480   </p>
481
482   <h3><a name="vector"></a>Vector image export</h3>
483
484   <p>
485   Jalview can export an alignment in Encapsulated PostScript (<code>eps</code>), Scalable Vector Graphics (<code>svg</code>), HTML (<code>html</code>) or BioJSON -- another HTML format (<code>biojs</code>), by using, e.g.
486   <pre>
487   jalview --open examples/uniref50.fa --colour gecos-flower --image printable.eps
488   </pre>
489   The image format can be specified with the <code>--type</code> argument or as a sub-value modifier on the <code>--image</code> value.  If neither is used the <code>type</code> will be guessed from the image file extension.  The following three examples should produce the same contents:
490   <pre>
491   jalview --open examples/uniref50.fa --colour gecos-flower --image printable.eps
492   jalview --open examples/uniref50.fa --colour gecos-flower --image printable.postscript --type eps
493   jalview --open examples/uniref50.fa --colour gecos-flower --image [type=eps]printable.postscript
494   </pre>
495   </p>
496
497   <h3><a name="textrenderer"></a><code>--textrenderer</code></h3>
498
499   <p>
500   In a vector format any text that appears on the page (including residue/base labels) can be saved in the image file either as <code>text</code> or as <code>lineart</code> using the <code>--textrenderer</code> argument.  This is only available for <code>eps</code>, <code>svg</code> and <code>html</code> formats.
501   </p>
502
503   <p>
504   The difference is potentially in the appearance of the file, and definitely in the filesize!  Saving with <code>text</code> requires the font used to display the text characters in the alignment to be present on the viewing platform to look exactly the same.  If it isn't then another suitable font will probably be used.  The filesize using <code>text</code> is relatively small.
505   </p>
506   <p>
507   When using <code>lineart</code> each individual character that appears in the alignment (including names/titles and resisdues/bases) is stored in the image with its own vector lines.  This means that the appearance of the text is retained exactly independent of installed fonts, but the filesize is increased.  You will also be unable to copy what appears to be text as text.
508   </p>
509
510   <p>
511   The type of <code>--textrenderer</code> can be specified with an argument following <code>--image</code> or as a sub-value modifier:
512   <pre>
513   jalview --open examples/uniref50.fa --colour gecos-flower --image printable.html --type biojs
514   jalview --open examples/uniref50.fa --colour gecos-flower --image [type=eps,textrenderer=lineart]printable.ps
515   </pre>
516   </p>
517
518
519   <h2><a name="filenamesubstitutionsandbatchprocessing"></a>Filename substitutions and batch processing (<code>--substitutions</code>, <code>--new</code>, <code>--close</code>, <code>--all</code>)</h2>
520
521   <h3><a name=""></a><code>--</code></h3>
522
523   <p>
524   <pre>
525   </pre>
526   </p>
527
528   <h3><a name=""></a><code>--</code></h3>
529
530   <p>
531   <pre>
532   </pre>
533   </p>
534
535   <h3><a name=""></a><code>--</code></h3>
536
537   <p>
538   <pre>
539   </pre>
540   </p>
541
542   <h3><a name=""></a><code>--</code></h3>
543
544   <p>
545   <pre>
546   </pre>
547   </p>
548
549   <h3><a name=""></a><code>--</code></h3>
550
551   <p>
552   <pre>
553   </pre>
554   </p>
555
556   Continue to <a href="clarguments-advanced.html">Jalview Command Line Arguments: advanced usage</a>.
557
558
559
560 </body>
561 </html>