Bio::Taxonomy::GlobalNames - Perlish OO bindings to the Global Names Resolver API
Version 0.06
use Bio::Taxonomy::GlobalNames; # Provide the input data and parameters. my $query = Bio::Taxonomy::GlobalNames->new( names => $names, data_source_ids => $data_source_ids, resolve_once => $resolve_once, ); my $output = $query->post(); # Perform a POST request and return the output. # Go through the Output object. my @data = @{ $output->data }; foreach my $datum (@data) { # Check if a non-empty Results arrayref was returned. if ( my @results = @{ $datum->results } ) { # Parse the Results objects. foreach my $result (@results) { # Retrieve the canonical name and score for each result. my $canonical_name = $result->canonical_form; my $score = $result->score; } } }
Bio::Taxonomy::GlobalNames provides Perl objects and functions that interface with the Global Names Resolver web service. Using a REST client, input is sent to the service, whereas results are internally converted from JSON format to nested objects and returned to the user.
This module can be used for automated standardisation of species names, according to a variety of sources that can be manually selected, if needed. See also the example script, provided with this module.
A string with a list of names delimited by new lines. You may optionally supply your local id for each name as:
123|Parus major 125|Parus thruppi 126|Parus carpi
Names in the response will contain your supplied ids, facilitating integration.
The attributes 'data', 'file' and 'names' are mutually exclusive.
A string with a pipe-delimited list of data sources. See the list of data sources.
A file in Unicode encoding with a list of names delimited by new lines, similar to the 'data' attribute. This attribute is valid only when the post method is used.
A string with a list of names delimited by either pipe "|" or tab "\t". Use a pipe with the get method.
A string with a boolean (true/false) value. Default: 'false'. Find the first available match instead of matches across all data sources with all possible renderings of a name.
When 'true', response is rapid but incomplete.
A string with a boolean (true/false) value. Default: 'true'. Reduce the likelihood of matches to taxonomic homonyms.
When 'true', a common taxonomic context is calculated for all supplied names from matches in data sources that have classification tree paths. Names out of determined context are penalized during score calculation.
Performs a GET request and returns an Output object.
Output
Performs a POST request and returns an Output object. If you are supplying an input file, you have to use the 'post' method.
A Context object, if 'with_context' parameter is set to true.
Context
An array reference of Data objects, containing query input(s) and results.
Data
my @data = @{ $output->data };
An array reference of DataSources objects, whose ids you used for name resolution. If no data sources were given, the array reference is empty.
DataSources
my @data_sources = @{ $output->data_sources };
The resolver request id. Your request is stored temporarily in the remote database and is assigned an id.
A Parameters object, containing the parameters of the query.
Parameters
The final status of the request -- 'success' or 'failure'.
The message associated with the status.
The url at which you can access your results for 7 days.
An array reference of Results objects.
Results
my @results = @{ $datum->results };
The id of the name string in the query (if provided).
The name string in the query.
A "canonical" version of the name generated by the Global Names parser.
Tree path to the root if a name string was found within a data source classification.
Tree path to the root using taxon_ids, if a name string was found within a data source classification.
The id of the data source where a name was found.
The title of the data source where a name was found.
An identifier for the found name string used in Global Names.
Shows id local to the data source (if provided by the data source manager).
Explains how resolver found the name. If the resolver cannot find names corresponding to the entire queried name string, it sequentially removes terminal portions of the name string until a match is found.
1 - Exact match
2 - Exact match by canonical form of a name
3 - Fuzzy match by canonical form
4 - Partial exact match by species part of canonical form
5 - Partial fuzzy match by species part of canonical form
6 - Exact match by genus part of a canonical form
The name string found in this data source.
Displays points used to calculate the score delimited by '|' -- "Match points|Author match points|Context points". Negative points decrease the final result.
A confidence score calculated for the match. 0.5 means an uncertain result that will require investigation. Results higher than 0.9 correspond to 'good' matches. Results between 0.5 and 0.9 should be taken with caution. Results less than 0.5 are likely poor matches. The scoring is described in more details at http://resolver.globalnames.org/about.
An identifier supplied in the source Darwin Core Archive for the name string record.
The ID of the data source.
The name of the data source.
An array reference of data source ids you used for name resolution. If no data sources were given, the arrayref is empty.
my @data_sources = @{ $parameters->data_sources };
True if 'resolve_once' parameter is set to true and vice versa.
True if 'with_context' parameter is set to true and vice versa.
A lowest taxonomic level in the data source that contains 90% or more of all names found. If there are too few names to determine, this element remains empty.
The id of a data source used to create the context.
Dimitrios - Georgios Kontopoulos, <d.kontopoulos13 at imperial.ac.uk>
<d.kontopoulos13 at imperial.ac.uk>
Please report any bugs or feature requests to bug-bio-taxonomy-globalnames at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Bio-Taxonomy-GlobalNames.
bug-bio-taxonomy-globalnames at rt.cpan.org
I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
More details about Global Names Resolver's algorithm can be obtained from its website.
You can find documentation for this module with the perldoc command.
perldoc Bio::Taxonomy::GlobalNames
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Bio-Taxonomy-GlobalNames
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Bio-Taxonomy-GlobalNames
CPAN Ratings
http://cpanratings.perl.org/d/Bio-Taxonomy-GlobalNames
Search MetaCPAN
http://search.mcpan.org/dist/Bio-Taxonomy-GlobalNames/
GitHub
https://github.com/dgkontopoulos/Bio-Taxonomy-GlobalNames
Copyright 2013-14 Dimitrios - Georgios Kontopoulos.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Bio::Taxonomy::GlobalNames, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Bio::Taxonomy::GlobalNames
CPAN shell
perl -MCPAN -e shell install Bio::Taxonomy::GlobalNames
For more information on module installation, please visit the detailed CPAN module installation guide.