icarus::ns::util Namespace Reference

Namespaces
	details

Classes
class	AtomicPassCounter
	Class counting pass/fail events. More...
class	FormatFlagsGuard
	Saves some status of the specified stream object, and restores it. More...
class	BinningSpecs
	Data structure holding binning information. More...
struct	ChangeMonitor
	Helper to check if an object has changed. More...
class	ThreadSafeChangeMonitor
	Helper to check if an object has changed. Thread-safe. More...
class	FixedBins
	Binned counts of data. More...
class	mfLoggingClass
	Helper for logging classes. More...
class	PassCounter
	Class counting pass/fail events. More...

Functions
template<typename T >
	ChangeMonitor (T const &) -> ChangeMonitor< T >
template<typename T >
	ThreadSafeChangeMonitor (T const &) -> ThreadSafeChangeMonitor< T >
template<typename T , typename C >
bool	empty (FixedBins< T, C > const &) noexcept
template<typename T , typename C >
std::size_t	size (FixedBins< T, C > const &) noexcept
template<typename T , typename C >
auto	cbegin (FixedBins< T, C > const &) noexcept
template<typename T , typename C >
auto	begin (FixedBins< T, C > const &) noexcept
template<typename T , typename C >
auto	cend (FixedBins< T, C > const &) noexcept
template<typename T , typename C >
auto	end (FixedBins< T, C > const &) noexcept
template<typename T >
	FixedBins (T) -> FixedBins< T >
template<typename T , typename U >
constexpr T	rounddown (T const value, U const quantum, T const offset=T{})
	Returns the value, rounded down. More...
template<typename T , typename U >
constexpr T	roundup (T const value, U const quantum, T const offset=T{})
	Returns the value, rounded up. More...
Format adapters
These functions should be used in stream insertion statements like: std::cout << icarus::ns::util::bin(0xAA) << std::endl;
template<typename T >
constexpr details::BinObj< T >	bin (T value)
	Returns a wrapper to print the specified data in binary format. More...
template<std::size_t Bits, typename T >
constexpr details::BinObj< T, Bits >	bin (T value)
	Returns a wrapper to print the specified data in binary format. More...
template<typename Atom >
details::HexDumper< Atom >	hexdump (Atom const *data, std::size_t size, unsigned int columns=16U)
	Returns a wrapper to print the specified data in hex dump format. More...
template<typename T >
details::ZeroPadder< T >	zeropad (T data, unsigned int field, char pad= '0')
	Returns a wrapper to print the specified data with a field width. More...
DetectorClocksData helpers
detinfo::DetectorClocksData	makeDetClockData (art::Event const *event)
	Returns a detinfo::DetectorClocksData from DetectorClocksService. More...
detinfo::DetectorClocksData	makeDetClockData (art::Event const &event)
detinfo::DetectorClocksData	makeDetClockData ()
DetectorTimings helpers
detinfo::DetectorTimings	makeDetTimings (art::Event const *event)
	Returns a detinfo::DetectorTimings from DetectorClocksService. More...
detinfo::DetectorTimings	makeDetTimings (art::Event const &event)
detinfo::DetectorTimings	makeDetTimings ()

Algorithms for binning.
The BinningSpecs class collects the usual characteristics of a binning: full range boundaries, number of bins, bin width. A few functions are provided that create a binning with "human-friendly" characteristics for pleasant plots: given a selection of bin width hints, the functions try to create a binning accommodating those hints. These functions always require the full range of the binning to be specified, and can take either a desired number of bins, or their width.
constexpr std::initializer_list< double >	DefaultBinningHints { 1.0, 0.8, 2.0, 0.5, 4.0, 5.0, 10.0, 20.0 }
	Set of bin sizes to be considered by the binning algorithms. More...
constexpr double	DefaultAllowedBinningStretch { 0.5 }
	Stretch factor on the requested binning range an algorithm is allowed. More...
BinningSpecs	makeBinningFromBinWidth (double lower, double upper, double width, std::initializer_list< double > hints=DefaultBinningHints, double allowedStretch=DefaultAllowedBinningStretch)
	Returns the "optimal" binning for the requested parameters. More...
BinningSpecs	makeBinningFromNBins (double lower, double upper, unsigned long nBins, std::initializer_list< double > hints=DefaultBinningHints, double allowedStretch=DefaultAllowedBinningStretch)
	Returns the "optimal" binning for the requested parameters. More...
