itkHistogram.h

Go to the documentation of this file.

/*=========================================================================
 *
 *  Copyright NumFOCUS
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *         https://www.apache.org/licenses/LICENSE-2.0.txt
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *
 *=========================================================================*/
#ifndef itkHistogram_h
#define itkHistogram_h
 
#include <vector>
 
#include "itkArray.h"
#include "itkSample.h"
#include "itkDenseFrequencyContainer2.h"
#include "itkSparseFrequencyContainer2.h"
 
namespace itk::Statistics
{

 
template <typename TMeasurement = float, typename TFrequencyContainer = DenseFrequencyContainer2>
class ITK_TEMPLATE_EXPORT Histogram : public Sample<Array<TMeasurement>>
{
public:
  ITK_DISALLOW_COPY_AND_MOVE(Histogram);
 
  // This type serves as the indirect definition of MeasurementVectorType
  using ArrayType = Array<TMeasurement>;

  using Self = Histogram;
  using Superclass = Sample<ArrayType>;
  using Pointer = SmartPointer<Self>;
  using ConstPointer = SmartPointer<const Self>;

  itkOverrideGetNameOfClassMacro(Histogram);

  itkNewMacro(Self);

  using MeasurementType = TMeasurement;

  using typename Superclass::MeasurementVectorType;
  using typename Superclass::InstanceIdentifier;
  using typename Superclass::MeasurementVectorSizeType;
 
  using ValueType = MeasurementVectorType;

  using FrequencyContainerType = TFrequencyContainer;
  using FrequencyContainerPointer = typename FrequencyContainerType::Pointer;

  using AbsoluteFrequencyType = typename FrequencyContainerType::AbsoluteFrequencyType;
  using TotalAbsoluteFrequencyType = typename FrequencyContainerType::TotalAbsoluteFrequencyType;
  using RelativeFrequencyType = typename FrequencyContainerType::RelativeFrequencyType;
  using TotalRelativeFrequencyType = typename FrequencyContainerType::TotalRelativeFrequencyType;

  using IndexType = Array<itk::IndexValueType>;
  using IndexValueType = typename IndexType::ValueType;

  using SizeType = Array<itk::SizeValueType>;
  using SizeValueType = typename SizeType::ValueType;

  using BinMinVectorType = std::vector<MeasurementType>;
  using BinMaxVectorType = std::vector<MeasurementType>;
  using BinMinContainerType = std::vector<BinMinVectorType>;
  using BinMaxContainerType = std::vector<BinMaxVectorType>;

  void
  Initialize(const SizeType & size);

  void
  Initialize(const SizeType & size, MeasurementVectorType & lowerBound, MeasurementVectorType & upperBound);

  void
  SetToZero();

  bool
  GetIndex(const MeasurementVectorType & measurement, IndexType & index) const;

  const IndexType &
  GetIndex(InstanceIdentifier id) const;

  itkGetConstMacro(ClipBinsAtEnds, bool);
  itkSetMacro(ClipBinsAtEnds, bool);
  itkBooleanMacro(ClipBinsAtEnds);
  bool
  IsIndexOutOfBounds(const IndexType & index) const;

  InstanceIdentifier
  GetInstanceIdentifier(const IndexType & index) const;

  InstanceIdentifier
  Size() const override;

  const SizeType &
  GetSize() const;

  SizeValueType
  GetSize(unsigned int dimension) const;

  const MeasurementType &
  GetBinMin(unsigned int dimension, InstanceIdentifier nbin) const;

  const MeasurementType &
  GetBinMax(unsigned int dimension, InstanceIdentifier nbin) const;

  void
  SetBinMin(unsigned int dimension, InstanceIdentifier nbin, MeasurementType min);

  void
  SetBinMax(unsigned int dimension, InstanceIdentifier nbin, MeasurementType max);

  const MeasurementType &
  GetBinMinFromValue(unsigned int dimension, float value) const;

  const MeasurementType &
  GetBinMaxFromValue(unsigned int dimension, float value) const;

  const BinMinVectorType &
  GetDimensionMins(unsigned int dimension) const;

  const BinMaxVectorType &
  GetDimensionMaxs(unsigned int dimension) const;

  const BinMinContainerType &
  GetMins() const;

  const BinMaxContainerType &
  GetMaxs() const;

  const MeasurementVectorType &
  GetHistogramMinFromIndex(const IndexType & index) const;

  const MeasurementVectorType &
  GetHistogramMaxFromIndex(const IndexType & index) const;

  AbsoluteFrequencyType
  GetFrequency(InstanceIdentifier id) const override;

  AbsoluteFrequencyType
  GetFrequency(const IndexType & index) const;

  void
  SetFrequency(AbsoluteFrequencyType value);

  bool
  SetFrequency(InstanceIdentifier id, AbsoluteFrequencyType value);

  bool
  SetFrequencyOfIndex(const IndexType & index, AbsoluteFrequencyType value);

  bool
  SetFrequencyOfMeasurement(const MeasurementVectorType & measurement, AbsoluteFrequencyType value);

  bool
  IncreaseFrequency(InstanceIdentifier id, AbsoluteFrequencyType value);

  bool
  IncreaseFrequencyOfIndex(const IndexType & index, AbsoluteFrequencyType value);

