Commits

Marko Toplak committed cb4e084

Fixes to arrayexpress documentation.

Comments (0)

Files changed (2)

docs/rst/reference/arrayexpress.rst

 `ArrayExpress`_ is a database of gene expression experiments
 that you can query and download.
 
-
 Retrieve the object representing experiment with accession E-TABM-25
 
-    >>> from Orange.bio import arrayexpress
-    >>> experiment = ArrayExpressExperiment("E-TABM-25")
-    >>> print experiment.accession
-    E-TABM-25
+>>> from Orange.bio import arrayexpress
+>>> experiment = ArrayExpressExperiment("E-TABM-25")
+>>> print experiment.accession
+E-TABM-25
 
-    >>> print experiment.name
-    Transcription profiling of aging in the primate brain
+>>> print experiment.name
+Transcription profiling of aging in the primate brain
 
-    >>> print experiment.species
-    ['Pan troglodytes']
+>>> print experiment.species
+['Pan troglodytes']
 
-    >>> print experiment.files
-    [{'kind': ...
+>>> print experiment.files
+[{'kind': ...
 
-    >>> # Retrieve the data matrix for experiment 'E-MEXP-2917'
-    >>> experiment = ArrayExpressExperiment("E-MEXP-2917")
-    >>> table = experiment.fgem_to_table()
+>>> # Retrieve the data matrix for experiment 'E-MEXP-2917'
+>>> experiment = ArrayExpressExperiment("E-MEXP-2917")
+>>> table = experiment.fgem_to_table()
 
 
-Low level Array Express query using REST services::
+Low level Array Express query using REST services:
 
-    >>> from Orange.bio import arrayexpress
-    >>> arrayexpress.query_experiments(accession='E-MEXP-31')
-    {u'experiments': ...
+>>> from Orange.bio import arrayexpress
+>>> arrayexpress.query_experiments(accession='E-MEXP-31')
+{u'experiments': ...
 
-    >>> arrayexpress.query_experiments(keywords='gliobastoma')
-    {u'experiments': ...
+>>> arrayexpress.query_experiments(keywords='gliobastoma')
+{u'experiments': ...
 
-    >>> arrayexpress.query_files(accession='E-MEXP-32', format="xml")
-    <xml.etree.ElementTree.ElementTree object ...
+>>> arrayexpress.query_files(accession='E-MEXP-32', format="xml")
+<xml.etree.ElementTree.ElementTree object ...
 
 .. note:: Currently querying ArrayExpress files only works with the xml format.
 
 .. autoclass:: SampleDataRelationship
    :members:
 
+.. autoclass:: InvestigationDesign
+   :members:
+
+
 Low-level querying with REST
 -----------------------------
 

orangecontrib/bio/arrayexpress.py

 
 class ArrayExpressConnection(object):
     """
-    A connection to the Array Express.
-
-    Used to construct a REST query and run it.
+    Constructs and runs REST query on ArrayExpress.
 
     :param address: Address of the ArrayExpress API.
-    :param timeout: Timeout for the socket connection.
+    :param timeout: Timeout for the connection.
 
     """
 
         return "&".join(parts)
 
     def query_url(self, what="experiments", **kwargs):
-        """Return a formated query URL for the query arguments.
+        """Return a formatted query URL for the query arguments.
 
         >>> conn.query_url(accession="E-MEXP-31")
         'http://www.ebi.ac.uk/arrayexpress/json/v2/experiments?accession=E-MEXP-31'
         return url
 
     def query_url_experiments(self, **kwargs):
-        """Return a formated experiments query URL for the query arguments
+        """Return query URL of formatted experiments for the query arguments.
         """
         return self.query_url("experiments", **kwargs)
 
     def query_url_files(self, **kwargs):
-        """ Return a formated experiments query URL for the query arguments
+        """ Return query URL of formatted experiments for the query arguments.
         """
         return self.query_url("files", **kwargs)
 
 
     def query_files(self, **kwargs):
         """Return an open stream to the files query results.
-           Takes the same arguments as the :obj:`query_experiments` function.
+           Takes the same arguments as the :obj:`query_files` function.
         """
         url = self.query_url_files(**kwargs)
         stream = self._cache_urlopen(url, timeout=self.timeout)
     def open_file(self, accession, kind="raw", ext=None):
         """ Return a file handle to experiment data.
         
-        Possible values for kind:
+        :param str accession:
+        :param str kind: Experiment data type.
+        
+        Possible values for the parameter `kind`:
             - raw: return the raw data if available
             - processed: return the processed data if available
             - biosamples: a png or svg design image
                       format="json", wholewords=None, connection=None):
     """ Query Array Express experiments.
 
-    :param keywords: A list of keywords to search (e.g. ['gliobastoma']
-    :param accession: Search by experiment accession (e.g. 'E-MEXP-31')
-    :param array: Search by array design name or accession (e.g. 'A-AFFY-33')
-    :param ef: Experimental factor (names of main variables of experiments)
-    :param efv: Experimental factor value (Has EFO expansion)
-    :param expdesign: Experiment design type. (e.g. ["dose", "response"])
-    :param exptype: Experiment type (e.g. 'RNA-Seq', has EFO expansion)
-    :param gxa: If True limit the results to experiments from the Gene
-        Expreission Atlas only.
-    :param pmid: Search by PubMed identifier
-    :param sa: Sample attribute values (e.g. 'fibroblast', has EFO expansion)
-    :param species: Search by species (e.g. 'Homo sapiens', has EFO expansion)
+    :param keywords: A list of keywords to search (e.g. ``['gliobastoma']``).
+    :param accession: Search by experiment accession (e.g. ``'E-MEXP-31'``).
+    :param array: Search by array design name or accession (e.g. ``'A-AFFY-33'``).
+    :param ef: Experimental factor (names of main variables of experiments).
+    :param efv: Experimental factor value (Has EFO expansion).
+    :param expdesign: Experiment design type (e.g. ``["dose", "response"]``).
+    :param exptype: Experiment type (e.g. 'RNA-Seq', has EFO expansion).
+    :param gxa: If True limit the results to the Gene Expression Atlas only.
+    :param pmid: Search by PubMed identifier.
+    :param sa: Sample attribute values (e.g. ``'fibroblast'``, has EFO expansion).
+    :param species: Search by species (e.g. ``'Homo sapiens'``, has EFO expansion)
+    :param expandefo: If True expand the search terms with all its child terms
+        in the Experimental Factor Ontology (EFO_) (e.g. ``keywords="cancer"``
+        will be expanded to include for synonyms and sub types of cancer).
+    :param directsub: If True return only experiments submitted directly to
+        Array Express; if False return only experiments imported from GEO
+        database; if None (default) return both.
+    :param assaycount: A two tuple (min, max) for filter on the number of
+        assays (e.g. (1, 5) will return only experiments with at least 1
+        and no more then 5 assays).
+    :param efcount: Filter on the number of experimental factors (e.g. (1, 5)).
+    :param sacount: Filter on the number of sample attribute categories.
+    :param rawcount: Filter on the number or raw files.
+    :param fgemcount: Filter on the number of final gene expression matrix
+        (processed data) files.
+    :param miamescore: Filter on the MIAME complience score (max 5).
+    :param date: Filter by release date.
 
-    :param expandefo: If True expand the search terms with all its child terms
-        in the Experimental Factor Ontology (EFO_) (e.g. keywords="cancer"
-        will be expanded to include for synonyms and sub types of cancer).
-    :param directsub: If True return only experiments submited directly to
-        Array Express else if False return only experiments imported from GEO
-        database (default None, return both)
-    :param assaycount: A two tuple (min, max) for filter on the number of
-        assays (e.g. (1, 5) will return only experiments with at least one
-        and no more then 5 assays).
-    :param efcount: Filter on the number of experimental factors (e.g. (1, 5))
-    :param sacount: Filter on the number of sample attribute categories
-    :param rawcount: Filter on the number or raw files
-    :param fgemcount: Filter on the number of final gene expression matrix
-        (processed data) files
-    :param miamescore: Filter on the MIAME complience score (max 5)
-    :param date: Filter by release date
-
-    Example ::
-
-        >>> query_experiments(species="Homo sapiens", ef="organism_part", efv="liver")
-        {u'experiments': ...
+    >>> query_experiments(species="Homo sapiens", ef="organism_part", efv="liver")
+    {u'experiments': ...
 
     .. _EFO: http://www.ebi.ac.uk/efo/
 
                 efcount=None, samplecount=None, rawcount=None,
                 fgemcount=None, miamescore=None, date=None,
                 format="json", wholewords=None, connection=None):
-    """Query Array Express files.
+    """Query Array Express files. See :obj:`query_experiments` for the
+    arguments.
 
-    Accepts the same arguments as :obj:`query_experiments`.
-
-    Example ::
-
-        >>> query_files(species="Mus musculus", ef="developmental_stage",
-        ...             efv="embryo", format="xml")
-        <xml.etree.ElementTree.ElementTree object ...
+    >>> query_files(species="Mus musculus", ef="developmental_stage",
+    ...             efv="embryo", format="xml")
+    <xml.etree.ElementTree.ElementTree object ...
 
     """
     if connection is None:
 
 
 """
-MAGE-TAB convinence functions, classes
-======================================
+MAGE-TAB convenience functions, classes
+=======================================
 """
 
 IDF_SINGLE_TAGS = \
 class InvestigationDesign(dict):
     r"""Investigation design (contains the contents of the .idf).
 
-    Example ::
-
-        >>> idf_file = StringIO(
-        ...     'Investigation Title\tfoo investigation\n' +
-        ...     'Experimental Design\tfubar\tsnafu\n' +
-        ...     'SDRF File\tfoobar.sdrf\n'
-        ... )
-        >>> idf = InvestigationDesign(idf_file)
-        >>> print idf.investigation_title
-        foo investigation
-        >>> print idf.experimental_design
-        ['fubar', 'snafu']
-        >>> print idf.sdrf_file
-        ['foobar.sdrf']
+    >>> idf_file = StringIO(
+    ...     'Investigation Title\tfoo investigation\n' +
+    ...     'Experimental Design\tfubar\tsnafu\n' +
+    ...     'SDRF File\tfoobar.sdrf\n'
+    ... )
+    >>> idf = InvestigationDesign(idf_file)
+    >>> print idf.investigation_title
+    foo investigation
+    >>> print idf.experimental_design
+    ['fubar', 'snafu']
+    >>> print idf.sdrf_file
+    ['foobar.sdrf']
 
     """
 
 
 class SampleDataRelationship(object):
     """Sample-Data Relationship (contains the contents of the .sdrf file).
+
     """
 
     # Nodes an edges
         self.rows = rows
 
     def transform_tag(self, tag):
-        """ Transform the tag into a proper python attribute name by
+        """ Transform the tag into a proper Python attribute name by
         replacing all spaces and special characters (e.g '[', ']' into
         underscores).
 
         return [r[index] for r in self.rows]
 
     def source(self):
-        """ Return the Source subsection
+        """ Return the Source subsection.
         """
         return self._subsection("Source Name")
 
     def source_name(self):
-        """ Return the Source Name subsection
+        """ Return the Source Name subsection.
         """
         return self._column("Source Name")
 
     def sample(self):
-        """ Return the Sample subsection
+        """ Return the Sample subsection.
         """
         return self._subsection("Sample Name")
 
         return self._column("Sample Name")
 
     def extract(self):
-        """ Return the Extract subsection
+        """ Return the Extract subsection.
         """
         return self._subsection("Extract Name")
 
     def extract_name(self):
-        """ Return the Extract Name subsection
+        """ Return the Extract Name subsection.
         """
         return self._column("Extract Name")
 
     def labeled_extract(self):
-        """ Return the Labeled Extract subsection
+        """ Return the Labeled Extract subsection.
         """
         return self._subsection("Labeled Extract Name")
 
     def labeled_extract_name(self):
-        """ Return the Labeled Extract Name subsection
+        """ Return the Labeled Extract Name subsection.
         """
         return self._column("Labeled Extract Name")
 
         return self._column("Hybridization Name")
 
     def assay(self):
-        """ Return the Assay subsection
+        """ Return the Assay subsection.
         """
         return self._subsection("Assay Name")
 
 
 
 class ArrayDesign(object):
+    """ Array design (contains the contents of the .adf file).
 
-    """ Array design (contains the contents of the .adf file).
     """
 
     def __init__(self, adf_file=None):
 
 
 def processed_matrix_to_orange(matrix_file, sdrf=None):
-    """ Load a single processed matrix file into an Orange.data.Table
-    instance.
+    """ Load a single processed matrix file into an :obj:`Orange.data.Table`.
     """
     import numpy
     import Orange
 
 
 def mage_tab_to_orange(idf_filename):
-    """Convert an MAGE-TAB annotated experiment into an Orange.data.Table
-    instance (assumes all the associated MAGE-TAB files are in the same
-    directory.
+    """Convert an MAGE-TAB annotated experiment into an 
+    :obj:`Orange.data.Table` (assumes all the associated MAGE-TAB 
+    files are in the same directory.
 
     """
     dirname = os.path.dirname(idf_filename)
 
 
 def hstack_tables(tables):
-    """ Stack the tables horizontaly.
+    """ Stack the tables horizontally.
     """
     import Orange
     max_len = max([len(table) for table in tables])
 class ArrayExpressExperiment(object):
 
     """
-    An convinience class representing an Array Express Experiment.
+    An convenience class representing an Array Express Experiment.
 
     >>> ae = ArrayExpressExperiment("E-MEXP-2917")
     >>> print ae.name
     >>> for file in ae.files:
     ...     print file["name"], file["url"]
     E-MEXP-2917...
-    >>> table = ae.fgem_to_table() # Retieve the experiment data table
+    >>> table = ae.fgem_to_table() # Retrieve the experiment data table
 
     :param str accession:
         The experiment accession id.
         self.files = [_dictify(file) for file in files]
 
     def _download_file(self, url, extract=True):
-        """ Download the `file` from the ArrayExpress saving it to a local
+        """ Download the `file` from the ArrayExpress into a local
         repository directory.
 
         """
                 raise ValueError("Unknown extension ('{0}').".format(basename))
 
     def _is_local(self, url):
-        """ Is the `url` stored in the local repository.
+        """ Is the `url` stored in the local repository?
         """
         return os.path.exists(self._local_filepath(url))
 
         return res
 
     def array_design(self):
-        """ Return a list of `ArrayDesign` instances used in this experiment.
+        """ Return a list of :obj:`ArrayDesign` instances used in this experiment.
         """
         files = [f for f in self.files if f.get("kind") == "adf" and
                  f.get("extension") == "txt"]
         return array_design
 
     def investigation_design(self):
-        """ Return an `InvestigationDesgin` instance for this experiment
+        """ Return an :obj:`InvestigationDesign` for this experiment.
         """
         files = [f for f in self.files if f.get("kind") == "idf" and \
                  f.get("extension") == "txt"]
 
     def sample_data_relationship(self):
         """
-        Return an `SampleDataRelationship` instance describing this experiment.
+        Return an :obj:`SampleDataRelationship` instance describing this experiment.
         """
         files = [f for f in self.files if f.get("kind") == "sdrf" and \
                  f.get("extension") == "txt"]
         return SampleDataRelationship(self._open(file.get("url")))
 
     def fgem_to_table(self):
-        """ Retrieve the processed matrix from the Array Express ftp
-        server and convert it to an :class:`Orange.data.Table` instance.
+        """ Retrieve the processed matrix from the Array Express FTP
+        server and convert it to a :class:`Orange.data.Table`.
 
         """
         assert(self.fgemdatafiles)