NAME

Genetics::API::DB::Query


SYNOPSIS

  use Genetics::API ;
  $api = new Genetics::API(DSN => {driver => "mysql",
                                   host => $Host,
                                   database => $Database},
                           user => $UserName,
                           password => $Password) ;
  $sv = $api->getObject({TYPE => "StudyVariable", 
                         NAME => "Aff", 
                         FULL => 1}) ;
  @affSubjects = $api->getSubjectsByPhenotype($sv, 2) ;
  @kindreds = $api->getObjects({TYPE => "Kindred"}) ;
  @d1s = $api->getObjects({TYPE => "Marker", Name => "D1S*"}) ;


DESCRIPTION

The Genetics::API::DB packages provide an interface for the manipulation of Genperl objects in a realtional database. This package contains methods to query for and return objects based on attributes/relationships other than id (for methods to do that, see Genetics::API::DB::Read).


LICENSE

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA


FEEDBACK

Currently, all feedback should be sent directly to the author.


AUTHOR - Steve Mathias

Email: mathias@genomica.com

Phone: (720) 565-4029

Address: Genomica Corporation 1745 38th Street Boulder, CO 80301


DETAILS

The rest of the documentation describes each of the object variables and methods. The names of internal variables and methods are preceded with an underscore (_).


Imported Packages

 strict             Just to be anal
 vars               Global variables
 Carp               Error reporting


Inheritance

 Exporter           Make methods available to importing packages


Public Methods

getObject

  Function  : Get and return Genetics::Object object(s) based on a set of query 
              parameters.. 
  Arguments : A reference to a hash containing the query parameters:
                %query = (
                          ID => integer
                          TYPE => Object type
                          NAME => text
                          WHERE => SQL where clause
                          FULL => Boolean
                         )
              If $query{FULL} is false (the default) mini objects returned.
  Returns   : A Genetics::Object object, or undef there are zero or more than 
              one that satisfy the query parameters.
  Scope     : Public
  Comments  : This is experimental and the interface may change.
              If the NAME parameter contains Perl wildcard characters * or ?, 
              these are converted to the SQL wildcards % and _.  This hopefully 
              results in the expected behavior.

getObjects

  Function  : Get and return Genetics::Object object(s) based on a set of query 
              parameters.. 
  Arguments : A reference to a hash containing the query parameters:
                %query = (
                          TYPE => Object type
                          NAME => text
                          KW => {KeywordType.name => Keyword.value}
                          WHERE => SQL where clause
                          FULL => Boolean
                         )
              If $query{FULL} is false (the default) mini objects returned.
  Returns   : An array of Genetics::Object object(s) which satisfy the query 
              parameters, or undef if there are none.
  Scope     : Public
  Comments  : This is experimental and the interface may change.
              If the NAME parameter contains Perl wildcard characters * or ?, 
              these are converted to the SQL wildcards % and _.  This hopefully 
              results in the expected behavior.

countObjects

  Function  : Return the count of Genetics::Object object(s) that match a set 
              of query parameters.
  Arguments : A reference to a hash containing the query parameters:
                %query = (
                          TYPE => Object type
                          NAME => text
                          WHERE => SQL where clause
                         )
  Returns   : Scalar
  Scope     : Public
  Comments  :

getClusterContents

  Function  : Get the objects referenced by a Cluster.
  Argument  : A Genetics::Cluster object
  Returns   : A list of Genetics::Object objects.
  Scope     : Public
  Comments  :

getClustersByType

 Function  : 
 Arguments : 
 Returns   : 
 Example   : getClustersByType()
 Scope     : 
 Comments  :

getFounders

  Function  : Query for and return the founders (Subjects without parents) in a 
              Kindred.
  Argument  : A Genetics::Kindred object.
  Returns   : A list of Genetics::Subject objects.

  Scope     : Public
  Comments  :

getSubjectsByPhenotype

  Function  : Query for Subjects based on their associated Phenotype values.
  Argument  : A Genetics::Object::StudyVariable object and a phenotype value.
  Returns   : Genetics::Object::Subject objects that have associated Phenotypes 
              with the query value.
  Scope     : Public
  Comments  :

