vectorose.polar_data
====================

.. py:module:: vectorose.polar_data

.. autoapi-nested-parse::

   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
-------

.. autoapisummary::

   vectorose.polar_data.PolarDiscretiser


Module Contents
---------------

.. py:class:: PolarDiscretiser(number_of_phi_bins: int, number_of_theta_bins: int, is_axial: bool)

   Construct polar histograms based on vectorial and axial data.


   .. py:attribute:: _is_axial
      :type:  bool

      Indicate whether the data are axial.

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


   .. py:attribute:: _phi_bins
      :type:  pandas.DataFrame

      Definition of the phi bins.


   .. py:attribute:: _theta_bins
      :type:  pandas.DataFrame

      Definition of the theta bins.


   .. py:attribute:: _phi_increment
      :type:  float

      Angular width of the phi bins.


   .. py:attribute:: _theta_increment
      :type:  float

      Angular width of the theta bins.


   .. py:attribute:: binning_precision
      :type:  int
      :value: 10


      Rounding precision when assigning bin values.


   .. py:property:: number_of_phi_bins
      :type: int


      Number of bins to capture the phi angles.


   .. py:property:: number_of_theta_bins
      :type: int


      Number of bins to capture the theta angles.


   .. py:property:: phi_increment
      :type: float


      Angular width of the phi bins.


   .. py:property:: theta_increment
      :type: float


      Angular width of the theta bins.


   .. py:property:: is_axial
      :type: bool


      Indicate whether the discretiser is considering axial data.


   .. py:method:: _generate_theta_bins(number_of_theta_bins: int) -> tuple[pandas.DataFrame, numpy.floating]
      :staticmethod:


      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.

      :param number_of_theta_bins: Number of bins to generate in the theta direction.

      :returns: * **theta_bins** (:class:`pandas.DataFrame`) -- Bin start and end angles, containing `number_of_theta_bins`
                  rows.
                * **theta_step** (:class:`np.floating`) -- Angular width of each bin.



   .. py:method:: _generate_phi_bins(number_of_phi_bins: int, is_axial: bool) -> tuple[pandas.DataFrame, numpy.floating]
      :staticmethod:


      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.

      :param number_of_phi_bins: Number of bins to generate in the phi direction.
      :param 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** (:class:`pandas.DataFrame`) -- Bin start and end angles, containing `number_of_theta_bins`
                  rows.
                * **theta_step** (:class:`np.floating`) -- Angular width of each bin.



   .. py:method:: assign_histogram_bins(vectors: numpy.ndarray) -> pandas.DataFrame

      Assign histogram orientation bins.

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

      :param 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: :class:`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.



   .. py:method:: _construct_histogram(labelled_vectors: pandas.DataFrame, angle_name: vectorose.util.AngleName) -> pandas.DataFrame

      Construct polar histogram for one of the two angles.

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

      :returns: :class:`pandas.DataFrame` -- Histogram containing each bin start, end, count and frequency
                values.



   .. py:method:: construct_phi_histogram(labelled_vectors: pandas.DataFrame) -> pandas.DataFrame

      Construct the phi polar histogram.

      :param labelled_vectors: Vectors with phi and theta bins assigned.

      :returns: :class:`pandas.DataFrame` -- Histogram containing each bin start, end, count and frequency
                values for each phi bin.



   .. py:method:: construct_theta_histogram(labelled_vectors: pandas.DataFrame) -> pandas.DataFrame

      Construct the theta polar histogram.

      :param labelled_vectors: Vectors with theta and theta bins assigned.

      :returns: :class:`pandas.DataFrame` -- Histogram containing each bin start, end, count and frequency
                values for each theta bin.