From 717b6f682f69435671f905bf6ebdaa4c996ab507 Mon Sep 17 00:00:00 2001 From: Ben Soares Date: Mon, 15 May 2023 17:26:25 +0100 Subject: [PATCH] JAL-629 More help text --- help/help/helpTOC.xml | 14 ++- help/help/html/features/clarguments-advanced.html | 123 +++++++++++++++++++++ help/help/html/features/clarguments-argfiles.html | 52 +++++++++ help/help/html/features/clarguments-basic.html | 115 +++++++++++++++++-- help/help/html/features/clarguments-intro.html | 3 + help/help/html/features/clarguments.html | 12 +- 6 files changed, 305 insertions(+), 14 deletions(-) create mode 100644 help/help/html/features/clarguments-argfiles.html diff --git a/help/help/helpTOC.xml b/help/help/helpTOC.xml index 11f0541..11e61be 100755 --- a/help/help/helpTOC.xml +++ b/help/help/helpTOC.xml @@ -169,12 +169,16 @@ - - - + + + + + + + + - - + diff --git a/help/help/html/features/clarguments-advanced.html b/help/help/html/features/clarguments-advanced.html index e69de29..2583b8d 100644 --- a/help/help/html/features/clarguments-advanced.html +++ b/help/help/html/features/clarguments-advanced.html @@ -0,0 +1,123 @@ + + +Jalview Command Line Arguments: advanced usage + + +

Jalview Command Line Arguments: advanced usage

+ +

+ Jalview Command Line Arguments: summary +
+ Jalview Command Line Arguments: introduction +
+ Jalview Command Line Arguments: basic usage +
+ Jalview Command Line Arguments: advanced usage +
+ Jalview Command Line Arguments: argfiles +

+ +
+ + + + +

Alignment linked IDs

+ +

+ Jalview's alignment related arguments are linked together using a linked ID. In all of the basic usage examples this linked ID is assigned using a default formula of JALVIEW:n where n starts at 0 and increments every time there is an --opened file (or a first use of --append) or the --newargument is used. +

+ +

+ When another alignment related argument is used, it is assigned the same linked ID. When the --all argument is used, following alignment related arguments are applied to all linked IDs (made so far). +

+ +

+ 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 ('[', ']') immediately following the argument (i.e. before any space or equals sign) like this: + 

+  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
+
+

+ +

+ 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. +

+ + +

More substitutions

+ +

+ In the basic usage document we have a list of special strings that get replaced in output filename values with parts of input filename values. +

+ +

+ There is also an incrementor integer value {n} that can be put into both linked IDs and filenames and works across different linked IDs. Whenever you use {n} in a linked ID or filename value it is replaced with the current value of n. The initial value is 0, and it can be incremented by using the argument --npp or --n++, or using a another substitution {++n} in either a linked ID or filename value which increments the value and is replaced with the new incremented value of n. +

+ +

+ In the same way that the --all argument enables (some) following arguments to apply to all opened alignments so far, the special linked ID {*} will also apply an individual argument to all opened linked IDs. + 

+  jalview --open[myId1] fileA.fa --open[myId2] fileB.fa --open[myId3] fileC.fa --colour[{*}] taylor --all --image tmp/image-{++n}.png --headless
+
+ The above will produce an image image-0.png for the alignment in fileA.fa, an image image-1.png for the alignment in fileB.fa, etc. +

+ + +

Equals separator and file globs

+ +

+ 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. +

+ +

+ 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). +

+ +

+ 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. + 

+  jalview --open=examples/uniref50*.fa --colour=clustal --all --image=*.png --scale=2.5 --headless
+
+

+ +

+ One benefit of this is seen above in the --image argument, the special "alloutput" wildcard filename *.png will not be expanded by the shell, so does not need to be escaped or surrounded with quotation marks. +

+ +

+ Another benefit is that the input filename + +

+ + +
+ Continue to Jalview Command Line Arguments: argfiles. +
+ Return to Jalview Command Line Arguments: summary. + + + + diff --git a/help/help/html/features/clarguments-argfiles.html b/help/help/html/features/clarguments-argfiles.html new file mode 100644 index 0000000..a527c21 --- /dev/null +++ b/help/help/html/features/clarguments-argfiles.html @@ -0,0 +1,52 @@ + + +Jalview Command Line Arguments: argfiles + + +

Jalview Command Line Arguments: argfiles

+ +

+ Jalview Command Line Arguments: summary +
+ Jalview Command Line Arguments: introduction +
+ Jalview Command Line Arguments: basic usage +
+ Jalview Command Line Arguments: advanced usage +
+ Jalview Command Line Arguments: argfiles +

