pvtend.compute_orthogonal_basis

pvtend.compute_orthogonal_basis(pv_anom: ndarray, pv_dx: ndarray, pv_dy: ndarray, x_rel: ndarray, y_rel: ndarray, *, pv_dx_dy: ndarray | None = None, pv_dx_dx: ndarray | None = None, pv_dy_dy: ndarray | None = None, geopotential: ndarray | None = None, mask: str | bool | ndarray | None = '< 0', apply_smoothing: bool = True, smoothing_deg: float = 3.0, smoothing_method: str = 'gaussian', grid_spacing: float = 1.5, center_lat: float = 60.0, apply_lat_weighting: bool = False, prenorm_mode: str = 'auto', pv_anom_prev: ndarray | None = None, pv_dx_prev: ndarray | None = None, pv_dy_prev: ndarray | None = None, pv_dx_dy_prev: ndarray | None = None, pv_dx_dx_prev: ndarray | None = None, pv_dy_dy_prev: ndarray | None = None, interp_alpha: float = 1.0, include_lap: bool = True, mask_negative: bool | None = None, mask_threshold: float | None = None) → OrthogonalBasisFields[source]

Compute six orthogonal basis fields from composite PV fields.

Parameters:

  • pv_anom – PV anomaly q’ in SI units.

  • pv_dx – Zonal PV gradient ∂q/∂x in SI.

  • pv_dy – Meridional PV gradient ∂q/∂y in SI.

  • x_rel – 1D relative x-coordinates (degrees).

  • y_rel – 1D relative y-coordinates (degrees).

  • pv_dx_dy – Pre-computed ∂²q/∂x∂y. Falls back to np.gradient if None.

  • pv_dx_dx – Pre-computed ∂²q/∂x². Falls back to np.gradient if None.

  • pv_dy_dy – Pre-computed ∂²q/∂y². Falls back to np.gradient if None.

  • geopotential – Optional geopotential for overlay plots.

  • mask –

    PV anomaly masking specification. Accepts:

    • str — comparison expression applied to q’, e.g. "< 0" (default, blocking), "< -2e-7" (tight single- event), "> 2e-7" (cyclones).

    • bool — True is equivalent to "< 0", False disables PV masking.

    • None — no PV-anomaly masking (NaN/Inf filtering only).

    • np.ndarray (bool, same shape as pv_anom) — a user- supplied mask; True = include in projection.

    Default "< 0" selects all grid points where q’ < 0 PVU.

  • apply_smoothing – Apply spatial smoothing after pre-normalization.

  • smoothing_deg – Smoothing FWHM (degrees). Default 3.0°.

  • smoothing_method – ‘gaussian’ or ‘fourier’.

  • grid_spacing – Grid spacing in degrees.

  • center_lat – Approximate latitude of the patch centre (degrees N). Used to compute cos(lat)-corrected zonal metric for the second-order derivative fallbacks (∂²q/∂x²). Defaults to 60.0°N (typical blocking latitude). Set to 0.0 to recover the old equatorial-metric behaviour.

  • apply_lat_weighting – Use cos(lat) weighting.

  • prenorm_mode – "auto" (default) for per-event runtime normalization, or "fixed" for legacy PRENORM constants.

  • pv_anom_prev – PV anomaly q’ at dh−1 (the earlier snapshot). If provided, pv_dx_prev and pv_dy_prev must also be given.

  • pv_dx_prev – Zonal PV gradient at dh−1.

  • pv_dy_prev – Meridional PV gradient at dh−1.

  • pv_dx_dy_prev – Pre-computed ∂²q/∂x∂y at dh−1. Optional; when given together with pv_dx_dx_prev and pv_dy_dy_prev, the second-order derivatives are also interpolated. When omitted the interpolated first-order gradients are used to recompute them via finite differences (less accurate).

  • pv_dx_dx_prev – Pre-computed ∂²q/∂x² at dh−1.

  • pv_dy_dy_prev – Pre-computed ∂²q/∂y² at dh−1.

  • interp_alpha – Interpolation weight for the positional (current-dh) fields. Default 1.0 uses only the current-dh fields (no interpolation).

  • include_lap – Whether to include the Laplacian (Φ₆) basis. When False, the Laplacian field is zeroed before prenorm so that Gram-Schmidt produces a zero-norm 6th basis. Default True.

  • mask_negative – Deprecated. Use mask instead.

  • mask_threshold – Deprecated. Use mask="< <value>" instead.

Returns:

OrthogonalBasisFields container.