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

.. meta::
   :keywords: OEFPVariogram, FPVariogram


.. _OEGraphSim_OEFPVariogram:

.. oe:class:: OEFPVariogram

   .. oe:api::

      class OEFPVariogram : public OEFPHistogram

   :ref:`OEFPVariogram <OEGraphSim_OEFPVariogram>` class is used to generate a
   variogram of similarity scores and related empirical measurements.
   An :ref:`OEFPVariogram <OEGraphSim_OEFPVariogram>` object is a
   :ref:`OEFPHistogram <OEGraphSim_OEFPHistogram>` with additional variogram data
   regarding user provided measurements.

   The empirical variogram has the form :

   :math:`\hat{\gamma}(h)=\frac{1}{2|N(h)|}\sum\limits_{(i,j)\in N(h)} |z_i-z_j|^2`

   Where :math:`N(h)` is the set of pairs that have a **distance** close to :math:`h`
   and :math:`z_i` is the measurement provided for the :math:`i` th molecule.

   For all of our built-in similarity measures, except for Tversky, distance is
   calculated a :math:`1-similarity`. It is not possible to calculate an empirical
   variogram using Tversky similarity.

   The **measurement** in the context of a variogram can be any user provided
   value per fingerprint e.g. bioassay data or calculated properties.

   The following methods are publicly inherited from :ref:`OEFPHistogram <OEGraphSim_OEFPHistogram>`:

   ======================================================================== ======================================================================== ========================================================================
   :oe:meth:`AddSample<OEGraphSim::OEFPHistogram::AddSample>`               :oe:meth:`GetCounts<OEGraphSim::OEFPHistogram::GetCounts>`               :oe:meth:`NumBins<OEGraphSim::OEFPHistogram::NumBins>`
   :oe:meth:`GetBinBoundaries<OEGraphSim::OEFPHistogram::GetBinBoundaries>` :oe:meth:`GetDensity<OEGraphSim::OEFPHistogram::GetDensity>`             :oe:meth:`NumSamples<OEGraphSim::OEFPHistogram::NumSamples>`
   :oe:meth:`GetBinCenters<OEGraphSim::OEFPHistogram::GetBinCenters>`       :oe:meth:`GetMax<OEGraphSim::OEFPHistogram::GetMax>`                     :oe:meth:`Std<OEGraphSim::OEFPHistogram::Std>`
   :oe:meth:`GetBinIdx<OEGraphSim::OEFPHistogram::GetBinIdx>`               :oe:meth:`GetMin<OEGraphSim::OEFPHistogram::GetMin>`
   :oe:meth:`GetBinWidth<OEGraphSim::OEFPHistogram::GetBinWidth>`           :oe:meth:`Mean<OEGraphSim::OEFPHistogram::Mean>`
   ======================================================================== ======================================================================== ========================================================================

   .. seealso::

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

   .. oe:method:: Constructors

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

         .. oe:api::

            OEFPVariogram(size_t numBins = 200, double min = 0, double max = 1)
            OEFPVariogram(const OEFPVariogram&)

      .. oe:language:: python

         .. oe:api:: python

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

      Creates an :ref:`OEFPVariogram <OEGraphSim_OEFPVariogram>` object with the
      given number of bins and similarity range.

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

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

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


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

      .. oe:api::

         OEFPVariogram & operator=(const OEFPVariogram &)

      Assignment operator.



   .. oe:method:: AddSample

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

         .. oe:api::

            size_t AddSample(const float sim, const float obs)

      .. oe:language:: python

         .. oe:api:: python

            AddSample(sim: float, obs: float) -> int

      Adds a sample representing a pair of molecules into the variogram

      **sim**
        Similarity between fingerprints i and j

      **obs**
        Measured difference between the relevant fingerprints :math:`z_i-z_j`

      .. note::

         Since we are dealing with :math:`|z_i-z_j|^2` this relationship is
         actually symmetrical.


   .. oe:method:: GetVariogram

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

         .. oe:api::

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

      .. oe:language:: python

         .. oe:api:: python

            GetVariogram() -> Iterable[float]

      Returns an iterator over the empirical variogram.
