Introduction to CaCOREperl

# Contents

- What is CaCOREperl
- Installing CaCOREperl
- Getting Started
- Object Descriptions
- Search
- Limitations
- More Information

## What is CaCOREperl?

CaCOREperl is a Perl application programming interface to caCORE hosted vocabulary, metadata, and biomedical data. It implements the caCORE object model with object-oriented methodology, and encapsulates webservice invocations and XML parsing so that programmers deal with caCORE objects directly. CaCOREperl is available in Windows, Solaris and other Perl supported operating systems
CaCOREperl requires Perl version 5.6.0 or above.
Current version of CaCOREperl is 3.1.

### Main Features of CaCOREperl:

- search caCORE server, a Java application, hosted vocabulary, metadata, and biomedical data
- manipulate search results in object oriented fashion
- association navigation from object to object

### CaCOREperl contains the following sub-packages:

- CaBIO
- CaMOD (Deprecated)
- CaDSR
- EVS
- Common

### Architecture

The following picture describe the architecture of CaCOREperl and how it is related to the caCORE server.

This picture illustrates the following features of CaCOREperl:

- CaCOREperl itself is not a data store, but a delegate to the caCORE server.
- CaCOREperl encapsulates the gory details of webservice call to the caCORE server, and serializing/deserializing of domain objects.
- Communication with caCORE server is transparent to the user.

## Installing CaCOREperl

Perl comes installed on Unix and Linux platforms. For window based systems, you can download a Perl version from www.activestate.com. CaCOREperl is depened on two Perl modules, XML::DOM and LWP::UserAgent. You must install both XML::DOM and LWP::UserAgent in addition to CaCOREperl.

There are multiple ways to installing Perl modules, the following are three of them.

### Using make

First unzip the CaCORE to a temporary folder. Then open a Command window, cd to the directory that contains this README file and type the following.

  `perl Makefile.PL`
Alternatively, if you plan to install CaCORE somewhere other than your system's perl library directory. You can type something like this:
  `perl Makefile.PL PREFIX=/home/me/perl INSTALLDIRS=perl`
Then to build you run make.
  `make`
You can then test the module by typing:
  `make test`
If you have write access to the perl library directories, you may then install by typing:
  `make install`

### Using Perl Package Manager (PPM)

Perl Package Manager (PPM) is a tool that comes with the ActiveState Perl installation. It can be used to manage your Perl packages. After installing ActiveState Perl, you can start PPM (depends on the version, this can be done through the Start->Programs->ActiveState Perl, or from a command prompt, cd to the \bin, and run ppm). This will bring up a command prompt PPM dialogue. From this dialogue, type in:
  `install XML-DOM`
This will install the XML::DOM module on your PC.

### Using CPAN

This will work on any platform, any Perl version. Run the command:

  `perl -MCPAN -e shell`
Refer to the CPAN documentation for more details on how to use this command.

### Manual installation

This is only recommended if all else failed. You can unzip this distribution, and copy the entire CaCORE folder under the lib folder to the lib/site folder in your Perl installation folder. For example, assume that you unzip this distribution to C:\temp, and your Perl installation is in C:\Perl, you can open a command prompt and type:

  `copy C:\temp\CaCORE\lib\CaCORE C:\Perl\lib\site`

## Getting Started

You can find sample scripts in the examples folder. It contains examples for using CaBIO, EVS, and CaDSR objects. The CaBIO test example (caBIOtest.pl) contains multiple examples that illustrate the multiple search mechanisms implemented in CaCOREperl. If you successfully install CaCOREperl, you can run these example programs directly as a starting point.

## CaCORE Object descriptions

Domain objects, such as gene, are represented as objects in CaCOREperl. All objects in CaCOREperl follows a set of identical patterns:

- A domain object can be created with a constructor method `new`;
- All attributes of the domain object are accessible via getter and setter methods;
- All domain objects that are associated with a domain objects are accessible via getter and setter methods.

Details of each domain object can be obtained in the object description. Here we describe the general pattern that applies to all domain objects. Refer to index.html for description of CaCORE objects.

### Package Name

Each domain object has a fully qualified name in the format of CaCORE::{Package}::{Object}. For example, gene has a fully qualified name of CaCORE::CaBIO::Gene.

### Object Creation

A new instance of the object is created via the `new` method. The following code creates a new gene instance.

  `my $gene = new CaCORE::CaBIO::Gene;`

### Object Attributes

Each object contains a set of attributes. For example, gene has the following attributes:

- clusterId
- fullName
- id
- symbol

To set or retrieve the value of each attribute, there is a setter and a getter method.

- The setter method is defined as `setObject` where Object is the name of the attribute, for example, `$gene->setSymbol`. When calling this method, the value of symbol should be passed in as a parameter. For example: `$gene->setSymbol("NAT2")` sets the $gene instance's symbol attribute to "NAT2";
- The getter method is defined as `getObject` where Object is the name of the attribute, for example, `$gene->getSymbol`. When calling this method, the return value is the value of the attribute. For example, `$gene->getFullName` returns the full name of the $gene.

