vectorose.sphere_base#

Basics for spherical histogram construction.

This module contains basic tools for different representations of optionally-nested spherical histograms.

Classes#

SphereBase

Base class for a spherical histogram.

Module Contents#

class vectorose.sphere_base.SphereBase(number_of_shells: int = 1, magnitude_range: Tuple[float, float] | None = None)[source]#

Bases: abc.ABC

Base class for a spherical histogram.

number_of_shells: int#: Number of shells to consider for bivariate vector histograms.

magnitude_range: Tuple[float, float] | None#

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.

magnitude_precision: int | None = 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.

property hist_group_cols: List[str]#: Names of the histogram columns to use for sorting.

property magnitude_shell_cols: List[str]#: Name of the histogram columns to use for magnitude.

property orientation_cols: List[str]#

Abstractmethod:

Name of the histogram columns to use for orientation.

assign_histogram_bins(vectors: numpy.ndarray) → Tuple[pandas.DataFrame, numpy.ndarray][source]#

Assign vectors to the appropriate histogram bin.

Parameters:

vectors – Array of shape (n, 3) containing the Cartesian components of the vectors from which to construct the histogram.

Returns:

pandas.DataFrame – All the vectors, including additional columns for the shell and the implementation-specific orientation bin.
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.

_initial_vector_data_preparation(vectors: pandas.DataFrame) → pandas.DataFrame[source]#

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.

Parameters:: 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:: 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 _initial_vector_component_preparation(), which is called by this function.

_initial_vector_component_preparation(vectors: pandas.DataFrame) → pandas.DataFrame[source]#

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 _initial_vector_data_preparation() which calls this function.

_compute_magnitude_bins(vectors: pandas.DataFrame) → Tuple[pandas.Series, numpy.ndarray][source]#

Perform binning based on magnitude.

Construct the magnitude histogram for the provided vectors.

Parameters:

vectors – The vectors from which the magnitude histogram is to be constructed.

Returns:

pandas.Series – The magnitude shell number for each vector, in a pandas.Series called shell.
numpy.ndarray – Array containing the histogram bin boundaries used to construct the histogram. The length of this array corresponds is one more than SphereBase.number_of_shells.

abstract _compute_orientation_binning(vectors: pandas.DataFrame) → pandas.core.generic.NDFrame[source]#

Bin the provided vectors based on orientation.

Parameters:: vectors – The vectors to place in orientation bins.
Returns:: pandas.Series or pandas.DataFrame – The orientation bin(s) corresponding to each vector. The number of columns will depend on the specific sphere representation used.

_construct_histogram_index() → pandas.MultiIndex[source]#: Construct the index for the histogram.

_construct_magnitude_index() → pandas.Index[source]#: Construct the index for the magnitude bins.

abstract _construct_orientation_index() → pandas.Index[source]#: Construct the index for the orientation bins.

construct_histogram(binned_data: pandas.DataFrame, return_fraction: bool = True) → pandas.Series[source]#

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.

Parameters:

binned_data – All vectors, with their respective bins, depending on the current sphere design.
return_fraction – Indicate whether the values returned should be the raw counts or the proportions.

Returns:

pandas.Series – The counts or proportions of vectors in each case, ordered by the columns specified in SphereBase.hist_group_cols.

construct_marginal_magnitude_histogram(binned_data: pandas.DataFrame, return_fraction: bool = True) → pandas.Series[source]#

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.

Parameters:

binned_data – Data frame containing the labelled vectors.
return_fraction – Indicate whether the values returned should be the raw counts or the proportions.

Returns:

pandas.Series – The counts or proportions of vectors in each magnitude shell.

See also

SphereBase.assign_histogram_bins: Label a set of vectors into different bins.
SphereBase.construct_histogram: Construct a bivariate magnitude and orientation histogram.
SphereBase.construct_marginal_orientation_histogram: Construct a marginal orientation histogram.

construct_marginal_orientation_histogram(binned_data: pandas.DataFrame, return_fraction: bool = True) → pandas.Series[source]#

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.

Parameters:

binned_data – Data frame containing the labelled vectors.
return_fraction – Indicate whether the values returned should be the raw counts or the proportions.

