3 * Jalview is distributed in the hope that it will be useful, but
4 * WITHOUT ANY WARRANTY; without even the implied warranty
5 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
6 * PURPOSE. See the GNU General Public License for more details.
8 * You should have received a copy of the GNU General Public License
9 * along with Jalview. If not, see <http://www.gnu.org/licenses/>.
10 * The Jalview Authors are detailed in the 'AUTHORS' file.
12 <title>Command Line: reference</title>
15 <h1>Command Line: reference</h1>
18 <a href="clarguments.html">Command Line: introduction</a>
20 <a href="clarguments-basic.html">Command Line: basic usage</a>
22 <a href="clarguments-advanced.html">Command Line: advanced usage</a>
24 <a href="clarguments-argfiles.html">Command Line: argument files</a>
26 Command Line: reference
32 <li><a href="#initialisingarguments">Initialising arguments</a></li>
33 <li><a href="#openinganalignment">Opening an alignment</a></li>
34 <li><a href="#adding3dstructure">Adding 3D structure</a></li>
35 <li><a href="#processingalignments">Processing alignments</a></li>
36 <li><a href="#outputtingalignmentfiles">Outputting alignment files</a></li>
37 <li><a href="#exportingimagefiles">Exporting image files</a></li>
38 <li><a href="#controllingflowofarguments">Controlling flow of arguments</a></li>
42 <h2><a name="initialisingarguments"></a>Initialising arguments</h2>
44 <table border="1" cellpadding="3">
46 <td><strong>argument</strong></td>
47 <td><strong>action</strong></td>
51 <td><code>‑‑help / -h</code>
53 <td>Display a help statement.</td>
56 <tr valign="top"><td><code>‑‑help‑config</code></td><td>Help for arguments used to configure Jalview from startup</td></tr>
57 <tr valign="top"><td><code>‑‑help‑opening</code></td><td>Help for arguments used to open and format alignments</td></tr>
58 <tr valign="top"><td><code>‑‑help‑structure</code></td><td>Help for arguments used to add and format 3D structure data</td></tr>
59 <tr valign="top"><td><code>‑‑help‑process</code></td><td>Help for arguments used to process an alignment once opened</td></tr>
60 <tr valign="top"><td><code>‑‑help‑output</code></td><td>Help for arguments used to save data from a processed alignment</td></tr>
61 <tr valign="top"><td><code>‑‑help‑image</code></td><td>Help for arguments used to export an image of an alignment</td></tr>
62 <tr valign="top"><td><code>‑‑help‑structureimage</code></td><td>Help for arguments used to export an image of an structure</td></tr>
63 <tr valign="top"><td><code>‑‑help‑flow</code></td><td>Help for arguments that control processing of the other arguments</td></tr>
64 <tr valign="top"><td><code>‑‑help‑all</code></td><td>Help for all arguments</td></tr>
67 <td><code>‑‑headless</code></td>
68 <td>Run Jalview in headless mode. In headless mode, no GUI interface will be created and Jalview will quit after all arguments have been processed.
70 If you use a command line argument to specify an output file of some kind (<code>‑‑output</code>, <code>‑‑image</code> or <code>‑‑structureimage</code>) then <strong>headless mode will be assumed</strong>. If you don't want this behaviour use <code>‑‑gui</code>.
75 <td><code>‑‑gui</code></td>
76 <td>Force Jalview to run in graphical mode. This can be used to counter the assumption of headless mode when an argument that creates an output file is used. <code>‑‑gui</code> takes precedence over <code>‑‑headless</code>.</td>
80 <td><code>‑‑jabaws <em>URL</em></code></td>
81 <td>Set a different URL to connect to a JABAWS server.</td>
85 <td><code>‑‑news / ‑‑nonews</code></td>
86 <td>Show (/ or don't show) the news feed.</td>
90 <td><code>‑‑splash / ‑‑nosplash</code></td>
91 <td>Show (/ or don't show) the About Jalview splash screen.</td>
95 <td><code>‑‑javaconsole / ‑‑nojavaconsole</code></td>
96 <td>Show (/ or don't show) the Java Console. Using one of these overrides any saved Preference.</td>
100 <td><code>‑‑questionnaire / ‑‑noquestionnaire</code></td>
101 <td>Show (/ or don't show) the questionnaire if one is available.</td>
105 <td><code>‑‑nousagestats</code></td>
106 <td>Don't send usage stats via Google analytics for this session. <em>Note: usage stats are useful for future funding for Jalview!</em></td>
110 <td><code>‑‑nostartupfile</code></td>
111 <td>Don't show the default startup file.</td>
115 <td><code>‑‑webservicediscovery / ‑‑nowebservicediscovery</code></td>
116 <td>Attempt (/ or don't attempt) to connect to JABAWS web services.</td>
120 <td><code>‑‑props <em>filename</em></code></td>
121 <td>Use file <em>filename</em> as the preferences file <em>instead</em> of the usual <code>~/.jalview_properties</code> file.</td>
125 <td><code>‑‑debug</code></td>
126 <td>Start Jalview in debug log level.</td>
130 <td><code>‑‑quiet</code></td>
131 <td>Stop all output to STDOUT (after the Java Virtual Machine has started). Use <code>‑‑quiet</code> a second time to stop all output to STDERR.</td>
136 <td><code>‑‑P<em>PREFERENCE=VALUE</em></code></td>
137 <td>Set a Jalview preference for this session only. Experimental.</td>
143 <td><code>‑‑initsubstitutions / ‑‑noinitsubstitutions</code></td>
144 <td>Set <code>‑‑substitutions</code> to be initially enabled (or initially disabled).</td>
150 <td><code>‑‑threads <em>NUMBER</em></code></td>
151 <td>When opening multiple alignment windows, set a limit of <em>NUMBER</em> alignments being processed at one time. The default is 3.</td>
157 <td><code>‑‑jvmmempc=<em>PERCENT</em></code></td>
159 Limit maximum heap size (memory) to <em>PERCENT</em>% of total physical memory detected.
160 This defaults to 90 if total physical memory can be detected.
162 The equals sign ("=") separator must be used with no spaces.
164 See <a href="../memory.html">Memory usage settings for Jalview</a> for more details.
169 <td><code>‑‑jvmmemmax=<em>MAXMEMORY</em></code></td>
171 Limit maximum heap size (memory) to <em>MAXMEMORY</em>. <em>MAXMEMORY</em> can be specified in bytes, kilobytes(k), megabytes(m),
172 gigabytes(g) or if you're lucky enough, terabytes(t).
173 This defaults to 32g if total physical memory can be detected, or to 8g if total physical memory cannot be detected.
175 The equals sign ("=") separator must be used with no spaces.
177 See <a href="../memory.html">Memory usage settings for Jalview</a> for more details.
184 <h2><a name="openinganalignment"></a>Opening an alignment</h2>
186 <table border="1" cellpadding="3">
188 <td><strong>argument</strong></td>
189 <td><strong>action</strong></td>
190 <td><strong>sub-value modifiers</strong> (optional)</td>
191 <td><strong>linked</strong> (optional)</td>
195 <td><code>‑‑open <em>filename/URL ...</em></code></td>
197 Opens one or more alignment files <em>filename</em> or URLs <em>URL</em> in new alignment windows.
201 colour=<em>name</em>,
203 title=<em>string</em>,
205 features=<em>filename</em>,
207 annotations=<em>filename</em>,
209 tree=<em>filename</em>,
220 <td align="center">✓</td>
224 <td><code>‑‑append <em>filename/URL ...</em></code></td>
225 <td>Appends one or more alignment files <em>filename</em> or URLs <em>URL</em> to the open alignment window (or opens a new alignment if none already open).</td>
228 colour=<em>name</em>,
230 title=<em>string</em>,
232 features=<em>filename</em>,
234 annotations=<em>filename</em>,
236 tree=<em>filename</em>,
247 <td align="center">✓</td>
251 <td><code>‑‑title <em>"string"</em></code></td>
252 <td>Specifies the title for the open alignment window as <em>string</em>.</td>
254 <td align="center">✓</td>
258 <td><code>‑‑colour <em>name</em></code></td>
259 <td>Applies the colour scheme <em>name</em> to the open alignment window. Valid values for <em>name</em> include:
261 <code>clustal</code>,
263 <code>blosum62</code>,
265 <code>pc-identity</code>,
271 <code>gecos-flower</code>,
273 <code>gecos-blossom</code>,
275 <code>gecos-sunset</code>,
277 <code>gecos-ocean</code>,
279 <code>hydrophobic</code>,
281 <code>helix-propensity</code>,
283 <code>strand-propensity</code>,
285 <code>turn-propensity</code>,
287 <code>buried-index</code>,
289 <code>nucleotide</code>,
291 <code>nucleotide-ambiguity</code>,
293 <code>purine-pyrimidine</code>,
295 <code>rna-helices</code>,
297 <code>t-coffee-scores</code>,
299 <code>sequence-id</code>.
302 Names of user defined schemes will also work, and jalview colour scheme specifications like:
304 <code>‑‑colour "D,E=red; K,R,H=0022FF; C,c=yellow"</code>
306 <td align="center">✓</td>
310 <td><code>‑‑features <em>filename/URL</em></code></td>
311 <td>Add a feature file <em>filename</em> or URL <em>URL</em> to the open alignment.</td>
313 <td align="center">✓</td>
319 <td><code>‑‑tree <em>filename/URL</em></code></td>
320 <td>Add a tree file <em>filename</em> or URL <em>URL</em> to the open alignment.</td>
322 <td align="center">✓</td>
326 <td><code>‑‑sortbytree / ‑‑nosortbytree</code></td>
327 <td>Enforces sorting (or not sorting) the alignment in the order of an attached phylogenetic tree.</td>
329 <td align="center">✓</td>
334 <td><code>‑‑annotations <em>filename/URL</em></code></td>
335 <td>Add an annotations file <em>filename</em> or URL <em>URL</em> to the open alignment.</td>
337 <td align="center">✓</td>
341 <td><code>‑‑showannotations / ‑‑noshowannotations</code></td>
342 <td>Enforces showing (or not showing) alignment annotations.</td>
344 <td align="center">✓</td>
348 <td><code>‑‑wrap / ‑‑nowrap</code></td>
349 <td>Enforces wrapped (or not wrapped) alignment formatting.</td>
351 <td align="center">✓</td>
355 <td><code>‑‑nostructure</code></td>
356 <td>Do not open or process any 3D structure in the <code>‑‑open</code> or <code>‑‑append</code> files.</td>
358 <td align="center">✓</td>
364 <h2><a name="adding3dstructure"></a>Adding 3D structure</h2>
366 <table border="1" cellpadding="3">
368 <td><strong>argument</strong></td>
369 <td><strong>action</strong></td>
370 <td><strong>sub-value modifiers</strong> (optional)</td>
371 <td><strong>linked</strong> (optional)</td>
375 <td><code>‑‑structure <em>filename/URL</em></code></td>
376 <td>Load a structure file <em>filename</em> or URL <em>URL</em> associated with a sequence in the open alignment. The sequence to be associated with can be specified with a following <code>‑‑seqid</code> argument, or the sub-value modifier <code>seqid=<em>ID</em></code> can be used. A sub-value <em>INDEX</em> can also be used to specify the <em>INDEX-th</em> sequence in the open alignment.</td>
379 seqid=<em>id</em></code> or <code><em>INDEX</em>,
381 paefile=<em>filename</em>,
383 tempfac=<em>name</em>,
391 structureviewer=<em>name</em>
393 <td align="center">✓</td>
398 <td><code>‑‑seqid <em>ID</em></code></td>
399 <td>Specify the sequence name for the preceding <code>‑‑structure</code> to be associated with.</td>
401 <td align="center">✓</td>
406 <td><code>‑‑paematrix <em>filename</em></code></td>
407 <td>Add a PAE json matrix file <em>filename</em> to the preceding <code>‑‑structure</code>.</td>
409 <td align="center">✓</td>
414 <td><code>‑‑tempfac <em>name</em></code></td>
415 <td>Set the type of temperature factor. Valid values for <em>name</em> are:
417 <code>default</code>,
422 <td align="center">✓</td>
427 <td><code>‑‑structureviewer <em>name</em></code></td>
428 <td>Set the structure viewer to use to open the 3d structure file specified in previous <code>‑‑structure</code> to <em>name</em>. Valid values of <em>name</em> are:
434 <code>chimera</code> <em>- requires installation, might need configuring in Preferences</em>,
436 <code>chimerax</code> <em>- requires installation, might need configuring in Preferences</em>,
438 <code>pymol</code> <em>- requires installation, might need configuring in Preferences</em>
441 <td align="center">✓</td>
447 <td><code>‑‑notempfac</code></td>
448 <td>Do not show the temperature factor annotation for the preceding <code>‑‑structure</code></td>
450 <td align="center">✓</td>
456 <td><code>‑‑showssannotations / ‑‑noshowssannotations</code></td>
457 <td>Do not show secondary structure annotations for the preceding <code>‑‑structure</code></td>
459 <td align="center">✓</td>
463 <td><code>‑‑close</code></td>
464 <td>Close the open alignment window. This occurs after other output, processing and image export arguments. This applies to the current open alignment -- to apply to all <code>‑‑output</code> and <code>‑‑image</code> files, use after <code>‑‑all</code>.</td>
466 <td align="center">✓</td>
472 <h2><a name="processingalignments"></a>Processing alignments</h2>
474 <table border="1" cellpadding="3">
476 <td><strong>argument</strong></td>
477 <td><strong>action</strong></td>
478 <td><strong>sub-value modifiers</strong> (optional)</td>
479 <td><strong>linked</strong> (optional)</td>
483 <td><code>‑‑groovy <em>filename</em></code></td>
484 <td>Process a groovy script in the file for the open alignment.</td>
486 <td align="center">✓</td>
491 <h2><a name="outputtingalignmentfiles"></a>Outputting alignment files</h2>
493 <table border="1" cellpadding="3">
495 <td><strong>argument</strong></td>
496 <td><strong>action</strong></td>
497 <td><strong>sub-value modifiers</strong> (optional)</td>
498 <td><strong>linked</strong> (optional)</td>
502 <td><code>‑‑output <em>filename</em></code></td>
503 <td>Export the open alignment to file <em>filename</em>. The format <em>name</em> is specified by the sub-value modifier <code>format=<em>name</em></code>, a following <code>‑‑format <em>name</em></code> argument or guessed from the file extension. Valid format names (and file extensions) are:
505 <code>fasta</code> (<code>fa, fasta, mfa, fastq</code>),
507 <code>pfam</code> (<code>pfam</code>),
509 <code>stockholm</code> (<code>sto, stk</code>),
511 <code>pir</code> (<code>pir</code>),
513 <code>blc</code> (<code>blc</code>),
515 <code>amsa</code> (<code>amsa</code>),
517 <code>json</code> (<code>json</code>),
519 <code>pileup</code> (<code>pileup</code>),
521 <code>msf</code> (<code>msf</code>),
523 <code>clustal</code> (<code>aln</code>),
525 <code>phylip</code> (<code>phy</code>),
527 <code>jalview</code> (<code>jvp, jar</code>).
529 To output directly to STDOUT (console output) use the filename <code>-</code> (a single hyphen). In this case all STDOUT messages will instead go to STDERR. If no <code>format</code> is supplied then Fasta will be assumed.
531 <td><code>format=<em>name</em></code></td>
532 <td align="center">✓</td>
536 <td><code>‑‑format <em>name</em></code></td>
537 <td>Sets the format for the preceding <code>‑‑output</code> file. Valid formats are:
543 <code>stockholm</code>,
557 <code>clustal</code>,
561 <code>jalview</code>.
564 <td align="center">✓</td>
568 <td><code>‑‑backups / ‑‑nobackups</code></td>
569 <td>Enable (or disable) writing backup files when saving an <code>‑‑output</code> file. This applies to the current open alignment -- to apply to all <code>‑‑output</code> and <code>‑‑image</code> files, use after <code>‑‑all</code>.</td>
571 <td align="center">✓</td>
575 <td><code>‑‑overwrite / ‑‑nooverwrite</code></td>
576 <td>Enable (or disable) overwriting of output files without backups enabled. This applies to the current open alignment -- to apply to all <code>‑‑output</code> and <code>‑‑image</code> files, use after <code>‑‑all</code>.</td>
578 <td align="center">✓</td>
582 <td><code>‑‑mkdirs</code></td>
583 <td>Enable automatic creation of new directories and parent directories for filenames given, or created through substitutions, in <code>‑‑output</code>, <code>‑‑image</code> or <code>‑‑structureimage</code> arguments.
585 <td align="center">✓</td>
590 Automatically create directories when outputting a file to a new directory
594 <h2><a name="exportingimagefiles"></a>Exporting image files</h2>
596 <table border="1" cellpadding="3">
598 <td><strong>argument</strong></td>
599 <td><strong>action</strong></td>
600 <td><strong>sub-value modifiers</strong> (optional)</td>
601 <td><strong>linked</strong> (optional)</td>
605 <td><code>‑‑image <em>filename</em></code></td>
606 <td>Output an image of the open alignment window. Format is specified by the sub-value modifier, a following <code>‑‑type</code> argument or guessed from the file extension. Valid formats/extensions are:
622 textrenderer=<em>name</em>,
624 scale=<em>number</em>,
626 width=<em>number</em>,
628 height=<em>number</em>,
630 imagecolour=<em>name</em>
633 <td align="center">✓</td>
637 <td><code>‑‑structureimage <em>filename</em></code></td>
638 <td>Export an image of a 3D structure opened in JMOL (currently jmol only). Each <code>‑‑structureimage</code> filename will output a file for each <code>‑‑structureimage</code> that has been applied to the open alignment window. In this situation, to avoid overwriting the same file with each structure, additional substitutions <code>{structuredirname}</code>, <code>{structurebasename}</code> and <code>{structureextname}</code> are available being substituted with the directory path, file basename and file extension of each structure file. Image formats can be:
650 textrenderer=<em>name</em>,
652 scale=<em>number</em>,
654 width=<em>number</em>,
656 height=<em>number</em>,
658 imagecolour=<em>name</em>
660 bgcolour=<em>name</em>
663 <td align="center">✓</td>
667 <td><code>‑‑type <em>name</em></code></td>
668 <td>Set the image format for the preceding <code>‑‑image</code> or <code>‑‑structureimage</code> to <em>name</em>. Valid values for <em>name</em> are:
681 <td align="center">✓</td>
685 <td><code>‑‑textrenderer <em>name</em></code></td>
686 <td>Sets whether text in a vector image format (SVG, HTML, EPS) should be rendered as text or vector line-art. Applies to the preceding <code>‑‑image</code> or <code>‑‑structureimage</code>. Valid values for <em>name</em> are:
690 <code>lineart</code>.
693 <td align="center">✓</td>
697 <td><code>‑‑scale <em>number</em></code></td>
698 <td>Sets a scaling for bitmap image format (PNG). Should be given as a floating point number. Applies to the preceding <code>‑‑image</code> or <code>‑‑structureimage</code>. This can also be set as a sub-value modifier to the <code>‑‑image</code> or <code>‑‑structureimage</code> value. If used in conjunction with <code>‑‑width</code> and <code>‑‑height</code> then the smallest size will be used (<code>scale</code>, <code>width</code> and <code>height</code> provide bounds for the image).
701 <td align="center">✓</td>
705 <td><code>‑‑width <em>number</em></code></td>
706 <td>Sets a width for bitmap image format (PNG) with the height maintaining the aspect ratio. Applies to the preceding <code>‑‑image</code> or <code>‑‑structureimage</code>. Should be given as a positive integer. This can also be set as a sub-value modifier to the <code>‑‑image</code> or <code>‑‑structureimage</code> value. If used in conjunction with <code>‑‑scale</code> and <code>‑‑height</code> then the smallest size will be used (<code>scale</code>, <code>width</code> and <code>height</code> provide bounds for the image).
709 <td align="center">✓</td>
713 <td><code>‑‑height <em>number</em></code></td>
714 <td>Sets a height for bitmap image format (PNG) with the width maintaining the aspect ratio. Applies to the preceding <code>‑‑image</code> or <code>‑‑structureimage</code>. Should be given as a positive integer. This can also be set as a sub-value modifier to the <code>‑‑image</code> or <code>‑‑structureimage</code> value. If used in conjunction with <code>‑‑scale</code> and <code>‑‑width</code> then the smallest size will be used (<code>scale</code>, <code>width</code> and <code>height</code> provide bounds for the image).</td>
716 <td align="center">✓</td>
720 <td><code>‑‑bgcolour <em>name</em></code></td>
721 <td>Only applies to structure images (opened with <code>jmol</code> structure viewer). Sets the background colour of the preceding <code>‑‑structureimage</code>. <em>name</em> should be either a named colour (e.g. <code>white</code>, <code>cyan</code>) known to Jmol, or can be given as a six digit RGB hex string (e.g. <code>ffffff</code>, <code>00ffff</code>). This can also be set as a sub-value modifier to the <code>‑‑structureimage</code> value.</td>
723 <td align="center">✓</td>
727 <td><code>‑‑groovy <em>filename</em></code></td>
728 <td>Process a groovy script in the file for the open alignment.</td>
730 <td align="center">✓</td>
736 <h2><a name="controllingflowofarguments"></a>Controlling flow of arguments</h2>
738 <table border="1" cellpadding="3">
740 <td><strong>argument</strong></td>
741 <td><strong>action</strong></td>
745 <td><code>‑‑new</code></td>
747 Move on to a new alignment window. This will ensure <code>‑‑append</code> will start a new alignment window and other linked arguments will apply to the new alignment window.
749 <em>Note</em> that <code>‑‑open</code> already starts a new alignment window for each file it opens.
754 <td><code>‑‑substitutions / ‑‑nosubstitutions</code></td>
755 <td>The following argument values allow (or don't allow) subsituting filename parts. This is initially true. Valid substitutions are
757 <code>{basename}</code> - the filename-without-extension of the currently <code>‑‑open</code>ed file (or first <code>‑‑append</code>ed file),
759 <code>{dirname}</code>, - the directory (folder) name of the currently <code>‑‑open</code>ed file (or first <code>‑‑append</code>ed file),
760 <code>{extension}</code>, - the extension of the filename of the currently <code>‑‑open</code>ed file (or first <code>‑‑append</code>ed file),
762 <code>{argfilebasename}</code> - the filename-without-extension of the current <code>‑‑argfile</code>,
764 <code>{argfiledirname}</code> - the directory (folder) name of the current <code>‑‑argfile</code>,
766 <code>{structurebasename}</code> - the filename-without-extension of the <code>‑‑structure</code> file. Only available to <code>‑‑structureimage</code> .
768 <code>{structuredirname}</code>, - the directory (folder) name of the <code>‑‑structure</code> file. Only available to <code>‑‑structureimage</code> .
770 <code>{structureextension}</code>, - the extension of the filename of the <code>‑‑structure</code> file. Only available to <code>‑‑structureimage</code> .
772 <code>{n}</code> - the value of the index counter (starting at 0).
774 <code>{++n}</code> - increase and substitute the value of the index counter.
776 <code>{m}</code> - the value of the on-the-fly counter (starting at 0). Only available to <code>‑‑structureimage</code> .
778 <code>{++m}</code> - increase and substitute the (incremented) value of the on-the-fly counter. Only available to <code>‑‑structureimage</code> .
780 <code>{}</code> - the value of the current alignment window <em>default</em> index.
785 <td><code>‑‑argfile <em>filename</em></code></td>
787 Open one or more files <em>filename</em> and read, line-by-line, as arguments to Jalview.
789 Values in an argfile should be given with an equals sign ("=") separator with no spaces.
791 <strong>Note</strong> that if you use one or more <code>‑‑argfile</code> arguments then all other non-initialising arguments will be ignored.
796 <td><code>‑‑npp</code></td>
797 <td>Increase the index counter used in argument value substitutions.</td>
801 <td><code>‑‑all / ‑‑noall</code></td>
802 <td>Apply (or stop applying) the following output arguments to <em>all</em> sets of linked arguments.</td>
806 <td><code>‑‑allstructures / ‑‑noallstructures</code></td>
808 Apply (or stop applying) the following 3D structure formatting arguments to all structures <em>within the current open alignment</em>. Whilst <code>‑‑allstructures</code> will continue to operate for a <code>‑‑new</code> alignment, the structure formatting arguments must be set again for each new alignment.
813 <td><code>‑‑quit</code></td>
814 <td>After all files have been opened, appended and output, quit Jalview. In <code>‑‑headless</code> mode this already happens.</td>
git://source.jalview.org / jalview.git / blob