Provided by: libbio-perl-perl_1.7.2-3_all bug

NAME

       Bio::Tools::Lucy - Object for analyzing the output from Lucy,
         a vector and quality trimming program from TIGR

SYNOPSIS

         # Create the Lucy object from an existing Lucy output file
         @params = ('seqfile' => 'lucy.seq', 'lucy_verbose' => 1);
         $lucyObj = Bio::Tools::Lucy->new(@params);

         # Get names of all sequences
         $names = $lucyObj->get_sequence_names();

         #  Print seq and qual values for sequences >400 bp in order to run CAP3
         foreach $name (@$names) {
             next unless $lucyObj->length_clear($name) > 400;
             print SEQ ">$name\n", $lucyObj->sequence($name), "\n";
             print QUAL ">$name\n", $lucyObj->quality($name), "\n";
         }

         # Get an array of Bio::PrimarySeq objects
         @seqObjs = $lucyObj->get_Seq_Objs();

DESCRIPTION

       Bio::Tools::Lucy.pm provides methods for analyzing the sequence and quality values
       generated by Lucy program from TIGR.

       Lucy will identify vector, poly-A/T tails, and poor quality regions in a sequence.
       (www.genomics.purdue.edu/gcg/other/lucy.pdf)

       The input to Lucy can be the Phred sequence and quality files generated from running Phred
       on a set of chromatograms.

       Lucy can be obtained (free of charge to academic users) from www.tigr.org/softlab

       There are a few methods that will only be available if you make some minor changes to the
       source for Lucy and then recompile.  The changes are in the 'lucy.c' file and there is a
       diff between the original and the modified file in the Appendix

       Please contact the author of this module if you have any problems making these
       modifications.

       You do not have to make these modifications to use this module.

   Creating a Lucy object
         @params = ('seqfile' => 'lucy.seq', 'adv_stderr' => 1,
                    'fwd_desig' => '_F', 'rev_desig' => '_R');
         $lucyObj = Bio::Tools::Lucy->new(@params);

   Using a Lucy object
         You should get an array with the sequence names in order to use
         accessor methods.  Note: The Lucy binary program will fail unless
         the sequence names provided as input are unique.

         $names_ref = $lucyObj->get_sequence_names();

         This code snippet will produce a Fasta format file with sequence
         lengths and %GC in the description line.

         foreach $name (@$names) {
             print FILE ">$name\t",
                        $lucyObj->length_clear($name), "\t",
                        $lucyObj->per_GC($name), "\n",
                        $lucyObj->sequence($name), "\n";
         }

         Print seq and qual values for sequences >400 bp in order to assemble
         them with CAP3 (or other assembler).

         foreach $name (@$names) {
             next unless $lucyObj->length_clear($name) > 400;
             print SEQ ">$name\n", $lucyObj->sequence($name), "\n";
             print QUAL ">$name\n", $lucyObj->quality($name), "\n";
         }

         Get all the sequences as Bio::PrimarySeq objects (eg., for use with
         Bio::Tools::Run::StandaloneBlast to perform BLAST).

         @seqObjs = $lucyObj->get_Seq_Objs();

         Or use only those sequences that are full length and have a Poly-A
         tail.

         foreach $name (@$names) {
             next unless ($lucyObj->full_length($name) and $lucy->polyA($name));
             push @seqObjs, $lucyObj->get_Seq_Obj($name);
         }

         Get the names of those sequences that were rejected by Lucy.

         $rejects_ref = $lucyObj->get_rejects();

         Print the names of the rejects and 1 letter code for reason they
         were rejected.

         foreach $key (sort keys %$rejects_ref) {
             print "$key:  ", $rejects_ref->{$key};
         }

         There is a lot of other information available about the sequences
         analyzed by Lucy (see APPENDIX).  This module can be used with the
         DBI module to store this sequence information in a database.

FEEDBACK

   Mailing Lists
       User feedback is an integral part of the evolution of this and other Bioperl modules.
       Send your comments and suggestions preferably to one of the Bioperl mailing lists.  Your
       participation is much appreciated.

         bioperl-l@bioperl.org                  - General discussion
         http://bioperl.org/wiki/Mailing_lists  - About the mailing lists

   Support
       Please direct usage questions or support issues to the mailing list:

       bioperl-l@bioperl.org

       rather than to the module maintainer directly. Many experienced and reponsive experts will
       be able look at the problem and quickly address it. Please include a thorough description
       of the problem with code and data examples if at all possible.

   Reporting Bugs
       Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their
       resolution. Bug reports can be submitted via the web:

         https://github.com/bioperl/bioperl-live/issues

AUTHOR

       Andrew G. Walsh          paeruginosa@hotmail.com

