Changeset 1736:b3b664abcfdd in orange-bioinformatics


Ignore:
Timestamp:
04/05/13 19:43:36 (13 months ago)
Author:
Ales Erjavec <ales.erjavec@…>
Branch:
default
Message:

Added sphinx rst documentation for obiKEGG.

Files:
4 added
5 edited

Legend:

Unmodified
Added
Removed
  • _bioinformatics/obiKEGG/__init__.py

    r1735 r1736  
    44============================================== 
    55 
    6 This is a python module for access to `KEGG`_ using its web services. 
    7  
    8 To use this module you need to have `slumber` and `requests` package 
    9 installed. 
    10  
    11 .. _`KEGG`: http://www.genome.jp/kegg/ 
    12  
     6:mod:`obiKEGG` is a python module for accessing `KEGG (Kyoto Encyclopedia 
     7of Genes and Genomes) <http://www.genome.jp/kegg/>`_ using its web services. 
     8 
     9.. note:: To use this module you need to have `slumber`_ and `requests`_ 
     10          package installed. 
     11 
     12.. _`slumber`: https://pypi.python.org/pypi/slumber/ 
     13 
     14.. _`requests`: https://pypi.python.org/pypi/requests 
     15 
     16 
     17>>> # Create a KEGG Genes database interface 
     18>>> genome = KEGGGenome() 
     19>>> # List all available entry ids 
     20>>> keys = genome.keys() 
     21>>> print keys[0] 
     22T01001 
     23>>> # Retrieve the entry for the key. 
     24>>> entry = genome[keys[0]] 
     25>>> print entry.entry_key 
     26T01001 
     27>>> print entry.definition 
     28Homo sapiens (human) 
     29>>> print str(entry) 
     30ENTRY       T01001            Complete  Genome 
     31NAME        hsa, HUMAN, 9606 
     32DEFINITION  Homo sapiens (human) 
     33... 
     34 
     35The :class:`Organism` class can be used as a convenient starting point 
     36for organism specific databases. 
     37 
     38>>> organism = Organism("Homo sapiens")  # searches for the organism by name 
     39>>> print organism.org_code  # prints the KEGG organism code 
     40hsa 
     41>>> genes = organism.genes  # get the genes database for the organism 
     42>>> gene_ids = genes.keys() # KEGG gene identifiers 
     43>>> entry = genes["hsa:672"] 
     44>>> print entry.definition 
     45breast cancer 1, early onset 
     46>>> print entry  # print the entry in DBGET database format. 
     47ENTRY       672               CDS       T01001 
     48NAME        BRCA1, BRCAI, BRCC1, BROVCA1, IRIS, PNCA4, PPP1R53, PSCP, RNF53 
     49DEFINITION  breast cancer 1, early onset 
     50... 
    1351 
    1452""" 
     
    64102    organism in the KEGG Genes database. 
    65103 
    66     :param org: KEGGG organism code (e.g. "hsa", "sce") 
     104    :param org: KEGG organism code (e.g. "hsa", "sce"). Can also be a 
     105        descriptive name (e.g. 'yeast', "homo sapiens") in which case the 
     106        organism code will be searched for by using KEGG `find` api. 
    67107    :type org: str 
     108 
     109    .. seealso:: 
     110 
     111        :func:`organism_name_search` 
     112            Search KEGG for an organism code 
    68113 
    69114    """ 
     
    83128    def genes(self): 
    84129        """ 
    85         An :class:`Genes` database instance for this organism. 
     130        An :class:`~.databases.Genes` database instance for this organism. 
    86131        """ 
    87132        # TODO: This should not be a property but a method. 
     
    134179    def list_pathways(self): 
    135180        """ 
    136         List all pathways. 
     181        List all pathways for this organism. 
     182 
     183        .. deprecated: 2.5 
     184            Use :func:`pathways` instead. 
     185 
    137186        """ 
    138187        # NOTE: remove/deprecate and use pathways() 
     
    304353 
    305354def organism_name_search(name): 
     355    """ 
     356    Search and organism by `name` and return an KEGG organism code. 
     357    """ 
    306358    return KEGGOrganism.organism_name_search(name) 
    307359 
    308360 
    309361def pathways(org): 
     362    """ 
     363    Return a list of all KEGG pathways for an KEGG organism code `org`. 
     364    """ 
    310365    return KEGGPathway.list(org) 
    311366 
    312367 
    313368def organisms(): 
     369    """ 
     370    Return a list of all KEGG organisms. 
     371    """ 
    314372    return KEGGOrganism.organisms() 
    315373 
    316374 
    317375def from_taxid(taxid): 
     376    """ 
     377    Return a KEGG organism code for a an NCBI Taxonomy id string `taxid`. 
     378    """ 
    318379    genome = KEGGGenome() 
    319380    res = genome.search(taxid) 
     
    328389 
    329390def to_taxid(name): 
     391    """ 
     392    Return a NCBI Taxonomy id for a given KEGG Organism name 
     393    """ 
    330394    genome = KEGGGenome() 
    331395    if name in genome: 
  • _bioinformatics/obiKEGG/databases.py

    r1734 r1736  
    11""" 
    2 DBGET database 
     2DBGET Database Interface 
     3======================== 
     4 
    35""" 
    46from __future__ import absolute_import 
     
    1214 
    1315def iter_take(source_iter, n): 
     16    """ 
     17    Return a list of the first `n` items in `source_iter`. 
     18    """ 
    1419    source_iter = iter(source_iter) 
    1520    return [item for _, item in zip(range(n), source_iter)] 
     
    1722 
    1823def batch_iter(source_iter, n): 
     24    """ 
     25    Split the `source_iter` into batches of size `n`. 
     26    """ 
    1927    source_iter = iter(source_iter) 
    2028    while True: 
     
    4654class DBDataBase(object): 
    4755    """ 
    48     A wrapper for DBGET database. 
    49  
    50     """ 
    51     # ENTRY_TYPE constructor (type) 
     56    Base class for a DBGET database interface. 
     57 
     58    """ 
     59    #: ENTRY_TYPE constructor (a :class:`~.entry.DBEntry` subclass). This 
     60    #: should be redefined in subclasses. 
    5261    ENTRY_TYPE = entry.DBEntry 
    5362 
    54     # A database name/abbreviation (e.g. path). Needs to be set in a 
    55     # subclass or object instance's constructor 
     63    #: A database name/abbreviation (e.g. 'pathway'). Needs to be set in a 
     64    #: subclass or object instance's constructor before calling the base. 
     65    #: __init__ 
    5666    DB = None 
    5767 
     
    6979    def keys(self): 
    7080        """ 
    71         Return a list of database keys. These are unique kegg identifiers 
     81        Return a list of database keys. These are unique KEGG identifiers 
    7282        that can be used to query the database. 
    7383 
     
    7787    def iterkeys(self): 
    7888        """ 
    79         Return an iterator over the `keys` 
     89        Return an iterator over the `keys`. 
    8090        """ 
    8191        return iter(self._keys) 
     
    8393    def items(self): 
    8494        """ 
    85         Return a list of all (key, `ENTRY_TYPE` instance) tuples. 
     95        Return a list of all (key, :obj:`DBDataBase.ENTRY_TYPE` instance) 
     96        tuples. 
     97 
    8698        """ 
    8799        return list(zip(self.keys(), self.batch_get(self.keys()))) 
     
    98110    def values(self): 
    99111        """ 
    100         Return a list of all `ENTRY_TYPE` instances. 
     112        Return a list of all :obj:`DBDataBase.ENTRY_TYPE` instances. 
    101113        """ 
    102114        return self.batch_get(self.keys()) 
     
    104116    def itervalues(self): 
    105117        """ 
    106         Return an iterator over all `ENTRY_TYPE` instances. 
     118        Return an iterator over all :obj:`DBDataBase.ENTRY_TYPE` instances. 
    107119        """ 
    108120        batch_size = 100 
     
    113125    def get(self, key, default=None): 
    114126        """ 
    115         Return an `ENTRY_TYPE` instance for the `key`. Raises `KeyError` if 
    116         not found. 
     127        Return an :obj:`DBDataBase.ENTRY_TYPE` instance for the `key`. 
     128        Raises :class:`KeyError` if not found. 
    117129 
    118130        """ 
     
    160172    def find(self, name): 
    161173        """ 
    162         Find ``name`` using kegg ``find`` api. 
     174        Find `name` using kegg `find` api. 
    163175        """ 
    164176        res = self.api.find(self.DB, name).splitlines() 
     
    167179    def pre_cache(self, keys=None, batch_size=10, progress_callback=None): 
    168180        """ 
    169         Retrieve all the entries and cache them locally. 
    170         """ 
    171         # TODO do this in multiple threads 
    172  
     181        Retrieve all the entries for `keys` and cache them locally for faster 
     182        subsequent retrieval. If `keys` is ``None`` then all entries will be 
     183        retrieved. 
     184 
     185        """ 
    173186        if not isinstance(self.api, api.CachedKeggApi): 
    174187            raise TypeError("Not an instance of api.CachedKeggApi") 
     
    268281        return self.TAXONOMY.taxid 
    269282 
    270 #    def org_code(self): 
    271 #        if self.name is not None: 
    272 #            return self.name.split(",")[0] 
    273 #        else: 
    274 #            return self.entry.split(" ")[0] 
     283    def org_code(self): 
     284        # for backwards compatibility; return the `organism_code` 
     285        return self.organism_code 
    275286 
    276287 
     
    383394 
    384395class Genes(DBDataBase): 
     396    """ 
     397    Interface to the KEGG Genes database. 
     398 
     399    :param org_code: KEGG organism code (e.g. 'hsa'). 
     400    :type org_code: str 
     401 
     402    """ 
    385403    DB = None  # Needs to be set in __init__ 
    386404    ENTRY_TYPE = GeneEntry 
  • _bioinformatics/obiKEGG/entry/__init__.py

    r1734 r1736  
    1010from . import fields 
    1111from .parser import DBGETEntryParser 
     12 
     13 
     14# TODO: Remove the use of entry_decorate decorator 
     15# for constructing a DBEntry subclass, make fields 
     16# properties with __get__ method, and explicit assignment 
     17# and meaningful docstrings 
    1218 
    1319 
     
    6470    @property 
    6571    def entry_key(self): 
    66         """ Primary entry key used for querying. 
     72        """ 
     73        Primary entry key used for identifying the entry. 
    6774        """ 
    6875        return self.entry.split(" ", 1)[0] 
    6976 
    7077    def parse(self, text): 
     78        """ 
     79        Parse `text` string containing a formated DBGET entry. 
     80        """ 
    7181        parser = DBGETEntryParser() 
    7282        gen = parser.parse_string(text) 
     
    136146 
    137147    def format(self, section_indent=12): 
     148        """ 
     149        Return a DBGET formated string representation. 
     150        """ 
    138151        return "".join(f.format(section_indent) 
    139152                       for f in self.fields) 
  • _bioinformatics/obiKEGG/pathway.py

    r1734 r1736  
    11""" 
    2 KEGG Pathway (from kgml file) 
     2============ 
     3KEGG Pathway 
     4============ 
    35 
    46""" 
     
    3234 
    3335class Pathway(object): 
     36    """ 
     37    Class representing a KEGG Pathway (parsed from a "kgml" file) 
     38 
     39    :param str pathway_id: A KEGG pathway id (e.g. 'path:hsa05130') 
     40 
     41    """ 
    3442    KGML_URL_FORMAT = "http://www.genome.jp/kegg-bin/download?entry={pathway_id}&format=kgml" 
    3543 
     
    5563 
    5664    def _get_kgml(self): 
    57         """ Return an open kgml file for the pathway. 
     65        """ 
     66        Return an open kgml file for the pathway. 
    5867        """ 
    5968        from datetime import datetime, timedelta 
     
    8796 
    8897    def _get_image_filename(self): 
    89         """ Return a filename of a local copy of the pathway image 
     98        """ 
     99        Return a filename of a local copy of the pathway image 
    90100        """ 
    91101        # TODO: keep-alive (using httplib if it supports it) 
     
    126136 
    127137    def _local_kgml_filename(self): 
    128         """ Return the local kgml xml filename for the pathway. 
     138        """ 
     139        Return the local kgml xml filename for the pathway. 
    129140        """ 
    130141        local_filename = os.path.join(self.local_cache, 
     
    137148            self.graphics = () 
    138149            self.components = [] 
    139             self.graphics = dict(dom_element.getElementsByTagName("graphics")[0].attributes.items()) 
    140             self.components = [node.getAttribute("id") for node in dom_element.getElementsByTagName("component")] 
     150 
     151            graphics = dom_element.getElementsByTagName("graphics")[0] 
     152            self.graphics = dict(graphics.attributes.items()) 
     153 
     154            components = dom_element.getElementsByTagName("component") 
     155            self.components = [node.getAttribute("id") for node in components] 
    141156 
    142157    class reaction(object): 
    143158        def __init__(self, dom_element): 
    144159            self.__dict__.update(dom_element.attributes.items()) 
    145             self.substrates = [node.getAttribute("name") for node in dom_element.getElementsByTagName("substrate")] 
    146             self.products = [node.getAttribute("name") for node in dom_element.getElementsByTagName("product")] 
     160            self.substrates = [node.getAttribute("name") for node in 
     161                               dom_element.getElementsByTagName("substrate")] 
     162            self.products = [node.getAttribute("name") for node in 
     163                             dom_element.getElementsByTagName("product")] 
    147164 
    148165    class relation(object): 
    149166        def __init__(self, dom_element): 
    150167            self.__dict__.update(dom_element.attributes.items()) 
    151             self.subtypes = [node.attributes.items() for node in dom_element.getElementsByTagName("subtype")] 
     168            self.subtypes = [node.attributes.items() for node in 
     169                             dom_element.getElementsByTagName("subtype")] 
    152170 
    153171    @cached_method 
     
    157175    @property 
    158176    def name(self): 
     177        """ 
     178        Pathway name/id (e.g. "path:hsa05130") 
     179        """ 
    159180        return self.pathway_attributes().get("name") 
    160181 
    161182    @property 
    162183    def org(self): 
     184        """ 
     185        Pathway organism code (e.g. 'hsa') 
     186        """ 
    163187        return self.pathway_attributes().get("org") 
    164188 
    165189    @property 
    166190    def number(self): 
     191        """ 
     192        Pathway number as a string (e.g. '05130') 
     193        """ 
    167194        return self.pathway_attributes().get("number") 
    168195 
    169196    @property 
    170197    def title(self): 
     198        """ 
     199        Pathway title string. 
     200        """ 
    171201        return self.pathway_attributes().get("title") 
    172202 
    173203    @property 
    174204    def image(self): 
     205        """ 
     206        URL of the pathway image. 
     207        """ 
    175208        return self.pathway_attributes().get("image") 
    176209 
    177210    @property 
    178211    def link(self): 
     212        """ 
     213        URL to a pathway on the KEGG web site. 
     214        """ 
    179215        return self.pathway_attributes().get("link") 
    180216 
     
    214250 
    215251    def __iter__(self): 
    216         """ Iterate over all elements in the pathway 
     252        """ 
     253        Iterate over all elements in the pathway. 
    217254        """ 
    218255        return iter(self.all_elements()) 
    219256 
    220257    def __contains__(self, element): 
    221         """ Retrurn true if element in the pathway 
     258        """ 
     259        Return ``True`` if element in the pathway. 
    222260        """ 
    223261        return element in self.all_elements() 
     
    231269    @cached_method 
    232270    def all_elements(self): 
    233         """ Return all elements 
     271        """ 
     272        Return all elements 
    234273        """ 
    235274        return reduce(list.__add__, 
     
    246285    @cached_method 
    247286    def genes(self): 
    248         """ Return all genes on the pathway 
     287        """ 
     288        Return all genes on the pathway. 
    249289        """ 
    250290        return self._get_entries_by_type("gene") 
     
    252292    @cached_method 
    253293    def compounds(self): 
    254         """ Return all compounds on the pathway 
     294        """ 
     295        Return all compounds on the pathway. 
    255296        """ 
    256297        return self._get_entries_by_type("compound") 
     
    258299    @cached_method 
    259300    def enzymes(self): 
    260         """ Return all enzymes on the pathway 
     301        """ 
     302        Return all enzymes on the pathway. 
    261303        """ 
    262304        return self._get_entries_by_type("enzyme") 
     
    264306    @cached_method 
    265307    def orthologs(self): 
    266         """ Return all orthologs on the pathway 
     308        """ 
     309        Return all orthologs on the pathway. 
    267310        """ 
    268311        return self._get_entries_by_type("ortholog") 
     
    270313    @cached_method 
    271314    def maps(self): 
    272         """ Return all linked maps on the pathway 
     315        """ 
     316        Return all linked maps on the pathway. 
    273317        """ 
    274318        return self._get_entries_by_type("map") 
     
    276320    @cached_method 
    277321    def groups(self): 
    278         """ Return all groups on the pathway 
     322        """ 
     323        Return all groups on the pathway. 
    279324        """ 
    280325        return self._get_entries_by_type("ortholog") 
    281326 
    282327    def get_image(self): 
    283         """ Return an image of the pathway 
     328        """ 
     329        Return an local filesystem path to an image of the pathway. The image 
     330        will be downloaded if not already cached. 
    284331        """ 
    285332        return self._get_image_filename() 
     
    287334    @classmethod 
    288335    def list(cls, organism): 
     336        """ 
     337        List all pathways for KEGG organism code `organism`. 
     338        """ 
    289339        kegg = api.CachedKeggApi() 
    290340        return kegg.list_pathways(organism) 
  • docs/rst/index.rst

    r1674 r1736  
    2424.. toctree:: 
    2525   :maxdepth: 1 
     26 
     27   reference/kegg.rst 
    2628 
    2729Installation 
Note: See TracChangeset for help on using the changeset viewer.