diff --git a/docs/sphinx_source/build_root.rst b/docs/sphinx_source/build_root.rst index 3fca6031..66e0ee1a 100644 --- a/docs/sphinx_source/build_root.rst +++ b/docs/sphinx_source/build_root.rst @@ -1,11 +1,11 @@ How to build ROOT with CVMFS on CentOS 7 ========================================= -For profiling with debug symbols or just to test the newest ROOT features, you may want to use your own ROOT version. Here are the commands, which allow you to build ROOT with a given build type, ROOT release tag and C++ 17. +For profiling with debug symbols or just to test the latest ROOT features, you may want to use your own ROOT version. Here are the commands that allow you to build ROOT with a given build type, ROOT release tag and C++ 17. -Most likely, you want to use :code:`RelWithDebInfo` as build type so you get debug symbols but also a realistic performance due to compiler optimizations. +Most likely, you want to use :code:`RelWithDebInfo` as build type. This provides debug symbols while maintaining a realistic performance due to compiler optimizations. -To look up the release tags, go to https://github.com/root-project/root and see the tags (not the branches!). +To look up the release tags, visit https://github.com/root-project/root and check the tags (not the branches!). .. code-block:: console diff --git a/docs/sphinx_source/changelog.rst b/docs/sphinx_source/changelog.rst index e50f7aef..66456c68 100644 --- a/docs/sphinx_source/changelog.rst +++ b/docs/sphinx_source/changelog.rst @@ -4,20 +4,20 @@ Changelog May 2024 - Version 0.4.0 * Switch to ROOT 6.30, supporting now RHEL8 and RHEL9. -* Introduced support for ML inference via `OnnxRuntime`. A generic producer is avialable at this link: https://github.com/KIT-CMS/CROWN/blob/main/include/ml.hxx -* Introduced a CorrectionManager, that is responsible for loading correction files and sharing them among the different producers. This allows to load the corrections only once and share them among the different producers, resulting in a signifiant speedup of the initial loading time. In the course of this implementation, Many functions now have a deprecated version, that does not use the `CorrectionManager`. The old functions will be removed in the next release. A more detailed description can be found in the :ref:`The Correction Manager` page. +* Introduced support for ML inference via `OnnxRuntime`. A generic producer is available at this link: https://github.com/KIT-CMS/CROWN/blob/main/include/ml.hxx +* Introduced a CorrectionManager that is responsible for loading correction files and sharing them across producers. This allows to load the corrections only once and share them among the different producers, resulting in a significant speedup of the initial loading time. As part of this implementation, many functions now have a deprecated version, that does not use the `CorrectionManager`. The old functions will be removed in the next major release. A more detailed description can be found on :ref:`The Correction Manager` page. Sept. 2023 - Version 0.3.0 * Switched to ROOT 6.28 via LCG 104, resulting in about 20% faster processing times. -* Added support for the generation of friend trees with additional friends as input. For more details, check :ref:`FriendTree Generation`. -* Added option to compile the CROWNlib only, allowing to reuse the same libary for multiple CROWN executables. +* Added support for generating friend trees with additional input friends.. For more details, check :ref:`FriendTree Generation`. +* Added option to compile the CROWNlib only, allowing to reuse the same library for multiple CROWN executables. Feb. 2023 * Added support for the generation of friend trees. For more details, check :ref:`FriendTree Generation`. -* Added documentation on ntuple and friend production via KingMaker. For more details, check :ref:`KingMaker`. +* Added documentation on Ntuple and friend production via KingMaker. For more details, check :ref:`Workflow Management`. Jan. 2023 -* Added Quantities <-> Shifts mapping to the output files to allow an easier Postprocessing. For more details, check :ref:`Quantity mapping`. +* Added Quantities <-> Shifts mapping to the output files to allow easier postprocessing. For more details, check :ref:`Quantity mapping`. diff --git a/docs/sphinx_source/contrib.rst b/docs/sphinx_source/contrib.rst index ed6c242f..7f0f0d1d 100644 --- a/docs/sphinx_source/contrib.rst +++ b/docs/sphinx_source/contrib.rst @@ -1,18 +1,18 @@ Writing a new producer ======================= -Writing a new producer requires two main parts, adding the :ref:`C++ function` and the required :ref:`python part`. +Writing a new producer involves two main parts, adding the :ref:`C++ function` and the required :ref:`python component`. -If the C++ function is written generally enough, it can be used in multiple producers and multiple purposes in the end. +If the C++ function is written generically enough, it can be used in multiple producers and multiple purposes in the end. For example, the producer generating the pt_1 quantity can be used regardless of what particle is being considered. -In the following, an introduction on how to add a new producer is given. As an example, we will add a new producer, which can be used to calculate the Lorentz vectors of particles, in our case electrons. For simplicity, we only want to calculate one single Lorentz vector for a given index. First, we will do the C++ implementation of the function followed by the Python definition. Keep in mind, that those two parts are connected. +In the following, an introduction to adding a new producer is given. As an example, we will add a new producer, which can be used to calculate the Lorentz vectors of particles, in our case electrons. For simplicity, we only want to calculate one single Lorentz vector for a given index. First, we will do the C++ implementation of the function followed by the Python definition. Keep in mind, that those two parts are connected. Writing a new C++ function ============================ -For a new C++ function, a definition in the header file, and the implementation in the source file are required. As good practice, we will add the function to a namespace called ``lorentzvector``, and call the function ``build``. -The return type of any function in CROWN should always be ``ROOT::RDF::RNode`` and the first argument of the function should always be the RDataframe, where we want to Define our new quantity. This means the basic definition of the function should look like this: +For a new C++ function, both a definition in the header file and the implementation in the source file are required. As good practice, we will add the function to a namespace called ``lorentzvector``, and call the function ``build``. +The return type of any function in CROWN should always be ``ROOT::RDF::RNode``, and the first argument of the function should always be the RDataframe, where we want to Define our new quantity. This means the basic definition of the function should look like this: .. code-block:: cpp diff --git a/docs/sphinx_source/correction_manager.rst b/docs/sphinx_source/correction_manager.rst index d70034df..2a31b491 100644 --- a/docs/sphinx_source/correction_manager.rst +++ b/docs/sphinx_source/correction_manager.rst @@ -13,7 +13,7 @@ For now, the CorrectionManager supports the following correction files: - correctionlib files of type ``correction::CompoundCorrection`` using the :cpp:func:`correctionManager::CorrectionManager::loadCompoundCorrection` function - json files using the :cpp:func:`correctionManager::CorrectionManager::loadjson` function -A Documentation of all Correction Manager functions can be found in :ref:`Namespace:Correctionmanager` +A Documentation of all Correction Manager functions can be found in :ref:`Namespace: Correctionmanager` Required Changes ****************** diff --git a/docs/sphinx_source/friend_trees.rst b/docs/sphinx_source/friend_trees.rst index 9e38c3f6..948788d0 100644 --- a/docs/sphinx_source/friend_trees.rst +++ b/docs/sphinx_source/friend_trees.rst @@ -1,21 +1,21 @@ FriendTree Generation =========================== -CROWN can be used, to generate FriendTrees based on a CROWN ntuple. The concept of FriendTrees is explained here: https://root.cern/manual/trees/#widening-a-ttree-through-friends. They allow to extend an existing ntuple with new quantities. Common use cases are new high-level variables like neural network outputs or additional correction factors. +CROWN can be used, to generate FriendTrees based on a CROWN Ntuple. The concept of FriendTrees is explained here: https://root.cern/manual/trees/#widening-a-ttree-through-friends. They allow to extend an existing ntuple with new quantities. Common use cases are new high-level variables like neural network outputs or additional correction factors. .. image:: ../images/root_friends.png :width: 900 :align: center :alt: Sketch of how Friend trees work -The the example depicted above, two additional friends to the main NTuple are created. During analysis, the quantities stored in the friend trees can be added by using the ``AddFriend`` method. The quantities are then available in the TTree as if they were part of the original NTuple. +In the example depicted above, two additional friends to the main NTuple are created. During analysis, the quantities stored in the friend trees can be added by using the ``AddFriend`` method. The quantities are then available in the TTree as if they were part of the original NTuple. A FriendTree is generated using a FriendTreeConfiguration. Such a configuration has some major differences, compared to a regular configuration: -1. The input file is a CROWN ntuple, not a ROOT file. +1. The input file is a CROWN Ntuple, not a ROOT file. 2. Only one scope per user is allowed. 3. No global scope is required -4. The available inputs have to be specified. The available inputs can be provided by using a CROWN ntuple as input, or a JSON file. The ntuple can be used for debugging proposes, when running a production, it is recommended to use a JSON file. The basic structure of this quantities map is listed below. Such a JSON can then be used for multiple eras, sample types and scopes. +4. The available inputs must be specified. The available inputs can be provided by using a CROWN Ntuple as input, or a JSON file. The Ntuple can be used for debugging purposes, when running a production. It is recommended to use a JSON file. The basic structure of this quantities map is listed below. Such a JSON can then be used for multiple eras, sample types and scopes. .. code-block:: JSON @@ -43,28 +43,28 @@ A FriendTree is generated using a FriendTreeConfiguration. Such a configuration -The recommended way of producing FriendTrees is to use a workflow tool, that manages the submission of jobs, generation of tarballs and organizing the output. One possible workflow tool choice is KingMaker (https://github.com/KIT-CMS/KingMaker). A more detailed description of the KingMaker workflow can be found in :ref:`KingMaker`. +The recommended way of producing FriendTrees is to use a workflow tool, that manages the submission of jobs, generation of tarballs and organizing the output. One possible workflow tool choice is KingMaker (https://github.com/KIT-CMS/KingMaker). A more detailed description of the KingMaker workflow can be found in :ref:`Workflow Management`. Writing a FriendTreeConfiguration --------------------------------- -The basic structure of a FriendTreeConfiguration is identical to a regular configuration. When creating a new FriendTree executable, an additional argument has to be provided: +The basic structure of a FriendTreeConfiguration is identical to a regular configuration. When creating a new FriendTree executable, you must provide an additional argument: -* ``DQUANTITIESMAP`` - The path to the quantities map JSON file or the crown ntuple root file. +* ``DQUANTITIESMAP`` - The path to the quantities map JSON file or the crown Ntuple ROOT file. -All other parameters are identical to the regular configuration. Setting up producers, outputs and new systematic shifts works the same way as before. The configuration has to be of type ``FriendTreeConfiguration``. During the configuration, the available inputs are checked for consistency, to catch any possible misconfiguration early. In addition, as for CROWN ntuples, only required shifts are executed. +All other parameters are identical to the regular configuration. Setting up producers, outputs and new systematic shifts works the same way as before. The configuration must be of type ``FriendTreeConfiguration``. During the configuration, the available inputs are checked for consistency, to catch any possible misconfiguration early. In addition, as for CROWN Ntuples, only required shifts are executed. FriendTrees with multiple input friend trees -------------------------------------------- -Starting from version 0.3 of CROWN, it is also possible to use multiple input friend trees. A typical use case for this feature is the evaluation of Classifiers, and storing the output of the classifier in the friend tree. This way, the classifier can utilize quantities from both the main ntuple and from additional friend trees. The interface for configuring such a FriendTree executable is similar to the regular FriendTree configuration, with the following differences: +Starting from version 0.3 of CROWN, it is also possible to use multiple input friend trees. A typical use case for this feature is the evaluation of Classifiers, and storing the output of the classifier in the friend tree. This way, the classifier can utilize quantities from both the main Ntuple and from additional friend trees. The interface for configuring such a FriendTree executable is similar to the regular FriendTree configuration, with the following differences: -* The information for all input files has to be provided. This means that the ``DQUANTITIESMAP`` has to be extended. It is possible to - 1. provide a single JSON file, that contains the input information for all input files (the crown ntuple + all additional files) +* The information for all input files must provided. This means that the ``DQUANTITIESMAP`` must extended. It is possible to + 1. provide a single JSON file, that contains the input information for all files (the crown Ntuple + all additional files) 2. provide a list of JSON files, each containing the input information for one input file - 3. provide a list of root files (crown ntuple + all additional files) + 3. provide a list of ROOT files (crown Ntuple + all additional files) -During the execution, all input files have to be provided, resulting in a command line like this: +During execution, all input files must be provided, resulting in a command line like this: .. code-block:: bash @@ -74,4 +74,4 @@ During the execution, all input files have to be provided, resulting in a comman Before execution, the input files are checked for consistency. This means that the following checks are performed: * All input files have to contain the same number of entries -* All input files have to be readable (no missing files) \ No newline at end of file +* All input files must be readable and present (no missing files) diff --git a/docs/sphinx_source/introduction.rst b/docs/sphinx_source/introduction.rst index 809a764c..caf4c976 100644 --- a/docs/sphinx_source/introduction.rst +++ b/docs/sphinx_source/introduction.rst @@ -1,7 +1,7 @@ Introduction ============= -The **C** ++-based **RO** OT **W** orkflow for **N** -tuples (CROWN) is a fast new way to convert NanoAOD samples into flat :code:`TTrees` to be used in further analysis. The main focus of the framework is to provide a fast and clean way of selecting events and calculating quantities and weights. The framework has minimal dependencies and only uses ROOT and it's Dataframe as a backend. +The **C** ++-based **RO** OT **W** orkflow for **N** -tuples (CROWN) is a fast new way to convert NanoAOD samples into flat :code:`TTrees` to be used in further analysis. The main focus of the framework is to provide a fast and clean way of selecting events and calculating quantities and weights. The framework has minimal dependencies and only uses ROOT and its Dataframe as a backend. Design Idea diff --git a/docs/sphinx_source/postprocessing.rst b/docs/sphinx_source/postprocessing.rst index 28e0569a..53b9887e 100644 --- a/docs/sphinx_source/postprocessing.rst +++ b/docs/sphinx_source/postprocessing.rst @@ -1,13 +1,13 @@ Ntuples in Postprocessing =========================== -The CROWN Ntuples can be used by any Postprocessing framework. Some things have to be kept in mind, in order to ensure an easy processing. -Most important difference is, that only quantities affected by a shift are recalculated. This means the prostprocessing framework must be able to use a mixture of the original and the shifted quantities, when applying shifts. In order to make this step a bit easier, the information, which quantities are affected by a shift, is stored in the Ntuple. +The CROWN Ntuples can be used by any Postprocessing framework. There are a few things to keep in mind to ensure easy processing. +The most important difference is that only quantities affected by a shift are recalculated. This means the postprocessing framework must be able to use a mixture of the original and shifted quantities, when applying shifts. In order to make this step a bit easier, the information which quantities are affected by a shift, is stored in the Ntuple. Quantity mapping ***************** -To read the mapping from a NTuple, the python function listed below may be used. Two types of mapping are available, depending on the actual usecase. In the first, the mapping is sorted by shift; in the second the mapping is sorted by quantity. +To read the mapping from an Ntuple, the python function listed below may be used. Two types of mapping are available, depending on the actual use case. In the first, the mapping is sorted by shift; in the second the mapping is sorted by quantity. .. code-block:: python