ftag

atlas-ftag-tools - Common tools for ATLAS flavour tagging software.

Submodules

• ftag.cli_utils
• ftag.cuts
• ftag.find_metadata
• ftag.fraction_optimization
• ftag.git_check
• ftag.hdf5
• ftag.labeller
• ftag.labels
• ftag.mock
• ftag.region
• ftag.sample
• ftag.track_selector
• ftag.transform
• ftag.utils
• ftag.vds
• ftag.working_points

Attributes

__version__

Exceptions

GitError

Raised when a Git-related precondition is not satisfied.

Classes

Cuts	Cuts dataclass to store multiple Cut instances and apply them.
Labeller	Defines a labelling scheme.
Label	Dataclass to hold info about one flavour/label.
LabelContainer	Label container that holds multiple labels.
Sample	Dataclass which holds info about a specific sample.
Transform	Transform class to transform variables.

Functions

check_for_fork(→ None)	Ensure the local clone's origin remote is a fork of upstream.
check_for_uncommitted_changes(→ None)	Raise if the repository at path has uncommitted changes.
create_and_push_tag(→ None)	Create an annotated Git tag and push it to origin.
get_git_hash(→ str | None)	Return the short commit hash for HEAD at path, if available.
is_git_repo(→ bool)	Return whether path is inside a Git working tree.
get_mock_file(→ tuple[str, h5py.File])	Get a mock file for testing.
get_working_points(→ dict | None)	Calculate the working points.

Package Contents

ftag.__version__ = 'v0.2.16'

class ftag.Cuts

Cuts dataclass to store multiple Cut instances and apply them.

cuts

Tuple with the Cut instances

Type:

tuple[Cut, …]

cuts: tuple[Cut, Ellipsis]

classmethod from_list(cuts: list) → Cuts

classmethod empty() → Cuts

__post_init__()

property variables: list[str]

ignore(variables: list[str])

__call__(array: numpy.ndarray) → CutsResult

__add__(other: Cuts)

__len__() → int

__iter__() → collections.abc.Iterator

__getitem__(variable)

__repr__() → str

exception ftag.GitError

Bases: Exception

Raised when a Git-related precondition is not satisfied.

Initialize self. See help(type(self)) for accurate signature.

ftag.check_for_fork(path: str | os.PathLike[str], upstream: str) → None

Ensure the local clone’s origin remote is a fork of upstream.

Parameters:

• path (str | PathLike[str]) – Filesystem path to the repository root or any directory within it.

• upstream (str) – Expected upstream repository URL substring (e.g. 'github.com/org/repo').

Raises:

GitError – If the repository is present but its origin URL does not contain upstream.

Notes

If path is not a Git repository, the function returns silently.

ftag.check_for_uncommitted_changes(path: str | os.PathLike[str]) → None

Raise if the repository at path has uncommitted changes.

Parameters:

path (str | PathLike[str]) – Filesystem path to the repository root or any directory within it.

Raises:

GitError – If path is a Git repository and there are uncommitted changes.

Notes

• If path is not a Git repository, the function returns silently.

• If the current process is running under pytest (detected via sys.modules), the check is skipped and the function returns.

ftag.create_and_push_tag(path: str | os.PathLike[str], upstream: str, tagname: str, msg: str) → None

Create an annotated Git tag and push it to origin.

Parameters:

• path (str | PathLike[str]) – Filesystem path to the repository root or any directory within it.

• upstream (str) – Expected upstream repository URL substring; passed to check_for_fork().

• tagname (str) – Name of the tag to create.

• msg (str) – Annotation message for the tag (git tag -m).

Notes

If path is not a Git repository, the function returns silently.

ftag.get_git_hash(path: str | os.PathLike[str]) → str | None

Return the short commit hash for HEAD at path, if available.

Parameters:

path (str | PathLike[str]) – Filesystem path to the repository root or any directory within it.

Returns:

The short (--short) commit hash as a string, or None if path is not a Git repository.

Return type:

str | None

ftag.is_git_repo(path: str | os.PathLike[str]) → bool

Return whether path is inside a Git working tree.

Parameters:

path (str | PathLike[str]) – Filesystem path used as the current working directory for the Git command.

Returns:

True if path is inside a Git working tree, False otherwise.

Return type:

bool

Notes

This function runs:

git rev-parse --is-inside-work-tree HEAD

Any non-zero exit status is treated as “not a Git repository”. If Git is not available on the system, an OSError may be raised by subprocess.

class ftag.Labeller

Defines a labelling scheme.

Classes are assigned integer labels in [0, …, n] based on pre-defined selections.

labels

The labels to be use.

Type:

LabelContainer | list[str | Label]

require_labels

Whether to require that all objects are labelled.

Type:

bool

labels: ftag.labels.LabelContainer | list[str | ftag.labels.Label]

require_labels: bool = True

__post_init__() → None

property variables: list[str]

Returns the variables used for labelling.

Returns:

The variables used for labelling.

Return type:

list[str]

get_labels(array: numpy.ndarray) → numpy.ndarray

Returns the labels for the given array.

Parameters:

array (np.ndarray) – The array to label.

Returns:

The labels for the given array.

Return type:

np.ndarray

Raises:

ValueError – If the require_labels attribute is set to True and some objects were not labelled.

