finally

hail/python/hail/docs/_templates/_autosummary/class2.rst

@@ -4,7 +4,6 @@
 
 .. autoclass:: {{ objname }}()
     :members:
-    :show-inheritance:
     :special-members:
     :inherited-members:
     :no-undoc-members:

hail/python/hail/docs/api.rst

@@ -46,6 +46,8 @@ Top-Level Functions
 ~~~~~~~~~~~~~~~~~~~
 
 .. autofunction:: hail.init
+.. autofunction:: hail.asc
+.. autofunction:: hail.desc
 .. autofunction:: hail.stop
 .. autofunction:: hail.spark_context
 .. autofunction:: hail.default_reference

hail/python/hail/docs/conf.py

@@ -29,7 +29,7 @@
 
 # -- General configuration ------------------------------------------------
 
-# nitpicky = True
+nitpicky = True
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #
@@ -90,6 +90,7 @@
                         ]
 # autoclass_content = "both"
 autodoc_default_flags = ['members', 'undoc-members']
+autodoc_typehints = 'none'
 
 napoleon_use_rtype = False
 napoleon_use_param = False
@@ -99,6 +100,7 @@
     'PySpark': ('https://spark.apache.org/docs/latest/api/python/', None),
     'Bokeh': ('https://docs.bokeh.org/en/1.2.0/', None),
     'numpy': ('https://numpy.org/doc/stable/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy-1.3.3/reference', None),
     'pandas': ('https://pandas.pydata.org/docs/', None)}
 
 # Add any paths that contain templates here, relative to this directory.

hail/python/hail/docs/experimental/vcf_combiner.rst

@@ -195,7 +195,7 @@ Functions
 ~~~~~~~~~
 
 There are a number of functions for working with sparse data. Of particular
-importance is :func:`densify`, which transforms a sparse matrix table to a dense
+importance is :func:`~.densify`, which transforms a sparse matrix table to a dense
 project-VCF-like matrix table on the fly. While computationally expensive, this
 operation is necessary for many downstream analyses, and should be thought of as
 roughly costing as much as reading a matrix table created by importing a dense

hail/python/hail/docs/functions/core.rst

@@ -39,5 +39,10 @@ Core language functions
 
 .. currentmodule:: hail.expr.builders
 
-.. autoclass:: CaseBuilder
-.. autoclass:: SwitchBuilder
+.. autosummary::
+    :nosignatures:
+    :toctree: ./
+    :template: class.rst
+
+    CaseBuilder
+    SwitchBuilder

hail/python/hail/docs/guides/api.rst

@@ -16,4 +16,4 @@ Writing output of :meth:`.Table.show` to log file
 
         >>> ht.show(handler=lambda x: logging.info(x))  # doctest: +SKIP
 
-:**dependencies**: :func:`.Table.show`, :meth:`.Expression.show`
+:**dependencies**: :meth:`.Table.show`, :meth:`.Expression.show`

hail/python/hail/docs/nd/index.rst

@@ -21,6 +21,7 @@ As much as possible, we try to mimic the numpy array interface.
     full
     zeros
     ones
+    diagonal
     qr
     svd
     inv
@@ -35,6 +36,7 @@ As much as possible, we try to mimic the numpy array interface.
 .. autofunction:: full
 .. autofunction:: zeros
 .. autofunction:: ones
+.. autofunction:: diagonal
 .. autofunction:: qr
 .. autofunction:: svd
 .. autofunction:: inv

hail/python/hail/docs/overview/expressions.rst

@@ -58,9 +58,8 @@ an expression representing the computation of ``x + y``, but not the actual
 value.
 
 To peek at the value of this computation, there are two options:
-:meth:`.Expression.eval`, which returns a Python value, and
-:meth:`.Expression.show`, which prints a human-readable representation of an
-expression.
+:func:`~hail.expr.eval`, which returns a Python value, and :meth:`.Expression.show`,
+which prints a human-readable representation of an expression.
 
     >>> hl.eval(z)
     11
@@ -154,7 +153,7 @@ and ``~``.
     >>> ~s1
     <BooleanExpression of type bool>
 
-Remember that you can use :meth:`.Expression.eval` to evaluate the expression.
+Remember that you can use :func:`~hail.expr.eval`: to evaluate the expression.
 
     >>> hl.eval(~s1)
     True
@@ -215,12 +214,12 @@ For example, we might want to return ``1`` if ``x < -1``, ``2`` if
     ...   .or_missing())
     <Int32Expression of type int32>
 
-Notice that this expression ends with a call to :meth:`.CaseBuilder.or_missing`,
+Notice that this expression ends with a call to :meth:`~hail.expr.builders.CaseBuilder.or_missing`,
 which means that if none of the conditions are met, a missing value is returned.
 
 Cases started with :func:`.case` can end with a call to
