sphstat.descriptives module

Functions to calculate descriptive statistics on spherical data

• resultants() calculates the descriptive statistics of a sample

• rotationmatrix() calculates the rotation matrix for a given set of rotation angles

• rotationmatrix_withaxis() calculates the rotation matrix with respect to an axis

• rotate() rotates a point with the given set of rotation angles

• rotatesample() rotate all observations in a sample with the given set of rotation angles

• movematrix() calculates the matrix which moves a vector to another vector

• orientationmatrix() calculates the orientation matrix for a sample

• momentofinertia() calculates the moment of intertia of a sample with respect to a point

• pointsonanellipse() calculates a number of points on an ellipse

• mediandir() calculates the median direction of a sample

sphstat.descriptives.mediandir(sample: dict, ciflag: bool = True, alpha: float = 0.05) → tuple

Find the median direction and the confidence cone of the sample. Before this, make sure that the sample comes from a unimodal distribution

Parameters

• sample (dict) – Sample to be tested in ‘cart’ format

• ciflag (bool) – (1-alpha)% confidence cone calculation

• alpha (float) – Type-I error level for the CI (e.g. 0.05)

Returns

Tuple with: - Median direction [theta, phi] (np.array) - Optimisation successful? (bool) - Confidence cone parameters (dict) - W matrix (np.ndarray)

Return type

tuple

sphstat.descriptives.momentofinertia(samplecart: dict, pt0: numpy.ndarray) → float

Calculate the moment of inertia for a point given a sample

Parameters

• samplecart (dict) – Sample in cart format

• pt0 (np.ndarray) – Point

Returns

Moment of inertia

Return type

float

sphstat.descriptives.movematrix(pt1: numpy.ndarray, pt2: numpy.ndarray) → numpy.ndarray

Move a vector pt1 to pt2

Parameters

• pt1 (np.ndarray) – Source point

• pt2 (np.ndarray) – Destination point

Returns

Matrix that moves pt1 to pt2 such that pt2 = H @ pt1,

Return type

np.ndarray

sphstat.descriptives.orientationmatrix(samplecart)

Calculate the orientation matrix and its eigenvectors / eigenvalues for a given sample

Parameters

samplecart (dict) – Sample in cart format

Returns

Orientation matrix

Return type

np.ndarray

sphstat.descriptives.pointsonanellipse(h1: numpy.ndarray, h2: numpy.ndarray, h3: numpy.ndarray, ellipsecoeffs: tuple, psinum: int = 360) → list

Calculate a number of points on an ellipse on the sphere

Parameters

• h1 (np.ndarray) – First axis

• h2 (np.ndarray) – Second axis

• h3 (np.ndarray) – Third axis

• ellipsecoeffs (tuple) – Parameters of the ellipse

• psinum (int) – Number of points to calculate

Returns

Points on a sphere as a list

Return type

list

sphstat.descriptives.resultants(samplecart: dict) → dict

Summary statistics of the data in sample. Data must be in cartesian coordinates (i.e. convert first using polartocart() if data is in polar coordinates)

Parameters

samplecart – Data in ‘cart format’

Returns

A dictionary containing different summary statistics for the data

Return type

dict

sphstat.descriptives.rotate(pt: numpy.array, th0: float, ph0: float, psi0: float = 0.0) → numpy.ndarray

Rotate a single point by (th0, ph0, psi0)

Parameters

• pt (np.ndarray) – Point to be rotated

• th0 (float) – Inclination rotation angle (in rad)

• ph0 (float) – Azimuth rotation angle (in rad)

• psi0 (float) – Polar axis rotation angle (Defaults to 0.0)

Returns

Rotated point

Return type

np.ndarray

sphstat.descriptives.rotatesample(sample: dict, th0: float, ph0: float, psi0: float = 0.0) → dict

Rotate all observations in a sample by (th0, ph0, psi0)

Parameters

• sample (dict) – Sample to be rotated in cart format

• th0 (float) – Inclination rotation angle (in rad)

• ph0 (float) – Azimuth rotation angle (in rad)

• psi0 (float) – Polar axis rotation angle (Defaults to 0.0)

Returns

Sample with all points rotated by the given rotation parameters

Return type

dict

sphstat.descriptives.rotationmatrix(th0: float, ph0: float, psi0: float = 0.0) → numpy.ndarray

Rotation matrix to rotate data in a given direction (th0, ph0)

Parameters

• th0 – Inclination angle of the rotation

• ph0 – Azimuth angle of the rotation

• psi0 – Rotation angle about the polar axis (Default is 0)

Returns

Rotation matrix

Return type

np.ndarray

sphstat.descriptives.rotationmatrix_withaxis(ua: numpy.array, ub: numpy.array) → numpy.ndarray

Calculate a rotation matrix around an axis

Parameters

• ua (np.array) – First unit vector

• ub (np.array) – First unit vector

Returns

Rotation matrix

Return type

np.ndarray

sphstat.descriptives.shapestrength(sample: dict) → tuple

Exploratory summary metrics for assessing properties of the underlying distribution

Parameters

sample (dict) – Sample in cart format

Returns

• shape: Shape parameter

• strength: Strength parameter

Return type

tuple