The string shown when the -help qualifier is used on the command line

Help is usually only defined if a specific string is needed. If help is not defined, the value of the "information" attribute, or the default prompt, will be used.

expect:

A string used in the "Default" column of the command line syntax table in the documentation. This table is automatically generated from the ACD file, and in most cases there is a reasonable value generated. Where there is no suitable value, this attribute should be used to provide one.

valid:

A string used in the "Allowed values" column of the command line syntax table in the documentation. This table is automatically generated from the ACD file, and in most cases there is a reasonable value generated. Where there is no suitable value, this attribute should be used to provide one.

knowntype:

The knowntype attribute defines one of a controlled vocabulary of known value types. Some ACD data types require a knowntype attribute.

These standard values are read from a file knowntypes.standard which is stored and installed in the ACD file directory. A few other values are accepted, for example "(programname) output" for an outfile data type. These are documented under each output type. The acdvalid utility will check all knowntype values in an ACD file, and report any missing values for data types that require a knowntype.

prompt:

The string used if the user has to be queried for a value, though information can be used instead and usually only one will be defined. information is preferred.

missing:

Indicates whether a qualifier can have no value, especially when it appears on the command line (for example to override a default value in the ACD file).

needed:

Indicates whether a parameter is expected to be included in a GUI form. Some parameters are available on the command line, but are not generally useful to users, or can cause confusion when presented in a GUI form with all other options.

outputmodifier:

Indicates that this qualifier modifies the output in ways that can break parsers, for example by changing text output into HTML. Authors of wrappers can use this to test for qualifiers that can be hardcoded to fix the output syntax and content. Please let the EMBOSS team know if any other qualifiers are candidates for marking as output modifiers.

code:

A code word (no spaces) which is searched for in the file codes.english to give a standard prompt, for example when asking for an alignment gap penalty. The standard default prompts are in the same file. The code word is not case-sensitive. information is preferred.

comment:

A comment, provided for use by the EBI's SoapLab project but not defined in the standard ACD files.

style:

Provided for use by the EBI's SoapLab project but not defined in the standard ACD files.

Any global or specific attribute must have a second token representing the value of the attribute. The attribute must be followed by a colon ':' and usually the value will be enclosed in double quotes.

The syntax of the global attributes is

Formalised:

help: "String"
information: "String"
default: "value"
additional: "Y"/"N"
parameter: "Y"/"N"
information: "String"
standard: "Y"/"N"

Example:

sequence: asequence [
    standard: "Y"
    information: "Enter filename"
  ]

2.4.1.1.1 Parameter: attribute

The parameter: attribute is a boolean attribute, defining the order of the parameters on the command line, if the parameter name is not explicitly entered on the command line. If set to Y, the parameter can be entered on the command line without using the parameter name.

Formalised:

datatype: parametername [
    parameter: Y/N
  ]

Example:

ACD file definition (partly) :

application: acddemo [
    documentation: ""
    groups: ""
  ]

sequence: asequence [
  ]

Command line :

% acddemo -asequence filename.seq

Is equivalent to:

ACD file definition (partly) :

sequence: asequence [
    parameter: Y
  ]

Command line:

% acddemo filename.seq

In both examples filename.seq is the value of the parameter named asequence for the EMBOSS program acddemo.

The second example will also allow the command line from the first, as parameter names are accepted as qualifiers.

If more then one parameter: attribute is used, the order in which they appear in the ACD file is the same as the order in which they appear on the command line.

Example: ACD file definition (partly) :

application: acddemo [
    documentation: ""
    groups: ""
  ]

sequence: asequence [
    parameter: Y
  ]
outseq: outseq [
    parameter: Y
  ]

Command line :

% acddemo infilename.seq outfilename.seq

will assign the name infilename.seq to parameter asequence, and outfilename.seq to parameter outseq.

2.4.1.1.2 Standard: attribute

Any program is expected to have one or more required inputs. An ACD data type that is defined as a "parameter:" (see section 2.4.1.1.1) is automatically counted as required. All other required inputs should have the "standard:" attribute set.

When the program runs, the user will be prompted for any "required" values that are not already on the command line.