Since CaCOREperl is mainly a query application, in most cases, setter methods are used to set search criteria. Getter methods are used to obtain the details of an object after searches.

### Object Associations

Each domain object is related to certain objects. For example, gene is directly related to the following objects:

- Chromosome
- DatabaseCrossReference
- ExpressionFeature
- GeneAlias
- GeneOntology
- GeneRelativeLocation
- GenericReporter
- Histopathology
- HomologousAssociation
- Library
- Location
- NucleicAcidSequence
- OrganOntology
- Pathway
- Protein
- Target
- Taxon

The relationship between two objects can be one-to-many or many-to-one. For example, one Gene is related to multiple Pathway objects (one-to-many), and many Genes can be related to one Taxon (many-to-one).

All objects that are associated with the current object can be access via the `getX` (for many-to-one associations) or `getXCollection` (for one-to-many associations) methods. Where "X" is the name of the associated object. Example: `$gene->getTaxon` retrieves the Taxon object associated with the Gene object, since one Taxon object is associated with many Gene objects, and `$gene->getPathwayCollection` retrieves all the Pathway objects associated, with the Gene object. Since one Gene object is associated with many Pathway objects.

The following table is a description of all objects associated with Gene, how they are related, and the methods of retrieving them.

Gene associations
Association Object Name | Relationship | Getter
--- | --- | ---
Chromosome | Many to one | getChromosome
DatabaseCrossReference | One to many | getDatabaseCrossReferenceCollection
ExpressionFeature | One to many | getExpressionFeatureCollection
GeneAlias | One to many | getGeneAliasCollection
GeneOntology | One to many | getGeneOntologyCollection
GeneRelativeLocation | One to many | getGeneRelativeLocationCollection
GenericReporter | One to many | getGenericReporterCollection
Histopathology | One to many | getHistopathologyCollection
HomologousAssociation | One to many | getHomologousAssociationCollection
Library | One to many | getLibraryCollection
Location | One to many | getLocationCollection
NucleicAcidSequence | One to many | getNucleicAcidSequenceCollection
OrganOntology | One to many | getOrganOntologyCollection
Pathway | One to many | getPathwayCollection
Protein | One to many | getProteinCollection
Target | One to many | getTargetCollection
Taxon | Many to one | getTaxon

### Differences between Attributes and Associations

The following applies to all domain object packages, except for EVS objects, which is discussed in the following section. Attributes are generally used for:

- Create search criteria. You can invoke the attribute setter methods to define the information you have in a search;
- Examine the details of search result. Once the search results return (via calling ApplicationService methods or getter methods of associations), you can invoke the attribute getter methods to retrieve detail information of a domain object.

Associations, on the other hand, are generally used for querying purposes. You can not call the setter methods. The getter methods are searching methods. Under the hood, the getter methods invoke the ApplicationService search methods, which will make remote webservice calls to the caCORE server.

Lazy Fetch. caCORE server supports (except for EVS) the so called "lazy fetch" kind of searches. This means that when you query for certain objects, only the attributes of the objects are retrieved and returned. None of the objects associated with the target object(s) are returned. For example, when you call $gene->getPathwayCollection, the caCORE server only retrieves and returns all the pathway objects associated with the $gene object. It will not return any objects that are associated with the pathway objects. To retrieve those objects, you must make subsequent calls.

### EVS Object Associations

EVS objects are a little different than objects of other packages.

- Search entry points are limited to DescLogicConcept and MetaThesaurusConcept. This means that when you invoke the ApplicationService->query and ApplicationService->queryObject methods, you can only pass in the name of these two objects as the target class.
- Searches are "pre-fetch" instead of "lazy fetch". This means that all navigably associated objects, instead of directly related objects, are fetched and returned. For example, if you search for DescLogicConcept object, in addition to the objects that are directly related to the DescLogicConcept objects (including Property, HistoryRecord, EdgeProperties, TreeNode, Role, and Association), objects that are associated with these association objects (including Qualifier, History, and AttributeSetDescriptor), are also retrieved and returned. So when calling the association getter methods of these objects, CaCOREperl returns them from the local memory, instead of making a remote webservice call to the caCORE server.
- Setter methods exist for association objects. You can call these setter methods to create search criteria.

## Limitations

Since CaCOREperl completely depends on caCORE server, all limitations on the caCORE server, most notably the webservice API, are imposed on CaCOREperl as well. The most notable ones being:

- By default, when calling ApplicationService->queryObject, the caCORE server automatically trim the resultset to 1000 objects if the there more than 1000. So in reality, if you want to retrieve anything beyond 1000, you must use ApplicationService->query.
- As of the time of writing, some queries take a long time to execute on the caCORE server. A few of them may cause a webservice timeout (default is 600 seconds).

## More info

See More Resources for additional sources of information.