Sequence is an explicit sequence in either upper or lower case, for example:

Format must be a name of one of the valid sequence formats (Section A.1, “Supported Sequence Formats”).

The sequence format may usually be omitted when reading in a sequence; EMBOSS will try most known sequence formats until it can read the sequence.

ListFileName is the name of a listfile: a file of USAs with one USA per line. Either @ or list: are required before the name of the listfile to indicate that it is a listfile. Listfiles may be nested (a listfile may contain the USA of another listfile).

Where the sequence specification [start : end : reverse] is used, then all the USAs in the listfile are affected, unless these USAs have their own [start : end : reverse] specifier in which case that given on the command line is overridden.

This also holds true where the sequence is specified with the -sbegin or -send or any other command line qualifier (Section 6.4, “Datatype-specific Command Line Qualifiers”) which affects the input sequence: all USAs in the listfile are affected unless they have their own sequence specification.

DatabaseName must be a valid database name as defined in the EMBOSS configuration files (Section 2.8, “Maintenance”).

If the name is not a valid database, a file with the same name is looked for instead. Database names may have Search Field names appended to them (for example embl-des, embl-id) (see below).

FileName is a filename which can be wildcarded.

Entry specifies the ID name or accession number of one or more sequences in a database or file. If it is omitted, then all the files in the database or file will be read. Entry may be wildcarded. For example hs* will match all ID names starting with hs.* indicates that all entries in the database or file will be read.

There may be restrictions on certain databases preventing access to a single entry, wildcarded entries or reading in all entries. This is a consequence of the way some databases are accessed. The restrictions are given in the database definition (see the EMBOSS Administrators Guide).

A database or file location must be given as part of a USA that has an Entry; you cannot give an entry name on its own, i.e. you cannot give just an accession number or ID name and expect EMBOSS to deduce that it is indeed an accession number or ID name and to which database it might refer.

SearchField is the name of one of the available search fields shown in the table (Table 6.3, “Sequence Retrieval Search Fields”).

Word is the keyword to search for in the search field. Words may be wildcarded.

Words in ORG and KEY fields may contain spaces because the complete key-phrase or organism classification level (the text field (including spaces) between the semicolons (;) delimiting sections of these fields) is indexed as one 'word'.

Words in the DES field contain only alphanumeric characters and thus end at spaces or other non-alphanumeric characters.

The words in ID and ACC fields are equivalent to Entry above.

Program is the name of a sequence retrieval application in the current path. ProgramParameters are any parameters it takes in order to specify one or more entries.

Any USA may optionally take a subsequence specifier after the main body of the USA in one of the following forms:

Where start and end are the required start and end positions. Negative positions count from the end of the sequence. Zero values for start and end stand for the default values, i.e. position 1 and the length of the sequence respectively.

Use of the USA subsequence specifier is equivalent to using the -sbegin or -send or -sreverse command line qualifiers. For more information see Section 6.4, “Datatype-specific Command Line Qualifiers”).

The database name is specified in a USA before either an entry to retrieve or a search field:

The name of any database you've defined in your EMBOSS installation can be used. Databases are defined in your EMBOSS configuration files (Section 2.8, “Maintenance”). To find out what local databases are available run:

This will give a table of the database names, whether they are protein or nucleic and the types of access that is possible (see below). If EMBOSS was set up by your system administrator it's likely that one or more of the following major databases will have been set up:

Abbreviations of these names are often used, for example em for databases in EMBL format. There is no standard naming scheme for databases because total control over database setup (including naming) is given to you or your local system administrator (the person who set up EMBOSS at your site). The dot character ('.') is, however, not allowed in database names. EMBOSS interprets a '.' character as being part of a file name.

The simplest way to specify a database entry in a USA is:

where DatabaseName is the name of a database and Entry is either the sequence's accession number or ID in that database. For example:

EMBOSS will try searching for your specified sequence by both the accession number field and the ID name field. You don't need to specify whether you gave the accession number or ID. The database name and entry are case-insensitive: they can be in either upper or lower-case. For example: EM:AF061303 is the same as em:af061303.

