awkward_zipper package

Behaviors

Layouts

awkward_zipper.awkward_util

Kernels

awkward_zipper.kernels.begin_end_counts(begin_content, end_content)[source]

Flat end - begin counts for EDM4HEP begin/end index ranges (lazy).

awkward_zipper.kernels.begin_end_mapping(begin, end, target_content)[source]

Group target_content into per-item lists using begin/end index ranges.

EDM4HEP stores OneToMany relations and VectorMembers as flat per-event arrays plus per-item {member}_begin / {member}_end ranges. Those ranges are contiguous and exactly cover the target, so the mapping reduces to regrouping the target by counts = end - begin.

begin/end are the per-event jagged range arrays (ListOffsetArray); target_content is the flat content of the per-event target array. Returns a doubly-jagged ListOffsetArray (event -> item -> sub-items).

awkward_zipper.kernels.children(counts, globalparents)[source]

Compute children

Signature: offsets,globalparents,!children Output will be a jagged array with same outer shape as globalparents content

awkward_zipper.kernels.counts2nestedindex(local_counts, target_offsets)[source]

Turn jagged local counts into doubly-jagged global index into a target Outputs a jagged array with same axis-0 shape as counts axis-1

Example usage: Local counts [[4, 3, 2],

[4, 2]]

Target offsets [9, 6] Target output [[[0, 1, 2, 3], [4, 5, 6], [7, 8]],

[[9, 10, 11, 12], [13, 14]]]

awkward_zipper.kernels.counts2offsets(counts)[source]
awkward_zipper.kernels.dispatch_wrap(function)[source]
awkward_zipper.kernels.distinct_children_deep(counts, global_parents, global_pdgs)[source]

Compute all distinct children, skipping children with same pdg id in between.

Signature: offsets,global_parents,global_pdgs,!distinctChildrenDeep Expects global indexes, flat arrays, which should be same length

awkward_zipper.kernels.distinct_parent(parents, pdg)[source]

Compute first parent with distinct PDG id

Signature: globalparents,globalpdgs,!distinctParent Expects global indexes, flat arrays, which should be same length

awkward_zipper.kernels.ensure_array(arraylike)[source]

Converts arraylike to a Numpy array

awkward_zipper.kernels.eventindex_content(offsets_index)[source]

Flat int64 content giving each element’s event index (from offsets).

awkward_zipper.kernels.full_like_from_array(content, fill_value, dtype=<class 'numpy.float32'>)[source]

Create a flat content shaped like content with every element set to fill_value.

Mirrors coffea’s full_like_from_content transform (the ATLAS ntuple variant: takes a possibly jagged array, fills float32). Unlike full_like_from_counts() this works from an existing flat content, which is what the ATLAS ntuple schema needs: its collections carry their own offsets and there is no n{collection} counts branch to derive a shape from.

A jagged source keeps its offsets, so the result lines up element-for-element with the collection it was derived from.

Stays lazy: when the source buffer is virtual the result is a virtual buffer that only materializes the source to learn how many elements to fill.

awkward_zipper.kernels.full_like_from_content(source_content, fill_value)[source]

A flat content shaped like source_content, filled with fill_value.

awkward_zipper.kernels.full_like_from_counts(counts, fill_value)[source]

Create a jagged array shaped like a collection with counts elements per event, with every element set to fill_value (as float32).

This mirrors coffea’s full_like_from_offsets transform, but works from the n{collection} counts branch instead of the o{collection} offsets branch. It is used to synthesize branches (e.g. Photon_mass, Jet_charge) that must be present for the 4-vector behaviors to work.

Only the flat content of the returned array is ultimately consumed by the schema (the collection re-wraps it with its own offsets), but a valid ListOffsetArray is returned so that awkward.to_buffers yields the expected {"node0-offsets", "node1-data"} buffers.

awkward_zipper.kernels.grow_local_index_to_target_shape(index, target_offsets)[source]

Grow a local index to the target’s shape, filling unreferenced slots with -1.

Mirrors coffea’s grow_local_index_to_target_shape: for every element of the target, emit its local index if that index appears in index for the event, otherwise -1. Returns the flat content, evaluated lazily.

awkward_zipper.kernels.local2global(index, target_offsets)[source]

Turn a jagged local index into a global index into a target collection.

Mirrors coffea’s local2global transform. index is a per-event jagged ListOffsetArray; target_offsets is the target collection’s per-event offsets buffer. Returns the flat (global) index content, evaluated lazily.

awkward_zipper.kernels.local2globalindex(index, counts)[source]

Convert a jagged local index to a global index

This is the same as local2global(index, counts2offsets(counts)) where local2global and counts2offsets are as in coffea.nanoevents.transforms

Example usage: Index array [[], [1], [], [2, 3]] Counts array [8, 7, 4, 7] Output array will be: [[], [9], [], [21, 22]] (here 21=8+7+4+2)

awkward_zipper.kernels.met_to_rho(met_content, eta_content)[source]

Compute rho = met * cosh(eta) on flat contents, lazily.

Mirrors coffea’s met_to_rho transform. met_content and eta_content are flat NumpyArray contents; the result is returned as a flat NumpyArray content and is only evaluated when the buffer is read.

awkward_zipper.kernels.nested_local2global(nested_index, target_offsets)[source]

local2global for a doubly-jagged index (event -> item -> indices).

