[Bio] / Sprout / Sprout.pm Repository:
ViewVC logotype

Diff of /Sprout/Sprout.pm

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.31, Wed Sep 14 13:14:12 2005 UTC revision 1.70, Fri Jun 23 19:08:58 2006 UTC
# Line 1  Line 1 
1  package Sprout;  package Sprout;
2    
3        require Exporter;
4        use ERDB;
5        @ISA = qw(Exporter ERDB);
6      use Data::Dumper;      use Data::Dumper;
7      use strict;      use strict;
8      use Carp;      use Carp;
# Line 7  Line 10 
10      use XML::Simple;      use XML::Simple;
11      use DBQuery;      use DBQuery;
12      use DBObject;      use DBObject;
     use ERDB;  
13      use Tracer;      use Tracer;
14      use FIGRules;      use FIGRules;
15      use Stats;      use Stats;
# Line 32  Line 34 
34  query tasks. For example, L</genomes> lists the IDs of all the genomes in the database and  query tasks. For example, L</genomes> lists the IDs of all the genomes in the database and
35  L</dna_seq> returns the DNA sequence for a specified genome location.  L</dna_seq> returns the DNA sequence for a specified genome location.
36    
37    The Sprout object is a subclass of the ERDB object and inherits all its properties and methods.
38    
39  =cut  =cut
40    
41  #: Constructor SFXlate->new_sprout_only();  #: Constructor SFXlate->new_sprout_only();
# Line 62  Line 66 
66    
67  * B<xmlFileName> name of the XML file containing the database definition (default C<SproutDBD.xml>)  * B<xmlFileName> name of the XML file containing the database definition (default C<SproutDBD.xml>)
68    
69  * B<userData> user name and password, delimited by a slash (default C<root/>)  * B<userData> user name and password, delimited by a slash (default same as SEED)
70    
71  * B<port> connection port (default C<0>)  * B<port> connection port (default C<0>)
72    
73    * B<sock> connection socket (default same as SEED)
74    
75  * B<maxSegmentLength> maximum number of residues per feature segment, (default C<4500>)  * B<maxSegmentLength> maximum number of residues per feature segment, (default C<4500>)
76    
77  * B<maxSequenceLength> maximum number of residues per sequence, (default C<8000>)  * B<maxSequenceLength> maximum number of residues per sequence, (default C<8000>)
# Line 92  Line 98 
98                                                          # database type                                                          # database type
99                         dataDir      => $FIG_Config::sproutData,                         dataDir      => $FIG_Config::sproutData,
100                                                          # data file directory                                                          # data file directory
101                         xmlFileName  => "$FIG_Config::sproutData/SproutDBD.xml",                         xmlFileName  => "$FIG_Config::fig/SproutDBD.xml",
102                                                          # database definition file name                                                          # database definition file name
103                         userData     => "$FIG_Config::dbuser/$FIG_Config::dbpass",                         userData     => "$FIG_Config::dbuser/$FIG_Config::dbpass",
104                                                          # user name and password                                                          # user name and password
105                         port         => $FIG_Config::dbport,                         port         => $FIG_Config::dbport,
106                                                          # database connection port                                                          # database connection port
107                           sock         => $FIG_Config::dbsock,
108                         maxSegmentLength => 4500,        # maximum feature segment length                         maxSegmentLength => 4500,        # maximum feature segment length
109                         maxSequenceLength => 8000,       # maximum contig sequence length                         maxSequenceLength => 8000,       # maximum contig sequence length
110                         noDBOpen     => 0,               # 1 to suppress the database open                         noDBOpen     => 0,               # 1 to suppress the database open
# Line 111  Line 118 
118      my $dbh;      my $dbh;
119      if (! $optionTable->{noDBOpen}) {      if (! $optionTable->{noDBOpen}) {
120          $dbh = DBKernel->new($optionTable->{dbType}, $dbName, $userName,          $dbh = DBKernel->new($optionTable->{dbType}, $dbName, $userName,
121                                  $password, $optionTable->{port});                                  $password, $optionTable->{port}, undef, $optionTable->{sock});
122      }      }
123      # Create the ERDB object.      # Create the ERDB object.
124      my $xmlFileName = "$optionTable->{xmlFileName}";      my $xmlFileName = "$optionTable->{xmlFileName}";
125      my $erdb = ERDB->new($dbh, $xmlFileName);      my $retVal = ERDB::new($class, $dbh, $xmlFileName);
126      # Create this object.      # Add the option table and XML file name.
127      my $self = { _erdb => $erdb, _options => $optionTable, _xmlName => $xmlFileName };      $retVal->{_options} = $optionTable;
128      # Bless and return it.      $retVal->{_xmlName} = $xmlFileName;
129      bless $self;      # Return it.
130      return $self;      return $retVal;
131  }  }
132    
133  =head3 MaxSegment  =head3 MaxSegment
# Line 155  Line 162 
162      return $self->{_options}->{maxSequenceLength};      return $self->{_options}->{maxSequenceLength};
163  }  }
164    
 =head3 Get  
   
 C<< my $query = $sprout->Get(\@objectNames, $filterClause, \@parameterList); >>  
   
 This method allows a general query against the Sprout data using a specified filter clause.  
   
 The filter is a standard WHERE/ORDER BY clause with question marks as parameter markers and each  
 field name represented in the form B<I<objectName>(I<fieldName>)>. For example, the  
 following call requests all B<Genome> objects for the genus specified in the variable  
 $genus.  
   
 C<< $query = $sprout->Get(['Genome'], "Genome(genus) = ?", [$genus]); >>  
   
 The WHERE clause contains a single question mark, so there is a single additional  
 parameter representing the parameter value. It would also be possible to code  
   
 C<< $query = $sprout->Get(['Genome'], "Genome(genus) = \'$genus\'"); >>  
   
 however, this version of the call would generate a syntax error if there were any quote  
 characters inside the variable C<$genus>.  
   
 The use of the strange parenthesized notation for field names enables us to distinguish  
 hyphens contained within field names from minus signs that participate in the computation  
 of the WHERE clause. All of the methods that manipulate fields will use this same notation.  
   
 It is possible to specify multiple entity and relationship names in order to retrieve more than  
 one object's data at the same time, which allows highly complex joined queries. For example,  
   
 C<< $query = $sprout->Get(['Genome', 'ComesFrom', 'Source'], "Genome(genus) = ?", [$genus]); >>  
   
 This query returns all the genomes for a particular genus and allows access to the  
 sources from which they came. The join clauses to go from Genome to Source are generated  
 automatically.  
   
 Finally, the filter clause can contain sort information. To do this, simply put an C<ORDER BY>  
 clause at the end of the filter. Field references in the ORDER BY section follow the same rules  
 as they do in the filter itself; in other words, each one must be of the form B<I<objectName>(I<fieldName>)>.  
 For example, the following filter string gets all genomes for a particular genus and sorts  
 them by species name.  
   
 C<< $query = $sprout->Get(['Genome'], "Genome(genus) = ? ORDER BY Genome(species)", [$genus]); >>  
   
 It is also permissible to specify I<only> an ORDER BY clause. For example, the following invocation gets  
 all genomes ordered by genus and species.  
   
 C<< $query = $sprout->Get(['Genome'], "ORDER BY Genome(genus), Genome(species)"); >>  
   
 Odd things may happen if one of the ORDER BY fields is in a secondary relation. So, for example, an  
 attempt to order B<Feature>s by alias may (depending on the underlying database engine used) cause  
 a single feature to appear more than once.  
   
 If multiple names are specified, then the query processor will automatically determine a  
 join path between the entities and relationships. The algorithm used is very simplistic.  
 In particular, you can't specify any entity or relationship more than once, and if a  
 relationship is recursive, the path is determined by the order in which the entity  
 and the relationship appear. For example, consider a recursive relationship B<IsParentOf>  
 which relates B<People> objects to other B<People> objects. If the join path is  
 coded as C<['People', 'IsParentOf']>, then the people returned will be parents. If, however,  
 the join path is C<['IsParentOf', 'People']>, then the people returned will be children.  
   
 =over 4  
   
 =item objectNames  
   
 List containing the names of the entity and relationship objects to be retrieved.  
   
 =item filterClause  
   
 WHERE/ORDER BY clause (without the WHERE) to be used to filter and sort the query. The WHERE clause can  
 be parameterized with parameter markers (C<?>). Each field used must be specified in the standard form  
 B<I<objectName>(I<fieldName>)>. Any parameters specified in the filter clause should be added to the  
 parameter list as additional parameters. The fields in a filter clause can come from primary  
 entity relations, relationship relations, or secondary entity relations; however, all of the  
 entities and relationships involved must be included in the list of object names.  
   
 =item parameterList  
   
 List of the parameters to be substituted in for the parameters marks in the filter clause.  
   
 =item RETURN  
   
 Returns a B<DBQuery> that can be used to iterate through all of the results.  
   
 =back  
   
 =cut  
   
 sub Get {  
     # Get the parameters.  
     my ($self, $objectNames, $filterClause, $parameterList) = @_;  
     # We differ from the ERDB Get method in that the parameter list is passed in as a list reference  
     # rather than a list of parameters. The next step is to convert the parameters from a reference  
     # to a real list. We can only do this if the parameters have been specified.  
     my @parameters;  
     if ($parameterList) { @parameters = @{$parameterList}; }  
     return $self->{_erdb}->Get($objectNames, $filterClause, @parameters);  
 }  
   
 =head3 GetEntity  
   
 C<< my $entityObject = $sprout->GetEntity($entityType, $ID); >>  
   
 Return an object describing the entity instance with a specified ID.  
   
 =over 4  
   
 =item entityType  
   
 Entity type name.  
   
 =item ID  
   
 ID of the desired entity.  
   
 =item RETURN  
   
 Returns a B<DBObject> representing the desired entity instance, or an undefined value if no  
 instance is found with the specified key.  
   
 =back  
   
 =cut  
   
 sub GetEntity {  
     # Get the parameters.  
     my ($self, $entityType, $ID) = @_;  
     # Call the ERDB method.  
     return $self->{_erdb}->GetEntity($entityType, $ID);  
 }  
   
 =head3 GetEntityValues  
   
 C<< my @values = GetEntityValues($entityType, $ID, \@fields); >>  
   
 Return a list of values from a specified entity instance.  
   
 =over 4  
   
 =item entityType  
   
 Entity type name.  
   
 =item ID  
   
 ID of the desired entity.  
   
 =item fields  
   
 List of field names, each of the form I<objectName>C<(>I<fieldName>C<)>.  
   
 =item RETURN  
   
 Returns a flattened list of the values of the specified fields for the specified entity.  
   
 =back  
   
 =cut  
 #: Return Type @;  
 sub GetEntityValues {  
     # Get the parameters.  
     my ($self, $entityType, $ID, $fields) = @_;  
     # Call the ERDB method.  
     return $self->{_erdb}->GetEntityValues($entityType, $ID, $fields);  
 }  
   
 =head3 ShowMetaData  
   
 C<< $sprout->ShowMetaData($fileName); >>  
   
 This method outputs a description of the database to an HTML file in the data directory.  
   
 =over 4  
   
 =item fileName  
   
 Fully-qualified name to give to the output file.  
   
 =back  
   
 =cut  
   
 sub ShowMetaData {  
     # Get the parameters.  
     my ($self, $fileName) = @_;  
     # Compute the file name.  
     my $options = $self->{_options};  
     # Call the show method on the underlying ERDB object.  
     $self->{_erdb}->ShowMetaData($fileName);  
 }  
   
