YODA::Axis< T, isCAxis< T > > Class Template Reference

Continuous axis with floating-point-type edges. More...

#include <BinnedAxis.h>

Public Types
using	EdgeT = T
using	ContainerT = std::vector< T >
using	const_iterator = typename ContainerT::const_iterator
using	CAxisT = isCAxis< T >

Public Member Functions
	Axis ()
	Nullary constructor for unique pointers etc.
	Axis (const Axis< T, CAxisT > &other)
	Axis (Axis< T, CAxisT > &&other)
	Axis (std::vector< EdgeT > edges)
	Constructs continuous Axis from a vector.
	Axis (std::initializer_list< T > &&edges)
	Constructs continuous Axis from an initializer list.
	Axis (std::vector< std::pair< EdgeT, EdgeT > > binsEdges)
	Axis (size_t nBins, EdgeT lower, EdgeT upper)
Axis &	operator= (const Axis &other)
Axis &	operator= (Axis &&other)
size_t	index (const EdgeT &x) const
	Bin searcher.
size_t	size () const noexcept
	Returns amount of bins in axis.
size_t	numBins (const bool includeOverflows=false) const noexcept
	Returns amount of bins in axis.
EdgeT	edge (const size_t i) const
	Returns edge corresponding to index.
std::vector< EdgeT >	edges () const noexcept
	Returns a copy of all axis edges. Includes -inf and +inf edges.
const_iterator	begin () const
	Returns the const begin iterator for the edges container.
const_iterator	end () const
	Returns the const end iterator for the edges container.
bool	hasSameEdges (const Axis< EdgeT, CAxisT > &other) const noexcept
	Check if two BinnedAxis objects have the same edges.
std::vector< T >	sharedEdges (const Axis< EdgeT, CAxisT > &other) const noexcept
	Find edges which are shared between BinnedAxis objects, within numeric tolerance.
bool	isSubsetEdges (const Axis< EdgeT, CAxisT > &other) const noexcept
	Check if other axis edges are a subset of edges of this one.
std::vector< size_t >	maskedBins () const noexcept
	Returns the masked indices.
I/O
std::string	type () const noexcept
	Returns a string representation of EdgeT.
Transformations
void	mergeBins (std::pair< size_t, size_t >)
	Merges bins, e.g. removes edges in between.
Space characteristics
std::vector< T >	widths (const bool includeOverflows=false) const noexcept
EdgeT	width (size_t binNum) const noexcept
	Width of bin side on this axis.
EdgeT	max (size_t binNum) const noexcept
	Max of bin side on this axis.
EdgeT	min (size_t binNum) const noexcept
	Min of bin side on this axis.
EdgeT	mid (size_t binNum) const noexcept
	Mid of bin side on this axis.

Detailed Description

template<typename T>
class YODA::Axis< T, isCAxis< T > >

Continuous axis with floating-point-type edges.

Definition at line 326 of file BinnedAxis.h.

Member Typedef Documentation

CAxisT

template<typename T >

using YODA::Axis< T, isCAxis< T > >::CAxisT = isCAxis<T>

Definition at line 331 of file BinnedAxis.h.

const_iterator

template<typename T >

using YODA::Axis< T, isCAxis< T > >::const_iterator = typename ContainerT::const_iterator

Definition at line 330 of file BinnedAxis.h.

ContainerT

template<typename T >

using YODA::Axis< T, isCAxis< T > >::ContainerT = std::vector<T>

Definition at line 329 of file BinnedAxis.h.

EdgeT

template<typename T >

using YODA::Axis< T, isCAxis< T > >::EdgeT = T

Definition at line 328 of file BinnedAxis.h.

Constructor & Destructor Documentation

Axis() [1/7]

template<typename T >

YODA::Axis< T, isCAxis< T > >::Axis ( )

inline

Nullary constructor for unique pointers etc.

Definition at line 334 of file BinnedAxis.h.

           {
      _updateEdges({});
      _setEstimator();
    }

Axis() [2/7]

template<typename T >

YODA::Axis< T, isCAxis< T > >::Axis

(

const Axis< T, CAxisT > &

other

)

