vectorose.sphere_base ===================== .. py:module:: vectorose.sphere_base .. autoapi-nested-parse:: Basics for spherical histogram construction. This module contains basic tools for different representations of optionally-nested spherical histograms. Classes ------- .. autoapisummary:: vectorose.sphere_base.SphereBase Module Contents --------------- .. py:class:: SphereBase(number_of_shells: int = 1, magnitude_range: Optional[Tuple[float, float]] = None) Bases: :py:obj:`abc.ABC` Base class for a spherical histogram. .. py:attribute:: number_of_shells :type: int Number of shells to consider for bivariate vector histograms. .. py:attribute:: magnitude_range :type: Optional[Tuple[float, float]] Range for the magnitude values. Maximum and minimum values to consider for the magnitude. If ``None``, then the maximum and minimum values are computed from the provided vectors. .. py:attribute:: magnitude_precision :type: Optional[int] :value: 8 Precision with which to round the magnitudes when binning. To avoid floating point errors, the vector magnitudes may be rounded before binning. This option allows the precision of the rounding to be set. If ``None``, then no rounding is performed. .. py:property:: hist_group_cols :type: List[str] Names of the histogram columns to use for sorting. .. py:property:: magnitude_shell_cols :type: List[str] Name of the histogram columns to use for magnitude. .. py:property:: orientation_cols :type: List[str] :abstractmethod: Name of the histogram columns to use for orientation. .. py:method:: assign_histogram_bins(vectors: numpy.ndarray) -> Tuple[pandas.DataFrame, numpy.ndarray] Assign vectors to the appropriate histogram bin. :param vectors: Array of shape ``(n, 3)`` containing the Cartesian components of the vectors from which to construct the histogram. :returns: * :class:`pandas.DataFrame` -- All the vectors, including additional columns for the shell and the implementation-specific orientation bin. * :class:`numpy.ndarray` -- Histogram bin edges for the magnitude shells. .. warning:: All zero-vectors must be removed from the dataset before processing. These vectors have no orientation and thus cannot be properly assigned to an orientation bin. .. py:method:: _initial_vector_data_preparation(vectors: pandas.DataFrame) -> pandas.DataFrame Prepare the vectors for histogram construction. Convert the vectors into a representation specific for the histogram spherical implementation. If spatial coordinates are provided for the vectors, these are preserved. :param vectors: DataFrame with ``n`` rows and either 3 or 6 columns. The required vector component columns are ``vx, vy, vz``. Optional spatial coordinate columns are ``x, y, z``. It is preferrable (but not required) for the spatial columns to be the first 3 columns. :returns: :class:`pandas.DataFrame` -- DataFrame containing ``n`` rows and a subclass-specific number of columns. The columns represent an alternative representation of the vectors to assist in orientation binning. If spatial coordinate columns were present in the original data they will be preserved in the output. .. warning:: This method should typically **not** be overridden. The implementation-specific functionality should be written in the method :meth:`_initial_vector_component_preparation`, which is called by this function. .. py:method:: _initial_vector_component_preparation(vectors: pandas.DataFrame) -> pandas.DataFrame Prepare the vector components for histogram construction. Override this method to include specific operations that should be performed on the vectors in order to construct the histogram in the specific implementation. .. warning:: This function should **not** perform any tasks related to the vector spatial locations, if those are included in the data. Those are handled separately by :meth:`._initial_vector_data_preparation` which calls this function. .. py:method:: _compute_magnitude_bins(vectors: pandas.DataFrame) -> Tuple[pandas.Series, numpy.ndarray] Perform binning based on magnitude. Construct the magnitude histogram for the provided vectors. :param vectors: The vectors from which the magnitude histogram is to be constructed. :returns: * :class:`pandas.Series` -- The magnitude shell number for each vector, in a :class:`pandas.Series` called ``shell``. * :class:`numpy.ndarray` -- Array containing the histogram bin boundaries used to construct the histogram. The length of this array corresponds is one more than :attr:`SphereBase.number_of_shells`. .. py:method:: _compute_orientation_binning(vectors: pandas.DataFrame) -> pandas.core.generic.NDFrame :abstractmethod: Bin the provided vectors based on orientation. :param vectors: The vectors to place in orientation bins. :returns: :class:`pandas.Series` or :class:`pandas.DataFrame` -- The orientation bin(s) corresponding to each vector. The number of columns will depend on the specific sphere representation used. .. py:method:: _construct_histogram_index() -> pandas.MultiIndex Construct the index for the histogram. .. py:method:: _construct_magnitude_index() -> pandas.Index Construct the index for the magnitude bins. .. py:method:: _construct_orientation_index() -> pandas.Index :abstractmethod: Construct the index for the orientation bins. .. py:method:: construct_histogram(binned_data: pandas.DataFrame, return_fraction: bool = True) -> pandas.Series Construct a histogram based on the labelled data. Using the binned data, construct a histogram with either the counts or the proportion of points in each face. :param binned_data: All vectors, with their respective bins, depending on the current sphere design. :param return_fraction: Indicate whether the values returned should be the raw counts or the proportions. :returns: :class:`pandas.Series` -- The counts or proportions of vectors in each case, ordered by the columns specified in :attr:`SphereBase.hist_group_cols`. .. py:method:: construct_marginal_magnitude_histogram(binned_data: pandas.DataFrame, return_fraction: bool = True) -> pandas.Series Construct the marginal magnitude histogram. Compute the marginal histogram of the magnitude data, disregarding the orientation differences. The resulting histogram has the same number of bins as the number of shells. :param binned_data: Data frame containing the labelled vectors. :param return_fraction: Indicate whether the values returned should be the raw counts or the proportions. :returns: :class:`pandas.Series` -- The counts or proportions of vectors in each magnitude shell. .. seealso:: :obj:`SphereBase.assign_histogram_bins` Label a set of vectors into different bins. :obj:`SphereBase.construct_histogram` Construct a bivariate magnitude and orientation histogram. :obj:`SphereBase.construct_marginal_orientation_histogram` Construct a marginal orientation histogram. .. py:method:: construct_marginal_orientation_histogram(binned_data: pandas.DataFrame, return_fraction: bool = True) -> pandas.Series Construct the marginal orientation histogram. Compute the marginal histogram of the orientation data, disregarding the magnitude differences. The resulting histogram has the same configuration of bins as a single shell. :param binned_data: Data frame containing the labelled vectors. :param return_fraction: Indicate whether the values returned should be the raw counts or the proportions. :returns: :class:`pandas.Series` -- The counts or proportions of vectors in each orientation bin. .. seealso:: :obj:`SphereBase.assign_histogram_bins` Label a set of vectors into different bins. :obj:`SphereBase.construct_histogram` Construct a bivariate magnitude and orientation histogram. :obj:`SphereBase.construct_marginal_magnitude_histogram` Construct a marginal magnitude histogram. .. py:method:: construct_conditional_orientation_histogram(binned_data: pandas.DataFrame) -> pandas.Series Construct the conditional orientation histogram. Construct the histogram of orientations conditioned on the magnitude. Within each shell, the returned fractions sum to 1. :param binned_data: Data frame containing the labelled vectors. :returns: :class:`pandas.Series` -- The proportion of vectors in each orientation relative to all vectors within that shell. The index used is the same as that obtained in the bivariate case. .. warning:: Unlike the bivariate and marginal histograms, this method does not allow returning raw counts. The returned values are proportions relative to each shell. .. py:method:: construct_conditional_magnitude_histogram(binned_data: pandas.DataFrame) -> pandas.Series Construct the conditional magnitude histogram. Construct the histogram of magnitudes conditioned on the orientation. Within each orientation bin, the returned fractions sum to 1. :param binned_data: Data frame containing the labelled vectors. :returns: :class:`pandas.Series` -- The proportion of vectors in each magnitude shell relative to all vectors having that orientation. The index used is the same as that obtained in the bivariate case, having the magnitude first, followed by the orientation parameters. .. warning:: Unlike the bivariate and marginal histograms, this method does not allow returning raw counts. The returned values are proportions relative to each shell. .. py:method:: create_mesh() -> pyvista.PolyData :abstractmethod: Return the mesh representation of the current sphere. .. py:method:: create_shell_mesh(histogram: pandas.Series, radius: float = 1.0, series_name: Optional[str] = 'frequency') -> pyvista.PolyData Create the mesh for a given shell. Using the provided histogram data for a specific shell, produce a sphere with the desired radius, storing the frequencies as face values. :param histogram: The counts or frequencies of orientations in each sphere face of the specific shell. :param radius: Desired shell radius. This typically corresponds to a magnitude bin upper bound. :param series_name: The name to associate with the provided scalar data. If `None`, then the value of :attr:`pandas.Series.name` is used. :returns: :class:`pyvista.PolyData` -- The constructed shell containing the desired scalars in the specified slot. .. py:method:: create_histogram_meshes(histogram_data: pandas.Series, magnitude_bins: Optional[numpy.ndarray], normalise_by_shell: bool = False) -> List[pyvista.PolyData] Create mesh shells for the supplied histogram. :param histogram_data: The binned histogram data, ordered by shell and then other implementation-specific parameters. :param magnitude_bins: The upper bounds for the magnitude bins. These are used to determine the radius of each shell. If None, then all shells will have a radius of 1. :param normalise_by_shell: Indicate whether each shell should be normalised with respect to its maximum value. :returns: :class:`list` of :class:`pyvista.PolyData` -- List containing one mesh for each shell, with the appropriate scalar values assigned to the ``frequency`` array. .. warning:: The provided histogram must have been constructed with the current sphere, or an equivalent sphere. .. rubric:: Notes The option `normalise_by_shell` produces meshes where the faces values are divided by the maximum value in their corresponding shell. The values can therefore be thought of as representing fractions of the respective maxima. .. py:method:: convert_vectors_to_cartesian_array(labelled_vectors: pandas.DataFrame, create_unit_vectors: bool = False, include_spatial_coordinates: bool = False) -> numpy.ndarray :abstractmethod: Convert a set of labelled vectors into Cartesian coordinates. Each concrete implementation of a sphere may internally represent the vectors differently. This abstract method converts from that implementation-specific formatting to Cartesian coordinates. :param labelled_vectors: The set of labelled ``n`` labelled vectors in ``d`` dimensions, in the same format as produced by :meth:`SphereBase.assign_histogram_bins`. :param create_unit_vectors: Indicate where the returned vectors should be unit vectors. Depending on the implementation, this may either remove an extraneous normalisation step later, or add an extra normalisation step now. :param include_spatial_coordinates: Indicate whether to include spatial coordinates in the new array. This option may only be called if the vectors have spatial coordinates. :returns: :class:`numpy.ndarray` -- Array of shape ``(n, d)`` containing the vector components in Cartesian coordinates. .. warning:: The option `include_spatial_coordinates` is only valid if the `labelled_vectors` include spatial coordinates. .. py:method:: get_vectors_from_single_cell(labelled_vectors: pandas.DataFrame, selected_cell: pandas.Series) -> pandas.DataFrame Extract vectors from a single selected cell. Isolate the vectors contained in a single mesh cell to filter based on either pure orientation, or a combination of magnitude and orientation. :param labelled_vectors: The set of labelled ``n`` labelled vectors in ``d`` dimensions, in the same format as produced by :meth:`SphereBase.assign_histogram_bins`. :param selected_cell: The scalar values from the selected cell, as rows in a :class:`~pandas.Series`. The index should contain at least the entries in :attr:`.SphereBase.orientation_cols`. :returns: :class:`pandas.DataFrame` -- The set of labelled vectors falling in the selected cell. This :class:`~pandas.DataFrame` has the same format as `labelled_vectors`, but fewer entries. .. py:method:: get_vectors_from_selected_cells(labelled_vectors: pandas.DataFrame, selected_cells: pandas.DataFrame) -> pandas.DataFrame Extract vectors from selected cells. Isolate the vectors contained in specified shells and cells in order to filter the vector collection by magnitude and orientation. :param labelled_vectors: The set of labelled ``n`` labelled vectors in ``d`` dimensions, in the same format as produced by :meth:`SphereBase.assign_histogram_bins`. :param selected_cells: The scalar values from the selected cells. The columns in this table should contain at least the entries in :attr:`.SphereBase.orientation_cols`. :returns: :class:`pandas.DataFrame` -- The set of labelled vectors falling in the selected cells. This :class:`~pandas.DataFrame` has the same format as `labelled_vectors`, but fewer entries. .. warning:: If the vectors were duplicated for the purpose of visualisation, that duplication is **not** preserved here. .. seealso:: :obj:`.get_vectors_from_single_cell` Extract vectors from one cell. .. py:method:: get_cell_indices(bins: pandas.DataFrame) -> pandas.Series :abstractmethod: Get cell indices for specific bins. Get the mesh cell index for specified orientation bins. :param bins: DataFrame containing the implementation-specific orientation bin information for the desired cells :returns: :class:`Series` -- Indices of the mesh cells corresponding to the desired orientation bin. .. seealso:: :obj:`.SphereBase.assign_histogram_bins` assign specific orientations and magnitudes to histogram bins.