class Bio::TogoWS::REST

Description

Bio::TogoWS::REST is a REST client for the TogoWS web service.

Details of the service are desribed in the following URI.

Examples

For light users, class methods can be used.

print Bio::TogoWS::REST.entry('genbank', 'AF237819')
print Bio::TogoWS::REST.search('uniprot', 'lung cancer')

For heavy users, an instance of the REST class can be created, and using the instance is more efficient than using class methods.

t = Bio::TogoWS::REST.new
print t.entry('genbank', 'AF237819')
print t.search('uniprot', 'lung cancer')

References

Constants

BASE_URI

URI of the TogoWS REST service

DEFAULT_RETRIEVAL_DATABASES

preset default databases used by the retrieve method.

Attributes

debug[RW]

If true, shows debug information to $stderr.

Public Class Methods

convert(*arg) click to toggle source

The same as #convert.

# File lib/bio/io/togows.rb, line 339
def self.convert(*arg)
  self.new.convert(*arg)
end
entry(*arg) click to toggle source

The same as #entry.

# File lib/bio/io/togows.rb, line 329
def self.entry(*arg)
  self.new.entry(*arg)
end
entry_database_list(*arg) click to toggle source

The same as #entry_database_list

# File lib/bio/io/togows.rb, line 349
def self.entry_database_list(*arg)
  self.new.entry_database_list(*arg)
end
new(uri = BASE_URI) click to toggle source

Creates a new object.


Arguments:

  • (optional) uri: String or URI object

Returns

new object

# File lib/bio/io/togows.rb, line 142
def initialize(uri = BASE_URI)
  uri = URI.parse(uri) unless uri.kind_of?(URI)
  @pathbase = uri.path
  @pathbase = '/' + @pathbase unless /\A\// =~ @pathbase
  @pathbase = @pathbase + '/' unless /\/\z/ =~ @pathbase
  @http = Bio::Command.new_http(uri.host, uri.port)
  @header = {
    'User-Agent' => "BioRuby/#{Bio::BIORUBY_VERSION_ID}"
  }
  @debug = false
end
retrieve(*arg) click to toggle source

The same as #retrieve.

# File lib/bio/io/togows.rb, line 344
def self.retrieve(*arg)
  self.new.retrieve(*arg)
end
search_database_list(*arg) click to toggle source

The same as #search_database_list

# File lib/bio/io/togows.rb, line 354
def self.search_database_list(*arg)
  self.new.search_database_list(*arg)
end

Public Instance Methods

convert(data, inputformat, format) click to toggle source

Data format conversion.

Example:

t = Bio::TogoWS::REST.new
blast_string = File.read('test.blastn')
t.convert(blast_string, 'blast', 'gff')

Arguments:

  • (required) text: (String) input data

  • (required) inputformat: (String) data source format

  • (required) format: (String) output format

Returns

String or nil

# File lib/bio/io/togows.rb, line 304
def convert(data, inputformat, format)
  response = post_data(data, 'convert', "#{inputformat}.#{format}")

  prepare_return_value(response)
end
entry(database, ids, format = nil, field = nil) click to toggle source

Retrieves entries corresponding to the specified IDs.

Example:

t = Bio::TogoWS::REST.new
kuma = t.entry('genbank', 'AF237819')
# multiple IDs at a time
misc = t.entry('genbank', [ 'AF237819', 'AF237820' ])
# with format change
p53 = t.entry('uniprot', 'P53_HUMAN', 'fasta')

Arguments:

  • (required) database: (String) database name

  • (required) ids: (String) an entry ID, or (Array containing String) IDs. Note that strings containing “,” are regarded as multiple IDs.

  • (optional) format: (String) format. nil means the default format (differs depending on the database).

  • (optional) field: (String) gets only the specified field if not nil

Returns

String or nil

# File lib/bio/io/togows.rb, line 242
def entry(database, ids, format = nil, field = nil)
  begin
    a = ids.to_ary
  rescue NoMethodError
    ids = ids.to_s
  end
  ids = a.join(',') if a

  arg = [ 'entry', database, ids ]
  arg.push field if field
  arg[-1] = "#{arg[-1]}.#{format}" if format
  response = get(*arg)

  prepare_return_value(response)
end
entry_database_list() click to toggle source

Returns list of available databases in the entry service.


Returns

Array containing String

# File lib/bio/io/togows.rb, line 313
def entry_database_list
  database_list('entry')
end
internal_http() click to toggle source

Debug purpose only. Returns Net::HTTP object used inside the object. The method will be changed in the future if the implementation of this class is changed.

# File lib/bio/io/togows.rb, line 161
def internal_http
  @http
