SelectSubset< StoredClass > Class Template Reference

Class to create a subset of a given StoreArray together with the relations with other StoreArrays. More...

#include <SelectSubset.h>

Inheritance diagram for SelectSubset< StoredClass >:

Public Member Functions
	SelectSubset ()
	Constructor.
	~SelectSubset ()
	Destructor.
void	registerSubset (const StoreArray< StoredClass > &set, DataStore::EStoreFlags storeFlags=DataStore::c_ErrorIfAlreadyRegistered)
	Remove all non-selected objects from set.
void	registerSubset (const StoreArray< StoredClass > &set, const std::string &subsetName, DataStore::EStoreFlags storeFlags=DataStore::c_ErrorIfAlreadyRegistered)
	Register the StoreArray<StoredClass> that will contain the subset of selected elements.
template<class T , class ... MoreArguments>
void	inheritRelationsFrom (const StoreArray< T > &array, MoreArguments... moreArgs)
	Inherit relations pointing from Other to objects selected into this subset.
template<class T , class ... MoreArguments>
void	inheritRelationsTo (const StoreArray< T > &array, MoreArguments... moreArgs)
	Inherit relations pointing from objects selected into this subset to Other.
void	inheritAllRelations ()
	Automatically inherit all relations to or from the original set (if registered when calling this function).
void	select (const std::function< bool(const StoredClass *)> &f)
	This method is the actual worker.
StoreAccessorBase *	getSet () override
	Get accessor for original set.
StoreAccessorBase *	getSubSet () override
	Get accessor for reduced set.
std::vector< std::string >	getInheritFromArrays () const
	Get list of arrays we inherit relations from.
std::vector< std::string >	getInheritToArrays () const
	Get list of arrays we inherit relations to.
bool	getInheritToSelf () const
	Do we inherit relations from original set to itself?
void	swapSetsAndDestroyOriginal ()
	Swap set and subset (+relations), and keep only the reduced set.

Protected Member Functions
std::map< int, int >	copySetWithRelations (std::function< bool(const StoredClass *)> f)
	Selects the elements, fill the subset and copies all the relations in which the set is involved.
void	copyRelationsToSelf ()
	Copy any set -> set relations between selected objects.
void	inheritRelationsFrom ()
	Empty method to stop the recursion of the variadic template.
void	inheritRelationsTo ()
	Empty method to stop the recursion of the variadic template.

Protected Attributes
StoreArray< StoredClass > *	m_set = nullptr
	The array we use as input.
StoreArray< StoredClass > *	m_subset = nullptr
	The array we create.
DataStore::EStoreFlags	m_subsetFlags = DataStore::c_WriteOut
	Flags used for m_subset.
std::vector< std::string >	m_inheritFromArrays
	array names we inherit relations from.
std::vector< std::string >	m_inheritToArrays
	array names we inherit relations to.
bool	m_inheritToSelf = false
	If true, relations from set objects to set objects are copied.
bool	m_reduceExistingSet = false
	If true, non-selected candidates are removed from m_set, m_subset only exists temporarily.

Detailed Description

template<typename StoredClass>
class Belle2::SelectSubset< StoredClass >

Class to create a subset of a given StoreArray together with the relations with other StoreArrays.

The class SelectSubset selects a subset of objects contained in a given StoreArray creating at the same time a set of relations with objects contained in other StoreArrays that are the natural restrictions on the subset of the relations "from" or "to" the original one.

Creating a subset

Assuming you have a StoreArray called 'particles' that contains objects of type Particle you can use SelectSubset to select particles with a given feature and put them in another StoreArray called, as an example,'oddParticles'.

Instantiation

First you need to add a SelectSubset to your module as a member variable:

SelectSubset< Particle > m_selector;

Initialization

In the initialize method of your module you have to initialize the SelectSubset

StoreArray< Particle > set( "particles" );
set.isRequired(); // or isOptional(). The choice is up to you.
m_selector.registerSubset( set, "oddParticles");