The only difference between "parameter:" and "standard:" is that a "parameter" can appear on the command line as the simple value with no name, to provide simple command lines.

2.4.1.1.3 Additional: attribute

When the additional: attribute is set, the parameter will only be queried for, when the -options qualifier is set (on the command line or when the system default is set using an environment variable (See 3.7) or any other way). If the -options qualifier is not set, the user will not be queried for this parameter, if it is omitted in the program execution (i.e. not mentioned on the command line or any other way).

2.4.1.1.4 The prompt: help: and information: attributes

The information: attribute defines the text hint to the user entering a data value. The same text is intended for use in the prompt to the user at a terminal, and as the text in an HTML form or a GUI.

In rare cases where the information: string is misleading, a prompt: string can be defined for use as a terminal prompt. For general use, information: is now preferred.

To provide standard prompts for common ACD data, there are default information: strings for most data types. These can be found in the file codes.english with the names DEFXXXX where XXXX is the name of the ACD data type.

Common practice is to use the default prompt for input and output ACD data types.

The help: attribute is shown in the help information, when the user requests assistance using the -help qualifier on the command line, or when help in other format is requested (Web page).

Again, there is a default help string in the codes.english file with the name HELPXXXX where XXXX is the name of the ACD data type.

The codes.english file includes some additional standard prompts such as GAP for gap penalties. These prompts can be used with the code: attribute, for example code: "GAP", but GUI developers found these hard to use, so we have replaced them with normal information: attributes.

2.4.1 2 Data type-specific specific attributes

The default set of attributes is available for all ACD data type definitions.

Each ACD type has its own set of specific attributes, summarized in Table 1 and described in more detail below.

2.4.1.2.1 Simple

Formalised:

Table 4.1. Simple data types - attributes.

Array

The value for an array is a set of floating point numbers with white space or commas. The size: attribute sets the number of elements in the array. As for the float data type, the minimum: and maximum: attributes define the lower and upper value limits and default to the boundaries as specified by the systems set-up. For validation purposes, the sum: attribute defines the total for all values in the array (tested unless the sumtest: attribute is false), and the tolerance: attribute specifies how closely the sum should match the total. Remember that most floating point fractions cannot be represented accurately in binary form.

Boolean

Although there are (currently) no specific attributes for a boolean ACD type, care should be taken over the definition of the information: and help: attributes. These are used to prompt the user (interactively or via a GUI), and to provide help text. The text provided in each case should reflect the expected default value of the boolean option, which may be the opposite of what the name implies. For example, if set to "Y" by default, then the command line option would typically be "-noxxx" where "xxx" is the qualifier. If set to "N" by default, then the default action may be the opposite of what the information or help text implies. If the value is calculated, the user may need some extra guidance.

The outputmodifier: attribute is set where this parameter changes the content or syntax of the output. This is provided for the developers of other interfaces and parsers of EMBOSS output so that they can fix the value, or provide parsers for each alternative.

Float

The minimum: and maximum: attributes define the lower and upper value limits and default to the boundaries as specified by the systems set-up.

The increment: attribute defines the steps that this parameter is allowed to take, in case there is a need to iterate this parameter. The increment: attribute can be any valid float value.

The precision: attribute defines the maximum number of significant decimal places that will be taken into account for this value.

Integer

The integer data type can hold simple integer values. The minimum: and maximum: attributes define the boundaries and default to the boundaries as specified by the systems setup. The increment: attribute defines the steps that this parameter is allowed to take, in case there is a need to iterate this parameter.

Range

Sequence ranges have similar attribute to integers. The minimum: and maximum: attributes define the boundaries and default to the boundaries as specified by the systems setup. The minlength: attribute defines the minimum number of values required.

The size: attribute defines an exact number of values required. The minsize: attribute defines a minimum number of values required for ranges that can be any length. Only one of these values should be defined for any range.

The value provided by the user is a list of sequence position pairs to be interpreted by the application. The upper and lower bounds (sequence positions can be negative to count back from the end) will depend on the length of the sequence to which they are applied.

String

The minlength: attribute defines the minimum length the string must be, the maxlength: attribute defines the maximum length the string can be. The default minimum length is zero. There is no default maximum.

