LICENSE
Copyright [1999-2015] Wellcome Trust Sanger Institute and the EMBL-European Bioinformatics Institute Copyright [2016-2024] EMBL-European Bioinformatics Institute
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
CONTACT
Please email comments or questions to the public Ensembl
developers list at <http://lists.ensembl.org/mailman/listinfo/dev>.
Questions may also be sent to the Ensembl help desk at
<http://www.ensembl.org/Help/Contact>.NAME
Bio::EnsEMBL::External::ExternalFeatureAdaptor
SUMMARY
Allows features created externally from Ensembl in a single coordinate system to be retrieved in several other (Ensembl-style) coordinate systems. This is intended to be a replacement for the old Bio::EnsEMBL::DB::ExternalFeatureFactoryI interface.
SYNOPSIS
$database_adaptor = new Bio::EnsEMBL::DBSQL::DBAdaptor(
-host => 'kaka.sanger.ac.uk',
-dbname => 'homo_sapiens_core_9_30',
-pass => 'anonymous'
);
$xf_adaptor = new ExternalFeatureAdaptorSubClass;
# Connect the Ensembl core database:
$xf_adaptor->db($database_adaptor);
# get some features in vontig coords
@feats =
@{ $xf_adaptor->fetch_all_by_contig_name('AC000087.2.1.42071') };
# get some features in assembly coords
@feats =
@{ $xf_adaptor->fetch_all_by_chr_start_end( 'X', 100000, 200000 ) };
# get some features in clone coords
@feats = @{ $xf_adaptor->fetch_all_by_clone_accession('AC000087') };
# Add the adaptor to the ensembl core dbadaptor (implicitly sets db
# attribute)
$database_adaptor->add_ExternalFeatureAdaptor($xf_adaptor);
# get some features in Slice coords
$slice_adaptor = $database_adaptor->get_SliceAdaptor;
$slice =
$slice_adaptor->fetch_all_by_chr_start_end( 1, 100000, 200000 );
@feats = @{ $xf_adaptor->fetch_all_by_Slice($slice) };
# now features can be retrieved directly from Slice
@feats = @{ $slice->get_all_ExternalFeatures };DESCRIPTION
This class is intended to be used as a method of getting external features into EnsEMBL. To work, this class must be extended and must implement the the coordinate_systems method. As well, the subclass is required to implement a single fetch method so that the external features may be retrieved. By implementing a single fetch_method in a single coordinate system all of the other ExternalFeatureAdaptor fetch methods become available for retrieving the data in several different coordinate systems.
The coordinate_systems method should return a list of strings indicating which coordinate system(s) have been implemented. If a given string is returned from the coordinate_systems method then the corresponding fetch method must be implemented. The reverse is also true: if a fetch method is implemented then coordinate_systems must return the appropriate string in its list of return values. The following are the valid coordinate system values and the corresponding fetch methods that must be implemented:
COORD SYSTEM STRING FETCH_METHOD
------------------- ------------
'ASSEMBLY' fetch_all_by_chr_start_end
'CLONE' fetch_all_by_clone_accession
'CONTIG' fetch_all_by_contig_name
'SUPERCONTIG' fetch_all_by_supercontig_name
'SLICE' fetch_all_by_SliceThe objects returned by the fetch methods should be EnsEMBL or BioPerl style Feature objects. These objects MUST have start, end and strand methods.
Before the non-overridden ExternalFeatureAdaptor fetch methods may be called an EnsEMBL core database adaptor must be attached to the ExternalFeatureAdaptor . This database adaptor is required to perform the remappings between various coordinate system. This may be done implicitly by adding the ExternalFeatureAdaptor to the database adaptor through a call to the DBAdaptor add_ExternalFeatureAdaptor method or explicitly by calling the ExternalFeatureAdaptor ensembl_db method.
METHODS
new
Arg [1] : none
Example : $xfa = new Bio::EnsEMBL::External::ExternalFeatureAdaptor;
Description: Creates a new ExternalFeatureAdaptor object. You may wish to
extend this constructor and provide your own set of paremeters.
Returntype : Bio::EnsEMBL::External::ExternalFeatureAdaptor
Exceptions : none
Caller : generalensembl_db
Arg [1] : (optional) Bio::EnsEMBL::DBSQL::DBAdaptor
Example : $external_feature_adaptor->ensembl_db($new_val);
Description: none
Returntype : Bio::EnsEMBL::DBSQL::DBAdaptor
Exceptions : none
Caller : internalcoordinate_systems
Arg [1] : none
Example : @implemented_coord_systems = $ext_adaptor->coordinate_systems;
Description: ABSTRACT method. Must be implemented by all
ExternalFeatureAdaptor subclasses. This method returns a list
of coordinate systems which are implemented by the subclass.
A minimum of on valid coordinate system must be implemented.
Valid coordinate systems are: 'SLICE', 'ASSEMBLY', 'CONTIG',
and 'CLONE'.
Returntype : list of strings
Exceptions : none
Caller : internaltrack_name
Arg [1] : none
Example : $track_name = $xf_adaptor->track_name;
Description: Currently this is not really used. In the future it may be
possible to have ExternalFeatures automatically displayed by
the EnsEMBL web code. By default this method returns
'External features' but you are encouraged to override this
method and provide your own meaningful name for the features
your adaptor provides. This also allows you to distinguish the
type of features retrieved from Slices. See
the PODs for Bio::EnsEMBL::Slice::get_all_ExternalFeatures and
Bio::EnsEMBL::DBSQL::DBAdaptor::add_ExternalFeatureAdaptor
methods.
Returntype : string
Exceptions : none
Caller : Bio::EnsEMBL::DBSQL::DBAdaptor::add_ExternalFeatureAdaptorfeature_type
Arg [1] : none
Example : $feature_type = $xf_adaptor->track_name
Description: Currently this is not used. In the future it may be possible
to have ExternalFeatures automatically displayed by the EnsEMBL
web code. This method would then be used do determine the
type of glyphs used to draw the features which are returned
from this external adaptor.
Returntype : string
Exceptions : none
Caller : nonefetch_all_by_Slice
Arg [1] : Bio::EnsEMBL::Slice $slice
Example : @features = @{$ext_adaptor->fetch_all_by_Slice($slice)};
Description: Retrieves all features which lie in the region defined
by $slice in slice coordinates.
If this method is overridden then the coordinate_systems method
must return 'SLICE' as one of its values.
This method will work as is (i.e. without overriding it)
providing at least one of the other fetch methods is overridden.
Returntype : reference to a list of Bio::SeqFeature objects in the Slice
coordinate system
Exceptions : Thrown on incorrect input arguments
Caller : general, fetch_all_by_chr_start_endfetch_all_by_contig_name
Arg [1] : string $contig_name
Arg [2] : int $start (optional)
The start of the region on the contig to retrieve features on
if not specified the whole of the contig is used.
Arg [3] : int $end (optional)
The end of the region on the contig to retrieve features on
if not specified the whole of the contig is used.
Example : @fs = @{$self->fetch_all_by_contig_name('AB00879.1.1.39436')};
Description: Retrieves features on the contig defined by the name
$contig_name in contig coordinates.
If this method is overridden then the coordinate_systems
method must return 'CONTIG' as one of its values.
This method will work as is (i.e. without being overridden)
providing at least one other fetch method has
been overridden.
Returntype : reference to a list of Bio::SeqFeature objects in the contig
coordinate system.
Exceptions : thrown if the input argument is incorrect
thrown if the coordinate_systems method returns the value
'CONTIG' and this method has not been overridden.
Caller : general, fetch_all_by_Slicefetch_all_by_supercontig_name
Arg [1] : string $supercontig_name
Arg [2] : int $start (optional)
The start of the region on the contig to retrieve features on
if not specified the whole of the contig is used.
Arg [3] : int $end (optional)
The end of the region on the contig to retrieve features on
if not specified the whole of the contig is used.
Example : @fs = @{$self->fetch_all_by_contig_name('NT_004321')};
Description: Retrieves features on the contig defined by the name
$supercontigname in supercontig coordinates.
If this method is overridden then the coordinate_systems
method must return 'SUPERCONTIG' as one of its values.
This method will work as is (i.e. without being overridden)
providing at least one other fetch method has
been overridden.
Returntype : reference to a list of Bio::SeqFeature objects in the contig
coordinate system.
Exceptions : thrown if the input argument is incorrect
thrown if the coordinate_systems method returns the value
'SUPERCONTIG' and this method has not been overridden.
Caller : general, fetch_all_by_Slicefetch_all_by_clone_accession
Arg [1] : string $acc
The EMBL accession number of the clone to fetch features from.
Arg [2] : (optional) string $ver
Arg [3] : (optional) int $start
Arg [4] : (optional) int $end
Example : @fs = @{$self->fetch_all_by_clone_accession('AC000093')};
Description: Retrieves features on the clone defined by the $acc arg in
Clone coordinates.
If this method is overridden then the coordinate_systems method
must return 'CLONE' as one of its values. The arguments
start, end, version are passed if this method is overridden and
can optionally be used to reduce the scope of the query and
improve performance.
This method will work as is - providing at least one other
fetch method has been overridden.
Returntype : reference to a list of Bio::SeqFeature objects in the Clone
coordinate system
Exceptions : thrown if the input argument is incorrect
thrown if the coordinate system method returns the value 'CLONE'
and this method is not overridden.
thrown if the coordinate systems method does not return any
valid values.
Caller : general, fetch_all_by_clone_accessionfetch_all_by_chr_start_end
Arg [1] : string $chr_name
The name of the chromosome to retrieve features from
Arg [2] : int $start
The start coordinate of the chromosomal region to retrieve
features from.
Arg [3] : int $end
The end coordinate of the chromosomal region to retrieve
features from.
Example : @features
Description: Retrieves features on the region defined by the $chr_name,
$start, and $end args in assembly (chromosomal) coordinates.
If this method is overridden then the coordinate_systems method
must return 'ASSEMBLY' as one of its values.
This method will work as is (i.e. without overriding it)
providing at least one of the other fetch methods is overridden.
Returntype : reference to a list of Bio::SeqFeatures
Exceptions : Thrown if the coordinate_systems method returns ASSEMBLY as a
value and this method is not overridden.
Thrown if any of the input arguments are incorrect
Caller : general, fetch_all_by_Slice_no_valid_coord_system
Arg [1] : none
Example : none
Description: PRIVATE method - throws an error with a descriptive message
Returntype : none
Exceptions : always thrown
Caller : internal_supported
Arg [1] : string $system
Example : print "CONTIG system supported" if($self->_supported('CONTIG'));
Description: PRIVATE method. Tests if the coordinate system defined by
the $system argument is implemented.
Returntype : boolean
Exceptions : none
Caller : internal