Distances#

mergen.distances#

Distance metrics for mixed continuous / categorical parameter spaces.

Mergen supports parameter spaces that mix numerical (continuous, discrete, integer, or ordinal) and nominal (unordered categorical) factors. The nearest-neighbour and space-filling machinery of the package therefore needs a distance function that treats each column according to its type. The Heterogeneous Euclidean-Overlap Metric (HEOM) of Wilson & Martinez (1997) is the standard choice: it degenerates to the ordinary normalised Euclidean distance when no nominal columns are present, so callers that never use nominal factors are not affected.

For two rows \(x_a, x_b\) with \(p\) numerical columns and \(q\) nominal columns (\(d = p + q\) total):

\[d_\mathrm{HEOM}(x_a, x_b) \;=\; \sqrt{\sum_{j=1}^{d} d_j(x_{aj}, x_{bj})^2}\]

where the per-column term is

\[\begin{split}d_j = \begin{cases} |x_{aj} - x_{bj}| / R_j & \text{numerical column,} \\ \mathbb{1}(x_{aj} \neq x_{bj}) & \text{nominal column.} \end{cases}\end{split}\]

Here \(R_j = \max_i x_{ij} - \min_i x_{ij}\) is the observed range of column \(j\). The design coordinates handed to Mergen optimisers are already normalised to \([0, 1]^d\), so numerical columns pass through as |x_{aj} - x_{bj}| with no rescaling.

References

Wilson, D. R. & Martinez, T. R. (1997). Improved heterogeneous

distance functions. Journal of Artificial Intelligence Research, 6, 1-34.

Gower, J. C. (1971). A general coefficient of similarity and some

of its properties. Biometrics, 27(4), 857-871.

mergen.distances.heom_squared(a, b, space=None, nominal_mask=None)[source]#

Squared HEOM distance between corresponding rows of a and b.

Computing squared distances avoids the sqrt call, which is a significant saving in the inner loops of maximin/Kennard-Stone selection where only distance ordering is needed. Callers that require the actual distance can take np.sqrt of the return value.

Both arrays must already be in the normalised design space \([0, 1]^d\). Nominal columns are compared for equality via np.isclose because they carry float-encoded level indices (0.0, 1.0, …).

Parameters:

  • a (np.ndarray) – Broadcast-compatible arrays of shape (..., d). The last axis indexes the parameter columns.

  • b (np.ndarray) – Broadcast-compatible arrays of shape (..., d). The last axis indexes the parameter columns.

  • space (ParameterSpace, optional) – Source for the nominal-column mask. Ignored if nominal_mask is given explicitly.

  • nominal_mask (array-like of bool, shape (d,), optional) – Column-wise mask marking nominal columns. When neither space nor nominal_mask is provided, every column is treated as numerical and HEOM reduces to the squared normalised Euclidean distance.

Returns:

np.ndarray – Squared HEOM distances, with the broadcast shape of a and b minus their trailing column axis.

Return type:

np.ndarray

References

Wilson, D. R. & Martinez, T. R. (1997). J. Artif. Intell. Res.,

6, 1-34.

mergen.distances.heom(a, b, space=None, nominal_mask=None)[source]#

HEOM distance between corresponding rows of a and b.

Convenience wrapper around heom_squared() that returns the actual distance (i.e., with the sqrt applied). Use heom_squared() directly in tight loops when only distance ordering matters.

See heom_squared() for parameter documentation.

References

Wilson, D. R. & Martinez, T. R. (1997). J. Artif. Intell. Res.,

6, 1-34.

Parameters:

  • a (np.ndarray)

  • b (np.ndarray)

  • space (Optional['ParameterSpace'])

  • nominal_mask (Optional[np.ndarray])

Return type:

np.ndarray

mergen.distances.heom_pairwise(X, space=None, nominal_mask=None, squared=False)[source]#

Full pairwise HEOM distance matrix for a design X.

Runs in \(O(n^2 d)\) time and uses \(O(n^2)\) memory. For large designs where only the nearest-neighbour distance per row is needed, prefer computing row-vs-set distances with heom_squared() in a loop rather than materialising the full matrix.

Parameters:

  • X (np.ndarray, shape (n, d)) – Design in normalised coordinates.

  • space (Optional['ParameterSpace']) – See heom_squared().

  • nominal_mask (Optional[np.ndarray]) – See heom_squared().

  • squared (bool, default False) – Return squared distances when True. Saves an np.sqrt call when only the ordering is required (e.g., inside Kennard-Stone selection).

Returns:

np.ndarray, shape (n, n) – Symmetric pairwise distance matrix. The diagonal is 0.

Return type:

np.ndarray