Concept check shall appear inside body of type's member function or outside of type, since otherwise type is considered incomplete.

Note

Concept check appears once to check whether the type Axis satisfies the concept.

Definition at line 560 of file BinnedAxis.h.

                                                        {
    static_assert(MetaUtils::checkConcept<Axis<EdgeT>, YODAConcepts::AxisImpl>(),
      "Axis<T> should implement Axis concept.");
 
    _est = other._est;
    _edges = other._edges;
    _maskedBins = other._maskedBins;
  }

Axis() [3/7]

template<typename T >

YODA::Axis< T, isCAxis< T > >::Axis ( Axis< T, CAxisT > &&  other )

inline

Definition at line 341 of file BinnedAxis.h.

      : _est(other._est),
        _maskedBins(std::move(other._maskedBins)),
        _edges(std::move(other._edges)) {}

Axis() [4/7]

template<typename T >

YODA::Axis< T, isCAxis< T > >::Axis

(

std::vector< EdgeT >

edges

)

Constructs continuous Axis from a vector.

Note

Edges are sorted on construction stage.

Definition at line 642 of file BinnedAxis.h.

                                                  {
    std::sort(edges.begin(), edges.end());
    edges.erase( std::unique(edges.begin(), edges.end()), edges.end() );
 
    _updateEdges(std::move(edges));
 
    _setEstimator();
  }

Axis() [5/7]

template<typename T >

YODA::Axis< T, isCAxis< T > >::Axis

(

std::initializer_list< T > &&

edges

)

Constructs continuous Axis from an initializer list.

Note

Edges are sorted on construction stage

Definition at line 652 of file BinnedAxis.h.

                                                             {
    std::vector<T> edges{edgeList};
    std::sort(edges.begin(), edges.end());
    edges.erase( std::unique(edges.begin(), edges.end()), edges.end() );
 
    _updateEdges(std::move(edges));
 
    _setEstimator();
  }

Axis() [6/7]

template<typename T >

YODA::Axis< T, isCAxis< T > >::Axis

(

std::vector< std::pair< EdgeT, EdgeT > >

binsEdges

)

Note

Vector shouldn't contain any intersecting pairs, e.g. pair1.second > pair2.first. Order of pairs does not matter. BinsEdges is sorted on construction stage.

Merge if equal

Note

If there is a gap, mark bin as masked.

In case there have been merges. +1 to account for +inf.

Definition at line 594 of file BinnedAxis.h.

                                                                      {
    if (binsEdges.empty()) throw BinningError("Expected at least one discrete edge");
 
    std::sort(binsEdges.begin(), binsEdges.end(), [](auto &left, auto &right) {
      return left.first < right.first;
    });
 
    _edges.resize(binsEdges.size()*2+2);
 
    _edges[0] = -std::numeric_limits<double>::infinity();
 
 
    /*             Edges pairs from binsEdges vector
    */
 
    size_t i = 1;
    for (const auto& pair : binsEdges) {
      if (!fuzzyGtrEquals(pair.first, _edges[i-1])) throw BinningError("Bin edges shouldn't intersect");
      if (i == 1 && std::isinf(pair.first) && pair.first < 0) {
        _edges[i++] = pair.second;
        continue;
      }
      if (fuzzyEquals(pair.first, _edges[i-1])) {
        _edges[i++] = pair.second; 
        continue;
      }
      if (i != 1 && pair.first > _edges[i-1]) {
        _maskedBins.emplace_back(i-1);
      }
      _edges[i++] = pair.first;
      _edges[i++] = pair.second;
    }
 
    _edges[i] = std::numeric_limits<double>::infinity();
 
    _edges.resize(i+1); 
 
    _setEstimator();
  }

References YODA::fuzzyEquals(), and YODA::fuzzyGtrEquals().

Axis() [7/7]

template<typename T >

YODA::Axis< T, isCAxis< T > >::Axis	(	size_t	nBins,
		EdgeT	lower,
		EdgeT	upper
	)

