CMap Application Programming Interface
$Revision: 1.2 $
This document was written for the upcoming CMap 1.0 release. It corresponds to code that is in CVS at the time off commit. It may not be applicable to older versions.
This document is intended to help you interface with the CMap database using the CMap API. As CMap is written in Perl, that is the language used to interface with it.
There are two types of interaction between your program and the CMap database; Importing Data and Querying the CMap Database. Each type of interaction is performed in its own way.
Importing data requires the use of a Bio::GMOD::CMap::Admin object. Creating this will be descibed in the Importing Data section.
Querying the CMap database is done through the use of an object returned by the
sql()
method, which any CMap module has access to.
All the accession id columns in the CMap tables act the same. They are all character fields, so they will accept any combination of numbers and letters you care to use. Please don't use spaces or characters outside the ranges ``a-z,'' ``A-Z,'' ``0-9'' or dashes (``-'') as this will likely only cause you headaches. It is also not necessary to explicitly assign any accession IDs. While they *are* required by the database, there is code in place to ensure that the accession ID is set to the primary ID of the record if the accession ID is empty. Once your accession IDs have been established and publicized, they should never change.
Also, it is best to avoid strictly numeric accession ids since the automatic accessions are numeric and this can cause conflicts.
After changing information in the database (or a config file), the query cache needs to be purged. Not doing so, often results in a mix of old and new information being displayed, which can be confusing.
You can purge the cache inside a script or use the command line.
Purging inside your program is simple. Use a Bio::GMOD::CMap::Admin object (see Importing Data for creating this object) to call the purge_cache method.
$admin->purge_cache( );
A cache level can be specified. See the section below on cache levels for more information.
$admin->purge_cache( $cache_level );
To purge the cache on the command line use cmap/bin/cmap_admin.pl. You can either use the menu system or by command line:
$ cmap_admin.pl [-d data_source] [--cache_level level] --action purge_query_cache
There are four layers of the cache. This is to keep data from being unnecessarily purged. For instance when a correpspondence is added, no map data is changed, so only the correspondence information should be purged.
When one layer is purged all of the layers below it are purged.
It is important to note that if you are writing a plug-in for CMAE, the methods described in this section will only work if the data is stored locally. If the data access is remote, you must use the methods in AppData.pm. There will be further documentation written on this topic.
To create data in the CMap database, a CMap admin object needs to be created. In the following example, $data_source stores the data source name that identifies which configuration file to use.
use Bio::GMOD::CMap::Admin;
my $data_source = 'CMAP_DEMO'; my $cmap_admin = Bio::GMOD::CMap::Admin->new( data_source => $data_source, );
my $species_id = $admin->species_create( species_full_name => $species_full_name, species_common_name => $species_common_name, display_order => $display_order, species_acc => $species_acc, );
my $map_set_id = $admin->map_set_create( map_set_name => $map_set_name, map_set_acc => $map_set_acc, map_type_acc => $map_type_acc, width => $width, is_relational_map => $is_relational_map, published_on => $published_on, map_set_short_name => $map_set_short_name, display_order => $display_order, species_id => $species_id, color => $color, shape => $shape, );
my $map_id = $admin->map_create( map_name => $map_name, map_set_id => $map_set_id, map_acc => $map_acc, map_start => $map_start, map_stop => $map_stop, display_order => $display_order, );
my $feature_id = $admin->feature_create( map_id => $map_id, feature_name => $feature_name, feature_acc => $feature_acc, feature_start => $feature_start, feature_stop => $feature_stop, is_landmark => $is_landmark, feature_type_acc => $feature_type_acc, direction => $direction, #gclass => $gclass, # not likely to be used );
my $feature_correspondence_id = $admin->feature_correspondence_create( feature_id1 => $feature_id1, feature_id2 => $feature_id2, feature_acc1 => $feature_acc1, feature_acc2 => $feature_acc2, is_enabled => $is_enabled, evidence_type_acc => $evidence_type_acc, # Alt: correspondence_evidence score => $score, # used in conjunction with evidence_type_acc feature_correspondence_acc => $feature_correspondence_acc, );
In an effort so speed up import of correspondences, correspondences can be queued. When the number in the queue breaks a threshold, those correspondences are then added into the database. Supplying a ``threshold'' value to this method will enable that feature. From experience, a good threshold is between 100 and 1000 but feel free to play around with it.
To finish creating the correspondences in the queue, simply run the method again with no arguments.
$admin->feature_correspondence_create();
my $evidences = [ { evidence_type_acc => $evidence_type_acc, score => $score, }, ];
$admin->attribute_create( object_id => $object_id, attribute_name => $attribute_name, attribute_value => $attribute_value, object_type => $object_type, display_order => $display_order, is_public => $is_public, );
See also $admin->set_attribute()
for a slightly faster (but more complicated)
version.
$admin->xref_create( object_id => $object_id, xref_name => $xref_name, xref_url => $xref_url, object_type => $object_type, display_order => $display_order, is_public => $is_public, );
See also $admin->set_xref()
for a slightly faster (but more complicated)
version.
$admin->map_to_feature_create( feature_id => $feature_id, feature_acc => $feature_acc, map_id => $map_id, map_acc => $map_acc, );
To query the data, another object is needed which we will call the $sql_object. The $sql_object can be created from any CMap object. For the following examble, we'll use the $cmap_admin object from the Importing Data section.
my $sql_object = $cmap_admin->sql();
When you have the $sql_object, you can then call any of the methods in Bio/GMOD/CMap/Data/Generic.pm.
my $species = $sql_object->get_species();
The parameters narrow down search results or provide direction for the results.
If no parameters are provided, it will return all species in the database.
[ { species_id => $species_id, species_acc => $species_acc, species_common_name => $species_common_name, species_full_name => $species_full_name, display_order => $display_order, }, ]
my $map_sets = $sql_object->get_map_sets();
The parameters narrow down search results or provide direction for the results.
If no parameters are provided, it will return all map sets in the database.
[ { map_set_id => $map_set_id, map_set_acc => $map_set_acc, map_set_name => $map_set_name, map_set_short_name => $map_set_short_name, map_type_acc => $map_type_acc, published_on => $published_on, is_enabled => $is_enabled, is_relational_map => $is_relational_map, map_units => $map_units, map_set_display_order => $map_set_display_order, shape => $shape, color => $color, width => $width, species_id => $species_id, species_acc => $species_acc, species_common_name => $species_common_name, species_full_name => $species_full_name, species_display_order => $species_display_order, map_type => $map_type, map_type_display_order => $map_type_display_order, epoch_published_on => $epoch_published_on, map_count => $map_count, # (Only if count_maps is specified) }, ]
The get_map_sets_simple by executing ``perldoc Bio::GMOD::CMap::Data::Generic'';
my $maps = $sql_object->get_maps();
The parameters narrow down search results or provide direction for the results.
If no parameters are provided, it will return all maps in the database.
[ { map_id => $map_id, map_acc => $map_acc, map_name => $map_name, map_start => $map_start, map_stop => $map_stop, display_order => $display_order, map_set_id => $map_set_id, map_set_acc => $map_set_acc, map_set_name => $map_set_name, map_set_short_name => $map_set_short_name, published_on => $published_on, shape => $shape, width => $width, color => $color, map_type_acc => $map_type_acc, map_units => $map_units, is_relational_map => $is_relational_map, species_id => $species_id, species_acc => $species_acc, species_common_name => $species_common_name, species_full_name => $species_full_name, map_type_display_order => $map_type_display_order, map_type => $map_type, epoch_published_on => $epoch_published_on, default_shape => $default_shape, default_color => $default_color, default_width => $default_width, feature_count => $feature_count, # (Only if count_features is specified) }, ]
The get_maps_simple by executing ``perldoc Bio::GMOD::CMap::Data::Generic'';
my $features = $sql_object->get_features();
The parameters narrow down search results or provide direction for the results.
Identifiers that are more specific are used instead of more general ids. For instance, if a feature_id and a map_id are specified, only the feature_id will be used because the map_id is a more broad search.
If no parameters are provided, it will return all features in the database.
[ { feature_id => $feature_id, feature_acc => $feature_acc, feature_type_acc => $feature_type_acc, feature_type => $feature_type, feature_name => $feature_name, feature_start => $feature_start, feature_stop => $feature_stop, direction => $direction, map_id => $map_id, is_landmark => $is_landmark, map_acc => $map_acc, map_name => $map_name, map_start => $map_start, map_stop => $map_stop, map_set_id => $map_set_id, map_set_acc => $map_set_acc, map_set_name => $map_set_name, map_set_short_name => $map_set_short_name, is_relational_map => $is_relational_map, map_type_acc => $map_type_acc, map_type => $map_type, map_units => $map_units, species_id => $species_id, species_acc => $species_acc, species_common_name => $species_common_name, feature_type => $feature_type, default_rank => $default_rank, aliases => $aliases, # a list of aliases (Unless $aliases_get_rows #or $ignore_aliases are specified), }, ]
The get_features_simple by executing ``perldoc Bio::GMOD::CMap::Data::Generic'';
my $correspondences = $sql_object->get_feature_correspondence_details()
The parameters narrow down search results or provide direction for the results.
Note: If not supplying evidence type information, the disregard_evidence_type parameter must be set to true, otherwise, no data will be returned.
[ { feature_name2 => $feature_name2, feature_id2 => $feature_id2, feature_id2 => $feature_id2, feature_acc1 => $feature_acc1, feature_acc2 => $feature_acc2, feature_start2 => $feature_start2, feature_stop2 => $feature_stop2, feature_type_acc2 => $feature_type_acc2, map_id2 => $map_id2, map_acc2 => $map_acc2, map_name2 => $map_name2, map_display_order2 => $map_display_order2, map_set_id2 => $map_set_id2, map_set_acc2 => $map_set_acc2, map_set_short_name2 => $map_set_short_name2, ms_display_order2 => $ms_display_order2, published_on2 => $published_on2, map_type_acc2 => $map_type_acc2, map_units2 => $map_units2, species_common_name2 => $species_common_name2, species_display_order2 => $species_display_order2, feature_correspondence_id => $feature_correspondence_id, feature_correspondence_acc => $feature_correspondence_acc, is_enabled => $is_enabled, evidence_type_acc => $evidence_type_acc, map_type2 => $map_type2, feature_type2 => $feature_type2, evidence_type => $evidence_type, }, ]
The get_feature_correspondences_simple by executing ``perldoc Bio::GMOD::CMap::Data::Generic'';
my $attributes = $sql_object->get_attributes();
The parameters narrow down search results or provide direction for the results.
If no parameters are provided, it will return all features in the database.
[ { attribute_id => $attribute_id, object_id => $object_id, table_name => $table_name, display_order => $display_order, is_public => $is_public, attribute_name => $attribute_name, attribute_value => $attribute_value, object_type => $object_type, }, ]
my $xrefs = $sql_object->get_xrefs();
The parameters narrow down search results or provide direction for the results.
If no parameters are provided, it will return all features in the database.
[ { xref_id => $xref_id, object_id => $object_id, display_order => $display_order, xref_name => $xref_name, xref_url => $xref_url, object_type => $object_type, }, ]
my $map_to_features = $sql_object->get_map_to_features()
The parameters narrow down search results or provide direction for the results.
If no parameters are provided, it will return all features in the database.
[ { map_id => $map_id, map_acc => $map_acc, feature_id => $feature_id, feature_acc => $feature_acc, }, ]
For more information about the methods available, execute ``perldoc Bio::GMOD::CMap::Data::Generic'' on the command line.
Contact the CMap list, gmod-cmap@lists.sourceforge.net with your questions or comments.
You can also leave a bug report for CMap at the SourceForge site for GMOD, http://sourceforge.net/projects/gmod/.
Ben Faga, faga@cshl.edu
Copyright (c) 2007 Cold Spring Harbor Laboratory