Skip to content
Snippets Groups Projects
Commit 0c4d308e authored by edgrif's avatar edgrif
Browse files

produce some kind of first draft of styles docs for users.

parent 92614ebe
No related branches found
No related tags found
No related merge requests found
...@@ -9,6 +9,8 @@ pre{ width: 95%; background-color: #DDDDDD; border-style: solid; border-width: 1 ...@@ -9,6 +9,8 @@ pre{ width: 95%; background-color: #DDDDDD; border-style: solid; border-width: 1
</style> </style>
<br />
<fieldset> <fieldset>
<legend>Overview</legend> <legend>Overview</legend>
...@@ -18,53 +20,100 @@ those features are processed during user interaction, e.g. by clicking on them t ...@@ -18,53 +20,100 @@ those features are processed during user interaction, e.g. by clicking on them t
display detais or perhaps dumping them to files. display detais or perhaps dumping them to files.
</fieldset> </fieldset>
<br />
<br />
<fieldset> <fieldset>
<legend>Mandatory Tags</legend> <legend>Mandatory Properties</legend>
<p>The policy for ZMap Styles is that a subset of tags must be specified if a feature is to <p>There is only one mandatory property for a style and that is it's name, the name is used
be displayed. This policy was implemented because past experience has shown that the alternative to make a unique id for the style. This very flexible policy is what allows inheritance to
is that the code must have embedded in it a large number of defaults that are often "best guesses" work but has the disadvantage that the user must set certain properties explicitly for there
about how features should be displayed. This leads to confusion and uncertainty about how to be enough information for ZMap to display the set of features referencing that style.</p>
feature display is controlled.
</p> <p>ZMap does not have display defaults embedded in the code because past experience has shown that
this requires a large number of defaults that are at best "guesses" as to what the user wants to
see. This leads to confusion and uncertainty about how feature display is controlled. </p>
<p>The following tags <b>must</b> be specified if the features referencing the style are to be
<p>The following properties <b>must</b> be specified if the features referencing the style are to be
displayed: displayed:
</p> </p>
<ul>
<li><b>mode:</b> must be set to one of <table class="zebra" id="timtable">
<ul> <caption align=top>Displayable Styles</caption>
<li><b>ZMAPSTYLE_MODE_BASIC</b> <thead>
<li><b>ZMAPSTYLE_MODE_TRANSCRIPT</b> <tr>
<li><b>ZMAPSTYLE_MODE_ALIGNMENT</b> <th>Property</th>
<li><b>ZMAPSTYLE_MODE_TEXT</b> <th>Type</th>
<li><b>ZMAPSTYLE_MODE_GRAPH</b> <th>Value Range</th>
<li><b>ZMAPSTYLE_MODE_GLYPH</b> <th>Description</th>
<p>also requires glyph mode to be set, currrently only ZMAPSTYLE_GLYPH_SPLICE </tr>
is supported. </thead>
</ul> <tbody>
<li><b>overlap:</b> must be set to one of <tr>
<ul> <td>"mode"</td>
<li>...</li> <td>one of</td>
</ul> <td>"basic", "transcript" etc.</td>
<li><b>width:</b> must be set. <td>Identifies how feature should be processed, e.g. as a transcript, match etc.</td>
<li><b>colours:</b> different modes require different colours to be set: </tr>
<ul> <tr>
<li><b>ZMAPSTYLE_MODE_BASIC</b>, <b>ZMAPSTYLE_MODE_TRANSCRIPT</b>, <b>ZMAPSTYLE_MODE_ALIGNMENT</b> <td>"overlap_mode"</td>
need fill and or border to be set. <td>one of</td>
<li><b>ZMAPSTYLE_MODE_TEXT</b> needs fill and draw to be set. <td>"complete", "Overlap" etc</td>
<li><b>ZMAPSTYLE_MODE_GRAPH</b> <td>Controls how features are arranged in within the column, e.g. overlapping, by name etc.</td>
<li><b>ZMAPSTYLE_MODE_GLYPH</b> </tr>
<p>ZMAPSTYLE_GLYPH_SPLICE requires all 3 frame colours to be set. <tr>
</ul> <td>"width"</td>
</ul> <td>double</td>
<td>0 &lt; width &lt; col_max</td>
<td>gives a default width to the feature (in pixels ???), some features will have different
widths, e.g. if they are scaled by score.</td>
</tr>
<tr>
<td>"border" and/or "fill" and/or "draw"</td>
<td>string</td>
<td>standard colour specifier</td>
<td>basic, transcript and alignment features require fill and/or border colours,
all text (e.g. dna) requires fill and/or draw colours.</td>
</tr>
</table>
<p>
Here are some examples:
</p>
<pre class="example">
ZMap_style : "Allele"
Basic
Colours Normal Fill "orange"
Width 1.100000
Unbumped
ZMap_style : "BLASTN_EST_briggsae"
Alignment
Colours Normal Fill "brown"
Width 15.000000
Unbumped
ZMap_style : "curated"
Transcript
Colours Normal Border "darkblue"
Width 15.000000
Compact_cluster
</pre>
</fieldset> </fieldset>
<br />
<br />
<fieldset> <fieldset>
<legend>Inheritance</legend> <legend>Inheritance</legend>
...@@ -114,116 +163,141 @@ GFF Source "BLASTN_TC1" ...@@ -114,116 +163,141 @@ GFF Source "BLASTN_TC1"
</pre> </pre>
</fieldset> </fieldset>
<br />
<fieldset>
<legend>Column_group styles</legend>
<p>ZMap allows multiple sets of features within a single column, each set with its own style for
colouring, bumping and so on.
</p>
<p>Where several different types of features all perhaps having their own styles are displayed in a
single column specified via the "Column_group" tag, then there must be a style with name given by
that tag. This is partly to make processing within zmap uniform (i.e. everything has a style) and
partly because we need an overall style for the column to allow column wide operations such as
bumping all features in the column or hiding the whole column etc.
</p>
</fieldset>
<br /> <br />
<fieldset> <fieldset>
<legend>Predefined Styles</legend> <legend>Predefined Styles</legend>
<p>There are a number of predefined styles for common features such as DNA sequence display. These <p>There are a number of predefined styles for common features such as DNA sequence display. These
features have reserved names which should not be used for other sorts of features. features have reserved names which should not be used for other sorts of features. The feature set
and the style for these features have the same name.
</p> </p>
<p>Some of these styles are "meta" styles which control the action of a column rather than <p>Some of these styles are "meta" styles which control the action of a column rather than
specific features, e.g. "3 Frame" controls whether the 3 frame translation columns are displayed specific features, e.g. "3 Frame" controls whether and where the 3 frame translation columns are displayed
but the individual column display is controlled by the style for each column. but the individual column display is controlled by the style for each column. Others are normal
</p> styles and some of their settings can be overridden by the user. The following table summarises
the predefined styles:
<p>Other predefined styles are used in the normal way, e.g. the "DNA" style simply controls the
colour of the dna text (normal and selected).
</p>
<p>Although these styles are predefined, they must be available from the data source supplied to
zmap if that particular type of data is to be displayed. The style does not have to be completely
filled out as ZMap will fill in the style with some reasonable defaults. Any values from the data
source will override the default values.
</p> </p>
<p>The current list of these styles is: <table class="zebra" id="timtable">
<caption align=top>Predefined Styles</caption>
<thead>
<tr>
<th>Style</th>
<th>Style Type</th>
<th>User Specifiable</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>"3 Frame"</td>
<td>Meta</td>
<td>No</td>
<td>controlling 3 frame display</td>
</tr>
<tr>
<td>"3 Frame Translation"</td>
<td>Normal</td>
<td>Yes</td>
<td>3 frame protein translation display</td>
</tr>
<tr>
<td>"dna"</td>
<td>Normal</td>
<td>Yes</td>
<td>dna sequence display</td>
</tr>
<tr>
<td>Locus</td>
<td>Normal</td>
<td>Yes</td>
<td>display of a column of locus names + navigator bit</td>
</tr>
<tr>
<td>GeneFinderFeatures</td>
<td>Meta</td>
<td>No</td>
<td>splice sites from the Gene Finder program</td>
</tr>
<tr>
<td>Show Translation</td>
<td>Normal</td>
<td>Yes</td>
<td>Show peptide translation column</td>
</tr>
</table>
<p>The rules for using these predefined styles are:
<ul> <ul>
<li><b>"3 Frame"</b> Meta style controlling 3 frame display <li>The features for the predefined style must be fetchable from the database.
<li><b>"Show Translation"</b> Meta style controlling if translation is shown at all <li>To display the data for a predefined style the style name must be specified
<li><b>"3 Frame Translation"</b> Predefined style for 3 frame protein translation display in the "feature_sets" list in the "ZMap" stanza of the config file.
<li><b>"DNA"</b> dna sequence display <li>The style itself does not have to exist in the database, ZMap will create the
<li><b>"Locus"</b> display of a column of locus names style with sensible defaults for display.
<li><b>"GeneFinderFeatures"</b> splice sites from the Gene Finder program <li>"Normal" styles can have relevant fields overriden by specifying them in
<li><b>"scale"</b> dna base scale a style of the same name in the database, e.g. foreground/background colours
can be overidden for "dna".
</ul> </ul>
<p> <p>
</fieldset> </fieldset>
<br />
<hr>
<fieldset>
<legend>ZMap Styles Struct Details</legend>
<p>Refer to the ZMap code documentation for ZMap Styles <a href="../html/index.shtml">here</a></p>
<h5>Field setting</h5>
<p>stuff needed....</p>
</fieldset>
<br /> <br />
<hr>
<fieldset> <fieldset>
<legend>ZMap Styles and Acedb</legend> <legend>ZMap Styles and Acedb</legend>
<h3>Acedb Methods vs. ZMap styles</h3>
<p>When ZMap accesses an acedb database as one of its data sources then if styles are to be <p>
specified via acedb classes then there must be a very precise relationship between the ZMap will read either acedb ?Method or ?ZMap_style objects for style information.
styles and acedbs Method class objects: The default is to read ?ZMap_style objects and you should convert to using these instead
of Methods as many features are not available with Methods.
</p> </p>
<ul> <p>
<li>ZMap must be instructed to look for ZMap style objects rather than acedb Method objects The relationship between features and ?Method objects is different according to
by specifying the "use_zmap_styles" tag in the configuration file "source" stanza: whether you are using ?ZMap_style objects or ?Method objects to specify styles. The
<p>use_zmap_styles = true following sections describe how to use each one. Support for ?Method object styles
<li>All Styles referenced by any feature must be represented by a ZMap_style object in the acedb database AND will be maintained to allow immediate usage of acedb databases without the need to convert
also an acedb Method, they MUST have the same name. to styles each time.
<ul> </p>
<li>ZMap feature display is completely controlled by the ZMap_style object.
<li>Retrieval of features from the acedb database is completely controlled by the acedb Method because
we use the acedb GFF dumper which makes heavy use of acedb Methods.
</ul>
<p>It is vital that acedb Methods continue to exist unaltered alongside the new
ZMap_style objects.
</ul>
<h3>Acedb Classes required to support ZMap Styles</h3> <h4>Using ?ZMap_style objects for Styles</h4>
<ul>
<li>The semantics of the ?Method class are changed: all features must reference a ?Method object
which now <b>only</b> represents the feature set containing those features. Specifically, none of
the display information in the object is referenced. The only tags used are those in
the Feature_set tag set (see below).
<p>The ?Method object name will be the column name for that feature set when displayed unless
the ?Method object contains a Column_parent tag (see below).</p>
<li><p>Each ?Method object <b>must</b> contain a Style tag pointing to a valid ?ZMap_Style
object. The style object contains all the display/processing options for that feature set.</p>
<li>Each ?Method object can optionally contain a Column_parent tag pointing to a valid
?Method object, the feature set will then be displayed as part of the Column_parent column
along with any other feature sets referencing that Column_parent. Note that the Column_parent
column must also reference a valid ?ZMap_Style.
</ul>
<p> Using ?ZMap_style objects means that all feature display is completely controlled by the
ZMap_style object and all retrieval of features from the acedb database is completely controlled
by the acedb ?Methods. This echoes the separation adopted by DAS and other feature display protocols.
</p>
<p>A number of classes must be added to wspec/models.wrm to fully support ZMap Styles <p>A number of classes must be added to wspec/models.wrm to fully support ZMap Styles
from an acedb database. The following is a definitive, annotated list of these classes which can from an acedb database and several tags must be added to the ?Method class.
The following is a definitive, annotated list of the new classes and tags which can
be copied and pasted direct into a models.wrm file. be copied and pasted direct into a models.wrm file.
</p> </p>
...@@ -298,6 +372,7 @@ be copied and pasted direct into a models.wrm file. ...@@ -298,6 +372,7 @@ be copied and pasted direct into a models.wrm file.
Match_colours Perfect UNIQUE #ZMap_feature_colour Match_colours Perfect UNIQUE #ZMap_feature_colour
Colinear UNIQUE #ZMap_feature_colour Colinear UNIQUE #ZMap_feature_colour
Non_colinear UNIQUE #ZMap_feature_colour Non_colinear UNIQUE #ZMap_feature_colour
Pfetchable // If present it means these alignments have pfetch entries.
// Specifies properties unique to a sequence feature. // Specifies properties unique to a sequence feature.
// //
...@@ -327,21 +402,21 @@ be copied and pasted direct into a models.wrm file. ...@@ -327,21 +402,21 @@ be copied and pasted direct into a models.wrm file.
// Specifies how columns should be displayed when bumped. // Specifies how columns should be displayed when bumped.
?Zmap_overlap Remark Text ?Zmap_overlap Remark Text
Overlap_mode UNIQUE Complete // Draw on top - default Overlap_mode UNIQUE Complete // Draw on top - default
Compact_cluster // All features with same name in a single column, several names in one Overlap // Bump by set amount if coords overlap.
// column but no 2 features overlap. Item_overlap // Bump so items do not overlap at all if coords overlap.
Compact_cluster_range // All features with same name in a single column if they overlap the Start // Bump if match start at same coord.
// focus range, all other features in a single column.
Cluster // All features with same name in a single column, several names in one
// column but no interleaving of sets of features.
Ends_range // Sort by 5' and 3' best/biggest matches, one match per column, very
// fmap like but better...
Compact_limit // Constrain matches to be colinear within range or are truncated.
Oscillate // Oscillate between one column and another, useful for displaying tile paths.
Overlap // Bump if match coords overlap.
Position // Bump if match start at same coord.
Name // One column per match target Name // One column per match target
Item_overlap // Bump if item coords overlap in canvas space Oscillate // Oscillate between one column and another, useful for displaying tile paths.
Simple // One column per match, good for testing Simple // One column per match, good for testing
Ends_range // Sort by 5' and 3' best/biggest matches, one match per column, very
// fmap like but better...
Compact // All features with same name in a single column, several names in one
// column but no 2 features overlap.
Compact_no_interleave // All features with same name in a single column, several names in one
// column but no interleaving of sets of features.
Range // All features with same name in a single column if they overlap the
// mark range.
Range_colinear // As for "Range" but constrain matches to be colinear across range.
...@@ -356,7 +431,8 @@ be copied and pasted direct into a models.wrm file. ...@@ -356,7 +431,8 @@ be copied and pasted direct into a models.wrm file.
// Parent points to a parent style from which attributes can be inherited, // Parent points to a parent style from which attributes can be inherited,
// there can be an arbitrary depth of parents/children but they must form // there can be an arbitrary depth of parents/children but they must form
// a DAG, cycles are _not_ permitted. // a DAG, cycles are _not_ permitted.
Parent UNIQUE ?ZMap_Style Parent Style_parent UNIQUE ?ZMap_Style XREF Style_child
Style_child ?ZMap_Style XREF Style_parent
// //
// The mode of the features, i.e. transcript, text or what..... // The mode of the features, i.e. transcript, text or what.....
Mode UNIQUE Basic #Zmap_mode_basic Mode UNIQUE Basic #Zmap_mode_basic
...@@ -368,21 +444,20 @@ be copied and pasted direct into a models.wrm file. ...@@ -368,21 +444,20 @@ be copied and pasted direct into a models.wrm file.
Graph #ZMap_mode_graph Graph #ZMap_mode_graph
Glyph #ZMap_mode_glyph Glyph #ZMap_mode_glyph
// //
// Column_group allows placement of different sets of features within a single column: // Controls all aspects of feature display.
//
// Column_group "column group name"
// //
Column_group UNIQUE Text UNIQUE ?ZMap_Style //Display Hide UNIQUE Always // never display features (default FALSE)
// Initially // Hide features initially (default FALSE)
// Show_when_empty // Show set even if empty (default FALSE)
// //
// Controls all aspects of feature display. Display Col_display UNIQUE Not_displayable // never display this column (for meta columns)
Display Hide UNIQUE Always // never display features (default FALSE) Displayable Col_state UNIQUE Hide // hide column always (can be unset by user)
Initially // Hide features initially (default FALSE) Show_hide // hide column according to zoom/mark etc. (can be unset by user)
Show_when_empty // Show set even if empty (default FALSE) Show // show column always (can be unset by user)
Show_when_empty // Show set even if empty (default FALSE)
// No_Compress // Always show, even in "compressed" display.
// //
Colours UNIQUE #ZMap_feature_colour Colours UNIQUE #ZMap_feature_colour
Frame_colours Frame_0 UNIQUE #ZMap_feature_colour
Frame_1 UNIQUE #ZMap_feature_colour
Frame_2 UNIQUE #ZMap_feature_colour
// //
Width UNIQUE Float // default is 0.0 Width UNIQUE Float // default is 0.0
// //
...@@ -400,8 +475,12 @@ be copied and pasted direct into a models.wrm file. ...@@ -400,8 +475,12 @@ be copied and pasted direct into a models.wrm file.
// //
Strand_sensitive Show_up_strand Strand_sensitive Show_up_strand
// //
// Is feature read frame dependent ? (optionally only ever show as 3 frames) // Read frame sensitive features, in 3 frame mode shown in separate reading frame cols.
Frame_sensitive Show_only_as_3_frame Frame_sensitive Frame_display Show_only_as_3_frame // show only in 3 frame mode.
Show_only_as_1_column // show only in 3 frame mode but as single col.
Frame_colours Frame_0 UNIQUE #ZMap_feature_colour
Frame_1 UNIQUE #ZMap_feature_colour
Frame_2 UNIQUE #ZMap_feature_colour
// //
// Score_bounds controls feature width when related to score, specifies min/max. // Score_bounds controls feature width when related to score, specifies min/max.
Score Score_style UNIQUE Score_by_width // only visual display supported for now. Score Score_style UNIQUE Score_by_width // only visual display supported for now.
...@@ -414,47 +493,115 @@ be copied and pasted direct into a models.wrm file. ...@@ -414,47 +493,115 @@ be copied and pasted direct into a models.wrm file.
//========================================================================================= //=========================================================================================
// Method:
// With styles the method class will have a different meaning, it will be
// be used to represent different sets of features and the Column_group tag
// can be used to clump sets of features into one common set.
//
//
?Method Remark ?Text #Evidence
// ZMap related tags.
//
// ZMap_style points to a style specifying how to display/process this feature set.
//
// Column_parent specifies the parent "feature set" for features that reference
// this method, this is the "column" in zmap.
// Column_child specifies child feature sets that exist within this parent
// feature set or column. Note that this is a one level thing: children do not
// have their own children, parents do not have parents. N.B. the XREF will fill in
// this tag.
//
Feature_set Style UNIQUE ?ZMap_style
Group UNIQUE Column_child ?Method XREF Column_parent
Column_parent UNIQUE ?Method XREF Column_child
//
// All other method tags are as before and will be ignored by ZMap.
//
</pre> </pre>
<h3 id="acedb_minimum_style">The Minimum Style specification for feature display</h3> <h4>Using ?Method objects for styles</h4>
<p>Rules for using ?Method objects:</p>
<ul>
<li>ZMap must be instructed to look for ?Method objects rather than ?ZMap_style objects
by specifying the "use_methods" tag in the configuration file "source" stanza:
<pre class="example">
source
{
use_methods = true
}
</pre>
<li>ZMap will only read a subset of the ?Method object display and processing tags (see below)
to create styles for feature display.
</ul>
<p>ZMap Styles require that certain tags and values must be specified if features are to <p> Using ?Method objects means that both feature display and feature retrieval is completely controlled by the
be displayed, the following give examples of minimum specifications: ?Method object. There is no separation of these two, the ?Method is both the feature set and
it's display/processing. The ?Method object tags will not be extended so only a subset of ZMap
display features can be used. Use of ?Method objects should be seen as a "quick and easy" way of display
which will duplicate most of the acedb FMap display but that is all. The following extract from the ?Method class
shows which tags ZMap reads.
</p> </p>
<pre class="example"> <pre class="example">
ZMap_style : "Allele" // Method:
Remark "Alleles in WormBase represent small sequence mutations (substitutions or indels) with the differences usually being between the sequenced (N2) strain of C. elegans and some other strain. The Allele track on the WormBase web site also includes SNPs and transposon mediated insertions" //
Basic // These are the only tags read by ZMap.
Colours Normal Fill "orange" //
Width 1.100000 //
Unbumped ?Method Remark ?Text #Evidence
//
// the Display information controls how the column looks.
Display Control UNIQUE No_display // never display features
Init_hidden // initially hide features
Colour #Colour
CDS_colour #Colour
Frame_sensitive // Is feature read frame dependent ?
Strand_sensitive Show_up_strand #Colour
Score Score_by_offset // has priority over width, for Jean
Score_by_histogram UNIQUE Float // baseline value
Score_bounds UNIQUE Float UNIQUE Float
Overlap_mode UNIQUE Overlap // draw on top - default
Bumpable // bump to avoid overlap
Cluster // one column per homol target
Width UNIQUE Float
Max_mag UNIQUE Float // don't show if more bases per line
Min_mag UNIQUE Float // don't show if fewer bases per line
Gapped // draw sequences or homols with gaps
Join_blocks // link up all blocks of a single feature with lines
GFF GFF_source UNIQUE Text
GFF_feature UNIQUE Text
ZMap_style : "BLASTN_EST_briggsae" </pre>
Alignment
Colours Normal Fill "brown"
Width 15.000000
Unbumped
Score_by_width
ZMap_style : "curated"
Remark "Predicted protein-coding genes are flagged with this method. All of these genes have been looked at by a human curator at some point and have usually been modified with respect to the initial computer prediction."
Transcript CDS_colour Normal Fill "darkblue"
Colours Normal Border "darkblue"
Width 15.000000
Compact_cluster
</pre> <h4>Converting from ?Method to ?ZMap_style objects</h4>
<p>ZMap includes a small utility script, methods2style.pl, to do a first pass conversion, the result will
require hand editting as some fields cannot be determined from the ?Method object,
e.g. Mode.</p>
<pre class="example">
SYNOPSIS: methods2style.pl -file <methods.ace> -help
e.g. methods2style.pl -file ./my/methods/file > ./my_new/styles/file
</pre>
ADD STUFF ABOUT CONVERTING FROM METHODS TO STYLES....
</fieldset> </fieldset>
<br /> <br />
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment