DiscoverySpace Template Primer

Introduction

For example, a Query might return all the Tag Sequences of all the Experimental Tags for the Library named "GSM1", with certain constraints on the quality of the tags and the data of the sequence. Currently the user needs to recreate that Query for each new SAGE Library ("GSM2", "GSM3", etc), or at least duplicate the original and change the library name. This can be a time-consuming process, especially when one has to construct tag sets for over 100 libraries.

By constrast, a Template allows the user to specify the form and constraints of a basic query tree and set one particular property as a "Variable" property which is to be supplied later. In the SAGE Query above the Library name would be the perfect candidate for a "Variable" property, leaving the remainder of the Query as it is. When the user needs to generate her tag sets, she merely needs to supply values for the variable property and the Template will use the query tree to generate Queries from those variables ("GSM2", "GSM3", etc). These new Queries will then be added as separate entries into the Databank.

If you are wishing to create a Template and are not yet acquainted with DiscoverySpace Queries then please read the Query Primer before continuing any further. Available datatypes differ for each user, so you might not have access to the specific datatypes given in the examples. None-the-less, the general usage remains the same regardless of the specific datatypes available.

Creating Templates

Templates are created from the DiscoverySpace Databank by selecting the "New Template" button. This will create a new Template definition in the Databank and will launch the Template's Properties window.

The Query Panel

Figure 1) An image of the Query Panel from the example Template. The user has created a new Template from the Databank and has selected the starting datatype "GSC SAGE Libraries". Note the red marker upon the "Name" property of "GSC SAGE Libraries" which designates "Name" as the "Variable" property of this Template. By default, the Variable marker is placed upon the Accession of each given starting dataset.

The user first needs to construct the Query tree, specifying the path and supplying all the constraints except for those constraints on the "Variable" property. By default the "Variable" marker is placed on the Accession of the starting set but, though this is the anticipated use case, it is possible to change the location of the "Variable" via the Template panel. For more information about how to specify a Query Tree please refer to the Query Primer.

Figure 2) An image of the Query Panel from the example Template in which the user has constructed a base query tree. The user has set up the query tree to collect the Sequences of the Experimental Tags of the SAGE Libraries. She has put constraints on three properties to reduce the resulting set. She has left the "Variable" property, specified by the red marker, as "Name".

The General Panel

Once the user has specified the contents of the Query panel she needs to move on to the other panels of the Template. As with all DiscoverySpace definitions it is vital to name and describe the Template correctly in the definition's General panel. However, this is especially important in the case of the Template because the Template can be set to copy the Description and Annotation fields into any generated Queries.

Figure 3) An image of the General Panel from the example Template in which the user has named, described and annotated the Template. The Description and Annotation fields can be copied into any generated Queries.

The Template Panel

In the Template panel the user gets to set the Template-specific qualities of the definition. Here the user decides whether the Description and Annotation fields should be copied into generated Queries. Here too the user decides upon the naming convention of any generated Queries by specifying a Name Prefix and a Name Suffix. In figure 4 (below) one can see the prefix and suffix values entered. When queries are generated the prefix and suffix are applied to the supplied variable value for a given Query. For example, if the Library Name (the "Variable") value supplied for a given Query is "GSM01" then the name of that Query will be the combination of the prefix, "GSM01" and the suffix (in that order). In the case of Figure 4 that name would be "Tags from GSM01 with 0.99 cutoff".

Figure 4) An image of the Template Panel from the example Template. Here the user has set the Name Prefix and Suffix, and the result can be previewed in the "Example" field. The user has also has specified that the Description and Annotation fields should be copied into any generated Queries. In this case that means the values from Figure 3 (above). The user has left the "Variable" property of the Template to be the "Name" property of the "GSC SAGE Libraries" datatype.

Optionally the user can change the location of the "Variable" property, though in most cases this is not necessary. By default the "Variable" marker is placed on the accession of the starting set. In the example Template the "Variable" marker is placed on the "Name" property because "Name" is the Accession property of datatype "GSC SAGE Libraries".

Once a Template has been created it can either be used immediately or saved into the Databank for future use. As with all Databank definitions, Templates can be exported and shared with other users.

Using Templates

By default when a Template definition is opened up the Template panel is displayed. To use the Template the user needs to supply values for the "Variable" property. These values can be entered directly into the table of the Template panel or can be pasted from the clipboard or imported from file. Once values are present in the table the "Create Queries" button is enabled. The user simply has to click this button and one new Query will be generated for each value entered. Each Query will be added directly to the Databank.

Figure 5) An image of the Template Panel from the example Template in which the user is about to create four Queries. The user has added four values ("GSM01", "GSM02", "GSM03", "GSM04") directly into the table (bottom left). As values are entered into this table the "Create Queries" button is enabled (bottom right).

Figures 6 and 7 (below) show the results of Template execution. Each generated Query is added to the Databank in a modified (unsaved) form. Notice how closely the Query Tree of each Query matches the Query Tree from the originating Template. Also notice that the "Origin" property of each generated Query documents the name of that Template.

Figure 6) An image of the Databank after the "Create Queries" button has been clicked on the Template from Figure 5. A Query has been added for all four values and each has been added to the Databank. Notice also that the naming conventions have been correctly applied and that all four share the Description from Figure 3 as expected.

Figure 7) An image of the Properties windows from one of the newly generated Queries. The Query Tree is exactly the same as the Query Tree from Figure 2 except that the Variable marker has been replaced with a constraint. This constraint ties the Accession to the value "GSM01" (the first "Variable" value entered into the Template).

N. R. ROBERTSON 05 APR 2005