atlas-ftag-tools 0.2.8__py3-none-any.whl → 0.2.10__py3-none-any.whl

{atlas_ftag_tools-0.2.8.dist-info → atlas_ftag_tools-0.2.10.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: atlas-ftag-tools
-Version: 0.2.8
+Version: 0.2.10
 Summary: ATLAS Flavour Tagging Tools
 Author: Sam Van Stroud, Philipp Gadow
 License: MIT
@@ -8,8 +8,9 @@ Project-URL: Homepage, https://github.com/umami-hep/atlas-ftag-tools/
 Requires-Python: <3.12,>=3.8
 Description-Content-Type: text/markdown
 Requires-Dist: h5py>=3.0
-Requires-Dist: numpy
+Requires-Dist: numpy>=2.2.3
 Requires-Dist: PyYAML>=5.1
+Requires-Dist: scipy>=1.15.2
 Provides-Extra: dev
 Requires-Dist: ruff==0.6.2; extra == "dev"
 Requires-Dist: mypy==1.11.2; extra == "dev"

{atlas_ftag_tools-0.2.8.dist-info → atlas_ftag_tools-0.2.10.dist-info}/RECORD

@@ -1,28 +1,30 @@
-ftag/__init__.py,sha256=QQHtJR1oF0VAd1zVUKsPimr4TLlVf4ymtbKBcaUPra0,737
+ftag/__init__.py,sha256=v9emuK48Hhd-_TCiirfCNMsZSzk52frz1zEOgk9PViQ,787
 ftag/cli_utils.py,sha256=w3TtQmUHSyAKChS3ewvOtcSDAUJAZGIIomaNi8f446U,298
 ftag/cuts.py,sha256=9_ooLZHaO3SnIQBNxwbaPZn-qptGdKnB27FdKQGTiTY,2933
 ftag/flavours.py,sha256=ShH4M2UjQZpZ_NlCctTm2q1tJbzYxjmGteioQ2GcqEU,114
-ftag/flavours.yaml,sha256=r_5c6SOwYWBCN4qOaz7ZLLEBmbod-ErTDsGGBXJiyZA,8289
+ftag/flavours.yaml,sha256=5Lo9KWe-2KzmGMbc7o_X9gzwUyTl0Q5uVHYExduZ6T4,9502
+ftag/fraction_optimization.py,sha256=IlMEJe5fD0soX40f-LO4dYAYld2gMqgZRuBLctoPn9A,5566
 ftag/git_check.py,sha256=Y-XqM80CVXZ5ZKrDdZcYOJt3X64uU6W3OP6Z0D7AZU0,1663
 ftag/labeller.py,sha256=IXUgU9UBir39PxVWRKs5r5fqI66Tv0x7nJD3-RYpbrg,2780
-ftag/labels.py,sha256=C7IylPTnc32dFXq8C2Ks2wuljYK3WaY2EsPLGrhtXy8,3932
-ftag/mock.py,sha256=Eyj3tkkaSSnqvS3G6NS7fq8sB__Nx8YE9-OM2_lpdoQ,4992
+ftag/labels.py,sha256=2nmcmrZD8mWQPxJsGiOgcLDhSVgWfS_cEzqsBV-Qy8o,4198
+ftag/mock.py,sha256=P2D7nNKAz2jRBbmfpHTDj9sBVU9r7HGd0rpWZOJYZ90,5980
 ftag/region.py,sha256=ANv0dGI2W6NJqD9fp7EfqAUReH4FOjc1gwl_Qn8llcM,360
 ftag/sample.py,sha256=3N0FrRcu9l1sX8ohuGOHuMYGD0See6gMO4--7NzR2tE,2538
 ftag/track_selector.py,sha256=fJNk_kIBQriBqV4CPT_3ReJbOUnavDDzO-u3EQlRuyk,2654
 ftag/transform.py,sha256=uEGGJSnqoKOzLYQv650XdK_kDNw4Aw-5dc60z9Dp_y0,3963
 ftag/vds.py,sha256=nRViQZQIORB95nC7NZsW3KsSoGkLzEdOsuCViH5h8-U,3296
+ftag/working_points.py,sha256=RJws2jPMEDQDspCbXUZBifS1CCBmlMJ5ax0eMyDzCRA,15949
 ftag/hdf5/__init__.py,sha256=LFDNxVOCp58SvLHwQhdT68Q-KBMS_i6jBrbXoRpHzbM,354
 ftag/hdf5/h5move.py,sha256=oYpRu0IDCIJIQ2ML52HBAdoyDxmKkHTeM9JdbPEgKfI,947
 ftag/hdf5/h5reader.py,sha256=i31pDAqmOSaxdeRhc4iSBlld8xJ0pmp4rNd7CugNzw0,13706
 ftag/hdf5/h5split.py,sha256=4Wy6Xc3J58MdD9aBaSZHf5ZcVFnJSkWsm42R5Pgo-R4,2448
 ftag/hdf5/h5utils.py,sha256=-4zKTMtNCrDZr_9Ww7uzfsB7M7muBKpmm_1IkKJnHOI,3222
 ftag/hdf5/h5writer.py,sha256=9FkClV__UbBqmFsq_h2jwiZnbWVm8QFRL_4mDZZBbTs,5316
-ftag/wps/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ftag/wps/discriminant.py,sha256=VJdZlJJUwaTeyxmIDEk23rQSAuvWs6wDA3XRjDI6-_c,4277
-ftag/wps/working_points.py,sha256=cvStSpP8Cbb_FWM8v59tFsscUvdeqi831tLn5BiHUEg,9741
-atlas_ftag_tools-0.2.8.dist-info/METADATA,sha256=PhA8ikzMnWQUOSQxW9PzmxzteUaxCwutISL0JR4UWZY,5153
-atlas_ftag_tools-0.2.8.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-atlas_ftag_tools-0.2.8.dist-info/entry_points.txt,sha256=LfVLsZHQolqbPnwPgtmc5IQTh527BKkN2v-IpXWTNHw,137
-atlas_ftag_tools-0.2.8.dist-info/top_level.txt,sha256=qiYQuKcAvMim-31FwkT3MTQu7WQm0s58tPAia5KKWqs,5
-atlas_ftag_tools-0.2.8.dist-info/RECORD,,
+ftag/utils/__init__.py,sha256=C0PgaA6Nk5WVpFqKhBhrHgj2mwsKJbSxoO6Cl67RsaI,544
+ftag/utils/logging.py,sha256=54NaQiC9Bh4vSznSqzoPfR-7tj1PXfmoH7yKgv_ZHZk,3192
+ftag/utils/metrics.py,sha256=zQI4nPeRDSyzqKpdOPmu0GU560xSWoW1wgL13rrja-I,12664
+atlas_ftag_tools-0.2.10.dist-info/METADATA,sha256=VUhrtQML6_bUKlmZNFlUXxTTt5YBzNYupTrdlaF5IAw,5190
+atlas_ftag_tools-0.2.10.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+atlas_ftag_tools-0.2.10.dist-info/entry_points.txt,sha256=b46bVP_O8Mg6aSdPmyjGgVkaXSdyXZMeKAsofh2IDeA,133
+atlas_ftag_tools-0.2.10.dist-info/top_level.txt,sha256=qiYQuKcAvMim-31FwkT3MTQu7WQm0s58tPAia5KKWqs,5
+atlas_ftag_tools-0.2.10.dist-info/RECORD,,

{atlas_ftag_tools-0.2.8.dist-info → atlas_ftag_tools-0.2.10.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.8.0)
+Generator: setuptools (78.1.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

{atlas_ftag_tools-0.2.8.dist-info → atlas_ftag_tools-0.2.10.dist-info}/entry_points.txt

@@ -2,4 +2,4 @@
 h5move = ftag.hdf5.h5move:main
 h5split = ftag.hdf5.h5split:main
 vds = ftag.vds:main
-wps = ftag.wps.working_points:main
+wps = ftag.working_points:main

ftag/__init__.py

@@ -2,18 +2,18 @@
 
 from __future__ import annotations
 
-__version__ = "v0.2.8"
+__version__ = "v0.2.10"
 
-from ftag import hdf5
+from ftag import hdf5, utils
 from ftag.cuts import Cuts
 from ftag.flavours import Flavours
+from ftag.fraction_optimization import calculate_best_fraction_values
 from ftag.labeller import Labeller
 from ftag.labels import Label, LabelContainer
 from ftag.mock import get_mock_file
 from ftag.sample import Sample
 from ftag.transform import Transform
-from ftag.wps.discriminant import get_discriminant
-from ftag.wps.working_points import get_working_points
+from ftag.working_points import get_working_points
 
 __all__ = [
     "Cuts",
@@ -24,8 +24,9 @@ __all__ = [
     "Sample",
     "Transform",
     "__version__",
-    "get_discriminant",
+    "calculate_best_fraction_values",
     "get_mock_file",
     "get_working_points",
     "hdf5",
+    "utils",
 ]

ftag/flavours.yaml

@@ -60,12 +60,24 @@
   colour: tab:orange
   category: single-btag-ghost
   _px: pc
-- name: ghostujets
-  label: Light-jets
-  cuts: ["HadronGhostTruthLabelID == 0"]
+- name: ghostsjets
+  label: $s$-jets
+  cuts: ["HadronGhostTruthLabelID == 0", "PartonTruthLabelID == 3"]
+  colour: tab:red
+  category: single-btag-ghost
+  _px: ps
+- name: ghostudjets
+  label: Light-quark-jets
+  cuts: ["HadronGhostTruthLabelID == 0", "PartonTruthLabelID <= 2"]
   colour: tab:green
   category: single-btag-ghost
-  _px: pu
+  _px: pud
+- name: ghostgjets
+  label: Gluon-jets
+  cuts: ["HadronGhostTruthLabelID == 0", "PartonTruthLabelID == 21"]
+  colour: tab:gray
+  category: single-btag-ghost
+  _px: pg
 - name: ghosttaujets
   label: $\tau$-jets
   cuts: ["HadronGhostTruthLabelID == 15"]
@@ -119,6 +131,21 @@
   cuts: ["R10TruthLabel_R22v1 == 10", "GhostBHadronsFinalCount == 0", "GhostCHadronsFinalCount == 0"]
   colour: "green"
   category: xbb
+- name: htauel
+  label: $H \rightarrow \tau e$
+  cuts: ["R10TruthLabel_R22v1 == 14"]
+  colour: "#b40612"
+  category: xbb
+- name: htaumu
+  label: $H \rightarrow \tau\mu$
+  cuts: ["R10TruthLabel_R22v1 == 15"]
+  colour: "#b40657"
+  category: xbb
+- name: htauhad
+  label: $H \rightarrow \tau\tau$
+  cuts: ["R10TruthLabel_R22v1 == 16"]
+  colour: "#b406a0"
+  category: xbb
 
 # extended Xbb tagging
 - name: tqqb
@@ -305,3 +332,19 @@
   cuts: ["iffClass == 0"]
   colour: tab:gray
   category: isolation
+# Trigger-Xbb tagging
+- name: dRMatchedHbb
+  label: $H \rightarrow b\bar{b}$
+  cuts: ["HadronConeExclExtendedTruthLabelID == 55", "n_truth_higgs > 0", "n_truth_top == 0"]
+  colour: tab:blue
+  category: trigger-xbb
+- name: dRMatchedTop
+  label: Inclusive Top
+  cuts: ["n_truth_higgs == 0", "n_truth_top > 0"]
+  colour: "#A300A3"
+  category: trigger-xbb
+- name: dRMatchedQCD
+  label: QCD
+  cuts: ["n_truth_higgs == 0", "n_truth_top == 0"]
+  colour: "#38761D"
+  category: trigger-xbb

ftag/fraction_optimization.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+from scipy.optimize import minimize
+
+from ftag import Flavours
+from ftag.utils import calculate_rejection, get_discriminant, logger
+
+if TYPE_CHECKING:  # pragma: no cover
+    from ftag.labels import Label, LabelContainer
+
+
+def convert_dict(
+    fraction_values: dict | np.ndarray,
+    backgrounds: LabelContainer,
+) -> np.ndarray | dict:
+    if isinstance(fraction_values, dict):
+        return np.array([fraction_values[iter_bkg.frac_str] for iter_bkg in backgrounds])
+
+    if isinstance(fraction_values, np.ndarray):
+        fraction_values = [
+            float(frac_value / np.sum(fraction_values)) for frac_value in fraction_values
+        ]
+
+        return dict(zip([iter_bkg.frac_str for iter_bkg in backgrounds], fraction_values))
+
+    raise ValueError(
+        f"Only input of type `dict` or `np.ndarray` are accepted! You gave {type(fraction_values)}"
+    )
+
+
+def get_bkg_norm_dict(
+    jets: np.ndarray,
+    tagger: str,
+    signal: Label,
+    flavours: LabelContainer,
+    working_point: float,
+) -> dict:
+    # Init a dict for the bkg rejection norm values
+    bkg_rej_norm = {}
+
+    # Get the background classes
+    backgrounds = flavours.backgrounds(signal)
+
+    # Define a bool array if the jet is signal
+    is_signal = signal.cuts(jets).idx
+
+    # Loop over backgrounds
+    for bkg in backgrounds:
+        # Get the fraction value dict to maximize rejection for given class
+        frac_dict_bkg = {
+            iter_bkg.frac_str: 1 - (0.01 * len(backgrounds)) if iter_bkg == bkg else 0.01
+            for iter_bkg in backgrounds
+        }
+
+        # Calculate the disc value using the new fraction dict
+        disc = get_discriminant(
+            jets=jets,
+            tagger=tagger,
+            signal=signal,
+            flavours=flavours,
+            fraction_values=frac_dict_bkg,
+        )
+
+        # Calculate the discriminant
+        bkg_rej_norm[bkg.name] = calculate_rejection(
+            sig_disc=disc[is_signal],
+            bkg_disc=disc[bkg.cuts(jets).idx],
+            target_eff=working_point,
+        )
+
+    return bkg_rej_norm
+
+
+def calculate_rejection_sum(
+    fraction_dict: dict | np.ndarray,
+    jets: np.ndarray,
+    tagger: str,
+    signal: Label,
+    flavours: LabelContainer,
+    working_point: float,
+    bkg_norm_dict: dict,
+    rejection_weights: dict,
+) -> float:
+    # Get the background classes
+    backgrounds = flavours.backgrounds(signal)
+
+    # Define a bool array if the jet is signal
+    is_signal = signal.cuts(jets).idx
+
+    # Check that the fraction dict is a dict
+    if isinstance(fraction_dict, np.ndarray):
+        fraction_dict = convert_dict(
+            fraction_values=fraction_dict,
+            backgrounds=backgrounds,
+        )
+
+    # Calculate discriminant
+    disc = get_discriminant(
+        jets=jets,
+        tagger=tagger,
+        signal=signal,
+        flavours=flavours,
+        fraction_values=fraction_dict,
+    )
+
+    # Init a dict to which the bkg rejs are added
+    sum_bkg_rej = 0
+
+    # Loop over the backgrounds and calculate the rejections
+    for iter_bkg in backgrounds:
+        sum_bkg_rej += (
+            calculate_rejection(
+                sig_disc=disc[is_signal],
+                bkg_disc=disc[iter_bkg.cuts(jets).idx],
+                target_eff=working_point,
+            )
+            / bkg_norm_dict[iter_bkg.name]
+        ) * rejection_weights[iter_bkg.name]
+
+    # Return the negative sum to enable minimizer
+    return -1 * sum_bkg_rej
+
+
+def calculate_best_fraction_values(
+    jets: np.ndarray,
+    tagger: str,
+    signal: Label,
+    flavours: LabelContainer,
+    working_point: float,
+    rejection_weights: dict | None = None,
+    optimizer_method: str = "Powell",
+) -> dict:
+    logger.debug("Calculating best fraction values.")
+    logger.debug(f"tagger: {tagger}")
+    logger.debug(f"signal: {signal}")
+    logger.debug(f"flavours: {flavours}")
+    logger.debug(f"working_point: {working_point}")
+    logger.debug(f"rejection_weights: {rejection_weights}")
+    logger.debug(f"optimizer_method: {optimizer_method}")
+
+    # Ensure Label instance
+    if isinstance(signal, str):
+        signal = Flavours[signal]
+
+    # Get the background classes
+    backgrounds = flavours.backgrounds(signal)
+
+    # Define a default fraction dict
+    def_frac_dict = {iter_bkg.frac_str: 1 / len(backgrounds) for iter_bkg in backgrounds}
+
+    # Define rejection weights if not set
+    if rejection_weights is None:
+        rejection_weights = {iter_bkg.name: 1 for iter_bkg in backgrounds}
+
+    # Get the normalisation for all bkg rejections
+    bkg_norm_dict = get_bkg_norm_dict(
+        jets=jets,
+        tagger=tagger,
+        signal=signal,
+        flavours=flavours,
+        working_point=working_point,
+    )
+
+    # Get the best fraction values combination
+    result = minimize(
+        fun=calculate_rejection_sum,
+        x0=convert_dict(fraction_values=def_frac_dict, backgrounds=backgrounds),
+        method=optimizer_method,
+        bounds=[(0, 1)] * len(backgrounds),
+        args=(jets, tagger, signal, flavours, working_point, bkg_norm_dict, rejection_weights),
+    )
+
+    # Get the final fraction dict
+    final_frac_dict = convert_dict(fraction_values=result.x, backgrounds=backgrounds)
+
+    logger.info(f"Minimization Success: {result.success}")
+    logger.info("The following best fraction values were found:")
+    for frac_str, frac_value in final_frac_dict.items():
+        logger.info(f"{frac_str}: {round(frac_value, ndigits=3)}")
+
+    return final_frac_dict

ftag/labels.py

@@ -62,6 +62,9 @@ class LabelContainer:
         except KeyError as e:
             raise KeyError(f"Label '{key}' not found") from e
 
+    def __len__(self) -> int:
+        return len(self.labels.keys())
+
     def __getattr__(self, name) -> Label:
         return self[name]
 
@@ -120,8 +123,13 @@ class LabelContainer:
     def from_list(cls, labels: list[Label]) -> LabelContainer:
         return cls({f.name: f for f in labels})
 
-    def backgrounds(self, label: Label, only_signals: bool = True) -> LabelContainer:
-        bkg = [f for f in self if f.category == label.category and f != label]
+    def backgrounds(self, signal: Label, only_signals: bool = True) -> LabelContainer:
+        bkg = [f for f in self if f.category == signal.category and f != signal]
         if not only_signals:
             bkg = [f for f in bkg if f.name not in {"ujets", "qcd"}]
+        if len(bkg) == 0:
+            raise TypeError(
+                "No background flavour could be found in the flavours for signal "
+                f"flavour {signal.name}"
+            )
         return LabelContainer.from_list(bkg)

ftag/mock.py

@@ -54,33 +54,74 @@ TRACK_VARS = [
 ]
 
 
-def softmax(x, axis=None):
+def softmax(x: np.ndarray, axis: int | None = None) -> np.ndarray:
+    """Softmax function for numpy arrays.
+
+    Parameters
+    ----------
+    x : np.ndarray
+        Input array for the softmax
+    axis : int | None, optional
+        Axis along which the softmax is calculated, by default None
+
+    Returns
+    -------
+    np.ndarray
+        Output array with the softmax output
+    """
     e_x = np.exp(x - np.max(x, axis=axis, keepdims=True))
     return e_x / e_x.sum(axis=axis, keepdims=True)
 
 
-def get_mock_scores(labels: np.ndarray, is_xbb: bool = False):
-    means = [
-        [2, 0, 0, 0],
-        [0, 1, 0, 0],
-        [0, 0, 3.5, 0],
-        [0, 0, 0, 1],
-    ]
+def get_mock_scores(labels: np.ndarray, is_xbb: bool = False) -> np.ndarray:
     if not is_xbb:
         label_dict = {"u": 0, "c": 4, "b": 5, "tau": 15}
-        label_mapping = dict(zip(label_dict.values(), means))
-    else:
-        label_dict = {"hbb": 11, "hcc": 12, "top": 1, "qcd": 10}
-        label_mapping = dict(zip(label_dict.values(), means))
 
+    else:
+        label_dict = {
+            "hbb": 11,
+            "hcc": 12,
+            "top": 1,
+            "qcd": 10,
+            "htauel": 14,
+            "htaumu": 15,
+            "htauhad": 16,
+        }
+
+    # Set random seed
     rng = np.random.default_rng(42)
-    nclass = len(label_dict)
-    scores = np.zeros((len(labels), nclass))
-    scales = [1, 2.5, 5, 1]
+
+    # Set a list of possible means/scales
+    mean_scale_list = [1, 2, 2.5, 3.5]
+
+    # Get the number of classes
+    n_classes = len(label_dict)
+
+    # Init a scores array
+    scores = np.zeros((len(labels), n_classes))
+
+    # Generate means/scales
+    means = []
+    scales = []
+    for i in range(n_classes):
+        tmp_means = []
+        tmp_means = [
+            0 if j != i else mean_scale_list[np.random.randint(0, len(mean_scale_list))]
+            for j in range(n_classes)
+        ]
+        means.append(tmp_means)
+        scales.append(mean_scale_list[np.random.randint(0, len(mean_scale_list))])
+
+    # Map the labels to the means
+    label_mapping = dict(zip(label_dict.values(), means))
+
+    # Generate random mock scores
     for i, (label, count) in enumerate(zip(*np.unique(labels, return_counts=True))):
         scores[labels == label] = rng.normal(
-            loc=label_mapping[label], scale=scales[i], size=(count, nclass)
+            loc=label_mapping[label], scale=scales[i], size=(count, n_classes)
         )
+
+    # Pipe scores through softmax
     scores = softmax(scores, axis=1)
     name = "MockXbbTagger" if is_xbb else "MockTagger"
     cols = [f"{name}_p{x}" for x in label_dict]
@@ -103,7 +144,7 @@ def mock_jets(num_jets=1000) -> np.ndarray:
     jets["HadronConeExclTruthLabelID"] = rng.choice([0, 4, 5, 15], size=num_jets)
     jets["GhostBHadronsFinalCount"] = rng.choice([0, 1, 2], size=num_jets)
     jets["GhostCHadronsFinalCount"] = rng.choice([0, 1, 2], size=num_jets)
-    jets["R10TruthLabel_R22v1"] = rng.choice([1, 10, 11, 12], size=num_jets)
+    jets["R10TruthLabel_R22v1"] = rng.choice([1, 10, 11, 12, 14, 15, 16], size=num_jets)
     scores = get_mock_scores(jets["HadronConeExclTruthLabelID"])
     xbb_scores = get_mock_scores(jets["R10TruthLabel_R22v1"], is_xbb=True)
     return join_structured_arrays([jets, scores, xbb_scores])

ftag/utils/__init__.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from ftag.utils.logging import logger, set_log_level
+from ftag.utils.metrics import (
+    calculate_efficiency,
+    calculate_efficiency_error,
+    calculate_rejection,
+    calculate_rejection_error,
+    get_discriminant,
+    save_divide,
+    weighted_percentile,
+)
+
+__all__ = [
+    "calculate_efficiency",
+    "calculate_efficiency_error",
+    "calculate_rejection",
+    "calculate_rejection_error",
+    "get_discriminant",
+    "logger",
+    "save_divide",
+    "set_log_level",
+    "weighted_percentile",
+]

ftag/utils/logging.py

@@ -0,0 +1,123 @@
+"""Configuration for logger of atlas-ftag-tools."""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import ClassVar
+
+
+class CustomFormatter(logging.Formatter):
+    """
+    Logging Formatter to add colours and count warning / errors using implementation
+    from
+    https://stackoverflow.com/questions/384076/how-can-i-color-python-logging-output.
+    """
+
+    grey = "\x1b[38;21m"
+    yellow = "\x1b[33;21m"
+    green = "\x1b[32;21m"
+    red = "\x1b[31;21m"
+    bold_red = "\x1b[31;1m"
+    reset = "\x1b[0m"
+    debugformat = "%(asctime)s - %(levelname)s:%(name)s: %(message)s (%(filename)s:%(lineno)d)"
+    date_format = "%(levelname)s:%(name)s: %(message)s"
+
+    formats: ClassVar = {
+        logging.DEBUG: grey + debugformat + reset,
+        logging.INFO: green + date_format + reset,
+        logging.WARNING: yellow + date_format + reset,
+        logging.ERROR: red + debugformat + reset,
+        logging.CRITICAL: bold_red + debugformat + reset,
+    }
+
+    def format(self, record):
+        log_fmt = self.formats.get(record.levelno)
+        formatter = logging.Formatter(log_fmt)
+        return formatter.format(record)
+
+
+def get_log_level(
+    level: str,
+):
+    """Get logging levels with string key.
+
+    Parameters
+    ----------
+    level : str
+        Log level as string.
+
+    Returns
+    -------
+    logging level
+        logging object with log level info
+
+    Raises
+    ------
+    ValueError
+        If non-valid option is given
+    """
+    log_levels = {
+        "CRITICAL": logging.CRITICAL,
+        "ERROR": logging.ERROR,
+        "WARNING": logging.WARNING,
+        "INFO": logging.INFO,
+        "DEBUG": logging.DEBUG,
+        "NOTSET": logging.NOTSET,
+    }
+    if level not in log_levels:
+        raise ValueError(f"The 'DebugLevel' option {level} is not valid.")
+    return log_levels[level]
+
+
+def initialise_logger(
+    log_level: str | None = None,
+):
+    """Initialise.
+
+    Parameters
+    ----------
+    log_level : str, optional
+        Logging level defining the verbose level. Accepted values are:
+        CRITICAL, ERROR, WARNING, INFO, DEBUG, NOTSET, by default None
+        If the log_level is not set, it will be set to info
+
+    Returns
+    -------
+    logger
+        logger object with new level set
+    """
+    retrieved_log_level = get_log_level(
+        os.environ.get("LOG_LEVEL", "INFO") if log_level is None else log_level
+    )
+
+    tools_logger = logging.getLogger("atlas-ftag-tools")
+    tools_logger.setLevel(retrieved_log_level)
+    ch_handler = logging.StreamHandler()
+    ch_handler.setLevel(retrieved_log_level)
+    ch_handler.setFormatter(CustomFormatter())
+
+    tools_logger.addHandler(ch_handler)
+    tools_logger.propagate = False
+    return tools_logger
+
+
+def set_log_level(
+    tools_logger,
+    log_level: str,
+):
+    """Setting log level.
+
+    Parameters
+    ----------
+    tools_logger : logger
+        logger object
+    log_level : str
+        Logging level corresponding CRITICAL, ERROR, WARNING, INFO, DEBUG, NOTSET
+    """
+    tools_logger.setLevel(get_log_level(log_level))
+    for handler in tools_logger.handlers:
+        handler.setLevel(get_log_level(log_level))
+
+
+logger = initialise_logger()