The SelectSubset class will take care of creating the new StoreArray<Particle>, register it into the datastore with name "oddParticles" same durability and same persistent attributes of the original one.

Inheritance of relations can also be configured here, see "Relations" section below.

Selection

To create the subset you have to specify the selection criterium. You can do that in two possible ways.

via C++ function

You can define your C++ function and then use it. E.g:

bool
MySelectionFunction( const Particle * particle){
// this function tells if the particle is odd
return ( particle->UniqueId() % 2 ) == 1 ;
}

Then in the event method of your module:

m_selector.select( MySelectionFunction );

via C++ lambda function

You can specify a lambda expression as parameter of the select method. E.g.: in the event method of your code:

m_selector.select( []( const Particle * particle )
{ return  ( particle->UniqueId() % 2 ) == 1 ; } );

with the advantage of an easy capture of module parameters. E.g. to count the number of rejected particles:

int rejected(0);
m_selector.select( [& rejected]( const Particle * particle )
{
  if ( ( particle->UniqueId() % 2 ) == 1 )
    return true;
  rejected ++;
  return false;
});
B2INFO("The selector rejected " << rejected << " particles." );

Relations

By default the class SelectSubset produces a one to one relation from the set to the subset by which you can interpret all the relations from and to the original set. E.g. The original StoreArray<Particle> is in relation To the StoreArray<MCParticle>. You can use the relation from the set to the subset and then from the set to the MCParticles. This can be quite tedious, so you can ask SelectSubset to produce the natural restrictions of the relations from and to the original set.

Automatic inheritance

If you want your subset to have the same relations as for the original set, you can simply use

m_selector.inheritAllRelations();

Manually specifying relations to inherit

Alternatively, you can specify the arrays you want to inherit from/to manually:

Relations to other StoreArrays

Assuming there is a relation from your original set to other arrays A and B, you can inherit these relations for all objects selected into your subset using:

StoreArray<A> a;
StoreArray<B> b;
m_selector.inheritRelationsTo(a, b);
 
//alternatively, you can also use multiple calls to the function
m_selector.inheritRelationsTo(a);
m_selector.inheritRelationsTo(b);

Relations from other StoreArrays

Relations pointing from objects in other arrays to objects in the original set can also be inherited in a very similar way:

StoreArray<C> c;
StoreArray<D> d;
m_selector.inheritRelationsFrom(c, d);
 
//alternatively, you can also use multiple calls to the function
m_selector.inheritRelationsFrom(c);
m_selector.inheritRelationsFrom(d);

Relations from the StoreArray to itself

If there are relations from objects in the original set to other objects in the same array (e.g. Particles -> Particles), you can also inherit these by doing

m_selector.inheritRelationsFrom(set);
// or:
// m_selector.inheritRelationsTo(set);

Note that both objects related must pass the selection criteria, or there would be one missing partner in the relation.

Definition at line 193 of file SelectSubset.h.

Constructor & Destructor Documentation

SelectSubset()

SelectSubset ( )

inline

Constructor.

Definition at line 198 of file SelectSubset.h.

: SelectSubsetBase() {};

~SelectSubset()

~SelectSubset ( )

inline

Destructor.

Definition at line 201 of file SelectSubset.h.

    {
      delete m_set;
      delete m_subset;
    }

Member Function Documentation

getInheritFromArrays()

std::vector< std::string > getInheritFromArrays ( ) const

inlineinherited

Get list of arrays we inherit relations from.

Definition at line 32 of file SelectSubset.h.

{ return m_inheritFromArrays; }

getInheritToArrays()

std::vector< std::string > getInheritToArrays ( ) const

inlineinherited

Get list of arrays we inherit relations to.

Definition at line 34 of file SelectSubset.h.

{ return m_inheritToArrays; }

getInheritToSelf()

bool getInheritToSelf ( ) const

inlineinherited

Do we inherit relations from original set to itself?

Definition at line 36 of file SelectSubset.h.

{ return m_inheritToSelf; }

getSet()

