Robert Buels


Bio::BLAST::Database - work with formatted BLAST databases


  use Bio::BLAST::Database;

  # open an existing bdb for reading
  my $fs = Bio::BLAST::Database->open(
               full_file_basename => '/path/to/my_bdb',
  # will read from /path/to/my_bdb.nin, /path/to/my_bdb.nsq, etc

  my @filenames = $fs->list_files;

  #reopen it for writing
  $fs = Bio::BLAST::Database->open(
            full_file_basename => '/path/to/my_bdb',
            write => 1,

  # replace it with a different set of sequences

  # can also get some metadata about it
  print "db's title is ".$fs->title;
  print "db was last formatted on ".localtime( $fs->format_time );
  print "db file modification was ".localtime( $fs->file_modtime );


Each object of this class represents an NCBI-formatted sequence database on disk, which is a set of files, the exact structure of which varies a bit with the type and size of the sequence set.

This is mostly an object-oriented wrapper for using NCBI's fastacmd and formatdb tools.



Full path to the blast database file basename. This is the entire path to the BLAST database files, except for the final suffixes (.nin, .nsq, etc).

   my $basename = $db->full_file_basename;
   #returns '/data/shared/blast/databases/genbank/nr'


true/false flag for whether to create any necessary dirs at format time


true/false flag for whether to write any files that are in the way when formatted


title of this blast database, if set


return whether this blast database is indexed


accessor for type of blastdb. must be set in new(), but open() looks at the existing files and sets this



  Usage: my $fs = Bio::BLAST::Database->open({
                      full_file_basename => $ffbn,
                      write => 1,
                      create_dirs => 1,
  Desc : open a BlastDB with the given ffbn.
  Args : hashref of params as:
         {  full_file_basename => full path plus basename of files in this blastdb,
            type => 'nucleotide' or 'protein'
            write => default false, set true to write any files in the way,
            create_dirs => default false, set true to create any necessary directories
                           if formatted
  Ret  : Bio::BLAST::Database object
  Side Effects: none if no files are present at the given ffbn.  overwise,
                dies if files are present and write is not specified,
                or if dir does not exist and create_dirs was not specified


  Usage: my $fasta_fh = $bdb->to_fasta;
  Desc : get the contents of this blast database in FASTA format
  Ret  : an IO::Pipe filehandle
  Args : none
  Side Effects: runs 'fastacmd' in a forked process, cleaning up its output,
                and passing it to you


  Usage: $db->format_from_file(seqfile => 'mysequences.seq');
  Desc : format this blast database from the given source file,
         into its proper place on disk, overwriting the files already
  Ret  : nothing meaningful
  Args : hash-style list as:
          seqfile => filename containing sequences,
          title   => (optional) title for this blast database,
          indexed_seqs => (optional) if true, formats the database with
                          indexing (and sets indexed_seqs in this obj)
  Side Effects: runs 'formatdb' to format the given sequences,
                dies on failure


  Desc: get the earliest unix modification time of the database files
  Args: none
  Ret : unix modification time of the database files
  Side Effects:


  Usage: my $time = $db->format_time;
  Desc : get the format time of these db files
  Ret  : the value time() would have returned when
         this database was last formatted, or undef
         if that could not be determined (like if the
         files aren't there)
  Args : none
  Side Effects: runs 'fastacmd' to extract the formatting
                time from the database files

  NOTE:  This function assumes that the computer that
         last formatted this database had the same time zone
         set as the computer we are running on.
         Also, the time returned by this function is rounded
         down to the minute, because fastacmd does not print
         the format time in seconds.


  Usage: $bdb->check_format_from_file() or die "cannot format!\n";
  Desc : check directory existence and file permissions to see if a
         format_from_file() is likely to succeed.  This is useful,
         for example, when you have a script that downloads some
         remote database and you'd like to check first whether
         we even have permissions to format before you take the
         time to download something.
  Args : (optional) alternate full file basename to write blast DB to
           e.g. '/tmp/mytempdir/tester_blast_db'
  Ret  : nothing if everything looks good,
         otherwise a string error message summarizing the reason
         for failure
  Side Effects: reads from filesystem, may stat some files


  Usage: print "that thing is split, yo" if $db->is_split;
  Desc : determine whether this database is in multiple parts
  Ret  : true if this database has been split into multiple
         files by formatdb (e.g.,, etc.)
  Args : none
  Side Effects: looks in filesystem


  Usage: print "complete!" if $db->files_are_complete;
  Desc : tell whether this blast db has a complete set of files on disk
  Ret  : true if the set of files on disk looks complete,
         false if not
  Args : (optional) true value if the files should only be
         considered complete if the sequences are indexed for retrieval
  Side Effects: lists files on disk


  Usage: my @files = $db->list_files;
  Desc : get the list of files that belong to this blast database
  Ret  : list of full paths to all files belonging to this blast database,
  Args : none
  Side Effects: looks in the filesystem


  Desc: get the number of sequences in this blast database
  Args: none
  Ret : number of distinct sequences in this blast database, or undef
        if it could not be determined due to some error or other
  Side Effects: runs 'fastacmd' to get stats on the blast database file


  Usage: my $seq = $fs->get_sequence('LE_HBa0001A02');
  Desc : get a particular sequence from this db
  Args : sequence name to retrieve
  Ret  : Bio::PrimarySeqI-implementing object, or nothing if not found
  Side Effects: dies on error




Robert Buels <>


This software is copyright (c) 2011 by Robert Buels.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.