Bio.TogoWS package

Module contents

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/

Bio.TogoWS.entry(db, id, format=None, field=None)

Call TogoWS ‘entry’ to fetch a record.

Arguments:

  • 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.

Bio.TogoWS.search_count(db, query)

Call TogoWS search count to see how many matches a search gives.

Arguments:

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.

Bio.TogoWS.search_iter(db, query, limit=None, batch=100)

Call TogoWS search iterating over the results (generator function).

Arguments:

  • 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.

>>> from Bio import TogoWS
>>> for id in TogoWS.search_iter("pubmed", "diabetes+human", limit=10):
...     print("PubMed ID: %s" %id) # maybe fetch data with entry?
PubMed ID: ...

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

Bio.TogoWS.search(db, query, offset=None, limit=None, format=None)

Call TogoWS search.

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.

Arguments:

  • 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).

Bio.TogoWS.convert(data, in_format, out_format)

Call TogoWS for file format conversion.

Arguments:

  • 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)