BinningSpecs	alignBinningTo (BinningSpecs const &binning, double boundary, bool extendCoverage=true)
	Returns a binning shifted to align with the specified boundary. More...
double	chooseBinningWidth (double lower, double upper, double width, unsigned long nBins, std::initializer_list< double > hints=DefaultBinningHints, double allowedStretch=DefaultAllowedBinningStretch)
	Returns the "optimal" bin width for the requested parameters. More...

Function Documentation

auto icarus::ns::util::alignBinningTo	(	BinningSpecs const &	binning,
		double	boundary,
		bool	extendCoverage = true
	)

Returns a binning shifted to align with the specified boundary.

Parameters

binning	the binning to be aligned
boundary	the point to align the binning with
extendCoverage	(default: true) increase number of bins if needed

Returns

a new, aligned binning

The binning lower and upper boundaries are moved so that one of the bins has boundary as a border. The shift is the minimal to achieve the goal. If extendCoverage is true, if the boundaries are shifted a single bin is also added to the binning to preserve (and extend) the original coverage region; otherwise, the size of the binning stays the same but part of the original range may not be covered by the returned binning.

Definition at line 112 of file BinningSpecs.cxx.

                  {
  
  int const iBin = binning.binWith(boundary);
  std::pair<double, double> const binBorders = binning.binBorders(iBin);
  
  double const shift { boundary - (
      ((boundary - binBorders.first) <= (binBorders.second - boundary))
      ? binBorders.first
      : boundary - binBorders.second
      )
    };
  
  double const width = binning.binWidth();
  double lower = binning.lower() + shift;
  double upper = binning.upper() + shift;
  if (extendCoverage && (shift != 0.0)) { // rounding may be trouble here...
    if (shift > 0.0) lower -= width;
    else             upper += width;
  }
  
  return BinningSpecs{ lower, upper, width };
  
} // icarus::ns::util::alignBinningTo()

template<typename T , typename C >

auto icarus::ns::util::begin ( FixedBins< T, C > const &  bins )

noexcept

Definition at line 573 of file FixedBins.h.

  { return bins.begin(); }

template<typename T >

constexpr details::BinObj<T> icarus::ns::util::bin

(

T

value

)

Returns a wrapper to print the specified data in binary format.

Template Parameters

T	type of datum to be printed

Parameters

value

the value to be printed

See Also

icarus::ns::util::details::operator<< (std::ostream&, icarus::ns::util::details::BinObj<T, Bits> const&) * Example:

std::cout << icarus::ns::util::bin(0xAA) << std::endl;
std::cout << icarus::ns::util::bin<char>(0xAA) << std::endl;

will print (32) 0000 0000 0000 0000 0000 0000 1010 1010 on the first line (assuming the representation of int is 32 bit) and (8) 1010 1010 on the second line.

template<std::size_t Bits, typename T >

constexpr details::BinObj<T, Bits> icarus::ns::util::bin

(

T

value

)

Returns a wrapper to print the specified data in binary format.

Template Parameters

Bits	number of bits to print out of the type T
T	type of datum to be printed

Parameters

value

the value to be printed

See Also

icarus::ns::util::details::operator<< (std::ostream&, icarus::ns::util::details::BinObj<T, Bits> const&)

Only the least significant Bits will be printed.

Example:

std::cout << icarus::ns::util::bin<10U>(0xAA) << std::endl;

will print (10) 00 1010 1010.

template<typename T , typename C >

auto icarus::ns::util::cbegin ( FixedBins< T, C > const &  bins )

noexcept

Definition at line 567 of file FixedBins.h.

  { return bins.cbegin(); }

template<typename T , typename C >

auto icarus::ns::util::cend ( FixedBins< T, C > const &  bins )

noexcept

Definition at line 579 of file FixedBins.h.

  { return bins.cend(); }

template<typename T >

icarus::ns::util::ChangeMonitor

(

T const &

)

-> ChangeMonitor< T >

double icarus::ns::util::chooseBinningWidth	(	double	lower,
		double	upper,
		double	width,
		unsigned long	nBins,
		std::initializer_list< double >	hints = DefaultBinningHints,
		double	allowedStretch = DefaultAllowedBinningStretch
	)

Returns the "optimal" bin width for the requested parameters.

Parameters

lower	desired lower limit of the binning
upper	desired upper limit of the binning
width	desired bin width
nBins	desired number of bins
hints	set of bin sizes to consider (not including the order of magnitude)
allowedStretch	how much the resulting range can differ from the desired one (upper - lower), as a factor

