help/help/html/features/clarguments-advanced.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>Command Line: advanced usage</title>
  23 <body>
  24
  25   <h1>Command Line: advanced usage</h1>
  26
  27   <p>
  28   <a href="clarguments.html">Command Line: summary</a>
  29   <br/>
  30   <a href="clarguments-intro.html">Command Line: introduction</a>
  31   <br/>
  32   <a href="clarguments-basic.html">Command Line: basic usage</a>
  33   <br/>
  34   Command Line: advanced usage
  35   <br/>
  36   <a href="clarguments-argfiles.html">Command Line: argument files</a>
  37   </p>
  38
  39   <hr/>
  40
  41   <ul>
  42   <li><a href="#alignmentlinkedids">Alignment linked IDs</a></li>
  43   <li><a href="#moresubstitutions">More substitutions</a></li>
  44   <li><a href="#equalsseparatorandfileglobs">Equals separator and file globs</a></li>
  45   <li><a href="#subvaluemodifiers">Sub-value modifiers</a></li>
  46   </ul>
  47
  48
  49   <h2><a name="alignmentlinkedids"></a>Alignment linked IDs</h2>
  50
  51   <p>
  52   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.
  53   </p>
  54
  55   <p>
  56   When another alignment related argument is used (without a specified linked ID), it is assigned this default linked ID.  When the <code>--all</code> argument is used, following alignment related arguments are applied to all of the linked IDs (made so far).
  57   </p>
  58
  59   <p>
  60   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</em> (i.e. before any space or equals sign) like this:
  61   <pre>
  62   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
  63   </pre>
  64
  65   <p>
  66   As you can see, if you specify your own linked IDs, the arguments for one alignment do not need to be adjacent as they are when using the default assigned linked ID.
  67   </p>
  68
  69   <p>
  70   A specified linked ID will also take precedence over a wildcard or <code>--all</code> set linked ID. e.g.
  71   <pre>
  72   jalview --open[myID] examples/uniref50.fa --all --colour taylor --colour[myID] gecos-blossom
  73   </pre>
  74   will open the alignment using the <code>gecos-blossom</code> colour scheme (thank goodness).
  75   </p>
  76
  77
  78   <h2><a name="moresubstitutions"></a>More substitutions (<code>{n}</code>, <code>{++n}</code>, <code>[*]</code>)</h2>
  79
  80   <p>
  81   In the <a href="clarguments-basic.html#substitutions">basic usage document</a> we have a list of special strings that get replaced in output filename values with parts of input filename values.
  82   </p>
  83
  84   <p>
  85   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 special 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>.
  86   </p>
  87
  88   <p>
  89   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 (in fact when you use the <code>--all</code> argument it simply changes the default linked ID to <code>*</code>).
  90   <pre>
  91   jalview --open[myId1] fileA.fa --open[myId2] fileB.fa --open[myId3] fileC.fa --colour[*] taylor --all --image tmp/image-{++n}.png --headless
  92   </pre>
  93   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.
  94   If you suddenly decide to colour the last alignment differently you could add to the command:
  95   <pre>
  96   jalview --open[myId1] fileA.fa --open[myId2] fileB.fa --open[myId3] fileC.fa --colour[*] taylor --all --image tmp/image-{++n}.png --headless --colour[myId3] gecos-blossom
  97   </pre>
  98   because all of the command line arguments are read and sorted into their linked IDs before starting to be processed, and the <code>[myId3]</code> specified linked ID takes precedence over the <code>[*]</code> wildcard linked ID.
  99   </p>
 100   </p>
 101
 102
 103   <h2><a name="equalsseparatorandfileglobs"></a>Equals separator and Java file globs</h2>
 104
 105   <p>
 106   When a Command-line argument requires one (or more) values, you can use the usual space separation, which allows the shell to expand any file "globs" (that is, filenames with wildcard characters allowing it to represent multiple files).  The shell "expands" this file glob and to Jalview it appears like a list of filenames supplied to the argument.
 107   </p>
 108
 109   <p>
 110   There is a limitation to shell expansion of file globs, as the length of a single command, or number of files the shell is willing to expand a file glob to, is limited (to different amounts depending on your shell and its configuration).
 111   </p>
 112
 113   <p>
 114   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.
 115   <pre>
 116   jalview --open=examples/uniref50*.fa --colour=clustal --all --image=*.png --scale=2.5 --headless
 117   </pre>
 118   </p>
 119
 120   <p>
 121   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.
 122   </p>
 123
 124   <p>
 125   A bigger benefit is that the <em>input</em> filename is not expanded by the shell but can instead be expanded by Jalview.  There is no limit to the number of files that this kind of file glob can match since it is expanded by Jalview, not the shell.
 126   </p>
 127
 128   <p>
 129   Jalview uses the Java PathMatcher "glob" scheme to match filenames, which is quite similar, though in some ways more powerful, to most shell glob rules.  The usual '<code>*</code>' and '<code>?</code>' characters act the same, but other combinations can be used too.  For the full rules see <a href="https://devdocs.io/openjdk~11/java.base/java/nio/file/filesystem#getPathMatcher(java.lang.String)">java.nio.file.PathMatcher.getPathMatcher</a> javadocs at https://devdocs.io/openjdk~11/java.base/java/nio/file/filesystem#getPathMatcher(java.lang.String).
 130   </p>
 131
 132   <p>
 133   One such PathMatcher addition to shell file globs is the use of <code>**</code> to match any number of directories and sub-directories (matching across file separator).  So to convert every Fasta file under the current working directory to BLC format you can do:
 134   <pre>
 135   jalview --open=./**/*.fa --output=*.blc --close --headless
 136   </pre>
 137   or to find every Stockholm and Pfam file under </code>/tmp</code> and convert to Fasta and save in your own folder, do
 138   <pre>
 139   jalview --open=/tmp/**/*.{stk,pfam} --all --output=~/rescued/{basenamedir}.fa --close --headless
 140   </pre>
 141   </p>
 142
 143   <h2><a name="subvaluemodifiers"></a>Sub-value modifiers</h2>
 144
 145   <p>
 146   Sub-value modifiers are given in square brackets ('[', ']') <em>immediately before the value</em> (i.e. after any space or equals sign, and with no space between it and the value) like this:
 147   <pre>
 148   jalview --open=examples/uniref50.fa --image=[scale=1.414]picture.png
 149   </pre>
 150   </p>
 151
 152   <p>
 153   Some arguments (such as <code>--scale=<em>n</em></code>) are used to modify the behaviour of other "primary" arguments (such as <code>--image=filename</code>).  These arguments can alternatively be specifed as <em>sub-value modifiers</em> of the values given to the primary argument.  If specified as a sub-value modifier, this modifier takes precedence over any following linked argument if given. e.g
 154   <pre>
 155   jalview --open=[colour=zappo]examples/*.fa
 156   </pre>
 157   Notice also that if a sub-value modifier is used for a value that is expanded by the application (i.e. using an equals sign ('=') to separate argument and value) then that modifier is applied to all of the values.
 158   </p>
 159
 160   <p>
 161   For shell expanded globs this is more problematic since the presence of a sub-value modifier will almost certainly prevent the shell from recognising the file glob, so
 162   <pre>
 163   jalview --open [colour=zappo]examples/*.fa
 164   </pre>
 165   will <em>NOT</em> work the same as above.  If you need to use sub-value modifiers on a file glob you should use an equals sign ('=') to separate it from the argument.
 166   </p>
 167
 168   <p>
 169   You can specify multiple sub-value modifiers separating them with a comma (',').  If you wish to specify a "boolean" argument, such as <code>--wrap</code> or <code>--nowrap</code> then simply use the argument name without a value, like this:
 170   <pre>
 171   jalview --open=[colour=gecos-flower,wrap,noannotations,features=examples/plantfdx.features]examples/plantfdx.fa
 172   </pre>
 173   </p>
 174
 175
 176   <hr/>
 177   Continue to <a href="clarguments-argfiles.html">Command Line: argument files</a>.
 178   <br/>
 179   Return to <a href="clarguments.html">Command Line: summary</a>.
 180
 181
 182 </body>
 183 </html>