-:meth:`.CaseBuilder.or_missing`, :meth:`.CaseBuilder.default`, or
-:meth:`.CaseBuilder.or_error`, depending on what you want to happen if none
+:meth:`~hail.expr.builders.CaseBuilder.or_missing`, :meth:`~hail.expr.builders.CaseBuilder.default`, or
+:meth:`~hail.expr.builders.CaseBuilder.or_error`, depending on what you want to happen if none
 of the *when* clauses are met.
 
 It's important to note that missingness propagates up in Hail, so if the value
@@ -241,8 +240,8 @@ Finally, Hail has the :func:`.switch` function to build a conditional tree based
 on the value of an expression. In the example below, ``csq`` is a
 :class:`.StringExpression` representing the functional consequence of a
 mutation. If ``csq`` does not match one of the cases specified by
-:meth:`.SwitchBuilder.when`, it is set to missing with
-:meth:`.SwitchBuilder.or_missing`. Other switch statements are documented in the
+:meth:`~hail.expr.builders.SwitchBuilder.when`, it is set to missing with
+:meth:`~hail.expr.builders.SwitchBuilder.or_missing`. Other switch statements are documented in the
 :class:`.SwitchBuilder` class.
 
     >>> csq = hl.str('nonsense')
@@ -279,7 +278,7 @@ don't satisfy a condition:
     <Float64Expression of type float64>
 
 The Python representation of a missing value is ``None``. For example, if
-we define ``cnull`` to be a missing value with type :class:`.tcall`, calling
+we define ``cnull`` to be a missing value with type :obj:`.tcall`, calling
 the method `is_het` will return ``None`` and not ``False``.
 
     >>> cnull = hl.null('call')
@@ -293,4 +292,4 @@ In addition to the methods exposed on each :class:`.Expression`, Hail also has
 numerous functions that can be applied to expressions, which also return an
 expression.
 
-Take a look at the :ref:`sec-functions` page for full documentation.
+Take a look at the :ref:`sec-functions` page for full documentation.

hail/python/hail/docs/overview/matrix_table.rst

@@ -394,10 +394,10 @@ Interacting with Matrix Tables Locally
 
 Some useful methods to interact with matrix tables locally are
 :meth:`.MatrixTable.describe`, :meth:`.MatrixTable.head`, and
-:meth:`.MatrixTable.sample`. `describe` prints out the schema for all row
+:meth:`.MatrixTable.sample_rows`. `describe` prints out the schema for all row
 fields, column fields, entry fields, and global fields as well as the row keys
 and column keys. `head` returns a new matrix table with only the first N rows.
-`sample` returns a new matrix table where the rows are randomly sampled with
+`sample_rows` returns a new matrix table where the rows are randomly sampled with
 frequency `p`.
 
 

hail/python/hail/docs/scans.rst

@@ -64,7 +64,7 @@ Scans over column fields can be done in a similar manner.
 .. DANGER::
 
     Computing the result of certain aggregators, such as
-    :func:`.agg.hardy_weinberg_test`, can be very expensive when done
+    :func:`~.aggregators.hardy_weinberg_test`, can be very expensive when done
     for every row in a scan."
 
 See the :ref:`sec-aggregators` module for documentation on the behavior

hail/python/hail/docs/types.rst

@@ -1,3 +1,5 @@
+.. _hail_types:
+
 Types
 =====
 
@@ -66,5 +68,9 @@ a :class:`.tstruct` with each option:
 .. autoclass:: tstruct
 .. autoclass:: ttuple
 .. autodata:: hail.expr.types.tcall
+
 .. autoclass:: tlocus
+
+    .. autoattribute:: reference_genome
+
 .. autoclass:: tinterval

hail/python/hail/experimental/expressions.py

@@ -22,7 +22,7 @@ def write_expression(expr, path, overwrite=False):
    Parameters
    ----------
 
-   expr : :class:`Expression`
+   expr : :class:`~.Expression`
        Expression to write.
    path : :class:`str`
        Path to which to write expression.
@@ -44,7 +44,7 @@ def write_expression(expr, path, overwrite=False):
 
 @typecheck(path=str)
 def read_expression(path):
-    """Read an :class:`Expression` written with :meth:`.experimental.write_expression`.
+    """Read an :class:`~.Expression` written with :func:`.experimental.write_expression`.
 
    Example
    -------
@@ -60,6 +60,6 @@ def read_expression(path):
 
    Returns
    -------