165  =head3 Load  =head3 Load
166    
167  C<< $sprout->Load($rebuild); >>;  C<< $sprout->Load($rebuild); >>;
# Line 379  Line 196 
196  sub Load {  sub Load {
197      # Get the parameters.      # Get the parameters.
198      my ($self, $rebuild) = @_;      my ($self, $rebuild) = @_;
     # Get the database object.  
     my $erdb = $self->{_erdb};  
199      # Load the tables from the data directory.      # Load the tables from the data directory.
200      my $retVal = $erdb->LoadTables($self->{_options}->{dataDir}, $rebuild);      my $retVal = $self->LoadTables($self->{_options}->{dataDir}, $rebuild);
201      # Return the statistics.      # Return the statistics.
202      return $retVal;      return $retVal;
203  }  }
204    
205  =head3 LoadUpdate  =head3 LoadUpdate
206    
207  C<< my %stats = $sprout->LoadUpdate($truncateFlag, \@tableList); >>  C<< my $stats = $sprout->LoadUpdate($truncateFlag, \@tableList); >>
208    
209  Load updates to one or more database tables. This method enables the client to make changes to one  Load updates to one or more database tables. This method enables the client to make changes to one
210  or two tables without reloading the whole database. For each table, there must be a corresponding  or two tables without reloading the whole database. For each table, there must be a corresponding
# Line 422  Line 237 
237  sub LoadUpdate {  sub LoadUpdate {
238      # Get the parameters.      # Get the parameters.
239      my ($self, $truncateFlag, $tableList) = @_;      my ($self, $truncateFlag, $tableList) = @_;
     # Get the database object.  
     my $erdb = $self->{_erdb};  
240      # Declare the return value.      # Declare the return value.
241      my $retVal = Stats->new();      my $retVal = Stats->new();
242      # Get the data directory.      # Get the data directory.
# Line 437  Line 250 
250              Trace("No load file found for $tableName in $dataDir.") if T(0);              Trace("No load file found for $tableName in $dataDir.") if T(0);
251          } else {          } else {
252              # Attempt to load this table.              # Attempt to load this table.
253              my $result = $erdb->LoadTable($fileName, $tableName, $truncateFlag);              my $result = $self->LoadTable($fileName, $tableName, $truncateFlag);
254              # Accumulate the resulting statistics.              # Accumulate the resulting statistics.
255              $retVal->Accumulate($result);              $retVal->Accumulate($result);
256          }          }
# Line 446  Line 259 
259      return $retVal;      return $retVal;
260  }  }
261    
262    =head3 GenomeCounts
263    
264    C<< my ($arch, $bact, $euk, $vir, $env, $unk) = $sprout->GenomeCounts($complete); >>
265    
266    Count the number of genomes in each domain. If I<$complete> is TRUE, only complete
267    genomes will be included in the counts.
268    
269    =over 4
270    
271    =item complete
272    
273    TRUE if only complete genomes are to be counted, FALSE if all genomes are to be
274    counted
275    
276    =item RETURN
277    
278    A six-element list containing the number of genomes in each of six categories--
279    Archaea, Bacteria, Eukaryota, Viral, Environmental, and Unknown, respectively.
280    
281    =back
282    
283    =cut
284    
285    sub GenomeCounts {
286        # Get the parameters.
287        my ($self, $complete) = @_;
288        # Set the filter based on the completeness flag.
289        my $filter = ($complete ? "Genome(complete) = 1" : "");
290        # Get all the genomes and the related taxonomy information.
291        my @genomes = $self->GetAll(['Genome'], $filter, [], ['Genome(id)', 'Genome(taxonomy)']);
292        # Clear the counters.
293        my ($arch, $bact, $euk, $vir, $env, $unk) = (0, 0, 0, 0, 0, 0);
294        # Loop through, counting the domains.
295        for my $genome (@genomes) {
296            if    ($genome->[1] =~ /^archaea/i)  { ++$arch }
297            elsif ($genome->[1] =~ /^bacter/i)   { ++$bact }
298            elsif ($genome->[1] =~ /^eukar/i)    { ++$euk }
299            elsif ($genome->[1] =~ /^vir/i)      { ++$vir }
300            elsif ($genome->[1] =~ /^env/i)      { ++$env }
301            else  { ++$unk }
302        }
303        # Return the counts.
304        return ($arch, $bact, $euk, $vir, $env, $unk);
305    }
306    
307    =head3 ContigCount
308    
309    C<< my $count = $sprout->ContigCount($genomeID); >>
310    
311    Return the number of contigs for the specified genome ID.
312    
313    =over 4
314    
315    =item genomeID
316    
317    ID of the genome whose contig count is desired.
318    
319    =item RETURN
320    
321    Returns the number of contigs for the specified genome.
322    
323    =back
324    
325    =cut
326    
327    sub ContigCount {
328        # Get the parameters.
329        my ($self, $genomeID) = @_;
330        # Get the contig count.
331        my $retVal = $self->GetCount(['Contig', 'HasContig'], "HasContig(from-link) = ?", [$genomeID]);
332        # Return the result.
333        return $retVal;
334    }
335    
336    =head3 GeneMenu
337    
338    C<< my $selectHtml = $sprout->GeneMenu(\%attributes, $filterString, \@params); >>
339    
340    Return an HTML select menu of genomes. Each genome will be an option in the menu,
341    and will be displayed by name with the ID and a contig count attached. The selection
342    value will be the genome ID. The genomes will be sorted by genus/species name.
343    
344    =over 4
345    
346    =item attributes
347    
348    Reference to a hash mapping attributes to values for the SELECT tag generated.
349    
350    =item filterString
351    
352    A filter string for use in selecting the genomes. The filter string must conform
353    to the rules for the C<< ERDB->Get >> method.
354    
355    =item params
356    
357    Reference to a list of values to be substituted in for the parameter marks in
358    the filter string.
359    
360    =item RETURN
361    
362    Returns an HTML select menu with the specified genomes as selectable options.
363    
364    =back
365    
366    =cut
367    
368    sub GeneMenu {
369        # Get the parameters.
370        my ($self, $attributes, $filterString, $params) = @_;
371        # Start the menu.
372        my $retVal = "<select " .
373            join(" ", map { "$_=\"$attributes->{$_}\"" } keys %{$attributes}) .
374            ">\n";
375        # Get the genomes.
376        my @genomes = $self->GetAll(['Genome'], $filterString, $params, ['Genome(id)',
377                                                                         'Genome(genus)',
378                                                                         'Genome(species)',
379                                                                         'Genome(unique-characterization)']);
380        # Sort them by name.
381        my @sorted = sort { lc("$a->[1] $a->[2]") cmp lc("$b->[1] $b->[2]") } @genomes;
382        # Loop through the genomes, creating the option tags.
383        for my $genomeData (@sorted) {
384            # Get the data for this genome.
385            my ($genomeID, $genus, $species, $strain) = @{$genomeData};
386            # Get the contig count.
387            my $count = $self->ContigCount($genomeID);
388            my $counting = ($count == 1 ? "contig" : "contigs");
389            # Build the option tag.
390            $retVal .= "<option value=\"$genomeID\">$genus $species $strain ($genomeID) [$count $counting]</option>\n";
391            Trace("Option tag built for $genomeID: $genus $species $strain.") if T(3);
392        }
393        # Close the SELECT tag.
394        $retVal .= "</select>\n";
395        # Return the result.
396        return $retVal;
397    }
398  =head3 Build  =head3 Build
399    
400  C<< $sprout->Build(); >>  C<< $sprout->Build(); >>
# Line 460  Line 409 
409      # Get the parameters.      # Get the parameters.
410      my ($self) = @_;      my ($self) = @_;
411      # Create the tables.      # Create the tables.
412      $self->{_erdb}->CreateTables;      $self->CreateTables();
413  }  }
414    
415  =head3 Genomes  =head3 Genomes
# Line 610  Line 559 
559          if ($prevContig eq $contigID && $dir eq $prevDir) {          if ($prevContig eq $contigID && $dir eq $prevDir) {
560              # Here the new segment is in the same direction on the same contig. Insure the              # Here the new segment is in the same direction on the same contig. Insure the
561              # new segment's beginning is next to the old segment's end.              # new segment's beginning is next to the old segment's end.
562              if (($dir eq "-" && $beg == $prevBeg - $prevLen) ||              if ($dir eq "-" && $beg + $len == $prevBeg) {
563                  ($dir eq "+" && $beg == $prevBeg + $prevLen)) {                  # Here we're merging two backward blocks, so we keep the new begin point
564                  # Here we need to merge two segments. Adjust the beginning and length values                  # and adjust the length.
565                  # to include both segments.                  $len += $prevLen;
566                    # Pop the old segment off. The new one will replace it later.
567                    pop @retVal;
568                } elsif ($dir eq "+" && $beg == $prevBeg + $prevLen) {
569                    # Here we need to merge two forward blocks. Adjust the beginning and
570                    # length values to include both segments.
571                  $beg = $prevBeg;                  $beg = $prevBeg;
572                  $len += $prevLen;                  $len += $prevLen;
573                  # Pop the old segment off. The new one will replace it later.                  # Pop the old segment off. The new one will replace it later.
# Line 622  Line 576 
576          }          }
577          # Remember this specifier for the adjacent-segment test the next time through.          # Remember this specifier for the adjacent-segment test the next time through.
578          ($prevContig, $prevBeg, $prevDir, $prevLen) = ($contigID, $beg, $dir, $len);          ($prevContig, $prevBeg, $prevDir, $prevLen) = ($contigID, $beg, $dir, $len);
579            # Compute the initial base pair.
580            my $start = ($dir eq "+" ? $beg : $beg + $len - 1);
581          # Add the specifier to the list.          # Add the specifier to the list.
582          push @retVal, "${contigID}_$beg$dir$len";          push @retVal, "${contigID}_$start$dir$len";
583      }      }
584      # Return the list in the format indicated by the context.      # Return the list in the format indicated by the context.
585      return (wantarray ? @retVal : join(',', @retVal));      return (wantarray ? @retVal : join(',', @retVal));
# Line 657  Line 613 
613      shift if UNIVERSAL::isa($_[0],__PACKAGE__);      shift if UNIVERSAL::isa($_[0],__PACKAGE__);
614      my ($location) = @_;      my ($location) = @_;
615      # Parse it into segments.      # Parse it into segments.
616      $location =~ /^(.*)_(\d*)([+-_])(\d*)$/;      $location =~ /^(.+)_(\d+)([+\-_])(\d+)$/;
617      my ($contigID, $start, $dir, $len) = ($1, $2, $3, $4);      my ($contigID, $start, $dir, $len) = ($1, $2, $3, $4);
618      # If the direction is an underscore, convert it to a + or -.      # If the direction is an underscore, convert it to a + or -.
619      if ($dir eq "_") {      if ($dir eq "_") {
# Line 733  Line 689 
689  should be of the form returned by L</featureLocation> when in a list context. In other words,  should be of the form returned by L</featureLocation> when in a list context. In other words,
690  each location is of the form I<contigID>C<_>I<begin>I<dir>I<end>.  each location is of the form I<contigID>C<_>I<begin>I<dir>I<end>.
691    
692    For example, the following would return the DNA sequence for contig C<83333.1:NC_000913>
693    between positions 1401 and 1532, inclusive.
694    
695        my $sequence = $sprout->DNASeq('83333.1:NC_000913_1401_1532');
696    
697  =over 4  =over 4
698    
699  =item locationList  =item locationList
700    
701  List of location specifiers, each in the form I<contigID>C<_>I<begin>I<dir>I<end> (see  List of location specifiers, each in the form I<contigID>C<_>I<begin>I<dir>I<len> or
702  L</FeatureLocation> for more about this format).  I<contigID>C<_>I<begin>C<_>I<end> (see L</FeatureLocation> for more about this format).
703    
704  =item RETURN  =item RETURN
705    
# Line 765  Line 726 
726          # the start point is the ending. Note that in the latter case we must reverse the DNA string          # the start point is the ending. Note that in the latter case we must reverse the DNA string
727          # before putting it in the return value.          # before putting it in the return value.
728          my ($start, $stop);          my ($start, $stop);
729          Trace("Parsed location is $beg$dir$len.") if T(SDNA => 4);          Trace("Parse of \"$location\" is $beg$dir$len.") if T(SDNA => 4);
730          if ($dir eq "+") {          if ($dir eq "+") {
731              $start = $beg;              $start = $beg;
732              $stop = $beg + $len - 1;              $stop = $beg + $len - 1;
# Line 788  Line 749 
749              Trace("Sequence is from $startPosition to $stopPosition.") if T(SDNA => 4);              Trace("Sequence is from $startPosition to $stopPosition.") if T(SDNA => 4);
750              # Figure out the start point and length of the relevant section.              # Figure out the start point and length of the relevant section.
751              my $pos1 = ($start < $startPosition ? 0 : $start - $startPosition);              my $pos1 = ($start < $startPosition ? 0 : $start - $startPosition);
752              my $len1 = ($stopPosition <= $stop ? $stopPosition : $stop) - $startPosition - $pos1;              my $len1 = ($stopPosition < $stop ? $stopPosition : $stop) + 1 - $startPosition - $pos1;
753              Trace("Position is $pos1 for length $len1.") if T(SDNA => 4);              Trace("Position is $pos1 for length $len1.") if T(SDNA => 4);
754              # Add the relevant data to the location data.              # Add the relevant data to the location data.
755              $locationDNA .= substr($sequenceData, $pos1, $len1);              $locationDNA .= substr($sequenceData, $pos1, $len1);
# Line 834  Line 795 
795      return @retVal;      return @retVal;
796  }  }
797    
798    =head3 GenomeLength
799    
800    C<< my $length = $sprout->GenomeLength($genomeID); >>
801    
802    Return the length of the specified genome in base pairs.
803    
804    =over 4
805    
806    =item genomeID
807    
808    ID of the genome whose base pair count is desired.
809    
810    =item RETURN
811    
812    Returns the number of base pairs in all the contigs of the specified
813    genome.
814    
815    =back
816    
817    =cut
818    
819    sub GenomeLength {
820        # Get the parameters.
821        my ($self, $genomeID) = @_;
822        # Declare the return variable.
823        my $retVal = 0;
824        # Get the genome's contig sequence lengths.
825        my @lens = $self->GetFlat(['HasContig', 'IsMadeUpOf'], 'HasContig(from-link) = ?',
826                           [$genomeID], 'IsMadeUpOf(len)');
827        # Sum the lengths.
828        map { $retVal += $_ } @lens;
829        # Return the result.
830        return $retVal;
831    }
832    
833    =head3 FeatureCount
834    
835    C<< my $count = $sprout->FeatureCount($genomeID, $type); >>
836    
837    Return the number of features of the specified type in the specified genome.
838    
839    =over 4
840    
841    =item genomeID
842    
843    ID of the genome whose feature count is desired.
844    
845    =item type
846    
847    Type of feature to count (eg. C<peg>, C<rna>, etc.).
848    
849    =item RETURN
850    
851    Returns the number of features of the specified type for the specified genome.
852    
853    =back
854    
855    =cut
856    
857    sub FeatureCount {
858        # Get the parameters.
859        my ($self, $genomeID, $type) = @_;
860        # Compute the count.
861        my $retVal = $self->GetCount(['HasFeature', 'Feature'],
862                                    "HasFeature(from-link) = ? AND Feature(feature-type) = ?",
863                                    [$genomeID, $type]);
864        # Return the result.
865        return $retVal;
866    }
867    
868    =head3 GenomeAssignments
869    
870    C<< my $fidHash = $sprout->GenomeAssignments($genomeID); >>
871    
872    Return a list of a genome's assigned features. The return hash will contain each
873    assigned feature of the genome mapped to the text of its most recent functional
874    assignment.
875    
876    =over 4
877    
878    =item genomeID
879    
880    ID of the genome whose functional assignments are desired.
881    
882    =item RETURN
883    
884    Returns a reference to a hash which maps each feature to its most recent
885    functional assignment.
886    
887    =back
888    
889    =cut
890    
891    sub GenomeAssignments {
892        # Get the parameters.
893        my ($self, $genomeID) = @_;
894        # Declare the return variable.
895        my $retVal = {};
896        # Query the genome's features and annotations. We'll put the oldest annotations
897        # first so that the last assignment to go into the hash will be the correct one.
898        my $query = $self->Get(['HasFeature', 'IsTargetOfAnnotation', 'Annotation'],
899                               "HasFeature(from-link) = ? ORDER BY Annotation(time)",
900                               [$genomeID]);
901        # Loop through the annotations.
902        while (my $data = $query->Fetch) {
903            # Get the feature ID and annotation text.
904            my ($fid, $annotation) = $data->Values(['HasFeature(to-link)',
905                                                    'Annotation(annotation)']);
906            # Check to see if this is an assignment. Note that the user really
907            # doesn't matter to us, other than we use it to determine whether or
908            # not this is an assignment.
909            my ($user, $assignment) = _ParseAssignment('fig', $annotation);
910            if ($user) {
911                # Here it's an assignment. We put it in the return hash, overwriting
912                # any older assignment that might be present.
913                $retVal->{$fid} = $assignment;
914            }
915        }
916        # Return the result.
917        return $retVal;
918    }
919    
920  =head3 ContigLength  =head3 ContigLength
921    
922  C<< my $length = $sprout->ContigLength($contigID); >>  C<< my $length = $sprout->ContigLength($contigID); >>
# Line 867  Line 950 
950      # Set it from the sequence data, if any.      # Set it from the sequence data, if any.
951      if ($sequence) {      if ($sequence) {
952          my ($start, $len) = $sequence->Values(['IsMadeUpOf(start-position)', 'IsMadeUpOf(len)']);          my ($start, $len) = $sequence->Values(['IsMadeUpOf(start-position)', 'IsMadeUpOf(len)']);
953          $retVal = $start + $len;          $retVal = $start + $len - 1;
954        }
955        # Return the result.
956        return $retVal;
957    }
958    
959    =head3 ClusterPEGs
960    
961    C<< my $clusteredList = $sprout->ClusterPEGs($sub, \@pegs); >>
962    
963    Cluster the PEGs in a list according to the cluster coding scheme of the specified
964    subsystem. In order for this to work properly, the subsystem object must have
965    been used recently to retrieve the PEGs using the B<get_pegs_from_cell> method.
966    This causes the cluster numbers to be pulled into the subsystem's color hash.
967    If a PEG is not found in the color hash, it will not appear in the output
968    sequence.
969    
970    =over 4
971    
972    =item sub
973    
974    Sprout subsystem object for the relevant subsystem, from the L</get_subsystem>
975    method.
976    
977    =item pegs
978    
979    Reference to the list of PEGs to be clustered.
980    
981    =item RETURN
982    
983    Returns a list of the PEGs, grouped into smaller lists by cluster number.
984    
985    =back
986    
987    =cut
988    #: Return Type $@@;
989    sub ClusterPEGs {
990        # Get the parameters.
991        my ($self, $sub, $pegs) = @_;
992        # Declare the return variable.
993        my $retVal = [];
994        # Loop through the PEGs, creating arrays for each cluster.
995        for my $pegID (@{$pegs}) {
996            my $clusterNumber = $sub->get_cluster_number($pegID);
997            # Only proceed if the PEG is in a cluster.
998            if ($clusterNumber >= 0) {
999                # Push this PEG onto the sub-list for the specified cluster number.
1000                push @{$retVal->[$clusterNumber]}, $pegID;
1001            }
1002      }      }
1003      # Return the result.      # Return the result.
1004      return $retVal;      return $retVal;
# Line 1017  Line 1148 
1148    
1149  =head3 FeatureAnnotations  =head3 FeatureAnnotations
1150    
1151  C<< my @descriptors = $sprout->FeatureAnnotations($featureID); >>  C<< my @descriptors = $sprout->FeatureAnnotations($featureID, $rawFlag); >>
1152    
1153  Return the annotations of a feature.  Return the annotations of a feature.
1154    
# Line 1027  Line 1158 
1158    
1159  ID of the feature whose annotations are desired.  ID of the feature whose annotations are desired.
1160    
1161    =item rawFlag
1162    
1163    If TRUE, the annotation timestamps will be returned in raw form; otherwise, they
1164    will be returned in human-readable form.
1165    
1166  =item RETURN  =item RETURN
1167    
1168  Returns a list of annotation descriptors. Each descriptor is a hash with the following fields.  Returns a list of annotation descriptors. Each descriptor is a hash with the following fields.
1169    
1170  * B<featureID> ID of the relevant feature.  * B<featureID> ID of the relevant feature.
1171    
1172  * B<timeStamp> time the annotation was made, in user-friendly format.  * B<timeStamp> time the annotation was made.
1173    
1174  * B<user> ID of the user who made the annotation  * B<user> ID of the user who made the annotation
1175    
# Line 1045  Line 1181 
1181  #: Return Type @%;  #: Return Type @%;
1182  sub FeatureAnnotations {  sub FeatureAnnotations {
1183      # Get the parameters.      # Get the parameters.
1184      my ($self, $featureID) = @_;      my ($self, $featureID, $rawFlag) = @_;
1185      # Create a query to get the feature's annotations and the associated users.      # Create a query to get the feature's annotations and the associated users.
1186      my $query = $self->Get(['IsTargetOfAnnotation', 'Annotation', 'MadeAnnotation'],      my $query = $self->Get(['IsTargetOfAnnotation', 'Annotation', 'MadeAnnotation'],
1187                             "IsTargetOfAnnotation(from-link) = ?", [$featureID]);                             "IsTargetOfAnnotation(from-link) = ?", [$featureID]);
# Line 1058  Line 1194 
1194              $annotation->Values(['IsTargetOfAnnotation(from-link)',              $annotation->Values(['IsTargetOfAnnotation(from-link)',
1195                                   'Annotation(time)', 'MadeAnnotation(from-link)',                                   'Annotation(time)', 'MadeAnnotation(from-link)',
1196                                   'Annotation(annotation)']);                                   'Annotation(annotation)']);
1197            # Convert the time, if necessary.
1198            if (! $rawFlag) {
1199                $timeStamp = FriendlyTimestamp($timeStamp);
1200            }
1201          # Assemble them into a hash.          # Assemble them into a hash.
1202          my $annotationHash = { featureID => $featureID,          my $annotationHash = { featureID => $featureID,
1203                                 timeStamp => FriendlyTimestamp($timeStamp),                                 timeStamp => $timeStamp,
1204                                 user => $user, text => $text };                                 user => $user, text => $text };
1205          # Add it to the return list.          # Add it to the return list.
1206          push @retVal, $annotationHash;          push @retVal, $annotationHash;
# Line 1089  Line 1229 
1229    
1230  =item RETURN  =item RETURN
1231    
1232  Returns a hash mapping the functional assignment IDs to user IDs.  Returns a hash mapping the user IDs to functional assignment IDs.
1233    
1234  =back  =back
1235    
# Line 1099  Line 1239 
1239      # Get the parameters.      # Get the parameters.
1240      my ($self, $featureID) = @_;      my ($self, $featureID) = @_;
1241      # Get all of the feature's annotations.      # Get all of the feature's annotations.
1242      my @query = $self->GetAll(['IsTargetOfAnnotation', 'Annotation'],      my @query = $self->GetAll(['IsTargetOfAnnotation', 'Annotation', 'MadeAnnotation'],
1243                              "IsTargetOfAnnotation(from-link) = ?",                              "IsTargetOfAnnotation(from-link) = ?",
1244                              [$featureID], ['Annotation(time)', 'Annotation(annotation)']);                              [$featureID], ['Annotation(time)', 'Annotation(annotation)',
1245                                               'MadeAnnotation(from-link)']);
1246      # Declare the return hash.      # Declare the return hash.
1247      my %retVal;      my %retVal;
     # Declare a hash for insuring we only make one assignment per user.  
     my %timeHash = ();  
1248      # Now we sort the assignments by timestamp in reverse.      # Now we sort the assignments by timestamp in reverse.
1249      my @sortedQuery = sort { -($a->[0] <=> $b->[0]) } @query;      my @sortedQuery = sort { -($a->[0] <=> $b->[0]) } @query;
1250      # Loop until we run out of annotations.      # Loop until we run out of annotations.
1251      for my $annotation (@sortedQuery) {      for my $annotation (@sortedQuery) {
1252          # Get the annotation fields.          # Get the annotation fields.
1253          my ($timeStamp, $text) = @{$annotation};          my ($timeStamp, $text, $user) = @{$annotation};
1254          # Check to see if this is a functional assignment.          # Check to see if this is a functional assignment.
1255          my ($user, $function) = _ParseAssignment($text);          my ($actualUser, $function) = _ParseAssignment($user, $text);
1256          if ($user && ! exists $timeHash{$user}) {          if ($actualUser && ! exists $retVal{$actualUser}) {
1257              # Here it is a functional assignment and there has been no              # Here it is a functional assignment and there has been no
1258              # previous assignment for this user, so we stuff it in the              # previous assignment for this user, so we stuff it in the
1259              # return hash.              # return hash.
1260              $retVal{$function} = $user;              $retVal{$actualUser} = $function;
             # Insure we don't assign to this user again.  
             $timeHash{$user} = 1;  
1261          }          }
1262      }      }
1263      # Return the hash of assignments found.      # Return the hash of assignments found.
# Line 1136  Line 1273 
1273  The functional assignment is handled differently depending on the type of feature. If  The functional assignment is handled differently depending on the type of feature. If
1274  the feature is identified by a FIG ID (begins with the string C<fig|>), then a functional  the feature is identified by a FIG ID (begins with the string C<fig|>), then a functional
1275  assignment is a type of annotation. The format of an assignment is described in  assignment is a type of annotation. The format of an assignment is described in
1276  L</ParseLocation>. Its worth noting that we cannot filter on the content of the  L</ParseAssignment>. Its worth noting that we cannot filter on the content of the
1277  annotation itself because it's a text field; however, this is not a big problem because  annotation itself because it's a text field; however, this is not a big problem because
1278  most features only have a small number of annotations.  most features only have a small number of annotations.
1279    
# Line 1198  Line 1335 
1335              }              }
1336          }          }
1337          # Build a query for all of the feature's annotations, sorted by date.          # Build a query for all of the feature's annotations, sorted by date.
1338          my $query = $self->Get(['IsTargetOfAnnotation', 'Annotation'],          my $query = $self->Get(['IsTargetOfAnnotation', 'Annotation', 'MadeAnnotation'],
1339                                 "IsTargetOfAnnotation(from-link) = ? ORDER BY Annotation(time) DESC",                                 "IsTargetOfAnnotation(from-link) = ? ORDER BY Annotation(time) DESC",
1340                                 [$featureID]);                                 [$featureID]);
1341          my $timeSelected = 0;          my $timeSelected = 0;
1342          # Loop until we run out of annotations.          # Loop until we run out of annotations.
1343          while (my $annotation = $query->Fetch()) {          while (my $annotation = $query->Fetch()) {
1344              # Get the annotation text.              # Get the annotation text.
1345              my ($text, $time) = $annotation->Values(['Annotation(annotation)','Annotation(time)']);              my ($text, $time, $user) = $annotation->Values(['Annotation(annotation)',
1346                                                         'Annotation(time)', 'MadeAnnotation(from-link)']);
1347              # Check to see if this is a functional assignment for a trusted user.              # Check to see if this is a functional assignment for a trusted user.
1348              my ($user, $function) = _ParseAssignment($text);              my ($actualUser, $function) = _ParseAssignment($user, $text);
1349              if ($user) {              Trace("Assignment user is $actualUser, text is $function.") if T(4);
1350                if ($actualUser) {
1351                  # Here it is a functional assignment. Check the time and the user                  # Here it is a functional assignment. Check the time and the user
1352                  # name. The time must be recent and the user must be trusted.                  # name. The time must be recent and the user must be trusted.
1353                  if ((exists $trusteeTable{$user}) && ($time > $timeSelected)) {                  if ((exists $trusteeTable{$actualUser}) && ($time > $timeSelected)) {
1354                      $retVal = $function;                      $retVal = $function;
1355                      $timeSelected = $time;                      $timeSelected = $time;
1356                  }                  }
# Line 1227  Line 1366 
1366      return $retVal;      return $retVal;
1367  }  }
1368    
1369    =head3 FunctionsOf
1370    
1371    C<< my @functionList = $sprout->FunctionOf($featureID, $userID); >>
1372    
1373    Return the functional assignments of a particular feature.
1374    
1375    The functional assignment is handled differently depending on the type of feature. If
1376    the feature is identified by a FIG ID (begins with the string C<fig|>), then a functional
1377    assignment is a type of annotation. The format of an assignment is described in
1378    L</ParseAssignment>. Its worth noting that we cannot filter on the content of the
1379    annotation itself because it's a text field; however, this is not a big problem because
1380    most features only have a small number of annotations.
1381    
1382    If the feature is B<not> identified by a FIG ID, then the functional assignment
1383    information is taken from the B<ExternalAliasFunc> table. If the table does
1384    not contain an entry for the feature, an empty list is returned.
1385    
1386    =over 4
1387    
1388    =item featureID
1389    
1390    ID of the feature whose functional assignments are desired.
1391    
1392    =item RETURN
1393    
1394    Returns a list of 2-tuples, each consisting of a user ID and the text of an assignment by
1395    that user.
1396    
1397    =back
1398    
1399    =cut
1400    #: Return Type @@;
1401    sub FunctionsOf {
1402        # Get the parameters.
1403        my ($self, $featureID) = @_;
1404        # Declare the return value.
1405        my @retVal = ();
1406        # Determine the ID type.
1407        if ($featureID =~ m/^fig\|/) {
1408            # Here we have a FIG feature ID. We must build the list of trusted
1409            # users.
1410            my %trusteeTable = ();
1411            # Build a query for all of the feature's annotations, sorted by date.
1412            my $query = $self->Get(['IsTargetOfAnnotation', 'Annotation', 'MadeAnnotation'],
1413                                   "IsTargetOfAnnotation(from-link) = ? ORDER BY Annotation(time) DESC",
1414                                   [$featureID]);
1415            my $timeSelected = 0;
1416            # Loop until we run out of annotations.
1417            while (my $annotation = $query->Fetch()) {
1418                # Get the annotation text.
1419                my ($text, $time, $user) = $annotation->Values(['Annotation(annotation)',
1420                                                                'Annotation(time)',
1421                                                                'MadeAnnotation(user)']);
1422                # Check to see if this is a functional assignment for a trusted user.
1423                my ($actualUser, $function) = _ParseAssignment($user, $text);
1424                if ($actualUser) {
1425                    # Here it is a functional assignment.
1426                    push @retVal, [$actualUser, $function];
1427                }
1428            }
1429        } else {
1430            # Here we have a non-FIG feature ID. In this case the user ID does not
1431            # matter. We simply get the information from the External Alias Function
1432            # table.
1433            my @assignments = $self->GetEntityValues('ExternalAliasFunc', $featureID,
1434                                                     ['ExternalAliasFunc(func)']);
1435            push @retVal, map { ['master', $_] } @assignments;
1436        }
1437        # Return the assignments found.
1438        return @retVal;
1439    }
1440    
1441  =head3 BBHList  =head3 BBHList
1442    
1443  C<< my $bbhHash = $sprout->BBHList($genomeID, \@featureList); >>  C<< my $bbhHash = $sprout->BBHList($genomeID, \@featureList); >>
# Line 1264  Line 1475 
1475          my $query = $self->Get(['IsBidirectionalBestHitOf'],          my $query = $self->Get(['IsBidirectionalBestHitOf'],
1476                                 "IsBidirectionalBestHitOf(from-link) = ? AND IsBidirectionalBestHitOf(genome) = ?",                                 "IsBidirectionalBestHitOf(from-link) = ? AND IsBidirectionalBestHitOf(genome) = ?",
1477                                 [$featureID, $genomeID]);                                 [$featureID, $genomeID]);
1478          # Look for the best hit.          # Peel off the BBHs found.
1479          my $bbh = $query->Fetch;          my @found = ();
1480          if ($bbh) {          while (my $bbh = $query->Fetch) {
1481              my ($targetFeature) = $bbh->Value('IsBidirectionalBestHitOf(to-link)');              push @found, $bbh->Value('IsBidirectionalBestHitOf(to-link)');
             $retVal{$featureID} = $targetFeature;  
1482          }          }
1483            $retVal{$featureID} = \@found;
1484      }      }
1485      # Return the mapping.      # Return the mapping.
1486      return \%retVal;      return \%retVal;
# Line 1347  Line 1558 
1558      my $genomeData = $self->GetEntity('Genome', $genomeID);      my $genomeData = $self->GetEntity('Genome', $genomeID);
1559      if ($genomeData) {      if ($genomeData) {
1560          # The genome exists, so get the completeness flag.          # The genome exists, so get the completeness flag.
1561          ($retVal) = $genomeData->Value('complete');          ($retVal) = $genomeData->Value('Genome(complete)');
1562      }      }
1563      # Return the result.      # Return the result.
1564      return $retVal;      return $retVal;
# Line 1387  Line 1598 
1598    
1599  C<< my $genomeID = $sprout->GenomeOf($featureID); >>  C<< my $genomeID = $sprout->GenomeOf($featureID); >>
1600    
1601  Return the genome that contains a specified feature.  Return the genome that contains a specified feature or contig.
1602    
1603  =over 4  =over 4
1604    
1605  =item featureID  =item featureID
1606    
1607  ID of the feature whose genome is desired.  ID of the feature or contig whose genome is desired.
1608    
1609  =item RETURN  =item RETURN
1610    
1611  Returns the ID of the genome for the specified feature. If the feature is not found, returns  Returns the ID of the genome for the specified feature or contig. If the feature or contig is not
1612  an undefined value.  found, returns an undefined value.
1613    
1614  =back  =back
1615    
# Line 1407  Line 1618 
1618  sub GenomeOf {  sub GenomeOf {
1619      # Get the parameters.      # Get the parameters.
1620      my ($self, $featureID) = @_;      my ($self, $featureID) = @_;
1621      # Create a query to find the genome associated with the feature.      # Create a query to find the genome associated with the incoming ID.
1622      my $query = $self->Get(['IsLocatedIn', 'HasContig'], "IsLocatedIn(from-link) = ?", [$featureID]);      my $query = $self->Get(['IsLocatedIn', 'HasContig'], "IsLocatedIn(from-link) = ? OR HasContig(to-link) = ?",
1623                               [$featureID, $featureID]);
1624      # Declare the return value.      # Declare the return value.
1625      my $retVal;      my $retVal;
1626      # Get the genome ID.      # Get the genome ID.
# Line 1455  Line 1667 
1667          # Get the ID and score of the coupling.          # Get the ID and score of the coupling.
1668          my ($couplingID, $score) = $clustering->Values(['Coupling(id)',          my ($couplingID, $score) = $clustering->Values(['Coupling(id)',
1669                                                          'Coupling(score)']);                                                          'Coupling(score)']);
1670          # The coupling ID contains the two feature IDs separated by a space. We use          # Get the other feature that participates in the coupling.
1671          # this information to find the ID of the other feature.          my ($otherFeatureID) = $self->GetFlat(['ParticipatesInCoupling'],
1672          my ($fid1, $fid2) = split / /, $couplingID;                                             "ParticipatesInCoupling(to-link) = ? AND ParticipatesInCoupling(from-link) <> ?",
1673          my $otherFeatureID = ($featureID eq $fid1 ? $fid2 : $fid1);                                             [$couplingID, $featureID], 'ParticipatesInCoupling(from-link)');
1674          # Attach the other feature's score to its ID.          # Attach the other feature's score to its ID.
1675          $retVal{$otherFeatureID} = $score;          $retVal{$otherFeatureID} = $score;
1676          $found = 1;          $found = 1;
# Line 1650  Line 1862 
1862      return join " ", sort @_;      return join " ", sort @_;
1863  }  }
1864    
 =head3 GetEntityTypes  
   
 C<< my @entityList = $sprout->GetEntityTypes(); >>  
   
 Return the list of supported entity types.  
   
 =cut  
 #: Return Type @;  
 sub GetEntityTypes {  
     # Get the parameters.  
     my ($self) = @_;  
     # Get the underlying database object.  
     my $erdb = $self->{_erdb};  
     # Get its entity type list.  
     my @retVal = $erdb->GetEntityTypes();  
 }  
   
