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.0

Unless 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::IdMapping::StableIdGenerator::EnsemblGeneric - default Ensembl StableIdGenerator implementation

SYNOPSIS

# inject the confiured StableIdGenerator plugin
my $stable_id_generator = $conf->param('plugin_stable_id_generator');
inject($stable_id_generator);

# create a new StableIdGenerator object
my $generator_instance = $stable_id_generator->new(
  -LOGGER => $self->logger,
  -CONF   => $self->conf,
  -CACHE  => $self->cache
);

# determine starting stable ID for new assignments
my $new_stable_id = $generator_instance->initial_stable_id('gene');

# loop over genes
foreach my $target_gene (@all_target_genes) {

  # if the stable Id for this gene was mapped, assign it
  if ( $mapping_exists{ $target_gene->id } ) {
    my $source_gene = $mappings{ $target_gene->id };
    $target_gene->stable_id( $source_gene->stable_id );

    # calculate and set version
    my $version =
      $generator_instance->calculate_version( $source_gene,
      $target_gene );
    $target_gene->version($version);

    # no mapping exists, assign a new stable Id
  } else {
    $target_gene->stable_id($new_stable_id);
    $target_gene->version('1');

  # increment the stable Id (to be assigned to the next unmapped gene)
    $new_stable_id =
      $generator_instance->increment_stable_id($new_stable_id);
  }
}

DESCRIPTION

This is the default implementation for a StableIdGenerator, which is used by Bio::EnsEMBL::IdMapping::StableIdMapper to generate new stable Ids and increment versions on mapped stable Ids. Refer to the documentation in this module if you would like to implement your own StableIdGenerator.

The stable Id mapping application allows you to plugin your own implementation by specifying it with the --plugin_stable_id_generator configuration parameter.

Requirements for a StableIdGenerator plugin:

- inherit from Bio::EnsEMBL::IdMapping::BaseObject
- implement all methods listed in METHODS below (see method POD for
  signatures)

METHODS

initial_stable_id
increment_stable_id
calculate_version

initial_stable_id

Arg[1]      : String $type - an entity type (gene|transcript|translation|exon)
Example     : my $new_stable_id = $generator->initial_stable_id('gene');
Description : Determine the initial stable Id to use for new assignments. This
              method is called once at the beginning of stable Id mapping.
Return type : String - a stable Id of appropriate type
Exceptions  : none
Caller      : Bio::EnsEMBL::IdMapping::StableIdMapper::map_stable_ids()
Status      : At Risk
            : under development

increment_stable_id

Arg[1]      : String $stable_id - the stable Id to increment
Example     : $next_stable_id = $generator->increment_stable_id(
                $current_stable_id);
Description : Increments the stable Id used for new assigments. This method is
              called after each new stable Id assigment to generate the next
              stable Id to be used.
Return type : String - the next new stable Id
Exceptions  : thrown on missing or malformed argument
Caller      : Bio::EnsEMBL::IdMapping::StableIdMapper::map_stable_ids()
Status      : At Risk
            : under development

is_valid

Arg[1]      : String $stable_id - the stable Id to check
Example     : unless ($generator->is_valid($stable_id)) {
                die "Invalid stable Id: $stable_id.\n";
              }
Description : Tests a stable Id to be valid (according to the Ensembl stable
              Id format definition).
Return type : Boolean - TRUE if valid, FALSE otherwise
Exceptions  : none
Caller      : general
Status      : At Risk
            : under development

calculate_version

Arg[1]      : Bio::EnsEMBL::IdMapping::TinyFeature $s_obj - source object
Arg[2]      : Bio::EnsEMBL::IdMapping::TinyFeature $t_obj - target object
Example     : my $version = $generator->calculate_version($source_gene,
                $target_gene);
              $target_gene->version($version);
Description : Determines the version for a mapped stable Id. For Ensembl
              genes, the rules for incrementing the version number are:
                  - exons: if exon sequence changed
                  - transcript: if spliced exon sequence changed or if number of exons changed
                  - translation: if translated sequence changed
                  - gene: if any of its transcript changed
Return type : String - the version to be used
Exceptions  : thrown on wrong argument
Caller      : Bio::EnsEMBL::IdMapping::StableIdMapper::map_stable_ids()
Status      : At Risk
            : under development