.. include:: ../../toolkit-substitutions
.. oe:namespace:: OEGraphSim

.. meta::
   :keywords: OEFPHistogram, FPHistogram


.. _OEGraphSim_OEFPHistogram:

.. oe:class:: OEFPHistogram

   .. oe:api::

      class OEFPHistogram

   The :ref:`OEFPHistogram <OEGraphSim_OEFPHistogram>` class is used to hold a histogram
   of similarity scores.

   This class is an efficient way to obtain statistics on large
   databases which would be unfeasible to keep as full NxN similarity matrices.

   The following classes derive from this class:
    * :ref:`OEFPVariogram <OEGraphSim_OEFPVariogram>`

   .. seealso::

      * :oe:meth:`OEGraphSim::OEFastFPDatabase::GetHistogram` method

   .. oe:method:: Constructors

      .. oe:language:: c++ java csharp

         .. oe:api::

            OEFPHistogram(const size_t numBins = 200u, const double min = 0.0,
                          const double max = 1.0);
            OEFPHistogram(const OEFPHistogram&)

      .. oe:language:: python

         .. oe:api:: python

            OEFPHistogram(numBins: int = 200, min: float = 0.0,
                          max: float = 1.0) -> OEFPHistogram
            OEFPHistogram(arg2: OEFPHistogram) -> OEFPHistogram

      Creates an :ref:`OEFPHistogram <OEGraphSim_OEFPHistogram>` object with given number of
      bins and range.

      **nrbins**
        Number of bins in the histogram. (default=200)

      **min**
        Minimum bound (inclusive) of the histogram range. (default = 0.0)

      **max**
        Maximum bound (inclusive) of the histogram range. (default = 1.0)

      .. note::

         The default range of [0,1] covers all built-in similarity measures.


   .. oe:method:: operator=
      :language: c++

      .. oe:api::

         OEFPHistogram & operator=(const OEFPHistogram &)

      Assignment operator.



   .. oe:method:: AddSample

      .. oe:language:: c++ java csharp

         .. oe:api::

            size_t AddSample(const float sample)
            size_t AddSample(const double sample)

      .. oe:language:: python

         .. oe:api:: python

            AddSample(sample: float) -> int

      Adds the sample into the histogram by incrementing the count in the
      relevant bin. Returns the bin index that the sample went into.


   .. oe:method:: GetBinBoundaries

      .. oe:language:: c++ java csharp

         .. oe:api::

            OESystem::OEIterBase<double>* GetBinBoundaries() const

      .. oe:language:: python

         .. oe:api:: python

            GetBinBoundaries() -> Iterable[float]

      Returns an iterator over the boundaries for each bin.

      .. note::

         The number of elements in this iterator is equal to
         :oe:meth:`OEGraphSim::OEFPHistogram::NumBins` **+1**.


   .. oe:method:: GetBinCenters

      .. oe:language:: c++ java csharp

         .. oe:api::

            OESystem::OEIterBase<double>* GetBinCenters() const

      .. oe:language:: python

         .. oe:api:: python

            GetBinCenters() -> Iterable[float]

      Returns an iterator over the center value for each bin.

      .. note::

         The number of elements in this iterator is equal to
         :oe:meth:`OEGraphSim::OEFPHistogram::NumBins`.

      .. hint::

         It is generally reasonable to plot the results of
         :oe:meth:`OEGraphSim::OEFPHistogram::GetCounts` or
         :oe:meth:`OEGraphSim::OEFPHistogram::GetDensity` against the bin centers
         returned by this method.


   .. oe:method:: GetBinIdx

      .. oe:language:: c++ java csharp

         .. oe:api::

            size_t GetBinIdx(const float sample) const
            size_t GetBinIdx(const double sample) const

      .. oe:language:: python

         .. oe:api:: python

            GetBinIdx(sample: float) -> int

      Returns the bin index that the sample would go into without actually
      adding the sample into the bin.


   .. oe:method:: GetBinWidth

      .. oe:language:: c++ java csharp

         .. oe:api::

            double GetBinWidth() const

      .. oe:language:: python

         .. oe:api:: python

            GetBinWidth() -> float

      Returns the width of bins in the histogram.


   .. oe:method:: GetCounts

      .. oe:language:: c++ java csharp

         .. oe:api::

            OESystem::OEIterBase<unsigned int>* GetCounts() const

      .. oe:language:: python

         .. oe:api:: python

            GetCounts() -> Iterable[int]

      Returns an iterator over the bin counts.

      .. note::

         Even though counts are returned as unsigned integers, they are internally
         kept as size_t. If the counts are overflowing the unsigned int type of
         the system, it may be more appropriate to use the normalized
         :oe:meth:`OEGraphSim::OEFPHistogram::GetDensity` instead.


   .. oe:method:: GetDensity

      .. oe:language:: c++ java csharp

         .. oe:api::

            OESystem::OEIterBase<double>* GetDensity() const

      .. oe:language:: python

         .. oe:api:: python

            GetDensity() -> Iterable[float]

      Returns an iterator over the probability density for each bin.

      .. note::

         Result is equivalent to :oe:meth:`OEGraphSim::OEFPHistogram::GetCounts`
         normalized by :oe:meth:`OEGraphSim::OEFPHistogram::NumSamples`.


   .. oe:method:: GetMax

      .. oe:language:: c++ java csharp

         .. oe:api::

            double GetMax() const

      .. oe:language:: python

         .. oe:api:: python

            GetMax() -> float

      Returns upper bound (inclusive) of the histogram range.


   .. oe:method:: GetMin

      .. oe:language:: c++ java csharp

         .. oe:api::

            double GetMin() const

      .. oe:language:: python

         .. oe:api:: python

            GetMin() -> float

      Returns lower bound (inclusive) of the histogram range.


   .. oe:method:: Mean

      .. oe:language:: c++ java csharp

         .. oe:api::

            double Mean()

      .. oe:language:: python

         .. oe:api:: python

            Mean() -> float

      Approximates and returns the sample mean over the histogram.

      .. note::

         This approximation is affected by number of bins in the histogram.


   .. oe:method:: NumBins

      .. oe:language:: c++ java csharp

         .. oe:api::

            size_t NumBins() const

      .. oe:language:: python

         .. oe:api:: python

            NumBins() -> int

      Returns the number of bins in the histogram.


   .. oe:method:: NumSamples

      .. oe:language:: c++ java csharp

         .. oe:api::

            size_t NumSamples() const

      .. oe:language:: python

         .. oe:api:: python

            NumSamples() -> int

      Returns the total number of samples in the histogram.


   .. oe:method:: Std

      .. oe:language:: c++ java csharp

         .. oe:api::

            double Std()

      .. oe:language:: python

         .. oe:api:: python

            Std() -> float

      Approximates and returns the sample standard deviation over the histogram.

      .. note::

         This approximation is affected by number of bins in the histogram.
