sh done

doc/index.rst

@@ -7,7 +7,7 @@ Limix's documentation
    :name: mastertoc
    :maxdepth: 2
 
-   installation
+   install
    io
    qc
    qtl
@@ -16,7 +16,6 @@ Limix's documentation
    cli
    stats
    api
-   dev
 
 Comments and bugs
 =================

doc/installation.rst → doc/install.rst

@@ -1,17 +1,17 @@
-************
-Installation
-************
+*******
+Install
+*******
 
 
 Pip
----
+===
 
 .. code:: bash
 
     pip install limix
 
 Conda
------
+=====
 
 .. code:: bash
 

doc/qtl.rst

@@ -613,4 +613,4 @@ Here is an example.
            205(3), 1063-1078.
 .. [Wh14]  White, H. (2014). Asymptotic theory for econometricians. Academic press.
 .. [Ho13]  Hoffman, G. E. (2013). Correcting for population structure and kinship using
-           the linear mixed model: theory and extensions. PloS one, 8(10), e75707.
+           the linear mixed model: theory and extensions. PloS one, 8(10), e75707.

limix/_cli/extract.py

@@ -8,9 +8,6 @@
 @click.option(
     "--verbose/--quiet", "-v/-q", help="Enable or disable verbose mode.", default=True
 )
-@click.option(
-    "--dest", help="Destination path.", default=".", type=click.Path(exists=True)
-)
-def extract(ctx, filepath, dest, verbose):
+def extract(ctx, filepath, verbose):
     """Extract a file."""
-    limix.sh.extract(filepath, dest=dest, verbose=verbose)
+    limix.sh.extract(filepath, verbose=verbose)

limix/_example/_example.py

@@ -84,14 +84,15 @@ def __init__(self, filenames):
         import tempfile
         import os
         from os.path import join
+        from limix.sh._user_dir import user_cache_dir
         import limix
 
         self._unlist = False
         if not isinstance(filenames, (tuple, list)):
             filenames = [filenames]
             self._unlist = True
 
-        self._orig_folder = join(limix.sh.user_cache_dir(), "examples")
+        self._orig_folder = join(user_cache_dir(), "examples")
         limix.sh.makedirs(self._orig_folder)
 
         for fn in filenames:

limix/qtl/_iscan.py

@@ -9,6 +9,86 @@
 
 
 def iscan(G, y, lik="normal", K=None, M=None, idx=None, E0=None, E1=None, verbose=True):
+    r"""
+    Single-trait association with interaction test via generalized linear mixed models.
+
+    The general formulae for normally distributed traits is
+
+    .. math::
+
+        𝐲 = 𝙼𝛂 + (𝙶⊙𝙴₀)𝛃₀ + (𝙶⊙𝙴₁)𝛃₁ + 𝐮 + 𝛆,\\
+        \text{where}~~ 𝐮∼𝓝(𝟎, 𝓋₀𝙺) ~~\text{and}~~ 𝛆∼𝓝(𝟎, 𝓋₁𝙸).
+
+    The operator ⊙ works as follows:
+
+    .. math::
+
+        𝙰⊙𝙱 = [𝙰₀𝙱₀ ~~...~~ 𝙰₀𝙱ₙ ~~ 𝙰₁𝙱₀ ~~...~~ 𝙰₁𝙱ₙ ~~...~~ 𝙰ₘ𝙱ₙ]
+
+    The covariates is enconded in matrix 𝙼 while the candidate set is enconded in matrix
+    𝙶. The parameters are the effect sizes 𝛂, 𝛃₀, and 𝛃₁, and the variances 𝓋₀ and 𝓋₁.
+
+    It performs likelihood-ratio tests for the following cases, where the first
+    hypothesis is the null one while the second hypothesis is the alternative one:
+
+    - H₀ vs H₁: testing for vec(𝛃₀) ≠ 𝟎 while vec(𝛃₁) = 𝟎
+    - H₀ vs H₂: testing for [vec(𝛃₀) vec(𝛃₁)] ≠ 𝟎
+    - H₁ vs H₂: testing for vec(𝛃₁) ≠ 𝟎
+
+    It also supports generalized linear mixed models (GLMM). In this case, the following
+    likelihoods are implemented:
+    - Bernoulli
+    - Probit
+    - Binomial
+    - Poisson
+
+    Formally, let p(𝜇) be one of the supported probability distributions where 𝜇 is
+    its mean. The H₀ model is defined as follows:
+
+    .. math::
+
+        yᵢ ∼ p(𝜇ᵢ=g(zᵢ)) ~~\text{for}~~ 𝐳 ∼ 𝓝(𝙼𝛂 + (𝙶⊙𝙴₀)𝛃₀ + (𝙶⊙𝙴₁)𝛃₁, 𝓋₀𝙺 + 𝓋₁𝙸).
+
+    g(⋅) is the corresponding canonical link function for the Bernoulli, Binomial, and
+    Poisson likelihoods. The Probit likelihood, on the other hand, is a Bernoulli
+    likelihood with probit link function.
+
+    Parameters
+    ----------
+    G : n×m array_like
+        Genetic candidates.
+    Y : n×p array_like
+        Rows are samples and columns are phenotypes.
+    lik : tuple, "normal", "bernoulli", "probit", "binomial", "poisson"
+        Sample likelihood describing the residual distribution.
+        Either a tuple or a string specifying the likelihood is required. The Normal,
+        Bernoulli, Probit, and Poisson likelihoods can be selected by providing a
+        string. Binomial likelihood on the other hand requires a tuple because of the
+        number of trials: ``("binomial", array_like)``. Defaults to ``"normal"``.
+    K : n×n array_like
+        Sample covariance, often the so-called kinship matrix.
+    M : n×c array_like
+        Covariates matrix.
+    idx : list
+        List of candidate indices that defines the set of candidates to be used in the
+        tests.
+    E0 : array_like
+        Matrix representing the first environment.
+    E1 : array_like
+        Matrix representing the second environment.
+    verbose : bool, optional
+        ``True`` to display progress and summary; ``False`` otherwise.
+
+    Returns
+    -------
+    result : :class:`limix.qtl._result.IScanResult`
+        P-values, log of marginal likelihoods, effect sizes, and associated statistics.
+
+    Notes
+    -----
+    It will raise a ``ValueError`` exception if non-finite values are passed. Please,
+    refer to the :func:`limix.qc.mean_impute` function for missing value imputation.
+    """
     from numpy_sugar.linalg import economic_qs
     from xarray import concat
     from numpy import asarray, empty, ones

