Properties

Description

The "Properties" data format relies on a template text supplied via a Text Variable to format the output of motifs, modules or sequences. The template can contain a mix of literal text and references to named motif/module/sequence properties on the form "{propertyName}". These references will be replaced by the actual values of the properties when a data object is output.

The following example shows a small template to output three motif properties:


Repeat blocks
   A repeat block is a convenient, short-hand way of outputting multiple properties in a similar fashion. A repeat block starts off with a header line consisting of a percentage sign followed by a comma-separated list of properties. This header is then followed by any number of regular template lines. The repeat block is ended when encountering a line containing a double percentage sign. When a data object is output, all the lines between the single and double percentage signs will be repeated once for each property in the list. In additional to regular named property references, the lines within a repeat block can contain the special references "{key}" and "{value}" which refers to the name and value of the property currently being processed. The list of properties to repeat over can contain the wildcard symbol "*", which will then add all known properties to the list, or the subset wildcards "*standard" (all standard properties) and "*user" (all non-standard user-defined properties). If the name of a property in the list is preceeded by a minus sign, it will be removed from the current list of properties. Hence, the list "*,-ID" will include all properties except "ID".

The motif template below will output the properties "Short name", "Consensus" and "IC-content" followed by all user-defined properties except the two named "Pazar" and "Medline". Each line will consist of the ID of the current motif followed by a colon, and then the name of a property from the list and its respective value separated by an equals sign.
The list of properties in the repeat block header can optionally be followed by a colon and then a series of settings specifications in the form of keywords that further control the formatting of the repeat block:

• skip and blank: These settings will override the "If missing" parameter of the data format for this repeat block only.
  A header on the form "%property:skip" thus essentially represents a conditional block that will only be output if the named property is defined for the data object.
• [default]: A value enclosed in brackets will be used as a default when a data object does not have a defined value for the property.
  If specified, this setting overrides both "skip" and "blank".
• "separator": A string enclosed in double quotes will be used as the separator when outputting properties with multiple values (lists).
  Use "\t" to represent TAB and "\n" for newline. This setting will default to comma unless specified.
• inline: This setting is really only useful if the repeat block consists of a single line. When in use, all the properties will be output on the same line immediately after each other. Also, unless explicitly specified with the "break before/after" settings, there will be no linebreaks occurring before and after the list of properties.
• break before and break after: These keywords can be used in combination with the "inline" setting to force linebreaks to occur before and/or after the inline repeat block.
• 'separator': A string enclosed in single quotes will be used as the separator when outputting a list of properties with an inline repeat block.
  Use "\t" to represent TAB. If unspecified, no separator will be output between the properties.
• expand list: This keyword (which is incompatible with "inline") can apply when a property has multiple values in the form of an explicit list or a comma-separated string. In this case, instead of replacing the {value} reference with the whole list as one string (with entries separated by commas unless otherwise specified), the whole repeat block will itself be repeated for every value from the list, and each time the {value} reference will be replaced with this single value.

Matrix block
   A matrix block is special kind of repeat block used to format the variable-length binding matrix of a motif. The special "{key} and {value}" references are not defined for this kind of repeat block. Instead the matrix block has a a few other references, including "{A}, {C}, {G} and {T}" which refers to the matrix values for these bases. A binding matrix can be output in either vertical (N×4) or horizontal (4×N) orientation, and the repeat block will behave differently in these two cases.

In the case of vertical orientation, the repeat block will be repeated N times (where N is the length of the motif), and with each repetition the values of {A}, {C}, {G} and {T} will refer to the next position in the matrix. The current position (row counter) can be accessed with the special references "{row}" or "{rowXX}", where the latter will always return the position in double digits. (If you want a row counter starting at 0 rather than 1, use the references "{row-1}" or "{rowXX-1}" instead). Another special reference "{x}" can be used to access the consensus base letter for the position. This base letter will be in uppercase for regular DNA bases and in lowercase for degenerate bases. The reference "{X}" will always return the base letter in uppercase.
In the case of horizontal orientation, the repeat block itself will not be repeated more than once. Instead, the references {A}, {C}, {G}, {T} and {x} will contain lists of values rather than single values. The values in these lists will be separated by a comma unless a different separator is specified within a pair of double quotes in the block header. The special reference "{columns}" (and also "{columnsXX}, {columns-1} and {columnsXX-1}") contains column position counters in similarly formatted lists.
The settings string in the header of the matrix block can contain the keywords "count" or "frequency" to force the matrix to be output in a count-matrix format (only integers) or normalized frequencies format (values between 0 and 1) instead of the default formats used by each motif internally.


Headers, footers and separators
   The template can optionally contain the definition of a header that will be output at the beginning of the document, a footer that will be output at the end, and a separator that will be output between each entry when multiple data objects are output. If included, these must be defined at the very top of the template and introduced by the keywords "HEADER:", "FOOTER:" and "SEPARATOR:" respectively, as shown in the example below (note that the keywords have to be in uppercase!). Each definition must be contained on a single line, but you can force linebreaks by including the newline character "\n". The header, footer and separator can not contain any property references, but they can contain the special reference "{size}" which is the size of the collection being output and "{counter}" which is a number that starts at 1 and is incremented for each entry output ("{counter-1}" is similar but starts the counting at 0).

Since templates can contain any text, the "Properties" format can be used to mimic nearly all other data formats for outputting motifs, modules or sequences, as demonstrated by the following example templates:

Example #1: BED format
   Since genomic sequence coordinates in BED files start at 0 rather than 1, a "[0]" suffix has been added to the "genomic start" property in the second column. The same suffix has not been added to the "genomic end" property in third column, however, since this coordinate is exclusive according to the BED-format definition, and exclusive 0-indexed end-coordinates are the same as inclusive 1-indexed end-coordinates. The "score" value in column five is just set to the constant number "1000".

Example #2: GFF format
   The ninth and final column of the GFF sequence format contains a semi-colon separated list of additional attributes defined as key="value" pairs. The template below outputs the sequence name as the first such attribute and if the sequence has any other user-defined attributes these will be output directly behind on the same line using a repeat block with the "inline" setting.

Example #3: JASPAR format
   The motif format used by the JASPAR database is very simple, consisting of just a FASTA-like header followed by four lines that define the matrix values for the four DNA bases. This template demonstrates how to use a repeat block to output the "matrix" property of the motif in a horizontal orientation. The TAB-sign "\t" is used to separate the columns in the matrix rather than the default separator (comma). Note that the template also includes an explicit entry SEPARATOR which is inserted between every motif in the output. In this case the separator is empty and will result in an empty line being output between each motif.

Example #4: TRANSFAC format
   The header of the TRANSFAC motif format is split across three lines with the use of the newline character "\n". The repeat block used to format the vertically oriented matrix includes both the row number in double digits "{rowXX}" and the consensus letter in upper case "{X}".

Example #5: XMS format
   XMS is an XML-based motif format where normalized frequency matrices are output in a vertical orientation. All the <motif> elements are enclosed in an outer <motifset> tag defined by HEADER and FOOTER.