/ 
Webservice-InterMine-1.0301
River stage one • 1 direct dependent • 1 total dependent
/ Webservice::InterMine::Cookbook::Templates::Recipe1

NAME

Webservice::InterMine::Cookbook::Templates::Recipe1 - Accessing Templates

SYNOPSIS

use Webservice::InterMine 'www.flymine.org/query/service';

my $template = Webservice::InterMine->template('All_Genes_In_Organism_To_Publications)
    or die "Could not find template";

my $results  = $template->results_with(
    opA    => '=',
    valueA => 'Drosophila*'
);

DESCRIPTION

Templates are exactly like queries (they are a subclass of them) and so can do pretty much what a normal query can do, plus a little bit more.

The whole point of a template is to save you time, and avoid duplication of effort. Rather than needing to construct the perfect query every time, you can run a predefined one, with the values that you want. Since these are simply another form of query, everything in the Cookbook about using queries holds true for them as well - you can change them by adding constraints, and you can call results and results_iterator, and the result format is the same. You can even extent them with roles in exactly the same way:

my $template = Webservice::InterMine->template(
    $name,
    with => [@roles],
);

results_with

The extra behaviour relies on the fact that templates have predefined constraints. As well as the results method, there is a results_with method, which lets you define values for the template's constraints without permanently altering it. If you call $template->show_constraints to examine its composition, you would get the following results:

A) Gene.organism.name = "Saccharomyces cerevisiae" (locked)

Showing that it has one constraint, with the code 'A', which should be used in the call to results_with. After calling $template->results_with(valueA => $value) it will still have the same default value, even though I queried with a different one.

A template can have multiple constraints, and these can be specified in the same call:

$template->results_with(
    opA    => '=',
    valueA => $foo,
    opB    => 'CONTAINS',
    valueB => $bar,
);

Note that only the operators and the values for the constraints can be specified - the path of the constraint is not editable. If you are happy with the default value or the default operator for any of the constraints, you simply do not need to include it in the list:

$template->results_with(
    valueA => $foo,
    opB    => 'CONTAINS',
);

Constraint attributes

If I call

my $name = 'GeneOrganism1_OrthologueOrganism2';
print Webservice::InterMine->template($name)->show_constraints;

I get back:

'A) Homologue.gene.organism.name = "Drosophila melanogaster" (locked)
B) Homologue.homologue.organism.name = "Caenorhabditis elegans" (locked)'

If you examine the GeneOrganism1_OrthologueOrganism2 template in more detail you will find it actually has three constraints, but the third (Homologue.type = "orthologue") does not appear in the list. The reason for this is that it is not editable, and so we cannot specify its value when we call results_with. Non-editable constraints can thus be ignored when using a template.

As well as being editable or not, constraints on templates are also marked as being optional or not. If a constraint is optional (or 'switchable' in our terminology) it can be in either an active ('switched on') or inactive ('switched off') state. If it is not switchable, then it is 'locked' (as in the above examples) Although you can supply values for inactive constraints to results_with when running a template, they will be ignored in its execution. To switch a constraint off:

$template->get_constraint('A')->switch_off;

And obviously, call switch_on for the converse action. This will throw an exception if the constraint is not switchable.

Generally it is assumed if you are using a template you are familiar with what it does (possibly because you wrote it yourself - see Templates::Recipe2), and so you should know which constraints are editable/switchable or not. If you would like to find out however, there are several ways to interrogate the template for the information:

$template->show_constraints;

this will return a string with a list of editable constraints in human-readable format, as seen above.

$template->editable_constraints;

This will return list of all the constraint objects which represent editable constraints.

$constraint->editable;

This will return true if the constraint is editable

$constraint->switchable;

This will return true if the constraint is switchable

$constraint->switched_on;

This will return true if the constraint is active (locked constraints are always active - switchable constraints can be either active or not).

CONCLUSION

Templates are a way of automating commonly used queries, which in tandem with scripting can mean extremely efficient workflows. If you find that you are using some of your own queries heavily as scripts, you can make them more widely accessible by uploading them as templates, a process which we will look at in the next recipe.

AUTHOR

Alex Kalderimis <dev@intermine.org>

BUGS

Please report any bugs or feature requests to dev@intermine.org.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Webservice::InterMine

You can also look for information at:

COPYRIGHT AND LICENSE

Copyright 2006 - 2010 FlyMine, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.