Bioinformatic Sequence Markup Language

BSML™ 2.2 Sequence Tutorials

Table of Contents

1. Introduction to the BSML Sequence Tutorials *

2. What Is BSML? *

3. Why Use BSML? *

Note: A full set of example BSML documents is included with the installation of the Genomic XML Viewer™. This set of BSML documents illustrates the content encoding available with BSML 2.2.

BSML is primarily concerned with biological sequences – DNA, RNA, and protein. The information of interest falls into two general categories – sequence data (sequencing runs, clones, contigs, cDNA, etc.) and sequence annotation (assertions about the properties of sequences). BSML was developed under a 1997 grant from the National Human Genome Research Institute, with the goal of creating a public domain standard for representing this information. The purpose of these tutorials is to enable people in two communities – life sciences and information technology – to make effective use of BSML. The first few tutorials in this series provide a general answer to three questions:

• What is BSML?
• Why is BSML useful?
• How can BSML be used?

BSML users. Within the life sciences and information technology disciplines, there are two general audiences to which these tutorials are directed:

• Producers - people who are interested in creating BSML content
• Consumers - people who are interested in using information encoded in BSML

Of course, a single individual or organization may be both a producer and a consumer. A scientist may wish to interact as a consumer with data already encoded in BSML, and then as a producer to edit the existing content by adding new annotation. After the general introduction, we present tutorials on the use of BSML by producers and consumers.

BSML, XML, and software. BSML is an XML application. This means that any software that can read XML can read BSML, and any software that can render XML in a generic way can render BSML. For example, an XML-aware HTML browser is capable of displaying BSML as text. However, generic software will have little capability to visualize sequence information in the way that was intended for data encoded in BSML. Similarly, software that is not "bioinformatics-aware" will not be able to process the links to information resources contained in BSML documents (e.g., a cross-reference to a public database).

Sequences may be described at various levels: complete genome, chromosome, regulatory region, gene, transcript, gene product, and so forth. Each of these levels may be thought of as defining a type of biological object. BSML is useful in simply capturing the semantics of biological objects, but it is especially useful in conjunction with appropriate software that enables interactive access to the full range of information that BSML can encode.

Why is software important? First, information technology makes it possible to render information in ways that are simply not available through print media. The ability to navigate through an information space using zooming and linking technologies brings new dimensions to information access. Second, life scientists are accustomed to visualizing biological objects and to communicating graphically about these objects and their annotations. Thus the capabilities of graphical rendering software are well suited to the communication needs of life scientists.

For these reasons, we devote several tutorials to the relationship between BSML and rendering software, with emphasis on the BSML browsers available from LabBook, Inc., including the free Genomic XML Viewer. (See Rendering BSML in the Genomic XML Viewer.)

XML and HTML. XML (eXtensible Markup Language) was developed by the World Wide Web Consortium (W3C) as a language that builds on the strengths of HTML (HyperText Markup Language) and corrects some of its deficiencies. For example, XML also embodies the use of links to connect one document element with another. At the same time, XML presents a model for capturing semantic content rather than presentation style, the latter being the focus of HTML.

To illustrate this difference, consider the representation of "Jane Doe" in a document. In an HTML document, the name might be represented as:

This notation tells the rendering software (HTML browser) to display the name using a bold (<B>) font. However, the HTML encoding does not truly distinguish this content as a person's name, and a search of HTML pages may have difficulty separating this "Doe" from "doe", a female deer, and "DOE", the Department of Energy. An XML encoding might state:

"Tags" (e.g., <Person>) are used in both cases to "mark up" the content, but only in the XML case do the tags capture the semantics of the content, i.e., that "Jane Doe" is a person's name consisting of a last name and a first name.

BSML is XML. Technically, BSML is an XML application that is represented by a Document Type Definition (DTD). This means that BSML conforms to the XML standard - a BSML document contains XML content that can be read by any XML parsing software and determined to be well-formed XML. Because of the BSML DTD, the parsing software may also validate the document to determine that it complies with the document rules specified in the BSML DTD.

BSML documents. BSML documents are documents. This means that they are readable by people as well as machines. A complete BSML document begins with the standard XML processing instruction and a reference to the BSML DTD:

The document content is enclosed between Bsml tags. This element is defined in the 2.2 DTD as:

General information (document author, creation date, etc.) may be attached to the entire document by using Attribute and Info elements.

BSML and Bioinformatic Sequences. BSML is not intended for the description of geological strata or subatomic particles. It is an XML application in the domain of bioinformatic sequences. BSML makes use of much of the functionality provided by XML and related standards, but to understand BSML requires understanding how it is applied in its domain.

Within the <Bsml> tags, the document is divided into two major sections, each of which is optional:

• Definitions – encoding of genomes and sequences, data tables, sets, and networks
• Display – encoding of display widgets that represent graphical representations of biological objects