getPhenotypesBySubject

  Function  : Query for Phenotypes based on their associated Subject.
  Argument  : A Genetics::Object::Subject object.
  Returns   : Genetics::Object::Phenotype objects.
  Scope     : Public
  Comments  : Returns only active Phenotypes.

getGenotypesBySubject

  Function  : Query for Genotypes based on their associated Subject.
  Argument  : A Genetics::Object::Subject object.
  Returns   : An array of Genetics::Object::Genotype objects.
  Scope     : Public
  Comments  : Returns only the active Genotypes.

getSubjectsByKindred

  Function  : Query for and return all the Subjects in a Kindred.
  Argument  : A Kindred object
  Returns   : A list of Subject objects
  Scope     : Public
  Comments  :

getSiblings

  Function  : Query for and return all the siblings of a Subject.
  Argument  : A Subject object
  Returns   : A list of Subject objects
  Scope     : Public
  Comments  :

getPOsByChromosome

 Function  : 
 Arguments : 
 Returns   : 
 Example   : getPOsByChromosome()
 Scope     : 
 Comments  : Right now this returns all SequenceObject types.  This works 
             because all SequenceObject types are also PolymorphicObjects.  
             It will have to be modified if new SequenceObject types are 
             introduced that are not also PolymorphicObjects.

getAllelesByType

  Function  : Query for and return a Markers allele names, by type.
  Argument  : A Marker or SNP object and a string containing an allele type.
  Returns   : An array of allele names.
  Scope     : Public
  Comments  : The returned allele names are sorted, first numerically then 
              alphabetically.

getPOAllelesByType

  Function  : Query for and return a Markers alleles by type.
  Argument  : A Marker or SNP object and a string containing an allele type.
  Returns   : An array of allele names.
  Scope     : Public
  Comments  : The returned allele names are sorted, first numerically then 
              alphabetically.

getAlleleCounts

  Function  : Query for and return raw allele counts.
  Argument  : A Marker or SNP object, a string containing an allele type, and 
              a Subject Cluster object.
  Returns   : Hash pointer.  The hash structure is:
                     $count{AlleleName} = $number
  Scope     : Public
  Comments  :

getAlleleFreqs

  Function  : Query for and return the allele frequencies for a group of Subjects.
  Argument  : A Marker object, a string containing an allele type, and one of 
              the following defining the Subject group:
                - a Subject Cluster object 
                - an array reference to a list of Subject objects
                - a Kindred Cluster object 
                - an array reference to a list of Kindred objects
  Returns   : Hash reference to a hash with the following structure:
                $freqs{AlleleName} = $number
  Scope     : Public
  Comments  :

getGtAlleles

  Function  : For a given Subject and Marker, query for and return the allele 
              names from the active Genotype.
  Argument  : A Subject object and a Marker object
  Returns   : An array containing the allele names or undef if there is not an 
              active Genotype associated with the input Subject and Marker.
  Scope     : Public
  Comments  :

getSNPGtCounts

 Function  : 
 Arguments : 
 Returns   : 
 Example   : getSNPGtCounts()
 Scope     : 
 Comments  :

getGtAllelesByGt

  Function  : For a given genotype, query for and return the allele names.
  Argument  : A Genotype object or id.
  Returns   : An array containing the allele names or undef if there is not an 
              active Genotype associated with the input Subject and Marker.
  Scope     : Public
  Comments  :

getPtValue

  Function  : For a given Subject and StudyVariable, query for and return the 
              associated Phenotype value for the active Phenotype.
  Argument  : A Subject object and a StudyVariable object
  Returns   : An scalar containing the Phenotype value or undef if there is not 
              an active Phenotype associated with the input Subject and 
              StudyVariable.
  Scope     : Public
  Comments  :


Private Methods

_generateSQL

  Function  : Generate SQL based on a hash reference of query parameters.
  Arguments : A reference to a hash containing the query parameters:
                %query = (
                          ID => integer
                          TYPE => Object type
                          NAME => text
                          KW => KeywordType.name=Keyword.value
                          WHERE => SQL where clause
                         )
  Returns   : A string containing the SQL.
  Scope     : Private instance method
  Called by : getObject() and getObjects()
  Comments  : If the NAME parameter contains Perl wildcard characters * or ?, 
              these are converted to the SQL wildcards % and _.  This hopefully 
              results in the expected behavior.
              NB. KW can only be used by itself or combined with TYPE