util[ity] <utility command> <other arguments>

    The 'utility' command is used to execute general utility commands.  For

    example, running 'utility clone /data/clone1' will clone the currently open

    project to /data/clone1.

    The following utility commands are available.  Run

    'help utility <utility command>' for more detailed information.

    validateNames           Validates the record names in the currently open

                                project.

    validateForComputation  Validates that the currently open project is ready

                                for computation.

    makeSetupScript         Makes a setup script that, if run, would attempt to

                                recreate the currently open project.

    clone                   Clones the currently open project.

    execute                 Executes a script file.

    util[ity] validateNames [-fix] [-fixPrefix <prefix>] [-fixSuffix <suffix>]

    Validates that the names of records in the currently open project conform

    to the requirements of the command interpreter.  Since commands use record

    names to identify records, duplicate record names can cause ambiguity.

    Additionally, names that are empty or consist entirely of whitespace

    can cause syntactic difficulties in certain situations.

    This command exists to support the manipulation of projects that 

    were created using the Graphical User Interface, where the same naming

    constraints are not currently applied.  Any project created or edited

    with the Command Line Interface will automatically be compatible with

    the Graphical User Interface.  This command provides a mechanism to 

    ensure that the reverse is true as well.

    In its default form, this command will report an error if there are 

    records that will cause ambiguity or syntactic problems if they are 

    encountered by other commands.  If there are no problematic names, this

    command does nothing.

    If the '-fix' option is supplied, this command will construct unique, 

    non-empty names for the records that would have caused problems.  The 

    constructed names will have the word "FIX_" prepended to them and have

    an underscore followed by a number appended to them for uniqueness.  The

    prefix is added to provide a marker that this command has modified the

    name of the record.

    The '-fixPrefix' option specifies a custom string that will be prepended to

    modified records instead of the default, "FIX_".  Setting this option

    implies '-fix'.

    The '-fixSuffix' option specifies a custom string that will appended to

    modified records before the number is appended for uniqueness instead of

    the default, "-".  Setting this option implies '-fix' as well.

    For example, suppose you have a project with 3 samples all named "MyAmp".

    Running 'utility validateNames' will report an error.  Running

    'utility validateNames -fix' will rename the amplicons to be "FIX_MyAmp_1",

    "FIX_MyAmp_2", and "FIX_MyAmp_3".  Running

    'utility validateNames -fix -fixPrefix "FLAG" -fixSuffix "#" will rename

    the amplicons to be "FLAG_MyAmp#1", "FLAG_MyAmp#2", and "FLAG_MyAmp#3".

    Note that since amplicons and variants can be distinguished by the

    reference sequence to which they refer, it is possible to have multiple

    amplicons or variants with the same name but different reference sequences.

    Such records will not be modified by this command, unless they are empty.  

    However, amplicons or variants with the same name and reference are 

    ambiguous and will be modified.

    util[ity] validateForComputation [-silent <boolean>]

    Validates that the currently open project is ready for computation.  The

    project is valid for computation if the following criteria are met.

    - Reference sequences have a sequence that is at least 1 base.

    - Amplicons refer to valid reference sequences and have target start and

      end coordinates that are contained within said reference sequence.

    - Read data files are available that are associated with at least

      one Sample and one or more valid Amplicons.

    - Optionally, Variants that refer to valid reference sequences and 

      have non-empty patterns that are valid with respect to said reference

      sequence.

    If some criteria are not met, warnings are reported describing the

    problems, and an error is reported for the operation.  If '-silent' is set

    to be true, no warnings are reported, but an error is still reported for

    the operation.  If all criteria are met, this command has no effect.

    util[ity] makeSetupScript [-outputFile <file>]

    Makes a setup script that, if run with the command interpreter, would

    attempt to recreate the currently open project.  Note that it will usually

    not be possible to run this script after creating it, since the project

    already exists in the same location.

    If no '-outputFile' is given, the script is printed to the standard output

    of the interpreter.  An output file of "-" has the same effect.  If an

    output file is given, the script is written to that file.

    Run 'help general filePaths' for more information about specifying files.

    util[ity] clone <clone project path>

                        [-projectName <clone project name>]

                        [-projectAnnotation <clone project annotation>]

                        [-copyReadData <boolean>]

                        [-scriptOnly <file>]

    Clones the currently open project.  The project will be cloned to the path

    given as the argument to this command.  By default, the read data and all

    project records that depend on the read data will be excluded from the

    clone.

    By providing the '-projectName' option, the name of the clone project can

    be set.  By default, the project name is set to the base name of the clone

    project path.

    By providing the '-projectAnnotation' option, the annotation of the clone

    project can be set.  By default, the annotation of the clone project will

    be set to be the same as the currently open project.

    If '-copyReadData' is set to "true", the read data and all project records

    that depend on the read data will be included in the clone.  If set to

    "false" (the default), they will not be included.

    If the '-scriptOnly' option is provided, no project will actually be

    created.  Instead, a script will be created that, if run by the command

    interpreter, will perform the clone.  This allows you to adapt and

    customize the clone before actually performing it.  If "-" is provided as

    the file, the script will be written to the standard output of the command

    interpreter.

    Note that the currently cloned project will be cloned as it currently

    exists in the command interpreter.  This means that unsaved changes are

    propagated to the clone.

    Run 'help general filePaths' for more information about the interpretation

    of relative paths when using the '-scriptOnly' option or specifying the 

    clone project path.

    util[ity] exec[ute] <script path>

                        [-withCurrDir <path>]

                        [-onMissingScript <"ignore", "warn", or "error">]

    Executes a script file.  This allows useful sequences of commands to be

    grouped and reused easily.  For example, it may be helpful to create a

    script file that creates standard amplicons.  Executing this script will

    create the amplicons in the currently open project.

    The execution will inherit the environment of the caller.  For example, if

    the verbose option is set in the caller, it will also be set in the script.

    Modification of the environment by the called script will not be propagated

    back to the caller.  For example, suppose the verbose option is set to

    "true" in script A at the time it executes script B.  Script B then sets

    the verbose option to "false".  Commands in script B will execute with a

    "false" verbose option, but once the execution of script B is complete,

    subsequent commands in script A will run with a "true" verbose option.  

    There are two important exceptions to this policy: the currently open

    project and the current directory (currDir).

    The currently open project is global.  For example, if script A executes

    script B and script B opens a project, that project will continue to be

    open in script A.

    The current directory for the execution of a script is set by default to

    the directory that contains the script itself.  For example, execution of

    the script at "someDir/someScript.ava" will run with a current directory of

    "someDir".  This default behavior allows a set of related scripts to

    refer to each other using relative paths, independent of where the scripts

    are actually installed.  It also allows the commands of a script to easily

    refer to a tabular file with the '-file' option in a relative manner when

    that tabular file is installed in a location relative to the script.

    However, this current directory for the script execution can be modified by

    using the '-withCurrDir' option.  If the '-withCurrDir' option is given,

    the path passed to it will be used instead. In particular, to invoke a

    script that will run with the same current directory as the calling script,

    simply do:

         utility execute someDir/someScript.ava -withCurrDir %currDir

    In this example, the shortcut path %currDir expands to the current

    directory of the calling script, thereby setting the current directory

    of the called script to be the same as that of the calling script.  Run 

    'help general filePaths' for more information on the use of relative paths

    and other available shortcut paths.

    The use of '-withCurrDir' has no effect on the current directory of the

    calling script itself.

    By providing the '-onMissingScript' option, the behavior of the command, if

    the file specified by the script path cannot be found, is customized.  If

    set to "ignore", a missing script will be ignored completely.  If set to

    "warn", a warning will be shown.  If set to "error" (the default), an error

    will be reported.

    Run 'help set onErrors' for information about how errors are handled within

    an executed script.

© 2011 454 Life Sciences Corporation, a Roche Company.

For life science research only. Not for use in diagnostic procedures.