Merge pull request #222 from saganatt/event-mixing

Update event mixing documentation with slice cache and lambda binning

Author: ddobrigk

docs/advanced-specifics/eventMixing.md

@@ -17,23 +17,23 @@ o2::soa::combinations (CombinationIndexPolicy(tracks1, tracks2, ...))
 
 which returns tuples of tracks (one track from each table of tracks).
 
-There are several *CombinationIndexPolicies* available which are explained [here](../framework/framework.md#getting-combinations-pairs-triplets-). It is recommended that you will get first well acquainted with combinations before moving on to mixing.
+There are several *CombinationIndexPolicies* available which are explained [here](../basics-tasks/CombiningData.md). It is recommended that you will get first well acquainted with combinations before moving on to mixing.
 
-## Event mixing
+## Mixing generator
 
 `GroupedCombinationsGenerator` which generates mixed event pairs is a generalization of block combination policies. Therefore, it accepts the same parameters:
 
 - binning policy
 - outsider
 - category neighbours (equivalent to the number of other collisions to mix with)
 
-You can consult a detailed description of these parameters in the [block combinations section](../framework/framework.md#block--binned-combination-policies).
+You can consult a detailed description of these parameters in the [block combinations section](../basics-tasks/CombiningData.md#block--binned-combination-policies).
 
 The `GroupedCombinationsGenerator` general constructor is defined as:
 
 ```cpp
 template <typename T1, typename GroupingPolicy, typename BP, typename G, typename... As>
-GroupedCombinationsGenerator(const BP& binningPolicy, int catNeighbours, const T1& outsider, G& grouping, std::tuple<T2s...>& associated)
+GroupedCombinationsGenerator(const BP& binningPolicy, int catNeighbours, const T1& outsider, G& grouping, std::tuple<T2s...>& associated, SliceCache* cache)
 ```
 
 This is a more general functionality which potentially could be used for other applications beyond event mixing. However, to simplify this tutorial, let's assume our `grouping` table is the table of collisions, and the `associated` are tables of structures like tracks and V0s.
@@ -43,7 +43,8 @@ This is a more general functionality which potentially could be used for other a
 - `T1`: type of an outsider value as well as the value itself as a parameter,
 - `GroupingPolicy`: type of a *BlockCombinationIndexPolicies* which specifies how collision pairs will be generated (strictly upper, upper or full block combinations)i,
 - `BP`: type of a binning policy applied to the block combinations of collisions as well as the policy instance,
-- input grouping (collisions) and associated (tracks, V0s) tables and their types.
+- input grouping (collisions) and associated (tracks, V0s) tables and their types
+- a pointer to the `SliceCache` which is used implicitly for efficient slicing of associated tables
 
 To simplify the code, there are helper shortcuts defined for the most common use cases:
 

docs/tutorials/eventMixing.md

@@ -14,13 +14,14 @@ Obtain mixed event tuples.
   Executable: o2-analysistutorial-event-mixing
 </div>
 
-For a general introduction to combinations and event mixing, check first [here](../framework/eventMixing.md).
+For a general introduction to combinations and event mixing, check first [here](../advanced-specifics/eventMixing.md).
 
-### MixedEvents
+## MixedEvents
 
-Firstly, we define binning of collisions for block combinations:
+Firstly, we define slice cache and binning of collisions for block combinations:
 
 ```cpp
+SliceCache cache;
 std::vector<double> xBins{VARIABLE_WIDTH, -0.064, -0.062, -0.060, 0.066, 0.068, 0.070, 0.072};
 std::vector<double> yBins{VARIABLE_WIDTH, -0.320, -0.301, -0.300, 0.330, 0.340, 0.350, 0.360};
 using BinningType = BinningPolicy<aod::collision::PosX, aod::collision::PosY>;
@@ -32,7 +33,7 @@ BinningType binningOnPositions{{xBins, yBins}, true};
 Then, we define the mixing structure itself:
 
 ```cpp
-SameKindPair<aod::Collisions, aod::Tracks, BinningType> pair{binningOnPositions, 5, -1}; // indicates that 5 events should be mixed and under/overflow (-1) to be ignored
+SameKindPair<aod::Collisions, aod::Tracks, BinningType> pair{binningOnPositions, 5, -1, &cache}; // indicates that 5 events should be mixed and under/overflow (-1) to be ignored
 ```
 
 In this case, only table types and the binning police type need to be passed, as the rest is taken from the defaults.
@@ -53,15 +54,15 @@ for (auto& [t1, t2] : combinations(CombinationsFullIndexPolicy(tracks1, tracks2)
 }
 ```
 
-### MixedEventsInsideProcess
+## MixedEventsInsideProcess
 
 This is the same task as above, with the difference that binning policy and `SameKindPair` are declared inside `process()`. This is particularly helpful when your bins are ConfigurableAxes. The standard out-of-process declaration of binning policy and corresponding mixing structure would take only default configurable values.
 
-### Task with different table structures
+## Tasks with different table structures
 
 These tasks demonstrate how mixing works with Filtered and Join.
 
-### MixedEventsDynamicColumns
+## MixedEventsDynamicColumns
 
 This is a more realistic example with mixing of collisions binned by z-vertex and multiplicity V0M. As `MultFV0M` is a dynamic column, its type is templated on the contributing column types. Therefore, the binning policy type is:
 
@@ -71,15 +72,15 @@ using BinningType = BinningPolicy<aod::collision::PosZ, aod::mult::MultFV0M<aod:
 
 The rest of the task is the same as in the basic example.
 
-### Tasks with different table kinds
+## Tasks with different table kinds
 
 These tasks demonstrate usage of `Pair`, `Triple` and `SameKindTriple` on tracks and V0s.
 
-### MixedEventsWithHashTask
+## MixedEventsWithHashTask
 
 This task shows how one can use `NoBinningPolicy` in case of bins predefined somewhere else.
 
-### MixedEventsPartitionedTracks
+## MixedEventsPartitionedTracks
 
 This is a bit more advanced example which shows how one can further partition the tracks from mixing. As the tracks tables are produced only at the generation of each mixed collision pair, `Partitions` must be declared inside the mixing loop. Additionally, each partition must be bound to a respective table -- `tracks1` or `tracks2`. Then, the corresponding partitioning condition is applied to the selected table.
 
@@ -95,3 +96,35 @@ for (auto& [c1, tracks1, c2, tracks2] : pair) {
   rightPhi2.bindTable(tracks2);
 }
 ```
+
+## MixedEventsLambdaBinning
+
+The task demonstrates how to use FlexibleBinningPolicy if binning cannot be calculated straight from the collision columns, but is obtained from other variables in a user-defined function.<br>
+This is naturally implemented for mixing inside `process()`, as the helper lambda function is usually defined inside `process()`. For example:
+
+```cpp
+void process(aod::Collisions& collisions, aod::Tracks& tracks) {
+  auto getTracksSize =
+    [&tracks, this](aod::Collision const& col) {
+      auto associatedTracks = tracks.sliceByCached(o2::aod::track::collisionId, col.globalIndex(), this->cache); // it's cached, so slicing/grouping happens only once
+      return associatedTracks.size();
+    };
+```
+
+The binning policy:
+
+```cpp
+using BinningType = FlexibleBinningPolicy<std::tuple<decltype(getTracksSize)>, aod::collision::PosZ, decltype(getTracksSize)>;
+BinningType binningWithLambda{{getTracksSize}, {axisVertex, axisMultiplicity}, true};
+```
+
+A tuple with types of all lambda functions must be first passed in the `BinningType` definition, before the rest of arguments follow in the order of usage.<br>
+Similarly, in `binningWithLambda` definition, one must first pass a tuple with all lambda functions before other arguments.<br>
+Note that binning with respect to z-vertex is calculated from column values as before, while the lambda is used only for the multiplicity axis. You must be careful to follow the same order of columns/lambdas in the `BinningType` definition and of the corresponding axes in binning instantation.
+Any combination of lambda- and column-based binning is possible.
+
+Finally, the mixing structure is defined like in previous examples:
+
+```cpp
+SameKindPair<aod::Collisions, aod::Tracks, BinningType> pair{binningWithLambda, 5, -1, collisions, tracksTuple, &cache};
+```