Definition at line 574 of file BinnedAxis.h.

                                                                                    {
    if(upper <= lower)
      throw(std::logic_error("Upper bound should be larger than lower."));
    _edges.resize(nBins+1+2);
    double step = (upper - lower) / nBins;
 
    _edges[0] = -std::numeric_limits<double>::infinity();
 
    _edges[1] = lower;
 
    for(size_t i = 2; i < _edges.size()-1; i++) {
      _edges[i] = _edges[i-1] + step;
    }
 
    _edges[_edges.size()-1] = std::numeric_limits<double>::infinity();
 
    _setEstimator();
  }

Member Function Documentation

begin()

template<typename T >

const_iterator YODA::Axis< T, isCAxis< T > >::begin ( ) const

inline

Returns the const begin iterator for the edges container.

Definition at line 425 of file BinnedAxis.h.

{ return _edges.cbegin(); }

edge()

template<typename T >

Axis< T, isCAxis< T > >::EdgeT YODA::Axis< T, isCAxis< T > >::edge

(

const size_t

i

)

const

Returns edge corresponding to index.

Definition at line 697 of file BinnedAxis.h.

                                                                                  {
    return this->_edges.at(i);
  }

edges()

template<typename T >

std::vector< typename Axis< T, isCAxis< T > >::EdgeT > YODA::Axis< T, isCAxis< T > >::edges ( ) const

noexcept

Returns a copy of all axis edges. Includes -inf and +inf edges.

Definition at line 702 of file BinnedAxis.h.

                                                                                         {
    return this->_edges;
  }

end()

template<typename T >

const_iterator YODA::Axis< T, isCAxis< T > >::end ( ) const

inline

Returns the const end iterator for the edges container.

Definition at line 428 of file BinnedAxis.h.

{ return _edges.cend(); }

hasSameEdges()

template<typename T >

bool YODA::Axis< T, isCAxis< T > >::hasSameEdges ( const Axis< EdgeT, CAxisT > &  other ) const

noexcept

Check if two BinnedAxis objects have the same edges.

Todo:

Be careful about using fuzzyEquals... should be an exact comparison?

Definition at line 707 of file BinnedAxis.h.

                                                                                   {
    if (this->numBins(true) != other.numBins(true)) return false;
    for (size_t i = 1; i < this->numBins(true) - 1; i++) {
      if (!fuzzyEquals(edge(i), other.edge(i))) return false;
    }
    return true;
  }

References YODA::fuzzyEquals().

index()

template<typename T >

size_t YODA::Axis< T, isCAxis< T > >::index

(

const EdgeT &

x

)

const

Bin searcher.

Author

David Mallows

Andy Buckley

Handles low-level bin lookups using a hybrid algorithm that is considerably faster for regular (logarithmic or linear) and near-regular binnings. Comparable performance for irregular binnings.

The reason this works is that linear search is faster than bisection search up to about 32-64 elements. So we make a guess, and we then do a linear search. If that fails, then we bisect on the remainder, terminating once bisection search has got the range down to about 32. So we actually pay for the fanciness of predicting the bin out of speeding up the bisection search by finishing it with a linear search. So in most cases, we get constant-time lookups regardless of the space.

Definition at line 663 of file BinnedAxis.h.

                                                        {
      if (_edges.size() <= 2) throw BinningError("Axis initialised without specifying edges");
      // Check overflows
      if (std::isinf(x)) { return x < 0? 0 : _edges.size() - 2; }
      // Get initial estimate
      size_t index = std::min(_est->estindex(x), _edges.size()-2);
      // Return now if this is the correct bin
      if (x >= this->_edges[index] && x < this->_edges[index+1]) return index;
 
      // Otherwise refine the estimate, if x is not exactly on a bin edge
      if (x > this->_edges[index]) {
        const ssize_t newindex = _linsearch_forward(index, x, SEARCH_SIZElc);
        index = (newindex > 0) ? newindex : _bisect(x, index, this->_edges.size()-1);
      } else if (x < this->_edges[index]) {
        const ssize_t newindex = _linsearch_backward(index, x, SEARCH_SIZElc);
        index = (newindex > 0) ? newindex : _bisect(x, 0, index+1);
      }
 
      assert(x >= this->_edges[index] && (x < this->_edges[index+1] || std::isinf(x)));
      return index;
  }