limix/sh/__init__.py

@@ -1,8 +1,6 @@
 from ._extract import extract
 from ._file import remove
-from ._dir import makedirs
 from ._hash import filehash
 from ._url import download
-from ._user_dir import user_cache_dir
 
-__all__ = ["filehash", "download", "extract", "remove", "user_cache_dir", "makedirs"]
+__all__ = ["filehash", "download", "extract", "remove"]

limix/sh/_extract.py

@@ -1,8 +1,17 @@
 from .._display import session_line
 
 
-# TODO: document
-def extract(filepath, verbose=True, dest="."):
+def extract(filepath, verbose=True):
+    """
+    Extract a compressed file.
+
+    Parameters
+    ----------
+    filepath : str
+        File path.
+    verbose : bool, optional
+        ``True`` for displaying progress. Defaults to ``True``.
+    """
     formats_order = _best_order(filepath)
 
     err_msgs = []
@@ -17,7 +26,7 @@ def extract(filepath, verbose=True, dest="."):
         raise RuntimeError(f"Could not extract `{filepath}`.\n" + "\n".join(err_msgs))
 
 
-def _extract_tar(filepath, dest="."):
+def _extract_tar(filepath):
     import tarfile
 
     tar = tarfile.open(filepath)
@@ -27,7 +36,7 @@ def _extract_tar(filepath, dest="."):
     return filepath
 
 
-def _extract_bz2(filepath, dest="."):
+def _extract_bz2(filepath):
     import bz2
     import os
 

limix/sh/_file.py

@@ -1,4 +1,12 @@
 def remove(filepath):
+    """
+    Remove file.
+
+    Parameters
+    ----------
+    filepath : str
+        File path.
+    """
     import os
 
     return os.remove(filepath)

limix/sh/_hash.py

@@ -1,8 +1,17 @@
-from __future__ import division
+def filehash(filepath):
+    """
+    Compute sha256 from a given file.
 
+    Parameters
+    ----------
+    filepath : str
+        File path.
 
-def filehash(filepath):
-    r""" Compute sha256 from a given file. """
+    Returns
+    -------
+    sha256 : str
+        Sha256 of a given file.
+    """
     import hashlib
 
     BUF_SIZE = 65536

limix/sh/_url.py

@@ -1,36 +1,42 @@
-import sys
-
 from .._display import session_line
 
-PY2 = sys.version_info < (3,)
-
 
 def download(url, dest=None, verbose=True):
+    """
+    Download file.
+
+    Parameters
+    ----------
+    url : str
+        Url to the file.
+    dest : str, optional
+        File destination. The current working directory is used if ``None`` is passed.
+        Defaults to ``None``.
+    verbose : bool, optional
+        ``True`` for displaying progress. Defaults to ``True``.
+
+    Returns
+    -------
+    filepath : str
+        File path to the downloaded file.
+    """
     import os
-
-    if PY2:
-        from urllib import urlretrieve
-    else:
-        from urllib.request import urlretrieve
+    from urllib.request import urlretrieve
 
     if dest is None:
         dest = os.getcwd()
 
     filepath = os.path.join(dest, _filename(url))
 
-    with session_line("Downloading {}... ".format(url), disable=not verbose):
+    with session_line(f"Downloading {url}... ", disable=not verbose):
         urlretrieve(url, filepath)
 
     return filepath
 
 
 def _filename(url):
     import os
-
-    if PY2:
-        from urlparse import urlparse
-    else:
-        from urllib.parse import urlparse
+    from urllib.parse import urlparse
 
     a = urlparse(url)
     return os.path.basename(a.path)