vectorose.mock_data#

Mock vector data creator.

This module provides tools to create artificial vectors for testing.

Warning

This module does not exist as an automatic top-level import in vectorose, and must therefore be explicitly imported.

References

Functions#

`create_vonmises_fisher_vectors_single_direction`(...)	Create a set of vectors using a von Mises-Fisher distribution.
`convert_args_to_length`(→ tuple[numpy.ndarray, Ellipsis])	Standardise the length of all arguments.
`create_von_mises_fisher_vectors_multiple_directions`(...)	Create vectors drawn from multiple von Mises-Fisher distributions.
`generate_watson_distribution`(→ numpy.ndarray)	Generate points from a Watson distribution.
`generate_watson_vectors_multiple_directions`(...)	Create vectors drawn from multiple von Watson distributions.

Module Contents#

vectorose.mock_data.create_vonmises_fisher_vectors_single_direction(phi: float, theta: float, kappa: float, number_of_points: int, magnitude: float = 1.0, magnitude_std: float = 0, use_degrees: bool = False, seed: int | None = None) → numpy.ndarray[source]#

Create a set of vectors using a von Mises-Fisher distribution.

Draw a set of random orientations from a von Mises-Fisher distribution on the unit sphere. The magnitude of these vectors can be modified using a normal distribution. These vectors are represented by components without any spatial coordinates.

Parameters:

phi – Mean phi value, where phi reflects the inclination from the positive z-axis.
theta – Mean theta value, where theta reflects the in-plane angle clockwise from the positive y-axis.
kappa – Concentration parameter for the von Mises-Fisher distribution.
number_of_points – Number of points to draw from the distribution.
magnitude – Average magnitude for the computed vectors.
magnitude_std – Standard deviation for the magnitude distribution. If this is a positive value, the magnitudes follow a Gaussian distribution with mean magnitude.
use_degrees – Indicate whether the angles phi and theta are provided in degrees.
seed – Optional seed for random number generation.

Returns:

numpy.ndarray – Array of shape (number_of_points, 3) containing the generated vectors.

See also

scipy.stats.vonmises_fisher: Function used to generate the von Mises-Fisher distribution.

Notes

This function relies on the von Mises-Fisher distribution, which is a true probability distribution on the sphere.

vectorose.mock_data.convert_args_to_length(n: int, *args: float | collections.abc.Collection[float]) → tuple[numpy.ndarray, Ellipsis][source]#

Standardise the length of all arguments.

Convert the provided numbers or collections of numbers to NumPy arrays of a specified length.

Parameters:

n – The length to which all fields will be standardised.
*args – The arguments to convert to arrays of a specified length. Each must either be a single value (or a collection of length 1) or a collection of length n.

Returns:

tuple of numpy.ndarray – The converted values in the same order they were originally passed. Any NumPy arrays passed will not be copied and the original arrays will simply be returned.

Raises:

ValueError – If collections passed in have a length that is not 1 or n.

vectorose.mock_data.create_von_mises_fisher_vectors_multiple_directions(phis: collections.abc.Collection[float], thetas: collections.abc.Collection[float], kappas: collections.abc.Collection[float], numbers_of_vectors: int | collections.abc.Collection[int] = 1000, magnitudes: float | collections.abc.Collection[float] = 1.0, magnitude_stds: float | collections.abc.Collection[float] = 0.5, use_degrees: bool = False, seeds: collections.abc.Collection[int] | None = None) → numpy.ndarray[source]#

Create vectors drawn from multiple von Mises-Fisher distributions.

Using the supplied arguments, generate a collection of vectors drawn from multiple von Mises-Fisher distributions. These vectors may have non-unit magnitude, determined using a Gaussian distribution.

Parameters:

phis – The set of phi values for the mean direction.
thetas – The set of theta values for the mean direction.
kappas – The set of concentration parameters for the distributions. If a single float is passed, the same concentration parameter will be used for each set of vectors.
numbers_of_vectors – Number of vectors to produce for each parameter set. If a single int is passed, the same number of vectors will be generated for each parameter set.
magnitudes – The average magnitude of the vectors produced for each parameter set. If a single float is passed, then the same average magnitude is used for all parameter sets.
magnitude_stds – The standard deviation of the magnitude for each parameter set. If greater than zero, then the magnitudes are drawn from a normal distribution. If a single float is passed, then the same standard deviation is used for all parameter sets.
use_degrees – Indicate whether the provided angles are in degrees. If False, the angles are assumed to be in radians.
seeds – Optional seeds for the random number generation for reproducibility.

Returns:

numpy.ndarray – The generated vectors drawn from different von Mises-Fisher distributions.

Warning

The array-like arguments must all have the same length, unless a single value is provided.