References YODA::SEARCH_SIZElc.

isSubsetEdges()

template<typename T >

bool YODA::Axis< T, isCAxis< T > >::isSubsetEdges ( const Axis< EdgeT, CAxisT > &  other ) const

noexcept

Check if other axis edges are a subset of edges of this one.

Remarks

Should it be symmetrical? E.g. ax1.subsetEdges(ax2) == ax2.subsetEdges(ax1)?

Skip if any of axes only has two limit edges

Note

std::includes demands sorted ranges

Since one of the axes consists only of limits (-inf, +inf), it's a subset of the other one

Definition at line 740 of file BinnedAxis.h.

                                                                                     {
    if (_edges.size() == other._edges.size()) return hasSameEdges(other);
 
    if (_edges.size() > 2 && other._edges.size() > 2) {
      return std::includes(std::next(_edges.begin()), std::prev(_edges.end()),
                            std::next(other._edges.begin()), std::prev(other._edges.end()));
    }
 
    return true;
  }

maskedBins()

template<typename T >

std::vector< size_t > YODA::Axis< T, isCAxis< T > >::maskedBins ( ) const

inlinenoexcept

Returns the masked indices.

Definition at line 442 of file BinnedAxis.h.

{  return _maskedBins; }

max()

template<typename T >

EdgeT YODA::Axis< T, isCAxis< T > >::max ( size_t  binNum ) const

inlinenoexcept

Max of bin side on this axis.

Definition at line 503 of file BinnedAxis.h.

                                            {
      return _edges[binNum+1];
    }

mergeBins()

template<typename T >

void YODA::Axis< T, isCAxis< T > >::mergeBins

(

std::pair< size_t, size_t >

mergeRange

)

Merges bins, e.g. removes edges in between.

Note

At least 1 non-overflow bin must exist after merging.

Definition at line 756 of file BinnedAxis.h.

                                                                        {
    if (_edges.size() <= 2) throw BinningError("Axis initialised without specifying edges");
    if (mergeRange.second < mergeRange.first) throw RangeError("Upper index comes before lower index");
    if (mergeRange.second >= numBins(true)) throw RangeError("Upper index exceeds last visible bin");
    _edges.erase(_edges.begin()+mergeRange.first+1, _edges.begin() + mergeRange.second + 1);
    // masked bins above the merge range need to be re-indexed
    // masked bins within the merge range need to be unmasked
    std::vector<size_t> toRemove;
    size_t mrange = mergeRange.second - mergeRange.first;
    for (size_t i = 0; i < _maskedBins.size(); ++i) {
      if (_maskedBins[i] > mergeRange.second)  _maskedBins[i] -= mrange;
      else if (_maskedBins[i] >= mergeRange.first) toRemove.push_back(_maskedBins[i]);
    }
    if (toRemove.size()) {
      _maskedBins.erase(
        std::remove_if(_maskedBins.begin(), _maskedBins.end(), [&](const auto& idx) {
          return std::find(toRemove.begin(), toRemove.end(), idx) != toRemove.end();
      }), _maskedBins.end());
    }
  }

mid()

template<typename T >

EdgeT YODA::Axis< T, isCAxis< T > >::mid ( size_t  binNum ) const

inlinenoexcept

Mid of bin side on this axis.

Note

Corner bins are overflow bins, thus infinite limit values.

Definition at line 514 of file BinnedAxis.h.

                                            {
      if(binNum == 0)
        return std::numeric_limits<EdgeT>::min();
      if (binNum == (numBins(true) - 1))
        return std::numeric_limits<EdgeT>::max();
 
      EdgeT minVal = min(binNum);
      return (max(binNum) - minVal)/2 + minVal;
    }

min()

template<typename T >

EdgeT YODA::Axis< T, isCAxis< T > >::min ( size_t  binNum ) const

inlinenoexcept

Min of bin side on this axis.

Definition at line 509 of file BinnedAxis.h.

                                            {
      return _edges[binNum];
    }

numBins()

template<typename T >

size_t YODA::Axis< T, isCAxis< T > >::numBins ( const bool  includeOverflows = false ) const

