vectorose.polar_data#

Polar data histogram calculations.

Compute 1D histograms for phi and theta angles separately.

Warning

Currently, this polar analysis is purely based on orientation and cannot be done in conjunction with studies of magnitude.

Classes#

PolarDiscretiser

Construct polar histograms based on vectorial and axial data.

Module Contents#

class vectorose.polar_data.PolarDiscretiser(number_of_phi_bins: int, number_of_theta_bins: int, is_axial: bool)[source]#

Construct polar histograms based on vectorial and axial data.

_is_axial: bool#

Indicate whether the data are axial.

This attribute is used to determine the range of the phi values.

_phi_bins: pandas.DataFrame#: Definition of the phi bins.

_theta_bins: pandas.DataFrame#: Definition of the theta bins.

_phi_increment: float#: Angular width of the phi bins.

_theta_increment: float#: Angular width of the theta bins.

binning_precision: int = 10#: Rounding precision when assigning bin values.

property number_of_phi_bins: int#: Number of bins to capture the phi angles.

property number_of_theta_bins: int#: Number of bins to capture the theta angles.

property phi_increment: float#: Angular width of the phi bins.

property theta_increment: float#: Angular width of the theta bins.

property is_axial: bool#: Indicate whether the discretiser is considering axial data.

static _generate_theta_bins(number_of_theta_bins: int) → tuple[pandas.DataFrame, numpy.floating][source]#

Generate the theta bins.

The theta bins fill the interval from 0 degrees (included) to 360 degrees (excluded). The last bin wraps around to zero degrees.

Parameters:

number_of_theta_bins – Number of bins to generate in the theta direction.

Returns:

theta_bins (pandas.DataFrame) – Bin start and end angles, containing number_of_theta_bins rows.
theta_step (np.floating) – Angular width of each bin.

static _generate_phi_bins(number_of_phi_bins: int, is_axial: bool) → tuple[pandas.DataFrame, numpy.floating][source]#

Generate the phi bins.

The phi bins fill the interval from 0 degrees (included) to either 90 degrees in the case of axial data, or 180 degrees in the case of vectorial data. This upper bound is included, the last bin starts at this final value to account for vectors at this value.

Parameters:

number_of_phi_bins – Number of bins to generate in the phi direction.
is_axial – Indicate whether to consider data as axial. In this case, only the phi values corresponding to the upper hemisphere are considered.

Returns:

theta_bins (pandas.DataFrame) – Bin start and end angles, containing number_of_theta_bins rows.
theta_step (np.floating) – Angular width of each bin.

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

Assign histogram orientation bins.

Label each provided vector with a bin index in phi and theta.

Parameters:: vectors – Array of shape (n, 3) or (n, 6) containing the Cartesian components of the vectors from which to construct the histogram. If 6 columns are present, the first 3 are assumed to be the spatial locations.
Returns:: pandas.DataFrame – All the vectors, including additional columns for the phi and theta bins.

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.

_construct_histogram(labelled_vectors: pandas.DataFrame, angle_name: vectorose.util.AngleName) → pandas.DataFrame[source]#

Construct polar histogram for one of the two angles.

Parameters:

labelled_vectors – Vectors with phi and theta bins assigned.
angle_name – Indicate which angle should be considered

Returns:

pandas.DataFrame – Histogram containing each bin start, end, count and frequency values.

construct_phi_histogram(labelled_vectors: pandas.DataFrame) → pandas.DataFrame[source]#

Construct the phi polar histogram.

Parameters:: labelled_vectors – Vectors with phi and theta bins assigned.
Returns:: pandas.DataFrame – Histogram containing each bin start, end, count and frequency values for each phi bin.

construct_theta_histogram(labelled_vectors: pandas.DataFrame) → pandas.DataFrame[source]#

Construct the theta polar histogram.

Parameters:: labelled_vectors – Vectors with theta and theta bins assigned.
Returns:: pandas.DataFrame – Histogram containing each bin start, end, count and frequency values for each theta bin.