Event Interface

The Event Interface provides the foundation for defining custom event types in AnalysisG.

Overview

Events are the primary data containers in HEP analyses. The EventTemplate class provides a flexible interface for:

Reading event data from ROOT files
Implementing event selection criteria
Processing and transforming event-level information
Organizing particles within events
Managing event weights and metadata

Core EventTemplate Class

File Location

Cython Implementation: src/AnalysisG/core/event_template.pyx
Cython Header: src/AnalysisG/core/event_template.pxd

Class Definition

class EventTemplate: The base class for all event types in AnalysisG.

Properties

Event Identification

property index

Unique identifier for the event.

Type:: int

property hash

Hash value for event identification and comparison.

Type:: str

Event Data

property Particles

Collection of particles in this event.

Type:: list[ParticleTemplate]
Getter:: Returns list of particles
Setter:: Assigns particles to event

property weight

Statistical weight for this event.

Type:: float
Getter:: Returns event weight
Setter:: Sets event weight

ROOT Integration

property Tree

Name of the ROOT TTree containing this event.

Type:: str
Getter:: Returns tree name
Setter:: Sets tree name

property Trees

List of all ROOT TTrees to process.

Type:: list[str]
Getter:: Returns list of tree names
Setter:: Sets tree names

property Branches

List of ROOT branches to read from the tree.

Type:: list[str]
Getter:: Returns branch names
Setter:: Sets branch names to read

Methods to Override

Selection Method

selection() → bool

Define event selection criteria.

This method should return True if the event passes your analysis selection requirements, and False otherwise. This is the primary method users should override.

Returns:: Whether the event passes selection
Return type:: bool

Example:

def selection(self):
    # Require at least 2 leptons and 4 jets
    leptons = [p for p in self.Particles if p.is_lep]
    jets = [p for p in self.Particles if p.Type == "jet"]
    return len(leptons) >= 2 and len(jets) >= 4

Strategy Method

strategy()

Define custom event processing strategy.

Override this method to implement custom event-level calculations, reconstructions, or other processing that should be performed on selected events.

Example:

def strategy(self):
    # Reconstruct top quarks from particles
    self.reconstruct_tops()
    self.calculate_observables()

Utility Methods

Comparison and Hashing

__hash__() → int: Return hash value for this event.

__eq__(EventTemplate other) → bool

Compare two events for equality.

Parameters:: other (EventTemplate) – Event to compare with
Returns:: True if events are equal
Return type:: bool

Merging

merge(EventTemplate other)

Merge data from another event.

Parameters:: other – Event to merge from
Type:: EventTemplate

Type Checking

is_self(inpt) → bool

Check if input is an EventTemplate instance.

Parameters:: inpt – Object to check
Returns:: True if input is EventTemplate or subclass
Return type:: bool

Usage Examples

Basic Event Selection

from AnalysisG.core import EventTemplate

class MyEvent(EventTemplate):
    def __init__(self):
        super().__init__()

    def selection(self):
        # Select events with high jet multiplicity
        jets = [p for p in self.Particles if p.Type == "jet"]
        return len(jets) >= 6

Event with Custom Processing

from AnalysisG.core import EventTemplate

class TopEvent(EventTemplate):
    def __init__(self):
        super().__init__()
        self.reconstructed_tops = []

    def selection(self):
        # Basic selection
        return len(self.Particles) > 0

    def strategy(self):
        # Custom reconstruction
        jets = [p for p in self.Particles if p.Type == "jet"]
        leptons = [p for p in self.Particles if p.is_lep]

        # Reconstruct top candidates
        for l in leptons:
            for j1 in jets:
                for j2 in jets:
                    if j1 != j2:
                        top_candidate = l + j1 + j2
                        self.reconstructed_tops.append(top_candidate)

Event with Weights

from AnalysisG.core import EventTemplate

class WeightedEvent(EventTemplate):
    def __init__(self):
        super().__init__()

    def selection(self):
        # Apply event weight based on conditions
        if self.some_condition():
            self.weight = 1.5
        else:
            self.weight = 1.0
        return True

Best Practices

Always call super().__init__(): Initialize the parent class in your constructor.
Keep selection simple: The selection() method should return a boolean. Complex logic should go in strategy().
Use properties: Access particle collections and event metadata through properties, not direct attribute access.
Cache results: If you perform expensive calculations in strategy(), store the results as instance attributes.
Handle edge cases: Check for empty particle lists or missing data before processing.