Returns

the recommended bin width

This is the core algorithm for determining a binning. Bin width is chosen so that it is multiple (within its order of magnitude) of any of the hinted factors and the total range is not "too far" (the stretching factor is no larger than allowedStretch).

The hint is chosen that yields the lower stretch. On tie, priority is given to the earlier hint in the list. If no hint is good enough, width is returned unchanged.

Definition at line 140 of file BinningSpecs.cxx.

  {
  
  assert(allowedStretch > 0.0);
  assert(width > 0.0);
  assert(lower <= upper);
  
  // order of magnitude of the bins: width will be chosen as this power-of-ten
  // multiplied by one of the hinted values
  double const order = std::pow(10.0, std::floor(std::log10(width)));
  
  double span = upper - lower;
  
  // don't consider binnings stretching the range more than allowed;
  // if no hinted binning is good enough, exact `width` will be used
  using Quality_t = std::pair<double, double>; // stretch/distance from request
  
  double best_w = width;
  Quality_t best_d { allowedStretch, 0.0 };
  for (double const factor: hints) {
    double const w = order * factor;
    Quality_t const d {
      std::abs((w * nBins / span) - 1.0),
      std::abs(w - width)
    };
    if (d >= best_d) continue;
    best_d = d;
    best_w = w;
  } // for
  
  return best_w;
  
} // icarus::ns::util::chooseBinningWidth()

template<typename T , typename C >

bool icarus::ns::util::empty ( FixedBins< T, C > const &  bins )

noexcept

Definition at line 555 of file FixedBins.h.

  { return bins.empty(); }

template<typename T , typename C >

auto icarus::ns::util::end ( FixedBins< T, C > const &  bins )

noexcept

Definition at line 585 of file FixedBins.h.

  { return bins.end(); }

template<typename T >

icarus::ns::util::FixedBins

(

T

)

-> FixedBins< T >

template<typename Atom >

details::HexDumper<Atom> icarus::ns::util::hexdump	(	Atom const *	data,
		std::size_t	size,
		unsigned int	columns = 16U
	)

Returns a wrapper to print the specified data in hex dump format.

Template Parameters

Atom	type of basic element of the data

Parameters

data	pointer to the data to be printed
size	number of elements to be printed
columns	(default: 16) atoms per output line

See Also

icarus::ns::util::details::operator<< (std::ostream&, icarus::ns::util::details::HexDumper<Atom> const&)

Only the least significant Bits will be printed.

Example:

const char data[] = "012345";
std::cout << icarus::ns::util::hexdump(data, 7U, 8U) << std::endl;

will print 7 bytes from data, using a 8 column format, with an output similar to:

0X81234560 | 30 31 32 33  34 35 00    |

while

const std::uint16_t powers[]
  = { 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096 };
std::cout << icarus::ns::util::hexdump(powers, 13U, 8U) << std::endl;

will print 13 values from data, using a 8 column format, with an output similar to:

0X81234570 | 0001 0002 0004 0008  0010 0020 0040 0080 |
0X81234580 | 0100 0200 0400 0800  1000                |

auto icarus::ns::util::makeBinningFromBinWidth	(	double	lower,
		double	upper,
		double	width,
		std::initializer_list< double >	hints = DefaultBinningHints,
		double	allowedStretch = DefaultAllowedBinningStretch
	)

Returns the "optimal" binning for the requested parameters.

Parameters

lower	desired lower limit of the binning
upper	desired upper limit of the binning
width	desired bin width
hints	set of bin sizes to consider (not including the order of magnitude)
allowedStretch	how much the resulting range can differ from the desired one (upper - lower), as a factor

Returns

the optimal binning

Bin width is used as returned by chooseBinningWidth() function, which chooses it so that it is multiple (within its order of magnitude) of any of the hinted factors and the total range is not "too far" (the stretching factor is no larger than allowedStretch).

Lower and upper limit are then aligned with that bin width (so that 0 would appear as a bin limit). Lower and upper limits are guaranteed to be included in the binning.

Note

The final bin width will likely differ from the requested one.

Definition at line 80 of file BinningSpecs.cxx.

                  {
  
  double const finalWidth = chooseBinningWidth(
    lower, upper, width, BinningSpecs::NBinsFor(lower, upper, width),
    std::move(hints), allowedStretch
    );
  return makeBinningAlignedTo0(lower, upper, finalWidth);
  
} // icarus::ns::util::makeBinningFromBinWidth()

