hats.pixel_math.sparse_histogram
================================

.. py:module:: hats.pixel_math.sparse_histogram

.. autoapi-nested-parse::

   Sparse 1-D histogram of healpix pixel counts.

   ..
       !! processed by numpydoc !!


Classes
-------

.. autoapisummary::

   hats.pixel_math.sparse_histogram.SparseHistogram
   hats.pixel_math.sparse_histogram.HistogramAggregator


Functions
---------

.. autoapisummary::

   hats.pixel_math.sparse_histogram.supplemental_count_histogram


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

.. py:class:: SparseHistogram(indexes, counts, order)

   
   Wrapper around a naive sparse array, that is just non-zero indexes and counts.

   e.g. for a dense 1-d numpy histogram of order 0, you might see::

       [0, 4, 0, 0, 0, 0, 0, 0, 9, 0, 0]

   There are only elements at [1, 8], and they have respective values [4, 9]. You
   would create the sparse histogram like::

       SparseHistogram([1, 8], [4, 9], 0)















   ..
       !! processed by numpydoc !!

   .. py:attribute:: indexes


   .. py:attribute:: counts


   .. py:attribute:: order


   .. py:method:: to_array()

      
      Convert the sparse array to a dense numpy array.





      :Returns:

          np.ndarray
              dense 1-d numpy array.











      ..
          !! processed by numpydoc !!


   .. py:method:: to_file(file_name)

      
      Persist the sparse array to disk.

      NB: this saves as a sparse array, and so will likely have lower space requirements
      than saving the corresponding dense 1-d numpy array.

      :Parameters:

          **file_name** : path-like
              intended file to save to














      ..
          !! processed by numpydoc !!


   .. py:method:: to_dense_file(file_name)

      
      Persist the DENSE array to disk as a numpy array.


      :Parameters:

          **file_name** : path-like
              intended file to save to














      ..
          !! processed by numpydoc !!


   .. py:method:: from_file(file_name)
      :classmethod:


      
      Read sparse histogram from a file.


      :Parameters:

          **file_name** : path-like
              intended file to save read from



      :Returns:

          SparseHistogram
              new sparse histogram











      ..
          !! processed by numpydoc !!


   .. py:method:: __eq__(value)


   .. py:method:: __str__()


.. py:class:: HistogramAggregator(order)

   
   Utility for aggregating sparse histograms.
















   ..
       !! processed by numpydoc !!

   .. py:attribute:: order


   .. py:attribute:: full_histogram


   .. py:method:: add(other)

      
      Add in another sparse histogram, updating this wrapper's array.


      :Parameters:

          **other** : SparseHistogram
              the wrapper containing the addend














      ..
          !! processed by numpydoc !!


   .. py:method:: to_sparse()

      
      Return a SparseHistogram, based on non-zero values in this aggregation.
















      ..
          !! processed by numpydoc !!


.. py:function:: supplemental_count_histogram(mapped_pixels, supplemental_count, highest_order)

   
   Specialized method for getting a histogram of some supplemental count,
   collating according to the pixels in the first argument.

   Typically used during import, when you wish to partition according to some supplemental
   data, such as in-memory size, or length of a nested column.

   :Parameters:

       **mapped_pixels** : array_like of int
           1-D array of healpix pixel IDs. Values will be
           aggregated by pixel to produce the row-count histogram.

       **supplemental_count** : None or array_like of int
           Optional 1-D array of supplemental counts (for example per-row memory
           sizes or nested-column lengths). If ``None``, no supplemental histogram
           will be produced and the returned second element will be ``None``.

       **highest_order** : int
           Healpix order used for the histograms.



   :Returns:

       tuple
           ``(row_count_histo, supplemental_count_histo)`` where both elements are
           :class:`SparseHistogram`. ``row_count_histo`` contains counts of rows
           per pixel. ``supplemental_count_histo`` contains the sum of the
           supplemental counts per pixel, or ``None`` if ``supplemental_count`` was
           ``None``.











   ..
       !! processed by numpydoc !!