NAME

Genetics::API::Analysis::Linkage


SYNOPSIS

  # The following code runs a full Genehunter genome scan using two different 
  # disease models:
  use Genetics::API ;
  $api = new Genetics::API(DSN => {driver => "mysql",
                                   host => $Host,
                                   database => $Database},
                           user => $UserName,
                           password => $Password) ;
  # Kindreds
  $kindredCluster = $api->getObject({TYPE => "Cluster", 
                                     NAME => "Bpall two generations"}) ;
  @kindreds = $api->getClusterContents($kindredCluster, 1) ;
  # Allele FrequencySource:
  $bpall = $api->getObject({TYPE => "Cluster", NAME => "Bpall"}) ;
  # StudyVariables:
  $bp = $api->getObject({TYPE => "StudyVariable", NAME => "BP"}) ;
  $bpup = $api->getObject({TYPE => "StudyVariable", NAME => "BPUP"}) ;
  @studyVars = ($bp, $bpup) ;
  $lcd = $api->getObject({TYPE => "StudyVariable", NAME => "AoO Dom LC"}) ;
  @chromosomes = qw(1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 XY) ;
  foreach $chr (@chromosomes) {
    $markerCluster = $api->getObject({TYPE => "Cluster", 
                                      NAME => "Chr$chr Markers"}) ;
    @markers = $api->getClusterContents($markerCluster, 1) ;
    $map = $api->getObject({TYPE => "Map", 
                            NAME => "Marshfield Chr$chr Map"}) ;

    foreach $sv (@studyVars) {
      $svName = $sv->name() ;
      $runName = $chr . $svName ;
      $api->runGenehunter(
                        KINDREDS => \@kindreds, 
                        MARKERS => \@markers, 
                        MAP => $map,
                        ALLELETYPE => "Size", 
                        AFS => $bpall, 
                        TRAIT => $sv, 
                        LC => $lcd,
                        SETUPFILENAME => "$runName.setup", 
                        PHOTOFILENAME => "$runName.out", 
                        DATFILENAME => "$runName.dat", 
                        PEDFILENAME => "$runName.pre", 
                        ANALYSIS => "BOTH", 
                        SINGLEPOINT => "off", 
                        OFFEND => "5.0",
                        INCREMENT => "step 3",
                        MAXBITS => 18,
                       ) ;
    }
  }


DESCRIPTION

This package contains methods relating to the use of data contained in GenPerl objects in genetic linkage analyses. Generally speaking, this means reading and writing linkage format pedigree and locus files, and/or running programs such as genehunter, etc.


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

writeLinkageFiles

  Function  : Write LINKAGE format pedigree and locus files.
  Arguments : A hash of parameters as follows
              KINDREDS => Array pointer to a list of Kindred objects.
                          These define the Subjects being analyzed.
                          Required, for obvious reasons.
              MARKERS => Array pointer to a list of Marker objects.
                         These define the Markers being analyzed.
                         Required, for obvious reasons.
              ALLELETYPE => String containing the allele type of the alleles 
                            to be used.
                            Optional.  Default value is Code.
              AFS => Array pointer to a list of Subject or Kindred objects, or 
                     a single Cluster (Kindred or Subject) object.
                     The source for allele frequencies.
                     Optional.  If not provided, the input Kindreds will be used
              EXTAFS => A FrequencySource object.
                        The source for allele frequencies.
                        Optional.  If not provided, the input Kindreds will be used
              TRAIT => A StudyVariable object.
                       The trait locus being analyzed.  The category of this 
                       StudyVariable must be DynamicAffectionStatus or 
                       StaticAffectionStatus.
                       Optional.
              LC => A StudyVariable object.
                    This StudyVariable defines the liability classes to be used 
                    with the trait locus being analyzed.  The category of this 
                    StudyVariable must be StaticLiabilityClass.
                    Optional.
              QTLS => Array pointer to a list of StudyVariable objects.
                      QTLs to be analyzed.
                      Optional.
              MAP => A Map object.
                     This Map will be used to order the markers.  Also, the distances 
                     will be used.  Right now, every input Marker MUST be on the Map 
                     and there MUST NOT be any markers on the map that are not being 
                     analyzed.
                     Optional.  
              DATFILE => Filehandle reference.
                         The filehandle to which the locus file will be written.
                         Optional.  If not provided, STDOUT will be used.
              PEDFILE => Filehandle reference.
                         The filehandle to which the pedigree file will be 
                         written.
                         Optional.  If not provided, STDOUT will be used.
              MARKERDELIM => Scalar containint the string to be used to 
                             delimit marker names in the locus file.
                             Optional.  If not provided, # is used.
              RENUMBER => Boolean.
                          Optional.  If not provided, alleles are NOT re-
                          numbered.
  Returns   : N/A
  Scope     : Public
  Called by : 
  Comments  : To Do: support for X-linked data
                     support for dynamic trait loci
                     support for dynamic liability classes
                     support for QTLs