Note: BSML builds on various public standards for the representation of information, such as NCBI's (the U.S. National Center for Biotechnology Information) representation of GenBank content.

What characteristics of a biological sequence provide enough information to identify and describe the sequence? The information needed to accomplish these tasks is encoded in the Sequence element of BSML.

The minimum information needed to describe a sequence is an indication of the type of molecule that is being represented and its length in residues. BSML represents all of this information using attributes and their values, which are encoded in the XML as:

For example, the most basic description of a sequence might be:

This identifies a DNA sequence that is 1000 bp long. In the DTD, we define these attributes as follows:

This means that molecule is an attribute that can only take on a limited set of values (a controlled vocabulary) and that the default value is dna. (The notation (x|y|z) means one of the members of the set of x, y, and z.)

The length attribute may theoretically be any text (CDATA=character data), but in practice must be an integer that represents the number of residues.

In practice, we usually want to know more about a sequence than its molecule type and length, especially in the case of DNA.

DNA strands and topology. DNA is typically characterized as single- (ss) or double-stranded (ds), and its shape is typically characterized as linear or circular. BSML provides two attributes for presenting this information:

Thus a double-stranded linear DNA fragment might be described as:

Ends of Linear Double-stranded DNA. If a DNA fragment is the result of a sequencing project, we are not likely to be concerned with characterizing the ends of the fragment, regardless of the procedure (PCR, restriction) used to manipulate the fragment during sequencing. On the other hand, if the fragment is the product of a cloning procedure, characterizing the ends of the fragment may be very important. BSML provides a set of tags for describing the 5' overhang on each end and the phosphorylization state of each end:

Note: These attribute definitions use entities that tell us how to interpret the text value of the attribute. Thus %integer; is defined to indicate that the text must be resolved to an integer value (positive or negative). Similarly, %yesorno; is defined to mean that "1" indicates "yes" (logical true) and "0" indicates "no" (logical false).

If a fragment has been cut at its 5' end by a blunt cutting restriction enzyme, that end has been kinased, and if the other end was produced by cutting with EcoRI, the fragment might be described as:

In this case, the length of 1000 refers to the length of the coding strand.

Sequence representation. In some cases, we are simply interested in stating that a particular sequence exists, without describing its sequence data. Such a representation may be defined as virtual. In other cases we wish to explicitly provide the sequence data as part of the definition of this sequence – a representation termed raw. Following the model of NCBI, BSML provides the following controlled vocabulary for this attribute:

Thus a sequence representation that contains protein sequence data might be encoded as:

Beyond the description of a sequence, we typically want to identify the sequence. Identification may mean several things.

Sequence title. BSML provides a number of attributes that apply to most elements, including title and comment. The title attribute generally contains the displayable name of an element: the text that is shown to a user to identify the element. The comment attribute may contain additional information or a more extended version of the title. For example:

Private sequence source. One common need is to identify where a sequence came from. If the sequence was determined in a local laboratory, the identification may consist of describing the machine and sequencing run. There may well be some unique local identifier that may be captured in the following attribute:

For example:

Public sequence source. Another principal source of sequences is the international consortium of public database (GenBank, EMBL, and DDBJ). BSML provides three attributes to identify sequences from sources such as these:

For example:

Additional identification. Although a great deal of identification is explicitly represented in the attributes defined by BSML for sequences, there may always be additional descriptions that the BSML creator wishes to associate with a sequence. The Attribute element is provided for this purpose. For example, the following elements might be added to a GenBank description:

XML element identification. In the world of XML, an element may be identified by an attribute that is designated as its unique identifier, which means that the element must be uniquely identified in the XML document containing it. In the case of BSML, this attribute is the id attribute, which may be defined for almost all BSML elements. We may choose to use a unique public identifier (e. g., an EMBL accession key) as the id, for example:

Alternatively, we may wish to use an identifier that is unique to a private library of sequences, even if the source of the sequence is a public database:

Sequence positional context and identification. To be more explicit about the position of a sequence on a genome, we may use the Numbering element to relate a particular sequence to a larger context.