The pattern: attribute defines a regular expression used to check the string value. ACD uses the Perl-compatible regular expression library (PCRE) so any Perl-compatible regular expression should be usable.

The word: attribute requires the result to be a valid word with no whitespace. The default minimum length of zero allows an empty string but this is not accepted as a word. This may change in future.

Toggle

Although there are (currently) no specific attributes for a toggle ACD type, care should be taken over the definition of the information: and help: attributes. These are used to prompt the user (interactively or via a GUI), and to provide help text. The text provided in each case should reflect the expected default value of the toggle option, which may be the opposite of what the name implies. For example, if set to "Y" by default, then the command line option would typically be "-noxxx" where "xxx" is the qualifier. If set to "N" by default, then the default action may be the opposite of what the information or help text implies. If the value is calculated, the user may need some extra guidance.

The outputmodifier: attribute is set where this parameter changes the content or syntax of the output. This is provided for the developers of other interfaces and parsers of EMBOSS output so that they can fix the value, or provide parsers for each alternative.  

2.4.1.2.2 Input

Formalised:

Table 4.2. Input data types - attributes.

Codon

Codon usage tables are species-specific, and in some cases specific to a class of genes within a species. This makes it useful to specify a default value for a codon usage table name. Internally, a default is set in the ACD source code. Usually this is "Ehum.cut", the human codon usage table provided in the EMBOSS distribution.

Individual codon inputs can set their own default names with the name: attribute which in the current version has the same effect as setting the default: attribute.

The nullok: attribute allows a default value to be replaced by an empty string or by -noxxx on the command line if the application can run without a data file. The application must be able to accept a null value for this qualifier.

Cpdb

Cleaned PDB file input has a default value (typically "1azu") set in the ACD source code although this is not really a good idea.

Individual cpdb inputs can set their own default names with the name: attribute which in the current version has the same effect as setting the default: attribute.

Datafile

The default datafile name is defined by two ACD attributes, name: and extension:. The directory: attribute defines the EMBOSS data subdirectory to be searched.

The nullok: attribute allows a default value to be replaced by an empty string or by -noxxx on the command line if the application can run without a data file. The application must be able to accept a null value for this qualifier.

Directory

The extension: attribute sets the extension for all files read from the directory. Files with other extensions will not be read

The fullpath: attribute can be used to require a full rather than a relative path specification for a directory.

If a null value (the current directory) is allowed,the nullok: attribute must be set true.

The nullok: attribute allows a default value to be replaced by an empty string or by -noxxx on the command line if the application can run without a directory. The application must be able to accept a null value for this qualifier.

The nulldefault: attribute overrides the default name generation, and uses an empty string (no directory) as the default for programs where a directory is only occasionally required. If an empty string is specified on the command line, the standard default value will be generated instead. In combination with the nullok: and missing: attributes, this allows qualifiers to be null by default, and turned on from the command line.

Dirlist

The extension: attribute sets the extension for all files read from the directories. Files with other extensions will not be read

The fullpath: attribute can be used to require a full rather than a relative path specification for a directory.

If a null value (the current directory) is allowed,the nullok: attribute must be set true.

The nullok: attribute allows a default value to be replaced by an empty string or by -noxxx on the command line if the application can run without a directory. The application must be able to accept a null value for this qualifier.

Discretestates

The discretestates data type can be replaced by a simple input file in GUIs, with the user required to provide the correct data format.

The attributes define characteristics required for Phylip programs.

The length: attribute defines the number of state values (the length of the discrete characters string) in each set

The size: attribute defines the number of sets of values, usually 1 but some programs will accept multiple sets.

The characters: attribute defines which discrete state characters can be specified. This is defined as a string containing all possible characters.

The nullok: attribute allows a default value to be replaced by an empty string or by -noxxx on the command line if the application can run without a discretestates file.

Distances

The distances data type can be replaced by a simple input file in GUIs, with the user required to provide the correct data format.

The attributes define characteristics required for Phylip programs. The distance matrices accepted by ACD include all the formats read by Phylip, with automatic interconversion.

The length: attribute defines the number of rows in the distance matrix.