You cannot specify a sequence in EMBOSS by giving just the ID name or accession number; the database name must be given. You cannot therefore just give X65923 and expect EMBOSS to know what this is - it will assume that X65923 is the name of a database or a file which of course is unlikely to exist.

It's common to run an application on all the entries in a database. This can be done by just giving the name of the database. Typically, however, an asterisk is used to indicate all entries are required. Either of the following therefore refer to all of the entries in the EMBL database:

Often a set of wildcarded entry names in a database are required. Wildcard text is specified by a * whereas a single wildcard character is specified by using a ? character. For example:

refers to all the human entries in swissprot (strictly, it is all the entries in swissprot whose names end in _human.)

The specifications for a complete database or wildcarded entry names both refer to multiple entries in a database, but are implemented in EMBOSS in a very different way. When all entries are read, the application starts at the beginning of the database and reads an entry at a time. In contrast, reading wildcarded entries requires an index file of entry ID names and accession numbers. The index file is queried and gives the positions in the database of those entries whose names match the wildcarded specification. For more information on database indexing see the EMBOSS Administrators Guide.

Not all databases will be searchable by all types of sequence specifications. For example, databases that are set up to access a web site will probably not allow retrieval of wildcarded entry name specifications or complete databases: it would take too long to transfer the files across the Internet!

The application showdb will give a list of the available databases, together with the ways in which they can be accessed. This information is given under the three columns ID, Query and All:

Ideally all of the databases available on your site will be available using all three methods, but this may well not be the case, so you should check how you can access the databases by running showdb.

% seqret
Reads and writes (returns) sequences
Input sequence(s): embl:*
..

Most sequence formats allow files to contain more than one sequence in the same file. Some formats however, such as gcg, plain, raw, staden do not: they have no indication of where the sequence ends and the next sequence starts.

If just the name of the file containing multiple sequences is specified, then all the sequences in that file will be read. This is the equivalent of specifying filename:*. For example

is the same thing as

The simplest way to specify a single specific sequence in a file containing multiple sequences is:

where FileName is the name of a file and Entry is the sequence's ID name or accession number in that file. For example the following USA would specify a sequence in the file myfile.fasta whose ID name is xyz_123:

As for database entries, you cannot specify a sequence in EMBOSS by giving just the ID name, the file name must be given.

To help GCG users, an additional syntax is allowed where the entry name is enclosed in curly brackets:

When given on the command line the brackets must be escaped as follows:

To specify wildcarded sequence names, the wildcard characters '*' and '?' are again used. When used on the command line (but not in response to an EMBOSS prompt) they must be enclosed in quotes or preceded by a backslash. For example:

will read in all sequences in the file myfile.fasta whose ID name starts with IXI.

To specify a wildcarded set of file names the characters * and ? are again used. For example:

will read in all sequences in the files whose base names start with myfile.

The id and acc search fields can normally be omitted. If no search field is specified, (for example embl:X13776), then the default is to search for a match in both the id and acc fields .

Using database-acc:AccessionNumber or file:acc:AccessionNumber is a way of telling EMBOSS that it need not try to search for the entry by testing both the ID name field and the accession number field; it only needs to test accession number. This is allowed for ID too, for example, database-id:ID. Specifying the acc and id search fields will make accessing the sequences slightly faster, but they are not required. EMBOSS applications report USAs in this style however, so do not get alarmed when you see it.

The ORG, KEY and DES fields have the following meaning:

Searches in these fields are by word. For example embl-des:fau will search for the text "fau" in the description field. If you wish to search for part of a word, use an asterisk to indicate a wildcard. For example: embl-des:h*emoglobin. The searches are case-insensitive: 'Human' is the same as 'human'.

The definition of a 'word' in KEY and ORG searches is anything that matches the text field (including spaces) between the semicolons (;) delimiting the sections of these fields, or the entire field if no sections are described as is the case for the KW field in the EMBL example above.

