bs-python-utils 0.5.2__tar.gz → 0.8.0__tar.gz

{bs_python_utils-0.5.2 → bs_python_utils-0.8.0}/PKG-INFO

@@ -1,28 +1,26 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: bs-python-utils
-Version: 0.5.2
-Summary: my Python utilities
-Home-page: https://github.com/bsalanie/bs-python-utils
-Author: Bernard Salanie
-Author-email: bsalanie@columbia.edu
-Requires-Python: >=3.8,<4.0
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Requires-Dist: altair (>=4.2.2,<5.0.0)
-Requires-Dist: altair-saver (>=0.5.0,<0.6.0)
-Requires-Dist: emcee (>=3.1.4,<4.0.0)
-Requires-Dist: griffe (>=0.32.3,<0.33.0)
-Requires-Dist: matplotlib (>=3.7.1,<4.0.0)
-Requires-Dist: scikit-learn (>=1.2.2,<2.0.0)
-Requires-Dist: seaborn (>=0.12.2,<0.13.0)
-Requires-Dist: statsmodels (>=0.13.5,<0.14.0)
-Requires-Dist: vega-datasets (>=0.9.0,<0.10.0)
-Project-URL: Documentation, https://bsalanie.github.io/bs-python-utils/
-Project-URL: Repository, https://github.com/bsalanie/bs-python-utils
+Version: 0.8.0
+Summary: Add your description here
+Requires-Python: >=3.12
 Description-Content-Type: text/markdown
+Requires-Dist: altair>=5.5.0
+Requires-Dist: altair-saver>=0.5.0
+Requires-Dist: emcee>=3.1.6
+Requires-Dist: matplotlib>=3.10.6
+Requires-Dist: mkdocs>=1.6.1
+Requires-Dist: mkdocs-material>=9.6.20
+Requires-Dist: mkdocstrings-python>=1.18.2
+Requires-Dist: numpy>=2.3.3
+Requires-Dist: pandas>=2.3.2
+Requires-Dist: pre-commit>=4.3.0
+Requires-Dist: pytest>=8.4.2
+Requires-Dist: scikit-learn>=1.7.2
+Requires-Dist: scipy>=1.16.2
+Requires-Dist: seaborn>=0.13.2
+Requires-Dist: statsmodels>=0.14.5
+Requires-Dist: streamlit>=1.49.1
+Requires-Dist: vega-datasets>=0.9.0
 
 # bs-python-utils
 
@@ -32,33 +30,72 @@ Description-Content-Type: text/markdown
 
 [![Build status](https://img.shields.io/github/actions/workflow/status/bsalanie/bs-python-utils/main.yml?branch=main)](https://github.com/bsalanie/bs-python-utils/actions/workflows/main.yml?query=branch%3Amain) <!-- [![codecov](https://codecov.io/gh/bsalanie/bs-python-utils/branch/main/graph/badge.svg)](https://codecov.io/gh/bsalanie/bs-python-utils) --> <!-- [![Commit activity](https://img.shields.io/github/commit-activity/m/bsalanie/bs-python-utils)](https://img.shields.io/github/commit-activity/m/bsalanie/bs-python-utils) --> [![License](https://img.shields.io/github/license/bsalanie/bs-python-utils)](https://img.shields.io/github/license/bsalanie/bs-python-utils)
 
-My Python utilities.
+**My Python utilities**.
 
--   **Github repository**: <https://github.com/bsalanie/bs-python-utils/>
--   **Documentation** <https://bsalanie.github.io/bs-python-utils/>
+- **Github repository**: <https://github.com/bsalanie/bs-python-utils/>
+- **Documentation** <https://bsalanie.github.io/bs-python-utils/>
 
 ### Release notes
+
+#### 0.8 (October 14, 2025)
+Switched to `uv` for project management. Used Codex to clean up the code and generate more tests. Added the `examples` subdirectory.
+
+#### 0.7 (June 18, 2024)
+Added `make_lowertri` in `bsnputils`, and some utility code in `bs_plots`.
+
+#### 0.6.4 (November 26, 2023)
+Moved to Altair 5.0; made timing optional in `bs_opt`.
+
+#### 0.6.3 (November 26, 2023)
+Updated statsmodels dependency.
+
+#### 0.6.1 and 0.6.2 (November 18, 2023)
+Added a Matplotlib plot for discrete choice models, a boxplot for Altair, and a density plot for Seaborn.
+
+#### 0.6 (November 9, 2023)
+
+Added matrix heatmap plot in Altair and Streamlit utility code.
+
+#### 0.5.5 (October 23, 2023)
+
+Added `fstring***` in `bsutils`.
+
 #### 0.5.2 (August 16, 2023)
+
 Added two interpolation routines from values at the Chebyshev nodes in `chebyshev` module.
+
 #### 0.5.1 (August 14, 2023)
-Added two functions to draw random samples in  `bsstats` module.
+
+Added two functions to draw random samples in `bsstats` module.
+
 #### 0.5 (August 7, 2023)
+
 Added 1-dimensional root finding in `chebyshev` module.
+
 #### 0.4.2 (August 2, 2023)
+
 Updated the docs.
+
 #### 0.4.1 (July 23, 2023)
+
 Only print if verbose in bivariate quantiles.
+
 #### 0.4 (July 22, 2023)
+
 Added bivariate quantiles and ranks à la optimal transportation.
+
 #### 0.3 (July 21, 2023)
+
 Added in Numpy utils a function to set upper and lower triangle to a scalar;
 and `minimize_free` in `bs_opt`.
 
 #### 0.2 (July 17, 2023)
+
 Fixed printing in accelerated gradient descent.
 
 #### 0.1 (June 20, 2023)
-Added `grid_function` and the `chebyshev` module. 
+
+Added `grid_function` and the `chebyshev` module.
 
 #### 0.0.6 (May 9, 2023)
 

{bs_python_utils-0.5.2 → bs_python_utils-0.8.0}/README.md

@@ -6,33 +6,72 @@
 
 [![Build status](https://img.shields.io/github/actions/workflow/status/bsalanie/bs-python-utils/main.yml?branch=main)](https://github.com/bsalanie/bs-python-utils/actions/workflows/main.yml?query=branch%3Amain) <!-- [![codecov](https://codecov.io/gh/bsalanie/bs-python-utils/branch/main/graph/badge.svg)](https://codecov.io/gh/bsalanie/bs-python-utils) --> <!-- [![Commit activity](https://img.shields.io/github/commit-activity/m/bsalanie/bs-python-utils)](https://img.shields.io/github/commit-activity/m/bsalanie/bs-python-utils) --> [![License](https://img.shields.io/github/license/bsalanie/bs-python-utils)](https://img.shields.io/github/license/bsalanie/bs-python-utils)
 
-My Python utilities.
+**My Python utilities**.
 
--   **Github repository**: <https://github.com/bsalanie/bs-python-utils/>
--   **Documentation** <https://bsalanie.github.io/bs-python-utils/>
+- **Github repository**: <https://github.com/bsalanie/bs-python-utils/>
+- **Documentation** <https://bsalanie.github.io/bs-python-utils/>
 
 ### Release notes
+
+#### 0.8 (October 14, 2025)
+Switched to `uv` for project management. Used Codex to clean up the code and generate more tests. Added the `examples` subdirectory.
+
+#### 0.7 (June 18, 2024)
+Added `make_lowertri` in `bsnputils`, and some utility code in `bs_plots`.
+
+#### 0.6.4 (November 26, 2023)
+Moved to Altair 5.0; made timing optional in `bs_opt`.
+
+#### 0.6.3 (November 26, 2023)
+Updated statsmodels dependency.
+
+#### 0.6.1 and 0.6.2 (November 18, 2023)
+Added a Matplotlib plot for discrete choice models, a boxplot for Altair, and a density plot for Seaborn.
+
+#### 0.6 (November 9, 2023)
+
+Added matrix heatmap plot in Altair and Streamlit utility code.
+
+#### 0.5.5 (October 23, 2023)
+
+Added `fstring***` in `bsutils`.
+
 #### 0.5.2 (August 16, 2023)
+
 Added two interpolation routines from values at the Chebyshev nodes in `chebyshev` module.
+
 #### 0.5.1 (August 14, 2023)
-Added two functions to draw random samples in  `bsstats` module.
+
+Added two functions to draw random samples in `bsstats` module.
+
 #### 0.5 (August 7, 2023)
+
 Added 1-dimensional root finding in `chebyshev` module.
+
 #### 0.4.2 (August 2, 2023)
+
 Updated the docs.
+
 #### 0.4.1 (July 23, 2023)
+
 Only print if verbose in bivariate quantiles.
+
 #### 0.4 (July 22, 2023)
+
 Added bivariate quantiles and ranks à la optimal transportation.
+
 #### 0.3 (July 21, 2023)
+
 Added in Numpy utils a function to set upper and lower triangle to a scalar;
 and `minimize_free` in `bs_opt`.
 
 #### 0.2 (July 17, 2023)
+
 Fixed printing in accelerated gradient descent.
 
 #### 0.1 (June 20, 2023)
-Added `grid_function` and the `chebyshev` module. 
+
+Added `grid_function` and the `chebyshev` module.
 
 #### 0.0.6 (May 9, 2023)
 
@@ -52,4 +91,4 @@ Satisfied mypy.
 
 #### 0.0.2 (April 24, 2023)
 
-Fixed main PyPI page.
+Fixed main PyPI page.

{bs_python_utils-0.5.2 → bs_python_utils-0.8.0}/bs_python_utils/Timer.py

@@ -1,5 +1,8 @@
 """
-utilities to time code
+Utilities to time code:
+
+* a `Timer` class that can be used as a context manager
+* a `timeit` decorator for functions.
 """
 
 import time
@@ -28,20 +31,22 @@ class Timer:
     A timer that can be started, stopped, and reset as needed by the user.
     It keeps track of the total elapsed time in the `elapsed` attribute::
 
-       with Timer() as t:
-         ....
-       print(f"... took {t.elapsed} seconds")
+    Examples:
+        >>> with Timer() as t:
+        >>>  ....
+        >>> print(f"... took {t.elapsed} seconds")
 
     use `Timer(time.process_time)` to get only CPU time.
 
-    can also do::
+    can also do:
 
-       t = Timer()
-       t.start()
-       t.stop()
-       t.start()   # will add to the same counter
-       t.stop()
-       print(f"{t.elapsed} seconds total")
+    Examples:
+        >>> t = Timer()
+        >>> t.start()
+        >>> t.stop()
+        >>> t.start()   # will add to the same counter
+        >>> t.stop()
+        >>> print(f"{t.elapsed} seconds total")
     """
 
     def __init__(self, func: Callable = time.perf_counter) -> None:

bs_python_utils-0.8.0/bs_python_utils/__init__.py

@@ -0,0 +1,20 @@
+"""This package contains a number of functions that I have found useful in my programming.
+
+* `bsutils` has (inter alia) some I/O functions, error reporting, and $C^2$ extensions of log and exp
+* `bs_logging` has customized logging
+* `bs_mathstr` has Unicode for math strings
+* `bs_mem` reports memory usage
+* `Timer` has a `Timer` class to time code execution.
+* `bsnputils` has Numpy functions
+* `bssputils` has Scipy functions
+* `sklearn_utils` has Sklearn functions
+* `pandas_utils` has Pandas functions
+* `bsstats` has TSLS code; nonparametric and flexible estimation; and code to draw random samples
+* `bs_opt` interfaces with `scipy.optimize`
+* `bs_sparse_gaussian` uses sparse integration to evaluate $E f(X)$ for $X \\simeq N(0,1)$
+* `chebyshev` has Chebyshev interpolation and integration in dimensions 1 and 2
+* `distance_covariances` has measures of nonlinear dependence between random variables
+* `bivariate_quantiles` computes quantiles and ranks for 2-dimensional random variables à la [Chernozhukov-Galichon-Hallin-Henry (*Ann. Stats.* 2017)](https://projecteuclid.org/journals/annals-of-statistics/volume-45/issue-1/MongeKantorovich-depth-quantiles-ranks-and-signs/10.1214/16-AOS1450.full).
+
+* `bs_plots` gathers plotting routines in Matplotlib, Seaborn and Altair from `bsmplutils`, `bs_seaborn`, and `bs_altair`.
+"""

{bs_python_utils-0.5.2 → bs_python_utils-0.8.0}/bs_python_utils/bivariate_quantiles.py

@@ -1,94 +1,83 @@
 """This takes in observations of a bivariate random variable `y`
-and computes vector quantiles and vector ranks.
+and computes vector quantiles and vector ranks à la [Chernozhukov-Galichon-Hallin-Henry (*Ann. Stats.* 2017)](https://projecteuclid.org/journals/annals-of-statistics/volume-45/issue-1/MongeKantorovich-depth-quantiles-ranks-and-signs/10.1214/16-AOS1450.full).
 
-The sequence of steps is as follows:
 
-1.  choose a  number of Chebyshev nodes for numerical integration and
- optimize the weights: `v = solve_for_v(y, n_nodes)`
+Note:
+    if the math looks strange in the documentation, just reload the page.
 
-2a. to obtain the $(u_1,u_2)$ quantiles for $u_1, u_2\\in [0,1]$, run
-`qtiles_y = bivariate_quantiles_v(y, v, u1, u2)`
+The sequence of steps is as follows:
 
-2b.  to compute the vector ranks for all points in the sample (the barycenters of the cells in the power diagram):
+* choose a  number of Chebyshev nodes for numerical integration and optimize the weights: `v = solve_for_v(y, n_nodes)`
+* to obtain the $(u_1,u_2)$ quantiles for $(u_1, u_2)\\in [0,1]$, run
+`qtiles_y = bivariate_quantiles_v(y, v, u1, u2)`
+* to compute the vector ranks for all points in the sample (the barycenters of the cells in the power diagram):
 `ranks_y = bivariate_ranks_v(y, v, n_nodes)`
 
-Steps 1 and 2a can be combined: `qtiles_y = bivariate_quantiles(y, v, u1, u2, n_nodes)`
+Steps 1 and 2 can be combined: `qtiles_y = bivariate_quantiles(y, v, u1, u2, n_nodes)`
 
-Steps 1 and 2b can be combined: `ranks_y = bivariate_ranks(y, n_nodes)`
+Steps 1 and 3 can be combined: `ranks_y = bivariate_ranks(y, n_nodes)`
 """
+
 from typing import cast
 
 import numpy as np
 
-from bs_python_utils.bs_opt import (
-    minimize_free,
-    print_optimization_results,
-)
-from bs_python_utils.bsnputils import (
-    TwoArrays,
-    npmaxabs,
-)
+from bs_python_utils.bs_opt import minimize_free, print_optimization_results
+from bs_python_utils.bsnputils import TwoArrays, npmaxabs
 from bs_python_utils.bsutils import bs_error_abort
 from bs_python_utils.chebyshev import Interval, cheb_get_nodes_1d
 
 
-def compute_ab_(y_sorted: np.ndarray, v_sorted: np.ndarray) -> TwoArrays:
-    """evaluates the A and B matrices
-
-    Args:
-        y_sorted: the observations, an `(n,2)` matrix sorted by increasing `y[:, 1]`
-        v_sorted: the weights, an `n`-vector in the same sort order
-
-    Returns:
-        two `(n, n)` matrices
-
-    Warning:
-        the user must make sure that `y` and `v` have been sorted beforehand
-    """
-    n = v_sorted.size
+def _compute_ab(y_sorted: np.ndarray, v_sorted: np.ndarray) -> TwoArrays:
+    """Build the `A` and `B` matrices used in the dual optimisation."""
     y1 = y_sorted[:, 0]
     dy1 = np.subtract.outer(y1, y1)
     y2 = y_sorted[:, 1]
     dy2 = np.subtract.outer(y2, y2)
-    np.fill_diagonal(dy2, np.ones(n))  # to avoid division by 0
+    np.fill_diagonal(dy2, 1.0)
     dv = np.subtract.outer(v_sorted, v_sorted)
-    a_mat = dy1.T / dy2
-    b_mat = dv.T / dy2
+    with np.errstate(divide="ignore", invalid="ignore"):
+        a_mat = np.divide(dy1.T, dy2, where=np.abs(dy2) > 1e-12)
+        b_mat = np.divide(dv.T, dy2, where=np.abs(dy2) > 1e-12)
+    a_mat = np.nan_to_num(a_mat, nan=0.0, posinf=0.0, neginf=0.0)
+    b_mat = np.nan_to_num(b_mat, nan=0.0, posinf=0.0, neginf=0.0)
     return a_mat, b_mat
 
 
-def compute_u2_bounds_(
+def _compute_u2_bounds(
     k: int, u1: np.ndarray, a_mat: np.ndarray, b_mat: np.ndarray
 ) -> TwoArrays:
-    """for given u1, calculates the bounds on u2 that make k the chosen observation
-
-    Args:
-        k: an integer between 0 and (n-1)
-        u1: a vector of size `m`
-        a_mat: the `A` matrix of size `(n,n)`
-        b_mat: the `B` matrix of size `(n,n)`
-
-    Returns:
-        two vectors of size `m`, the left and right bounds in [0,1]
-    """
+    """Return the admissible interval of ``u2`` that selects index ``k``."""
     n = a_mat.shape[0]
     m = u1.size
     if k == 0:
         left_bound = np.zeros(m)
         a_right = a_mat[0, 1:]
         b_right = b_mat[0, 1:]
-        right_bound = np.min(np.outer(u1, a_right) - b_right, 1)
+        if a_right.size:
+            right_bound = np.min(np.outer(u1, a_right) - b_right, 1)
+        else:
+            right_bound = np.ones(m)
     elif 1 <= k < n - 1:
         a_left = a_mat[k, :k]
         b_left = b_mat[k, :k]
-        left_bound = np.max(np.outer(u1, a_left) - b_left, 1)
+        if a_left.size:
+            left_bound = np.max(np.outer(u1, a_left) - b_left, 1)
+        else:
+            left_bound = np.zeros(m)
         a_right = a_mat[k, (k + 1) :]
         b_right = b_mat[k, (k + 1) :]
-        right_bound = np.min(np.outer(u1, a_right) - b_right, 1)
+        if a_right.size:
+            right_bound = np.min(np.outer(u1, a_right) - b_right, 1)
+        else:
+            right_bound = np.ones(m)
     elif k == n - 1:
         a_left = a_mat[-1, :-1]
         b_left = b_mat[-1, :-1]
-        left_bound = np.max(np.outer(u1, a_left) - b_left, 1)
+        if a_left.size:
+            left_bound = np.max(np.outer(u1, a_left) - b_left, 1)
+        else:
+            left_bound = np.zeros(m)
         right_bound = np.ones(m)
     else:
         bs_error_abort(f"{k=} is not compatible with {n=}")
@@ -99,34 +88,44 @@ def compute_u2_bounds_(
 
 
 def bivariate_quantiles_v(y: np.ndarray, u: np.ndarray, v: np.ndarray) -> np.ndarray:
-    """computes the vector quantiles of `y` at values `u`, given the converged `v`
+    """Evaluate vector quantiles for a given set of dual weights.
 
     Args:
-        y: the observations, an `(n,2)` matrix
-        u: the values where we want the quantiles, an `(m,2)` matrix in $[0,1]$
-        v: the converged values of the weights, an `n`-vector
+        y: Observations with shape ``(n, 2)``.
+        u: Evaluation points in ``[0, 1]^2`` (shape ``(m, 2)``).
+        v: Dual weights solving the optimal transport problem (length ``n``).
 
     Returns:
-        an `(m,2)` matrix with the quantiles of `y` at the values `u`
+        Array of quantile locations with shape ``(m, 2)``.
     """
-    net_val = u @ y.T - v
-    k_max = np.argmax(net_val, 1)
-    return cast(np.ndarray, y[k_max])
+    u = np.atleast_2d(u)
+    if u.shape[1] != 2:
+        bs_error_abort("u must have two columns")
+    m = u.shape[0]
+    q = np.empty((m, 2))
+    block = max(1, min(m, 5_000))
+    for start in range(0, m, block):
+        stop = min(start + block, m)
+        chunk = u[start:stop]
+        net_val = chunk @ y.T - v
+        k_max = np.argmax(net_val, axis=1)
+        q[start:stop] = y[k_max]
+    return cast(np.ndarray, q)
 
 
 def bivariate_ranks_v(
     y: np.ndarray, v: np.ndarray, n_nodes: int = 32, presorted: bool = False
 ) -> np.ndarray:
-    """computes the vector ranks of `y`, given the converged `v`
+    """Compute the barycentric ranks of each observation given optimal weights.
 
     Args:
-        y: the observations, an `(n,2)` matrix
-        v: the converged values of the weights, an `n`-vector
-        n_nodes: the number of nodes for Chebyshev integration
-        presorted: if `True`, then `y` and `v` are sorted by increasing `y[:, 1]`.
+        y: Observations with shape ``(n, 2)``.
+        v: Dual weights returned by ``solve_for_v_``.
+        n_nodes: Number of Chebyshev nodes used in the quadrature.
+        presorted: Set to ``True`` when ``y``/``v`` are pre-sorted by the second coordinate.
 
     Returns:
-        an `(n,2)` matrix with the average ranks of `y`
+        Array of average ranks (shape ``(n, 2)``) with ``nan`` for zero-mass cells.
     """
     n, d = y.shape
 
@@ -145,24 +144,27 @@ def bivariate_ranks_v(
         y_sorted = y[sort_order, :]
         v_sorted = v[sort_order]
 
-    a_mat, b_mat = compute_ab_(y_sorted, v_sorted)
+    a_mat, b_mat = _compute_ab(y_sorted, v_sorted)
 
     average_ranks = np.zeros((n, 2))
 
     for k in range(n):
-        left_bounds, right_bounds = compute_u2_bounds_(k, u1_nodes, a_mat, b_mat)
+        left_bounds, right_bounds = _compute_u2_bounds(k, u1_nodes, a_mat, b_mat)
         pos_diffs = np.maximum(right_bounds - left_bounds, 0.0)
         pos_diffs_sq = np.maximum(
             right_bounds * right_bounds - left_bounds * left_bounds, 0.0
         )
         prob_k = pos_diffs @ u1_weights
+        if prob_k <= 1e-12:
+            average_ranks[sort_order[k], :] = np.array([np.nan, np.nan])
+            continue
         average_ranks[sort_order[k], 0] = ((u1_nodes * pos_diffs) @ u1_weights) / prob_k
         average_ranks[sort_order[k], 1] = ((pos_diffs_sq @ u1_weights) / 2.0) / prob_k
 
     return average_ranks
 
 
-def objgrad_(
+def _objgrad(
     v_sorted: np.ndarray, args: list, gr: bool = False
 ) -> float | tuple[float, np.ndarray]:
     """computes the expectation of $\\psi(U, v)$ and perhaps its gradient wrt `v`
@@ -180,12 +182,12 @@ def objgrad_(
     u1_nodes = args[1]
     u1_weights = args[2]
     vs1 = np.append(v_sorted, -np.sum(v_sorted))
-    a_mat, b_mat = compute_ab_(y_sorted, vs1)
+    a_mat, b_mat = _compute_ab(y_sorted, vs1)
 
     obj_val = 0.0
     probs = np.zeros(n)
     for k in range(n):
-        left_bounds, right_bounds = compute_u2_bounds_(k, u1_nodes, a_mat, b_mat)
+        left_bounds, right_bounds = _compute_u2_bounds(k, u1_nodes, a_mat, b_mat)
         pos_diffs = np.maximum(right_bounds - left_bounds, 0.0)
         pos_diffs_sq = np.maximum(
             right_bounds * right_bounds - left_bounds * left_bounds, 0.0
@@ -204,20 +206,30 @@ def objgrad_(
         return cast(float, obj_val)
 
 
-def obj_(v_sorted: np.ndarray, args: list):
-    return objgrad_(v_sorted, args)
+def _obj(v_sorted: np.ndarray, args: list):
+    return _objgrad(v_sorted, args)
 
 
-def grad_(v_sorted: np.ndarray, args: list):
-    res_objg = cast(tuple[float, np.ndarray], objgrad_(v_sorted, args, gr=True))
+def _grad(v_sorted: np.ndarray, args: list):
+    res_objg = cast(tuple[float, np.ndarray], _objgrad(v_sorted, args, gr=True))
     grad_val = res_objg[1]
     verbose = args[3]
     if verbose:
-        print(f"grad_err is {npmaxabs(grad_val)}")
+        print(f"The error on the gradient is {npmaxabs(grad_val)}")
     return grad_val
 
 
 def solve_for_v_(y: np.ndarray, n_nodes: int = 32, verbose: bool = False) -> np.ndarray:
+    """Solve the dual optimisation to obtain the optimal weights ``v``.
+
+    Args:
+        y: Observations with shape ``(n, 2)``.
+        n_nodes: Number of Chebyshev nodes for the quadrature.
+        verbose: Print optimisation diagnostics when ``True``.
+
+    Returns:
+        Array of length ``n`` containing the optimal weights (including the residual term).
+    """
     n, d = y.shape
 
     if d != 2:
@@ -234,7 +246,7 @@ def solve_for_v_(y: np.ndarray, n_nodes: int = 32, verbose: bool = False) -> np.
 
     argsog = [y_sorted, u1_nodes, u1_weights, verbose]
 
-    res = minimize_free(obj_, grad_, v0, args=argsog)
+    res = minimize_free(_obj, _grad, v0, args=argsog)
     if verbose:
         print_optimization_results(res, "Minimizing over v")
 
@@ -255,17 +267,16 @@ def solve_for_v_(y: np.ndarray, n_nodes: int = 32, verbose: bool = False) -> np.
 def bivariate_quantiles(
     y: np.ndarray, u: np.ndarray, n_nodes: int = 32, verbose: bool = False
 ) -> np.ndarray:
-    """computes the bivariate quantiles of `y` at the quantiles `u`
+    """Solve for the dual weights then evaluate bivariate quantiles.
 
     Args:
-        y: the observations, an `(n, 2)` matrix
-        u: the quantiles at which to compute the bivariate quantiles,
-            an `(m, 2)` matrix
-        n_nodes: the number of nodes to use for the quadrature
-        verbose: if `True`, print some information
+        y: Observations, shape ``(n, 2)``.
+        u: Query points in ``[0, 1]^2`` (shape ``(m, 2)``).
+        n_nodes: Number of Chebyshev nodes for the quadrature.
+        verbose: Print optimisation diagnostics when ``True``.
 
     Returns:
-        an `(m, 2)` matrix of bivariate quantiles
+        Bivariate quantiles at ``u``.
     """
     v = solve_for_v_(y, n_nodes, verbose)
     return bivariate_quantiles_v(y, u, v)
@@ -274,15 +285,15 @@ def bivariate_quantiles(
 def bivariate_ranks(
     y: np.ndarray, n_nodes: int = 32, verbose: bool = False
 ) -> np.ndarray:
-    """computes the bivariate ranks of `y`
+    """Compute ranks by first solving for the optimal weights ``v``.
 
     Args:
-        y: the observations, an `(n, 2)` matrix
-        n_nodes: the number of nodes to use for the quadrature
-        verbose: if `True`, print some information
+        y: Observations, shape ``(n, 2)``.
+        n_nodes: Number of Chebyshev nodes for the quadrature.
+        verbose: Print optimisation diagnostics when ``True``.
 
     Returns:
-        the `(n, 2)` matrix of bivariate average ranks
+        Average ranks with shape ``(n, 2)``.
     """
     v = solve_for_v_(y, n_nodes, verbose)
     return bivariate_ranks_v(y, v, n_nodes)