auto icarus::ns::util::makeBinningFromNBins	(	double	lower,
		double	upper,
		unsigned long	nBins,
		std::initializer_list< double >	hints = DefaultBinningHints,
		double	allowedStretch = DefaultAllowedBinningStretch
	)

Returns the "optimal" binning for the requested parameters.

Parameters

lower	desired lower limit of the binning
upper	desired upper limit of the binning
nBins	desired number of bins
hints	set of bin sizes to consider (not including the order of magnitude)
allowedStretch	how much the resulting range can differ from the desired one (upper - lower), as a factor

Returns

the optimal binning

Bin width is used as returned by chooseBinningWidth() function, which chooses it so that it is multiple (within its order of magnitude) of any of the hinted factors and the total range is not "too far" (the stretching factor is no larger than allowedStretch).

Lower and upper limit are then aligned with that bin width (so that 0 would appear as a bin limit). Lower and upper limits are guaranteed to be included in the binning.

Note

The final number of bins may differ from the requested one.

Definition at line 96 of file BinningSpecs.cxx.

                  {

  double const finalWidth = chooseBinningWidth(
    lower, upper, (upper - lower) / nBins, nBins,
    std::move(hints), allowedStretch
    );
  return makeBinningAlignedTo0(lower, upper, finalWidth);
  
} // icarus::ns::util::makeBinningFromNBins()

detinfo::DetectorClocksData icarus::ns::util::makeDetClockData

(

art::Event const *

event

)

Returns a detinfo::DetectorClocksData from DetectorClocksService.

Parameters

event

pointer to an art event

Returns

a detinfo::DetectorClocksData object (see the details below)

The detinfo::DetectorClocksService is queried to obtain a detinfo::DetectorClocksData object. The returned object is a static copy whose values will never update, even if the DetectorClocksService state changes.

If the event pointer is valid (i.e. not nullptr), the event is passed to the service DataFor() method for a complete timing record. Otherwise, DataForJob() is used, and the information might be incomplete or become outdated by the time a new event, run or file is accessed.

Note

This function is art dependent and accesses DetectorClocksService service.

Definition at line 49 of file icarusalg/icarusalg/Utilities/DetectorClocksHelpers.h.

    {
      auto const& detClocks
        = *(art::ServiceHandle<detinfo::DetectorClocksService const>());
      return event? detClocks.DataFor(*event): detClocks.DataForJob();
    } // makeDetClockData()

detinfo::DetectorClocksData icarus::ns::util::makeDetClockData

(

art::Event const &

event

)

Returns detector clock data for the specified event.

See Also

makeDetClockData(art::Event const*)

Definition at line 58 of file icarusalg/icarusalg/Utilities/DetectorClocksHelpers.h.

    { return makeDetClockData(&event); }

detinfo::DetectorClocksData icarus::ns::util::makeDetClockData

(

)

Returns generic detector clock data for the job.

See Also

makeDetClockData(art::Event const*)

Definition at line 63 of file icarusalg/icarusalg/Utilities/DetectorClocksHelpers.h.

    { return makeDetClockData(nullptr); }

detinfo::DetectorTimings icarus::ns::util::makeDetTimings

(

art::Event const *

event

)

Returns a detinfo::DetectorTimings from DetectorClocksService.

Parameters

event

pointer to an art event

Returns

a detinfo::DetectorTimings object (see the details below)

See Also

makeDetClockData(art::Event const*)

A detinfo::DetectorTimings object is created out of information obtained from detinfo::DetectorClocksService.

All the considerations described in makeDetClockData(art::Event const*) also hold for this function.

Definition at line 86 of file icarusalg/icarusalg/Utilities/DetectorClocksHelpers.h.

    { return detinfo::DetectorTimings{ makeDetClockData(event) }; }

detinfo::DetectorTimings icarus::ns::util::makeDetTimings

(

art::Event const &

event

)

Returns detector clock data for the specified event.

See Also

makeDetTimings(art::Event const*)

Definition at line 91 of file icarusalg/icarusalg/Utilities/DetectorClocksHelpers.h.

    { return makeDetTimings(&event); }

detinfo::DetectorTimings icarus::ns::util::makeDetTimings

(

)

Returns generic detector clock data for the job.

See Also

makeDetTimings(art::Event const*)

