vectorose.mock_data =================== .. py:module:: vectorose.mock_data .. autoapi-nested-parse:: 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. .. rubric:: References .. [#fisher-lewis-embleton] Fisher, N. I., Lewis, T., & Embleton, B. J. J. (1993). Statistical analysis of spherical data ([New ed.], 1. paperback ed). Cambridge Univ. Press. Functions --------- .. autoapisummary:: vectorose.mock_data.create_vonmises_fisher_vectors_single_direction vectorose.mock_data.convert_args_to_length vectorose.mock_data.create_von_mises_fisher_vectors_multiple_directions vectorose.mock_data.generate_watson_distribution vectorose.mock_data.generate_watson_vectors_multiple_directions Module Contents --------------- .. py:function:: 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: Optional[int] = None) -> numpy.ndarray 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. :param phi: Mean phi value, where phi reflects the inclination from the positive z-axis. :param theta: Mean theta value, where theta reflects the in-plane angle clockwise from the positive y-axis. :param kappa: Concentration parameter for the von Mises-Fisher distribution. :param number_of_points: Number of points to draw from the distribution. :param magnitude: Average magnitude for the computed vectors. :param magnitude_std: Standard deviation for the magnitude distribution. If this is a positive value, the magnitudes follow a Gaussian distribution with mean `magnitude`. :param use_degrees: Indicate whether the angles `phi` and `theta` are provided in degrees. :param seed: Optional seed for random number generation. :returns: :class:`numpy.ndarray` -- Array of shape ``(number_of_points, 3)`` containing the generated vectors. .. seealso:: :obj:`scipy.stats.vonmises_fisher` Function used to generate the von Mises-Fisher distribution. .. rubric:: Notes This function relies on the von Mises-Fisher distribution, which is a true probability distribution on the sphere. .. py:function:: convert_args_to_length(n: int, *args: Union[float, collections.abc.Collection[float]]) -> tuple[numpy.ndarray, Ellipsis] Standardise the length of all arguments. Convert the provided numbers or collections of numbers to NumPy arrays of a specified length. :param n: The length to which all fields will be standardised. :param \*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: :class:`tuple` of :class:`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`. .. py:function:: 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: Union[int, collections.abc.Collection[int]] = 1000, magnitudes: Union[float, collections.abc.Collection[float]] = 1.0, magnitude_stds: Union[float, collections.abc.Collection[float]] = 0.5, use_degrees: bool = False, seeds: Optional[collections.abc.Collection[int]] = None) -> numpy.ndarray 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. :param phis: The set of ``phi`` values for the mean direction. :param thetas: The set of ``theta`` values for the mean direction. :param kappas: The set of concentration parameters for the distributions. If a single :class:`float` is passed, the same concentration parameter will be used for each set of vectors. :param numbers_of_vectors: Number of vectors to produce for each parameter set. If a single :class:`int` is passed, the same number of vectors will be generated for each parameter set. :param magnitudes: The average magnitude of the vectors produced for each parameter set. If a single :class:`float` is passed, then the same average magnitude is used for all parameter sets. :param 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 :class:`float` is passed, then the same standard deviation is used for all parameter sets. :param use_degrees: Indicate whether the provided angles are in degrees. If `False`, the angles are assumed to be in radians. :param seeds: Optional seeds for the random number generation for reproducibility. :returns: :class:`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. .. seealso:: :obj:`create_vonmises_fisher_vectors_single_direction` Function that generates vectors drawn from a single von Mises-Fisher distribution. .. py:function:: generate_watson_distribution(mean_direction: numpy.ndarray, kappa: float, n: int = 100000, seed: Optional[int] = None) -> numpy.ndarray Generate points from a Watson distribution. Simulate a orientations from a Watson distribution using the steps presented by Fisher, Lewis and Embleton [#fisher-lewis-embleton]_ in section 3.6.2. :param mean_direction: Cartesian coordinates of the mean direction. :param kappa: Shape parameter of the watson distribution. :param n: Number of points to generate. :param seed: Optional seed for the random number generator. :returns: :class:`numpy.ndarray` -- Array with `n` rows, corresponding to the 3D Cartesian coordinates of the pseudo-randomly generated points. .. py:function:: generate_watson_vectors_multiple_directions(phis: collections.abc.Collection[float], thetas: collections.abc.Collection[float], kappas: collections.abc.Collection[float], numbers_of_vectors: Union[int, collections.abc.Collection[int]] = 1000, use_degrees: bool = False, seeds: Optional[collections.abc.Collection[int]] = None) -> numpy.ndarray Create vectors drawn from multiple von Watson distributions. Using the supplied arguments, generate a collection of vectors drawn from multiple Watson distributions. :param phis: The set of ``phi`` values for the mean direction. :param thetas: The set of ``theta`` values for the mean direction. :param kappas: The set of shape parameters for the distributions. If a single :class:`float` is passed, the same shape parameter will be used for each set of vectors. :param numbers_of_vectors: Number of vectors to produce for each parameter set. If a single :class:`int` is passed, the same number of vectors will be generated for each parameter set. :param use_degrees: Indicate whether the provided angles are in degrees. If `False`, the angles are assumed to be in radians. :param seeds: Optional seeds for the random number generation for reproducibility. :returns: :class:`numpy.ndarray` -- The generated vectors drawn from different Watson distributions. .. warning:: The array-like arguments must **all** have the same length, unless a single value is provided. .. seealso:: :obj:`generate_watson_distribution` Function that generates vectors drawn from a Watson distribution. :obj:`create_von_mises_fisher_vectors_multiple_directions` Similar function for generating vectors from multiple von Mises-Fisher distributions.