1865  =head3 ReadFasta  =head3 ReadFasta
1866    
1867  C<< my %sequenceData = Sprout::ReadFasta($fileName, $prefix); >>  C<< my %sequenceData = Sprout::ReadFasta($fileName, $prefix); >>
# Line 1812  Line 2007 
2007      # Get the data directory name.      # Get the data directory name.
2008      my $outputDirectory = $self->{_options}->{dataDir};      my $outputDirectory = $self->{_options}->{dataDir};
2009      # Dump the relations.      # Dump the relations.
2010      $self->{_erdb}->DumpRelations($outputDirectory);      $self->DumpRelations($outputDirectory);
2011  }  }
2012    
2013  =head3 XMLFileName  =head3 XMLFileName
# Line 1864  Line 2059 
2059      # Get the parameters.      # Get the parameters.
2060      my ($self, $objectType, $fieldHash) = @_;      my ($self, $objectType, $fieldHash) = @_;
2061      # Call the underlying method.      # Call the underlying method.
2062      $self->{_erdb}->InsertObject($objectType, $fieldHash);      $self->InsertObject($objectType, $fieldHash);
2063  }  }
2064    
2065  =head3 Annotate  =head3 Annotate
# Line 2545  Line 2740 
2740                                      ['HasSSCell(from-link)', 'IsRoleOf(from-link)']);                                      ['HasSSCell(from-link)', 'IsRoleOf(from-link)']);
2741      # Create the return value.      # Create the return value.
2742      my %retVal = ();      my %retVal = ();
2743        # Build a hash to weed out duplicates. Sometimes the same PEG and role appears
2744        # in two spreadsheet cells.
2745        my %dupHash = ();
2746      # Loop through the results, adding them to the hash.      # Loop through the results, adding them to the hash.
2747      for my $record (@subsystems) {      for my $record (@subsystems) {
2748            # Get this subsystem and role.
2749          my ($subsys, $role) = @{$record};          my ($subsys, $role) = @{$record};
2750          if (exists $retVal{$subsys}) {          # Insure it's the first time for both.
2751            my $dupKey = "$subsys\n$role";
2752            if (! exists $dupHash{"$subsys\n$role"}) {
2753                $dupHash{$dupKey} = 1;
2754              push @{$retVal{$subsys}}, $role;              push @{$retVal{$subsys}}, $role;
         } else {  
             $retVal{$subsys} = [$role];  
2755          }          }
2756      }      }
2757      # Return the hash.      # Return the hash.
# Line 2590  Line 2790 
2790      return @retVal;      return @retVal;
2791  }  }
2792    
2793    
2794    
2795  =head3 RelatedFeatures  =head3 RelatedFeatures
2796    
2797  C<< my @relatedList = $sprout->RelatedFeatures($featureID, $function, $userID); >>  C<< my @relatedList = $sprout->RelatedFeatures($featureID, $function, $userID); >>
# Line 2691  Line 2893 
2893      return @retVal;      return @retVal;
2894  }  }
2895    
 =head3 GetAll  
   
 C<< my @list = $sprout->GetAll(\@objectNames, $filterClause, \@parameters, \@fields, $count); >>  
   
 Return a list of values taken from the objects returned by a query. The first three  
 parameters correspond to the parameters of the L</Get> method. The final parameter is  
 a list of the fields desired from each record found by the query. The field name  
 syntax is the standard syntax used for fields in the B<ERDB> system--  
 B<I<objectName>(I<fieldName>)>-- where I<objectName> is the name of the relevant entity  
 or relationship and I<fieldName> is the name of the field.  
   
 The list returned will be a list of lists. Each element of the list will contain  
 the values returned for the fields specified in the fourth parameter. If one of the  
 fields specified returns multiple values, they are flattened in with the rest. For  
 example, the following call will return a list of the features in a particular  
 spreadsheet cell, and each feature will be represented by a list containing the  
 feature ID followed by all of its aliases.  
   
 C<< $query = $sprout->Get(['ContainsFeature', 'Feature'], "ContainsFeature(from-link) = ?", [$ssCellID], ['Feature(id)', 'Feature(alias)']); >>  
   
 =over 4  
   
 =item objectNames  
   
 List containing the names of the entity and relationship objects to be retrieved.  
   
 =item filterClause  
   
 WHERE/ORDER BY clause (without the WHERE) to be used to filter and sort the query. The WHERE clause can  
 be parameterized with parameter markers (C<?>). Each field used must be specified in the standard form  
 B<I<objectName>(I<fieldName>)>. Any parameters specified in the filter clause should be added to the  
 parameter list as additional parameters. The fields in a filter clause can come from primary  
 entity relations, relationship relations, or secondary entity relations; however, all of the  
 entities and relationships involved must be included in the list of object names.  
   
 =item parameterList  
   
 List of the parameters to be substituted in for the parameters marks in the filter clause.  
   
 =item fields  
   
 List of the fields to be returned in each element of the list returned.  
   
 =item count  
   
 Maximum number of records to return. If omitted or 0, all available records will be returned.  
   
 =item RETURN  
   
 Returns a list of list references. Each element of the return list contains the values for the  
 fields specified in the B<fields> parameter.  
   
 =back  
   
 =cut  
 #: Return Type @@;  
 sub GetAll {  
     # Get the parameters.  
     my ($self, $objectNames, $filterClause, $parameterList, $fields, $count) = @_;  
     # Call the ERDB method.  
     my @retVal = $self->{_erdb}->GetAll($objectNames, $filterClause, $parameterList,  
                                         $fields, $count);  
     # Return the resulting list.  
     return @retVal;  
 }  
   
 =head3 GetFlat  
   
 C<< my @list = $sprout->GetFlat(\@objectNames, $filterClause, $parameterList, $field); >>  
   
 This is a variation of L</GetAll> that asks for only a single field per record and  
 returns a single flattened list.  
   
 =over 4  
   
 =item objectNames  
   
 List containing the names of the entity and relationship objects to be retrieved.  
   
 =item filterClause  
   
 WHERE/ORDER BY clause (without the WHERE) to be used to filter and sort the query. The WHERE clause can  
 be parameterized with parameter markers (C<?>). Each field used must be specified in the standard form  
 B<I<objectName>(I<fieldName>)>. Any parameters specified in the filter clause should be added to the  
 parameter list as additional parameters. The fields in a filter clause can come from primary  
 entity relations, relationship relations, or secondary entity relations; however, all of the  
 entities and relationships involved must be included in the list of object names.  
   
 =item parameterList  
   
 List of the parameters to be substituted in for the parameters marks in the filter clause.  
   
 =item field  
   
 Name of the field to be used to get the elements of the list returned.  
   
 =item RETURN  
   
 Returns a list of values.  
   
 =back  
   
 =cut  
 #: Return Type @;  
 sub GetFlat {  
     # Get the parameters.  
     my ($self, $objectNames, $filterClause, $parameterList, $field) = @_;  
     # Construct the query.  
     my $query = $self->Get($objectNames, $filterClause, $parameterList);  
     # Create the result list.  
     my @retVal = ();  
     # Loop through the records, adding the field values found to the result list.  
     while (my $row = $query->Fetch()) {  
         push @retVal, $row->Value($field);  
     }  
     # Return the list created.  
     return @retVal;  
 }  
   
