From c5a37dd0ab4b3c2db8c8595fdcc3f9fcf3a554cf Mon Sep 17 00:00:00 2001
From: haddadanas <hhhaaanas@gmail.com>
Date: Wed, 13 Nov 2024 17:33:29 +0100
Subject: [PATCH] added documentation for this :)

---
 docs/user_guide/plotting.md | 61 +++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/docs/user_guide/plotting.md b/docs/user_guide/plotting.md
index 498b0d7c5..4926f8623 100644
--- a/docs/user_guide/plotting.md
+++ b/docs/user_guide/plotting.md
@@ -363,3 +363,64 @@ An example on how to implement such a plotting function is shown in the followin
 :start-at: def my_plot1d_func(
 :end-at: return fig, (ax,)
 ```
+
+## Applying a selection to a variable
+
+In some cases, you might want to apply a selection to a variable before plotting it.
+Instead of creating a new column with the selection applied, columnflow provides the possibility to apply a selection to a variable directly when histograming it.
+For this purpose, the ```selection``` parameter can be added in the variable definition in the config.
+This may look as follows:
+
+```python
+
+config.add_variable(
+    name="jet_pt",
+    expression="Jet.pt",
+    binning=(50, 0, 300.0),
+    selection="Jet.mass > 30.0",  # Select only jets with a mass larger than 30 GeV
+    null_value=EMPTY_FLOAT,  # Set the value of the variable to EMPTY_FLOAT if the selection is not passed
+    unit="GeV",
+    x_title=r"all Jet $p_{T}$",
+)
+
+```
+
+It is important to provide the ```null_value``` parameter, when using the ```selection``` parameter, as the variable will be set to this value if the selection is not passed.
+The ```selection``` parameter can take either strings (useful for simple selections) or functions / lambda expressions (useful for more complex selections).
+
+:::{dropdown} Format and limitation of the string selection
+The string selection takes values in the pattern of ```column name / route``` ```operator``` ```value```.
+The ```operator``` can be any of the following numerical operators: ```==```, ```!=```, ```<```, ```<=```, ```>```, ```>=```.
+The used ```column name``` is dynamically added to the required routes of the workflow.
+Multiple selections can be combined with the logical operators ```&``` (and) such as ```(Jet.pt > 30.0) & (Jet.mass < 50.0)``` and all required routes will be automatically added to the workflow.
+```|``` (or) logical operators are not supported yet.
+
+This is very convienient for simple selections, but arrives at its limits when more complex operation (e.g. ```abs```, addition, subtraction etc.) are required.
+In that case, you can use a lambda expression or a function to define the selection.
+:::
+
+:::{dropdown} Using a lambda expression or a function for the selection
+When using a lambda expression or a function, the selection can take a more complex form and there is no theoretical limit to the complexity of the selection.
+The function's signature needs to match ```def my_selection(events: ak.Array) -> ak.Array[bool]``` where
+the variable array is passed to the function and the returned value is a boolean array of the same length as the input array.
+
+The used columns in the selection function are not automatically added to the required routes of the workflow.
+For this reason, it is necessary to add the columns used in the selection function to variable instance auxiliary.
+An examble on how to do this is given in the following:
+
+```python
+
+config.add_variable(
+    name="jet_pt",
+    expression="Jet.pt",
+    binning=(50, 0, 300.0),
+    selection=(lambda events: abs(events.Jet.eta) ** 2 + abs(events.Jet.phi) ** 2 < 0.4),
+    null_value=EMPTY_FLOAT,
+    unit="GeV",
+    x_title=r"all Jet $p_{T}$",
+    aux={"inputs": ["Jet.eta", "Jet.phi"]},
+)
+
+```
+
+:::