QuantileFactory Class Reference

Builds binning and quantisation functions from a JSON configuration. More...

#include <QuantileFactory.h>

Collaboration diagram for QuantileFactory:

Public Types
using	QuantileFunc = std::pair<size_t, std::function<int(const SG::AuxElement&)>>

Static Public Member Functions
static QuantileFunc	quantileFactory (const nlohmann::json &cfg)
	Dispatch to the appropriate binning scheme based on the JSON config.
static std::vector< float >	parseEdges (const nlohmann::json &cfg)
	Parse an ordered list of bin edges from the JSON config.

Static Private Member Functions
static QuantileFunc	makeEnumerate (const nlohmann::json &cfg)
	Maps discrete values to category indices.
static QuantileFunc	makeCategory (const nlohmann::json &cfg)
	Converts a continuous variable into a bin index using an ordered list of bin edges.
static QuantileFunc	makeNodes (const nlohmann::json &cfg)
	Builds a tree-based lookup structure for node-based binning, primarily used for pseudo-continuous 2D tagging.
static QuantileFunc	makeDense (const nlohmann::json &cfg)
	Combines multiple binning dimensions into a single flattened global index used for scale factor lookup.

Detailed Description

Builds binning and quantisation functions from a JSON configuration.

Several binning schemes are supported, each suited to a different representation of the tagger output. The quantileFactory dispatches to the appropriate scheme based on the configuration.

Definition at line 16 of file QuantileFactory.h.

Member Typedef Documentation

QuantileFunc

using QuantileFactory::QuantileFunc = std::pair<size_t, std::function<int(const SG::AuxElement&)>>

Definition at line 19 of file QuantileFactory.h.

Member Function Documentation

makeCategory()

QuantileFactory::QuantileFunc QuantileFactory::makeCategory ( const nlohmann::json & cfg )

staticprivate

Converts a continuous variable into a bin index using an ordered list of bin edges.

Definition at line 43 of file QuantileFactory.cxx.

                                                                         {
  VariableFactory::IntFunc var = VariableFactory::intVariableFactory(cfg.at("variable"));
  std::vector<int> values = cfg.at("values").get<std::vector<int>>();
  int default_bin = cfg.at("default").get<int>();
 
  std::unordered_map<int,int> mapping;
  for (int i = 0; i < static_cast<int>(values.size()); ++i) {
    mapping[values[i]] = i;
  }
 
  auto func = [var, mapping, default_bin](const SG::AuxElement& el) -> int {
    int v = static_cast<int>(var(el));
    auto it = mapping.find(v);
    if (it != mapping.end()) {
      return it->second;
    }
    return default_bin;
  };
 
  return {values.size(), func};
 
}

makeDense()

QuantileFactory::QuantileFunc QuantileFactory::makeDense ( const nlohmann::json & cfg )

staticprivate

Combines multiple binning dimensions into a single flattened global index used for scale factor lookup.

Definition at line 141 of file QuantileFactory.cxx.

                                                                       {
  std::vector<std::function<int(const SG::AuxElement&)>> axes;
  std::vector<size_t> axis_sizes;
 
  for (const auto& axis : cfg.at("axes")) {
    auto [size, func] = QuantileFactory::quantileFactory(axis);
    axes.push_back(func);
    axis_sizes.push_back(size);
  }
 
  std::vector<int> strides(axes.size(), 1);
  for (int i = static_cast<int>(axes.size()) - 2; i >= 0; --i) {
    strides[i] = strides[i+1] * axis_sizes[i+1];
  }
 
  auto func = [axes, strides](const SG::AuxElement& el) -> int {
    int index = 0;
    for (size_t i = 0; i < axes.size(); ++i) {
      int bin = axes[i](el);
      if (bin < 0) {return -1;}
      index += bin * strides[i];
    }
    return index;
  };
 
  size_t total_size = 1;
  for (size_t size : axis_sizes) {
    total_size *= size;
  }
 
  return {total_size, func};
}

makeEnumerate()

QuantileFactory::QuantileFunc QuantileFactory::makeEnumerate ( const nlohmann::json & cfg )

staticprivate

Maps discrete values to category indices.

