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::Utils::ConversionSupport - Utility module for Vega release and schema conversion scripts
SYNOPSIS
my $serverroot = '/path/to/ensembl';
my $support = new Bio::EnsEMBL::Utils::ConversionSupport($serverroot);
# parse common options
$support->parse_common_options;
# parse extra options for your script
$support->parse_extra_options( 'string_opt=s', 'numeric_opt=n' );
# ask user if he wants to run script with these parameters
$support->confirm_params;
# see individual method documentation for more stuffDESCRIPTION
This module is a collection of common methods and provides helper functions for the Vega release and schema conversion scripts. Amongst others, it reads options from a config file, parses commandline options and does logging.
METHODS
new
Arg[1] : String $serverroot - root directory of your ensembl sandbox
Example : my $support = new Bio::EnsEMBL::Utils::ConversionSupport(
'/path/to/ensembl');
Description : constructor
Return type : Bio::EnsEMBL::Utils::ConversionSupport object
Exceptions : thrown if no serverroot is provided
Caller : generalparse_common_options
Example : $support->parse_common_options;
Description : This method reads options from a configuration file and parses
some commandline options that are common to all scripts (like
db connection settings, help, dry-run). Commandline options
will override config file settings.
All options will be accessible via $self->param('name').
Return type : true on success
Exceptions : thrown if configuration file can't be opened
Caller : generalparse_extra_options
Arg[1-N] : option descriptors that will be passed on to Getopt::Long
Example : $support->parse_extra_options('string_opt=s', 'numeric_opt=n');
Description : Parse extra commandline options by passing them on to
Getopt::Long and storing parameters in $self->param('name).
If the last option is '...' then unknown options are kept
in @ARGV for future calls to this method. Without '...'
then it is an error to have further options.
Return type : true on success
Exceptions : none (caugth by $self->error)
Caller : generalallowed_params
Arg[1-N] : (optional) List of allowed parameters to set
Example : my @allowed = $self->allowed_params(qw(param1 param2));
Description : Getter/setter for allowed parameters. This is used by
$self->confirm_params() to avoid cluttering of output with
conffile entries not relevant for a given script. You can use
$self->get_common_params() as a shortcut to set them.
Return type : Array - list of allowed parameters
Exceptions : none
Caller : generalget_common_params
Example : my @allowed_params = $self->get_common_params, 'extra_param';
Description : Returns a list of commonly used parameters in the conversion
scripts. Shortcut for setting allowed parameters with
$self->allowed_params().
Return type : Array - list of common parameters
Exceptions : none
Caller : generalget_loutre_params
Arg : (optional) return a list to parse or not
Example : $support->parse_extra_options($support->get_loutre_params('parse'))
Description : Returns a list of commonly used loutre db parameters - parse option is
simply used to distinguish between reporting and parsing parameters
Return type : Array - list of common parameters
Exceptions : none
Caller : generalget_annotrack_params
Arg : (optional) return a list to parse or not
Example : $support->parse_extra_options($support->get_annotrack_params('parse'))
Description : Returns a list of parameters used to connect to annotrack
Return type : Array - list of common parameters
Exceptions : none
Caller : generalremove_vega_params
Example : $support->remove_vega_params;
Description : Removes Vega db conection parameters. Usefull to avoid clutter in log files when
working exclusively with loutre
Return type : none
Exceptions : none
Caller : generalconfirm_params
Example : $support->confirm_params;
Description : Prints a table of parameters that were collected from config
file and commandline and asks user to confirm if he wants
to proceed.
Return type : true on success
Exceptions : none
Caller : generallist_all_params
Example : print LOG $support->list_all_params;
Description : prints a table of the parameters used in the script
Return type : String - the table to print
Exceptions : none
Caller : generalcreate_commandline_options
Arg[1] : Hashref $settings - hashref describing what to do
Allowed keys:
allowed_params => 0|1 # use all allowed parameters
exclude => [] # listref of parameters to exclude
replace => {param => newval} # replace value of param with
# newval
Example : $support->create_commandline_options({
allowed_params => 1,
exclude => ['verbose'],
replace => { 'dbname' => 'homo_sapiens_vega_33_35e' }
});
Description : Creates a commandline options string that can be passed to any
other script using ConversionSupport.
Return type : String - commandline options string
Exceptions : none
Caller : generalcheck_required_params
Arg[1-N] : List @params - parameters to check
Example : $self->check_required_params(qw(dbname host port));
Description : Checks $self->param to make sure the requested parameters
have been set. Dies if parameters are missing.
Return type : true on success
Exceptions : none
Caller : generaluser_proceed
Arg[1] : (optional) String $text - notification text to present to user
Example : # run a code snipped conditionally
if ($support->user_proceed("Run the next code snipped?")) {
# run some code
}
# exit if requested by user
exit unless ($support->user_proceed("Want to continue?"));
Description : If running interactively, the user is asked if he wants to
perform a script action. If he doesn't, this section is skipped
and the script proceeds with the code. When running
non-interactively, the section is run by default.
Return type : TRUE to proceed, FALSE to skip.
Exceptions : none
Caller : generalread_user_input
Arg[1] : (optional) String $text - notification text to present to user
Example : my $ret = $support->read_user_input("Choose a number [1/2/3]");
if ($ret == 1) {
# do something
} elsif ($ret == 2) {
# do something else
}
Description : If running interactively, the user is asked for input.
Return type : String - user's input
Exceptions : none
Caller : generalcomma_to_list
Arg[1-N] : list of parameter names to parse
Example : $support->comma_to_list('chromosomes');
Description : Transparently converts comma-separated lists into arrays (to
allow different styles of commandline options, see perldoc
Getopt::Long for details). Parameters are converted in place
(accessible through $self->param('name')).
Return type : true on success
Exceptions : none
Caller : generallist_or_file
Arg[1] : Name of parameter to parse
Example : $support->list_or_file('gene');
Description : Determines whether a parameter holds a list or it is a filename
to read the list entries from.
Return type : true on success
Exceptions : thrown if list file can't be opened
Caller : generalparam
Arg[1] : Parameter name
Arg[2-N] : (optional) List of values to set
Example : my $dbname = $support->param('dbname');
$support->param('port', 3306);
$support->param('chromosomes', 1, 6, 'X');
Description : Getter/setter for parameters. Accepts single-value params and
list params.
Return type : Scalar value for single-value parameters, array of values for
list parameters
Exceptions : thrown if no parameter name is supplied
Caller : generalerror
Arg[1] : (optional) String - error message
Example : $support->error("An error occurred: $@");
exit(0) if $support->error;
Description : Getter/setter for error messages
Return type : String - error message
Exceptions : none
Caller : generalwarnings
Example : print LOG "There were ".$support->warnings." warnings.\n";
Description : Returns the number of warnings encountered while running the
script (the warning counter is increased by $self->log_warning).
Return type : Int - number of warnings
Exceptions : none
Caller : generalserverroot
Arg[1] : (optional) String - root directory of your ensembl sandbox
Example : my $serverroot = $support->serverroot;
Description : Getter/setter for the root directory of your ensembl sandbox.
This is set when ConversionSupport object is created, so
usually only used as a getter.
Return type : String - the server root directory
Exceptions : none
Caller : generalget_database
Arg[1] : String $database - the type of database to connect to
(eg core, otter)
Arg[2] : (optional) String $prefix - the prefix used for retrieving the
connection settings from the configuration
Example : my $db = $support->get_database('core');
Description : Connects to the database specified.
Return type : DBAdaptor of the appropriate type
Exceptions : thrown if asking for unknown database
Caller : generalget_dbconnection
Arg[1] : (optional) String $prefix - the prefix used for retrieving the
connection settings from the configuration
Example : my $dbh = $self->get_dbconnection;
Description : Connects to the database server specified. You don't have to
specify a database name (this is useful for running commands
like $dbh->do('show databases')).
Return type : DBI database handle
Exceptions : thrown if connection fails
Caller : general
Status : At Riskdba
Arg[1] : (optional) String $database - type of db apaptor to retrieve
Example : my $dba = $support->dba;
Description : Getter for database adaptor. Returns default (i.e. created
first) db adaptor if no argument is provided.
Return type : Bio::EnsEMBL::DBSQL::DBAdaptor or Bio::Otter::DBSQL::DBAdaptor
Exceptions : none
Caller : generaldynamic_use
Arg [1] : String $classname - The name of the class to require/import
Example : $self->dynamic_use('Bio::EnsEMBL::DBSQL::DBAdaptor');
Description: Requires and imports the methods for the classname provided,
checks the symbol table so that it doesnot re-require modules
that have already been required.
Returntype : true on success
Exceptions : Warns to standard error if module fails to compile
Caller : internalget_chrlength
Arg[1] : (optional) Bio::EnsEMBL::DBSQL::DBAdaptor $dba
Arg[2] : (optional) String $version - coord_system version
Arg[3] : (optional) String $type - type of region eg chromsome (defaults to 'toplevel')
Arg[4] : (optional) Boolean - return non reference slies as well (required for haplotypes eq 6-COX)
Arg[5] : (optional) Override chromosome parameter filtering with this array reference. Empty denotes all.
Example : my $chr_length = $support->get_chrlength($dba);
Description : Get all chromosomes and their length from the database. Return
chr_name/length for the chromosomes the user requested (or all
chromosomes by default)
Return type : Hashref - chromosome_name => length
Exceptions : thrown if not passing a Bio::EnsEMBL::DBSQL::DBAdaptor
Caller : generalget_ensembl_chr_mapping
Arg[1] : (optional) Bio::EnsEMBL::DBSQL::DBAdaptor $dba
Arg[2] : (optional) String $version - coord_system version
Example : my $ensembl_mapping = $support->get_ensembl_chr_mapping($dba);
Description : Gets a mapping between Vega chromosome names and their
equivalent Ensembl chromosomes. Works with non-reference chromosomes
Return type : Hashref - Vega name => Ensembl name
Exceptions : thrown if not passing a Bio::EnsEMBL::DBSQL::DBAdaptor
Caller : generalget_taxonomy_id
Arg[1] : Bio::EnsEMBL::DBSQL::DBAdaptor $dba
Example : my $sid = $support->get_taxonony_id($dba);
Description : Retrieves the taxononmy ID from the meta table
Return type : Int - the taxonomy ID
Exceptions : thrown if no taxonomy ID is found in the database
Caller : generalget_species_scientific_name
Arg[1] : Bio::EnsEMBL::DBSQL::DBAdaptor $dba
Example : my $species = $support->get_species_scientific_name($dba);
Description : Retrieves the species scientific name (Genus species) from the
meta table
Return type : String - species scientific name
Exceptions : thrown if species name can not be determined from db
Caller : generalspecies
Arg[1] : (optional) String $species - species name to set
Example : my $species = $support->species;
my $url = "http://vega.sanger.ac.uk/$species/";
Description : Getter/setter for species name (Genus_species). If not set, it's
determined from database's meta table
Return type : String - species name
Exceptions : none
Caller : generalsort_chromosomes
Arg[1] : (optional) Hashref $chr_hashref - Hashref with chr_name as keys
Example : my $chr = { '6-COX' => 1, '1' => 1, 'X' => 1 };
my @sorted = $support->sort_chromosomes($chr);
Description : Sorts chromosomes in an intuitive way (numerically, then
alphabetically). If no chromosome hashref is passed, it's
retrieve by calling $self->get_chrlength()
Return type : List - sorted chromosome names
Exceptions : thrown if no hashref is provided
Caller : general_by_chr_num
Example : my @sorted = sort _by_chr_num qw(X, 6-COX, 14, 7);
Description : Subroutine to use in sort for sorting chromosomes. Sorts
numerically, then alphabetically
Return type : values to be used by sort
Exceptions : none
Caller : internal ($self->sort_chromosomes)split_chromosomes_by_size
Arg[1] : (optional) Int $cutoff - the cutoff in bp between small and
large chromosomes
Arg[2] : (optional) Boolean to include duplicate regions, ie PAR or not
(default is no)
Arg[3] : (optional) Coordsystem version to retrieve
Example : my $chr_slices = $support->split_chromosomes_by_size;
foreach my $block_size (keys %{ $chr_slices }) {
print "Chromosomes with blocksize $block_size: ";
print join(", ", map { $_->seq_region_name }
@{ $chr_slices->{$block_size} });
}
Description : Determines block sizes for storing DensityFeatures on
chromosomes, and return slices for each chromosome. The block
size is determined so that you have 150 bins for the smallest
chromosome over 5 Mb in length. For chromosomes smaller than 5
Mb, an additional smaller block size is used to yield 150 bins
for the overall smallest chromosome. This will result in
reasonable resolution for small chromosomes and high
performance for big ones. Does not return non-reference seq_regions
Return type : Hashref (key: block size; value: Arrayref of chromosome
Bio::EnsEMBL::Slices)
Exceptions : none
Caller : density scriptsis_patch
Arg[1] : B::E::Slice
Example : if ($support->is_patch($slice)) { ...
Description : Looks at seq_region attributes to decide if a slice is a patch or not
If PATCH seq_region_attrib is not there check to see if name suggests it is a PATCH
Return type : true/falselog
Arg[1] : String $txt - the text to log
Arg[2] : Int $indent - indentation level for log message
Example : my $log = $support->log_filehandle;
$support->log('Log foo.\n', 1);
Description : Logs a message to the filehandle initialised by calling
$self->log_filehandle(). You can supply an indentation level
to get nice hierarchical log messages.
Return type : true on success
Exceptions : thrown when no filehandle can be obtained
Caller : generallock_log
Description : Use flock-style locks to lock log and fastforward to end.
Useful if log is being written to by multiple processes.unlock_log
Description : Unlock log previously locked by lock_log.log_warning
Arg[1] : String $txt - the warning text to log
Arg[2] : Int $indent - indentation level for log message
Arg[3] : Bool - add a line break before warning if true
Example : my $log = $support->log_filehandle;
$support->log_warning('Log foo.\n', 1);
Description : Logs a message via $self->log and increases the warning counter.
Return type : true on success
Exceptions : none
Caller : generallog_error
Arg[1] : String $txt - the error text to log
Arg[2] : Int $indent - indentation level for log message
Example : my $log = $support->log_filehandle;
$support->log_error('Log foo.\n', 1);
Description : Logs a message via $self->log and exits the script.
Return type : none
Exceptions : none
Caller : generallog_verbose
Arg[1] : String $txt - the warning text to log
Arg[2] : Int $indent - indentation level for log message
Example : my $log = $support->log_filehandle;
$support->log_verbose('Log this verbose message.\n', 1);
Description : Logs a message via $self->log if --verbose option was used
Return type : TRUE on success, FALSE if not verbose
Exceptions : none
Caller : generallog_stamped
Arg[1] : String $txt - the warning text to log
Arg[2] : Int $indent - indentation level for log message
Example : my $log = $support->log_filehandle;
$support->log_stamped('Log this stamped message.\n', 1);
Description : Appends timestamp and memory usage to a message and logs it via
$self->log
Return type : TRUE on success
Exceptions : none
Caller : generallog_filehandle
Arg[1] : (optional) String $mode - file access mode
Example : my $log = $support->log_filehandle;
# print to the filehandle
print $log 'Lets start logging...\n';
# log via the wrapper $self->log()
$support->log('Another log message.\n');
Description : Returns a filehandle for logging (STDERR by default, logfile if
set from config or commandline). You can use the filehandle
directly to print to, or use the smart wrapper $self->log().
Logging mode (truncate or append) can be set by passing the
mode as an argument to log_filehandle(), or with the
--logappend commandline option (default: truncate)
Return type : Filehandle - the filehandle to log to
Exceptions : thrown if logfile can't be opened
Caller : generalfilehandle
Arg[1] : String $mode - file access mode
Arg[2] : String $file - input or output file
Example : my $fh = $support->filehandle('>>', '/path/to/file');
# print to the filehandle
print $fh 'Your text goes here...\n';
Description : Returns a filehandle (*STDOUT for writing, *STDIN for reading
by default) to print to or read from.
Return type : Filehandle - the filehandle
Exceptions : thrown if file can't be opened
Caller : generalinit_log_date
Example : $support->init_log_date;
Description : Opens a filehandle to a logfile with the date in the file name
Return type : Filehandle - the log filehandle
Exceptions : none
Caller : generalinit_log
Example : $support->init_log;
Description : Opens a filehandle to the logfile and prints some header
information to this file. This includes script name, date, user
running the script and parameters the script will be running
with.
Return type : Filehandle - the log filehandle
Exceptions : none
Caller : generalfinish_log
Example : $support->finish_log;
Description : Writes footer information to a logfile. This includes the
number of logged warnings, timestamp and memory footprint.
Return type : TRUE on success
Exceptions : none
Caller : generaldate_and_mem
Example : print LOG "Time, memory usage: ".$support->date_and_mem."\n";
Description : Prints a timestamp and the memory usage of your script.
Return type : String - timestamp and memory usage
Exceptions : none
Caller : generaldate
Example : print "Date: " . $support->date . "\n";
Description : Prints a nicely formatted datetamp (YYYY-DD-MM)
Return type : String - the timestamp
Exceptions : none
Caller : generaldate_and_time
Example : print "Date: " . $support->date . "\n";
Description : Prints a nicely formatted timestamp (YYYY-DD-MM hh:mm:ss)
Return type : String - the timestamp
Exceptions : none
Caller : generalformat_time
Example : print $support->format_time($gene->modifed_date) . "\n";
Description : Prints timestamps from the database
Return type : String - nicely formatted time stamp
Exceptions : none
Caller : generalmem
Example : print "Memory usage: " . $support->mem . "\n";
Description : Prints the memory used by your script. Not sure about platform
dependence of this call ...
Return type : String - memory usage
Exceptions : none
Caller : generalcommify
Arg[1] : Int $num - a number to commify
Example : print "An easy to read number: ".$self->commify(100000000);
# will print 100,000,000
Description : put commas into a number to make it easier to read
Return type : a string representing the commified number
Exceptions : none
Caller : general
Status : stablefetch_non_hidden_slices
Arg[1] : B::E::SliceAdaptor
Arg[2] : B::E::AttributeAdaptor
Arg[3] : string $coord_system_name (optional) - 'chromosome' by default
Arg[4] : string $coord_system_version (optional) - 'otter' by default
Example : $chroms = $support->fetch_non_hidden_slice($sa,$aa);
Description : retrieve all slices from a loutre database that don't have a hidden attribute.
Doesn't retrieve non-reference slices
Return type : arrayref
Caller : general
Status : stableget_non_hidden_slice_names
Arg[1] : B::E::SliceAdaptor
Arg[2] : B::E::AttributeAdaptor
Arg[3] : string $coord_system_name (optional) - 'chromosome' by default
Arg[4] : string $coord_system_version (optional) - 'otter' by default
Example : $chrom_names = $support->get_non_hidden_slice_names($sa,$aa);
Description : retrieve names of all slices from a loutre database that don't have a hidden attribute.
Doesn't retrieve non-reference slices
Return type : arrayref of names of all non-hidden slices
Caller : general
Status : stableget_wanted_chromosomes
Arg[1] : B::E::SliceAdaptor
Arg[2] : B::E::AttributeAdaptor
Arg[3] : string $coord_system_name (optional) - 'chromosome' by default
Arg[4] : string $coord_system_version (optional) - 'otter' by default
Example : $chr_names = $support->get_wanted_chromosomes($laa,$lsa);
Description : retrieve names of slices from a lutra database that are ready for dumping to Vega.
Deals with list of names to ignore (ignore_chr = LIST)
Return type : arrayref of slices
Caller : general
Status : stableis_haplotype
Arg[1] : B::E::Slice
Arg[2]: : B::E::DBAdaptor (optional, if you don't supply one then the *first* one you generated is returned, which may or may not be what you want!)
Description : Is the slice a Vega haplotype? At the moment this is
implemented by testing for presence of vega_ref_chrom but non_ref
which is correct in practice, but really misses the prupose of
vega_ref_chrom, so this might bite us if that changes.
Return type : booleanget_unique_genes
Arg[1] : B::E::Slice
Arg[2] : B::E::DBAdaptor (optional, if you don't supply one then the *first* one you generated is returned, which may or may not be what you want!)
Example : $genes = $support->get_unique_genes($slice,$dba);
Description : Retrieve genes that are only on the slice itself - used for human where assembly patches
are in the assembly_exception table. Needs the PATCHes to have 'non_ref' seq_region_attributes.
Return type : arrayref of genes
Caller : general
Status : stableget_attrib_values
Arg[1] : Arrayref of B::E::Attributes
Arg[2] : 'code' to search for
Arg[3] : 'value' to search for (optional)
Example : my $c = $self->get_attrib_values($attribs,'name'));
Description : (i) In the absence of an attribute value argument, examines an arrayref
of B::E::Attributes for a particular attribute type, returning the values
for each attribute of that type. Can therefore be used to test for the
number of attributes of that type.
(ii) In the presence of the optional value argument it returns all
attributes with that value ie can be used to test for the presence of an
attribute with that particular value.
Return type : arrayref of values for that attribute
Caller : general
Status : stablefix_attrib_value
Arg[1] : Arrayref of existing B::E::Attributes
Arg[2] : dbID of object
Arg[3] : name of object (just for reporting)
Arg[4] : attrib_type.code
Arg[5] : attrib_type.value
Arg[6] : interactive ? (0 by default)
Arg[7] : table
Example : $support->fix_attrib_value($attribs,$chr_id,$chr_name,'vega_export_mod','N',1);
Description : adds a new attribute to an object, or updates an existing attribute with a new value
Can be run in interactive or non-interactive mode (default)
Return type : arrayref of results
Caller : general
Status : only ever tested with seq_region_attributes to date_get_attrib_id
Arg[1] : attrib_type.code
Arg[2] : database handle
Example : $self->_get_attrib_id('name',$dbh)
Description : get attrib_type.attrib_type_id from a attrib_type.code
Return type : attrib_type.attrib_type_id
Caller : internal
Status : stablestore_new_attribute
Arg[1] : seq_region.seq_region_id
Arg[2] : attrib_type.code
Arg[3] : attrib_type.value
ARG[4] : table to update (seq_region_attribute by default)
Example : $support->store_new_attribute(23,name,5);
Description : uses MySQL to store an entry (code and value) in an attribute table
(seq_region_attrib by default)
Return type : array_ref
Caller : general
Status : stableupdate_attribute
Arg[1] : seq_region.seq_region_id
Arg[2] : attrib_type.code
Arg[3] : attrib_type.value
ARG[4] : table to update (seq_region_attribute by default)
Example : $support->update_attribute(23,name,5);
Description : uses MySQL to update an attribute table (seq_region_attrib by default)
Return type : array_ref
Caller : general
Status : stableremove_duplicate_attribs
Arg[1] : db handle
Arg[2] : table
Example : $support->remove_duplicate_attribs($dbh,'gene');
Description : uses MySQL to remove duplicate entries from an attribute table
Return type : none
Caller : general
Status : stablesav_seq
Arg[1] : string (sequence to save)
Example : $support->save_seq('ACGT')
Description : creates a temporary file containing the sequence you give it
Return type : string (filename)
Caller : general
Status : stableget_alignment
Arg[1] : string (first sequence)
Arg[1] : string (second sequence)
Arg[1] : string (sequence type))
Example : $support->get_alignment('AAAAA','CCCCCCC','DNA')
Description : creates a temporary file containing the sequence you give it
Return type : string (filename)
Caller : general
Status : stable