Linkage.pm

- NAME
- SYNOPSIS
- DESCRIPTION
- LICENSE
- FEEDBACK
- AUTHOR - Steve Mathias
- DETAILS
- Imported Packages
- Inheritance
- Public Methods

- writeLinkageFiles
- runGenehunter
- writeKEMFiles
- processKemResults
- printProcessedKemResults
- htmlizeKemResults
- orderMarkersWithMap

- Private Methods

- _renumberAlleles
- _reverseRenum
- _validateTraitInput
- _validateLCInput
- _validateQTLInput
- _processMarkersAndMap

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