-   :class:`Expression`
+   :class:`~.Expression`
     """
     return hl.read_table(path).index_globals().expr

hail/python/hail/experimental/ld_score_regression.py

@@ -91,13 +91,13 @@ def ld_score_regression(weight_expr,
     Notes
     -----
     The ``exprs`` provided as arguments to :func:`.ld_score_regression`
-    must all be from the same object, either a :class:`Table` or a
-    :class:`MatrixTable`.
+    must all be from the same object, either a :class:`~.Table` or a
+    :class:`~.MatrixTable`.
 
     **If the arguments originate from a table:**
 
     *  The table must be keyed by fields ``locus`` of type
-       :class:`.tlocus` and ``alleles``, a :py:data:`.tarray` of
+       :class:`.tlocus` and ``alleles``, a :class:`.tarray` of
        :py:data:`.tstr` elements.
     *  ``weight_expr``, ``ld_score_expr``, ``chi_sq_exprs``, and
        ``n_samples_exprs`` are must be row-indexed fields.
@@ -119,7 +119,7 @@ def ld_score_regression(weight_expr,
        (rows) by phenotypes (columns).
     *  The rows of the matrix table must be keyed by fields
        ``locus`` of type :class:`.tlocus` and ``alleles``,
-       a :py:data:`.tarray` of :py:data:`.tstr` elements.
+       a :class:`.tarray` of :py:data:`.tstr` elements.
     *  The columns of the matrix table must be keyed by a field
        of type :py:data:`.tstr` that uniquely identifies phenotypes
        represented in the matrix table. The column key must be a single
@@ -134,7 +134,7 @@ def ld_score_regression(weight_expr,
        :func:`.ld_score_regression` will have values corresponding to the
        column keys of the input matrix table.
 
-    This function returns a :class:`Table` with one row per set of summary
+    This function returns a :class:`~.Table` with one row per set of summary
     statistics passed to the ``chi_sq_exprs`` argument. The following
     row-indexed fields are included in the table:
 
@@ -197,7 +197,7 @@ def ld_score_regression(weight_expr,
 
     Returns
     -------
-    :class:`.Table`
+    :class:`~.Table`
         Table keyed by ``phenotype`` with intercept and heritability estimates
         for each phenotype passed to the function."""
 

hail/python/hail/experimental/phase_by_transmission.py

