geoprior.utils.shapes#

Shape utility helpers for arrays and tensors.

Functions

canonicalize_BHQO(y_pred, *[, y_true, ...])

Canonicalize quantile outputs to (B, H, Q, O).

canonicalize_BHQO_quantiles_np(y[, n_q, ...])

Return y in canonical (B,H,Q,O).

canonicalize_to_BHQO_using_contract(s_pred, *)

Canonicalize quantile tensor to (B,H,Q,O).

ensure_subs_bhq(s_pred_b, *, y_true_b, q_values)

Ensure subsidence quantile predictions are in (B,H,Q,O).
geoprior.utils.shapes.canonicalize_BHQO(y_pred, *, y_true=None, q_values=(0.1, 0.5, 0.9), n_q=None, layout=None, enforce_monotone=True, return_layout=False, verbose=0, log_fn=<built-in function print>)[source]#

Canonicalize quantile outputs to (B, H, Q, O).

Supported layouts (rank-4):

  • BHQO: (B, H, Q, O) -> unchanged

  • BQHO: (B, Q, H, O) -> transpose(0, 2, 1, 3)

  • BHOQ: (B, H, O, Q) -> transpose(0, 1, 3, 2)

If ambiguous (e.g., H == Q), and y_true is given, pick the transform with smallest MAE for q50.

If y_true is not given, fallback is:

  1. use layout if provided

  2. else prefer BHQO if plausible

  3. else pick by min crossing score

Parameters:

  • y_pred (Any) – Quantile tensor, NumPy array or TF tensor.

  • y_true (Any | None) – Target tensor (B, H, O) or (B, H, 1). Used only to resolve ambiguity robustly.

  • q_values (Sequence[float]) – Quantiles in order, e.g. (0.1, 0.5, 0.9).

  • n_q (int | None) – Number of quantiles. Defaults to len(q_values).

  • layout (str | None) – Force interpretation: “BHQO”, “BQHO”, “BHOQ”. Use “auto” (or None) to infer.

  • enforce_monotone (bool) – Sort along Q axis after canonicalization.

  • return_layout (bool) – If True, return (arr, chosen_layout).

  • verbose (int) – Logging controls.

  • log_fn (Callable[[str], None]) – Logging controls.

Returns:

Canonical (B, H, Q, O) and optionally the layout.

Return type:

arr or (arr, layout)

geoprior.utils.shapes.canonicalize_BHQO_quantiles_np(y, n_q=3, *, verbose=0, log_fn=<built-in function print>)[source]#

Return y in canonical (B,H,Q,O).

Accepts common layouts:

  • (B,H,Q,O) -> unchanged

  • (B,Q,H,O) -> transpose(0,2,1,3)

  • (B,H,O,Q) -> transpose(0,1,3,2)

If ambiguous (multiple axes match n_q), choose the transform with minimal quantile crossing score.

Parameters:
Return type:

Any