The nullok: attribute allows a default value to be replaced by an empty string or by -noxxx on the command line if the application can run without a distance file.

Features

The type: attribute defines whether the feature input is "protein" or "nucleotide". There is a default based on the type of any input sequence, but a value should always be specified.

The nullok: attribute allows a default value to be replaced by an empty string or by -noxxx on the command line if the application can run without features input. The application must be able to accept a null value for this qualifier.

The nulldefault: attribute overrides the default name generation, and uses an empty string (no feature input) as the default for programs where a directory is only occasionally required. If an empty string is specified on the command line, the standard default value will be generated instead. In combination with the nullok: and missing: attributes, this allows qualifiers to be null by default, and turned on from the command line.

Filelist

Filelist is equivalent to infile, but allows the user to specify one or more input files.

The nullok: attribute specifies that a missing input file is acceptable to the application, and that -noxxx can be used on the command line to avoid reading the default input file (if any)

Frequencies

The frequencies data type can be replaced by a simple input file in GUIs, with the user required to provide the correct data format.

The attributes define characteristics required for Phylip programs. The frequencies files formats accepted by ACD include all the formats read by Phylip, with automatic interconversion.

The length: attribute defines the number of loci (or values) in the frequencies file.

The size: attribute defines the number of sets of values, usually 1 but some programs will accept multiple sets.

The continuous: attribute specifies a frequencies file with continuous character data values.

The genedata: attribute specifies a frequencies file with genetic locus data values.

The within: attribute specifies a frequencies file with continuous data for multiple individuals (additional values on each line).

The nullok: attribute allows a default value to be replaced by an empty string or by -noxxx on the command line if the application can run without a frequencies file.

Infile

The nullok: attribute specifies that a missing input file is acceptable to the application, and that -noxxx can be used on the command line to avoid reading the default input file (if any)

The trydefault: attribute specifies that the default filename may not exist. If nullok: is also defined as true then no error is reported.

Matrix

The protein: attribute will determine if the scoring matrix is used as a DNA or Protein matrix.

Matrixf

The protein: attribute will determine if the scoring matrix is used as a DNA or Protein matrix.

Pattern

Patterns are processed by an internal set of library functions designed to handle PROSITE-style pattern definitions.

The minlength: attribute defines the minimum length the string must be, the maxlength: attribute defines the maximum length the regular expression string can be.

The upper: and lower:attributes convert an input regular expression to upper or lower case before compiling.

The type: attribute describes the pattern as applying to nucleotide or protein sequence. Nucleotide patterns are compared in both directions.

Properties

The properties data type can be replaced by a simple input file in GUIs, with the user required to provide the correct data format.

The attributes define characteristics required for Phylip programs. The properties files accepted by ACD include all the formats read by Phylip, with automatic interconversion.

The length: attribute defines the number of values in the properties file.

The size: attribute defines the number of sets of values, usually 1 but some programs will accept multiple sets.

The characters: attribute defines which property characters can be specified. This is defined as a string containing all possible characters.

The nullok: attribute allows a default value to be replaced by an empty string or by -noxxx on the command line if the application can run without a properties file.

Regexp

Regular expressions are processed by the "Perl-Compatible Regular Expression Library" (PCRE). Any value must be accepted by this library's compilation function. Some additional attributes are provided for further validation by ACD.

The minlength: attribute defines the minimum length the string must be, the maxlength: attribute defines the maximum length the regular expression string can be.

The upper: and lower:attributes convert an input regular expression to upper or lower case before compiling.

The type: attribute describes the pattern as applying to nucleotide or protein sequence. Nucleotide patterns are compared in both directions.

Scop

Scop file input has a default value (typically "d3sdha") set in the ACD source code although this is not really a good idea.

Individual scop inputs can set their own default names with the name: attribute which in the current version has the same effect as setting the default: attribute.

Sequence

The type: attribute will force the sequence to be of the given type. By default, any sequence type is accepted.

We recommend always defining the type: attribute so that the accepted input sequence type is always clear.

If the features: attribute is set, the sequence input will include feature information either in the same file (if the sequence format supports it) or in a separate file (by default in GFF format).