+ +
+ + + + + + + +
+ Return to Jalview Command Line Arguments: summary. + + + + diff --git a/help/help/html/features/clarguments-basic.html b/help/help/html/features/clarguments-basic.html index 19406b4..b557f4f 100644 --- a/help/help/html/features/clarguments-basic.html +++ b/help/help/html/features/clarguments-basic.html @@ -44,6 +44,7 @@
  • Adding 3D structures
  • Outputting/converting alignment files and images
  • Filename substitutions and batch processing
    • +
  • The all output wildcard

    • Opening alignments (--open, --append, --new)

    @@ -516,45 +517,145 @@

    -

    Filename substitutions and batch processing (--substitutions, --new, --close, --all)

    +

    Filename substitutions and batch processing (--substitutions, --close, --all)

    -

    --

    +

    + 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 all of the alignments as they are opened. This includes display and output arguments. +

    + +

    + 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. +

    + +

    + To refer to different parts of the opening filename, you can use the strings +

      +
    • {dirname} -- is replaced by the directory path to the opened file.
      • +
    • {basename} -- is replaced by the base of the filename of the opened file. This is without the path or file extension (if there is one).
      • +
    • {extension} -- is replaced by the extension of the filename of the opened file.
      • +
    + The braces (curly brackets '{', '}') are important! +

    + +

    + 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: +

    + +

    --substitutions / --nosubstitutions

    + Enable (or disable) filename substitutions in the following argument values and sub-value modifier values. 

    +  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

    -

    --

    +

    + 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 --output or --image 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 --all argument. +

    + +

    --all / -noall

    + +

    + When using the --all argument, following arguments will apply to all of the previously opened alignment windows. You can turn this behaviour off for following arguments using the --noall argument. The arguments that can apply to all previously opened alignments are: +
    + --colour +
    + --sortbytree +
    + --showannotations +
    + --wrap +
    + --nostructure +
    + --notempfac +
    + --showssannotations +
    + --image +
    + --type +
    + --textrenderer +
    + --scale +
    + --width +
    + --height +
    + --output +
    + --format +
    + --groovy +
    + --backups +
    + --overwrite +
    + --close +

    +

    + In particular, for our example above, we can use -all and --output like this (--close will be explained in a moment): + 

    +  jalview --open all_my_fasta_files/*.fa --all --output all_my_converted_stockholm_files/{basename}.stk --close --headless
+
    +

    + 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: + 

    +  jalview --open */*.fa --all --colour gecos-flower --image {dirname}/{basename}.eps --textrenderer text --close --headless
+
    + or thumbnails for every Fasta file with 
    +  jalview --open */*.fa --all --colour gecos-flower --image {dirname}/{basename}.png --width 256 --height 256 --close --headless

    -

    --

    +

    --close

    + The --close tag is used to close an alignment window after all output files or image exports are performed. This reduces memory use, especially if an --open 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.

    -

    --

    + +

    The all output wildcard: --output "*.ext", --image "*.ext"

    + +

    + Purely as an intuitive syntactic sweetener, you can use the --output wildcard * at the beginning of the output filename as shorthand for --all --output {dirname}/{basename} followed by whatever you put after the *. For example, to achieve the same as the thumbnails example above, you could use + 

    +  jalview --open */*.fa --image "*.png" --colour gecos-flower --width 256 --height 256 --close --headless
+
    + Here we move the --colour argument after the --output argument (it will still be applied before the image export or file output) so that it is included after the implied --all argument. The thumbnails will be placed in the same directory as the alignment file with the same filename except for a different extension of .png. +

    + For a simple conversion of many fasta files into Stockholm format, simply use 

    +  jalview --open all_my_fasta_files/*.fa --output "*.stk" --close --headless

    -

    --

    +

    + Important! Please note that using a bareword *.ext (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 .ext before this value is passed to Jalview. This will result in the first of these files being overwritten (multiple times)! If you shell-escape the * (usually with a backslash '\') or enclose the value in quotation marks ('"*.ext"') then the shell will not expand the wildcard. +

    + An alternative is to use an equals sign ('=') with no spaces between the argument and the value, --output=*.ext, which Jalview will interpret the same, but the shell will not automatically expand before it is sent to Jalview, e.g. 

    +  jalview --open all_my_fasta_files/*.fa --output=*.stk --close --headless

    +
    Continue to Jalview Command Line Arguments: advanced usage. - +
    + Return to Jalview Command Line Arguments: summary. diff --git a/help/help/html/features/clarguments-intro.html b/help/help/html/features/clarguments-intro.html index cee0a04..c3cc918 100644 --- a/help/help/html/features/clarguments-intro.html +++ b/help/help/html/features/clarguments-intro.html @@ -78,7 +78,10 @@ running Jalview from the command line.

    +
    Continue to Jalview Command Line Arguments: basic usage. +
    + Return to Jalview Command Line Arguments: summary. diff --git a/help/help/html/features/clarguments.html b/help/help/html/features/clarguments.html index 78fb006..20c8619 100644 --- a/help/help/html/features/clarguments.html +++ b/help/help/html/features/clarguments.html @@ -97,10 +97,18 @@ Set ‑‑substitutions to be initially enabled (or initially disabled). + + + + ‑‑jvmmempc=PERCENT - Limit maximum heap size (memory) to PERCENT% of total physical memory detected. + Limit maximum heap size (memory) to PERCENT% of total physical memory detected. This defaults to 90 if total physical memory can be detected.
    The equals sign ("=") separator must be used with no spaces. @@ -112,7 +120,7 @@ ‑‑jvmmemmax=MAXMEMORY - Limit maximum heap size (memory) to MAXMEMORY. MAXMEMORY can be specified in bytes, kilobytes(k), megabytes(m), + Limit maximum heap size (memory) to MAXMEMORY. MAXMEMORY 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.
    -- 1.7.10.2