Returns:

pandas.Series – The counts or proportions of vectors in each orientation bin.

See also

SphereBase.assign_histogram_bins: Label a set of vectors into different bins.
SphereBase.construct_histogram: Construct a bivariate magnitude and orientation histogram.
SphereBase.construct_marginal_magnitude_histogram: Construct a marginal magnitude histogram.

construct_conditional_orientation_histogram(binned_data: pandas.DataFrame) → pandas.Series[source]#

Construct the conditional orientation histogram.

Construct the histogram of orientations conditioned on the magnitude. Within each shell, the returned fractions sum to 1.

Parameters:: binned_data – Data frame containing the labelled vectors.
Returns:: 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.

construct_conditional_magnitude_histogram(binned_data: pandas.DataFrame) → pandas.Series[source]#

Construct the conditional magnitude histogram.

Construct the histogram of magnitudes conditioned on the orientation. Within each orientation bin, the returned fractions sum to 1.

Parameters:: binned_data – Data frame containing the labelled vectors.
Returns:: 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.

abstract create_mesh() → pyvista.PolyData[source]#: Return the mesh representation of the current sphere.

create_shell_mesh(histogram: pandas.Series, radius: float = 1.0, series_name: str | None = 'frequency') → pyvista.PolyData[source]#

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.

Parameters:

histogram – The counts or frequencies of orientations in each sphere face of the specific shell.
radius – Desired shell radius. This typically corresponds to a magnitude bin upper bound.
series_name – The name to associate with the provided scalar data. If None, then the value of pandas.Series.name is used.

Returns:

pyvista.PolyData – The constructed shell containing the desired scalars in the specified slot.

create_histogram_meshes(histogram_data: pandas.Series, magnitude_bins: numpy.ndarray | None, normalise_by_shell: bool = False) → List[pyvista.PolyData][source]#

Create mesh shells for the supplied histogram.

Parameters:

histogram_data – The binned histogram data, ordered by shell and then other implementation-specific parameters.
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.
normalise_by_shell – Indicate whether each shell should be normalised with respect to its maximum value.

Returns:

list of 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.

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.

abstract convert_vectors_to_cartesian_array(labelled_vectors: pandas.DataFrame, create_unit_vectors: bool = False, include_spatial_coordinates: bool = False) → numpy.ndarray[source]#

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.

Parameters:

labelled_vectors – The set of labelled n labelled vectors in d dimensions, in the same format as produced by SphereBase.assign_histogram_bins().
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.
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:

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.

get_vectors_from_single_cell(labelled_vectors: pandas.DataFrame, selected_cell: pandas.Series) → pandas.DataFrame[source]#

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.

Parameters:

labelled_vectors – The set of labelled n labelled vectors in d dimensions, in the same format as produced by SphereBase.assign_histogram_bins().
selected_cell – The scalar values from the selected cell, as rows in a Series. The index should contain at least the entries in SphereBase.orientation_cols.

Returns:

pandas.DataFrame – The set of labelled vectors falling in the selected cell. This DataFrame has the same format as labelled_vectors, but fewer entries.

get_vectors_from_selected_cells(labelled_vectors: pandas.DataFrame, selected_cells: pandas.DataFrame) → pandas.DataFrame[source]#

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.

Parameters:

labelled_vectors – The set of labelled n labelled vectors in d dimensions, in the same format as produced by SphereBase.assign_histogram_bins().
selected_cells – The scalar values from the selected cells. The columns in this table should contain at least the entries in SphereBase.orientation_cols.

Returns:

pandas.DataFrame – The set of labelled vectors falling in the selected cells. This 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.

See also

get_vectors_from_single_cell: Extract vectors from one cell.

abstract get_cell_indices(bins: pandas.DataFrame) → pandas.Series[source]#

Get cell indices for specific bins.

Get the mesh cell index for specified orientation bins.

Parameters:: bins – DataFrame containing the implementation-specific orientation bin information for the desired cells
Returns:: Series – Indices of the mesh cells corresponding to the desired orientation bin.

See also

SphereBase.assign_histogram_bins: assign specific orientations and magnitudes to histogram bins.