Bio::Tools::Lucy(3pm)

📦
version 1.7.8 · 3 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💖 Bio::Tools::Lucy 💖

okay bestie, welcome to Bio::Tools::Lucy(3pm) from the User Contributed Perl Documentation ✨ — literally the tool you need when you're staring down Lucy output and you want to actually do something with it. let's go 🦋

🌸 NAME 🌸

Bio::Tools::Lucy — the object that analyzes the output from Lucy, a vector and quality trimming program from TIGR. it's giving "I read your Lucy files so you don't have to" 💅

✨ SYNOPSIS ✨

okay so first things first, you make the object. either straight from a Lucy output file:

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

then you can grab all the sequence names like it's nothing:

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

and if you wanna print seq + qual for the big ones (over 400 bp) so you can run CAP3? say less:

#  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";
}

or if you just want a whole array of Bio::PrimarySeq objects, iconic:

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

🌈 DESCRIPTION 🌈

Bio::Tools::Lucy.pm hands you all the methods for analyzing the sequence and quality values that the Lucy program from TIGR spits out. no cap 🔥

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 🎀

okay so 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. periodt.

🧚 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. lowkey so useful ✨

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. the way that's such a specific vibe 💜

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. rip to them 😭

$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. bestie we literally want to hear from you 💖

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. ngl the more detail you give, the faster someone can help you out 🦋

🐛 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 ✨

okay bestie, here's the whole menu of methods you can call on a Lucy object. Read this bit carefully though: anything with a leading underscore is internal — that's private business, do not call it directly. iykyk 💅

💖 new 💖

  • Title: new
  • Usage: 
$lucyObj = Bio::Tools::Lucy->new(seqfile => lucy.seq, rev_desig => '_R',
fwd_desig => '_F')
  • Function: builds a Lucy object out of the Lucy analysis files 🫶
  • Returns: a reference to a Bio::Tools::Lucy object
  • Args:
    • seqfile — the Fasta sequence file that Lucy made
    • qualfile — the quality values file that Lucy made
    • infofile — the info file you get when Lucy is run with the -debug 'infofile' option
    • stderrfile — the standard error captured from Lucy when Lucy runs with the -info option and STDERR gets pointed at stderrfile (like lucy ... 2> stderrfile). This file's info includes sequences that got dropped for low quality. If you've modified the Lucy source (peep adv_stderr below), it also includes info on which sequences were dropped for being vector, for being too short, for having no insert, and whether a poly-A tail was found (that last one only if Lucy was run with the -cdna option).
    • lucy_verbose — verbosity level, 0-1
    • fwd_desig — the string used to figure out whether a sequence is a forward read. The parser assumes this match happens at the end of the sequence name string.
    • rev_desig — same deal as above, but for reverse reads.
    • adv_stderr — can be set to a true value (1). Only works if you've modified the Lucy source code the way DESCRIPTION lays out and you're capturing the standard error from Lucy.

If you don't hand over filenames for qualfile, infofile or stderrfile, the module just assumes the extensions .qual, .info, and .stderr and goes looking in the same directory as the .seq file. 🌸

so like, if you make a Lucy object with $lucyObj = Bio::Tools::Lucy->new(seqfile =>lucy.seq), the module will find lucy.qual, lucy.info and lucy.stderr all by itself. iconic.

You can leave out any or all of the quality, info or stderr files — but heads up, you won't get to use all the object methods then (check the method docs below to see what needs what). 🙈

💖 _parse 💖

  • Title: _parse
  • Usage: n/a (internal function)
  • Function: called by new() to parse the 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 a reference to a Bio::PrimarySeq object where -id = 'sequence name' and -seq = 'sequence'
  • Returns: reference to a Bio::PrimarySeq object
  • Args: name of a sequence

💖 get_sequence_names 💖

  • Title: get_sequence_names
  • Usage: $lucyObj->get_sequence_names
  • Function: returns a reference to an array of the names of the sequences Lucy analyzed. These names are required for most of the accessor methods. Note: the Lucy binary will fail unless the 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 Lucy analyzed.
  • Returns: string
  • Args: name of a sequence

💖 quality 💖

  • Title: quality
  • Usage: $lucyObj->quality($seqname)
  • Function: returns the quality values of one of the sequences Lucy analyzed. This method depends on you 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 Lucy analyzed.
  • Returns: float
  • Args: name of a sequence

💖 direction 💖

  • Title: direction
  • Usage: $lucyObj->direction($seqname)
  • Function: returns the direction for one of the sequences Lucy analyzed — as long as fwd_desig or rev_desig were set back when the Lucy object was created. The strings it hands back 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 before Lucy did its quality/vector trimming.
  • 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 after Lucy did its quality/vector trimming.
  • Returns: integer
  • Args: name of a sequence

💖 start_clear 💖

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

💖 end_clear 💖

  • Title: end_clear
  • Usage: $lucyObj->end_clear($seqname)
  • Function: returns the ending position of the good quality, vector free DNA sequence that Lucy determined.
  • 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 (aka vector present on both ends of the read). This method depends on you having provided the 'info' file — Lucy has to be run with the -debug 'info_filename' option to get that 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 you having modified the Lucy source the way DESCRIPTION lays out, plus invoking Lucy with the -cdna option and saving the standard error. Heads up: 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 holding the names of rejects plus 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 made the sequence too short

To actually get the rejects, you have to provide a file with the standard error from Lucy. And ngl, you'll only get the quality category rejects unless you've modified the source and recompiled Lucy the way DESCRIPTION outlines.

  • 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);

and that's the whole page bestie, we ate that 💅✨ this version lives at perl v5.32.1, dated 2021-08-15, filed under Bio::Tools::Lucy(3pm) — go forth and parse some Lucy files, you've got this 🎀🦋💖

📦 where this page comes from