FIGOTable of Contents

Overview FIGO all_figfams family_containing figfam functional_roles genomes new subsystems GenomeO contigs_of display features_of genus_species id new taxonomy_of ContigO contig_length display dna_seq genome id new FeatureO annotations bbhs begin contig coupled_to covers display dna_seq end function_of genome id in_subsystems location max merge min new possible_frameshift possibly_truncated prot_seq run sims type BBHO new norm_bitscore peg1 peg2 psc AnnotationO display fid made_by new text timestamp CouplingO display evidence new peg1 peg2 sc SubsystemO curator genomes id new pegs_in_cell roles usable variant FunctionalRoleO id new FigFamO display function id members new rep_seqs should_be_member Examples Accessing FIGfams Accessing Subsystem data Display all complete, prokaryotic genomes Getting representative sequences for a FIGfam Placing a sequence into a FIGfam Show how to access contigs and extract sequence Testing for membership in FIGfam OverviewThis module is a set of packages encapsulating the SEED's core method using an "OOP-like" style.

There are several modules clearly related to "individual genomes:" FIGO, GenomeO, ContigO, FeatureO (and maybe AnnotationO).

There are also modules that deal with complex relationships betwee pairs or sets of features in one, two, or more genomes rather than any particular single genome BBHO, CouplingO, SubsystemO, FunctionalRoleO, FigFamO.