add_labels(array: numpy.ndarray, label_name: str = 'labels') → numpy.ndarray

Adds the labels to the given array.

Parameters:

• array (np.ndarray) – The array to label.

• label_name (str) – The name of the label column.

Returns:

The array with the labels added.

Return type:

np.ndarray

Raises:

ValueError – If the require_labels attribute is set to False.

class ftag.Label

Dataclass to hold info about one flavour/label.

name

Name of the flavour/label

Type:

str

label

Plot label for this flavour/label

Type:

str

cuts

Cuts of this flavour/label

Type:

Cuts

colour

Colour of this flavour/label

Type:

str

category

Flavour category, to which this flavour/label belongs

Type:

str

name: str

label: str

cuts: ftag.cuts.Cuts

colour: str

category: str

_px: str | None = None

property px: str

property eff_str: str

property rej_str: str

property frac_str: str

__str__() → str

__lt__(other) → bool

class ftag.LabelContainer

Label container that holds multiple labels.

labels

Dict with the labels this container will hold

Type:

dict[str, Label]

labels: dict[str, Label]

__iter__() → collections.abc.Iterator

__getitem__(key) → Label

__len__() → int

__getattr__(name) → Label

__contains__(label: str | Label) → bool

__eq__(other) → bool

__repr__() → str

property categories: list[str]

by_category(category: str) → LabelContainer

from_cuts(cuts: list | ftag.cuts.Cuts) → Label

classmethod from_yaml(yaml_path: pathlib.Path | None = None, include_categories: collections.abc.Iterable[str] | None = None, exclude_categories: collections.abc.Iterable[str] | None = None) → LabelContainer

classmethod from_list(labels: list[Label]) → LabelContainer

backgrounds(signal: Label, only_signals: bool = True) → LabelContainer

ftag.get_mock_file(num_jets: int = 1000, fname: str | None = None, tracks_name: str = 'tracks', num_tracks: int = 40) → tuple[str, h5py.File]

Get a mock file for testing.

Parameters:

• num_jets (int, optional) – Number of jets in the file, by default 1000

• fname (str | None, optional) – Name of the file, by default None

• tracks_name (str, optional) – Name of the tracks dataset, by default “tracks”

• num_tracks (int, optional) – Number of tracks per jet, by default 40

Returns:

Tuple with the path and the h5 file

Return type:

tuple[str, h5py.File]

class ftag.Sample

Dataclass which holds info about a specific sample.

pattern

Filepattern for the h5 files

Type:

Path | str | tuple[Path | str, …]

ntuple_dir

Ntuple directory where the h5 files are stored, by default None

Type:

Path | str | None, optional

name

Name of the sample, for internal identification, by default None

Type:

str | None, optional

weights

List of weights for this sample, by default None

Type:

list[float] | None, optional

skip_checks

Decide, if certain checks are skipped, by default False

Type:

bool, optional

pattern: pathlib.Path | str | tuple[pathlib.Path | str, Ellipsis]

ntuple_dir: pathlib.Path | str | None = None

name: str | None = None

weights: list[float] | None = None

skip_checks: bool = False

__post_init__() → None

property path: tuple[pathlib.Path, Ellipsis]

property files: list[str]

property num_files: int

property dsid: list[str]

property sample_id: list[str]

property tags: list[str]

property ptag: list[str]

property rtag: list[str]

property dumper_tag: list[str]

virtual_file(**kwargs) → list[pathlib.Path | str]

__str__()

__lt__(other)

__eq__(other)

class ftag.Transform

Transform class to transform variables.

variable_map

Map with the old and new variables

Type:

dict[str, dict[str, str]] | None, optional

ints_map

Map with the old and new integer values

Type:

dict[str, dict[str, dict[int, int]]] | None, optional

floats_map

Map with the old and new float values

Type:

dict[str, dict[str, str | Callable]] | None, optional

variable_map: dict[str, dict[str, str]] | None = None

ints_map: dict[str, dict[str, dict[int, int]]] | None = None

floats_map: dict[str, dict[str, str | collections.abc.Callable]] | None = None

__post_init__()

__call__(batch: Batch) → Batch

map_variables(batch: Batch) → Batch

Rename variables in a batch of data.

Parameters:

batch (Batch) – Dict of structured numpy arrays.

Returns:

Dict of structured numpy arrays with renamed variables.

Return type:

Batch

map_ints(batch: Batch) → Batch

Map integer values to new values.

Parameters:

batch (Batch) – Dict of structured numpy arrays.

Returns:

Dict of structured numpy arrays with mapped integer values.

Return type:

Batch

map_floats(batch: Batch) → Batch

Transform float values.

Parameters:

batch (Batch) – Dict of structured numpy arrays.

Returns:

Dict of structured numpy arrays with transformed float values.

Return type:

Batch

map_dtype(name: str, dtype: numpy.dtype) → numpy.dtype

map_variable_names(name: str, variables: list[str], inverse=False) → list[str]

ftag.get_working_points(args: argparse.Namespace) → dict | None

Calculate the working points.

Parameters:

args (argparse.Namespace) – Input arguments from the argparser

Returns:

Dict with the working points. If args.outfile is given, the function returns None and stored the resulting dict in a yaml file in args.outfile.

Return type:

dict | None