@@ -42,7 +42,7 @@ def phase_by_transmission(
 
     Note
     ----
-    :meth:`.experimental.phase_trio_matrix_by_transmission` provides a convenience wrapper for phasing a trio matrix.
+    :func:`~.phase_trio_matrix_by_transmission` provides a convenience wrapper for phasing a trio matrix.
 
     Parameters
     ----------
@@ -304,7 +304,7 @@ def explode_trio_matrix(tm: hl.MatrixTable, col_keys: List[str] = ['s'], keep_tr
     Note
     ----
     This assumes that the input MatrixTable is a trio MatrixTable (similar to
-    the result of :meth:`.methods.trio_matrix`) Its entry schema has to contain
+    the result of :func:`~.trio_matrix`) Its entry schema has to contain
     'proband_entry`, `father_entry` and `mother_entry` all with the same type.
     Its column schema has to contain 'proband`, `father` and `mother` all with
     the same type.

hail/python/hail/experimental/plots.py

@@ -39,7 +39,7 @@ def plot_roc_curve(ht, scores, tp_label='tp', fp_label='fp', colors=None, title=
 
     Returns
     -------
-    :obj:`tuple` of :class:`bokeh.plotting.Figure` and :obj:`list` of :class:`str`
+    :obj:`tuple` of :class:`bokeh.plotting.figure.Figure` and :obj:`list` of :class:`str`
         Figure, and list of AUCs corresponding to scores.
     """
     if colors is None:
@@ -91,7 +91,7 @@ def hail_metadata(t_path):
 
     Returns
     -------
-    :class:`bokeh.plotting.Figure` or :class:`bokeh.models.layouts.Column`
+    :class:`bokeh.plotting.figure.Figure` or :class:`bokeh.models.layouts.Column`
     """
     def get_rows_data(rows_files):
         file_sizes = []

hail/python/hail/experimental/time.py

@@ -45,7 +45,7 @@ def strftime(format, time, zone_id):
 
     Returns
     -------
-    :class:`StringExpression`
+    :class:`~.StringExpression`
         A string of the specified format based on the requested time.
     """
     return _func("strftime", hl.tstr, format, time, zone_id)
@@ -92,7 +92,7 @@ def strptime(time, format, zone_id):
 
     Returns
     -------
-    :class:`Int64Expression`
+    :class:`~.Int64Expression`
         The Unix timestamp associated with the given time string.
     """
     return _func("strptime", hl.tint64, time, format, zone_id)

hail/python/hail/experimental/vcf_combiner/sparse_split_multi.py

@@ -7,7 +7,7 @@ def sparse_split_multi(sparse_mt, *, filter_changed_loci=False):
     Analogous to :func:`.split_multi_hts` (splits entry fields) for sparse
     representations.
 
-    Takes a dataset formatted like the output of :func:`.vcf_combiner`. The
+    Takes a dataset formatted like the output of :func:`.run_combiner`. The
     splitting will add `was_split` and `a_index` fields, as :func:`.split_multi`
     does. This function drops the `LA` (local alleles) field, as it re-computes
     entry fields based on the new, split globals alleles.
@@ -59,7 +59,7 @@ def sparse_split_multi(sparse_mt, *, filter_changed_loci=False):
 
     - `PL` array elements are calculated from the minimum `LPL` value for all
       allele pairs that downcode to the desired one. (This logic is identical to
-      the `PL` logic in :func:`.split_mult_hts`.) If a row has an alternate
+      the `PL` logic in :func:`~.split_multi_hts`.) If a row has an alternate
       allele but it is not present in `LA`, the `PL` field is set to missing.
       The `PL` for `ref/<NON_REF>` in that case can be drawn from `RGQ`.
 

hail/python/hail/expr/aggregators/aggregators.py

@@ -2,19 +2,19 @@
 from functools import wraps, update_wrapper
 
 import hail as hl
-from hail.expr.expressions import ExpressionException, Expression, \
-    ArrayExpression, SetExpression, BooleanExpression, Int64Expression, \
-    NumericExpression, DictExpression, StructExpression, Float64Expression, \
-    StringExpression, NDArrayNumericExpression, \
-    expr_any, expr_oneof, expr_array, expr_set, expr_bool, expr_numeric, \
-    expr_int32, expr_int64, expr_float64, expr_call, expr_str, expr_ndarray, \
-    unify_all, construct_expr, Indices, Aggregation, to_expr
-from hail.expr.types import hail_type, tint32, tint64, tfloat32, tfloat64, \
-    tbool, tcall, tset, tarray, tstruct, tdict, ttuple, tstr
+from hail.expr import (ExpressionException, Expression, ArrayExpression,
+                       SetExpression, BooleanExpression, Int64Expression, NumericExpression,
+                       DictExpression, StructExpression, Float64Expression, StringExpression,
+                       NDArrayNumericExpression, expr_any, expr_oneof, expr_array, expr_set,
+                       expr_bool, expr_numeric, expr_int32, expr_int64, expr_float64, expr_call,
+                       expr_str, expr_ndarray, unify_all, construct_expr, Indices, Aggregation,
+                       to_expr)
+from hail.expr.types import (hail_type, tint32, tint64, tfloat32, tfloat64,
+                             tbool, tcall, tset, tarray, tstruct, tdict, ttuple, tstr)
 from hail.expr.functions import rbind, float32, _quantile_from_cdf
 import hail.ir as ir
-from hail.typecheck import TypeChecker, typecheck_method, typecheck, \
-    sequenceof, func_spec, identity, nullable, oneof
+from hail.typecheck import (TypeChecker, typecheck_method, typecheck,
+                            sequenceof, func_spec, identity, nullable, oneof)
 from hail.utils import wrap_to_list
 from hail.utils.java import Env
 

hail/python/hail/expr/builders.py

@@ -42,8 +42,9 @@ class SwitchBuilder(ConditionalBuilder):
     Notes
     -----
     All expressions appearing as the `then` parameters to
-    :meth:`~.SwitchBuilder.when` or :meth:`~.SwitchBuilder.default` method
-    calls must be the same type.
+    :meth:`~hail.expr.builders.SwitchBuilder.when` or
+    :meth:`~hail.expr.builders.SwitchBuilder.default` method calls must be the
+    same type.
 
     See Also
     --------
@@ -193,8 +194,9 @@ class CaseBuilder(ConditionalBuilder):
     Notes
     -----
     All expressions appearing as the `then` parameters to
-    :meth:`~.CaseBuilder.when` or :meth:`~.CaseBuilder.default` method calls
-    must be the same type.
+    :meth:`~hail.expr.builders.CaseBuilder.when` or
+    :meth:`~hail.expr.builders.CaseBuilder.default` method calls must be the
+    same type.
 
     Parameters
     ----------
@@ -299,7 +301,7 @@ def or_error(self, message):
 
         Parameters
         ----------
-        message : :class:`.Expression` of type :data:`tstr`
+        message : :class:`.Expression` of type :obj:`.tstr`
 
         Returns
         -------