runGenehunter

  Function  : Run a Genehunter analysis
  Arguments : A hash of parameters as follows
              KINDREDS => Array pointer to a list of Kindred objects.
                          These define the Subjects being analyzed.
                          Required, for obvious reasons.
              MARKERS => Array pointer to a list of Marker objects.
                         These define the Markers being analyzed.
                         Required, for obvious reasons.
              AFS => Array pointer to a list of Subject or Kindred objects, or 
                     a single Cluster (Kindred or Subject) object.
                     The source for allele frequencies.
                     Optional.  If not provided, the input Kindreds will be used
              EXTAFS => A FrequencySource object.
                        The source for allele frequencies.
                        Optional.  If not provided, the input Kindreds will be used
              TRAIT => A StudyVariable object.
                       The trait locus being analyzed.  The category of this 
                       StudyVariable must be AffectionStatus or StaticAffectionStatus.
                       Optional.
              LC => A StudyVariable object.
                    This StudyVariable defines the liability classes to be used 
                    with the trait locus being analyzed.  The category of this 
                    StudyVariable must be StaticLiabilityClass.
                    Optional.
              DATFILENAME => A name to be used for the locus file.
                             Required.
              PEDFILENAME => A name to be used for the pedigree file.
                             Required.
              PHOTOFILENAME => A name to be used for the photo file.
                               Optional.
              FILESONLY => Boolean.  If true, only write files.
                           Optional, defaults to false.
  Returns   : N/A
  Scope     : Public
  Comments  :

writeKEMFiles

  Function  : Write "LINKAGE format" pedigree and locus files for use by KEM.
  Arguments : A hash of parameters as follows
              SUBJECTS => Array pointer to a list of Kindred objects.
                          These define the Subjects being analyzed.
                          Required, for obvious reasons.
              MARKERS => Array pointer to a list of Marker objects.
                         These define the Markers being analyzed.
                         Required, for obvious reasons.
              DISTANCES => Array pointer to a list of distances bewtween the 
                           Markers.
              ALLELETYPE => String containing the allele type of the alleles 
                            to be used.
                            Optional.  Default value is Code.
              DATFILE => Filehandle reference.
                         The filehandle to which the locus file will be written.
                         Optional.  If not provided, STDOUT will be used.
              PEDFILE => Filehandle reference.
                         The filehandle to which the pedigree file will be 
                         written.
                         Optional.  If not provided, STDOUT will be used.
  Returns   : A hash, keyed on marker names that maps the codes (used in the 
              output files) to the allele names of the markers.  The hash has 
              the following structure:
                 markerNames => code2alleleName hash references
  Scope     : Public
  Called by : 
  Comments  : Alleles have to be re-numbered for KEM.
              Markers and distances are used in their input order.

processKemResults

 Function  : Process K-EM output, as descibed below.
 Arguments : A file handle reference to a K-EM output file, an array reference 
             to the list of markers used in the analysis, and a hash reference 
             to the hash mapping allele codes to names (as returned by 
             writeKEMFiles()).
 Returns   : An array.  the first element is a scalar containing the best log 
             liklihood of the K-EM run.  The rest of the elements are hash 
             pointers containing processed results.  The structure of the 
             referenced hashes is:
               $htResult{name} = Ht number
               $htResult{freq} = float
               $htResult{ht}   = array reference to a list of allele names
 Example   : @kemResults = processKemResults(\@snps, \%poNameCode2Allele) ;
 Scope     : Public Class Method
 Comments  : Converts codes in K-EM output file back into allele names

