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.

Introduction

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.

Overview

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.

Important Notes

Accession IDs

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.

Purge the Cache

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.

Inside a Program

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 );

Command line

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

Cache Level

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.

- Cache Level 1 Purge All: Purge all when a map set or species has been added or modified. A change to map sets or species has potential to impact all of the data.
- Cache Level 2 (purge map info on down): Level 2 should be purged when map information is changed.
- Cache Level 3 (purge feature info on down): Level 3 should be purged when feature information is changed.
- Cache Level 4 (purge correspondence info on down): Level 4 should be purged when correspondence information is changed.

CMap Assembly Editor Plug-ins

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.

Importing Data

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, );

Creating a Species

    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,
    );