nested_index is ListOffsetArray(ListOffsetArray(NumpyArray)); the per-event grouping used for the offset lookup is the OUTER list.

awkward_zipper.kernels.nestedindex(indices)[source]

Concatenate a list of indices along a new axis Outputs a jagged array with same outer shape as index arrays

Example usage: First index array [[0, 2, 4],

[8, 6]]

Second index array [[1, 3, 5],

[-1, 7]]

Output [[[0, 1], [2, 3], [4, 5]],

[[8, -1], [6, 7]]]

awkward_zipper.kernels.qoverp_theta_to_pt(qoverp_content, theta_content)[source]

pt = sin(theta) / |qOverP|.

awkward_zipper.kernels.qoverp_to_p(qoverp_content)[source]

p = 1 / |qOverP| (cast to the source dtype, matching coffea).

awkward_zipper.kernels.regular_to_jagged(regular, dtype=<class 'numpy.float64'>)[source]

Convert a RegularArray(size, NumpyArray) to a jagged list of dtype.

EDM4HEP stores fixed-size members (e.g. covMatrix.values[21]) as a regular array; coffea’s ArrayBuilder-based transform turns them into variable-length lists of float64. Evaluated lazily.

Package classes

class awkward_zipper.BaseLayoutBuilder[source]

Base class for all layout builders

classmethod behavior()[source]

Behaviors necessary to implement this schema (dict)

class awkward_zipper.Delphes(version='latest')[source]

Delphes layout builder

The Delphes layout is built from all branches found in the supplied file, based on the naming pattern of the branches. Any branches named {name}_size are counts branches, converted to offsets. Every Delphes object collection is a jagged list of records; the split leaf branches ({name}.{var}) are grouped under the collection {name} and given the aliases required by the vector/candidate behaviors (pt, eta, phi, mass, rho).

A companion {name}.offsets field is emitted for each collection (matching coffea). Collections stored as length-1 vectors (see singletons) are flattened, removing an unnecessary level of nesting.

classmethod behavior()[source]

Behaviors necessary to implement this schema (dict)

mixins: ClassVar = {'CaloJet02': 'Jet', 'CaloJet04': 'Jet', 'CaloJet08': 'Jet', 'CaloJet15': 'Jet', 'EFlowNeutralHadron': 'Tower', 'EFlowPhoton': 'Photon', 'EFlowTrack': 'Track', 'Electron': 'Electron', 'ElectronCHS': 'Electron', 'Event': 'Event', 'EventLHEF': 'EventLHEF', 'FatJet': 'Jet', 'GenJet': 'Jet', 'GenJet02': 'Jet', 'GenJet04': 'Jet', 'GenJet08': 'Jet', 'GenJet15': 'Jet', 'GenJetAK8': 'Jet', 'GenMissingET': 'MissingET', 'GenPileUpMissingET': 'MissingET', 'HepMCEvent': 'HepMCEvent', 'Jet': 'Jet', 'JetAK8': 'Jet', 'JetPUPPI': 'Jet', 'JetPUPPIAK8': 'Jet', 'LHCOEvent': 'LHCOEvent', 'MissingET': 'MissingET', 'Muon': 'Muon', 'MuonLoose': 'Muon', 'MuonLooseCHS': 'Muon', 'MuonTight': 'Muon', 'MuonTightCHS': 'Muon', 'Particle': 'Particle', 'ParticleFlowJet02': 'Jet', 'ParticleFlowJet04': 'Jet', 'ParticleFlowJet08': 'Jet', 'ParticleFlowJet15': 'Jet', 'Photon': 'Photon', 'PhotonCHS': 'Photon', 'PuppiMissingET': 'MissingET', 'Rho': 'Rho', 'ScalarHT': 'ScalarHT', 'Tower': 'Tower', 'Track': 'Track', 'TrackJet02': 'Jet', 'TrackJet04': 'Jet', 'TrackJet08': 'Jet', 'TrackJet15': 'Jet', 'Weight': 'Weight', 'WeightLHEF': 'WeightLHEF'}

Default configuration for mixin types, based on the collection name.

singletons: ClassVar = ['Event', 'EventLHEF', 'HepMCEvent', 'LHCOEvent', 'Rho', 'ScalarHT', 'MissingET']

Fields stored as length-1 vectors in Delphes, flattened out in nanoevents.

classmethod v1()[source]

Build the DelphesEvents for version 1 (DelphesSchema.v1 in coffea)

class awkward_zipper.EDM4HEP[source]

EDM4HEP layout builder.

Array-based re-implementation of coffea’s EDM4HEPSchema for the newest bundled edm4hep.yaml version; use edm4hep_version() (or EDM4HEP.version(...)) to pick an older one. The layout is driven by the vendored EDM4HEP yaml data model, which describes each datatype’s Members, VectorMembers, OneToOneRelations and OneToManyRelations:

  • component members (Vector3f/Vector4f/…) such as X.position.{x,y,z} are zipped into an X.position sub-record,

  • VectorMembers and OneToManyRelations stored as flat per-event arrays plus per-item {member}_begin/{member}_end ranges are regrouped into doubly-jagged arrays,

  • OneToOneRelations and Links get a global index (index_Global) into their target collection,

  • the remaining X.* branches are zipped into the X collection.