printProcessedKemResults

 Function  : 
 Arguments : 
 Returns   : 
 Example   : printProcessedKemResults(%kemResults)
 Scope     : Public Class Method
 Comments  :

htmlizeKemResults

 Function  : Format processed K-EM results as HTML
 Arguments : An array of hash references as returned by processKemResults()
 Returns   : Scalar text string containing HTML
 Example   : $html = htmlizeKemResults(@processedKemResults)
 Scope     : Public Class Method
 Comments  :

orderMarkersWithMap

 Function  : Order markers and generate distances based on a Map object.
 Arguments : An array reference to a list of input Markers/SNPs, a Map, and two 
             array reference to be populated with the ordered markers and 
             distances, respecitvely.
 Returns   : N/A
 Example   : $api->orderMarkersWithMap(\@snps, undef, \@orderedSnps, \@distances) ;
 Scope     : Public Instance Method
 Comments  : This is used inconjunction with runKEM().
             This is basically a stub method right now.  It populates to 
             ordered list with a copy of the input list and populates the 
             distance list with 0.1s.


Private Methods

_renumberAlleles

  Function  : Renumber alleles into consecutive integers
  Arguments : A Marker or SNP object and a string containing an allele type.
  Returns   : A reference to a hash with the following structure:
                %hash = (alleleName => code)
  Scope     : Private instance method
  Called by : writeLinkageFiles().
  Comments  :

_reverseRenum

 Function  : See below
 Arguments : A hash of with the following structure:
                 markerNames => alleleName2code hash references
 Returns   : A hash of with the following structure:
                 markerNames => code2alleleName hash references
 Example   : %poName_c2a = _reverseRenum(%poName_a2c)
 Scope     : Private Class Method
 Comments  : This is needed because the linkage file writing routines 
             need to keep track of allele->code mapping, but they need 
             to return code->allele mappings.

_validateTraitInput

  Function  : Verify that a StudyVariable may be used as a trait locus.
  Arguments : A StudyVariable object and two pointers to flag variables used 
              in writeLinkageFiles().
  Returns   : N/A
  Scope     : Private class method
  Called by : writeLinkageFiles()
  Comments  : The fisrt flag pointer is to the trait flag; it is set to 1 if 
              the input StudyVariable may be used for static liability class 
              definition and assignments.  The second flag pointer is to 
              the liability class flag.  It is set to 2 if the input 
              StudyVariable may be used for dynamic liability class definition 
              and assignments.

_validateLCInput

  Function  : Verify that a StudyVariable may be used for static liability 
              class definition and assignments.
  Arguments : A StudyVariable object a pointer to a flag variable used 
              in writeLinkageFiles().
  Returns   : 
  Scope     : Private class method
  Called by : writeLinkageFiles()
  Comments  : The flag pointer is to the the liability class flag.  It is set 
              to 1 if the input StudyVariable may be used for static liability 
              class definition and assignments.

_validateQTLInput

  Function  : Verify that StudyVariable(s) may be used as QTL varibales in a 
              linkage analysis.
  Arguments : N/A
  Returns   : N/A
  Scope     : Private class method
  Called by : writeLinkageFiles()
  Comments  : Not implemented.

_processMarkersAndMap

  Function  : Order markers and generate distances for linkage analysis.
  Arguments : An array reference to a list of input Markers/SNPs, a Map 
  Returns   : N/A
  Scope     : Private class method
  Called by : writeLinkageFiles()
  Comments  : There does not have to be a Map object.  If there is not the 
              marker order used is that of the input list and all distances are 
              set to 0.1.  If there are input Markers/SNPs that are not on the 
              Map, they are included in the analysis after the ordered 
              Markers/SNPs with all distances are set to 0.1.
              NB. This does not yet deal with the following:
                - markers on the map that are not in the input set
                - global map order (it may never do this)
                - map distance units other than Theta or cM (it may never do this)