TFBS::MatrixSet(3pm)

NAME

TFBS::Matrix::Set - an agregate class representing a set of matrix patterns, containing methods for manipulating the set as a whole

SYNOPSIS

    # creation of a TFBS::MatrixSet object
    # let @list_of_matrix_objects be a list of TFBS::Matrix::* objects
    ###################################
    # Create a TFBS::MatrixSet object:
    my $matrixset = TFBS::MatrixSet->new(); # creates an empty set
    $matrixset->add_Matrix(@list_of_matrix_objects); #add matrix objects to set
    $matrixset->add_Matrix($matrixobj); # adds a single matrix object to set
    # or, same as above:
    my $matrixset = TFBS::MatrixSet->new(@list_of_matrix_objects, $matrixobj);
    ###################################
    #

DESCRIPTION

TFBS::MatrixSet is an aggregate class storing a set of TFBS::Matrix::* subclass objects, and providing methods form manipulating those sets as a whole. TFBS::MatrixSet objects are created <I>de novo<I> or returned by some database (TFBS::DB::*) retrieval methods.

FEEDBACK

Please send bug reports and other comments to the author.

AUTHOR - Boris Lenhard

Boris Lenhard <[email protected]> Modified by Eivind Valen [email protected]

APPENDIX

The rest of the documentation details each of the object methods. Internal methods are preceded with an underscore.

new

new2

add_matrix

 Title   : add_matrix
 Usage   : $matrixset->add_matrix(@list_of_matrix_objects);
 Function: Adds matrix objects to matrixset
 Returns : object reference (usually ignored)
 Args    : one or more TFBS::Matrix::* objects

add_matrix_set

 Title   : add_matrix
 Usage   : $matrixset->add_matrix(@list_of_matrixset_objects);
 Function: Adds to the matrixset matrix objects contained in one or
           more other matrixsets
 Returns : object reference (usually ignored)
 Args    : one or more TFBS::MatrixSet objects

search_seq

 Title   : search_seq
 Usage   : my $siteset = $matrixset->search_seq(%args)
 Function: scans a nucleotide sequence with all patterns represented
           stored in $matrixset;
           It works only if all matrix objects in $matrixset understand
           search_seq method (currently only TFBS::Matrix::PWM objects do)
 Returns : a TFBS::SiteSet object
 Args    : # you must specify either one of the following three:
           -file,       # the name od a fasta file (single sequence)
              #or
           -seqobj      # a Bio::Seq object
                        # (more accurately, a Bio::PrimarySeqobject or a
                        #  subclass thereof)
              #or
           -seqstring # a string containing the sequence
           -threshold,  # minimum score for the hit, either absolute
                        # (e.g. 11.2) or relative (e.g. "75%")
                        # OPTIONAL: default "80%"

search_aln

 Title   : search_aln
 Usage   : my $site_pair_set = $matrixset->search_aln(%args)
 Function: Scans a pairwise alignment of nucleotide sequences
           with the pattern represented by the PWM: it reports only
           those hits that are present in equivalent positions of both
           sequences and exceed a specified threshold score in both, AND
           are found in regions of the alignment above the specified
           conservation cutoff value.
           It works only if all matrix object in $matrixset understand
           search_aln method (currently only TFBS::Matrix::PWM objects do)
 Returns : a TFBS::SitePairSet object
 Args    : # you must specify either one of the following three:
           -file,       # the name of the alignment file in Clustal
                               format
              #or
           -alignobj      # a Bio::SimpleAlign object
                        # (more accurately, a Bio::PrimarySeqobject or a
                        #  subclass thereof)
              #or
           -alignstring # a multi-line string containing the alignment
                        # in clustal format
           #############
           -threshold,  # minimum score for the hit, either absolute
                        # (e.g. 11.2) or relative (e.g. "75%")
                        # OPTIONAL: default "80%"
           -window,     # size of the sliding window (inn nucleotides)
                        # for calculating local conservation in the
                        # alignment
                        # OPTIONAL: default 50
           -cutoff      # conservation cutoff (%) for including the
                        # region in the results of the pattern search
                        # OPTIONAL: default "70%"
           -subpart     # subpart of the alignment to search, given as e.g.
                        # -subpart => { relative_to => 1,
                        #               start       => 140,
                        #               end         => 180 }
                        # where start and end are coordinates in the
                        # sequence indicated by relative_to (1 for the
                        # 1st sequence in the alignment, 2 for the 2nd)
                        # OPTIONAL: by default searches entire alignment
           -conservation
                        # conservation profile, a TFBS::ConservationProfile
                        # OPTIONAL: by default the conservation profile is
                        # computed internally on the fly (less efficient)

size

 Title   : size
 Usage   : my $number_of_matrices = $matrixset->size;
 Function: gets the number of matrix objects in the $matrixset
           (i.e. the size of the set)
 Returns : a number
 Args    : none

Iterator

 Title   : Iterator
 Usage   : my $matrixset_iterator =
                   $matrixset->Iterator(-sort_by =>'total_ic');
           while (my $matrix_object = $matrix_iterator->next) {
               # do whatever you want with individual matrix objects
           }
 Function: Returns an iterator object that can be used to go through
           all members of the set
 Returns : an iterator object (currently undocumentened in TFBS -
                               but understands the 'next' method)
 Args    : -sort_by # optional - currently it accepts
                    #    'ID' (alphabetically)
                    #    'name' (alphabetically)
                    #    'class' (alphabetically)
                    #    'total_ic' (numerically, decreasing order)
           -reverse # optional - reverses the default sorting order if true

randomize_columns

 Title   : randomize_columns
 Usage   : $matrixset->randomize_columns();
 Function: Randomizes the columns between all the matrices in the set (in place).
 Returns : nothing
 Args    : none

remove_Matrix_by_ID

 Title   : remove_Matrix_by_ID
 Usage   : $matrixset->remove_Matrix_by_ID($id);
 Function: Removes a matrix from the set
 Returns : Nothing
 Args    : None

cluster

 Title   : cluster
 Usage   : $matrixset->cluster(%args)
 Function: Clusters the matrices in the set
 Returns : The root node of the hierarchical clustering tree. 
           An integer specifying the optimal number of clusters.
           An array of TFBS::MatrixSets, one for each cluster.
 Args    : Many:
            -stampdir   Directory where stamp is located. Not necessary if it is in the PATH.
            -tempdir    Directory to put temporary files. Defaults to "/tmp"
            -noclean    0 to clean up temporary files, 1 otherwise
            -tree       Method for constructing tree (UPGMA/SOTA). Def:UPGMA

fbp

 Title   : fbp 
 Usage   : $matrixset->fbp(%args);
 Function: Creates a familial binding profile (FBP) for the set
 Returns : A familial binding profile represented as a TFBS::Matrix::PFM
 Args    : Many
            -stampdir   Directory where stamp is located. Not necessary if it is in the PATH.
            -tempdir    Directory to put temporary files. Defaults to "/tmp"
            -noclean    0 to clean up temporary files, 1 otherwise
            -align      Alignment method