Boulder::Genbank methods

This section lists the public methods that the Boulder::Genbank class makes available.

new()

   # Network fetch via Entrez, with accession numbers
   $gb=new Boulder::Genbank(-accessor  =>  'Entrez',
                            -fetch     =>  [qw/M57939 M28274 L36028/]);
   # Same, but shorter and uses -> operator
   $gb = Boulder::Genbank->new qw(M57939 M28274 L36028);
   # Network fetch via Entrez, with a query
   # Network fetch via Entrez, with a query
   $query = 'Homo sapiens[Organism] AND EST[Keyword]';
   $gb=new Boulder::Genbank(-accessor  =>  'Entrez',
                            -fetch     =>  $query);
   # Local fetch via Yank, with accession numbers
   $gb=new Boulder::Genbank(-accessor  =>  'Yank',
                            -fetch     =>  [qw/M57939 M28274 L36028/]);
   # Local fetch via File
   $gb=new Boulder::Genbank(-accessor  =>  'File',
                            -fetch     =>  '/usr/local/genbank/gbpri3.seq');
    

The new() method creates a new Boulder::Genbank stream on the accessor provided. The three possible accessors are Entrez, Yank and File. If successful, the method returns the stream object. Otherwise it returns undef.

new() takes the following arguments:

        -accessor       Name of the accessor to use
        -fetch          Parameters to pass to the accessor
        -proxy          Path to an HTTP proxy, used when using
                         the Entrez accessor over a firewall.
    

Specify the accessor to use with the -accessor argument. If not specified, it defaults to Entrez.

-fetch is an accessor-specific argument. The possibilities are:

For Entrez, the -fetch argument may point to a scalar, in which case it is interpreted as an Entrez query string. See http://www.ncbi.nlm.nih.gov/Entrez/linking.html for a description of the query syntax. Alternatively, -fetch may point to an array reference, in which case it is interpreted as a list of accession numbers to retrieve. If -fetch points to a hash, it is interpreted as extended information. See "Extended Entrez Parameters" below.

For Yank, the -fetch argument must point to an array reference containing the accession numbers to retrieve.

For File, the -fetch argument must point to a string-valued scalar, which will be interpreted as the path to the file to read Genbank entries from.

For Entrez (and Entrez only) Boulder::Genbank allows you to use a shortcut syntax in which you provde new() with a list of accession numbers:

  $gb = new Boulder::Genbank('M57939','M28274','L36028');
    

newFh()

This works like new(), but returns a filehandle. To recover each GenBank record read from the filehandle with the <> operator:

  $fh = Boulder::GenBank->newFh('M57939','M28274','L36028');
  while ($record = <$fh>) {
     print $record->asString;
  }
    

get()

The get() method is inherited from Boulder::Stream, and simply returns the next parsed Genbank Stone, or undef if there is nothing more to fetch. It has the same semantics as the parent class, including the ability to restrict access to certain top-level tags.

The object returned is a Stone::GB_Sequence object, which is a descendent of Stone.

put()

The put() method is inherited from the parent Boulder::Stream class, and will write the passed Stone to standard output in Boulder format. This means that it is currently not possible to write a Boulder::Genbank object back into Genbank flatfile form.

Extended Entrez Parameters

The Entrez accessor recognizes extended parameters that allow you the ability to customize the search. Instead of passing a query string scalar or a list of accession numbers as the -fetch argument, pass a hash reference. The hashref should contain one or more of the following keys:

-query

The Entrez query to process.

-accession

The list of accession numbers to fetch, as an array ref.

-db

The database to search. This is a single-letter database code selected from the following list:

  m  MEDLINE
  p  Protein
  n  Nucleotide
  s  Popset
    

-proxy

An HTTP proxy to use. For example:

   -proxy => http://www.firewall.com:9000
    

If you think you need this, get the correct URL from your system administrator.

As an example, here's how to search for ESTs from Oryza sativa that have been entered or modified since 1999.

  my $gb = new Boulder::Genbank( -accessor=>Entrez, 
                                 -query=>'Oryza sativa[Organism] AND EST[Keyword] AND 1999[MDAT]', 
                                 -db   => 'n'   
                                });

$length = $entry->length

Get the length of the sequence.

$start = $entry->start

Get the start position of the sequence, currently always "1".

$end = $entry->end

Get the end position of the sequence, currently always the same as the length.

@feature_list = $entry->features(-pos=>[50,450],-type=>['CDS','Exon'])

features() will search the entry feature list for those features that meet certain criteria. The criteria are specified using the -pos and/or -type argument names, as shown below.

