NAME
Bio::Das::ProServer::SourceAdaptor - base class for sources
VERSION
$Revision: 637 $
SYNOPSIS
A base class implementing stubs for all SourceAdaptors.
DESCRIPTION
SourceAdaptor.pm generates XML and manages callouts for DAS request handling.
If you're extending ProServer, this class is probably what you need to inherit. The build_* methods are probably the ones you need to extend. build_features() in particular.
AUTHOR
Roger Pettett <rmp@sanger.ac.uk>
Andy Jenkinson <andy.jenkinson@ebi.ac.uk>
SUBROUTINES/METHODS
new - Constructor
my $oSourceAdaptor = Bio::Das::ProServer::SourceAdaptor::<implementation>->new({
'dsn' => q(),
'port' => q(),
'hostname' => q(),
'protocol' => q(),
'baseuri' => q(),
'config' => q(),
'debug' => 1,
});
Generally this would only be invoked on a subclassinit - Post-construction initialisation, passed the first argument to new()
$oSourceAdaptor->init();length - Returns the segment-length given a segment
my $sSegmentLength = $oSourceAdaptor->length('DYNA_CHICK');
By default returns 0mapmaster - Mapmaster for this source.
my $sMapMaster = $oSourceAdaptor->mapmaster();
By default returns configuration 'mapmaster' settingdescription - Description for this source.
my $sDescription = $oSourceAdaptor->description();
By default returns configuration 'description' setting or $self->titledoc_href - Location of a homepage for this source.
my $sDocHref = $oSourceAdaptor->doc_href();
By default returns configuration 'doc_href' settingtitle - Short title for this source.
my $title = $oSourceAdaptor->title();
By default returns configuration 'title' setting or $self->source_urisource_uri - URI for all versions of a source.
my $uriS = $oSourceAdaptor->source_uri();
By default returns configuration 'source_uri' setting or $self->dsnversion_uri - URI for a specific version of a source.
my $uriV = $oSourceAdaptor->version_uri();
By default returns configuration 'version_uri' setting or $self->source_urimaintainer - Contact email for this source.
my $email = $oSourceAdaptor->maintainer();
By default returns configuration 'maintainer' setting, server setting or an empty stringstrict_boundaries - Whether to return error segments for out-of-range queries
my $strict = $oSourceAdaptor->strict_boundaries(); # boolean
By default returns configuration 'strict_boundaries' setting, server setting or nothing (false)build_features - (subclasses only) Fetch feature data
This call is made by das_features(). It is passed one of:
{ 'segment' => $, 'start' => $, 'end' => $, 'types' => [$,$,...], 'maxbins' => $ }
{ 'feature_id' => $ }
{ 'group_id' => $, 'types' => [$,$,...], 'maxbins' => $ }
and is expected to return an array of hash references, i.e.
( {},{}...{} )Each hash returned represents a single feature and should contain a subset of the following keys and types. For scalar types (i.e. numbers and strings) refer to the specification on biodas.org.
segment => $ # segment ID (if not provided)
id || feature_id => $ # feature ID
label || feature_label => $ # feature text label
start => $ # feature start position
end => $ # feature end position
ori => $ # feature strand
phase => $ # feature phase
type => $ # feature type ID
typetxt => $ # feature type text label
typecategory || type_category => $ # feature type category
typesubparts => $ # feature has subparts
typesuperparts => $ # feature has superparts
typereference => $ # feature is reference
method => $ # annotation method ID
method_label => $ # annotation method text label
score => $ # annotation score
note => $ or [$,$,$...] # feature text note
##########################################################################
# For one or more links:
link => $ or [$,$,$...] # feature link href
linktxt => $ or [$,$,$...] # feature link label
# For hash-based links:
link => {
$ => $, # href => label
...
}
###############################################################################
# For a single target:
target_id => $ # target ID
target_start => $ # target start position
target_stop => $ # target end position
targettxt => $ # target text label
# For multiple targets:
target => scalar or [{
id => $,
start => $,
stop => $,
targettxt => $,
},{}...]
###############################################################################
# For a single group:
group_id => $ # feature group ID
grouplabel => $ # feature group text label
grouptype => $ # feature group type ID
groupnote => $ # feature group text note
grouplink => $ # feature group ID
grouplinktxt => $ # feature group ID
# For multiple groups:
group => [{
grouplabel => $
grouptype => $
groupnote => $
grouplink => $
grouplinktxt => $
note => $ or [$,$,$...]
target => [{
id => $
start => $
stop => $
targettxt => $
}],
}, {}...]sequence - (Subclasses only) fetch sequence/DNA data
This call is made by das_sequence() or das_dna(). It is passed:
{ 'segment' => $, 'start' => $, 'end' => $ }It is expected to return a hash reference:
{
seq => $,
version => $, # can also be specified with the segment_version method
moltype => $,
}For details of the data constraints refer to the specification on biodas.org.
build_types - (Subclasses only) fetch type data
This call is made by das_types(). If no specific segments are requested by the client, it is passed no arguments. Otherwise it is passed:
{ 'segment' => $, 'start' => $, 'end' => $ }It is expected to return an array of hash references, i.e. ( {},{}...{} )
Each hash returned represents a single type and should contain a subset of the following keys and values. For scalar types (i.e. numbers and strings) refer to the specification on biodas.org.
type => $ # required
count => $ # required
category|typecategory|type_category => $
method => $
c_ontology => $
evidence => $
e_ontology => $
description => $build_entry_points - (Subclasses only) fetch entry_points data
This call is made by das_entry_points(). It is not passed any args
and is expected to return an array of hash references, i.e. ( {},{}...{} )
Each hash returned represents a single entry_point and should contain a subset of the following keys and values. For scalar types (i.e. numbers and strings) refer to the specification on biodas.org.
segment => $
length => $
subparts => $
start => $
stop => $
ori => $build_alignment - (Subclasses only) fetch alignment data
This call is made by das_alignment(). It is passed these arguments:
(
$, # query sequence
$, # number of rows
[ $, $ ], # subjects
$ # subject coordinate system
)It is expected to return an array of alignment hash references:
(
{
name => $,
type => $,
max => $,
position => $,
alignObj => [
{
id => $, # internal object ID
version => $,
type => $,
dbSource => $,
dbVersion => $,
dbAccession => $,
dbCoordSys => $,
sequence => $,
aliObjectDetail => [
{
property => $,
value => $,
dbSource => $,
},
],
},
],
scores => [
{
method => $,
score => $,
},
],
blocks => [
{
blockOrder => $,
blockScore => $,
segments => [
{
id => $, # internal object ID
start => $,
end => $,
orientation => $, # + / - / undef
cigar => $,
},
],
],
geo3D => [
{
id
vector => {
x => $,
y => $,
z => $,
},
matrix => [
[$,$,$], # mat11, mat12, mat13
[$,$,$], # mat21, mat22, mat23
[$,$,$], # mat31, mat32, mat33
],
},
],
}
)build_interaction - (Subclasses only) fetch interaction data
This call is made by das_interaction(). It is passed this structure:
# For request:
# /interaction?interactor=$;interactor=$;detail=property:$;detail=property:$,value:$
{
interactors => [$, $, ..],
details => {
$ => undef, # property exists
$ => $, # property has a certain value
},
}It is expected to return a hash reference of interactions and interactors where all the requested interactors are part of the interaction:
{
interactors => [
{
id => $,
label || name => $,
dbSource => $,
dbSourceCvId => $, # controlled vocabulary ID
dbVersion => $,
dbAccession => $,
dbCoordSys => $, # co-ordinate system
sequence => $,
details => [
{
property => $,
value => $,
propertyCvId => $,
valueCvId => $,
start => $,
end => $,
startStatus => $,
endStatus => $,
startStatusCvId => $,
endStatusCvId => $,
},
..
],
},
..
],
interactions => [
{
label || name => $,
dbSource => $,
dbSourceCvId => $,
dbVersion => $,
dbAccession => $,
details => [
{
property => $,
value => $,
propertyCvId => $,
valueCvId => $,
},
..
],
participants => [
{
id => $,
details => [
{
property => $,
value => $,
propertyCvId => $,
valueCvId => $,
start => $,
end => $,
startStatus => $,
endStatus => $,
startStatusCvId => $,
endStatusCvId => $,
},
..
],
},
..
],
},
..
],
}build_volmap - (Subclasses only) fetch volume map data
This call is made by das_volmap(). It is passed a single 'query' argument.
It is expected to return a hash reference for a single volume map:
{
id => $,
class => $,
type => $,
version => $,
link => $, # href for data
linktxt => $, # text
note => $ OR [ $, $, .. ]
}init_segments - hook for optimising results to be returned.
By default - do nothing
Not necessary for most circumstances, but useful for deciding on what sort
of coordinate system you return the results if more than one type is available.
$self->init_segments() is called inside das_features() before build_features().known_segments - returns a list of valid segments that this adaptor knows about
my @aSegmentNames = $oSourceAdaptor->known_segments();segment_version - gives the version of a segment (MD5 under certain circumstances) given a segment name
my $sVersion = $oSourceAdaptor->segment_version($sSegment);dsn - get accessor for this sourceadaptor's dsn
my $sDSN = $oSourceAdaptor->dsn();dsnversion - get accessor for this sourceadaptor's dsn version
my $sDSNVersion = $oSourceAdaptor->dsnversion();
By default returns $self->{'dsnversion'}, configuration 'dsnversion' setting or '1.0'dsncreated - get accessor for this sourceadaptor's update time (variable format)
# e.g. '2007-09-20T15:26:23Z' -- ISO 8601, Coordinated Universal Time
# e.g. '2007-09-20T16:26:23+01:00' -- ISO 8601, British Summer Time
# e.g. '2007-09-20 07:26:23 -08' -- indicating Pacific Standard Time
# e.g. 1190301983 -- UNIX
# e.g. '2007-09-20'
my $sDSNCreated = $oSourceAdaptor->dsncreated();
By default tries and returns the following:
1. $self->{'dsncreated'}
2. configuration 'dsncreated' setting
3. adaptor's 'last_modified' method (if it exists)
4. zero (epoch)dsncreated_unix - this sourceadaptor's update time, in UNIX format
# e.g. 1190301983
my $sDSNCreated = $oSourceAdaptor->dsncreated_unix();dsncreated_iso - this sourceadaptor's update time, in ISO 8601 format
# e.g. '2007-09-20T15:26:23Z'
my $sDSNCreated = $oSourceAdaptor->dsncreated_iso();coordinates - Returns this sourceadaptor's supported coordinate systems
my $hCoords = $oSourceAdaptor->coordinates();
Hash contains a key-value pair for each coordinate system, the key being
either the URI or description, and the value being a suitable test range.
By default returns an empty hash referencecoordinates_full : Returns this sourceadaptor's supported coordinate systems
my $aCoords = $oSourceAdaptor->coordinates();
Returns the fully-annotated co-ordinates systems this adaptor supports, as an
array or array reference (depending on context):
[
{
'description' => 'NCBI_36,Chromosome,Homo sapiens',
'uri' => 'http://www.dasregistry.org/dasregistry/coordsys/CS_DS40',
'taxid' => '9606',
'authority' => 'NCBI',
'source' => 'Chromosome',
'version' => '36',
'test_range' => '1:11000000,12000000',
},
{
...
},
]
The co-ordinate system details are read in from disk by Bio::Das::ProServer.
By default returns an empty array.capabilities - Returns this sourceadaptor's supported commands
my $hCapabilities = $oSourceAdaptor->capabilities();
Hash contains a key-value pair for each command, the key being the command
name, and the value being the implementation version.
By default returns an empty hash.properties - Returns custom properties for this sourceadaptor
my $hProps = $oSourceAdaptor->properties();
Hash contains key-scalar or key-array pairs for custom properties.
By default returns an empty hash referencestart - get accessor for segment start given a segment
my $sStart = $oSourceAdaptor->start('DYNA_CHICK');
By default returns 1end - get accessor for segment end given a segment
my $sEnd = $oSourceAdaptor->end('DYNA_CHICK');
By default returns $self->lengthserver_url - Get the URL for the server (not including the /das)
my $sUrl = $oSourceAdaptor->server_url();source_url - Get the full URL for the source
my $sUrl = $oSourceAdaptor->source_url();hydra - Get the relevant B::D::PS::SourceHydra::<...> configured for this adaptor, if there is one
my $oHydra = $oSourceAdaptor->hydra();transport - Build the relevant B::D::PS::SA::Transport::<...> configured for this adaptor
my $oTransport = $oSourceAdaptor->transport();
OR
my $oTransport1 = $oSourceAdaptor->transport('foo');
my $oTransport2 = $oSourceAdaptor->transport('bar');authenticator : Build the B::D::PS::Authenticator::<...> configured for this adaptor
my $oAuthenticator = $oSourceAdaptor->authenticator();
Authenticators are built only if explicitly configured in the INI file, e.g.:
[mysource]
state = on
adaptor = simple
authenticator = ip
See L<Bio::Das::ProServer::Authenticator> for more details.config - get/set config settings for this adaptor
$oSourceAdaptor->config($oConfig);
my $oConfig = $oSourceAdaptor->config();implements - helper to determine if an adaptor implements a request based on its capabilities
my $bIsImplemented = $oSourceAdaptor->implements($sDASCall); # e.g. $sDASCall = 'sequence'das_capabilities - DAS-response capabilities header support
my $sHTTPHeader = $oSourceAdaptor->das_capabilities();unknown_segment - DAS-response unknown/error segment error response
my $sXMLResponse = $sa->unknown_segment();
Reference sources (i.e. those implementing the 'dna' or 'sequence' command) will return an <ERRORSEGMENT> element.
Annotation sources will return an <UNKNOWNSEGMENT> element.error_segment - DAS-response error segment error response
my $sXMLResponse = $sa->error_segment();
Returns an <ERRORSEGMENT> element.error_feature - DAS-response unknown feature error
my $sXMLResponse = $sa->error_feature();das_features - DAS-response for 'features' request
my $sXMLResponse = $sa->das_features();
See the build_features method for details of custom implementations.das_dna - DAS-response for DNA request
my $xml = $sa->das_dna();
See the sequence method for details of custom implementations.das_sequence - DAS-response for sequence request
my $sXMLResponse = $sa->das_sequence();
See the sequence method for details of custom implementations.das_types - DAS-response for 'types' request
my $sXMLResponse = $sa->das_types();
See the build_types method for details of custom implementations.das_entry_points - DAS-response for 'entry_points' request
my $sXMLResponse = $sa->das_entry_points();
See the build_entry_points method for details of custom implementations.das_interaction - DAS-response for 'interaction' request
my $sXMLResponse = $sa->das_interaction();
See the build_interaction method for details of custom implementations.das_volmap - DAS-response for 'volmap' request
my $sXMLResponse = $sa->das_volmap();
See the build_volmap method for details of custom implementations.das_stylesheet - DAS-response for 'stylesheet' request
my $sXMLResponse = $sa->das_stylesheet();
By default will use (in order of preference):
the "stylesheet" INI property (inline XML)
the "stylesheetfile" INI property (XML file location)
the "stylesheetfile" INI property, prepended with the "styleshome" property
a default stylesheetdas_sourcedata - DAS-response for 'sources' request
my $sXMLResponse = $sa->das_sourcedata();
Provides information about the DAS source for use in the sources command,
such as title, description, coordinates and capabilities.das_homepage - DAS-response (non-standard) for 'homepage' or blank request
my $sHTMLResponse = $sa->das_homepage();
By default will use (in order of preference):
the "homepage" INI property (inline HTML)
the "homepagefile" INI property (HTML file location)
a default homepagedas_dsn - DAS-response (non-standard) for 'dsn' request
my $sXMLResponse = $sa->das_dsn();das_xsl - DAS-response (non-standard) for 'xsl' request
my $sXSLResponse = $sa->das_xsl();das_alignment - DAS-response for 'alignment' request
my $sXMLResponse = $sa->das_alignment();
See the build_alignment method for details of custom implementations.
Example Response:<alignment> <alignObject> <alignObjectDetail /> <sequence /> </alignObject> <score/> <block> <segment> <cigar /> </segment> </block> <geo3D> <vector /> <matrix mat11="float" mat12="float" mat13="float" mat21="float" mat22="float" mat23="float" mat31="float" mat32="float" mat33="float" /> </geo3D> </alignment>
_gen_align_object_response
Title : _gen_align_object_response
Function : Formats alignment object into dasalignment xml
Args : align data structure
Returns : Das Response string encapuslating aliObject_gen_align_score_response
Title : _gen_align_score_response
Function: Formats input score data structure into dasalignment xml
Args : score data structure
Returns : Das Response string from alignment score_gen_align_block_response
Title : _gen_align_block_response
Function: Formats an input block data structure into
: dasalignment xml
Args : block data structure
Returns : Das Response string from alignmentblock_gen_align_geo3d_response
Title : genAlignGeo3d
Function : Formats geo3d data structure into alignment matrix xml
Args : data structure containing the vector and matrix
Returns : String containing the DAS response xmldas_structure
Title : das_structure
Function : This produces the das repsonse for a pdb structure
Args : query options. Currently, this will that query, chain and modelnumber.
: The only part of the specification that this does not adhere to is the range argument.
: However, I think this argument is a potential can of worms!
returns : string containing Das repsonse for the pdb structure
comment : See http://www.efamily.org.uk/xml/das/documentation/structure.shtml for more information
: on the das structure specification.
Example Response:
<object dbAccessionId="1A4A" intObjectId="1A4A" objectVersion="29-APR-98" type="protein structure" dbSource="PDB" dbVersion="20040621" dbCoordSys="PDBresnum" />
<chain id="A" SwissprotId="null">
<group name="ALA" type="amino" groupID="1">
<atom atomID="1" atomName=" N " x="-19.031" y="16.695" z="3.708" />
<atom atomID="2" atomName=" CA " x="-20.282" y="16.902" z="4.404" />
<atom atomID="3" atomName=" C " x="-20.575" y="18.394" z="4.215" />
<atom atomID="4" atomName=" O " x="-20.436" y="19.194" z="5.133" />
<atom atomID="5" atomName=" CB " x="-20.077" y="16.548" z="5.883" />
<atom atomID="6" atomName="1H " x="-18.381" y="17.406" z="4.081" />
<atom atomID="7" atomName="2H " x="-18.579" y="15.781" z="3.874" />
<atom atomID="8" atomName="3H " x="-19.018" y="16.844" z="2.68" />
</group>
<group name="HOH" type="hetatm" groupID="219">
<atom atomID="3057" atomName=" O " x="-17.904" y="13.635" z="-7.538" />
<atom atomID="3058" atomName="1H " x="-18.717" y="14.098" z="-7.782" />
<atom atomID="3059" atomName="2H " x="-17.429" y="13.729" z="-8.371" />
</group>
</chain>
<connect atomSerial="26" type="bond">
<atomID atomID="25" />
<atomID atomID="242" />
</connect>_gen_object_response
Title : _gen_object_response
Function : Formats the supplied structure object data structure into dasstructure xml
Args : object data structure
Returns : Das Response string encapuslating 'object'
Comment : The object response allows the details of the coordinates to be descriped. For example
: the fact that the coos are part of a pdb file._gen_chain_response
Title : _gen_chain_response
Function : Formats the supplied chain object data structure into dasstructure xml
Args : chain data structure
Returns : Das Response string encapuslating 'chain'
Comment : Chain objects contain all of the atom positions (including hetatoms).
: The groups are typically residues or ligands._gen_connect_response
Title : _gen_connect_response
Function : Formats the supplied connect data structure into dasstructure xml
Args : connect data structure
Returns : Das Response string encapuslating "connect"
Comment : Such objects are specified to enable groups of atoms to be connected together.cleanup : Post-request garbage collection
CONFIGURATION AND ENVIRONMENT
Used within Bio::Das::ProServer::Config, eg/proserver and of course all subclasses.
DIAGNOSTICS
set $self->{'debug'} = 1
DEPENDENCIES
INCOMPATIBILITIES
None reported
BUGS AND LIMITATIONS
None reported
LICENSE AND COPYRIGHT
Copyright (c) 2008 The Sanger Institute
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.