2896  =head3 Protein  =head3 Protein
2897    
2898  C<< my $protein = Sprout::Protein($sequence, $table); >>  C<< my $protein = Sprout::Protein($sequence, $table); >>
# Line 2911  Line 2994 
2994      # Create the return list, priming it with the name of the data directory.      # Create the return list, priming it with the name of the data directory.
2995      my @retVal = ($self->{_options}->{dataDir});      my @retVal = ($self->{_options}->{dataDir});
2996      # Concatenate the table names.      # Concatenate the table names.
2997      push @retVal, $self->{_erdb}->GetTableNames();      push @retVal, $self->GetTableNames();
2998      # Return the result.      # Return the result.
2999      return @retVal;      return @retVal;
3000  }  }
3001    
3002  =head3 LowBBHs  =head3 LowBBHs
3003    
3004  C<< my %bbhMap = $sprout->GoodBBHs($featureID, $cutoff); >>  C<< my %bbhMap = $sprout->LowBBHs($featureID, $cutoff); >>
3005    
3006  Return the bidirectional best hits of a feature whose score is no greater than a  Return the bidirectional best hits of a feature whose score is no greater than a
3007  specified cutoff value. A higher cutoff value will allow inclusion of hits with  specified cutoff value. A higher cutoff value will allow inclusion of hits with
# Line 3081  Line 3164 
3164      return $retVal;      return $retVal;
3165  }  }
3166    
3167    =head3 DeleteGenome
3168    
3169    C<< my $stats = $sprout->DeleteGenome($genomeID, $testFlag); >>
3170    
3171    Delete a genome from the database.
3172    
3173    =over 4
3174    
3175    =item genomeID
3176    
3177    ID of the genome to delete
3178    
3179    =item testFlag
3180    
3181    If TRUE, then the DELETE statements will be traced, but no deletions will occur.
3182    
3183    =item RETURN
3184    
3185    Returns a statistics object describing the rows deleted.
3186    
3187    =back
3188    
3189    =cut
3190    #: Return Type $%;
3191    sub DeleteGenome {
3192        # Get the parameters.
3193        my ($self, $genomeID, $testFlag) = @_;
3194        # Perform the delete for the genome's features.
3195        my $retVal = $self->Delete('Feature', "fig|$genomeID.%", $testFlag);
3196        # Perform the delete for the primary genome data.
3197        my $stats = $self->Delete('Genome', $genomeID, $testFlag);
3198        $retVal->Accumulate($stats);
3199        # Return the result.
3200        return $retVal;
3201    }
3202    
3203  =head2 Internal Utility Methods  =head2 Internal Utility Methods
3204    
3205  =head3 ParseAssignment  =head3 ParseAssignment
# Line 3091  Line 3210 
3210    
3211  A functional assignment is always of the form  A functional assignment is always of the form
3212    
3213      I<XXXX>C<\nset >I<YYYY>C< function to\n>I<ZZZZZ>      C<set >I<YYYY>C< function to\n>I<ZZZZZ>
3214    
3215    where I<YYYY> is the B<user>, and I<ZZZZ> is the actual functional role. In most cases,
3216    the user and the assigning user (from MadeAnnotation) will be the same, but that is
3217    not always the case.
3218    
3219  where I<XXXX> is the B<assigning user>, I<YYYY> is the B<user>, and I<ZZZZ> is the  In addition, the functional role may contain extra data that is stripped, such as
3220  actual functional role. In most cases, the user and the assigning user will be the  terminating spaces or a comment separated from the rest of the text by a tab.
 same, but that is not always the case.  
