2.6.2.1. pycsamt.emtf.orientation#

Format-neutral EMTF rotation and covariance transformations.

The implementation follows the general matrix formulation used by EMTF FCU:

TF' = V @ TF @ U.T

where U transforms input-channel coordinates and V transforms output-channel coordinates. When full error covariance factors are present, S (inverse signal covariance) and N (residual covariance) transform as S' = U @ S @ U.T and N' = V @ N @ V.T.

The physical SiteLayout is never rotated here. It continues to describe the original field geometry while OrientationMeta records the coordinate frame of the transfer-function data.

Functions

horizontal_inverse_rotation_matrix(theta1, ...)

Return the inverse of horizontal_rotation_matrix().

horizontal_rotation_matrix(theta1, theta2, ...)

Return the FCU Q transform from two channels to an orthogonal frame.

rotate_covariance(covariance, matrices, *, side)

Rotate an inverse-signal or residual covariance matrix family.

rotate_emtf(document[, angle, target, ...])

Rotate all primary transfer functions in an EMTF document.

rotate_transfer_function(tf, *, source_mode)

Rotate one matrix-valued transfer function and supported estimates.

Classes

RotationMatrices(input_matrix, ...)

Per-period input and output matrices used in an EMTF rotation.

Exceptions

ApproximateVarianceRotationWarning

Warn that variance was handled without complete covariance.

DerivedDataRotationWarning

Warn that derived products were dropped or retained stale.

EMTFRotationError

Raised when an EMTF rotation cannot be defined unambiguously.

EMTFRotationWarning

Base warning for scientifically incomplete EMTF rotations.

LegacyRotationAssumptionWarning

Warn that historical EDI rotation metadata are being interpreted.

UnsupportedEstimateRotationWarning

Warn that a statistical estimate cannot be rotated safely.
exception pycsamt.emtf.orientation.ApproximateVarianceRotationWarning[source]

Bases: EMTFRotationWarning

Warn that variance was handled without complete covariance.

exception pycsamt.emtf.orientation.DerivedDataRotationWarning[source]

Bases: EMTFRotationWarning

Warn that derived products were dropped or retained stale.

exception pycsamt.emtf.orientation.EMTFRotationError[source]

Bases: ValueError

Raised when an EMTF rotation cannot be defined unambiguously.

exception pycsamt.emtf.orientation.EMTFRotationWarning[source]

Bases: UserWarning

Base warning for scientifically incomplete EMTF rotations.

exception pycsamt.emtf.orientation.LegacyRotationAssumptionWarning[source]

Bases: EMTFRotationWarning

Warn that historical EDI rotation metadata are being interpreted.

class pycsamt.emtf.orientation.RotationMatrices(input_matrix, output_matrix, source_mode, target_mode, source_angles, target_angle)[source]

Bases: object

Per-period input and output matrices used in an EMTF rotation.

Parameters:

  • input_matrix (ndarray) – Array of shape (n_period, n_input, n_input) containing U.

  • output_matrix (ndarray) – Array of shape (n_period, n_output, n_output) containing V.

  • source_mode (str) – Coordinate-frame modes used to construct the matrices.

  • target_mode (str) – Coordinate-frame modes used to construct the matrices.

  • source_angles (ndarray or None) – Orthogonal source azimuth(s), in degrees clockwise from geographic north. None when the source follows the physical site layout.

  • target_angle (float or None) – Orthogonal target azimuth. None for site-layout targets.

input_matrix: ndarray
output_matrix: ndarray
source_mode: str
target_mode: str
source_angles: ndarray | None
target_angle: float | None
property n_periods: int[source]
property is_identity: bool[source]

Return whether both matrix families are identities.

exception pycsamt.emtf.orientation.UnsupportedEstimateRotationWarning[source]

Bases: EMTFRotationWarning

Warn that a statistical estimate cannot be rotated safely.

pycsamt.emtf.orientation.horizontal_rotation_matrix(theta1, theta2, target_angle)[source]

Return the FCU Q transform from two channels to an orthogonal frame.

Angles are degrees clockwise from geographic north. The source channels need not be orthogonal. The matrix maps source vector components into a right-handed orthogonal coordinate frame whose x-axis has azimuth target_angle.

Parameters:
Return type:

ndarray

pycsamt.emtf.orientation.horizontal_inverse_rotation_matrix(theta1, theta2, target_angle)[source]

Return the inverse of horizontal_rotation_matrix().

The explicit formula mirrors EMTF FCU rot2inv and permits a non-orthogonal original site layout. Parallel channels are singular and therefore rejected.

Parameters:
Return type:

ndarray

pycsamt.emtf.orientation.rotate_covariance(covariance, matrices, *, side)[source]

Rotate an inverse-signal or residual covariance matrix family.

Parameters:

  • covariance (array-like) – Shape (n_period, n, n).

  • matrices (array-like) – The corresponding U or V matrices for every period.

  • side ({"input", "output"}) – Descriptive validation label. Both covariance kinds use R @ C @ R.T; the side identifies which matrix family is supplied.

Return type:

ndarray

pycsamt.emtf.orientation.rotate_emtf(document, angle=0.0, *, target='orthogonal', inplace=False, source_angles=None, use_legacy_edi_rotation=False, variance_policy='drop', unsupported_estimates='drop', derived_policy='drop')[source]

Rotate all primary transfer functions in an EMTF document.

Parameters:

  • document (EMTF) – Source scientific document.

  • angle (float, optional) – Target azimuth in degrees clockwise from geographic north. Ignored for target='sitelayout'.

  • target ({"orthogonal", "sitelayout"}) – Coordinate frame to produce.

  • inplace (bool, default=False) – If True, mutate and return document. The original physical SiteLayout object is never modified.

  • source_angles (scalar, array-like, mapping, optional) – Explicit orthogonal source angle(s). A mapping may provide different vectors by TF tag/code, useful for historical principal-axis EDI.

  • use_legacy_edi_rotation (bool, default=False) – Opt in to interpreting retained edi_zrot / edi_trot vectors as orthogonal source frames when document-level orientation is ambiguous.

  • variance_policy ({"drop", "raise", "independent", "fcu"}) – Behavior for VAR when full covariance factors are unavailable.

  • unsupported_estimates ({"drop", "keep", "raise"}) – Policy for estimates without a defined rotation law.

  • derived_policy ({"drop", "keep", "raise"}) – Derived products are not rotated directly; normally they should be recomputed after rotating their primary transfer function.

Return type:

EMTF

pycsamt.emtf.orientation.rotate_transfer_function(tf, *, source_mode, target_mode='orthogonal', target_angle=0.0, source_angles=None, site_layout=None, variance_policy='drop', unsupported_estimates='drop')[source]

Rotate one matrix-valued transfer function and supported estimates.

Full INVSIGCOV + RESIDCOV factors are rotated exactly and VAR is recomputed from their diagonal products. If full covariance is absent, variance_policy controls whether VAR is dropped, rejected, or transformed under an explicit approximation.

Parameters:
Return type:

TransferFunction