Merge pull request #24 from biolink/issue-17

Issue 17

docs/inputs.rst

@@ -84,12 +84,14 @@ of storing sets of associations.
 
 .. currentmodule:: ontobio.assoc_factory
 
-Code example, fetching complete associations:
+Code example: parse all associations from a GAF, and filter according
+to provider:
 
 .. code-block:: python
 
     p = GafParser()
     assocs = p.parse(open(POMBASE,"r"))
+    pombase_assocs = [a for a in assocs if a['provided_by'] == 'UniProt']
 
 Code example, creating `AssociationSet` objects, using an :class:`AssociationSetFactory`
 

ontobio/io/gafparser.py

@@ -149,16 +149,23 @@ class AssocParser():
     """
 
     def parse(self, file, outfile=None):
-        """
-        Parse a file.
+        """Parse a line-oriented association file into a list of association dict objects
 
+        Note the returned list is of dict objects. TODO: These will
+        later be specified using marshmallow and it should be possible
+        to generate objects
+        
         Arguments
         ---------
-
-        - file : http URL, filename or `file-like-object`, for input assoc file
-
-        - outfile : a `file-like-object`. if specified, file-like objects will be written here
-
+        file : file or string
+            The file is parsed into association objects. Can be a http URL, filename or `file-like-object`, for input assoc file
+        outfile : file
+            Optional output file in which processed lines are written. This a file or `file-like-object`
+
+        Return
+        ------
+        list
+            Associations generated from the file
         """
         file = self._ensure_file(file)
         assocs = []
@@ -332,9 +339,22 @@ def skim(self, file):
             tuples.append( (id,None,t) )
         return tuples
 
-    def parse_line(self, line):
-        """
-        Parses a single line of a GPAD
+    def parse_line(self, line):            
+        """Parses a single line of a GPAD.
+
+        Return a tuple `(processed_line, associations)`. Typically
+        there will be a single association, but in some cases there
+        may be none (invalid line) or multiple (disjunctive clause in
+        annotation extensions)
+
+        Note: most applications will only need to call this directly if they require fine-grained control of parsing. For most purposes,
+        :method:`parse_file` can be used over the whole file
+
+        Arguments
+        ---------
+        line : str
+            A single tab-seperated line from a GPAD file
+
         """
         vals = line.split("\t")
         [db,
@@ -428,6 +448,20 @@ def skim(self, file):
     def parse_line(self, line, class_map=None, entity_map=None):
         """
         Parses a single line of a GAF
+
+        Return a tuple `(processed_line, associations)`. Typically
+        there will be a single association, but in some cases there
+        may be none (invalid line) or multiple (disjunctive clause in
+        annotation extensions)
+
+        Note: most applications will only need to call this directly if they require fine-grained control of parsing. For most purposes,
+        :method:`parse_file` can be used over the whole file
+
+        Arguments
+        ---------
+        line : str
+            A single tab-seperated line from a GPAD file
+
         """
         config = self.config
 
@@ -626,7 +660,21 @@ def __init__(self,config=AssocParserConfig()):
 
     def parse_line(self, line, class_map=None, entity_map=None):
         """
-        Parses a single line of a HPOA
+        Parses a single line of a HPOA file
+
+        Return a tuple `(processed_line, associations)`. Typically
+        there will be a single association, but in some cases there
+        may be none (invalid line) or multiple (disjunctive clause in
+        annotation extensions)
+
+        Note: most applications will only need to call this directly if they require fine-grained control of parsing. For most purposes,
+        :method:`parse_file` can be used over the whole file
+
+        Arguments
+        ---------
+        line : str
+            A single tab-seperated line from a GPAD file
+
         """
         config = self.config