3221    
3222  This is a static method.  This is a static method.
3223    
3224  =over 4  =over 4
3225    
3226    =item user
3227    
3228    Name of the assigning user.
3229    
3230  =item text  =item text
3231    
3232  Text of the annotation.  Text of the annotation.
# Line 3116  Line 3242 
3242    
3243  sub _ParseAssignment {  sub _ParseAssignment {
3244      # Get the parameters.      # Get the parameters.
3245      my ($text) = @_;      my ($user, $text) = @_;
3246      # Declare the return value.      # Declare the return value.
3247      my @retVal = ();      my @retVal = ();
3248      # Check to see if this is a functional assignment.      # Check to see if this is a functional assignment.
3249      my ($user, $type, $function) = split(/\n/, $text);      my ($type, $function) = split(/\n/, $text);
3250      if ($type =~ m/^set ([^ ]+) function to$/i) {      if ($type =~ m/^set function to$/i) {
3251          # Here it is, so we return the user name (which is in $1), the functional role text,          # Here we have an assignment without a user, so we use the incoming user ID.
3252          # and the assigning user.          @retVal = ($user, $function);
3253          @retVal = ($1, $function, $user);      } elsif ($type =~ m/^set (\S+) function to$/i) {
3254            # Here we have an assignment with a user that is passed back to the caller.
3255            @retVal = ($1, $function);
3256        }
3257        # If we have an assignment, we need to clean the function text. There may be
3258        # extra junk at the end added as a note from the user.
3259        if (@retVal) {
3260            $retVal[1] =~ s/(\t\S)?\s*$//;
3261      }      }
3262      # Return the result list.      # Return the result list.
3263      return @retVal;      return @retVal;
# Line 3152  Line 3285 
3285    
3286  sub FriendlyTimestamp {  sub FriendlyTimestamp {
3287      my ($timeValue) = @_;      my ($timeValue) = @_;
3288      my $retVal = strftime("%a %b %e %H:%M:%S %Y", localtime($timeValue));      my $retVal = localtime($timeValue);
3289      return $retVal;      return $retVal;
3290  }  }
3291    
# Line 3214  Line 3347 
3347  }  }
3348    
3349    
   
3350  1;  1;

Legend:
Removed from v.1.31  
changed lines
  Added in v.1.70

MCS Webmaster
ViewVC Help
Powered by ViewVC 1.0.3