  bool
  IncreaseFrequencyOfMeasurement(const MeasurementVectorType & measurement, AbsoluteFrequencyType value);

  const MeasurementVectorType &
  GetMeasurementVector(InstanceIdentifier id) const override;

  const MeasurementVectorType &
  GetMeasurementVector(const IndexType & index) const;

  MeasurementType
  GetMeasurement(InstanceIdentifier n, unsigned int dimension) const;

  TotalAbsoluteFrequencyType
  GetTotalFrequency() const override;

  AbsoluteFrequencyType
  GetFrequency(InstanceIdentifier n, unsigned int dimension) const;

  double
  Quantile(unsigned int dimension, double p) const;

  double
  Mean(unsigned int dimension) const;

  void
  Graft(const DataObject *) override;
 
protected:
  void
  PrintSelf(std::ostream & os, Indent indent) const override;
 
public:
  class ConstIterator
  {
  public:
    friend class Histogram;
 
    ConstIterator() = delete;
    ConstIterator(const Self * histogram)
      : m_Id(0)
      , m_Histogram(histogram)
    {}
 
    ConstIterator(const ConstIterator & it)
      : m_Id(it.m_Id)
      , m_Histogram(it.m_Histogram)
    {}
 
    ConstIterator &
    operator=(const ConstIterator & it) = default;
 
    [[nodiscard]] AbsoluteFrequencyType
    GetFrequency() const
    {
      return m_Histogram->GetFrequency(m_Id);
    }
 
    [[nodiscard]] InstanceIdentifier
    GetInstanceIdentifier() const
    {
      return m_Id;
    }
 
    [[nodiscard]] const MeasurementVectorType &
    GetMeasurementVector() const
    {
      return m_Histogram->GetMeasurementVector(m_Id);
    }
 
    [[nodiscard]] const IndexType &
    GetIndex() const
    {
      return m_Histogram->GetIndex(m_Id);
    }
 
    ConstIterator &
    operator++()
    {
      ++m_Id;
      return *this;
    }
 
    bool
    operator==(const ConstIterator & it) const
    {
      return (m_Id == it.m_Id);
    }
 
    ITK_UNEQUAL_OPERATOR_MEMBER_FUNCTION(ConstIterator);
 
  protected:
    ConstIterator(InstanceIdentifier id, const Self * histogram)
      : m_Id(id)
      , m_Histogram(histogram)
    {}
 
    // ConstIterator pointing DenseFrequencyContainer
    InstanceIdentifier m_Id;
 
    // Pointer of DenseFrequencyContainer
    const Self * m_Histogram;
  }; // end of iterator class

  class Iterator : public ConstIterator
  {
  public:
    Iterator() = delete;
    Iterator(const Self * histogram) = delete;
    Iterator(InstanceIdentifier id, const Self * histogram) = delete;
    Iterator(const ConstIterator & it) = delete;
    ConstIterator &
    operator=(const ConstIterator & it) = delete;
 
    Iterator(Self * histogram)
      : ConstIterator(histogram)
    {}
 
    Iterator(InstanceIdentifier id, Self * histogram)
      : ConstIterator(id, histogram)
    {}
 
    Iterator(const Iterator & it)
      : ConstIterator(it)
    {}
 
    Iterator &
    operator=(const Iterator & it)
    {
      this->ConstIterator::operator=(it);
      return *this;
    }
 
    bool
    SetFrequency(const AbsoluteFrequencyType value)
    {
      auto * histogram = const_cast<Self *>(this->m_Histogram);
 
      return histogram->SetFrequency(this->m_Id, value);
    }
  }; // end of iterator class
 
  Iterator
  Begin()
  {
    const Iterator iter(0, this);
 
    return iter;
  }
 
  Iterator
  End()
  {
    return Iterator(m_OffsetTable[this->GetMeasurementVectorSize()], this);
  }
 
  ConstIterator
  Begin() const
  {
    const ConstIterator iter(0, this);
 
    return iter;
  }
 
  ConstIterator
  End() const
  {
    return ConstIterator(m_OffsetTable[this->GetMeasurementVectorSize()], this);
  }
 
protected:
  Histogram();
  ~Histogram() override = default;
 
  // The number of bins for each dimension
  SizeType m_Size{};
 
private:
  using OffsetTableType = std::vector<InstanceIdentifier>;
  OffsetTableType           m_OffsetTable{};
  FrequencyContainerPointer m_FrequencyContainer{};
  unsigned int              m_NumberOfInstances{ 0 };
 
  // This method is provided here just to avoid a "hidden" warning
  // related to the virtual method available in DataObject.
  void
  Initialize() override
  {}
 
  // lower bound of each bin
  std::vector<std::vector<MeasurementType>> m_Min{};
 
  // upper bound of each bin
  std::vector<std::vector<MeasurementType>> m_Max{};
 
  mutable MeasurementVectorType m_TempMeasurementVector{};
  mutable IndexType             m_TempIndex{};
 
  bool m_ClipBinsAtEnds{ true };
};
} // namespace itk::Statistics
 
#ifndef ITK_MANUAL_INSTANTIATION
#  include "itkHistogram.hxx"
#endif
 
#endif