The collection datatypes come from the TTree’s branch typenames, which are not present in tree.arrays() output, so pass them explicitly. Generic podio links (vector<podio::LinkData>, podio >= 1.3) are typed from the file’s podio_metadata tree, which podio_collection_types() reads:

EDM4HEP()(
    tree.arrays(...),
    typenames=tree.typenames(),
    podio_collection_types=podio_collection_types(tree),
)

extra_mixins overrides the link type of a collection. If typenames is omitted, the datatypes are inferred by matching each collection’s member branch names against the yaml data model.

classmethod behavior()[source]

Behaviors necessary to implement this schema (dict)

edm4hep_version = '01-01'
extra_mixins: ClassVar = {'*idx': 'ObjectID'}
classmethod version(ver='latest')[source]

Return the layout builder class for a given edm4hep.yaml version.

Parameters:

ver (str, optional) – Version of edm4hep.yaml, written either as “00.99.04” or “00-99-04”. “latest” (default) selects the newest bundled version. The available versions are listed in awkward_zipper.assets.versions.

class awkward_zipper.EDM4HEP_v00_10_01

EDM4HEP layout builder for edm4hep version 00.10.01

edm4hep_version = '00-10-01'
class awkward_zipper.EDM4HEP_v00_10_02

EDM4HEP layout builder for edm4hep version 00.10.02

edm4hep_version = '00-10-02'
class awkward_zipper.EDM4HEP_v00_10_03

EDM4HEP layout builder for edm4hep version 00.10.03

edm4hep_version = '00-10-03'
class awkward_zipper.EDM4HEP_v00_10_04

EDM4HEP layout builder for edm4hep version 00.10.04

edm4hep_version = '00-10-04'
class awkward_zipper.EDM4HEP_v00_10_05

EDM4HEP layout builder for edm4hep version 00.10.05

edm4hep_version = '00-10-05'
class awkward_zipper.EDM4HEP_v00_99_00

EDM4HEP layout builder for edm4hep version 00.99.00

edm4hep_version = '00-99-00'
class awkward_zipper.EDM4HEP_v00_99_01

EDM4HEP layout builder for edm4hep version 00.99.01

edm4hep_version = '00-99-01'
class awkward_zipper.EDM4HEP_v00_99_02

EDM4HEP layout builder for edm4hep version 00.99.02

edm4hep_version = '00-99-02'
class awkward_zipper.EDM4HEP_v00_99_03

EDM4HEP layout builder for edm4hep version 00.99.03

edm4hep_version = '00-99-03'
class awkward_zipper.EDM4HEP_v00_99_04

EDM4HEP layout builder for edm4hep version 00.99.04

edm4hep_version = '00-99-04'
class awkward_zipper.EDM4HEP_v01_00

EDM4HEP layout builder for edm4hep version 01.00

edm4hep_version = '01-00'
class awkward_zipper.EDM4HEP_v01_01

EDM4HEP layout builder for edm4hep version 01.01

edm4hep_version = '01-01'
class awkward_zipper.FCC(version='latest')[source]

Choose the required variant of the FCC layout builder.

Example usage:

from awkward_zipper import FCC
FCC.get_schema(version="latest")

Available versions:

classmethod get_schema(version='latest')[source]
class awkward_zipper.FCCSchema[source]

FCC (pre-edm4hep1) layout builder.

