Class | Bio::TogoWS::REST
In: | lib/bio/io/togows.rb
Parent: | Object

## Description

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

Details of the service are desribed in the following URI.

- togows.dbcls.jp/site/en/rest.html

## 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

- togows.dbcls.jp/site/en/rest.html

### Methods

convert convert entry entry entry_database_list entry_database_list internal_http new retrieve retrieve search search search_database_list search_database_list

### Included Modules

AccessWait

### Constants

BASE_URI | = | 'http://togows.dbcls.jp/'.freeze |  | URI of the TogoWS REST service
DEFAULT_RETRIEVAL_DATABASES | = | %w( genbank uniprot embl ddbj dad ) |  | preset default databases used by the retrieve method.

### Attributes

debug | [RW] | If true, shows debug information to $stderr.

### Public Class methods

convert(*arg)

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

[Source]

         # File lib/bio/io/togows.rb, line 339
    339:       def self.convert(*arg)
    340:         self.new.convert(*arg)
    341:       end

entry(*arg)

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

[Source]

         # File lib/bio/io/togows.rb, line 329
    329:       def self.entry(*arg)
    330:         self.new.entry(*arg)
    331:       end

entry_database_list(*arg)

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

[Source]

         # File lib/bio/io/togows.rb, line 349
    349:       def self.entry_database_list(*arg)
    350:         self.new.entry_database_list(*arg)
    351:       end

new(uri = BASE_URI)

Creates a new object.

Arguments:

- (optional) uri: String or URI object

Returns: | new object

[Source]

         # File lib/bio/io/togows.rb, line 142
    142:       def initialize(uri = BASE_URI)
    143:         uri = URI.parse(uri) unless uri.kind_of?(URI)
    144:         @pathbase = uri.path
    145:         @pathbase = '/' + @pathbase unless /\A\// =~ @pathbase
    146:         @pathbase = @pathbase + '/' unless /\/\z/ =~ @pathbase
    147:         @http = Bio::Command.new_http(uri.host, uri.port)
    148:         @header = {
    149:           'User-Agent' => "BioRuby/#{Bio::BIORUBY_VERSION_ID}"
    150:         }
    151:         @debug = false
    152:       end

retrieve(*arg)

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

[Source]

         # File lib/bio/io/togows.rb, line 344
    344:       def self.retrieve(*arg)
    345:         self.new.retrieve(*arg)
    346:       end

search(*arg)

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

[Source]

         # File lib/bio/io/togows.rb, line 334
    334:       def self.search(*arg)
    335:         self.new.search(*arg)
    336:       end

search_database_list(*arg)

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

[Source]

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

### Public Instance methods

convert(data, inputformat, format)

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

[Source]

         # File lib/bio/io/togows.rb, line 304
    304:       def convert(data, inputformat, format)
    305:         response = post_data(data, 'convert', "#{inputformat}.#{format}")
    306:
    307:         prepare_return_value(response)
    308:       end

entry(database, ids, format = nil, field = nil)

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

[Source]

         # File lib/bio/io/togows.rb, line 242
    242:       def entry(database, ids, format = nil, field = nil)
    243:         begin
    244:           a = ids.to_ary
    245:         rescue NoMethodError
    246:           ids = ids.to_s
    247:         end
    248:         ids = a.join(',') if a
    249:
    250:         arg = [ 'entry', database, ids ]
    251:         arg.push field if field
    252:         arg[-1] = "#{arg[-1]}.#{format}" if format
    253:         response = get(*arg)
    254:
    255:         prepare_return_value(response)
    256:       end

entry_database_list()

Returns list of available databases in the entry service.

Returns: | Array containing String

[Source]

         # File lib/bio/io/togows.rb, line 313
    313:       def entry_database_list
    314:         database_list('entry')
    315:       end

internal_http()

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.

[Source]

         # File lib/bio/io/togows.rb, line 161
    161:       def internal_http
    162:         @http
    163:       end

retrieve(ids, hash = {})

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

[Source]

         # File lib/bio/io/togows.rb, line 187
    187:       def retrieve(ids, hash = {})
    188:         begin
    189:           a = ids.to_ary
    190:         rescue NoMethodError
    191:           ids = ids.to_s
    192:         end
    193:         ids = a.join(',') if a
    194:         ids = ids.split(',')
    195:
    196:         dbs = hash[:database] || DEFAULT_RETRIEVAL_DATABASES
    197:         begin
    198:           dbs.to_ary
    199:         rescue NoMethodError
    200:           dbs = dbs.to_s.empty? ? [] : [ dbs.to_s ]
    201:         end
    202:         return nil if dbs.empty? or ids.empty?
    203:
    204:         if dbs.size == 1 then
    205:           return entry(dbs[0], ids, hash[:format], hash[:field])
    206:         end
    207:
    208:         results = []
    209:         ids.each do |idstr|
    210:           dbs.each do |dbstr|
    211:             r = entry(dbstr, idstr, hash[:format], hash[:field])
    212:             if r and !r.strip.empty? then
    213:               results.push r
    214:               break
    215:             end
    216:           end #dbs.each
    217:         end #ids.each
    218:
    219:         results.join('')
    220:       end

search(database, query, offset = nil, limit = nil, format = nil)

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

- en.wikipedia.org/wiki/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

[Source]

         # File lib/bio/io/togows.rb, line 279
    279:       def search(database, query, offset = nil, limit = nil, format = nil)
    280:         arg = [ 'search', database, query ]
    281:         if offset then
    282:           limit ||= 1
    283:           arg.push "#{offset},#{limit}"
    284:         end
    285:         arg[-1] = "#{arg[-1]}.#{format}" if format
    286:         response = get(*arg)
    287:
    288:         prepare_return_value(response)
    289:       end

search_database_list()

Returns list of available databases in the search service.

Returns: | Array containing String

[Source]

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

[Validate]