Definition at line 66 of file QuantileFactory.cxx.

                                                                          {
  VariableFactory::FloatFunc var = VariableFactory::floatVariableFactory(cfg.at("variable"));
  std::vector<float> edges = QuantileFactory::parseEdges(cfg.at("edges"));
 
  const bool useAbs = cfg.value("abs", false);
 
  int underflow_bin = cfg.value("underflow_bin", -1);
  int overflow_bin  = cfg.value("overflow_bin", -1);
 
  auto func = [var, edges, useAbs, underflow_bin, overflow_bin] (const SG::AuxElement& el) -> int {
    float v = var(el);
    if (useAbs)  v = std::abs(v);
 
    if (v < edges.front()) {
      return underflow_bin;
    }
    if (v >= edges.back()) {
      return overflow_bin;
    }
 
    auto it = std::lower_bound(edges.begin(), edges.end(), v);
    return static_cast<int>(std::distance(edges.begin(), it)) - 1;
  };
 
  return {edges.size() - 1, func};
}

makeNodes()

QuantileFactory::QuantileFunc QuantileFactory::makeNodes ( const nlohmann::json & cfg )

staticprivate

Builds a tree-based lookup structure for node-based binning, primarily used for pseudo-continuous 2D tagging.

Definition at line 94 of file QuantileFactory.cxx.

                                                                      {
  VariableFactory::FloatFunc var = VariableFactory::floatVariableFactory(cfg.at("variable"));
  std::vector<float> edges = QuantileFactory::parseEdges(cfg.at("edges"));
 
  std::vector<std::function<int(const SG::AuxElement&)>> sub_nodes;
  std::vector<size_t> sub_sizes;
 
  size_t totalSize = 0;
 
  for (const auto& node : cfg.at("nodes")) {
    auto [size, func] = QuantileFactory::quantileFactory(node);
    sub_nodes.push_back(func);
    sub_sizes.push_back(size);
    totalSize += size;
  }
 
  std::string numbering = cfg.value("numbering", "sequential");
 
  std::vector<int> offsets(sub_nodes.size(), 0);
  if (numbering == "sequential") {
    for (size_t i = 1; i < sub_nodes.size(); ++i) {
      offsets[i] = offsets[i-1] + sub_sizes[i-1];
    }
  }
 
  auto func = [var, edges, sub_nodes, offsets, numbering]
         (const SG::AuxElement& el) -> int {
    float v = var(el);
 
    auto it = std::lower_bound(edges.begin(), edges.end(), v);
    int region = static_cast<int>(std::distance(edges.begin(), it)) - 1;
    if (region < 0 || region >= static_cast<int>(edges.size()) - 1) {
      throw std::runtime_error("Failed to find region for value " + std::to_string(v));
    }
 
    int local = sub_nodes[region](el);
 
    if (numbering == "sequential") {
      return offsets[region] + local;
    }
    return local;
  };
 
  return {totalSize, func};
}

parseEdges()

std::vector< float > QuantileFactory::parseEdges ( const nlohmann::json & cfg )

static

Parse an ordered list of bin edges from the JSON config.

Edges may be finite floats or the strings "inf", "+inf", "-inf". Throws if the resulting edges are not strictly sorted in ascending order.

Definition at line 9 of file QuantileFactory.cxx.

                                                           {
  std::vector<float> edges;
  edges.reserve(cfg.size());
 
  for (const auto& val : cfg) {
    if (val.is_number()) {
      edges.push_back(val.get<float>());
    }
    else if (val.is_string()) {
      const std::string s = val.get<std::string>();
 
      if (s == "inf" || s == "+inf") {
        edges.push_back(std::numeric_limits<float>::infinity());
      }
      else if (s == "-inf") {
        edges.push_back(-std::numeric_limits<float>::infinity());
      }
      else {
        throw std::runtime_error("Invalid edge value: " + s);
      }
    }
    else {
      throw std::runtime_error("Edge must be a number or \"inf\"/\"-inf\", got:" + val.dump());
    }
  }
 
  // Verify edges are strictly sorted ascending — catches malformed JSON early.
  if (!std::is_sorted(edges.begin(), edges.end())) {
    throw std::runtime_error("Bin edges must be sorted in ascending order");
  }
 
  return edges;
}

quantileFactory()

QuantileFactory::QuantileFunc QuantileFactory::quantileFactory ( const nlohmann::json & cfg )

static

Dispatch to the appropriate binning scheme based on the JSON config.

Definition at line 174 of file QuantileFactory.cxx.

                                                                            {
 
  std::string type = cfg.at("type");
 
  if (type == "category")  return QuantileFactory::makeCategory(cfg);
  if (type == "enumerate") return QuantileFactory::makeEnumerate(cfg);
  if (type == "nodes")     return QuantileFactory::makeNodes(cfg);
  if (type == "dense")     return QuantileFactory::makeDense(cfg);
 
  throw std::runtime_error("Unknown quantile type: " + type);
 
}

---

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

• QuantileFactory.h
• QuantileFactory.cxx