Class: Bio::TogoWS::REST

Inherits:
Object show all
Includes:
AccessWait
Defined in:
lib/bio/io/togows.rb

Overview

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

Constant Summary collapse

BASE_URI =

URI of the TogoWS REST service

'http://togows.dbcls.jp/'.freeze
DEFAULT_RETRIEVAL_DATABASES =

preset default databases used by the retrieve method.

%w( genbank uniprot embl ddbj dad )

Constants included from AccessWait

AccessWait::TOGOWS_ACCESS_WAIT, AccessWait::TOGOWS_ACCESS_WAIT_MAX

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(uri = BASE_URI) ⇒ REST

Creates a new object.

Arguments:

  • (optional) uri: String or URI object

Returns

new object



142
143
144
145
146
147
148
149
150
151
152
 
# 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

Instance Attribute Details

#debug ⇒ Object

If true, shows debug information to $stderr.



155
156
157
 
# File 'lib/bio/io/togows.rb', line 155

def debug
  @debug
end

Class Method Details

.convert(*arg) ⇒ Object

The same as Bio::TogoWS::REST#convert.



339
340
341
 
# File 'lib/bio/io/togows.rb', line 339

def self.convert(*arg)
  self.new.convert(*arg)
end

.entry(*arg) ⇒ Object

The same as Bio::TogoWS::REST#entry.



329
330
331
 
# File 'lib/bio/io/togows.rb', line 329

def self.entry(*arg)
  self.new.entry(*arg)
end

.entry_database_list(*arg) ⇒ Object

The same as Bio::TogoWS::REST#entry_database_list



349
350
351
 
# File 'lib/bio/io/togows.rb', line 349

def self.entry_database_list(*arg)
  self.new.entry_database_list(*arg)
end

.retrieve(*arg) ⇒ Object

The same as Bio::TogoWS::REST#retrieve.



344
345
346
 
# File 'lib/bio/io/togows.rb', line 344

def self.retrieve(*arg)
  self.new.retrieve(*arg)
end

.search(*arg) ⇒ Object

The same as Bio::TogoWS::REST#search.



334
335
336
 
# File 'lib/bio/io/togows.rb', line 334

def self.search(*arg)
  self.new.search(*arg)
end

.search_database_list(*arg) ⇒ Object

The same as Bio::TogoWS::REST#search_database_list



354
355
356
 
# File 'lib/bio/io/togows.rb', line 354

def self.search_database_list(*arg)
  self.new.search_database_list(*arg)
end

Instance Method Details

#convert(data, inputformat, format) ⇒ Object

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



304
305
306
307
308
 
# 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) ⇒ Object

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



242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
 
# 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 ⇒ Object

Returns list of available databases in the entry service.

Returns

Array containing String



313
314
315
 
# File 'lib/bio/io/togows.rb', line 313

def entry_database_list
  database_list('entry')
end

#internal_http ⇒ Object

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.



161
162
163
 
# File 'lib/bio/io/togows.rb', line 161

def internal_http
  @http
end

#retrieve(ids, hash = {}) ⇒ Object

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



187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
 
# 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, query, offset = nil, limit = nil, format = nil) ⇒ Object

Database search. Format of the search term string follows the Common Query Language.

Example:

t = Bio::TogoWS::REST.new
print t.search('uniprot', 'lung cancer')
# only get the 10th and 11th hit ID
print t.search('uniprot', 'lung cancer', 10, 2)
# with json format
print t.search('uniprot', 'lung cancer', 10, 2, 'json')

Arguments:

  • (required) database: (String) database name

  • (required) query: (String) query string

  • (optional) offset: (Integer) offset in search results.

  • (optional) limit: (Integer) max. number of returned results. If offset is not nil and the limit is nil, it is set to 1.

  • (optional) format: (String) format. nil means the default format.

Returns

String or nil



279
280
281
282
283
284
285
286
287
288
289
 
# File 'lib/bio/io/togows.rb', line 279

def search(database, query, offset = nil, limit = nil, format = nil)
  arg = [ 'search', database, query ]
  if offset then
    limit ||= 1
    arg.push "#{offset},#{limit}"
  end
  arg[-1] = "#{arg[-1]}.#{format}" if format
  response = get(*arg)

  prepare_return_value(response)
end

#search_database_list ⇒ Object

Returns list of available databases in the search service.

Returns

Array containing String



320
321
322
 
# File 'lib/bio/io/togows.rb', line 320

def search_database_list
  database_list('search')
end