phenotypic.util.geometric_median

phenotypic.util.geometric_median(points: ndarray, eps: float = 1e-06, method: Literal['cohen', 'weiszfeld'] = 'cohen', matrix_free: bool | None = None, matrix_free_threshold: int = 100, verbose: bool = True, **kwargs) → Tuple[ndarray, Dict]

Compute geometric median of a set of points.

Main interface supporting both Cohen et al. (2016) nearly-linear time algorithm and classical Weiszfeld algorithm.

Parameters:

• points (ndarray) – Data points, shape (n, d)

• eps (float) – Target accuracy for (1 + eps)-approximation

• method (Literal['cohen', 'weiszfeld']) – Algorithm to use: - ‘cohen’: Cohen et al. (2016) O(nd log³(n/ε)) algorithm [default] - ‘weiszfeld’: Classical Weiszfeld O(?) algorithm

• matrix_free (bool | None) – For Cohen method, whether to use matrix-free Hessian. If None, automatically decides based on dimension.

• matrix_free_threshold (int) – Dimension threshold for matrix-free mode

• verbose (bool) – Whether to print progress information

• **kwargs – Additional method-specific arguments

Returns:

Geometric median point, shape (d,) info: Dictionary with algorithm statistics:

• ’iterations’: Number of iterations performed

• ’objective’: Final objective value f(x)

• ’converged’: Whether algorithm converged

• ’method’: Algorithm used

• Additional method-specific statistics

Return type:

median

Raises:

ValueError – If method is invalid or points array has wrong shape

Examples

>>> # Cohen method (recommended for large problems)
>>> points = np.random.randn(10000, 50)
>>> median, info = geometric_median(points, method='cohen', eps=0.01)
>>> print(f"Converged: {info['converged']}")
>>> print(f"Objective: {info['objective']:.6f}")

>>> # Weiszfeld method (simple, good for small problems)
>>> points = np.random.randn(100, 3)
>>> median, info = geometric_median(points, method='weiszfeld', eps=1e-6)

>>> # Force matrix-free for high-dimensional problems
>>> points = np.random.randn(1000, 500)
>>> median, info = geometric_median(points, method='cohen',
...                                 matrix_free=True, eps=0.1)

References

Cohen, M. B., Lee, Y. T., Miller, G., Pachocki, J., & Sidford, A. (2016). Geometric median in nearly linear time. STOC 2016.