The
region condition applies to Region Datasets and is evaluated for each individual region in a sequence.
Operations will only be applied to regions where the condition holds true. Three different subtypes of region conditions exist.
The first type bases the condition on the value of a specific property of the region itself. The second type compares the region
to other regions from the same or a different region track. The last type bases the condition on the values of a numeric track within
the sequence segment spanned by the region. The general protocol syntax for these three cases are as follows:
where [not] region <property> <operator> <Operand>
where [not] region <operator> <RegionTrack> [ <comparator> <Operand2> ]
where [not] region <operator> <NumericTrack> <comparator> <Operand2>
|
The
region keyword discriminates this kind of condition from the
position condition.
For improved language in protocols, the alternative forms
region's,
regions and
regions' are also accepted.
If the optional
not keyword is specified immediately after "where", the truth value of the whole condition following it will be inverted.
Conditions based on region properties
| Property | Operator | Operand | Description |
|---|
| text property "name" | equals | Text | The condition holds true if the region's value for this property is identical to the text value of the operand |
| text property "name" | matches | Text | The condition holds true if the region's value for this property matches the value of the operand (which can be a regex) |
| text property "name" | is in | Set | The condition holds true if the region's value for this property is identical to one of the values in the set |
| text property "name" | matches in | Set | The condition holds true if the region's value for this property matches one of the values in the set (which can contain regexes) |
| numeric property "name" | = | value | The condition holds true if the region's value for this property equals the value of the operand |
| numeric property "name" | >= | value | The condition holds true if the region's value for this property is equal to or greater than the value of the operand |
| numeric property "name" | > | value | The condition holds true if the region's value for this property is greater than the value of the operand |
| numeric property "name" | <= | value | The condition holds true if the region's value for this property is equal to or less than the value of the operand |
| numeric property "name" | < | value | The condition holds true if the region's value for this property is less than the value of the operand |
| numeric property "name" | <> | value | The condition holds true if the region's value for this property is not equal to the value of the operand |
| numeric property "name" | in | N to M | The condition holds true if the region's value for this property is between the two values N and M (inclusive) |
The specification of the property must include its type (text, boolean or numeric) and the name of the property within double quotes. (Boolean properties are treated the same as text properties except that their values are expected to be boolean).
The three standard properties "type" (text), "score" (numeric) and "length" (numeric) are exempt from this rule and can be referred to by the short-hand notation "
where region type|score|length ...".
For numeric properties, the value(s) of the operand must be numeric and can be provided either as a constant number, a
Numeric Variable or a
Numeric Map.
If a
Motif- or
Module Numeric Map is used as the operand, the
type property of the region will be used as the key to look up the corresponding value in the map.
If a
Sequence Numeric Map is used, the value of the operand will be the value for the current sequence in the map.
For text properties, the operand can either be a constant string enclosed in double quotes, a
Text Variable, a
Collection or a
Text Map.
If a
Motif- or
Module Map is used as the operand, the
type property of the region will be used as the key to look up the corresponding value in the map.
If a
Sequence Map is used, the value of the operand will be the value for the current sequence in the map. The "equals" and "matches" operators expect the operand to be a single value that must match with the property.
The only difference between these two is that "matches" allows the operand to be/contain a
regular expression (
as explained here). Note that the property value is expected to match the full regular expression,
so if you want to target regions where the property contains some specific substring (e.g. "AP1") the regex must allow for optional characters before or after this substring (like so "
.*AP1.*"). (Regex matching is case-insensitive.)
The "is in" and "matches in" operators expect the operand to be a set with multiple values, for instance a Text Variable with multiple lines (each line will be treated as a separate value), a Collection or a Text Map (which possibly contains multiple comma-separated
values for each entry).
NB:
If a region does not have a defined value for the property, the following default values will be used: 0 (numeric properties), an empty string (text properties) or FALSE (boolean properties).
| Operator | Track | comp | Op2 | Description |
|---|
| present in | RegionTrack2 | | | The condition holds true for this region if RegionTrack2 contains a region which is identical in every respect to this region (both standard and user-defined properties must match!) |
| similar in | RegionTrack2 | | | The condition holds true for this region if RegionTrack2 contains a region with the same location, orientation and type as this region |
| overlaps | RegionTrack2 | | | The condition holds true for this region if it overlaps with a region in RegionTrack2 |
| inside | RegionTrack2 | | | The condition holds true for this region if it is wholly inside (i.e. completely covered by) a region in RegionTrack2 |
| covers | RegionTrack2 | | | The condition holds true for this region if it completely covers a region in RegionTrack2 |
| distance to any | RegionTrack2 | • | value | The condition holds true for this region if RegionTrack2 contains a region located within the specified distance from this region |
| distance to closest | RegionTrack2 | • | value | The condition holds true for this region if the closest region in RegionTrack2 is located within the specified distance from this region |
The distance between two regions is the number of bases between them, so two regions that lie back to back have a distance of zero. Overlapping regions have a defined distance of -1.
For the distance operators the value of Operand2 must be numeric and can be provided as usual with a constant number, Numeric Variable or Numeric Map.
The comparator (•) can be any one of the standard numeric comparison operators:
=, <, <=, >, >= or "
in N to M" as described above.
Although
compound conditions allow multiple conditions to be linked with AND/OR, these conditions are treated completely independent of each other,
and it is not currently possible to make crossreferences between conditions.
Hence, it is not possible to formulate general conditions on the form "where (this region overlaps RegionTrack2) AND (the overlapping region from RegionTrack2 satisfies some other condition)".
However, it is possible to make use of a few predefined qualifiers to place further constraints on the regions in RegionTrack2.
The following two qualifiers can be placed between the operator and the track name for all operators except "present in" and "similar in".
- type-equal: The region from RegionTrack2 must have the same "type" property as this region
- type-matching: The region from RegionTrack2 must have a "type" property which contains the type of this region. The type property of the other region could possibly be a list with several entries (note that this matching does not allow regular expressions).
The special keyword "interaction partner" can be used instead of the name of a second region track for the distance operators.
- interaction partner: This only applies if the target track is a motif track. The other region (which will be from the same track) must be an annotated interaction partner of the first region.
(i.e. the "type" property of the region must be a motif name and this Motif must have the type of the other region annotated in its "interactions" list).
| Operator | Track | comp | Op2 | Description |
|---|
| min | NumericTrack | • | value | The condition holds true for this region if the smallest value from the numeric track within the region satisfies the comparison |
| max | NumericTrack | • | value | The condition holds true for this region if the largest value from the numeric track within the region satisfies the comparison |
| average | NumericTrack | • | value | The condition holds true for this region if the average value from the numeric track over all positions within the region satisfies the comparison |
| median | NumericTrack | • | value | The condition holds true for this region if the median value from the numeric track of all positions within the region satisfies the comparison |
| sum | NumericTrack | • | value | The condition holds true for this region if the sum of all values from the numeric track over all positions within the region satisfies the comparison |
| weighted average | NumericTrack | • | value | The condition holds true for this region if the motif IC-weighted average value from the numeric track over all positions within the region satisfies the comparison |
| weighted sum | NumericTrack | • | value | The condition holds true for this region if the motif IC-weighted sum of all values from the numeric track over all positions within the region satisfies the comparison |
| startValue | NumericTrack | • | value | The condition holds true for this region if the value from the numeric track in the (genomic) start position of the region satisfies the comparison |
| endValue | NumericTrack | • | value | The condition holds true for this region if the value from the numeric track in the (genomic) end position of the region satisfies the comparison |
| centerValue | NumericTrack | • | value | The condition holds true for this region if the value from the numeric track in the middle position of the region satisfies the comparison |
| relativeStartValue | NumericTrack | • | value | The condition holds true for this region if the value from the numeric track in the most upstream position of the region (relative to the parent sequence) satisfies the comparison |
| relativeEndValue | NumericTrack | • | value | The condition holds true for this region if the value from the numeric track in the most downstream position of the region (relative to the parent sequence) satisfies the comparison |
| regionStartValue | NumericTrack | • | value | The condition holds true for this region if the value from the numeric track in the first position of the region (relative to the orientation of the region itself) satisfies the comparison |
| regionEndValue | NumericTrack | • | value | The condition holds true for this region if the value from the numeric track in the last position of the region (relative to the orientation of the region itself) satisfies the comparison |
The weighted sum and average only works for motif tracks where each region is associated with a Motif. In these cases the values from the numeric track will be weighted by the information content of the corresponding position in the motif.