<tocitem text="Groovy Features Counter example" target="groovy.featurescounter"/>
</tocitem>
<tocitem text="Command Line" target="commandline" expand="false">
- <tocitem text="Command Line Arguments" target="clarguments" />
- <tocitem text="Memory Settings" target="memory" expand="false"/>
- <tocitem text="Jalview Launch Files" target="jvlfiles" expand="false"/>
+ <tocitem text="Command Line Arguments: summary" target="clarguments" />
+ <tocitem text="Command Line Arguments: introduction" target="clarguments-intro" />
+ <tocitem text="Command Line Arguments: basic usage" target="clarguments-basic" />
+ <tocitem text="Command Line Arguments: advanced usage" target="clarguments-advanced" />
+ <tocitem text="Command Line Arguments: argfiles" target="clarguments-argfiles" />
+ </tocitem>
+ <tocitem text="Memory Settings" target="memory" expand="false"/>
+ <tocitem text="Jalview Launch Files" target="jvlfiles" expand="false"/>
</tocitem>
- <tocitem text="Privacy" target="privacy" />
- </tocitem>
+ <tocitem text="Privacy" target="privacy" />
<tocitem text="Useful information" expand="true">
<tocitem text="Amino Acid Table" target="aminoAcids" />
<tocitem text="Amino Acid Properties" target="aaProperties" />
+<html>
+<!--
+ * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
+ * Copyright (C) $$Year-Rel$$ The Jalview Authors
+ *
+ * This file is part of Jalview.
+ *
+ * Jalview is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation, either version 3
+ * of the License, or (at your option) any later version.
+ *
+ * Jalview is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty
+ * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+ * PURPOSE. See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with Jalview. If not, see <http://www.gnu.org/licenses/>.
+ * The Jalview Authors are detailed in the 'AUTHORS' file.
+ -->
+<title>Jalview Command Line Arguments: advanced usage</title>
+<body>
+
+ <h1>Jalview Command Line Arguments: advanced usage</h1>
+
+ <p>
+ <a href="clarguments.html">Jalview Command Line Arguments: summary</a>
+ <br/>
+ <a href="clarguments-intro.html">Jalview Command Line Arguments: introduction</a>
+ <br/>
+ <a href="clarguments-basic.html">Jalview Command Line Arguments: basic usage</a>
+ <br/>
+ Jalview Command Line Arguments: advanced usage
+ <br/>
+ <a href="clarguments-argfiles.html">Jalview Command Line Arguments: argfiles</a>
+ </p>
+
+ <hr/>
+
+ <ul>
+ <li><a href="#alignmentlinkedids">Alignment linked IDs</a></li>
+ <li><a href="#moresubtitutions">More substitutions</a></li>
+ <li><a href="#equalsseparatorandfileglobs">Equals separator and file globs</a></li>
+ </ul>
+
+
+ <h2><a name="alignmentlinkedids"></a>Alignment linked IDs</h2>
+
+ <p>
+ Jalview's alignment related arguments are linked together using a <em>linked ID</em>. In all of the basic usage examples this linked ID is assigned using a default formula of <code>JALVIEW:<em>n</em></code> where <em>n</em> starts at 0 and increments every time there is an <code>--open</code>ed file (or a first use of <code>--append</code>) or the <code>--new</code>argument is used.
+ </p>
+
+ <p>
+ When another alignment related argument is used, it is assigned the same linked ID. When the <code>--all</code> argument is used, following alignment related arguments are applied to all linked IDs (made so far).
+ </p>
+
+ <p>
+ You can assign your own linked IDs to alignments that are opened from the command-line. To do this put the linked ID in square brackets ('[', ']') <em>immediately following the argument (i.e. before any space or equals sign) like this:
+ <pre>
+ jalview --open[myId1] file1.fa --open[myId2] file2.fa --open[myId3] file3.fa --colour[myId1] gecos-flower --colour[myId2] gecos-blossom --colour[myId3] zappo --image "*.png" --headless
+ </pre>
+ </p>
+
+ <p>
+ As you can see the arguments for one alignment do not need to be adjacent as they are when using the default assigned linked ID.
+ </p>
+
+
+ <h2><a name="moresubstitutions"></a>More substitutions</h2>
+
+ <p>
+ In the <a href="clarguments-basic.html#substutions">basic usage document</a> we have a list of special strings that get replaced in output filename values with parts of input filename values.
+ </p>
+
+ <p>
+ There is also an incrementor integer value <code>{n}</code> that can be put into both linked IDs and filenames and works across different linked IDs. Whenever you use <code>{n}</code> in a linked ID or filename value it is replaced with the current value of <em>n</em>. The initial value is 0, and it can be incremented by using the argument <code>--npp</code> or <code>--n++</code>, or using a another substitution <code>{++n}</code> in either a linked ID or filename value which increments the value and is replaced with the new incremented value of <em>n</em>.
+ </p>
+
+ <p>
+ In the same way that the <code>--all</code> argument enables (some) following arguments to apply to all opened alignments so far, the special linked ID <code>{*}</code> will also apply an individual argument to all opened linked IDs.
+ <pre>
+ jalview --open[myId1] fileA.fa --open[myId2] fileB.fa --open[myId3] fileC.fa --colour[{*}] taylor --all --image tmp/image-{++n}.png --headless
+ </pre>
+ The above will produce an image <code>image-0.png</code> for the alignment in <code>fileA.fa</code>, an image <code>image-1.png</code> for the alignment in <code>fileB.fa</code>, etc.
+ </p>
+
+
+ <h2><a name="equalsseparatorandfileglobs"></a>Equals separator and file globs</h2>
+
+ <p>
+ When a Jalview command-line argument requires one (or more) values, you can use the usual space separation, which allows the shell to expand any filename "globs" (or wildcards representing multiple files). To Jalview this appears like a list of filenames supplied to the argument.
+ </p>
+
+ <p>
+ There is a limitation to shell expansion of file globs, as the length of a single command is limited (to different amounts depending on your shell and its configuration).
+ </p>
+
+ <p>
+ Jalview will also recognise values supplied to arguments (that expect one or more value) that are separated by an equals sign ("="). There should be no spaces around the equals sign, e.g.
+ <pre>
+ jalview --open=examples/uniref50*.fa --colour=clustal --all --image=*.png --scale=2.5 --headless
+ </pre>
+ </p>
+
+ <p>
+ One benefit of this is seen above in the <code>--image</code> argument, the special "alloutput" wildcard filename <code>*.png</code> will not be expanded by the shell, so does not need to be escaped or surrounded with quotation marks.
+ </p>
+
+ <p>
+ Another benefit is that the <em>input</em> filename
+
+ </p>
+
+
+ <hr/>
+ Continue to <a href="clarguments-argfiles.html">Jalview Command Line Arguments: argfiles</a>.
+ <br/>
+ Return to <a href="clarguments.html">Jalview Command Line Arguments: summary</a>.
+
+
+</body>
+</html>
--- /dev/null
+<html>
+<!--
+ * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
+ * Copyright (C) $$Year-Rel$$ The Jalview Authors
+ *
+ * This file is part of Jalview.
+ *
+ * Jalview is free software: you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation, either version 3
+ * of the License, or (at your option) any later version.
+ *
+ * Jalview is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty
+ * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+ * PURPOSE. See the GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with Jalview. If not, see <http://www.gnu.org/licenses/>.
+ * The Jalview Authors are detailed in the 'AUTHORS' file.
+ -->
+<title>Jalview Command Line Arguments: argfiles</title>
+<body>
+
+ <h1>Jalview Command Line Arguments: argfiles</h1>
+
+ <p>
+ <a href="clarguments.html">Jalview Command Line Arguments: summary</a>
+ <br/>
+ <a href="clarguments-intro.html">Jalview Command Line Arguments: introduction</a>
+ <br/>
+ <a href="clarguments-basic.html">Jalview Command Line Arguments: basic usage</a>
+ <br/>
+ <a href="clarguments-advanced.html">Jalview Command Line Arguments: advanced usage</a>
+ <br/>
+ Jalview Command Line Arguments: argfiles
+ </p>
+
+ <hr/>
+
+
+
+
+
+
+
+ <hr/>
+ Return to <a href="clarguments.html">Jalview Command Line Arguments: summary</a>.
+
+
+</body>
+</html>
<li><a href="#adding3dstructures">Adding 3D structures</a></li>
<li><a href="#outputtingalignmentfiles">Outputting/converting alignment files and images</a></li>
<li><a href="#filenamesubstitutionsandbatchprocessing">Filename substitutions and batch processing</a></li>
+ <li><a href="#alloutputwildcard">The all output wildcard</a></li>
</ul>
<h2><a name="openingalignments"></a>Opening alignments (<code>--open</code>, <code>--append</code>, <code>--new</code>)</h2>
</p>
- <h2><a name="filenamesubstitutionsandbatchprocessing"></a>Filename substitutions and batch processing (<code>--substitutions</code>, <code>--new</code>, <code>--close</code>, <code>--all</code>)</h2>
+ <h2><a name="filenamesubstitutionsandbatchprocessing"></a>Filename substitutions and batch processing (<code>--substitutions</code>, <code>--close</code>, <code>--all</code>)</h2>
- <h3><a name=""></a><code>--</code></h3>
+ <p>
+ One of the more powerful aspects of Jalview's command line operations is that stores all of the different opened alignment arguments (before opening them) and can apply some arguments to <em>all</em> of the alignments as they are opened. This includes display and output arguments.
+ </p>
+
+ <p>
+ When outputting a file you will obviously want to use a different filename for each of the alignments that are opened. There are several ways you can specify how that filename differs, but the easiest way is to refer to the input filename and change the extension. In the case of an alignment where multiple files are appended, the filename of the first file to be appended or opened is used.
+ </p>
+
+ <p>
+ To refer to different parts of the opening filename, you can use the strings
+ <ul>
+ <li><code>{dirname}</code> -- is replaced by the directory path to the opened file.</li>
+ <li><code>{basename}</code> -- is replaced by the base of the filename of the opened file. This is without the path or file extension (if there is one).</li>
+ <li><code>{extension}</code> -- is replaced by the extension of the filename of the opened file.</li>
+ </ul>
+ The braces (curly brackets '{', '}') are important!
+ </p>
+
+ <p>
+ These filename substitutions are on by default, but if for whatever reason you wish to disable the substitutions, they can be turned off (or back on again) through the list of arguments with:
+ </p>
+
+ <h3><a name="substitutions"></a><code>--substitutions / --nosubstitutions</code></h3>
<p>
+ Enable (or disable) filename substitutions in the following argument values and sub-value modifier values.
<pre>
+ jalview --open exampes/uniref50.fa --nosubstitutions --output I_Want_A_Weird_Output_Filname_With_{basename}_Curly_Brackets_In_And_A_Sensible_One_Next.stk --substitutions --output tmp/{basename}.stk --headless
</pre>
</p>
- <h3><a name=""></a><code>--</code></h3>
+ <p>
+ For opening single files this is less useful, since you could obviously just type the output filename, but for multiple opened alignments you can also use these substituted values and they will be replaced by the relevant part of the filename given for each opened alignment window. Normally an <code>--output</code> or <code>--image</code> argument will only be applied to the latest opened alignment window, but you can tell Jalview to apply some arguments to all alignments that have been opened (so far) by using the <code>--all</code> argument.
+ </p>
+
+ <h3><a name="all"></a><code>--all / -noall</code></h3>
+
+ <p>
+ When using the <code>--all</code> argument, following arguments will apply to all of the previously opened alignment windows. You can turn this behaviour off for following arguments using the <code>--noall</code> argument. The arguments that can apply to all previously opened alignments are:
+ <br/>
+ <code>--colour</code>
+ <br/>
+ <code>--sortbytree</code>
+ <br/>
+ <code>--showannotations</code>
+ <br/>
+ <code>--wrap</code>
+ <br/>
+ <code>--nostructure</code>
+ <br/>
+ <code>--notempfac</code>
+ <br/>
+ <code>--showssannotations</code>
+ <br/>
+ <code>--image</code>
+ <br/>
+ <code>--type</code>
+ <br/>
+ <code>--textrenderer</code>
+ <br/>
+ <code>--scale</code>
+ <br/>
+ <code>--width</code>
+ <br/>
+ <code>--height</code>
+ <br/>
+ <code>--output</code>
+ <br/>
+ <code>--format</code>
+ <br/>
+ <code>--groovy</code>
+ <br/>
+ <code>--backups</code>
+ <br/>
+ <code>--overwrite</code>
+ <br/>
+ <code>--close</code>
+ </p>
+ <p>
+ In particular, for our example above, we can use <code>-all</code> and <code>--output</code> like this (<code>--close</code> will be explained in a moment):
+ <pre>
+ jalview --open all_my_fasta_files/*.fa --all --output all_my_converted_stockholm_files/{basename}.stk --close --headless
+ </pre>
+ </p>
<p>
+ Another example would be to create a print quality coloured postscript image for every Fasta file in several directories and place the image next to the alignment:
+ <pre>
+ jalview --open */*.fa --all --colour gecos-flower --image {dirname}/{basename}.eps --textrenderer text --close --headless
+ </pre>
+ or thumbnails for every Fasta file with
<pre>
+ jalview --open */*.fa --all --colour gecos-flower --image {dirname}/{basename}.png --width 256 --height 256 --close --headless
</pre>
</p>
- <h3><a name=""></a><code>--</code></h3>
+ <h3><a name="close"></a><code>--close</code></h3>
<p>
+ The <code>--close</code> tag is used to close an alignment window after all output files or image exports are performed. This reduces memory use, especially if an <code>--open</code> value is set to open many files. These will be opened, formatted and output sequentially so since they are closed before the next one is opened memory use will not build up over a large number of alignments.
<pre>
</pre>
</p>
- <h3><a name=""></a><code>--</code></h3>
+
+ <h2><a name="alloutputwildcard"></a>The all output wildcard: <code>--output "*.ext"</code>, <code>--image "*.ext"</code></h2>
+
+ <p>
+ Purely as an intuitive syntactic sweetener, you can use the <code>--output</code> wildcard <code>*</code> <em>at the beginning of the output filename</em> as shorthand for <code>--all --output {dirname}/{basename}</code> followed by whatever you put after the <code>*</code>. For example, to achieve the same as the thumbnails example above, you could use
+ <pre>
+ jalview --open */*.fa --image "*.png" --colour gecos-flower --width 256 --height 256 --close --headless
+ </pre>
+ Here we move the <code>--colour</code> argument after the <code>--output</code> argument (it will still be applied before the image export or file output) so that it is included after the implied <code>--all</code> argument. The thumbnails will be placed in the same directory as the alignment file with the same filename except for a different extension of <code>.png</code>.
+ </p>
<p>
+ For a simple conversion of many fasta files into Stockholm format, simply use
<pre>
+ jalview --open all_my_fasta_files/*.fa --output "*.stk" --close --headless
</pre>
</p>
- <h3><a name=""></a><code>--</code></h3>
+ <p>
+ <strong>Important!</strong> Please note that using a bareword <code>*.ext</code> (i.e. without an escape or quotation marks) in a shell command line will potentially be expanded by the shell to a list of all the files in the current directory ending with <code>.ext</code> <em>before</em> this value is passed to Jalview. This will result in the first of these files being overwritten (multiple times)! If you shell-escape the <code>*</code> (usually with a backslash '\') or enclose the value in quotation marks ('"*.ext"') then the shell will not expand the wildcard.
+ </p>
<p>
+ An alternative is to use an equals sign ('=') with no spaces between the argument and the value, <code>--output=*.ext</code>, which Jalview will interpret the same, but the shell will not automatically expand before it is sent to Jalview, e.g.
<pre>
+ jalview --open all_my_fasta_files/*.fa --output=*.stk --close --headless
</pre>
</p>
+ <hr/>
Continue to <a href="clarguments-advanced.html">Jalview Command Line Arguments: advanced usage</a>.
-
+ <br/>
+ Return to <a href="clarguments.html">Jalview Command Line Arguments: summary</a>.
</body>
<a href="commandline.html">running Jalview from the command line</a>.
</p>
+ <hr/>
Continue to <a href="clarguments-basic.html">Jalview Command Line Arguments: basic usage</a>.
+ <br/>
+ Return to <a href="clarguments.html">Jalview Command Line Arguments: summary</a>.
</body>
<td>Set <code>‑‑substitutions</code> to be initially enabled (or initially disabled).</td>
</tr>
+<!--
+ <tr valign="top">
+ <td><code>‑‑threads <em>NUMBER</em></code></td>
+ <td>When opening multiple alignment windows, set a limit of <em>NUMBER</em> alignments being processed at one time. The default is 3.</td>
+-->
+
+ </tr>
+
<tr valign="top">
<td><code>‑‑jvmmempc=<em>PERCENT</em></code></td>
<td>
- Limit maximum heap size (memory) to PERCENT% of total physical memory detected.
+ Limit maximum heap size (memory) to <em>PERCENT</em>% of total physical memory detected.
This defaults to 90 if total physical memory can be detected.
<br/>
The equals sign ("=") separator must be used with no spaces.
<tr valign="top">
<td><code>‑‑jvmmemmax=<em>MAXMEMORY</em></code></td>
<td>
- Limit maximum heap size (memory) to MAXMEMORY. MAXMEMORY can be specified in bytes, kilobytes(k), megabytes(m),
+ Limit maximum heap size (memory) to <em>MAXMEMORY</em>. <em>MAXMEMORY</em> can be specified in bytes, kilobytes(k), megabytes(m),
gigabytes(g) or if you're lucky enough, terabytes(t).
This defaults to 32g if total physical memory can be detected, or to 8g if total physical memory cannot be detected.
<br/>
git://source.jalview.org / jalview.git / commitdiff