Array-based re-implementation of coffea’s FCCSchema, tested against the Spring2021/Winter2023 pregenerated FCC samples (https://fcc-physics-events.web.cern.ch/). These follow the edm4hep structure:

  • vector components (X.referencePoint.{x,y,z}) are zipped into X.referencePoint sub-collections,

  • *_begin/*_end range pairs are zipped, and MC parent/daughter relations get *_ranges plus global (G) indexers,

  • ObjectID branches (X#0.index/X#0.collectionID) become Xidx0 collections,

  • *_[0-9] trailing-underscore branches form their own collections,

  • the remaining X.* branches are zipped into the X collection, using momentum.{x,y,z} (+ energy) for the LorentzVector behavior.

all_cross_references: ClassVar = {'Electron#0.index': 'ReconstructedParticles', 'MCRecoAssociations#0.index': 'ReconstructedParticles', 'MCRecoAssociations#1.index': 'Particle', 'Muon#0.index': 'ReconstructedParticles'}
classmethod behavior()[source]

Behaviors necessary to implement this schema (dict)

extra_mixins: ClassVar = {'*idx': 'ObjectID'}
mc_relations: ClassVar = {'daughters': 'Particle#1.index', 'parents': 'Particle#0.index'}
class awkward_zipper.FCCSchema_edm4hep1[source]

FCC layout builder for samples produced with edm4hep >= 1.

Inherits from EDM4HEP version 00.99.01 (matching coffea’s FCCSchema_edm4hep1(EDM4HEPSchema)) and adds more functionality on top of it: the Links are also copied onto the collection they point to, with _datatype_priority choosing ReconstructedParticles among the collections sharing the ReconstructedParticle datatype (e.g. Jet).

classmethod behavior()[source]

Behaviors necessary to implement this schema (dict)

edm4hep_version = '00-99-01'
class awkward_zipper.NanoAOD(version='latest')[source]

NanoAOD layout builder

The NanoAOD layout is built from all branches found in the supplied file, based on the naming pattern of the branches. The following additional arrays are constructed:

  • Any branches named n{name} are assumed to be counts branches and converted to offsets o{name}

  • Any local index branches with names matching {source}_{target}Idx* are converted to global indexes for the event chunk (postfix G)

  • Any nested_items are constructed, if the necessary branches are available

  • Any special_items are constructed, if the necessary branches are available

From those arrays, NanoAOD collections are formed as collections of branches grouped by name, where:

  • one branch exists named name and no branches start with name_, interpreted as a single flat array;

  • one branch exists named name, one named n{name}, and no branches start with name_, interpreted as a single jagged array;

  • no branch exists named {name} and many branches start with name_*, interpreted as a flat table; or

  • one branch exists named n{name} and many branches start with name_*, interpreted as a jagged table.

Collections are assigned mixin types according to the mixins mapping. All collections are then zipped into one base.NanoEvents record and returned.

There is a class-level variable warn_missing_crossrefs which will alter the behavior of NanoAOD. If warn_missing_crossrefs is true then when a missing global index cross-ref target is encountered a warning will be issued. Regardless, the cross-reference is dropped.

The same holds for error_missing_events_id. If error_missing_events_id is true, then when the ‘run’, ‘event’, or ‘luminosityBlock’ fields are missing, an exception will be thrown; if it is false, just a warning will be issued.

alias_items: ClassVar = {'CorrT1METJet_mass': 'CorrT1METJet_rawMass', 'CorrT1METJet_pt': 'CorrT1METJet_rawPt'}

Arrays that should be aliased to ensure proper 4-vector behavior

all_cross_references: ClassVar = {'Electron_genPartIdx': 'GenPart', 'Electron_jetIdx': 'Jet', 'Electron_photonIdx': 'Photon', 'FatJet_genJetAK8Idx': 'GenJetAK8', 'FatJet_subJetIdx1': 'SubJet', 'FatJet_subJetIdx2': 'SubJet', 'FsrPhoton_muonIdx': 'Muon', 'GenPart_genPartIdxMother': 'GenPart', 'GenVisTau_genPartIdxMother': 'GenPart', 'Jet_electronIdx1': 'Electron', 'Jet_electronIdx2': 'Electron', 'Jet_genJetIdx': 'GenJet', 'Jet_muonIdx1': 'Muon', 'Jet_muonIdx2': 'Muon', 'LowPtElectron_electronIdx': 'Electron', 'LowPtElectron_genPartIdx': 'GenPart', 'LowPtElectron_photonIdx': 'Photon', 'Muon_fsrPhotonIdx': 'FsrPhoton', 'Muon_genPartIdx': 'GenPart', 'Muon_jetIdx': 'Jet', 'Photon_electronIdx': 'Electron', 'Photon_genPartIdx': 'GenPart', 'Photon_jetIdx': 'Jet', 'Tau_genPartIdx': 'GenPart', 'Tau_jetIdx': 'Jet'}

Cross-references, where an index is to be interpreted with respect to another collection

Each such cross-reference will be converted to a global indexer, so that arbitrarily sliced events can still resolve the indirection back the parent events

classmethod behavior()[source]

Behaviors necessary to implement this schema (dict)

error_missing_event_ids = True
event_ids: ClassVar = ['run', 'luminosityBlock', 'event']

List of NanoAOD event IDs

full_like_items: ClassVar = {'CorrT1METJet_mass': ('nCorrT1METJet', 0.0), 'FatJet_charge': ('nFatJet', 0.0), 'FsrPhoton_charge': ('nFsrPhoton', 0.0), 'FsrPhoton_mass': ('nFsrPhoton', 0.0), 'IsoTrack_mass': ('nIsoTrack', 0.0), 'Jet_charge': ('nJet', 0.0), 'Photon_charge': ('nPhoton', 0.0), 'Photon_mass': ('nPhoton', 0.0), 'SoftActivityJet_mass': ('nSoftActivityJet', 0.0), 'TrigObj_mass': ('nTrigObj', 0.0)}

Arrays that should be filled with constant values if not present to satisfy 4-vector requirements.

Each value is a (counts_branch, fill_value) pair; the array is built jagged from the n{collection} counts branch (mirrors coffea’s full_like_items, which uses the o{collection} offsets branch).

mixins: ClassVar = {'CaloMET': 'MissingET', 'ChsMET': 'MissingET', 'CorrT1METJet': 'PtEtaPhiMCollection', 'Electron': 'Electron', 'FatJet': 'FatJet', 'FsrPhoton': 'FsrPhoton', 'GenDressedLepton': 'PtEtaPhiMCollection', 'GenIsolatedPhoton': 'PtEtaPhiMCollection', 'GenJet': 'PtEtaPhiMCollection', 'GenJetAK8': 'PtEtaPhiMCollection', 'GenMET': 'MissingET', 'GenPart': 'GenParticle', 'GenVisTau': 'GenVisTau', 'IsoTrack': 'PtEtaPhiMCollection', 'Jet': 'Jet', 'LHEPart': 'PtEtaPhiMCollection', 'LowPtElectron': 'LowPtElectron', 'MET': 'MissingET', 'METFixEE2017': 'MissingET', 'Muon': 'Muon', 'PV': 'Vertex', 'Photon': 'Photon', 'PuppiMET': 'MissingET', 'RawMET': 'MissingET', 'RawPuppiMET': 'MissingET', 'SV': 'SecondaryVertex', 'SoftActivityJet': 'PtEtaPhiMCollection', 'SubGenJetAK8': 'PtEtaPhiMCollection', 'SubJet': 'PtEtaPhiMCollection', 'Tau': 'Tau', 'TkMET': 'MissingET', 'TrigObj': 'PtEtaPhiMCollection'}

Default configuration for mixin types, based on the collection name.

The types are implemented in the awkward_zipper.behaviors.nanoaod module.

nested_index_items: ClassVar = {'FatJet_pFCandsIdxG': ('FatJet_nConstituents', 'FatJetPFCands'), 'GenFatJet_pFCandsIdxG': ('GenJetAK8_nConstituents', 'GenFatJetCands'), 'GenJet_pFCandsIdxG': ('GenJet_nConstituents', 'GenJetCands'), 'Jet_pFCandsIdxG': ('Jet_nConstituents', 'JetPFCands')}

Nested collections, where nesting is accomplished by assuming the target can be unflattened according to a source counts

nested_items: ClassVar = {'FatJet_subJetIdxG': ['FatJet_subJetIdx1G', 'FatJet_subJetIdx2G'], 'Jet_electronIdxG': ['Jet_electronIdx1G', 'Jet_electronIdx2G'], 'Jet_muonIdxG': ['Jet_muonIdx1G', 'Jet_muonIdx2G']}

Nested collections, where nesting is accomplished by a fixed-length set of indexers

rename_items: ClassVar = {'Electron_regrEnergy': 'Electron_energy', 'Photon_regrEnergy': 'Photon_energy'}

Arrays that should be renamed to ensure proper 4-vector behavior

special_items: ClassVar = {'GenPart_childrenIdxG': (<function children>, ('nGenPart', 'GenPart_genPartIdxMotherG')), 'GenPart_distinctChildrenDeepIdxG': (<function distinct_children_deep>, ('nGenPart', 'GenPart_genPartIdxMotherG', 'GenPart_pdgId')), 'GenPart_distinctChildrenIdxG': (<function children>, ('nGenPart', 'GenPart_distinctParentIdxG')), 'GenPart_distinctParentIdxG': (<function distinct_parent>, ('GenPart_genPartIdxMotherG', 'GenPart_pdgId'))}

Special arrays, where the callable and input arrays are specified in the value

classmethod v5()[source]

Build the NanoEvents assuming NanoAODv5

Returns:

out – Schema assuming NanoAODv5

Return type:

NanoAOD

classmethod v6()[source]

Build the NanoEvents assuming NanoAODv6

Returns:

out – Schema assuming NanoAODv6

Return type:

NanoAOD

classmethod v7()[source]

Build the NanoEvents assuming NanoAODv7

For example, one can use NanoEventsFactory.from_root("file.root", schemaclass=NanoAOD.v7) to ensure NanoAODv7 compatibility.

Returns:

out – Schema assuming NanoAODv7

Return type:

NanoAOD

warn_missing_crossrefs = True
class awkward_zipper.Ntuple(version='latest')[source]

Builder for ATLAS ntuples following the typical centralized formats.

Collections are built from all branches found in the tree, based on the naming pattern of the branches, which is assumed to be

{collection:str}_{subcollection:str}_{systematic:str}

So el_pt_NOSYS is the pt subcollection of the el collection, for the nominal (NOSYS) systematic. Branches carrying a systematic variation are additionally gathered into one record per systematic, sitting alongside the nominal collections, so that events.EG_SCALE_ALL__1up.el.pt reads the varied electron transverse momentum while events.el.pt reads the nominal one.

Collections are assigned mixin types according to the mixins mapping; anything unrecognized falls back to suggested_behavior. All collections are then zipped into one base.NanoEvents record and returned.

alias_items: ClassVar = {'MissingET': {'rho': 'met'}}

fields to alias, keyed by behavior name. Maps new_field -> source_field.

classmethod behavior()[source]

Behaviors necessary to implement this schema (dict)

default_behavior: ClassVar[str] = 'NanoCollection'

default behavior to use for any collection

docstrings: ClassVar = {'charge': 'charge', 'eta': 'pseudorapidity', 'mass': 'invariant mass [MeV]', 'met': 'missing transverse energy [MeV]', 'phi': 'azimuthal angle', 'pt': 'transverse momentum [MeV]'}

docstrings to assign for specific subcollections across the collections

error_missing_event_ids: ClassVar[bool] = False

treat missing event-level branches as an error instead of a warning

event_ids: ClassVar = {'actualInteractionsPerCrossing', 'averageInteractionsPerCrossing', 'dataTakingYear', 'eventNumber', 'lumiBlock', 'mcChannelNumber', 'mcEventWeights', 'runNumber'}

all event IDs to expect in the dataset

event_ids_data: ClassVar = {'actualInteractionsPerCrossing', 'averageInteractionsPerCrossing', 'dataTakingYear', 'lumiBlock'}

event IDs to expect in data datasets

event_ids_mc: ClassVar = {'eventNumber', 'mcChannelNumber', 'mcEventWeights', 'runNumber'}

event IDs to expect in MC datasets

full_like_items: ClassVar = {'Electron': {'mass': ('pt', 0.51099895069)}, 'Muon': {'mass': ('pt', 105.6583755)}, 'Photon': {'charge': ('pt', 0.0), 'mass': ('pt', 0.0)}, 'Tau': {'mass': ('pt', 1776.93)}}

fields to materialize as full_like arrays, keyed by behavior name. Each entry maps new_field -> (source_field, fill_value).

identify_closest_behavior: ClassVar[bool] = True

determine closest behavior for a given branch, or use default_behavior

mixins: ClassVar = {'el': 'Electron', 'jet': 'Jet', 'met': 'MissingET', 'mu': 'Muon', 'pass': 'Pass', 'ph': 'Photon', 'trigPassed': 'Trigger', 'weight': 'Weight'}

mapping from collection name to the behavior to use for that collection

rename_items: ClassVar = {'Jet': {'mass': 'm'}}

fields to rename, keyed by behavior name. Maps new_field -> old_field.

singletons: ClassVar = {}

additional branches to pass through with no zipping or interpretation

classmethod suggested_behavior(key, cutoff=0.4)[source]

Suggest a behavior to use for a provided collection or branch name.

If identify_closest_behavior is False, or nothing scores above cutoff, this returns default_behavior.

classmethod v1()[source]

Build the NtupleEvents for version 1

warn_missing_crossrefs: ClassVar[bool] = True

warn when a cross-reference index or target is missing

class awkward_zipper.PDUNE[source]

ProtoDUNE-SP pduneana layout builder

The branches (named <top_object>_<a>_<b>_...) are regrouped into nested records by splitting on _. Branches whose trailing token is a coordinate (X/Y/Z or Px/Py/Pz/E) are collected into ThreeVector/LorentzVector sub-records (*3D/*4D).

This is an array-based re-implementation of coffea’s PDUNESchema.

classmethod behavior()[source]

Behaviors necessary to implement this schema (dict)

mixins: ClassVar = {'RecoBeam': 'Beam', 'Showers': 'Showers', 'Tracks': 'Tracks', 'end3D': 'ThreeVector', 'end4D': 'LorentzVector', 'reco_beam': 'RecoBeam', 'reco_daughter_allShower': 'Showers', 'reco_daughter_allTrack': 'Tracks', 'start3D': 'ThreeVector', 'start4D': 'LorentzVector', 'vtx3D': 'ThreeVector'}
top_objects: ClassVar = {'reco_beam': 'RecoBeam', 'reco_daughter_allShower': 'Showers', 'reco_daughter_allTrack': 'Tracks', 'true_beam': 'TrueBeam'}
class awkward_zipper.PFNanoAOD(version='latest')[source]

PFNano schema builder

PFNano is an extended NanoAOD format that includes PF candidates and secondary vertices More info at https://github.com/cms-jet/PFNano

all_cross_references: ClassVar = {'Electron_genPartIdx': 'GenPart', 'Electron_jetIdx': 'Jet', 'Electron_photonIdx': 'Photon', 'FatJetPFCands_jetIdx': 'FatJet', 'FatJetPFCands_pFCandsIdx': 'PFCands', 'FatJetSVs_jetIdx': 'FatJet', 'FatJetSVs_sVIdx': 'SV', 'FatJet_electronIdx3SJ': 'Electron', 'FatJet_genJetAK8Idx': 'GenJetAK8', 'FatJet_muonIdx3SJ': 'Muon', 'FatJet_subJetIdx1': 'SubJet', 'FatJet_subJetIdx2': 'SubJet', 'FsrPhoton_muonIdx': 'Muon', 'GenFatJetCands_jetIdx': 'GenJetAK8', 'GenFatJetCands_pFCandsIdx': 'GenCands', 'GenFatJetSVs_jetIdx': 'GenJetAK8', 'GenFatJetSVs_sVIdx': 'SV', 'GenJetCands_jetIdx': 'GenJet', 'GenJetCands_pFCandsIdx': 'GenCands', 'GenJetSVs_jetIdx': 'GenJet', 'GenJetSVs_sVIdx': 'SV', 'GenPart_genPartIdxMother': 'GenPart', 'GenVisTau_genPartIdxMother': 'GenPart', 'JetPFCands_jetIdx': 'Jet', 'JetPFCands_pFCandsIdx': 'PFCands', 'JetSVs_jetIdx': 'Jet', 'JetSVs_sVIdx': 'SV', 'Jet_electronIdx1': 'Electron', 'Jet_electronIdx2': 'Electron', 'Jet_genJetIdx': 'GenJet', 'Jet_muonIdx1': 'Muon', 'Jet_muonIdx2': 'Muon', 'LowPtElectron_electronIdx': 'Electron', 'LowPtElectron_genPartIdx': 'GenPart', 'LowPtElectron_photonIdx': 'Photon', 'Muon_fsrPhotonIdx': 'FsrPhoton', 'Muon_genPartIdx': 'GenPart', 'Muon_jetIdx': 'Jet', 'Photon_electronIdx': 'Electron', 'Photon_genPartIdx': 'GenPart', 'Photon_jetIdx': 'Jet', 'SubJet_subGenJetAK8Idx': 'SubGenJetAK8', 'Tau_genPartIdx': 'GenPart', 'Tau_jetIdx': 'Jet'}

Cross-references, where an index is to be interpreted with respect to another collection

Each such cross-reference will be converted to a global indexer, so that arbitrarily sliced events can still resolve the indirection back the parent events

mixins: ClassVar = {'CaloMET': 'MissingET', 'ChsMET': 'MissingET', 'CorrT1METJet': 'PtEtaPhiMCollection', 'Electron': 'Electron', 'FatJet': 'FatJet', 'FatJetPFCands': 'AssociatedPFCand', 'FatJetSVs': 'AssociatedSV', 'FsrPhoton': 'FsrPhoton', 'GenCands': 'PFCand', 'GenDressedLepton': 'PtEtaPhiMCollection', 'GenFatJetCands': 'AssociatedPFCand', 'GenFatJetSVs': 'AssociatedSV', 'GenIsolatedPhoton': 'PtEtaPhiMCollection', 'GenJet': 'PtEtaPhiMCollection', 'GenJetAK8': 'PtEtaPhiMCollection', 'GenJetCands': 'AssociatedPFCand', 'GenJetSVs': 'AssociatedSV', 'GenMET': 'MissingET', 'GenPart': 'GenParticle', 'GenVisTau': 'GenVisTau', 'IsoTrack': 'PtEtaPhiMCollection', 'Jet': 'Jet', 'JetPFCands': 'AssociatedPFCand', 'JetSVs': 'AssociatedSV', 'LHEPart': 'PtEtaPhiMCollection', 'LowPtElectron': 'LowPtElectron', 'MET': 'MissingET', 'METFixEE2017': 'MissingET', 'Muon': 'Muon', 'PFCands': 'PFCand', 'PV': 'Vertex', 'Photon': 'Photon', 'PuppiMET': 'MissingET', 'RawMET': 'MissingET', 'RawPuppiMET': 'MissingET', 'SV': 'SecondaryVertex', 'SoftActivityJet': 'PtEtaPhiMCollection', 'SubGenJetAK8': 'PtEtaPhiMCollection', 'SubJet': 'PtEtaPhiMCollection', 'Tau': 'Tau', 'TkMET': 'MissingET', 'TrigObj': 'PtEtaPhiMCollection'}

Default configuration for mixin types, based on the collection name.

The types are implemented in the awkward_zipper.behaviors.nanoaod module.

class awkward_zipper.PHYSLITE[source]

ATLAS DAOD_PHYSLITE layout builder

Array-based re-implementation of coffea’s PHYSLITESchema. Branches named <Collection>Aux[Dyn].<field> are grouped by collection (with the Analysis/Aux/AuxDyn affixes stripped) and zipped into jagged records. Split ElementLink members (link.m_persKey/link.m_persIndex) are reconstituted into sub-records, a synthetic _eventindex column is added per collection, and TrackParticle/Muon collections get their derived p/pt/tau/m fields.

classmethod behavior()[source]

Behaviors necessary to implement this schema (dict)

mixins: ClassVar = {'CombinedMuonTrackParticles': 'TrackParticle', 'Electrons': 'Electron', 'ExtrapolatedMuonTrackParticles': 'TrackParticle', 'GSFTrackParticles': 'TrackParticle', 'InDetTrackParticles': 'TrackParticle', 'Jets': 'Particle', 'MuonSpectrometerTrackParticles': 'TrackParticle', 'Muons': 'Muon', 'Photons': 'Particle', 'TauJets': 'Particle', 'TruthBoson': 'TruthParticle', 'TruthBottom': 'TruthParticle', 'TruthElectrons': 'TruthParticle', 'TruthMuons': 'TruthParticle', 'TruthNeutrinos': 'TruthParticle', 'TruthPhotons': 'TruthParticle', 'TruthTaus': 'TruthParticle', 'TruthTop': 'TruthParticle', 'egammaClusters': 'NanoCollection'}
truth_collections: ClassVar = ['TruthPhotons', 'TruthMuons', 'TruthNeutrinos', 'TruthTaus', 'TruthElectrons', 'TruthBoson', 'TruthBottom', 'TruthTop']
class awkward_zipper.ScoutingNanoAOD(version='latest')[source]

ScoutingNano schema builder

ScoutingNano is a NanoAOD format that includes Scouting objects

alias_items: ClassVar = {'CorrT1METJet_mass': 'CorrT1METJet_rawMass', 'CorrT1METJet_pt': 'CorrT1METJet_rawPt', 'MET_phi': 'MET_fiducialGenPhi', 'MET_pt': 'MET_fiducialGenPt'}

Arrays that should be aliased to ensure proper 4-vector behavior

all_cross_references: ClassVar = {'Electron_genPartIdx': 'GenPart', 'Electron_jetIdx': 'Jet', 'Electron_photonIdx': 'Photon', 'FatJet_genJetAK8Idx': 'GenJetAK8', 'FatJet_subJetIdx1': 'SubJet', 'FatJet_subJetIdx2': 'SubJet', 'FsrPhoton_muonIdx': 'Muon', 'GenPart_genPartIdxMother': 'GenPart', 'GenVisTau_genPartIdxMother': 'GenPart', 'Jet_electronIdx1': 'Electron', 'Jet_electronIdx2': 'Electron', 'Jet_genJetIdx': 'GenJet', 'Jet_muonIdx1': 'Muon', 'Jet_muonIdx2': 'Muon', 'LowPtElectron_electronIdx': 'Electron', 'LowPtElectron_genPartIdx': 'GenPart', 'LowPtElectron_photonIdx': 'Photon', 'Muon_fsrPhotonIdx': 'FsrPhoton', 'Muon_genPartIdx': 'GenPart', 'Muon_jetIdx': 'Jet', 'Photon_electronIdx': 'Electron', 'Photon_genPartIdx': 'GenPart', 'Photon_jetIdx': 'Jet', 'Tau_genPartIdx': 'GenPart', 'Tau_jetIdx': 'Jet'}

Cross-references, where an index is to be interpreted with respect to another collection

Each such cross-reference will be converted to a global indexer, so that arbitrarily sliced events can still resolve the indirection back the parent events

full_like_items: ClassVar = {'CorrT1METJet_mass': ('nCorrT1METJet', 0.0), 'FatJet_charge': ('nFatJet', 0.0), 'FsrPhoton_charge': ('nFsrPhoton', 0.0), 'FsrPhoton_mass': ('nFsrPhoton', 0.0), 'IsoTrack_mass': ('nIsoTrack', 0.0), 'Jet_charge': ('nJet', 0.0), 'Photon_charge': ('nPhoton', 0.0), 'Photon_mass': ('nPhoton', 0.0), 'ScoutingFatJet_charge': ('nScoutingFatJet', 0.0), 'ScoutingJet_charge': ('nScoutingJet', 0.0), 'ScoutingPhoton_charge': ('nScoutingPhoton', 0.0), 'ScoutingPhoton_m': ('nScoutingPhoton', 0.0), 'SoftActivityJet_mass': ('nSoftActivityJet', 0.0), 'TrigObj_mass': ('nTrigObj', 0.0)}

Arrays that should be filled with constant values if not present to satisfy 4-vector requirements.

Each value is a (counts_branch, fill_value) pair; the array is built jagged from the n{collection} counts branch (mirrors coffea’s full_like_items, which uses the o{collection} offsets branch).

mixins: ClassVar = {'CaloMET': 'MissingET', 'ChsMET': 'MissingET', 'CorrT1METJet': 'PtEtaPhiMCollection', 'Electron': 'Electron', 'FatJet': 'FatJet', 'FsrPhoton': 'FsrPhoton', 'GenDressedLepton': 'PtEtaPhiMCollection', 'GenIsolatedPhoton': 'PtEtaPhiMCollection', 'GenJet': 'PtEtaPhiMCollection', 'GenJetAK8': 'PtEtaPhiMCollection', 'GenMET': 'MissingET', 'GenPart': 'GenParticle', 'GenVisTau': 'GenVisTau', 'IsoTrack': 'PtEtaPhiMCollection', 'Jet': 'Jet', 'LHEPart': 'PtEtaPhiMCollection', 'LowPtElectron': 'LowPtElectron', 'MET': 'MissingET', 'METFixEE2017': 'MissingET', 'Muon': 'Muon', 'PV': 'Vertex', 'Photon': 'Photon', 'PuppiMET': 'MissingET', 'RawMET': 'MissingET', 'RawPuppiMET': 'MissingET', 'SV': 'SecondaryVertex', 'ScoutingElectron': 'Electron', 'ScoutingFatJet': 'FatJet', 'ScoutingJet': 'Jet', 'ScoutingMET': 'MissingET', 'ScoutingMuonNoVtx': 'Muon', 'ScoutingMuonNoVtxDisplacedVertex': 'Vertex', 'ScoutingMuonVtx': 'Muon', 'ScoutingMuonVtxDisplacedVertex': 'Vertex', 'ScoutingPhoton': 'Photon', 'ScoutingPrimaryVertex': 'Vertex', 'SoftActivityJet': 'PtEtaPhiMCollection', 'SubGenJetAK8': 'PtEtaPhiMCollection', 'SubJet': 'PtEtaPhiMCollection', 'Tau': 'Tau', 'TkMET': 'MissingET', 'TrigObj': 'PtEtaPhiMCollection'}

Default configuration for mixin types, based on the collection name.

The types are implemented in the awkward_zipper.behaviors.nanoaod module.

class awkward_zipper.TreeMaker[source]

TreeMaker layout builder

The TreeMaker layout is built from all branches found in the supplied file, based on the naming pattern of the branches. There are two steps to the generation of the array collections:

  • Objects with vector-like quantities (momentum, coordinate points) in the TreeMaker n-tuples are stored using ROOT PtEtaPhiEVector and XYZPoint classes with maximum TTree splitting. These split branches (<Object>.fCoordinates.f{Pt,Eta,Phi,E} and <Object>.fCoordinates.f{X,Y,Z}) are grouped into a single collection with the original object name, mapping the coordinate variables to the standard names used by the vector behaviors (pt, eta, phi, energy and x, y, z).

  • Extended quantities of physics objects are stored as <Object>_<variable> (e.g. Jets_jecFactor) and are merged into the collection <Object>.

Sub-collections, signalled by a <Object>_<subcol>Counts branch, are nested as doubly-jagged arrays inside their parent collection.

All collections are then zipped into one base.NanoEvents record.

classmethod behavior()[source]

Behaviors necessary to implement this schema (dict)

awkward_zipper.edm4hep_version(ver='latest')[source]

Return the EDM4HEP layout builder class for a given edm4hep.yaml version.

ver is written either as "00.99.04" or "00-99-04"; "latest" (default) selects the newest bundled version. The available versions are listed in awkward_zipper.assets.versions.

awkward_zipper.podio_collection_types(tree)[source]

Map collection name to podio dataType from the file’s podio_metadata tree.

Returns None when the file has no metadata or predates the named leaf layout (podio < 1.3 writes positional _0.._3 leaves).