Finally, the methods in "Attribute" might in principle attac "atributes" to any type of object. (Likewise, in principle one might like to attach an "annotation" to any type of object

The four modules dealing with "genomes" have a reasonable clea "implied heirarchy:"

However, inheritance is NOT implemented using the @ISA mechanism because some methods deal with "pairwise" or "setwise" relations between object or other more complex relationships that do not naturally fit into any heirarchy -- which would get us into the whole quagmire of "multiple inheritance."

We have chosen to in many cases sidestep the entire issue of inheritanc via an ad hoc mechanism If a "child" object needs access to its "ancestors'" methods we will explicitly pass it references to its "ancestors," as subroutine arguments This is admittedly ugly, clumsy, and potentially error-prone -- but it has the advantage that, unlike multiple inheritance, we understand how to do it...

MODULE DEPENDENCIES: FIG, FIG_Config, FigFams, SFXlate, SproutFIG, Tracer gjoparseblast, Data::Dumper.

FIGOThe effective "base class" containing a few "top-level" methods.

newConstructs a new FIGO object.

USAGE:my $figo = FIGO->new(); #...Subclass defaults to FIG

my $figo = FIGO->new('SPROUT'); #...Subclass is a SPROUT object

genomesReturns a list of Taxonomy-IDs, possibly constrained by selection criteria (Default: Empty constraint returns all Tax-IDs in the SEED or SPROUT.)

USAGE:my @tax_ids = $figo->genomes();

my @tax_ids = $figo->genomes( @constraints );

@constraintsRETURNS: List of Tax-IDs.EXAMPLE:Display all complete, prokaryotic genomes

subsystemsRETURNS:EXAMPLE:Accessing Subsystem data

functional_roles(Not yet implemented)

RETURNS:EXAMPLE:all_figfamsReturns a list of all FIGfam objects.

USAGE:foreach $fam ($figO->all_figfams) { #...Do something }

RETURNS:EXAMPLE:Accessing FIGfams

family_containingUSAGE:my ($fam, $sims) = $figO->family_containing($seq);

$seq:RETURNS:EXAMPLE: Placing a sequence into a FIGfamfigfamUSAGE:my $fam = $figO->figfam($family_id);

$family_id;RETURNS:GenomeO newConstructor of GenomeO objects.

USAGE:my $orgO = GenomeO->new($figO, $tax_id);

RETURNS:idUSAGE:my $tax_id = $orgO->id();

RETURNS:genus_speciesUSAGE:$gs = $orgO->genus_species();

RETURNS:taxonomy_ofFUNCTION:Return the TAXONOMY string of a "GenomeO" object.

USAGE:my $taxonomy = $orgO->taxonomy_of();

RETURNS:TAXONOMY string.

contigs_ofRETURNS:List of contig objects contained in a GenomeO object.

EXAMPLE:Show how to access contigs and extract sequence

features_ofFUNCTION:Returns a list of "FeatureO" objects contained in a "GenomeO" object.

USAGE:my @featureOs = $orgO->features_of(); #...Fetch all features

my @featureOs = $orgO->features_of('peg'); #...Fetch only PEGs

RETURNS:List of "FeatureO" objects.

displayPrints the genus, species, and strain information about a genome to STDOUT.

USAGE:$genome->display();

RETURNS:ContigOMethods for working with DNA sequence objects.

newContig constructor.

USAGE:$contig = ContigO->new( $figO, $genomeId, $contigId);

$figO:$genomeId:$contigId:RETURNS:idRETURNS:genomeUSAGE:my $tax_id = $contig->genome->id();

RETURNS:contig_lengthUSAGE:my $len = $contig->contig_length();

RETURNS:dna_seqUSAGE:my $seq = $contig->dna_seq(beg, $end);

$beg:$end:RETURNS:displayPrints summary information about a "ContigO" object to STDOUT:

Genus, species, strain

Contig ID

Contig length

RETURNS:FeatureOMethods for working with features on "ContigO" objects.

newConstructor of new "FeatureO" objects

USAGE:my $feature = FeatureO->new( $figO, $fid );

$figO:"Base" FIGO object.

$fid:Feature-ID for new feature

RETURNS:A newly created "FeatureO" object.

idUSAGE:my $fid = $feature->id();

RETURNS:The FID (Feature ID) of a "FeatureO" object.

genomeUSAGE:my $taxid = $feature->genome();

RETURNS:The Taxon-ID for the "GenomeO" object containing the feature.

typeUSAGE:my $feature_type = $feature->type();

RETURNS:The feature object's "type" (e.g., "peg," "rna," etc.)

locationUSAGE:my $loc = $feature->location();

RETURNS:A string representing the feature object's location on the genome's DNA in SEED "tbl format" (i.e., "contig_beging_end").

contigUSAGE:my $contig = $feature->contig();

RETURNS:A "ContigO" object to access the contig dat for the contig the feature is on.

beginUSAGE:my $beg = $feature->begin();

RETURNS:The numerical coordinate of the first base of the feature.

endUSAGE:my $end = $feature->end();

RETURNS:The numerical coordinate of the last base of the feature.

dna_seqUSAGE:my $dna_seq = $feature->dna_seq();

RETURNS:A string contining the DNA subsequence of the conti running from the first to the last base of the feature.

If ($beg > $end), the reverse complement subsequence is returned.

prot_seqUSAGE:my $dna_seq = $feature->prot_seq();

RETURNS:A string contining the protein translation of the feature (if it exists) or the "undef" value if the feature does not exist or is not a PEG.

function_ofUSAGE:my $func = $feature->function_of();

RETURNS:A string containing the function assigned to the feature or the "undef" value if no function has been assigned.

coupled_toUSAGE:my @coupled_features = $feature->coupled_to();

RETURNS:A list of "CouplingO" objects describing the evidence for functional couplin between this feature and other nearby features.

annotationsUSAGE:my @annot_list = $feature->annotations();

RETURNS:A list of "AnnotationO" objects allowing access to the annotations for this feature.

in_subsystemsUSAGE:my @subsys_list = $feature->in_subsystems();

RETURNS:A list of "SubsystemO" objects allowing access to the subsystem that this feature particupates in.

possibly_truncatedUSAGE:my $trunc = $feature->possibly_truncated();

RETURNS:Boolean TRUE if the feature may be truncated boolean FALSE otherwise.

possible_frameshiftUSAGE:my $fs = $feature->possible_frameshift();

RETURNS:Boolean TRUE if the feature may be a frameshifted fragment boolean FALSE otherwise.

(NOTE: This is a crude prototype implementation and is mostly as an example of how to code using FIGO.)

run(Note: This function should be considered "PRIVATE")

FUNCTION:Passes a string containing a command to be execture by the "system" shell command.

USAGE:$feature->run($cmd);

RETURNS:Nil if the execution of $cmd was successful aborts with traceback if $cmd fails.

max(Note: This function should be considered "PRIVATE")

USAGE:my $max = $feature->max($x, $y);

$x and $yNumerical values.

RETURNS:The larger of the two numerical values $x and $y.

min(Note: This function should be considered "PRIVATE")

USAGE:my $min = $feature->min($x, $y);

$x and $yNumerical values.

RETURNS:The smaller of the two numerical values $x and $y.

covers(Question: Should this function be considered "PRIVATE" ???)

USAGE if (&covers(\@hits, $len, $diff, $must_shift)) { #...Do stuff }

Returns boolean TRUE if a set of BLAST HSPs "cover" more than 90 of the database sequence(?).

mergeMerge two HSPs unless their overlap or separation is too large.

RETURNS: Merged boundaries if merger succeeds, and undef if merger fails.

simsFUNCTION:Returns precomputed "Sim.pm" objects from the SEED.

USAGE:my @sims = $pegO->sims( -all, -cutoff => 1.0e-10);

my @sims = $pegO->sims( -max => 50, -cutoff => 1.0e-10);

RETURNS: List of sim objects.bbhsFUNCTION:Given a PEG-type "FeatureO" object, returns the list of BBHO object corresponding to the pre-computed BBHs for that PEG.

USAGE:my @bbhs = $pegO->bbhs();

RETURNS:List of BBHO objects.

displayFUNCTION:Prints info about a "FeatureO" object to STDOUT.

USAGE:$pegO->display();

RETURNS;(void)

BBHOMethods for accessing "Bidirectiona Best Hits" (BBHs).

newConstructor of BBHO objects.

(NOTE: The "average user" should never need to invoke this method.)

peg1USAGE:my $peg1 = $bbh->peg1();

RETURNS:A "FeatureO" object corresponding to the "query" sequenc in a BBH pair.

peg2USAGE:my $peg2 = $bbh->peg2();

RETURNS:A "FeatureO" object corresponding to the "database" sequenc in a BBH pair.

pscUSAGE:my $psc = $bbh->psc();

RETURNS:The numerical value of the BLAST E-value for the pair.

norm_bitscoreUSAGE:my $bsc = $bbh->norm_bitscore();

RETURNS:The "BLAST bit-score per aligned character" for the pair.

AnnotationOMethods for accessing SEED annotations.

newFUNCTION:Cronstruct a new "AnnotationO" object

USAGE:my $annotO = AnnotationO->new( $fid, $timestamp, $who, $text);

$fidA feature identifier.

$timestampThe UN*X timestamp one wishes to associate with the annotation.

$whoThe annotator's user-name.

$textThe textual content of the annotation.

RETURNS:An "AnnotationO" object.

fidFUNCTION:Extract the feature-ID that was annotated.

USAGE:my $fid = $annotO->fid();

RETURNS;The feature-ID as a string.

timestampFUNCTION:Extract the UN*X timestamp of the annotation.

USAGE:my $fid = $annotO->timestamp();

RETURNS;The timestamp as a string.

made_byFUNCTION:Extract the annotator's user-name.

USAGE:my $fid = $annotO->made_by();

RETURNS;The username of the annotator, as a string.

textFUNCTION:Extract the text of the annotation.

USGAE:my $text = $annotO->text();

RETURNS:The text of the annotation, as a string.

displayFUNCTION:Print the contents of an "AnnotationO" object to STDOUTUSAGE:my $annotO->display();

RETURNS:(void)

CouplingOMethods for accessing the "Functional coupling scores" of PEGs in close physical proximity to each other.

newFUNCTION:Construct a new "CouplingO" objec encapsulating the "functional coupling" scor between a pair of features in some genome.

USAGE:$couplingO = CouplingO->new($figO, $fid1, $fid2, $sc);

$figOParent "FIGO" object.

$fid1 and $fid2A pair of feature-IDs.

$scA functional-coupling score

RETURNS:A "CouplingO" object.

peg1FUNCTION:Returns a "FeatureO" object corresponding to the first FID in a coupled pair.

USAGE:my $peg1 = $couplingO->peg1();

RETURNS:A "FeatureO" object.

peg2FUNCTION:Returns a "FeatureO" object corresponding to the second FID in a coupled pair.

USAGE:my $peg2 = $couplingO->peg2();

RETURNS:A "FeatureO" object.

scFUNCTION:Extracts the "functional coupling" score from a "CouplingO" object.

USAGE:my $sc = $couplingO->sc();

RETURNS:A scalar score.

evidenceFUNCTION:Fetch the evidence for a "functional coupling" between two close PEGs in the form of a list of objects describing the "Pairs of Close Homologs" (PCHs supporting the existence of a functional coupling between the two close PEGs.

USAGE:my $evidence = $couplingO->evidence();

RETURNSList of pairs of "FeatureO" objects.

displayFUNCTION:Print the contents of a "CouplingO" object to STDOUT in human-readable form.

USAGE:$couplingO->display();

RETURNS:(Void)

SubsystemO new id usable genomes roles curator variant pegs_in_cell FunctionalRoleOMethods for accessing the functional roles of features.

new id FigFamO new id function members rep_seqs should_be_member display Examples Display all complete, prokaryotic genomesuse FIGO my $figO = new FIGO;

foreach $genome ($figO->genomes('complete','prokaryotic') $genome->display }

#---------------------------------------------

use FIG my $fig = new FIG;

foreach $genome (grep { $fig->is_prokaryotic($_) } $fig->genomes('complete') print join("\t",("Genome",$genome,$fig->genus_species($genome))),"\n" }

###############################################

Show how to access contigs and extract sequenceuse FIGO my $figO = new FIGO;

$genomeId = '83333.1' my $genome = new GenomeO($figO,$genomeId);

foreach $contig ($genome->contigs_of $tag1 = $contig->dna_seq(1,10) $tag2 = $contig->dna_seq(10,1) print join("\t",($tag1,$tag2,$contig->id,$contig->contig_length)),"\n" }

#---------------------------------------------

use FIG my $fig = new FIG;

$genomeId = '83333.1';

$contig_lengths = $fig->contig_lengths($genomeId);

foreach $contig ($fig->contigs_of($genomeId) $tag1 = $fig->dna_seq($genomeId,join("_",($contig,1,10))) $tag2 = $fig->dna_seq($genomeId,join("_",($contig,10,1))) print join("\t",($tag1,$tag2,$contig,$contig_lengths->{$contig})),"\n" }

###############################################

### accessing data related to features

use FIGO my $figO = new FIGO;

my $genome = new GenomeO($figO,"83333.1") my $peg = "fig|83333.1.peg.4" my $pegO = new FeatureO($figO,$peg);

print join("\t",$pegO->id,$pegO->location,$pegO->function_of),"\n" $pegO->dna_seq,"\n" $pegO->prot_seq,"\n";

foreach $fidO ($genome->features_of('rna') print join("\t",$fidO->id,$fidO->location,$fidO->function_of),"\n" }

#---------------------------------------------

use FIG my $fig = new FIG;

my $genome = "83333.1" my $peg = "fig|83333.1.peg.4";

print join("\t",$peg,scalar $fig->feature_location($peg),scalar $fig->function_of($peg)),"\n" $fig->dna_seq($genome,$fig->feature_location($peg)),"\n" $fig->get_translation($peg),"\n";

foreach $fid ($fig->all_features($genome,'rna') print join("\t",$fid,scalar $fig->feature_location($fid),scalar $fig->function_of($fid)),"\n" }

###############################################

### accessing similarities

use FIGO my $figO = new FIGO;

$peg = "fig|83333.1.peg.4" $pegO = new FeatureO($figO,$peg);

@sims = $pegO->sims; # use sims( -all => 1, -max => 10000, -cutoff => 1.0e-20) to al # sims (including non-FIG sequence foreach $sim (@sims $peg2 = $sim->id2 $pegO2 = new FeatureO($figO,$peg2) $func = $pegO2->function_of $sc = $sim->psc print join("\t",($peg2,$sc,$func)),"\n" }

#---------------------------------------------

use FIG my $fig = new FIG;

$peg = "fig|83333.1.peg.4";

@sims = $fig->sims($peg,1000,1.0e-5,"fig") foreach $sim (@sims $peg2 = $sim->id2 $func = $fig->function_of($peg2) $sc = $sim->psc print join("\t",($peg2,$sc,$func)),"\n" }

###############################################

### accessing BBHs

use FIGO my $figO = new FIGO;

$peg = "fig|83333.1.peg.4" $pegO = new FeatureO($figO,$peg);

@bbhs = $pegO->bbhs foreach $bbh (@bbhs $peg2 = $bbh->peg2 $pegO2 = new FeatureO($figO,$peg2) $func = $pegO2->function_of $sc = $bbh->psc print join("\t",($peg2,$sc,$func)),"\n" }

#---------------------------------------------

use FIG my $fig = new FIG;

$peg = "fig|83333.1.peg.4";

@bbhs = $fig->bbhs($peg) foreach $bbh (@bbhs ($peg2,$sc,$bit_score) = @$bbh $func = $fig->function_of($peg2) print join("\t",($peg2,$sc,$func)),"\n" }

###############################################

### accessing annotations

use FIGO my $figO = new FIGO;

$peg = "fig|83333.1.peg.4" $pegO = new FeatureO($figO,$peg);

@annotations = $pegO->annotations;

foreach $ann (@annotations print join("\n",$ann->fid,$ann->timestamp(1),$ann->made_by,$ann->text),"\n\n" }

#---------------------------------------------

use FIG my $fig = new FIG;

$peg = "fig|83333.1.peg.4" @annotations = $fig->feature_annotations($peg) foreach $_ (@annotations (undef,$ts,$who,$text) = @$_ $who =~ s/master://i print "$ts\n$who\n$text\n\n" }

###############################################

### accessing coupling data

use FIGO my $figO = new FIGO;

my $peg = "fig|83333.1.peg.4" my $pegO = new FeatureO($figO,$peg) foreach $coupled ($pegO->coupled_to print join("\t",($coupled->peg1,$coupled->peg2,$coupled->sc)),"\n" foreach $tuple ($coupled->evidence my($peg3O,$peg4O,$rep) = @$tuple print "\t",join("\t",($peg3O->id,$peg4O->id,$rep)),"\n" print "\n" }

#---------------------------------------------

use FIG my $fig = new FIG;

my $peg1 = "fig|83333.1.peg.4" foreach $coupled ($fig->coupled_to($peg1) ($peg2,$sc) = @$coupled print join("\t",($peg1,$peg2,$sc)),"\n" foreach $tuple ($fig->coupling_evidence($peg1,$peg2) my($peg3,$peg4,$rep) = @$tuple print "\t",join("\t",($peg3,$peg4,$rep)),"\n" print "\n" }

###############################################

Accessing Subsystem datause FIGO my $figO = new FIGO;

foreach $sub ($figO->subsystems if ($sub->usable print join("\t",($sub->id,$sub->curator)),"\n";

print "\tRoles\n";@roles = $sub->roles;foreach $role (@roles){print "\t\t",join("\t",($role->id)),"\n";}print "\tGenomes\n";foreach $genome ($sub->genomes){print "\t\t",join("\t",($sub->variant($genome),$genome->id,$genome->genus_species)),"\n";@pegs = ();foreach $role (@roles){push(@pegs,$sub->pegs_in_cell($genome,$role));}print "\t\t\t",join(",",@pegs),"\n";}}}#---------------------------------------------

use FIG my $fig = new FIG;

foreach $sub (grep { $fig->usable_subsystem($_) } $fig->all_subsystems $subO = new Subsystem($sub,$fig) $curator = $subO->get_curator print join("\t",($sub,$curator)),"\n";

print "\tRoles\n";@roles = $subO->get_roles;foreach $role (@roles){print "\t\t",join("\t",($role)),"\n";}print "\tGenomes\n";foreach $genome ($subO->get_genomes){print "\t\t",join("\t",($subO->get_variant_code_for_genome($genome),$genome,$fig->genus_species($genome))),"\n";foreach $role (@roles){push(@pegs,$subO->get_pegs_from_cell($genome,$role));}print "\t\t\t",join(",",@pegs),"\n";}print "\n";}###############################################

Accessing FIGfamsuse FIGO my $figO = new FIGO;

foreach $fam ($figO->all_figfams print join("\t",($fam->id,$fam->function)),"\n" foreach $pegO ($fam->members $peg = $pegO->id print "\t$peg\n" }

#---------------------------------------------

use FIG use FigFam use FigFams;

my $fig = new FIG my $figfams = new FigFams($fig);

foreach $fam ($figfams->all_families my $figfam = new FigFam($fig,$fam) print join("\t",($fam,$figfam->family_function)),"\n" foreach $peg ($figfam->list_members print "\t$peg\n" }

###############################################

Placing a sequence into a FIGfamuse FIGO my $figO = new FIGO;

$seq = "MKLYNLKDHNEQVSFAQAVTQGLGKNQGLFFPHDLPEFSLTEIDEMLKLDFVTRSAKIL AFIGDEIPQEILEERVRAAFAFPAPVANVESDVGCLELFHGPTLAFKDFGGRFMAQMLT IAGDKPVTILTATSGDTGAAVAHAFYGLPNVKVVILYPRGKISPLQEKLFCTLGGNIET AIDGDFDACQALVKQAFDDEELKVALGLNSANSINISRLLAQICYYFEAVAQLPQETRN LVVSVPSGNFGDLTAGLLAKSLGLPVKRFIAATNVNDTVPRFLHDGQWSPKATQATLSN MDVSQPNNWPRVEELFRRKIWQLKELGYAAVDDETTQQTMRELKELGYTSEPHAAVAYR LRDQLNPGEYGLFLGTAHPAKFKESVEAILGETLDLPKELAERADLPLLSHNLPADFAA RKLMMNHQ" $seq =~ s/\n//gs;

my($fam,$sims) = $figO->family_containing($seq);

if ($fam){print join("\t",($fam->id,$fam->function)),"\n";print &Dumper($sims);}else{print "Could not place it in a family\n";}#---------------------------------------------

use FIG use FigFam use FigFams;

my $fig = new FIG my $figfams = new FigFams($fig);

my($fam,$sims) = $figfams->place_in_family($seq);

if ($fam){print join("\t",($fam->family_id,$fam->family_function)),"\n";print &Dumper($sims);}else{print "Could not place it in a family\n";}###############################################

Getting representative sequences for a FIGfamuse FIGO my $figO = new FIGO;

$fam = "FIG102446" my $famO = &FigFamO::new('FigFamO',$figO,$fam) my @rep_seqs = $famO->rep_seqs;

foreach $seq (@rep_seqs print ">query\n$seq\n" }

#---------------------------------------------

use FIG use FigFam use FigFams;

my $fig = new FIG;

$fam = "FIG102446" my $famO = new FigFam($fig,$fam) my @rep_seqs = $famO->representatives;

foreach $seq (@rep_seqs print ">query\n$seq\n" }

###############################################

Testing for membership in FIGfamuse FIGO my $figO = new FIGO;

$fam = "FIG102446" my $famO = &FigFamO::new('FigFamO',$figO,$fam) my($should_be, $sims) = $famO->should_be_member($seq);

if ($should_be print join("\t",($famO->id,$famO->function)),"\n" print &Dumper($sims) els print "Sequence should not be added to family\n" }

#---------------------------------------------

use FIG use FigFam use FigFams;

my $fig = new FIG;

$fam = "FIG102446" my $famO = new FigFam($fig,$fam) my($should_be, $sims) = $famO->should_be_member($seq);

if ($should_be print join("\t",($famO->family_id,$famO->family_function)),"\n" print &Dumper($sims) els print "Sequence should not be added to family\n" }