For convenience the available ACD datatypes are organised into five groupings reflecting similar properties or modes of usage as follows:

The groupings are described below and in some cases are subdivided further for convenience. See also a complete description of the available datatypes including their data value, default value and key attributes (Section A.2, “Datatypes”).

The simple datatypes (Section A.2.1, “Description of Simple ACD Datatypes”) include primitive and some derived datatypes:

The input datatypes (Section A.2.2, “Description of Input ACD Datatypes”) cater for input of sequences, sequence features, files and directories, inputs specific to the phylipnew EMBASSY package, data files and other files of biological data.

The output datatypes cater for output of sequences, sequence features, alignments, files and directories, outputs specific to the phylipnew EMBASSY package, data files, other files of biological data and formatted application output files (reports). See Section A.2.3, “Description of Output ACD Datatypes”.

The selection datatypes cater for menus (Section A.2.4.2, “selection”.

The user is presented with a limited list of options they can choose from. An option consists of a label and descriptive text. One or more options may be selected. Selection datatypes include:

The data value is one (or more) of the valid options. An option is specified by label (whether text or numerical) or by a non-ambiguous part of the descriptive text itself given after the label. If multiple selections are allowed then the user must supply a comma-separated list of options.

The graphics datatypes cater for graphical output (Section A.2.5, “Description of Graphics ACD Datatypes”.

Graphics datatypes include:

The data value is a supported graphics device (Section A.2.5, “Description of Graphics ACD Datatypes”).

Each application parameter, i.e. every data definition in the ACD file, can be defined via the appropriate global attribute to be one of a "parameter", "standard qualifier" or "additional qualifier" with the default of "advanced qualifier". These four types have different properties in terms of how they may be specified on the command line, how they are prompted for and the location of the help information. See Section 4.3, “Data Definition” for further information.

The attributes have boolean values and are defined as follows:

parameter:  "Boolean"    ("N")
standard:   "Boolean"    ("N")
additional: "Boolean"    ("N")

The default value is "N" however this is never specified explicitly in the ACD file (see Section 4.3, “Data Definition”).

Reports. The report datatype, where used, is typically a primary output of an application and, as such, should be defined as a parameter using the parameter: attribute. The first report file must be defined as parameter: (an error will be generated during ACD processing otherwise). It is recommended that subsequent report definitions (second, third and so on) are also defined as parameters (a warning will be generated during ACD processing if they are not). The exception is if the default: or nullok: attributes are set, in which case no warning or error messages are generated as the application can run with a default or without any value for the definition respectively.

Sequences. Sequence inputs (sequence, seqall, seqsetall or seqset ACD datatypes) and outputs (seqout, seqoutall and seqoutset ACD datatypes) are typically the primary input or output of an EMBOSS application, and as such should be defined as parameters in the same way as for the report datatype above.

Features. Sequence features, where used, are typically the primary input (feature ACD datatype) or output (featout), as such, should be defined as parameters in the same way as for the report datatype.

Alignments. The align datatype, where used, is typically the primary output and should be defined as a parameter. The first and subsequent alignment outputs should be defined as parameter: types, a warning will be generated during ACD processing if they are not. The exception is if the default: or nullok: attributes are set, in which case no warning or error messages are generated as the application can run with a default or without any value for the definition respectively.

Files. File datatypes, where there are used, are typically the primary input (infile, filelist, directory or dirlist ACD datatypes) or output (outdir ACD datatype) and should be defined as parameters in the same way as for the report datatypes described above.

The attributes below are used to provide the text that will be used on the screen to prompt the user for values. Whether a prompt will appear at all depends on whether the option was defined as a parameter or one of the qualifier types (see above) and on the command used to invoke the application (i.e. what options were specified). In some cases, the prompt may or may not appear depending on the value of other inputs. For more information see Section 4.5, “Controlling the Prompt”).

The attributes are defined as follows (the strings are empty by default):

information: "String"      ("")
code: "String"             ("")
prompt: "String"           ("")

Only one of code:, prompt: or information should ever be defined. The use of information: (with a standard name, see below) is preferred. In practice, prompt: is only ever required in the rare cases where the information: string might be misleading.

To provide standard prompts a default value for the information: string is defined for most common datatypes (see Section 4.3.5.2.1, “Standard Prompts File (codes.english)”). The standard practice is, where possible, to use the default prompt for all input and output ACD datatypes. A warning will be generated during ACD processing if either the information: attribute is missing or if the value used is not the standard value (where a standard value is available).

If a non-standard prompt is used, the text given after the information: attribute should conform to certain conventions (Section A.4.4.1, “information: "String" ("")”

In the example below a non-standard prompt is defined for asequence. A warning will be generated if you try to run this:

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

In the next example, no information: string is specified, therefore the standard prompt of "Read sequence from" (from codes.english) would be used instead:

sequence: asequence 
[
    standard: "Y"
]

#
# This is the EMBOSS coded prompts file. Any messages found here will
# override those in the .acd file, and can be translated into other
# languages. The file extension (default "english") is set by the
# variable "emboss_language"
#
# Messages are referred to by .acd files as code: NAME
#
# DEFXXXX codes are automatically searched for ACD type XXXX if there
# is no information (or prompt) defined in the ACD file of as a
# standard prompt for the ACD type.
#
# HELPXXXX codes are automatically searched for ACD type XXXX if there
# is no help text in the ACD file.
#

# Default prompts: these are used where no prompt for a data type
# has been provided.

DEFALIGN     "Write output alignment to"
DEFREPORT    "Write output report to"
DEFINTEGER   "Enter a number"
DEFFLOAT     "Enter a number"
DEFBOOL      "Yes or No"
.
.
.
# Gap penalties

GAP          "What gap penalty"
GAPEXT       "What gap extension penalty"

Five global attributes are associated with, or describe, the data to which the ACD definition refers. For example, a parameter can be given a default value, be assigned to a known type taken from a controlled vocabulary, or its relations to other parameters described. The attributes are defined as follows:

knowntype: "String"        ("")
default: "Value"           ("")
relations: "String"        ("")
outputmodifier: "Boolean"  ("N")
missing: "Boolean"         ("N")

knowntype: is a string describing the type of a data definition and should be defined where the type is not already clear from the datatype itself. It is typically defined for string:, infile:, outfile: and outfileall datatypes but not, for example, for a sequence:.

Valid known type strings are listed in the file knowntypes.standard (Section 4.3.5.3.1, “Application Data Known Types File (knowntypes.standard)”). A few other values are accepted, for example "ApplicationName output" for an outfile datatype. These are documented with the datatypes (Section A.2, “Datatypes”.)

If a value is given that is not a standard known type or other accepted value, a warning message will be generated during ACD processing. The acdvalid utility will check all knowntype values in an ACD file, and report any missing values for data definitions that require a known type.

# Known Types
# Knowntype_string                Type           Comment
aaindex_data                      file           AAINDEX entry
aaindex_database                  file           AAINDEX database
abi_trace                         file           ABI sequencing trace
ajint_ajlong_data                 file           Standard format info on ajint and ajlong
alistat_input                     file           HMMER alistat program input
alistat_output                    file           HMMER alistat program output
amino_acid_classification         file           Amino acid chemical classes data
.
.
.

Every EMBOSS application accepts the global qualifiers -help and -verbose, the latter used in combination with the former (if at all). When an application is run with -help, helpful information is printed to the screen, including all the program parameters and qualifiers with explanatory text alongside.

The attributes below define the text that's used:

help: "String"             ("")
valid: "String"            ("")
expected: "String"         ("")

help: is usually only defined if a deeper explanation of an application parameter is needed. If help: is not defined, the value of the information: attribute (if available) or the default help string (see below) will be used instead. valid: and expected: are used to describe the allowed and expected values for the online documentation. They are not usually required as, in most cases, a reasonable value is generated automatically.

An example where help: is helpful:

integer: window 
[
    standard: "N"
    default: 10
    minimum: 5
    maximum: 100
    information: "Window size"
    help: "Number of residues used to calculate the value for each point"
]

The help: string must conform to certain conventions (Section A.4.6.1, “help: "String" ("")”).

HELPSEQUENCE  "Sequence USA"
HELPDIRECTORY "Directory name"

The needed: global attribute indicates whether a parameter is expected to be included in a GUI form. It is used to help GUI developers and more such attributes may be added in the future as support for external developers is improved. Certain datatype-specific attributes, for example button: which can be defined for selection lists, are also used to provide such hints. See Section A.5, “Datatype-specific Attributes”.

The attribute is defined as follows:

needed: "Boolean"            ("Y")

The following attributes provide metadata for the SOAPLAB project. They are not used by EMBOSS directly and should not appear in standard EMBOSS application ACD files.

The attributes are defined as follows:

qualifier: "String"        ("")
template: "String"         ("")
comment: "String"          ("")

These are used to validate user input.

These are used to specify the input data and to validate user input.

These are used to specify the output file and in some cases exactly what data is generated and how it is validated.

These control the aspects of the menus (lists of options) the user is presented with. For example, the text appearing above the menu, and how user input is validated, the minimum and maximum number of selections and whether the options are case-sensitive.

For example, consider this ACD list definition:

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 on screen is:

Comparison matrices

      B : blosum
      P : pam
      I : id

Select one [blosum] : PAM

With this ACD list definition:

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
]

You get:

Comparison matrices

      1 : blosum
      2 : pam
      3 : id

Select one [blosum] : PAM

These specify the graph data that are output.

gtitle: specifies the graph title for a graph or graphxy datatype. Many other graphical elements can be set.

multiple: specifies the number of multiple graphs in a single graph or graphxy datatype output.

The nullok: and nulldefault: attributes are available for both graphics datatypes. They have exactly the same meaning as for the output datatypes (see above).

Values of calculated attributes are retrieved by an operation (Section 4.4, “Operations”) from within the ACD file. The operation uses a ParameterName.AttributeName term surrounded by parentheses with a dollar sign ($) at the front:

$(ParameterName.CalculatedAttributeName)

The $ syntax means "get the value of", in this case the term enclosed by parentheses.

This is typically done from within a data definition that relies on the value of a calculated attribute from some other data definition. For example, the following ACD file excerpt defines a sequence parameter and an integer window:

sequence: sequence 
[
  parameter: "Y"
  type: pureprotein
]

integer: window 
[
  standard: "y"
  default: "10"
  maximum: "$(sequence.length)"
]

The maximum window size (maximum attribute of the window datatype) is being set to the length of the sequence by using maximum: "$(sequence.length)".

All of the sequence input datatypes:

have six calculated attributes:

Let's assume we've defined a sequence input called asequence and have an ACD file looking something like:

sequence: asequence 
[
  parameter: "Y"
  type: protein
]

The attributes would be referred to as follows:

These are properties of an input sequence that can be queried within ACD.

The seqset and seqsetall datatypes have the following calculated attributes :

seqsetall also has :

To retrieve calculated attribute values from the definition of asequence shown above you can use:

$(asequence.begin)
$(asequence.end)
$(asequence.length)

Example. When writing a program to insert one sequence into another, one way to make sure that the insertion position isn't greater than the length of the first sequence is to use code like the following:

    if(position > ajSeqGetLen(seq))
       ajFatal("Insertion position out of bounds");

The problem is that the program can prematurely terminate after the user has gone to all the effort of configuring the application (entering all the inputs). What would be better is if the interface forced the correct input, and there is a way to achieve that by using calculated attributes in the ACD file itself.

Now, instead of hard-coding the check for the sequence insertion position you just need to add:

maximum: $(asequence.end)

to the integer definition of the insert position. An ACD file with two input sequences and an integer insert position might look something like:

sequence: targetsequence 
[
  parameter: "Y"
  type: "protein"
]

sequence: insertsequence 
[
  parameter: "Y"
  type: "protein"
]

integer: position
[
  parameter: "Y"
  maximum: $(targetsequence.end)
]

You may of course retrieve the value of calculated attributes from both sequences. In the following example, a sequence window is defined which cannot be any longer than the sum of the lengths of the two sequences. A calculation is used, which therefore has to be enclosed by parentheses and started with the 'at' symbol ('@'):

integer: window
[
  parameter: "Y"
  maximum: @($(targetsequence.length) + $(insertsequence.length))
]

These calculated attributes are also useful for conditional statements. In the example below the sequence input is of the any type. A ternary conditional (see Section 4.4, “Operations”) is being used to set a default substitution matrix based on the automatically determined type of sequence:

sequence: sequence 
[
  parameter: "Y"
  type: "any"
]

integer: penalty 
[
  parameter: "Y"
  default: "@($(sequence.protein) ? EBLOSUM62 : EDNAFULL)"
  etc
]

The sequence feature input datatype:

has seven calculated attributes:

These are properties of an input feature that can be queried within ACD.

Assuming you've defined a feature input called afeatures and have an ACD file looking something like:

features: afeatures
[
  parameter: "Y"
]

The attributes would be referred to as follows:

and so on.

To retrieve calculated attribute values from your definition of afeatures above you can use:

$(afeatures.begin)
$(afeatures.end)
$(afeatures.length)

Example. When writing a program to compare the features of two sequences, which might be protein or nucleotide sequences, you need to ensure that both sequences are of the same type. One way to do this from the application code is to call an AJAX function to return the type of both, and exit if they are not the same:

if((ajFeattableIsProt(features1) && ajFeattableIsNuc(features2)) ||
  (ajFeattableIsNuc(features1) && ajFeattableIsProt(features2))
   ajFatal("Input feature tables are not of the same type");

The problem with this code is that the application will terminate once it is running if the feature tables are not of the same type. The user, having gone to the effort of configuring the application, will not be impressed! Far better if the interface forced the correct input before the application proper started, which can be achieved by using calculated attributes in the ACD file itself.

Assume the application takes two feature table parameters as input and the ACD file therefore looks something like:

features: afeatures
[
   parameter: "Y"
]

features: bfeatures
[
   parameter: "Y"
]

Instead of hard-coding the check for feature type, it can be enforced on the second of the features that is read: the first feature table can be of the any type but the second must match the first. This is achieved by declaring the type: attribute for the feature tables. The type: of the second feature table is set to that of the first by retrieving the fprotein calculated attribute of the first feature table in a ternary conditional (see Section 4.4, “Operations”):

features: afeatures
[
   parameter: "Y"
   type: "any"
]

features: bfeatures
[
   parameter: "Y"
   type: "@($(afeatures.fprotein) ? protein : nucleotide)"

]