sphstat.utils module

Utility functions

degtorad() converts sample in ‘deg’ to a sample in ‘rad’
readsample() reads one or more samples from an Excel file
polartocart() converts sample in ‘rad’ format to a sample in ‘cart’ format
carttopolar() converts sample in ‘cart’ format to a sample in ‘rad’ format
excludesample() removes an observation from a sample
deepcopy() generates a deep copy of a sample
poolsamples() combines multiple samples into a single sample
angle() calculates the angle between two vectors
cart2sph() converts a point from Cartesian to polar format
sph2cart() converts a point from polar to Cartesian format
negatesample() generates a sample with observations in the opposing direction of the observations in a sample
cot() calculates the cotangent of the input
poltoll() converts a pair of polar angles to langitude/latitude ‘lonlat’ form
poltodi() converts a pair of polar angles to declination/inclination ‘decinc’ form
convert() converts a sample in ‘decinc’ or ‘lonlat’ form to polar form
maptofundamental() maps the angles to the fundamental range, i.e. 0 <= th <= pi and 0 <= phi < 2 * pi
randompermutations() creates a number of random permutation indices
jackknife() is a generic jackknife function
prettyprintdict() prints a dictionary (e.g. results from a hypothesis test) in an easy to read format

sphstat.utils.angle(pt1: numpy.ndarray, pt2: numpy.ndarray) → float[source]

Return the angle between two unit vectors

Parameters

pt1 (numpy.array) – Vector with unit norm
pt2 (numpy.array) – Vector with unit norm

Returns

Angle between the two vectors in radians

Return type

float

sphstat.utils.cart2sph(pt: numpy.array) → tuple[source]

Convert unit vector from Cartesian to polar (i.e. spherical) coordinates

Parameters: pt – Unit norm vector in Cartesian coordinates
Returns: Tuple containing inclination and azimuth angles: th, ph
Return type: tuple

sphstat.utils.carttopolar(sample: dict) → dict[source]

Convert the sample given in Cartesian coordinates to polar/spherical

Parameters: sample (dict) – Dictionary that contains the data (e.g. from readsample()) in ‘cart’ format
Returns: Converted dictionary containing data, number of data points, and type of data
Return type: dict

sphstat.utils.convert(sample: dict, fromformat: str) → dict[source]: Convert sample to the polar coordinates used in sphstat package :param sample: Sample in ‘rad’ format :param fromformat: One of ‘latlon’, ‘decinc’, ‘plunge’… :return:

sphstat.utils.cot(x)[source]

Cotangent of the argument

Parameters: x (float) – Angle in radians
Returns: Cotangent of the input
Return type: float

sphstat.utils.deepcopy(samplecart: dict) → dict[source]

Generate a new data dictionary that is a (deep) copy of the original

Parameters: samplecart (dict) – Dictionary that contains the data (e.g. from readsample()) in ‘cart’ format
Returns: Dictionary with the datum removed
Return type: dict

sphstat.utils.degtorad(sample: dict) → dict[source]

Utility function to convert observations on the unit sphere given in degrees to radians and create a new ‘sample’

Parameters: sample (dict) – Dictionary that contains the data (e.g. from readsample())
Returns: Converted dictionary containing data, number of data points, and type of data
Return type: dict

sphstat.utils.excludesample(samplecart: dict, excludeind: int) → dict[source]

Exclude the datum with a given index from the data and generate new sample with the outlier eliminated

Parameters

samplecart (dict) – Dictionary that contains the data (e.g. from readsample()) in ‘cart’ format
excludeind – Index of the datum to be excluded

Returns

Dictionary with the datum removed

Return type

dict

sphstat.utils.jackknife(estfun: Callable, funargs: tuple, sample: dict, dictkey: Optional[str] = None, tupleind: Optional[int] = None, alpha: float = 0.05, unbiasflag: bool = True) → tuple[source]

Jackknife method for calculating an approximate confidence interval for an statistical parameter of a sample

Parameters

estfun (Callable) – Function that outputs the desired statistical parameter
funargs (tuple) – Arguments to be passed to estfun
sample (dict) – Sample to be used in the computations
dictkey – If the function returns a dictionary use the value for this key
dictkey – ‘str’
tupleind – If the function returns a tuple use the value at this index
tupleind – int
alpha (float) – (1-alpha)% CI is calculated
unbiasflag (bool) – Flag indicating whether estfun gives an unbiased estimate

Returns

psijhat: Unbiased estimate using the jackknife method (float)
ci: (1-alpha)% confidence interval

Return type

tuple

sphstat.utils.maptofundamental(dirct: tuple) → tuple[source]

Utility function to map a pair of angles to the fundamental polar range

Parameters: dirct (tuple) – Inclination and azimuth angles
Returns: Remapped angles th and ph
Return type: tuple

sphstat.utils.negatesample(samplecart: dict) → dict[source]

Negate the vectors in a sample

Parameters: samplecart (dict) – Dictionary that contains the data (e.g. from readsample())
Returns: Sample with observations containing negated directions
Return type: dict

sphstat.utils.polartocart(sample: dict) → dict[source]

Convert the sample given in polar coordinates to Cartesian

Parameters: sample (dict) – Dictionary that contains the data (e.g. from readsample())
Returns: Converted dictionary containing data, number of data points, and type of data
Return type: dict

sphstat.utils.poltodi(th, ph)[source]

Convert polar form to declination/inclination form

Parameters

th (float) – Colatitude angle (0 <= th <= np.pi)
ph (float) – Longitude angle (0 <= ph < 2 * np.pi)

Returns

lat: Inclination angle
lon: Declination angle

Return type

tuple

sphstat.utils.poltoll(th: float, ph: float) → tuple[source]

Convert polar form to longitude/latitude form

Parameters

th (float) – Colatitude angle (0 <= th <= np.pi)
ph (float) – Longitude angle (0 <= ph < 2 * np.pi)

Returns

lat: Latitude angle
lon: Longitude angle

Return type

tuple

sphstat.utils.poolsamples(samplelist: list, typ='cart') → dict[source]

Combine multiple samples in a single data dictionary

Parameters

samplelist (list) – List of data dictionaries
typ (str) – ‘deg’, ‘rad’, ‘cart’ Defaults to ‘cart’

Returns

Dictionary that contains all data in the input list of data dictionaries

Return type

dict

sphstat.utils.prettyprintdict(data: dict)[source]

Print a dictionary contents in a user friendly way

Parameters: data (dict) – A dictionary containing some data
Returns: None
Return type: None

sphstat.utils.randompermutations(rangein: int, numpermute: int) → list[source]

Generate random permutations

Parameters

rangein (int) – Number of observations to be permuted (n)
numpermute (int) – Number of unique permutations to use

Returns

List of lists of index permutations

Return type

list

sphstat.utils.readsample(path: str, wsindex=0, typ='deg') → dict[source]

Reads a number of observations comprising a sample. Data assumed to be polar and in degrees by default

Parameters

path (str) – String containing the PATH to the file containing data to be processed
wsindex (int, optional) – Index of the worksheet in which the data resides, Defaults to 0 which is the active worksheet
typ (str) – ‘deg’, ‘rad’, ‘cart’ Defaults to ‘deg’

Returns

Dictionary containing data, number of data points, and type of data

Return type

dict

sphstat.utils.sph2cart(th: float, ph: float) → numpy.array[source]

Convert unit vector from polar (i.e. spherical) tp Cartesian coordinates

Parameters

th (float) – Inclination angle of the vector 0 <= th <= pi
ph (float) – Azimuth angle of the vector 0 <= th <= 2 * pi

Returns

Array containing x, y, z components of the vector

Return type

np.array