Therefore, embl-key:"fau gene" would match the entry X13776 displayed above, as would embl-key:fau*, but embl-key:fau would not match it.

Similarly, embl-org:"homo sapiens (human)" and embl-org:*human* and embl-org:hominidae would match this entry, but embl-org:human would not match it as the 'word' that contains "human" is "Homo sapiens (human)". The search embl-org:homo would match as the word "Homo" occurs in its own field at the end of the second OC line.

The definition of a 'word' is much more intuitive in DES searches: a 'word' is bounded by spaces and other non-alphanumeric characters. Words start with a letter or number, and end with a letter or number. SRS typically does the same, but allows a single quote at the end. This catches words such as 3' and 5' but is a problem with some quoted text.

Therefore embl-des:fau and embl-des:sapiens match. "H.sapiens" is not a word - it is split into the words 'H' and 'sapiens' because the dot (.) is not an alphanumeric character. Phrases don't work for the DES field; it is word based, so the search embl-des:"fau mRNA" will fail.

Sequence versions are formed from the accession number followed by a full stop ('.') and then the number of releases there have been of this sequence. (e.g. X65923.1). It makes it possible to find the current version of any sequence and to find the SV of all previous versions. Further, a sequence may be unambiguously identified by the sequence version, for example: embl-sv:X65923.1 Care is needed however. In February 1999, everything in DDBJ/EMBL/GenBank was assigned version 1, even if it was the 1st or 10th version for a given sequence. Consider the entry below:

ID   AC000003; SV 1; linear; genomic DNA; STD; HUM; 122228 BP.
XX
AC   AC000003;
XX
DT   01-OCT-1996 (Rel. 49, Created)
DT   07-MAR-2000 (Rel. 63, Last updated, Version 6)
XX
DE   Homo sapiens chromosome 17, clone 104H12, complete sequence.
XX
KW   HTG.
XX

The entry AC000003 shows version 1, but is really the third sequence version (3rd gi) for that record (see http://www.ncbi.nlm.nih.gov:80/entrez/sutils/girevhist.cgi?val=AC000003). Rather confusingly, the version on the DT line has nothing to do with the sequence version (SV)

If, after Feb 1999, the author had updated the sequence of AC000003, then that new one would be version 2 (AC000003.2) and it is a lot easier for a human to track sequence version changes when you see the incremental increase. Bear in mind that just because you are looking at SV X00001.1 it doesn't mean you have the first version that was ever in the databases (DDBJ, EMBL, GenBank).

Both sequence version identifiers and GI numbers (see below) share the sv field in USAs.

GI numbers are assigned to entries in GenBank and other sequence databases originating from the NCBI. They are an integer key for identifying the entry version. For example:

VERSION     AF181452.1  GI:6017929
            ^^^^^^^^^^  ^^^^^^^^^^
            Compound    NCBI GI
            Accession   Identifier
            Number

The NCBI GI identifier on the VERSION line serves as a method for identifying the sequence data that has existed for a database entry over time. GI identifiers are numeric values of one or more digits. Since they are integer keys they are less human-friendly than the accession version system described above. If the sequence changes a new integer GI will be assigned.

A sequence may be unambiguously identified by the GI Number, for example: genbank-sv:6017929.

Two methods for identifying the version of the sequence associated with a database entry are used because:

Both sequence version identifiers (see above) and GI numbers share the sv field in USAs.

The start and end of the sequence is specified by appending [start:end] to the end of the USA. For example:

specifies the sequences in the file myfile.fasta starting at 20 and ending at position 45.

If the 'start' or 'end' position is given as a negative number, then the position is counted from the end of the sequence. For example:

specifies the last 10 residues.

If [start:end:r] is given at the end of the USA, then nucleotide sequenced are reverse-complemented. For example:

is the whole sequence reverse-complemented.

Zeros can be used to denote the start and end of the complete sequence. For example, the entire sequence may be specified by:

USA Examples