StoreAccessorBase * getSet ( )

inlineoverridevirtual

Get accessor for original set.

Implements SelectSubsetBase.

Definition at line 325 of file SelectSubset.h.

{ return m_set; }

getSubSet()

StoreAccessorBase * getSubSet ( )

inlineoverridevirtual

Get accessor for reduced set.

Implements SelectSubsetBase.

Definition at line 327 of file SelectSubset.h.

{ return m_subset; }

inheritAllRelations()

void inheritAllRelations ( )

inline

Automatically inherit all relations to or from the original set (if registered when calling this function).

Equivalent to calling inheritRelationsFrom()/To() for all related arrays.

Note: Do not combine with inheritRelationsFrom() and inheritRelationsTo().

Definition at line 301 of file SelectSubset.h.

    {
      auto arrays = DataStore::Instance().getListOfRelatedArrays(*m_set);
 
      for (std::string arrayName : arrays) {
        StoreArray<TObject> array(arrayName, m_set->getDurability());
        if (array == *m_subset)
          continue; // from registerSubset(), ignore
 
        if (array.optionalRelationTo(*m_set, m_set->getDurability()))
          inheritRelationsFrom(array);
        if (m_set->optionalRelationTo(array, m_set->getDurability()))
          inheritRelationsTo(array);
      }
    }

inheritRelationsFrom() [1/2]

void inheritRelationsFrom ( )

inlineprotected

Empty method to stop the recursion of the variadic template.

Definition at line 337 of file SelectSubset.h.

{ }

inheritRelationsFrom() [2/2]

void inheritRelationsFrom ( const StoreArray< T > &  array, MoreArguments...  moreArgs  )

inline

Inherit relations pointing from Other to objects selected into this subset.

You can specify an unlimited number of arrays as arguments to this function.

Definition at line 250 of file SelectSubset.h.

    {
      if (array.getName() == m_set->getName()) {
        m_inheritToSelf = true;
        inheritRelationsFrom(*m_subset, moreArgs...);
      } else {
        const_cast<StoreArray<T>&>(array).isRequired();
 
        DataStore::EStoreFlags flags = m_subsetFlags;
        if (m_subset->notWrittenOut() or array.notWrittenOut())
          flags |= DataStore::c_DontWriteOut;
        array.registerRelationTo(*m_subset, m_subset->getDurability(), flags);
 
        if (array.getName() != m_subset->getName())
          m_inheritFromArrays.push_back(array.getName());
 
        inheritRelationsFrom(moreArgs ...);
      }
    }

inheritRelationsTo() [1/2]

void inheritRelationsTo ( )

inlineprotected

Empty method to stop the recursion of the variadic template.

Definition at line 339 of file SelectSubset.h.

{ }

inheritRelationsTo() [2/2]

void inheritRelationsTo ( const StoreArray< T > &  array, MoreArguments...  moreArgs  )

inline

Inherit relations pointing from objects selected into this subset to Other.

You can specify an unlimited number of arrays as arguments to this function.

Definition at line 275 of file SelectSubset.h.

    {
      if (array.getName() == m_set->getName()) {
        m_inheritToSelf = true;
        inheritRelationsTo(*m_subset, moreArgs...);
      } else {
        const_cast<StoreArray<T>&>(array).isRequired();
 
        DataStore::EStoreFlags flags = m_subsetFlags;
        if (m_subset->notWrittenOut() or array.notWrittenOut())
          flags |= DataStore::c_DontWriteOut;
        m_subset->registerRelationTo(array, m_subset->getDurability(), flags);
 
        if (array.getName() != m_subset->getName())
          m_inheritToArrays.push_back(array.getName());
 
        inheritRelationsTo(moreArgs ...);
      }
    }

registerSubset() [1/2]

void registerSubset ( const StoreArray< StoredClass > &  set, const std::string &  subsetName, DataStore::EStoreFlags  storeFlags = DataStore::c_ErrorIfAlreadyRegistered  )

inline

