Package Bio :: Package TogoWS
[hide private]
[frames] | no frames]

Package TogoWS

source code

Provides code to access the TogoWS integrated websevices of DBCLS, Japan.

This module aims to make the TogoWS (from DBCLS, Japan) easier to use. See: http://togows.dbcls.jp/

The TogoWS REST service provides simple access to a range of databases, acting as a proxy to shield you from all the different provider APIs. This works using simple URLs (which this module will construct for you). For more details, see http://togows.dbcls.jp/site/en/rest.html

The functionality is somewhat similar to Biopython's Bio.Entrez module which provides access to the NCBI's Entrez Utilities (E-Utils) which also covers a wide range of databases.

Currently TogoWS does not provide any usage guidelines (unlike the NCBI whose requirements are reasonably clear). To avoid risking overloading the service, Biopython will only allow three calls per second.

The TogoWS SOAP service offers a more complex API for calling web services (essentially calling remote functions) provided by DDBJ, KEGG and PDBj. For example, this allows you to run a remote BLAST search at the DDBJ. This is not yet covered by this module, however there are lots of Python examples on the TogoWS website using the SOAPpy python library. See: http://togows.dbcls.jp/site/en/soap.html http://soapy.sourceforge.net/

Functions [hide private]
 
_get_fields(url)
Queries a TogoWS URL for a plain text list of values (PRIVATE).
source code
 
_get_entry_dbs() source code
 
_get_entry_fields(db) source code
 
_get_entry_formats(db) source code
 
_get_convert_formats() source code
 
entry(db, id, format=None, field=None)
TogoWS fetch entry (returns a handle).
source code
 
search_count(db, query)
TogoWS search count (returns an integer).
source code
 
search_iter(db, query, limit=None, batch=100)
TogoWS search iteratating over the results (generator function).
source code
 
search(db, query, offset=None, limit=None, format=None)
TogoWS search (returns a handle).
source code
 
convert(data, in_format, out_format)
TogoWS convert (returns a handle).
source code
 
_open(url, post=None)
Helper function to build the URL and open a handle to it (PRIVATE).
source code
Variables [hide private]
  _BASE_URL = 'http://togows.dbcls.jp'
  _search_db_names = None
hash(x)
  _entry_db_names = None
hash(x)
  _entry_db_fields = {}
  _entry_db_formats = {}
  _convert_formats = []
  __package__ = 'Bio.TogoWS'
Function Details [hide private]

entry(db, id, format=None, field=None)

source code 

TogoWS fetch entry (returns a handle).

  • db - database (string), see list below.
  • id - identier (string) or a list of identifiers (either as a list of strings or a single string with comma separators).
  • format - return data file format (string), options depend on the database e.g. "xml", "json", "gff", "fasta", "ttl" (RDF Turtle)
  • field - specific field from within the database record (string) e.g. "au" or "authors" for pubmed.

At the time of writing, this includes the following:

KEGG: compound, drug, enzyme, genes, glycan, orthology, reaction,
      module, pathway
DDBj: ddbj, dad, pdb
NCBI: nuccore, nucest, nucgss, nucleotide, protein, gene, onim,
      homologue, snp, mesh, pubmed
EBI:  embl, uniprot, uniparc, uniref100, uniref90, uniref50

For the current list, please see http://togows.dbcls.jp/entry/

This function is essentially equivalent to the NCBI Entrez service EFetch, available in Biopython as Bio.Entrez.efetch(...), but that does not offer field extraction.

search_count(db, query)

source code 

TogoWS search count (returns an integer).

db - database (string), see http://togows.dbcls.jp/search query - search term (string)

You could then use the count to download a large set of search results in batches using the offset and limit options to Bio.TogoWS.search(). In general however the Bio.TogoWS.search_iter() function is simpler to use.

search_iter(db, query, limit=None, batch=100)

source code 

TogoWS search iteratating over the results (generator function).

  • db - database (string), see http://togows.dbcls.jp/search
  • query - search term (string)
  • limit - optional upper bound on number of search results
  • batch - number of search results to pull back each time talk to TogoWS (currently limited to 100).

You would use this function within a for loop, e.g.

>>> for id in search_iter("pubmed", "lung+cancer+drug", limit=10):
...     print(id) # maybe fetch data with entry?

Internally this first calls the Bio.TogoWS.search_count() and then uses Bio.TogoWS.search() to get the results in batches.

search(db, query, offset=None, limit=None, format=None)

source code 

TogoWS search (returns a handle).

This is a low level wrapper for the TogoWS search function, which can return results in a several formats. In general, the search_iter function is more suitable for end users.

  • db - database (string), see http://togows.dbcls.jp/search/
  • query - search term (string)
  • offset, limit - optional integers specifying which result to start from (1 based) and the number of results to return.
  • format - return data file format (string), e.g. "json", "ttl" (RDF) By default plain text is returned, one result per line.

At the time of writing, TogoWS applies a default count limit of 100 search results, and this is an upper bound. To access more results, use the offset argument or the search_iter(...) function.

TogoWS supports a long list of databases, including many from the NCBI (e.g. "ncbi-pubmed" or "pubmed", "ncbi-genbank" or "genbank", and "ncbi-taxonomy"), EBI (e.g. "ebi-ebml" or "embl", "ebi-uniprot" or "uniprot, "ebi-go"), and KEGG (e.g. "kegg-compound" or "compound"). For the current list, see http://togows.dbcls.jp/search/

The NCBI provide the Entrez Search service (ESearch) which is similar, available in Biopython as the Bio.Entrez.esearch() function.

See also the function Bio.TogoWS.search_count() which returns the number of matches found, and the Bio.TogoWS.search_iter() function which allows you to iterate over the search results (taking care of batching for you).

convert(data, in_format, out_format)

source code 

TogoWS convert (returns a handle).

data - string or handle containing input record(s) in_format - string describing the input file format (e.g. "genbank") out_format - string describing the requested output format (e.g. "fasta")

For a list of supported conversions (e.g. "genbank" to "fasta"), see http://togows.dbcls.jp/convert/

Note that Biopython has built in support for conversion of sequence and alignnent file formats (functions Bio.SeqIO.convert and Bio.AlignIO.convert)

_open(url, post=None)

source code 

Helper function to build the URL and open a handle to it (PRIVATE).

Open a handle to TogoWS, will raise an IOError if it encounters an error.

In the absense of clear guidelines, this function enforces a limit of "up to three queries per second" to avoid abusing the TogoWS servers.