If the entry: attribute is set, the sequence input will include the full original text of the input sequence or database entry.

The nullok: attribute allows a default value to be replaced by an empty string or by -noxxx on the command line if the application can run without a sequence input. The application must be able to accept a null value for this qualifier.

The sask: attribute sets the defauklt for the -sask qualifier, and if set to "Y" specifies that the program will prompt the user for a sequence begin and end position, and prompt for the reversing of a nucleotide sequence. The EMBOSS "yank" program works with fragments of sequences, and uses the sask: attribute to prompt the user.

The nulldefault: attribute overrides the default name generation, and uses an empty string (no sequence input) as the default for programs where seqeunce input is only occasionally required. If an empty string is specified on the command line, the standard default value will be generated instead. In combination with the nullok: and missing: attributes, this allows qualifiers to be null by default, and turned on from the command line.

Seqall

The type: attribute will force the sequence(s) to be of the given type. By default, any sequence type is accepted.

We recommend always defining the type: attribute so that the accepted input sequence type is always clear.

If the features: attribute is set, the sequence input will include feature information either in the same file (if the sequence format supports it) or in a separate file (by default in GFF format).

If the entry: attribute is set, the sequence input will include the full original text of the input sequence or database entry.

The nullok: attribute allows a default value to be replaced by an empty string or by -noxxx on the command line if the application can run without a sequence input. The application must be able to accept a null value for this qualifier.

The nulldefault: attribute overrides the default name generation, and uses an empty string (no sequence input) as the default for programs where seqeunce input is only occasionally required. If an empty string is specified on the command line, the standard default value will be generated instead. In combination with the nullok: and missing: attributes, this allows qualifiers to be null by default, and turned on from the command line.

The minseqs: attribute specifies a minimum number of sequences to be read. By default, a single sequence is acceptable.

Seqset

The type: attribute will force the sequence set to be of the given type. By default, any sequence type is accepted.

We recommend always defining the type: attribute so that the accepted input sequence type is always clear.

The aligned: attribute, if true, specifies that all sequences in the input are expected to be aligned. If false, then the sequences are assumed to be unaligned, and are simply read into memory together for processing. We recommend always defining the aligned: attribute so that the nature of the sequence set if clearly defined.

If the features: attribute is set, the sequence input will include feature information either in the same file (if the sequence format supports it) or in a separate file (by default in GFF format).

If the entry: attribute is set, the sequence input will include the full original text of the input sequence or database entry.

The nullok: attribute allows a default value to be replaced by an empty string or by -noxxx on the command line if the application can run without a sequence input. The application must be able to accept a null value for this qualifier.

The nulldefault: attribute overrides the default name generation, and uses an empty string (no sequence input) as the default for programs where sequence input is only occasionally required. If an empty string is specified on the command line, the standard default value will be generated instead. In combination with the nullok: and missing: attributes, this allows qualifiers to be null by default, and turned on from the command line.

The minseqs: attribute specifies a minimum number of sequences to be read. By default, a single sequence is acceptable.

Seqsetall

The type: attribute will force the sequence set(s) to be of the given type. By default, any sequence type is accepted.

We recommend always defining the type: attribute so that the accepted input sequence type is always clear.

The aligned: attribute, if true, specifies that all sequences in the input are expected to be aligned. If false, then the sequences are assumed to be unaligned, and are simply read into memory together for processing. We recommend always defining the aligned: attribute so that the nature of the sequence set if clearly defined.

If the features: attribute is set, the sequence input will include feature information either in the same file (if the sequence format supports it) or in a separate file (by default in GFF format).

If the entry: attribute is set, the sequence input will include the full original text of the input sequence or database entry.

The nullok: attribute allows a default value to be replaced by an empty string or by -noxxx on the command line if the application can run without a sequence input. The application must be able to accept a null value for this qualifier.

The nulldefault: attribute overrides the default name generation, and uses an empty string (no sequence input) as the default for programs where sequence input is only occasionally required. If an empty string is specified on the command line, the standard default value will be generated instead. In combination with the nullok: and missing: attributes, this allows qualifiers to be null by default, and turned on from the command line.