Internally, the length of every sequence is expressed as a positive integer. Sequences and other sequence-related elements may specify their unit of measurement (bp, cM, etc.) through the use of a Numbering element, which also may define a relative numbering basis or a linear transformation rule for converting internal sequence positions to display values. By using various reference attributes, a Numbering element may indicate the location of a sequence in a larger context, e.g., the location of a sequence on a clone or the location of a clone on a chromosome. By chained references, a sequence may be placed in more than one positional context. The following example illustrates how a sequence (id='SEQ1") may be located on the complementary strand of a clone (id="CLONE1"), which is, in turn, located on the coding strand of a chromosome (id="CHR1"), thus establishing the positional context of the sequence:

If the representation of a sequence is raw, the sequence data are contained within the Sequence element, either directly or by reference to an external file containing the sequence data.

Direct inclusion of sequence data. Sequence data are included directly using the content of a Seq-data element. For example:

The data are represented by single character IUPAC codes and the representation is not case-sensitive (e.g., AKFFGLKL=akffglkl). Any whitespace (blanks, etc.) and characters not included in the IUPAC alphabets for amino acids and nucleotides are ignored; thus the following is valid:

External file storage of sequence data. The Seq-data-import element is used to refer to an external URL that may be accessed to obtain the sequence data. In addition to an ASCII text file containing IUPAC codes that may be interspersed with whitespace and non-sequence characters, the format may be one of the following:

For example:

The term "sequence annotation" is not rigorously defined within the bioinformatics community. In BSML, the term is used to refer to a variety of elements that provide information about a sequence beyond the sequence data. Some annotation refers to the sequence as a whole or to characteristics that are not associated with any particular region of the sequence. This annotation is considered nonpositional. Other annotation refers explicitly to a region of the complete sequence and is considered positional.

Features. Positional annotation in BSML is handled mainly through a Feature-table element, which is contained within Feature-tables and may contain any number of Feature elements:

The Feature element itself defines the position of a feature (with an Interval-loc or Point-loc element) and may add a variety of information in the form of Qualifier elements. For example:

The purpose of allowing many Feature-table elements is to allow features to be grouped so that Feature-table elements may be selected for particular views of a sequence. Thus, the following organization might be used:

The numbering used for features in Interval-loc or Point-loc elements is defined relative to the start of the Sequence on which these features are located. The following point is defined as the 10th base of the sequence relative to base 1 of this particular sequence.

Of course, a particular feature may be viewed in a larger context. Base "1" on a fragment prepared by PCR from a complete genome has little meaning. As noted above, Numbering elements and Sequence attributes may be used to place a sequence in the larger context of a clone or chromosome. This context is automatically transferred to the features on the sequence, so that these features may be referenced relative to the start of the fragment, the start of the clone, or the start of the chromosome.

Qualitative annotation typically means asserting properties about a Feature in the form of Qualifiers. In BSML, the value-type attribute is used to indicate the type of a qualifier, and the value attribute is used to indicate the specific content of the qualifier. For example, a Qualifier element may be used to indicate the translation of a region:

Quantitative annotation may be supplied in a variety of ways in BSML.

The value attribute may be used to convey a quantitative index that is interpreted in terms of the value-type attribute. For example:

Referential annotation refers to the use of linking and cross-reference elements to associate a sequence or its features with an external object. The external object may be an entry in a public database, a graphic image, a text, etc. Referential annotation may also be used to place a biological object in the context of an ontology that defines such characteristics as function and cellular location.

A cross-reference may be added to a Feature by adding a Qualifier with the value-type attribute set to db_xref and the value attribute set to the database and identifier, as follows:

Note: The processing of such a cross-reference is software-dependent and depends on the interpretation of the database:identifier pairs. For example, the Genomic XML Viewer currently supports the following databases:

The various linking elements may be used to annotate by reference to a resource contained in the current document or elsewhere. For example:

BSML provides alternative ways for representing and presenting biological content. This section discusses the data model of BSML as it pertains to biological objects and graphical objects and the relationship between the two.

A biological object may be thought of as an abstraction representing some reasonably well-defined biological entity or concept that is encoded in some form (relational database schema, XML schema, UML notation, etc.). In BSML, for example, the Sequence element and all of its attributes and child elements represent the notion of a sequence as a biological object. The element definition represents the abstract definition of the object and defines a subset of all properties that are potentially of interest. An instance of the element in a BSML document represents an instance of the object, with values supplied for the defining attributes (shape, length, etc.).

Some biological objects may be considered individually, without reference to other objects. For example, an RNA molecule may be considered as a separate Sequence entity.

Other biological objects are best considered as sets. For example, the cleavage sites for a restriction enzyme on a particular sequence are usually considered as a set. The sequence fragments produced by a digest with the restriction enzyme are defined by the set of cleavage sites, even though a researcher may only be interested in one fragment. For similar reasons, sets of features (e.g., exons) have a collective meaning that is not available from any particular member of the set.

A graphical object may be considered at several levels of abstraction: the pixels turned on or off on a display, the drawing primitives (line, arc, etc.) used to render the object, etc. In BSML, each graphical object is termed a display widget. Rather than emphasizing the drawing routines, each display widget is defined in terms of its function.

Some of the functions represented by display widgets are not particularly biological. For example, a Caption-widget element represents text to be displayed on the page. Similarly, Line-pointer and Shape widgets provide graphical objects that are not particularly biological.

The vast majority of the display widgets defined in BSML are graphical objects with biological meaning. In many cases, the display widget represents a graphical metaphor that is commonly used by molecular biologists to describe their subject matter. For example, a View element depicts a biological sequence. Together with its children elements (Interval-widget, Point-widget, etc.), the View provides a graphical representation of an annotated sequence.

In other cases, the display widget represents an abstract rendering of a research product such as an electrophoresis gel image (Gel-plot-widget). Still other widgets represent data in commonly accepted display formats (e.g., Dot-plot-widget).

In most cases, underlying biological data are not encoded directly into the graphical widget. Instead, the data are associated with the object by reference to elements in the Definitions portion of the document. This method provides for clean separation between graphical objects, contained in the Display section of a BSML document, and the data elements contained in the Definitions section. For example, a View element uses its seqref attribute to refer to a Sequence element.

The representation of graphical objects may be specified in terms of a number of attributes controlling such display characteristics as line widths, colors, and text fonts. When these attributes are specified, the author of the BSML document has control over how the graphical object appears when rendered with suitable software. If these attributes are left unspecified (all are optional), the rendering will be determined by the software using default or style sheet assignments provided by the recipient.

There are certain assumptions made in the encoding methods defined by BSML for graphical widgets, but they are not too restrictive. It should be noted that there are no constraints that make the rendering of BSML content specific to any particular language, machine, or operating system. Any rendering agent that can implement basic text and drawing routines can render BSML graphical widgets.

BSML is geared toward paged media, but there is no stipulation of page size, so an arbitrarily long page could be used.

The graphical display objects (widgets) are all nested under a Page element. Some elements are nested within others (for example, a View element may contain an Aligned-chart-widget).

Because BSML is able to represent a wide range of data types (hierarchies, sets, tables, textual, numeric, etc.), appropriate rendering software ("viewers") must be associated with each data type (e.g., a BLAST result viewer).

In its short lifetime XML has proven to be very useful for representing data, exchanging data between environments and applications, and transporting data over distributed networks. XML is particularly useful for hierarchically structured data, and XML linking mechanisms support network data representations.

BSML takes advantage of XML features for encoding hierarchically organized information (e.g., sequence - feature table - feature - qualifier hierarchy). By providing an explicit representation of knowledge in a particular domain – biological sequences –BSML capitalizes on the general strengths of XML and the domain knowledge that BSML represents.

There are various ways to encode hierarchically organized content, including object-oriented databases, ASN.1, SGML, etc. There is probably no single solution that is optimal for all purposes (e.g., rich representation of semantics, storage ease, queryability, bandwidth conservation, etc.). BSML is a reasonable choice under many circumstances.

BSML is not intended to be the answer to every issue of knowledge representation in the life sciences. Additional public standards are needed to represent cellular processes, gene expression, etc.

To move from one data representation to another requires a mapping between the representations. Certain considerations apply when mapping from one type of data representation to BSML.

It is generally possible to decompose a hierarchical representation of data into a relational representation. For example, there have been relational database representations of GenBank for many years (e.g., NCGR). Mapping from a relational database to BSML is generally a matter of establishing the correspondence between various tables and their joins and the hierarchical sequence - feature table - feature - qualifier structure of BSML.

Flatfile representations of sequence information may be transformed into BSML using appropriate parsing technology. The first step is to establish a mapping between elements in one format and elements in the other. This subject is discussed in greater detail in another LabBook manual on mapping public database formats (GenBank, EMBL and Swiss-Prot) to BSML (see Mapping to BSML 2.2 from Public Sequence Formats).

BSML and ASN.1 (Abstract Scientific Notation) are very compatible and map directly, because both are hierarchical and object oriented.

Other XML-based representations of sequence information may usually be mapped directly to BSML using XSLT transformations.

BSML documents are generally produced by software applications that extract information from other sources.

Query software generally uses SQL statements to access information from a relational database. The LabBook OSU Human Genome (OHGD) Query, described elsewhere, provides an example of how relational databases may be queried to produce BSML content.

Creation software is often tailored to particular functions. LabBook, Inc. provides a BSML Java API that includes utility classes for creating BSML documents. Additional software modules (e.g., Perl modules) are available in the public domain for converting from generic formats to BSML (see BSML 2.2 Java API and ToolKit).

Interactive editing software is useful for fine-grain editing of BSML documents. The BSML Java API includes a simple interactive editor, and more extensive editing software is available from LabBook, Inc.

Visualization software must be capable of rendering BSML content. LabBook, Inc. provides the Genomic XML Viewer and Genomic XML Browser for this purpose (see Rendering BSML in the Genomic XML Viewer).

BSML is an XML application. This means that any software capable of reading and writing XML can be used to work with BSML documents (DOM parsers, SAX parsers, etc.).