noexcept

Returns amount of bins in axis.

Definition at line 691 of file BinnedAxis.h.

                                                                                {
    if (_edges.size() < 3)  return includeOverflows? 1 : 0; // no visible bin edge
    return this->_edges.size() - (includeOverflows? 1 : 3); // has 2 extra edges for +-inf
  }

References YODA::Axis< T, typename >::size().

operator=() [1/2]

template<typename T >

Axis & YODA::Axis< T, isCAxis< T > >::operator= ( Axis< T, isCAxis< T > > &&  other )

inline

Definition at line 372 of file BinnedAxis.h.

                                  {
      if (this != &other) {
        _est = std::move(other._est);
        _maskedBins = std::move(other._maskedBins);
        _edges = std::move(other._edges);
      }
      return *this;
    }

operator=() [2/2]

template<typename T >

Axis & YODA::Axis< T, isCAxis< T > >::operator= ( const Axis< T, isCAxis< T > > &  other )

inline

Definition at line 363 of file BinnedAxis.h.

                                       {
      if (this != &other) {
        _est = other._est;
        _maskedBins = other._maskedBins;
        _edges = other._edges;
      }
      return *this;
    }

sharedEdges()

template<typename T >

std::vector< T > YODA::Axis< T, isCAxis< T > >::sharedEdges ( const Axis< EdgeT, CAxisT > &  other ) const

noexcept

Find edges which are shared between BinnedAxis objects, within numeric tolerance.

Note

The return vector is sorted and includes -inf and inf

Skip if any of axes only has two limit edges

Definition at line 717 of file BinnedAxis.h.

                                                                                           {
    std::vector<T> intersection;
 
    if (_edges.size() > 2 && other._edges.size() > 2) {
      std::set_intersection(std::next(_edges.begin()), std::prev(_edges.end()),
                            std::next(other._edges.begin()), std::prev(other._edges.end()),
                            std::back_inserter(intersection));
    }
 
    std::vector<T> rtn;
    rtn.reserve(intersection.size()+2);
 
    rtn.emplace_back(-std::numeric_limits<Axis<T, isCAxis<T>>::EdgeT>::infinity());
    rtn.insert(std::next(rtn.begin()),
                  std::make_move_iterator(intersection.begin()),
                  std::make_move_iterator(intersection.end()));
    rtn.emplace_back(std::numeric_limits<Axis<T, isCAxis<T>>::EdgeT>::infinity());
 
    return rtn;
  }

size()

template<typename T >

size_t YODA::Axis< T, isCAxis< T > >::size ( ) const

noexcept

Returns amount of bins in axis.

Definition at line 686 of file BinnedAxis.h.

                                                  {
    return numBins(true); // number of visible + 2 for +-inf
  }

type()

template<typename T >

std::string YODA::Axis< T, isCAxis< T > >::type ( ) const

inlinenoexcept

Returns a string representation of EdgeT.

Definition at line 467 of file BinnedAxis.h.

{ return TypeID<EdgeT>::name(); }

width()

template<typename T >

EdgeT YODA::Axis< T, isCAxis< T > >::width ( size_t  binNum ) const

inlinenoexcept

Width of bin side on this axis.

Definition at line 498 of file BinnedAxis.h.

                                              {
      return _edges[binNum+1] - _edges[binNum];
    }

widths()

template<typename T >

std::vector< T > YODA::Axis< T, isCAxis< T > >::widths ( const bool  includeOverflows = false ) const

inlinenoexcept

Definition at line 484 of file BinnedAxis.h.

                                                                            {
      // number of widths = number of edges - 1
      // unless you exclude under-/overflow
      size_t offset = includeOverflows? 1 : 3;
      std::vector<T> ret(_edges.size()-offset);
      size_t start = 1 + !includeOverflows;
      size_t end = _edges.size() - !includeOverflows;
      for (size_t i = start; i < end; ++i) {
        ret[i-start] = _edges[i] - _edges[i-1];
      }
      return ret;
    }

---

The documentation for this class was generated from the following file:

• include/YODA/BinnedAxis.h