APPENDIX

       Methods available to Lucy objects are described below.  Please note that any method
       beginning with an underscore is considered internal and should not be called directly.

   new
        Title   :  new
        Usage   :  $lucyObj = Bio::Tools::Lucy->new(seqfile => lucy.seq, rev_desig => '_R',
                   fwd_desig => '_F')
        Function:  creates a Lucy object from Lucy analysis files
        Returns :  reference to Bio::Tools::Lucy object
        Args    :  seqfile     Fasta sequence file generated by Lucy
                      qualfile Quality values file generated by Lucy
                      infofile Info file created when Lucy is run with -debug
                            'infofile' option
                      stderrfile       Standard error captured from Lucy when Lucy is run
                                with -info option and STDERR is directed to stderrfile
                                (ie. lucy ... 2> stderrfile).
                                Info in this file will include sequences dropped for low
                                quality. If you've modified Lucy source (see adv_stderr below),
                                it will also include info on which sequences were dropped because
                                they were vector, too short, had no insert, and whether a poly-A
                                tail was found (if Lucy was run with -cdna option).
                      lucy_verbose verbosity level (0-1).
                      fwd_desig        The string used to determine whether sequence is a
                 forward read.
                                The parser will assume that this match will occus at the
                                end of the sequence name string.
                      rev_desig        As above, for reverse reads.
                      adv_stderr       Can be set to a true value (1).  Will only work if
                 you have modified
                                the Lucy source code as outlined in DESCRIPTION and capture
                                the standard error from Lucy.

       If you don't provide filenames for qualfile, infofile or stderrfile, the module will
       assume that .qual, .info, and .stderr are the file extensions and search in the same
       directory as the .seq file for these files.

       For example, if you create a Lucy object with $lucyObj = Bio::Tools::Lucy->new(seqfile
       =>lucy.seq), the module will find lucy.qual, lucy.info and lucy.stderr.

       You can omit any or all of the quality, info or stderr files, but you will not be able to
       use all of the object methods (see method documentation below).

   _parse
        Title   :  _parse
        Usage   :  n/a (internal function)
        Function:  called by new() to parse Lucy output files
        Returns :  nothing
        Args    :  none

   get_Seq_Objs
        Title   :  get_Seq_Objs
        Usage   :  $lucyObj->get_Seq_Objs()
        Function:  returns an array of references to Bio::PrimarySeq objects
                   where -id = 'sequence name' and -seq = 'sequence'

        Returns :  array of Bio::PrimarySeq objects
        Args    :  none

   get_Seq_Obj
        Title   :  get_Seq_Obj
        Usage   :  $lucyObj->get_Seq_Obj($seqname)
        Function:  returns reference to a Bio::PrimarySeq object where -id = 'sequence name'
                   and -seq = 'sequence'
        Returns :  reference to Bio::PrimarySeq object
        Args    :  name of a sequence

   get_sequence_names
        Title   :  get_sequence_names
        Usage   :  $lucyObj->get_sequence_names
        Function:  returns reference to an array of names of the sequences analyzed by Lucy.
                   These names are required for most of the accessor methods.
                   Note: The Lucy binary will fail unless sequence names are unique.
        Returns :  array reference
        Args    :  none

   sequence
        Title   :  sequence
        Usage   :  $lucyObj->sequence($seqname)
        Function:  returns the DNA sequence of one of the sequences analyzed by Lucy.
        Returns :  string
        Args    :  name of a sequence

   quality
        Title   :  quality
        Usage   :  $lucyObj->quality($seqname)
        Function:  returns the quality values of one of the sequences analyzed by Lucy.
                   This method depends on the user having provided a quality file.
        Returns :  string
        Args    :  name of a sequence

   avg_quality
        Title   :  avg_quality
        Usage   :  $lucyObj->avg_quality($seqname)
        Function:  returns the average quality value for one of the sequences analyzed by Lucy.
        Returns :  float
        Args    :  name of a sequence

   direction
        Title   :  direction
        Usage   :  $lucyObj->direction($seqname)
        Function:  returns the direction for one of the sequences analyzed by Lucy
                   providing that 'fwd_desig' or 'rev_desig' were set when the
                   Lucy object was created.
                   Strings returned are: 'F' for forward, 'R' for reverse.
        Returns :  string
        Args    :  name of a sequence

   length_raw
        Title   :  length_raw
        Usage   :  $lucyObj->length_raw($seqname)
        Function:  returns the length of a DNA sequence prior to quality/ vector
                   trimming by Lucy.
        Returns :  integer
        Args    :  name of a sequence

   length_clear
        Title   :  length_clear
        Usage   :  $lucyObj->length_clear($seqname)
        Function:  returns the length of a DNA sequence following quality/ vector
                   trimming by Lucy.
        Returns :  integer
        Args    :  name of a sequence

   start_clear
        Title   :  start_clear
        Usage   :  $lucyObj->start_clear($seqname)
        Function:  returns the beginning position of good quality, vector free DNA sequence
                   determined by Lucy.
        Returns :  integer
        Args    :  name of a sequence

   end_clear
        Title   :  end_clear
        Usage   :  $lucyObj->end_clear($seqname)
        Function:  returns the ending position of good quality, vector free DNA sequence
                   determined by Lucy.
        Returns :  integer
        Args    :  name of a sequence

   per_GC
        Title   :  per_GC
        Usage   :  $lucyObj->per_GC($seqname)
        Function:  returns the percente of the good quality, vector free DNA sequence
                   determined by Lucy.
        Returns :  float
        Args    :  name of a sequence

   full_length
        Title   :  full_length
        Usage   :  $lucyObj->full_length($seqname)
        Function:  returns the truth value for whether or not the sequence read was
                   full length (ie. vector present on both ends of read).  This method
                   depends on the user having provided the 'info' file (Lucy must be
                   run with the -debug 'info_filename' option to get this file).
        Returns :  boolean
        Args    :  name of a sequence

   polyA
        Title   :  polyA
        Usage   :  $lucyObj->polyA($seqname)
        Function:  returns the truth value for whether or not a poly-A tail was detected
                   and clipped by Lucy.  This method depends on the user having modified
                   the source for Lucy as outlined in DESCRIPTION and invoking Lucy with
                   the -cdna option and saving the standard error.
                   Note, the final sequence will not show the poly-A/T region.
        Returns :  boolean
        Args    :  name of a sequence

   get_rejects
        Title   :  get_rejects
        Usage   :  $lucyObj->get_rejects()
        Function:  returns a hash containing names of rejects and a 1 letter code for the
                   reason Lucy rejected the sequence.
                   Q- rejected because of low quality values
                   S- sequence was short
                   V- sequence was vector
                   E- sequence was empty
                   P- poly-A/T trimming caused sequence to be too short
                   In order to get the rejects, you must provide a file with the standard
                   error from Lucy.  You will only get the quality category rejects unless
                   you have modified the source and recompiled Lucy as outlined in DESCRIPTION.
        Returns :  hash reference
        Args    :  none

   Diff for Lucy source code
         352a353,354
         >       /* AGW added next line */
         >       fprintf(stderr, "Empty: %s\n", seqs[i].name);
         639a642,643
         >         /* AGW added next line */
         >         fprintf(stderr, "Short/ no insert: %s\n", seqs[i].name);
         678c682,686
         <     if (left) seqs[i].left+=left;
         ---
         >     if (left) {
         >       seqs[i].left+=left;
         >       /*  AGW added next line */
         >       fprintf(stderr, "%s has PolyA (left).\n", seqs[i].name);
         >     }
         681c689,693
         <     if (right) seqs[i].right-=right;
         ---
         >     if (right) {
         >       seqs[i].right-=right;
         >       /* AGW added next line */
         >       fprintf(stderr, "%s has PolyA (right).\n", seqs[i].name);
         >     }
         682a695,696
         >       /* AGW added next line */
         >       fprintf(stderr, "Dropped PolyA: %s\n", seqs[i].name);
         734a749,750
         >       /* AGW added next line */
         >       fprintf(stderr, "Vector: %s\n", seqs[i].name);

   This patch is to be applied to lucy.c from the lucy-1.19p release
        277a278,279
        >       /* AGW added next line */
        >       fprintf(stderr, "Short/ no insert: %s\n", seqs[i].name);
        588c590,592
        <     if ((seqs[i].len=bases)<=0)
        ---
        >     if ((seqs[i].len=bases)<=0) {
        >       /* AGW added next line */
        >       fprintf(stderr, "Empty: %s\n", seqs[i].name);
        589a594
        >     }
        893c898,902
        <       if (left) seqs[i].left+=left;
        ---
        >       if (left) {
        >         seqs[i].left+=left;
        >         /*  AGW added next line */
        >         fprintf(stderr, "%s has PolyA (left).\n", seqs[i].name);
        >       }
        896c905,909
        <       if (right) seqs[i].right-=right;
        ---
        >       if (right) {
        >         seqs[i].right-=right;
        >         /*  AGW added next line */
        >         fprintf(stderr, "%s has PolyA (right).\n", seqs[i].name);
        >         }
        898a912,913
        >         /* AGW added next line */
        >         fprintf(stderr, "Dropped PolyA: %s\n", seqs[i].name);
        949a965,966
        >         /* AGW added next line */
        >           fprintf(stderr, "Vector: %s\n", seqs[i].name);