Register the StoreArray<StoredClass> that will contain the subset of selected elements.

Parameters

set	The StoreArray<StoredClass> from which the elements will be selected
subsetName	The name of the StoreArray<StoredClass> that will contain the selected elements
storeFlags	ORed combination of DataStore::EStoreFlags.

Definition at line 229 of file SelectSubset.h.

    {
      if (m_set or m_subset) {
        B2FATAL("SelectSubset::registerSubset() can only be called once!");
      }
 
      m_set = new StoreArray<StoredClass>(set);
 
      m_subset = new StoreArray<StoredClass>(subsetName, m_set->getDurability());
      m_subset->registerInDataStore(storeFlags);
      m_subsetFlags = storeFlags;
 
      set.registerRelationTo(*m_subset, m_subset->getDurability(), storeFlags);
    }

registerSubset() [2/2]

void registerSubset ( const StoreArray< StoredClass > &  set, DataStore::EStoreFlags  storeFlags = DataStore::c_ErrorIfAlreadyRegistered  )

inline

Remove all non-selected objects from set.

All relations registered so far are retained. TODO: consider moving this into StoreArray itself

Parameters

set	The StoreArray<StoredClass> from which to retain only selected elements
storeFlags	flags used for temporary arrays and relations. Should be changed from the default if you want multiple instances. c_DontWriteOut is always used.

Definition at line 215 of file SelectSubset.h.

    {
      m_reduceExistingSet = true;
      registerSubset(set, set.getName() + "_tmpSubset", storeFlags | DataStore::c_DontWriteOut);
 
      inheritAllRelations();
    }

swapSetsAndDestroyOriginal()

void swapSetsAndDestroyOriginal ( )

inherited

Swap set and subset (+relations), and keep only the reduced set.

Subset and associated relations will be empty afterwards.

Definition at line 14 of file SelectSubset.cc.

{
  StoreAccessorBase* set = getSet();
  StoreAccessorBase* subset = getSubSet();
 
  //replace set with subset
  DataStore::Instance().replaceData(*subset, *set);
 
  //swap relations
  for (const std::string& fromArray : m_inheritFromArrays) {
    RelationArray setRel(DataStore::relationName(fromArray, set->getName()));
    RelationArray subsetRel(DataStore::relationName(fromArray, subset->getName()));
    DataStore::Instance().replaceData(subsetRel, setRel);
  }
  for (const std::string& toArray : m_inheritToArrays) {
    RelationArray setRel(DataStore::relationName(set->getName(), toArray));
    RelationArray subsetRel(DataStore::relationName(subset->getName(), toArray));
    DataStore::Instance().replaceData(subsetRel, setRel);
  }
}

Member Data Documentation

m_inheritFromArrays

std::vector<std::string> m_inheritFromArrays

protectedinherited

array names we inherit relations from.

Definition at line 54 of file SelectSubset.h.

m_inheritToArrays

std::vector<std::string> m_inheritToArrays

protectedinherited

array names we inherit relations to.

Definition at line 56 of file SelectSubset.h.

m_inheritToSelf

bool m_inheritToSelf = false

protectedinherited

If true, relations from set objects to set objects are copied.

(if both objects are selected!).

Definition at line 58 of file SelectSubset.h.

m_reduceExistingSet

bool m_reduceExistingSet = false

protectedinherited

If true, non-selected candidates are removed from m_set, m_subset only exists temporarily.

Definition at line 60 of file SelectSubset.h.

m_set

StoreArray<StoredClass>* m_set = nullptr

protected

The array we use as input.

Definition at line 342 of file SelectSubset.h.

m_subset

StoreArray<StoredClass>* m_subset = nullptr

protected

The array we create.

Definition at line 344 of file SelectSubset.h.

m_subsetFlags

DataStore::EStoreFlags m_subsetFlags = DataStore::c_WriteOut

protected

Flags used for m_subset.

Definition at line 346 of file SelectSubset.h.

---

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

• framework/datastore/include/SelectSubset.h