The minseqs: attribute specifies a minimum number of sequences to be read for each set. By default, a single sequence is acceptable.

Tree

The tree data type can be replaced by a simple input file in GUIs, with the user required to provide the correct data format.

The attributes define characteristics required for Phylip programs. The tree files accepted by ACD include all the formats read by Phylip, with automatic interconversion.

The size: attribute defines the number of trees in the input file, usually 0 but some programs will accept multiple sets. Some can only accept a single tree (so the value should be set to "1" for these.

The nullok: attribute allows a default value to be replaced by an empty string or by -noxxx on the command line if the application can run without a properties file.

2.4.1.2.3 Selection lists

Formalised:

Table 4.3. Selection data types - attributes.

For both selection list types, the values that the user can choose from are defined in the values: attribute as a string, delimited by the character that is given by the delimiter: attribute (which defaults to the semi-colon ';'). For the list data type there is a second delimiter ( codedelimiter:) character that defines the delimiter that separates the label from the value (defaults to the colon ":"). The minimum: and maximum: attributes define the number of choices that this parameter can handle. The header: attribute will hold the text that is displayed above the option list. The casesensitive: attribute will indicate if the options are case sensitive or not, but the value of the parameter will be exactly what the list value is. The button: attribute, which can either be Y(es) or N(o), is used in for web front ends, to indicate if radiobuttons/checkbox/selection lists are to be used or if the list is simply displayed with a text entry box beneath it, to enter the option.

List

The values: attribute contains the list of valid code names and values. The delimiter: and codedelimiter: attributes specify how to parse this string into individual list items.

The minimum: attribute specifies the minimum number of selections required. By default, 1 selection is required.

The maximum: attribute specifies the maximum number of selections required. By default, exactly 1 selection is required. A higher value allows multiple selections.

The header: attribute defines text to appear before the list is presented to the user. The information: attribute defines text to be used as a prompt after the list.

The delimiter: attribute specifies the character used in the values: string to separate list items.

The codedelimiter: attribute specifies the character used in the values: string to separate codes (names) and descriptions of list items.

The button: attribute suggests whether a list is best represented as checkboxes or radio buttons in an interface (value "Y") or as a pull-down list.

The casesensitive: attribute defines whether the input must match the exact case of the selection list item.

Example:

list: matrix [
     default: "blosum"   # default value
     minimum: 1 maximum: 1   # must select exactly 1
     header: "Comparison matrices" # printed before list
     values: "B:blosum, P:pam, I:id" 3 valid values
     delim: ","      # delimiter default ";"
     codedelim: ":"  # label delimiter default ":"
     prompt: "Select one" # prompt after list
     button: Y       # use radio buttons rather than
                      # checkboxes in HTML,
                     # ignored by ACD  ]

What you get is:

Comparison matrices

      B : blosum
      P : pam
      I : id

Select one [blosum] : PAM

Selection

The values: attribute contains the list of valid values. The delimiter: attribute specifies how to parse this string into individual selection list items.

The minimum: attribute specifies the minimum number of selections required. By default, 1 selection is required.

The maximum: attribute specifies the maximum number of selections required. By default, exactly 1 selection is required. A higher value allows multiple selections.

The header: attribute defines text to appear before the selection list is presented to the user. The information: attribute defines text to be used as a prompt after the list.

The delimiter: attribute specifies the character used in the values: string to separate list items.

The button: attribute suggests whether a selection list is best represented as checkboxes or radio buttons in an interface (value "Y") or as a pull-down list.

The casesensitive: attribute defines whether the input must match the exact case of the selection list item.

Example:

select: matrix [
       default: "blosum"  # default value
       minimum: "1" maximum: "1"  # must select exactly 1
       header: "Comparison matrices" # printed before list
       values: "blosum, pam, id" # valid values
       delimiter: ","     # delimiter default ";"
       information: "Select one" # prompt after list
       button: "Y"      # use radio buttons rather than
                      # checkboxes in HTML,
                      # ignored by ACD
  ]

What you get is:

Comparison matrices

      1 : blosum
      2 : pam
      3 : id

Select one [blosum] : PAM

2.4.1.2.4 Output

Formalised: