bs-python-utils 1.0.1__tar.gz → 1.1.1__tar.gz

{bs_python_utils-1.0.1 → bs_python_utils-1.1.1}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: bs-python-utils
-Version: 1.0.1
+Version: 1.1.1
 Summary: Utilities programs for my Python code
-Requires-Python: >=3.12
+Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: altair>=5.5.0
@@ -26,6 +26,7 @@ Requires-Dist: streamlit>=1.49.1
 Requires-Dist: vega-datasets>=0.9.0
 Requires-Dist: colorama>=0.4.6
 Requires-Dist: pyarrow>=23.0.0
+Requires-Dist: scipy-stubs~=1.16.2
 Dynamic: license-file
 
 ## bs-python-utils
@@ -49,6 +50,9 @@ Dynamic: license-file
 
 ### Release notes
 
+#### 1.1.1 (September 04, 2026)
+Added simulation-based bivariate ranks.
+
 #### 1.0.1 (May 9, 2026)
 Fixed badges.
 

{bs_python_utils-1.0.1 → bs_python_utils-1.1.1}/README.md

@@ -19,6 +19,9 @@
 
 ### Release notes
 
+#### 1.1.1 (September 04, 2026)
+Added simulation-based bivariate ranks.
+
 #### 1.0.1 (May 9, 2026)
 Fixed badges.
 

{bs_python_utils-1.0.1 → bs_python_utils-1.1.1}/bs_python_utils/numerical/bsnputils.py

@@ -300,9 +300,7 @@ def npmaxabs(arr: np.ndarray) -> float:
     return cast(float, np.max(np.abs(arr)))
 
 
-def rice_stderr(
-    y: np.ndarray, x: np.ndarray, is_sorted: bool = False
-) -> np.ndarray | float:
+def rice_stderr(y: np.ndarray, x: np.ndarray, is_sorted: bool = False) -> np.ndarray:
     """
     computes the Rice local estimators of the standard error of y | x
 

{bs_python_utils-1.0.1 → bs_python_utils-1.1.1}/bs_python_utils/opt/bs_opt.py

@@ -25,6 +25,7 @@ import numpy as np
 import scipy.linalg as spla
 import scipy.optimize as spopt
 
+
 from bs_python_utils.numerical.bsnputils import TwoArrays, check_vector, npmaxabs
 from bs_python_utils.core.bsutils import bs_error_abort, print_stars
 from bs_python_utils.core.Timer import timeit
@@ -221,11 +222,11 @@ def check_gradient_scalar_function(
         fg: should return the scalar value, and the gradient if its `gr` argument is `True`
         p: where we are checking the gradient
         args: other arguments passed to `fg`
-        mode: "central" or "forward" derivatives
-        EPS: the step for forward or central derivatives
+        mode: ``"central"`` or ``"forward"``
+        EPS: the step for forward or central finite differences
 
     Returns:
-        the analytic and numeric gradients.
+        the analytic and numeric (or AD) gradients.
     """
     f0, f_grad = fg(p, args, gr=True)  # type: ignore
     f0 = cast(float, f0)
@@ -285,7 +286,6 @@ def acc_grad_descent(
     Returns:
         A pair ``(x_star, status)`` where ``status`` is ``0`` on convergence and ``1`` otherwise.
     """
-
     # no proximal projection if no h
     local_prox_h: ProximalFunction = prox_h if prox_h else lambda x, t, p: x
 
@@ -420,8 +420,8 @@ def minimize_some_fixed(
             obj,
             x_init,
             method="L-BFGS-B",
-            args=args,
-            options=options,
+            args=(args,),
+            options=cast(Any, options),
             jac=grad_obj,
             bounds=bounds,
         )
@@ -453,8 +453,8 @@ def minimize_some_fixed(
             fixed_obj,
             t_init,
             method="L-BFGS-B",
-            args=args,
-            options=options,
+            args=(args,),
+            options=cast(Any, options),
             jac=fixed_grad_obj,
             bounds=t_bounds,
         )
@@ -508,8 +508,8 @@ def minimize_free(
             obj,
             x_init,
             method="BFGS",
-            args=args,
-            options=options,
+            args=(args,),
+            options=cast(Any, options),
             jac=grad_obj,
         )
     else:
@@ -517,8 +517,8 @@ def minimize_free(
             obj,
             x_init,
             method="L-BFGS-B",
-            args=args,
-            options=options,
+            args=(args,),
+            options=cast(Any, options),
             jac=grad_obj,
             bounds=bounds,
         )

{bs_python_utils-1.0.1 → bs_python_utils-1.1.1}/bs_python_utils/stats/bivariate_quantiles.py

@@ -15,6 +15,8 @@ References:
     Quantiles, Ranks and Signs." *Annals of Statistics* 45(1), 2017.
 """
 
+from __future__ import annotations
+
 from typing import cast
 
 import numpy as np
@@ -23,6 +25,74 @@ from bs_python_utils.core.bsutils import bs_error_abort
 from bs_python_utils.numerical.bsnputils import TwoArrays, npmaxabs
 from bs_python_utils.numerical.chebyshev import Interval, cheb_get_nodes_1d
 from bs_python_utils.opt.bs_opt import minimize_free, print_optimization_results
+from bs_python_utils.numerical.bsnputils import check_matrix
+from scipy.special import logsumexp
+
+
+def bivariate_ranks_simul(
+    x: np.ndarray,
+    rng: np.random.Generator,
+    n_draws: int = 10_000,
+    h_mult: float = 100.0,
+) -> np.ndarray:
+    """This computes bivariate ranks for a matrix ``x` using simulations
+
+    Args:
+        x: Input matrix of shape ``(n, 2)``.
+        rng: Random number generator for reproducibility.
+        n_draws: Number of random draws for the simulation.
+        h_mult: we set the bandwidth h as std(v_init)/h_mult, default is 100.0
+    """
+    n, d = check_matrix(x)
+    if d != 2:
+        bs_error_abort("Input matrix x must have 2 columns for bivariate ranks.")
+
+    v_init = np.mean(x, axis=1)[:-1]
+    h = np.std(v_init) / 100.0
+
+    tau_draws = rng.uniform(low=0.0, high=1.0, size=2 * n_draws).reshape((n_draws, 2))
+
+    def objv_and_grad(
+        v: np.ndarray,
+        ret: int = 0,
+    ) -> float | np.ndarray | None:
+        vn = np.zeros(n)
+        vn[:-1] = v.copy()
+        vn[-1] = -np.sum(v)
+        psi_vals = tau_draws @ x.T - vn
+        lse_vals = logsumexp(psi_vals / h, axis=1)
+        psi_maxs = h * lse_vals
+        obj_val = np.mean(psi_maxs)
+        probs = np.exp(psi_vals / h - lse_vals.reshape((-1, 1)))
+        mean_probs = np.mean(probs, axis=0)
+        if ret == 0:
+            return cast(float, obj_val)
+        elif ret == 1:
+            grad = -mean_probs[:-1] + mean_probs[-1]
+            return cast(np.ndarray, grad)
+        elif ret == 2:
+            ranks = (probs.T @ tau_draws / n_draws) / mean_probs.reshape((-1, 1))
+            return cast(np.ndarray, ranks)
+        else:
+            bs_error_abort("Invalid value for ret. Must be 0, 1, or 2.")
+            return None
+
+    def objv(v: np.ndarray, args: list) -> float:
+        return cast(float, objv_and_grad(v, ret=0))
+
+    def grad_objv(v: np.ndarray, args: list) -> np.ndarray:
+        return cast(np.ndarray, objv_and_grad(v, ret=1))
+
+    def ranks(v: np.ndarray, args: list) -> np.ndarray:
+        return cast(np.ndarray, objv_and_grad(v, ret=2))
+
+    resv = minimize_free(objv, grad_objv, v_init, args=[])
+    if not resv.success:
+        bs_error_abort(f"Optimization failed, message: {resv.message}")
+
+    v_sol = resv.x
+    r_x = ranks(v_sol, args=[])
+    return r_x
 
 
 def _compute_ad(y: np.ndarray) -> TwoArrays:
@@ -54,16 +124,11 @@ def _compute_m_M(
     Args:
         v: Dual weights of length ``n``.
         a_mat: Pairwise slope matrix returned by :func:`_compute_ad`.
-        dy2: Pairwise differences in the second coordinate.
+        dy2: Pairwise differences in the second coordinate (1 on diagonal).
         tau1_nodes: Quadrature nodes for the first coordinate.
 
     Returns:
         A tuple ``(m, M)`` with arrays of shape ``(n, len(tau1_nodes))``.
-
-    Warning:
-        The (rare) ``dy2 == 0`` case currently raises warnings in computing ``b_mat``.
-        That logic works for the present implementation but should be refactored into a cleaner, more explicit
-        branch.
     """
     dv = np.subtract.outer(v, v)
     b_mat = dv / dy2
@@ -71,17 +136,12 @@ def _compute_m_M(
     EPS = 1e-12
     maskp = dy2 < EPS
     maskm = dy2 > -EPS
-    n, n_nodes = v.size, tau1_nodes.size
-    m_low = np.empty((n, n_nodes))
-    m_high = np.empty((n, n_nodes))
-    for i, tau1 in enumerate(tau1_nodes):
-        f_mat = tau1 * a_mat - b_mat
-        f_matp = f_mat.copy()
-        f_matm = f_mat.copy()
-        f_matp[maskp] = 1
-        f_matm[maskm] = 0
-        m_low[:, i] = np.max(f_matm, axis=1)
-        m_high[:, i] = np.min(f_matp, axis=1)
+    # Vectorised over all quadrature nodes at once: (n_nodes, n, n)
+    f_mats = tau1_nodes[:, None, None] * a_mat[None, :, :] - b_mat[None, :, :]
+    f_mats_p = np.where(maskp, 1.0, f_mats)
+    f_mats_m = np.where(maskm, 0.0, f_mats)
+    m_low = np.max(f_mats_m, axis=2).T  # (n, n_nodes)
+    m_high = np.min(f_mats_p, axis=2).T
     return np.clip(m_low, 0.0, 1.0), np.clip(m_high, 0.0, 1.0)
 
 
@@ -132,11 +192,6 @@ def _objgrad(
     tau1_weights = args[4]
     vs1 = np.append(v, -np.sum(v))
     m, M = _compute_m_M(vs1, a_mat, dy2, tau1_nodes)
-    # print(f"m is {m}")
-    # print(f"M  is {M}")
-    # import sys
-
-    # sys.exit(1)
 
     EPS = 1e-12
     bivrank = np.zeros((n, 2))
@@ -190,7 +245,11 @@ def _grad(v: np.ndarray, args: list):
     return grad_val
 
 
-def _solve_for_v(y: np.ndarray, n_nodes: int = 32, verbose: bool = False) -> TwoArrays:
+def _solve_for_v(
+    y: np.ndarray,
+    n_nodes: int = 32,
+    verbose: bool = False,
+) -> TwoArrays:
     """Solve the dual optimization problem for the sample.
 
     Args:
@@ -221,16 +280,21 @@ def _solve_for_v(y: np.ndarray, n_nodes: int = 32, verbose: bool = False) -> Two
     argsog = [y, a_mat, dy2, tau1_nodes, tau1_weights, verbose]
 
     res = minimize_free(_obj, _grad, v0, args=argsog)
+
     if verbose:
         print_optimization_results(res, "Minimizing over v")
 
     if not res.success:
         bs_error_abort("Problem! the optimization failed.")
-    vstar = res.x
+
+    vstar_free = res.x
+
     if verbose:
         print(f"The final gradient over v is close to 0: error {npmaxabs(res.jac)}")
-    _, _, bivranks = cast(tuple, _objgrad(vstar, argsog, gr=True))
-    vstar = np.append(vstar, -np.sum(vstar))
+
+    _, _, bivranks = cast(tuple, _objgrad(vstar_free, argsog, gr=True))
+
+    vstar = np.append(vstar_free, -np.sum(vstar_free))
     return cast(np.ndarray, vstar), cast(np.ndarray, bivranks)
 
 
@@ -255,11 +319,14 @@ def bivariate_ranks(
         bs_error_abort(f"only works for 2-dimensional y, not for {d}")
 
     _, bivranks = _solve_for_v(y, n_nodes, verbose)
-    return cast(np.ndarray, bivranks)
+    return bivranks
 
 
 def bivariate_quantiles(
-    y: np.ndarray, tau: np.ndarray, n_nodes: int = 32, verbose: bool = False
+    y: np.ndarray,
+    tau: np.ndarray,
+    n_nodes: int = 32,
+    verbose: bool = False,
 ) -> np.ndarray:
     """Solve for the dual weights and evaluate bivariate quantiles.
 

{bs_python_utils-1.0.1 → bs_python_utils-1.1.1}/bs_python_utils/stats/bsstats.py

@@ -342,6 +342,7 @@ def bs_multivariate_normal_pdf(
             bs_error_abort(
                 f"cov_mat should be a matrix ({nvars}, {nvars}) not ({nrows}, {ncols})"
             )
+        cov_mat = cast(np.ndarray, cov_mat)
         resid = values_x - means_x
         argresid = spla.solve(cov_mat, resid.T)
         argexp = np.zeros(n)

{bs_python_utils-1.0.1 → bs_python_utils-1.1.1}/bs_python_utils.egg-info/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: bs-python-utils
-Version: 1.0.1
+Version: 1.1.1
 Summary: Utilities programs for my Python code
-Requires-Python: >=3.12
+Requires-Python: >=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: altair>=5.5.0
@@ -26,6 +26,7 @@ Requires-Dist: streamlit>=1.49.1
 Requires-Dist: vega-datasets>=0.9.0
 Requires-Dist: colorama>=0.4.6
 Requires-Dist: pyarrow>=23.0.0
+Requires-Dist: scipy-stubs~=1.16.2
 Dynamic: license-file
 
 ## bs-python-utils
@@ -49,6 +50,9 @@ Dynamic: license-file
 
 ### Release notes
 
+#### 1.1.1 (September 04, 2026)
+Added simulation-based bivariate ranks.
+
 #### 1.0.1 (May 9, 2026)
 Fixed badges.
 

{bs_python_utils-1.0.1 → bs_python_utils-1.1.1}/bs_python_utils.egg-info/requires.txt

@@ -19,3 +19,4 @@ streamlit>=1.49.1
 vega-datasets>=0.9.0
 colorama>=0.4.6
 pyarrow>=23.0.0
+scipy-stubs~=1.16.2

{bs_python_utils-1.0.1 → bs_python_utils-1.1.1}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "bs-python-utils"
-version = "1.0.1"
+version = "1.1.1"
 description = "Utilities programs for my Python code"
 readme = "README.md"
-requires-python = ">=3.12"
+requires-python = ">=3.13"
 dependencies = [
     "altair>=5.5.0",
     "altair-saver>=0.5.0",
@@ -26,8 +26,13 @@ dependencies = [
     "vega-datasets>=0.9.0",
     "colorama>=0.4.6",
     "pyarrow>=23.0.0",
+    "scipy-stubs~=1.16.2",
 ]
 
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["bs_python_utils*"]

{bs_python_utils-1.0.1 → bs_python_utils-1.1.1}/tests/test_bivariate_quantiles.py

@@ -4,6 +4,7 @@ from bs_python_utils.numerical.bsnputils import npmaxabs
 from bs_python_utils.stats.bivariate_quantiles import (
     _compute_ad,
     _solve_for_v,
+    bivariate_ranks_simul,
 )
 
 
@@ -27,6 +28,25 @@ def test_bivariate_ranks():
     assert npmaxabs(bivranks - bivranks_th) < 0.1
 
 
+def test_bivariate_ranks_simul():
+    rng = np.random.default_rng(123)
+    n = 500
+    y = rng.normal(size=(n, 2))
+
+    bivranks = bivariate_ranks_simul(y, rng)
+
+    bivranks_th = np.empty_like(bivranks)
+    for k in range(n):
+        bivranks_th[k, 0] = np.mean(y[:, 0] < y[k, 0]) + 0.5 * np.mean(
+            y[:, 0] == y[k, 0]
+        )
+        bivranks_th[k, 1] = np.mean(y[:, 1] < y[k, 1]) + 0.5 * np.mean(
+            y[:, 1] == y[k, 1]
+        )
+
+    assert npmaxabs(bivranks - bivranks_th) < 0.1
+
+
 def test_compute_ad():
     y = np.array([[0.0, 1.0], [1.0, 1.3], [-1.0, 3.0]])
     a_mat, dy2 = _compute_ad(y)