Provided by: libtfbs-perl_0.6.0+dfsg-1_amd64 bug

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 <Boris.Lenhard@cgb.ki.se> Modified by Eivind Valen eivind.valen@gmail.com

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 hierachical 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    1 to clean up temporary files, 0 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    1 to clean up temporary files, 0 otherwise
                   -align      Alignment method