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
 418   <p>
 419   <pre>
 420   </pre>
 421   </p>
 422
 423   <h3><a name=""></a><code>--</code></h3>
 424
 425   <p>
 426   <pre>
 427   </pre>
 428   </p>
 429
 430   <h3><a name=""></a><code>--</code></h3>
 431
 432   <p>
 433   <pre>
 434   </pre>
 435   </p>
 436
 437   <h3><a name=""></a><code>--</code></h3>
 438
 439   <p>
 440   <pre>
 441   </pre>
 442   </p>
 443
 444
 445   <h2><a name="filenamesubstitutionsandbatchprocessing"></a>Filename substitutions and batch processing (<code>--substitutions</code>, <code>--new</code>, <code>--close</code>, <code>--all</code>)</h2>
 446
 447   <h3><a name=""></a><code>--</code></h3>
 448
 449   <p>
 450   <pre>
 451   </pre>
 452   </p>
 453
 454   <h3><a name=""></a><code>--</code></h3>
 455
 456   <p>
 457   <pre>
 458   </pre>
 459   </p>
 460
 461   <h3><a name=""></a><code>--</code></h3>
 462
 463   <p>
 464   <pre>
 465   </pre>
 466   </p>
 467
 468   <h3><a name=""></a><code>--</code></h3>
 469
 470   <p>
 471   <pre>
 472   </pre>
 473   </p>
 474
 475   <h3><a name=""></a><code>--</code></h3>
 476
 477   <p>
 478   <pre>
 479   </pre>
 480   </p>
 481
 482   Continue to <a href="clarguments-advanced.html">Jalview Command Line Arguments: advanced usage</a>.
 483
 484
 485
 486 </body>
 487 </html>