Python API

The core Orientation module

The core orientation module contains classes implementing different planar fitting algorithms. These methods generally produce an object describing a planar fit.

The most useful of these methods is described by

class attitude.orientation.pca.PCAOrientation(arr, weights=None, axes=None)

Gets the axis-aligned principle components of the dataset.

U

Property to support lazy evaluation of residuals

angular_error(axis_length)

The angular error for an in-plane axis of given length (either a PCA major axis or an intermediate direction).

angular_errors(degrees=True)

Minimum and maximum angular errors corresponding to 1st and 2nd axes of PCA distribution.

as_conic(level=1)

as_hyperbola(rotated=False)

Hyperbolic error area

azimuth

center

centered_array

coefficients

covariance_matrix

The data covariance matrix is related to the cross-product matrix M^T M but scaled by the number of samples.

eigenvalues

Eigenvalues of the data covariance matrix

error_coords(**kwargs)

error_ellipse(spherical=True, vector=False, level=1)

explained_variance

Proportion of variance that is explained by the first two principal components (which together represent the planar fit). Analogous to R^2 of linear least squares.

classmethod from_axes()

Recovers a principal component dataset from a set of axes (singular values*principal axes) of the dataset.

hyperbolic_axes

plane_errors(**kwargs)

rake()

residuals()

Returns residuals of fit against all three data axes (singular values 1, 2, and 3). This takes the form of data along singular axis 3 (axes 1 and 2 define the plane)

rotated()

Returns a dataset ‘despun’ so that it is aligned with the princpal axes of the dataset.

slope

strike_dip(degrees=True)

Computes strike and dip from a normal vector. Results are usually the same as LLSQ in strike (to a few decimal places) and close in dip. Sometimes, dips are greater by as much as 45 degrees, reflecting inclusion of errors in x-y plane.

strike_dip_rake()

to_mapping(**values)

Create a JSON-serializable representation of the plane that is usable with the javascript frontend

Other orientation representations

A few other representations of orientation error spaces have been prepared for use when working with grouped or reconstructed planes.

class attitude.orientation.grouped.GroupedOrientation(*orientations, **kwargs)

to_mapping(**values)

Create a JSON-serializable representation of the plane that is usable with the javascript frontend

exception attitude.orientation.grouped.GroupedPlaneError

attitude.orientation.grouped.create_groups(orientations, *groups, **kwargs)

Create groups of an orientation measurement dataset

class attitude.orientation.reconstructed.ErrorShell(axes, covariance)

Object representing a specific error level

class attitude.orientation.reconstructed.ReconstructedPlane(strike, dip, rake, *angular_errors, **kwargs)

This class represents a plane with errors on two axes. This error is presumably the result of some statistical process, and is a single confidence interval or shell derived from this result.

Construction of error bars

attitude.error.asymptotes(hyp, n=1000)

Gets a cone of asymptotes for hyperbola

attitude.error.average_orientation(orientations)

Find the average orientation of a set of fitted or reconstructed orientations, taking into account uncertainty.

attitude.error.from_normal_errors(ax1)

Hyperbolic error axis lengths for planes from the equivalent representation for normal vector endpoints

attitude.error.pca_to_mapping(pca, **extra_props)

A helper to return a mapping of a PCA result set suitable for reconstructing a planar error surface in other software packages

kwargs: method (defaults to sampling axes)

attitude.error.to_normal_errors(axes)

A temporary method that gets normal vector errors corresponding with a fitted orientation

Functions for converting fit parameters into covariance and hyperbolic axes. These all operate in axis-aligned space—rotation into global coordinate systems should occur after these transformations are applied.

attitude.error.axes.angular_errors(hyp_axes)

Minimum and maximum angular errors corresponding to 1st and 2nd axes of PCA distribution.

Ordered as [minimum, maximum] angular error.

attitude.error.axes.apply_error_level(cov, level)

Adds sigma level to covariance matrix

attitude.error.axes.apply_error_scaling_old(nominal, errors, **kw)

This method does not account for errors on the in-plane axes

attitude.error.axes.axis_angular_error(hyp_axes, axis_length)

The angular error for an in-plane axis of given length (either a PCA major axis or an intermediate direction).

attitude.error.axes.mean_estimator(data_variance, n)

Get the variance of the mean from a data variance term (e.g. an eigenvalue) and return an estimator of the precision of the mean

attitude.error.axes.noise_covariance(fit, dof=2, **kw)

Covariance taking into account the ‘noise covariance’ of the data. This is technically more realistic for continuously sampled data. From Faber, 1993

attitude.error.axes.sampling_axes(fit, **kw)

Hyperbolic axis lengths based on sample-size normal statistics

attitude.error.axes.statistical_axes(fit, **kw)

Hyperbolic error using a statistical process (either sampling or noise errors)

Integrates covariance with error level and degrees of freedom for plotting confidence intervals.

Degrees of freedom is set to 2, which is the relevant number of independent dimensions to planar fitting of a priori centered data.

attitude.error.axes.weingarten_axes(fit, confidence_level=0.95)

This is basically meaningless in its current form

Display functions

Functions for displaying data using matplotlib, cartopy, and interactive javascript, both for static plotting and the IPython notebook.

Deprecated code for generating HTML reports is also included in this module.

Helper functions

attitude.coordinates.centered(coordinates)

Centers coordinate distribution with respect to its mean on all three axes. This is used as the input to the regression model, so it can be converted easily into radial coordinates.

attitude.coordinates.spherical(coordinates)

No error is propagated