<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>
git://source.jalview.org / jalview.git / blobdiff