Definition at line 96 of file icarusalg/icarusalg/Utilities/DetectorClocksHelpers.h.

    { return makeDetTimings(nullptr); }

template<typename T , typename U >

constexpr T icarus::ns::util::rounddown	(	T const	value,
		U const	quantum,
		T const	offset = T{}
	)

Returns the value, rounded down.

Template Parameters

T	type of the value to be rounded
U	type of the quantization value

Parameters

value	the value to be rounded down
quantum	the rounding unit
offset	an offset to subtract for the rounding

Returns

value rounded down to multiples of quantum

The value is returned rounded down into multiples of quantum. Optionally, the rounding happens only for the amount of value above an offset. Examples:

std::cout << icarus::ns::util::rounddown(23.0, 2.5)
  << "\n" << icarus::ns::util::rounddown(23.0, 2.5, 1.0)
  << std::endl;

will print 22.5 and 21.

Type requirements

• T must support addition and subtraction;
• U must support product to double: P operator* (U, double), with the result P implicitly convertible to T;
• T and U must support multiplication (P operator* (T, U)), and the result P must be convertible back to T;
• T and U must support division (R operator/ (T, U)), and the result R must be implicitly convertible to an integral or floating point type;
• T and U must support addition (S operator+ (T, U)), and the result S must be convertible back to type T.

Definition at line 68 of file rounding.h.

{
  return
    static_cast<T>(offset + quantum * std::floor((value - offset) / quantum));
} // icarus::ns::util::rounddown()

template<typename T , typename U >

constexpr T icarus::ns::util::roundup	(	T const	value,
		U const	quantum,
		T const	offset = T{}
	)

Returns the value, rounded up.

Template Parameters

T	type of the value to be rounded
U	type of the quantization value

Parameters

value	the value to be rounded up
quantum	the rounding unit
offset	an offset to subtract for the rounding

Returns

value rounded up to multiples of quantum

The value is returned rounded up into multiples of quantum. Optionally, the rounding happens only for the amount of value above an offset. Examples:

std::cout << icarus::ns::util::roundup(23.0, 2.5)
  << "\n" << icarus::ns::util::roundup(23.0, 2.5, 1.0)
  << std::endl;

will print 25 and 23.5.

Type requirements

• T must support comparison (operator < (T, T);
• T must support addition and subtraction;
• double must be convertivle into T;
• T and U must support multiplication (P operator* (T, U)), and the result P must be convertible back to type T;
• T and U must support division (R operator/ (T, U)), and the result R must be implicitly convertible to an integral or floating point type;
• T and U must support addition (S operator+ (T, U)), and the result S must be convertible back to type T.

Definition at line 112 of file rounding.h.

{
  T const rounded = rounddown(value, quantum, offset);
  return (rounded < value)? static_cast<T>(rounded + quantum): rounded;
} // icarus::ns::util::roundup()

template<typename T , typename C >

std::size_t icarus::ns::util::size ( FixedBins< T, C > const &  bins )

noexcept

Definition at line 561 of file FixedBins.h.

  { return bins.size(); }

template<typename T >

icarus::ns::util::ThreadSafeChangeMonitor

(

T const &

)

-> ThreadSafeChangeMonitor< T >

template<typename T >

details::ZeroPadder<T> icarus::ns::util::zeropad	(	T	data,
		unsigned int	field,
		char	pad = '0'
	)

Returns a wrapper to print the specified data with a field width.

Template Parameters

T	type of data to be printed

Parameters

data	value to be printed
field	number of characters to use
pad	(default: 0) filling character

Returns

object to be inserted into a stream

The specified value is printed right-padded into a space at least field character wide, using pad as filling character on the left of value.

C++ STL I/O is used to produce the output. Example:

std::cout << icarus::ns::util::zeropad(79, 4) << std::endl;

will print 0079 while

std::cout << std::hex << icarus::ns::util::zeropad(79, 4, '*') << std::endl;

will print **4F.

Variable Documentation

constexpr double icarus::ns::util::DefaultAllowedBinningStretch { 0.5 }

inline

Stretch factor on the requested binning range an algorithm is allowed.

Definition at line 47 of file BinningSpecs.h.

constexpr std::initializer_list<double> icarus::ns::util::DefaultBinningHints { 1.0, 0.8, 2.0, 0.5, 4.0, 5.0, 10.0, 20.0 }

inline

Set of bin sizes to be considered by the binning algorithms.

Definition at line 43 of file BinningSpecs.h.