.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Bio::Tools::Lucy 3pm"
.TH Bio::Tools::Lucy 3pm "2021-08-15" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Bio::Tools::Lucy \- Object for analyzing the output from Lucy,
  a vector and quality trimming program from TIGR
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  # Create the Lucy object from an existing Lucy output file
\&  @params = (\*(Aqseqfile\*(Aq => \*(Aqlucy.seq\*(Aq, \*(Aqlucy_verbose\*(Aq => 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\en", $lucyObj\->sequence($name), "\en";
\&      print QUAL ">$name\en", $lucyObj\->quality($name), "\en";
\&  }
\&
\&  # Get an array of Bio::PrimarySeq objects
\&  @seqObjs = $lucyObj\->get_Seq_Objs();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Bio::Tools::Lucy.pm provides methods for analyzing the sequence and
quality values generated by Lucy program from \s-1TIGR.\s0
.PP
Lucy will identify vector, poly\-A/T tails, and poor quality regions in
a sequence.  (www.genomics.purdue.edu/gcg/other/lucy.pdf)
.PP
The input to Lucy can be the Phred sequence and quality files
generated from running Phred on a set of chromatograms.
.PP
Lucy can be obtained (free of charge to academic users) from
www.tigr.org/softlab
.PP
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
.PP
Please contact the author of this module if you have any problems
making these modifications.
.PP
You do not have to make these modifications to use this module.
.SS "Creating a Lucy object"
.IX Subsection "Creating a Lucy object"
.Vb 3
\&  @params = (\*(Aqseqfile\*(Aq => \*(Aqlucy.seq\*(Aq, \*(Aqadv_stderr\*(Aq => 1, 
\&             \*(Aqfwd_desig\*(Aq => \*(Aq_F\*(Aq, \*(Aqrev_desig\*(Aq => \*(Aq_R\*(Aq);
\&  $lucyObj = Bio::Tools::Lucy\->new(@params);
.Ve
.SS "Using a Lucy object"
.IX Subsection "Using a Lucy object"
.Vb 3
\&  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\et",
\&                 $lucyObj\->length_clear($name), "\et",
\&                 $lucyObj\->per_GC($name), "\en",
\&                 $lucyObj\->sequence($name), "\en";
\&  }
\&
\&
\&  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\en", $lucyObj\->sequence($name), "\en";
\&      print QUAL ">$name\en", $lucyObj\->quality($name), "\en";
\&  }
\&
\&  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.
.Ve
.SH "FEEDBACK"
.IX Header "FEEDBACK"
.SS "Mailing Lists"
.IX Subsection "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.
.PP
.Vb 2
\&  bioperl\-l@bioperl.org                  \- General discussion
\&  http://bioperl.org/wiki/Mailing_lists  \- About the mailing lists
.Ve
.SS "Support"
.IX Subsection "Support"
Please direct usage questions or support issues to the mailing list:
.PP
\&\fIbioperl\-l@bioperl.org\fR
.PP
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.
.SS "Reporting Bugs"
.IX Subsection "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:
.PP
.Vb 1
\&  https://github.com/bioperl/bioperl\-live/issues
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Andrew G. Walsh		paeruginosa@hotmail.com
.SH "APPENDIX"
.IX Header "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.
.SS "new"
.IX Subsection "new"
.Vb 10
\& Title   :  new
\& Usage   :  $lucyObj = Bio::Tools::Lucy\->new(seqfile => lucy.seq, rev_desig => \*(Aq_R\*(Aq, 
\&            fwd_desig => \*(Aq_F\*(Aq)
\& 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 
\&                     \*(Aqinfofile\*(Aq 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\*(Aqve 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.
.Ve
.PP
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.
.PP
For example, if you create a Lucy object with \f(CW$lucyObj\fR =
Bio::Tools::Lucy\->new(seqfile =>lucy.seq), the module will
find lucy.qual, lucy.info and lucy.stderr.
.PP
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).
.SS "_parse"
.IX Subsection "_parse"
.Vb 5
\& Title   :  _parse
\& Usage   :  n/a (internal function)
\& Function:  called by new() to parse Lucy output files
\& Returns :  nothing
\& Args    :  none
.Ve
.SS "get_Seq_Objs"
.IX Subsection "get_Seq_Objs"
.Vb 4
\& Title   :  get_Seq_Objs
\& Usage   :  $lucyObj\->get_Seq_Objs()
\& Function:  returns an array of references to Bio::PrimarySeq objects 
\&            where \-id = \*(Aqsequence name\*(Aq and \-seq = \*(Aqsequence\*(Aq
\&
\& Returns :  array of Bio::PrimarySeq objects
\& Args    :  none
.Ve
.SS "get_Seq_Obj"
.IX Subsection "get_Seq_Obj"
.Vb 6
\& Title   :  get_Seq_Obj
\& Usage   :  $lucyObj\->get_Seq_Obj($seqname)
\& Function:  returns reference to a Bio::PrimarySeq object where \-id = \*(Aqsequence name\*(Aq
\&            and \-seq = \*(Aqsequence\*(Aq
\& Returns :  reference to Bio::PrimarySeq object
\& Args    :  name of a sequence
.Ve
.SS "get_sequence_names"
.IX Subsection "get_sequence_names"
.Vb 7
\& 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
.Ve
.SS "sequence"
.IX Subsection "sequence"
.Vb 5
\& 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
.Ve
.SS "quality"
.IX Subsection "quality"
.Vb 6
\& 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
.Ve
.SS "avg_quality"
.IX Subsection "avg_quality"
.Vb 5
\& 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
.Ve
.SS "direction"
.IX Subsection "direction"
.Vb 8
\& Title   :  direction
\& Usage   :  $lucyObj\->direction($seqname)
\& Function:  returns the direction for one of the sequences analyzed by Lucy
\&            providing that \*(Aqfwd_desig\*(Aq or \*(Aqrev_desig\*(Aq were set when the
\&            Lucy object was created.
\&            Strings returned are: \*(AqF\*(Aq for forward, \*(AqR\*(Aq for reverse.  
\& Returns :  string 
\& Args    :  name of a sequence
.Ve
.SS "length_raw"
.IX Subsection "length_raw"
.Vb 6
\& 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
.Ve
.SS "length_clear"
.IX Subsection "length_clear"
.Vb 6
\& 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
.Ve
.SS "start_clear"
.IX Subsection "start_clear"
.Vb 6
\& 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
.Ve
.SS "end_clear"
.IX Subsection "end_clear"
.Vb 6
\& 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
.Ve
.SS "per_GC"
.IX Subsection "per_GC"
.Vb 6
\& 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
.Ve
.SS "full_length"
.IX Subsection "full_length"
.Vb 8
\& 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 \*(Aqinfo\*(Aq file (Lucy must be
\&            run with the \-debug \*(Aqinfo_filename\*(Aq option to get this file).
\& Returns :  boolean 
\& Args    :  name of a sequence
.Ve
.SS "polyA"
.IX Subsection "polyA"
.Vb 9
\& 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
.Ve
.SS "get_rejects"
.IX Subsection "get_rejects"
.Vb 10
\& 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
.Ve
.SS "Diff for Lucy source code"
.IX Subsection "Diff for Lucy source code"
.Vb 10
\&  352a353,354
\&  >       /* AGW added next line */
\&  >       fprintf(stderr, "Empty: %s\en", seqs[i].name);
\&  639a642,643
\&  >         /* AGW added next line */
\&  >         fprintf(stderr, "Short/ no insert: %s\en", 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).\en", 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).\en", seqs[i].name);
\&  >     }
\&  682a695,696
\&  >       /* AGW added next line */
\&  >       fprintf(stderr, "Dropped PolyA: %s\en", seqs[i].name); 
\&  734a749,750
\&  >       /* AGW added next line */
\&  >       fprintf(stderr, "Vector: %s\en", seqs[i].name);
.Ve
.SS "This patch is to be applied to lucy.c from the lucy\-1.19p release"
.IX Subsection "This patch is to be applied to lucy.c from the lucy-1.19p release"
.Vb 10
\& 277a278,279
\& >       /* AGW added next line */
\& >       fprintf(stderr, "Short/ no insert: %s\en", 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\en", 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).\en", 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).\en", seqs[i].name);
\& >         }
\& 898a912,913
\& >         /* AGW added next line */
\& >         fprintf(stderr, "Dropped PolyA: %s\en", seqs[i].name);
\& 949a965,966
\& >         /* AGW added next line */
\& >           fprintf(stderr, "Vector: %s\en", seqs[i].name);
.Ve