end
retrieve(ids, hash = {}) click to toggle source

Intelligent version of the entry method. If two or more databases are specified, sequentially tries them until valid entry is obtained.

If database is not specified, preset default databases are used. See DEFAULT_RETRIEVAL_DATABASES for details.

When multiple IDs and multiple databases are specified, sequentially tries each IDs. Note that results with no hits found or with server errors are regarded as void strings. Also note that data format of the result entries can be different from entries to entries.


Arguments:

  • (required) ids: (String) an entry ID, or (Array containing String) IDs. Note that strings containing “,”

  • (optional) hash: (Hash) options below can be passed as a hash.

    • (optional) :database: (String) database name, or (Array containing String) database names.

    • (optional) :format: (String) format

    • (optional) :field: (String) gets only the specified field

Returns

String or nil

# File lib/bio/io/togows.rb, line 187
def retrieve(ids, hash = {})
  begin
    a = ids.to_ary
  rescue NoMethodError
    ids = ids.to_s
  end
  ids = a.join(',') if a
  ids = ids.split(',')

  dbs = hash[:database] || DEFAULT_RETRIEVAL_DATABASES
  begin
    dbs.to_ary
  rescue NoMethodError
    dbs = dbs.to_s.empty? ? [] : [ dbs.to_s ]
  end
  return nil if dbs.empty? or ids.empty?

  if dbs.size == 1 then
    return entry(dbs[0], ids, hash[:format], hash[:field])
  end

  results = []
  ids.each do |idstr|
    dbs.each do |dbstr|
      r = entry(dbstr, idstr, hash[:format], hash[:field])
      if r and !r.strip.empty? then
        results.push r
        break
      end
    end #dbs.each
  end #ids.each
  
  results.join('')
end
search_database_list() click to toggle source

Returns list of available databases in the search service.


Returns

Array containing String

# File lib/bio/io/togows.rb, line 320
def search_database_list
  database_list('search')
end

Private Instance Methods

database_list(service) click to toggle source

Returns list of available databases


Arguments:

Returns

Array containing String

# File lib/bio/io/togows.rb, line 444
def database_list(service)
  response = get_dir(service)
  str = prepare_return_value(response)
  if str then
    str.chomp.split(/\r?\n/)
  else
    raise 'Unexpected server response'
  end
end
get(*paths) click to toggle source

Access to the TogoWS by using GET method.

Example 1:

get('entry', 'genbank', AF209156')

Example 2:

get('search', 'uniprot', 'lung cancer')

Arguments:

Returns

Net::HTTPResponse object

# File lib/bio/io/togows.rb, line 371
def get(*paths)
  path = make_path(paths)
  if @debug then
    $stderr.puts "TogoWS: HTTP#get(#{path.inspect}, #{@header.inspect})"
  end
  togows_access_wait
  @http.get(path, @header)
end
get_dir(*paths) click to toggle source

Access to the TogoWS by using GET method. Always adds '/' at the end of the path.

Example 1:

get_dir('entry')

Arguments:

Returns

Net::HTTPResponse object

# File lib/bio/io/togows.rb, line 390
def get_dir(*paths)
  path = make_path(paths)
  path += '/' unless /\/\z/ =~ path
  if @debug then
    $stderr.puts "TogoWS: HTTP#get(#{path.inspect}, #{@header.inspect})"
  end
  togows_access_wait
  @http.get(path, @header)
end
make_path(paths) click to toggle source

Generates path string from the given paths.


Arguments:

  • (required) paths: Array containing String objects

Returns

String

# File lib/bio/io/togows.rb, line 422
def make_path(paths)
  @pathbase + paths.collect { |x| CGI.escape(x.to_s) }.join('/')
end
post_data(data, *paths) click to toggle source

Access to the TogoWS by using POST method. The data is stored to the form key 'data'. Mime type is 'application/x-www-form-urlencoded'.


Arguments:

Returns

Net::HTTPResponse object

# File lib/bio/io/togows.rb, line 408
def post_data(data, *paths)
  path = make_path(paths)
  if @debug then
    $stderr.puts "TogoWS: Bio::Command.http_post_form(#{path.inspect}, { \"data\" => (#{data.size} bytes) }, #{@header.inspect})"
  end
  togows_access_wait
  Bio::Command.http_post_form(@http, path, { 'data' => data }, @header)
end
prepare_return_value(response) click to toggle source

If response.code == “200”, returns body as a String. Otherwise, returns nil.

# File lib/bio/io/togows.rb, line 428
def prepare_return_value(response)
  if @debug then
    $stderr.puts "TogoWS: #{response.inspect}"
  end
  if response.code == "200" then
    response.body
  else
    nil
  end
end