Belle II Software light-2406-ragdoll
BestCandidateSelectionModule.cc
1/**************************************************************************
2 * basf2 (Belle II Analysis Software Framework) *
3 * Author: The Belle II Collaboration *
4 * *
5 * See git log for contributors and copyright holders. *
6 * This file is licensed under LGPL-3.0, see LICENSE.md. *
7 **************************************************************************/
8
9#include <analysis/modules/BestCandidateSelection/BestCandidateSelectionModule.h>
10
11#include <analysis/utility/ValueIndexPairSorting.h>
12
13#include <analysis/VariableManager/Utility.h>
14
15#include <analysis/DecayDescriptor/DecayDescriptor.h>
16
17#include <framework/logging/Logger.h>
18#include <framework/utilities/MakeROOTCompatible.h>
19
20using namespace std;
21using namespace Belle2;
22
23
24REG_MODULE(BestCandidateSelection);
25
26
28 m_variable(nullptr)
29{
30 //the "undefined order" bit is not strictly true in the current implementation, but details (with anti-particle lists) are tricky
31 setDescription(R"DOC(Sort particles by the value of a given ``variable``
32in the input list and optionally remove particles after the nth position.
33
34Per default particles are sorted in descending order but it can be switched to
35an ascending order by setting ``selectLowest=True``. The convenience functions
36`modularAnalysis.rankByHighest` and `modularAnalysis.rankByLowest` set this
37parameter automatically based on their names.
38
39Particles will receive an extra-info field containing their rank as an integer
40starting at 1 (best). The name of this extra-info field defaults to
41``${variable}_rank`` but can be chosen freely using the ``outputVariable``
42parameter.
43
44The ranking also takes antiparticles into account, so there will only be one
45B+- candidate with ``rank=1``. The remaining list is sorted from best to worst
46candidate (each charge, e.g. B+/B-, separately). The sorting is guaranteed
47to be stable between particle and anti particle list: particles with the same
48value for ``variable`` will keep their relative order. That is, a particle "A"
49which was before another particle "B" in the same list and has the same value
50for ``variable`` will also stay before "B" after sorting.
51
52If ``allowMultiRank=False`` (the default) candidates with same value of
53``variable`` will have different ranks. If ``allowMultiRank=True`` they will
54share the same rank.
55
56IF ``numBest>0`` only candidates with this rank or better will remain in the
57output list. If ``allowMultiRank=True`` that means that there can be more than
58``numBest`` candidates in the output list if they share ranks.
59)DOC");
60
62
63 addParam("particleList", m_inputListName, "Name of the ParticleList to rank for best candidate");
64 addParam("variable", m_variableName, "Variable which defines the candidate ranking (see ``selectLowest`` for ordering)");
65 addParam("selectLowest", m_selectLowest, "If true, candidate with lower values of ``variable`` are better, otherwise higher is better", false);
66 addParam("allowMultiRank", m_allowMultiRank, "If true, candidates with identical values get identical rank", false);
67 addParam("numBest", m_numBest, "Keep only particles with this rank or better. If ``allowMultiRank=False`` this is "
68 "identical to the maximum amount of candidates left in the list. Otherwise there may be more candidates if "
69 "some share the same rank (0: keep all)", 0);
70 addParam("cut", m_cutParameter, "Only candidates passing the cut will be ranked. The others will have rank -1.", std::string(""));
71 addParam("outputVariable", m_outputVariableName,
72 "Name for created variable, which contains the rank for the particle. If not provided, the standard name ``${variable}_rank`` is used.");
73 addParam("overwriteRank", m_overwriteRank, "If true, the extraInfo of rank is overwritten when the particle has already the extraInfo.", false);
74
75}
76
78
80{
82 m_inputList.isRequired(m_inputListName);
83
85 if (!m_variable) {
86 B2ERROR("Variable '" << m_variableName << "' is not available in Variable::Manager!");
87 }
88 if (!(m_variable->variabletype == Variable::Manager::VariableDataType::c_double or m_variable->variabletype == Variable::Manager::VariableDataType::c_int)) {
89 B2ERROR("Variable '" << m_variableName << "' has wrong data type! It must be either double or integer.");
90 }
91 if (m_numBest < 0) {
92 B2ERROR("value of numBest must be >= 0!");
93 } else if (m_numBest != 0) {
94 DecayDescriptor decaydescriptor;
95 decaydescriptor.init(m_inputListName);
96
97 const DecayDescriptorParticle* ddpart = decaydescriptor.getMother();
98 const int pdgCode = ddpart->getPDGCode();
99 const string listLabel = ddpart->getLabel();
100
101 // For final state particles we protect the label "all".
102 if (Const::finalStateParticlesSet.contains(Const::ParticleType(abs(pdgCode))) and listLabel == "all") {
103 B2FATAL("You are trying to apply a best-candidate-selection on the list " << m_inputListName <<
104 " but the label 'all' is protected for lists of final-state particles." <<
105 " It could introduce *very* dangerous bugs.");
106 } else if (listLabel == "MC" or listLabel == "V0") {
107 // the labels MC and V0 are also protected
108 B2FATAL("You are trying to apply a best-candidate-selection on the list " << m_inputListName <<
109 " but the label " << listLabel << " is protected and can not be reduced.");
110 }
111
112 }
113
115
116 // parse the name that the rank will be stored under
117 if (m_outputVariableName.empty()) {
118 std::string root_compatible_VariableName = MakeROOTCompatible::makeROOTCompatible(m_variableName);
119 m_outputVariableName = root_compatible_VariableName + "_rank";
120 }
121}
122
124{
125 // input list
126 if (!m_inputList) {
127 B2WARNING("Input list " << m_inputList.getName() << " was not created?");
128 return;
129 }
130
131 if (m_numBest == 0 and m_inputList->getIsReserved())
132 m_inputList->setEditable(true);
133
134 // create list of particle index and the corresponding value of variable
135 typedef std::pair<double, unsigned int> ValueIndexPair;
136 std::vector<ValueIndexPair> valueToIndex;
137 const unsigned int numParticles = m_inputList->getListSize();
138 valueToIndex.reserve(numParticles);
139 for (const Particle& p : *m_inputList) {
140 double value = 0;
141 auto var_result = m_variable->function(&p);
142 if (std::holds_alternative<double>(var_result)) {
143 value = std::get<double>(var_result);
144 } else if (std::holds_alternative<int>(var_result)) {
145 value = std::get<int>(var_result);
146 }
147 valueToIndex.emplace_back(value, p.getArrayIndex());
148 }
149
150 // use stable sort to make sure we keep the relative order of elements with
151 // same value as it was before
152 if (m_selectLowest) {
153 std::stable_sort(valueToIndex.begin(), valueToIndex.end(), ValueIndexPairSorting::lowerPair<ValueIndexPair>);
154 } else {
155 std::stable_sort(valueToIndex.begin(), valueToIndex.end(), ValueIndexPairSorting::higherPair<ValueIndexPair>);
156 }
157
158 // assign ranks and (optionally) remove everything but best candidates
159 m_inputList->clear();
160 int rank{1};
161 double previous_val{0};
162 bool first_candidate{true};
163 for (const auto& candidate : valueToIndex) {
164 Particle* p = m_particles[candidate.second];
165 if (!m_cut->check(p)) {
166 p->addExtraInfo(m_outputVariableName, -1);
167 m_inputList->addParticle(p);
168 continue;
169 }
170 if (first_candidate) {
171 first_candidate = false;
172 } else {
173 // If allowMultiRank, only increase rank when value changes
174 if (!m_allowMultiRank || (candidate.first != previous_val)) ++rank;
175 }
176
177 if ((m_numBest != 0) and (rank > m_numBest)) // Only keep particles with same rank or below
178 break;
179
180 if (!p->hasExtraInfo(m_outputVariableName))
181 p->addExtraInfo(m_outputVariableName, rank);
182 else if (m_overwriteRank)
183 p->setExtraInfo(m_outputVariableName, rank);
184
185 m_inputList->addParticle(p);
186 previous_val = candidate.first;
187
188
189 }
190
191 if (m_numBest == 0 and m_inputList->getIsReserved())
192 m_inputList->setEditable(false);
193}
bool m_allowMultiRank
Give the same rank to candidates with the same value.
virtual void initialize() override
Initialize the module (set up datastore)
virtual void event() override
Process an event.
std::string m_variableName
Variable which defines the candidate ranking.
StoreArray< Particle > m_particles
StoreArray of Particle objects.
bool m_selectLowest
Select the candidate with the lowest value (instead of highest).
virtual ~BestCandidateSelectionModule() override
Destructor.
std::unique_ptr< Variable::Cut > m_cut
cut object which performs the cuts
StoreObjPtr< ParticleList > m_inputList
input particle list
const Variable::Manager::Var * m_variable
Variable which defines the candidate ranking.
std::string m_cutParameter
Selection for candidates to be ranked.
int m_numBest
Number of best candidates to keep.
bool m_overwriteRank
If true, the extraInfo of rank is overwritten when the particle has already the extraInfo.
std::string m_outputVariableName
Name of generated Ranking-Variable, if specified by user.
std::string m_inputListName
name of input particle list.
The ParticleType class for identifying different particle types.
Definition: Const.h:408
static const ParticleSet finalStateParticlesSet
set of final set particles that can be created by the ParticleLoader
Definition: Const.h:657
Represents a particle in the DecayDescriptor.
int getPDGCode() const
Return PDG code.
std::string getLabel() const
The label of this particle, "default" returned, when no label set.
The DecayDescriptor stores information about a decay tree or parts of a decay tree.
bool init(const std::string &str)
Initialise the DecayDescriptor from given string.
const DecayDescriptorParticle * getMother() const
return mother.
static std::unique_ptr< GeneralCut > compile(const std::string &cut)
Creates an instance of a cut and returns a unique_ptr to it, if you need a copy-able object instead y...
Definition: GeneralCut.h:84
static std::string makeROOTCompatible(std::string str)
Remove special characters that ROOT dislikes in branch names, e.g.
void setDescription(const std::string &description)
Sets the description of the module.
Definition: Module.cc:214
void setPropertyFlags(unsigned int propertyFlags)
Sets the flags for the module properties.
Definition: Module.cc:208
@ c_ParallelProcessingCertified
This module can be run in parallel processing mode safely (All I/O must be done through the data stor...
Definition: Module.h:80
Class to store reconstructed particles.
Definition: Particle.h:75
bool isRequired(const std::string &name="")
Ensure this array/object has been registered previously.
const Var * getVariable(std::string name)
Get the variable belonging to the given key.
Definition: Manager.cc:57
static Manager & Instance()
get singleton instance.
Definition: Manager.cc:25
void addParam(const std::string &name, T &paramVariable, const std::string &description, const T &defaultValue)
Adds a new parameter to the module.
Definition: Module.h:560
#define REG_MODULE(moduleName)
Register the given module (without 'Module' suffix) with the framework.
Definition: Module.h:650
Abstract base class for different kinds of events.
Definition: ClusterUtils.h:24
STL namespace.
VariableDataType variabletype
data type of variable
Definition: Manager.h:133
FunctionPtr function
Pointer to function.
Definition: Manager.h:147