-pos

Provide a position or range of positions which the feature must overlap. A single position is specified in this way:

   -pos => 1500;         # feature must overlap postion 1500
    

or a range of positions in this way:

   -pos => [1000,1500];  # 1000 to 1500 inclusive
    

If no criteria are provided, then features() returns all the features, and is equivalent to calling the Features() accessor.

-type, -types

Filter the list of features by type or a set of types. Matches are case-insensitive, so "exon", "Exon" and "EXON" are all equivalent. You may call with a single type as in:

   -type => 'Exon'
    

or with a list of types, as in

   -types => ['Exon','CDS']
    

The names "-type" and "-types" can be used interchangeably.

$seqObj = $entry->bioSeq;

Returns a Bio::Seq object from the Bioperl project. Dies with an error message unless the Bio::Seq module is installed.

Top-Level Tags

These are tags that appear at the top level of the parsed Genbank entry.

Accession

The accession number of this entry. Because of the vagaries of the Genbank data model, an entry may have multiple accession numbers (e.g. after a merging operation). Accession may therefore be a multi-valued tag.

Example:

      my $accessionNo = $s->Accession;
    

Authors

The list of authors, as they appear on the AUTHORS line of the Genbank record. No attempt is made to parse them into individual authors.

Basecount

The nucleotide basecount for the entry. It is presented as a Boulder Stone with keys "a", "c", "t" and "g". Example:

     my $A = $s->Basecount->A;
     my $C = $s->Basecount->C;
     my $G = $s->Basecount->G;
     my $T = $s->Basecount->T;
     print "GC content is ",($G+$C)/($A+$C+$G+$T),"\n";
    

Blob

The entire flatfile record as an unparsed chunk of text (a "blob"). This is a handy way of reassembling the record for human inspection.

Comment

The COMMENT line from the Genbank record.

Definition

The DEFINITION line from the Genbank record, unmodified.

Features

The FEATURES table. This is a complex stone object with multiple subtags. See the "The Features Tag" for details.

Journal

The JOURNAL line from the Genbank record, unmodified.

Keywords

The KEYWORDS line from the Genbank record, unmodified. No attempt is made to parse the keywords into separate values.

Example:

    my $keywords = $s->Keywords
    

Locus

The LOCUS line from the Genbank record. It is not further parsed.

Medline, Nid

References to other database accession numbers.

Organism

The taxonomic name of the organism from which this entry was derived. This line is taken from the Genbank entry unmodified. See the NCBI data model documentation for an explanation of their taxonomic syntax.

Reference

The REFERENCE line from the Genbank entry. There are often multiple Reference lines. Example:

  my @references = $s->Reference;
    

Sequence

The DNA or RNA sequence of the entry. This is presented as a single lower-case string, with all base numbers and formatting characters removed.

Source

The entry's SOURCE field; often giving clues on how the sequencing was performed.

Title

The TITLE field from the paper describing this entry, if any.

The Features Tag

The Features tag points to a Stone record that contains multiple subtags. Each subtag is the name of a feature which points, in turn, to a Stone that describes the feature's location and other attributes. The full list of feature is beyond this document, but the following are the features that are most often seen:

        Cds             a CDS
        Intron          an intron
        Exon            an exon
        Gene            a gene
        Mrna            an mRNA
        Polya_site      a putative polyadenylation signal
        Repeat_unit     a repetitive region
        Source          More information about the organism and cell
                        type the sequence was derived from
        Satellite       a microsatellite (dinucleotide repeat)

Each feature will contain one or more of the following subtags:

DB_xref

A cross-reference to another database in the form DB_NAME:accession_number. See the NCBI Web site for a description of these cross references.

Evidence

The evidence for this feature, either "experimental" or "predicted".

Gene

If the feature involves a gene, this will be the gene's name (or one of its names). This subtag is often seen in "Gene" and Cds features.

Example:

        foreach ($s->Features->Cds) {
           my $gene = $_->Gene;
           my $position = $_->Position;
           Print "Gene $gene ($position)\n";
        }
    

Map

If the feature is mapped, this provides a map position, usually as a cytogenetic band.

Note

A grab-back for various text notes.

Number

When multiple features of this type occur, this field is used to number them. Ordinarily this field is not needed because Boulder::Genbank preserves the order of features.

Organism

If the feature is Source, this provides the source organism.

Position

The position of this feature, usually expresed as a range (1970..1975).

Product

The protein product of the feature, if applicable, as a text string.

Translation

The protein translation of the feature, if applicable.