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="#exporting3dstructureimagefiles">Exporting 3D structure image files</a></li>
39 <li><a href="#controllingflowofarguments">Controlling flow of arguments</a></li>
43 <h2><a name="initialisingarguments"></a>Initialising arguments</h2>
45 <table border="1" cellpadding="3">
47 <td><strong>argument</strong></td>
48 <td><strong>action</strong></td>
52 <td><code>‑‑help / -h</code>
54 <td>Display a help statement.</td>
57 <tr valign="top"><td><code>‑‑help‑config</code></td><td>Help for arguments used to configure Jalview from startup</td></tr>
58 <tr valign="top"><td><code>‑‑help‑opening</code></td><td>Help for arguments used to open and format alignments</td></tr>
59 <tr valign="top"><td><code>‑‑help‑structure</code></td><td>Help for arguments used to add and format 3D structure data</td></tr>
60 <tr valign="top"><td><code>‑‑help‑process</code></td><td>Help for arguments used to process an alignment once opened</td></tr>
61 <tr valign="top"><td><code>‑‑help‑output</code></td><td>Help for arguments used to save data from a processed alignment</td></tr>
62 <tr valign="top"><td><code>‑‑help‑image</code></td><td>Help for arguments used to export an image of an alignment</td></tr>
63 <tr valign="top"><td><code>‑‑help‑structureimage</code></td><td>Help for arguments used to export an image of an structure</td></tr>
64 <tr valign="top"><td><code>‑‑help‑flow</code></td><td>Help for arguments that control processing of the other arguments</td></tr>
65 <tr valign="top"><td><code>‑‑help‑all</code></td><td>Help for all arguments</td></tr>
68 <td><code>‑‑headless / ‑‑noheadless</code></td>
69 <td>Run Jalview in headless (/ or not in headless) mode. In headless mode, no GUI interface will be created and Jalview will quit after all arguments have been processed.
71 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>--noheadless</code> or <code>--gui</code>.
76 <td><code>‑‑gui</code></td>
77 <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>
81 <td><code>‑‑jabaws <em>URL</em></code></td>
82 <td>Set a different URL to connect to a JABAWS server.</td>
86 <td><code>‑‑news / ‑‑nonews</code></td>
87 <td>Show (/ or don't show) the news feed.</td>
91 <td><code>‑‑splash / ‑‑nosplash</code></td>
92 <td>Show (/ or don't show) the About Jalview splash screen.</td>
96 <td><code>‑‑questionnaire / ‑‑noquestionnaire</code></td>
97 <td>Show (/ or don't show) the questionnaire if one is available.</td>
101 <td><code>‑‑nousagestats</code></td>
102 <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>
106 <td><code>‑‑nostartupfile</code></td>
107 <td>Don't show the default startup file.</td>
111 <td><code>‑‑webservicediscovery / ‑‑nowebservicediscovery</code></td>
112 <td>Attempt (/ or don't attempt) to connect to JABAWS web services.</td>
116 <td><code>‑‑props <em>filename</em></code></td>
117 <td>Use file <em>filename</em> as the preferences file <em>instead</em> of the usual <code>~/.jalview_properties</code> file.</td>
121 <td><code>‑‑debug</code></td>
122 <td>Start Jalview in debug log level.</td>
126 <td><code>‑‑quiet</code></td>
127 <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>
132 <td><code>‑‑P<em>PREFERENCE=VALUE</em></code></td>
133 <td>Set a Jalview preference for this session only. Experimental.</td>
139 <td><code>‑‑initsubstitutions / ‑‑noinitsubstitutions</code></td>
140 <td>Set <code>‑‑substitutions</code> to be initially enabled (or initially disabled).</td>
146 <td><code>‑‑threads <em>NUMBER</em></code></td>
147 <td>When opening multiple alignment windows, set a limit of <em>NUMBER</em> alignments being processed at one time. The default is 3.</td>
153 <td><code>‑‑jvmmempc=<em>PERCENT</em></code></td>
155 Limit maximum heap size (memory) to <em>PERCENT</em>% of total physical memory detected.
156 This defaults to 90 if total physical memory can be detected.
158 The equals sign ("=") separator must be used with no spaces.
160 See <a href="../memory.html">Memory usage settings for Jalview</a> for more details.
165 <td><code>‑‑jvmmemmax=<em>MAXMEMORY</em></code></td>
167 Limit maximum heap size (memory) to <em>MAXMEMORY</em>. <em>MAXMEMORY</em> can be specified in bytes, kilobytes(k), megabytes(m),
168 gigabytes(g) or if you're lucky enough, terabytes(t).
169 This defaults to 32g if total physical memory can be detected, or to 8g if total physical memory cannot be detected.
171 The equals sign ("=") separator must be used with no spaces.
173 See <a href="../memory.html">Memory usage settings for Jalview</a> for more details.
180 <h2><a name="openinganalignment"></a>Opening an alignment</h2>
182 <table border="1" cellpadding="3">
184 <td><strong>argument</strong></td>
185 <td><strong>action</strong></td>
186 <td><strong>sub-value modifiers</strong> (optional)</td>
187 <td><strong>linked</strong> (optional)</td>
191 <td><code>‑‑open <em>filename/URL ...</em></code></td>
193 Opens one or more alignment files <em>filename</em> or URLs <em>URL</em> in new alignment windows.
197 colour=<em>name</em>,
199 title=<em>string</em>,
201 features=<em>filename</em>,
203 annotations=<em>filename</em>,
205 tree=<em>filename</em>,
216 <td align="center">✓</td>
220 <td><code>‑‑append <em>filename/URL ...</em></code></td>
221 <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>
224 colour=<em>name</em>,
226 title=<em>string</em>,
228 features=<em>filename</em>,
230 annotations=<em>filename</em>,
232 tree=<em>filename</em>,
243 <td align="center">✓</td>
247 <td><code>‑‑title <em>"string"</em></code></td>
248 <td>Specifies the title for the open alignment window as <em>string</em>.</td>
250 <td align="center">✓</td>
254 <td><code>‑‑colour <em>name</em></code></td>
255 <td>Applies the colour scheme <em>name</em> to the open alignment window. Valid values for <em>name</em> include:
257 <code>clustal</code>,
259 <code>blosum62</code>,
261 <code>pc-identity</code>,
267 <code>gecos-flower</code>,
269 <code>gecos-blossom</code>,
271 <code>gecos-sunset</code>,
273 <code>gecos-ocean</code>,
275 <code>hydrophobic</code>,
277 <code>helix-propensity</code>,
279 <code>strand-propensity</code>,
281 <code>turn-propensity</code>,
283 <code>buried-index</code>,
285 <code>nucleotide</code>,
287 <code>nucleotide-ambiguity</code>,
289 <code>purine-pyrimidine</code>,
291 <code>rna-helices</code>,
293 <code>t-coffee-scores</code>,
295 <code>sequence-id</code>.
298 Names of user defined schemes will also work, and jalview colour scheme specifications like:
300 <code>‑‑colour "D,E=red; K,R,H=0022FF; C,c=yellow"</code>
302 <td align="center">✓</td>
306 <td><code>‑‑features <em>filename/URL</em></code></td>
307 <td>Add a feature file <em>filename</em> or URL <em>URL</em> to the open alignment.</td>
309 <td align="center">✓</td>
315 <td><code>‑‑tree <em>filename/URL</em></code></td>
316 <td>Add a tree file <em>filename</em> or URL <em>URL</em> to the open alignment.</td>
318 <td align="center">✓</td>
322 <td><code>‑‑sortbytree / ‑‑nosortbytree</code></td>
323 <td>Enforces sorting (or not sorting) the alignment in the order of an attached phylogenetic tree.</td>
325 <td align="center">✓</td>
330 <td><code>‑‑annotations <em>filename/URL</em></code></td>
331 <td>Add an annotations file <em>filename</em> or URL <em>URL</em> to the open alignment.</td>
333 <td align="center">✓</td>
337 <td><code>‑‑showannotations / ‑‑noshowannotations</code></td>
338 <td>Enforces showing (or not showing) alignment annotations.</td>
340 <td align="center">✓</td>
344 <td><code>‑‑wrap / ‑‑nowrap</code></td>
345 <td>Enforces wrapped (or not wrapped) alignment formatting.</td>
347 <td align="center">✓</td>
351 <td><code>‑‑nostructure</code></td>
352 <td>Do not open or process any 3D structure in the <code>‑‑open</code> or <code>‑‑append</code> files.</td>
354 <td align="center">✓</td>
360 <h2><a name="adding3dstructure"></a>Adding 3D structure</h2>
362 <table border="1" cellpadding="3">
364 <td><strong>argument</strong></td>
365 <td><strong>action</strong></td>
366 <td><strong>sub-value modifiers</strong> (optional)</td>
367 <td><strong>linked</strong> (optional)</td>
371 <td><code>‑‑structure <em>filename/URL</em></code></td>
372 <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>
375 seqid=<em>id</em></code> or <code><em>INDEX</em>,
377 paefile=<em>filename</em>,
379 tempfac=<em>name</em>,
387 structureviewer=<em>name</em>
389 <td align="center">✓</td>
394 <td><code>‑‑seqid <em>ID</em></code></td>
395 <td>Specify the sequence name for the preceding <code>‑‑structure</code> to be associated with.</td>
397 <td align="center">✓</td>
402 <td><code>‑‑paematrix <em>filename</em></code></td>
403 <td>Add a PAE json matrix file <em>filename</em> to the preceding <code>‑‑structure</code>.</td>
405 <td align="center">✓</td>
410 <td><code>‑‑tempfac <em>name</em></code></td>
411 <td>Set the type of temperature factor. Valid values for <em>name</em> are:
413 <code>default</code>,
418 <td align="center">✓</td>
423 <td><code>‑‑structureviewer <em>name</em></code></td>
424 <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:
430 <code>chimera</code> <em>- requires installation, might need configuring in Preferences</em>,
432 <code>chimerax</code> <em>- requires installation, might need configuring in Preferences</em>,
434 <code>pymol</code> <em>- requires installation, might need configuring in Preferences</em>
437 <td align="center">✓</td>
443 <td><code>‑‑notempfac</code></td>
444 <td>Do not show the temperature factor annotation for the preceding <code>‑‑structure</code></td>
446 <td align="center">✓</td>
452 <td><code>‑‑showssannotations / ‑‑noshowssannotations</code></td>
453 <td>Do not show secondary structure annotations for the preceding <code>‑‑structure</code></td>
455 <td align="center">✓</td>
459 <td><code>‑‑close</code></td>
460 <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>
462 <td align="center">✓</td>
468 <h2><a name="processingalignments"></a>Processing alignments</h2>
470 <table border="1" cellpadding="3">
472 <td><strong>argument</strong></td>
473 <td><strong>action</strong></td>
474 <td><strong>sub-value modifiers</strong> (optional)</td>
475 <td><strong>linked</strong> (optional)</td>
479 <td><code>‑‑groovy <em>filename</em></code></td>
480 <td>Process a groovy script in the file for the open alignment.</td>
482 <td align="center">✓</td>
487 <h2><a name="outputtingalignmentfiles"></a>Outputting alignment files</h2>
489 <table border="1" cellpadding="3">
491 <td><strong>argument</strong></td>
492 <td><strong>action</strong></td>
493 <td><strong>sub-value modifiers</strong> (optional)</td>
494 <td><strong>linked</strong> (optional)</td>
498 <td><code>‑‑output <em>filename</em></code></td>
499 <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:
501 <code>fasta</code> (<code>fa, fasta, mfa, fastq</code>),
503 <code>pfam</code> (<code>pfam</code>),
505 <code>stockholm</code> (<code>sto, stk</code>),
507 <code>pir</code> (<code>pir</code>),
509 <code>blc</code> (<code>blc</code>),
511 <code>amsa</code> (<code>amsa</code>),
513 <code>json</code> (<code>json</code>),
515 <code>pileup</code> (<code>pileup</code>),
517 <code>msf</code> (<code>msf</code>),
519 <code>clustal</code> (<code>aln</code>),
521 <code>phylip</code> (<code>phy</code>),
523 <code>jalview</code> (<code>jvp, jar</code>).
525 <td><code>format=<em>name</em></code></td>
526 <td align="center">✓</td>
530 <td><code>‑‑format <em>name</em></code></td>
531 <td>Sets the format for the preceding <code>‑‑output</code> file. Valid formats are:
537 <code>stockholm</code>,
551 <code>clustal</code>,
555 <code>jalview</code>.
558 <td align="center">✓</td>
562 <td><code>‑‑backups / ‑‑nobackups</code></td>
563 <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>
565 <td align="center">✓</td>
569 <td><code>‑‑overwrite / ‑‑nooverwrite</code></td>
570 <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>
572 <td align="center">✓</td>
578 <h2><a name="exportingimagefiles"></a>Exporting image files</h2>
580 <table border="1" cellpadding="3">
582 <td><strong>argument</strong></td>
583 <td><strong>action</strong></td>
584 <td><strong>sub-value modifiers</strong> (optional)</td>
585 <td><strong>linked</strong> (optional)</td>
589 <td><code>‑‑image <em>filename</em></code></td>
590 <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:
603 <code>type=<em>name</em>,
604 <code>textrenderer=<em>name</em>,
605 <code>scale=<em>number</em>,
606 <code>width=<em>number</em>,
607 <code>height=<em>number</em>
609 <td align="center">✓</td>
613 <td><code>‑‑type <em>name</em></code></td>
614 <td>Set the image format for the preceding <code>‑‑image</code> to <em>name</em>. Valid values for <em>name</em> are:
627 <td align="center">✓</td>
631 <td><code>‑‑textrenderer <em>name</em></code></td>
632 <td>Sets whether text in a vector image format (SVG, HTML, EPS) should be rendered as text or vector line-art. Valid values for <em>name</em> are:
636 <code>lineart</code>.
639 <td align="center">✓</td>
643 <td><code>‑‑scale <em>number</em></code></td>
644 <td>Sets a scaling for bitmap image format (PNG). Should be given as a floating point number. This can also be set as a sub-value modifier to the <code>--image</code> value. If used in conjunction with <code>--width</code> and <code>--height</code> then the smallest scaling will be used (<code>scale</code>, <code>width</code> and <code>height</code> provide bounds for the image).
647 <td align="center">✓</td>
651 <td><code>‑‑width <em>number</em></code></td>
652 <td>Sets a width for bitmap image format (PNG) with the height maintaining the aspect ratio. Should be given as a positive integer. This can also be set as a sub-value modifier to the <code>--image</code> value. If used in conjunction with <code>--scale</code> and <code>--height</code> then the smallest scaling will be used (<code>scale</code>, <code>width</code> and <code>height</code> provide bounds for the image).
655 <td align="center">✓</td>
659 <td><code>‑‑height <em>number</em></code></td>
660 <td>Sets a height for bitmap image format (PNG) with the width maintaining the aspect ratio. Should be given as a positive integer. This can also be set as a sub-value modifier to the <code>--image</code> value. If used in conjunction with <code>--scale</code> and <code>--width</code> then the smallest scaling will be used (<code>scale</code>, <code>width</code> and <code>height</code> provide bounds for the image).</td>
662 <td align="center">✓</td>
666 <td><code>‑‑groovy <em>filename</em></code></td>
667 <td>Process a groovy script in the file for the open alignment.</td>
669 <td align="center">✓</td>
675 <h2><a name="exporting3dstructureimagefiles"></a>Exporting 3D structure image files (<code>jmol</code> only)</h2>
677 <table border="1" cellpadding="3">
679 <td><strong>argument</strong></td>
680 <td><strong>action</strong></td>
681 <td><strong>sub-value modifiers</strong> (optional)</td>
682 <td><strong>linked</strong> (optional)</td>
686 <td><code>‑‑structureimage <em>filename</em></code></td>
687 <td>Export an image of a 3D structure opened in JMOL. Image formats can be:
696 <code>structureimagetype=<em>name</em>,
697 <code>structureimagetextrenderer=<em>name</em>,
698 <code>structureimagescale=<em>number</em>,
699 <code>structureimagewidth=<em>number</em>,
700 <code>structureimageheight=<em>number</em>
702 <td align="center">✓</td>
706 <td><code>‑‑structureimagetype <em>name</em></code></td>
707 <td>Set the structure image format for the preceding --structureimage. Valid values are:
716 <td align="center">✓</td>
720 <td><code>‑‑structureimagetextrenderer <em>name</em></code></td>
721 <td>Sets whether text in a vector structure image format (SVG, EPS) should be rendered as text or vector line-art. Possible values are:
725 <code>lineart</code>.
728 <td align="center">✓</td>
732 <td><code>‑‑structureimagescale <em>number</em></code></td>
733 <td>Sets a scaling for bitmap structure image format (PNG). Should be given as a floating point number. If used in conjunction with --structureimagewidth and --structureimageheight then the smallest scaling will be used (structureimagescale, structureimagewidth and structureimageheight provide bounds for the structure image).
736 <td align="center">✓</td>
740 <td><code>‑‑structureimagewidth <em>number</em></code></td>
741 <td>Sets a width for bitmap structure image format (PNG) with the height maintaining the aspect ratio. Should be given as a positive integer. If used in conjunction with --structureimagescale and --structureimageheight then the smallest scaling will be used (structureimagescale, structureimagewidth and structureimageheight provide bounds for the structure image).
744 <td align="center">✓</td>
748 <td><code>‑‑structureimageheight <em>number</em></code></td>
749 <td>Sets a height for bitmap structure image format (PNG) with the width maintaining the aspect ratio. Should be given as a positive integer. If used in conjunction with --structureimagescale and --structureimagewidth then the smallest scaling will be used (structureimagescale, structureimagewidth and structureimageheight provide bounds for the structure image).
752 <td align="center">✓</td>
758 <h2><a name="controllingflowofarguments"></a>Controlling flow of arguments</h2>
760 <table border="1" cellpadding="3">
762 <td><strong>argument</strong></td>
763 <td><strong>action</strong></td>
767 <td><code>‑‑new</code></td>
769 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.
771 <em>Note</em> that <code>--open</code> already starts a new alignment window for each file it opens.
776 <td><code>‑‑substitutions / ‑‑nosubstitutions</code></td>
777 <td>The following argument values allow (or don't allow) subsituting filename parts. This is initially true. Valid substitutions are
778 <code>{basename}</code> - the filename-without-extension of the currently <code>‑‑open</code>ed file (or first <code>‑‑append</code>ed file),
780 <code>{dirname}</code>, - the directory (folder) name of the currently <code>‑‑open</code>ed file (or first <code>‑‑append</code>ed file),
782 <code>{argfilebasename}</code> - the filename-without-extension of the current <code>‑‑argfile</code>,
784 <code>{argfiledirname}</code> - the directory (folder) name of the current <code>‑‑argfile</code>,
786 <code>{n}</code> - the value of the index counter (starting at 0).
788 <code>{++n}</code> - increase and substitute the value of the index counter,
790 <code>{}</code> - the value of the current alignment window <em>default</em> index.
795 <td><code>‑‑argfile <em>filename</em></code></td>
797 Open one or more files <em>filename</em> and read, line-by-line, as arguments to Jalview.
799 Values in an argfile should be given with an equals sign ("=") separator with no spaces.
801 <strong>Note</strong> that if you use one or more <code>‑‑argfile</code> arguments then all other non-initialising arguments will be ignored.
806 <td><code>‑‑npp</code></td>
807 <td>Increase the index counter used in argument value substitutions.</td>
811 <td><code>‑‑all / ‑‑noall</code></td>
812 <td>Apply (or stop applying) the following output arguments to <em>all</em> sets of linked arguments.</td>
816 <td><code>‑‑allstructures / ‑‑noallstructures</code></td>
818 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.
823 <td><code>‑‑quit</code></td>
824 <td>After all files have been opened, appended and output, quit Jalview. In <code>‑‑headless</code> mode this already happens.</td>