awkward_zipper.layouts

awkward_zipper.layouts.atlas

Layout builder for ATLAS ntuples (the atlas-schema NtupleSchema)

class awkward_zipper.layouts.atlas.Ntuple(version='latest')

Bases: BaseLayoutBuilder

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()

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)

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()

Build the NtupleEvents for version 1

warn_missing_crossrefs: ClassVar[bool] = True

warn when a cross-reference index or target is missing

awkward_zipper.layouts.base

class awkward_zipper.layouts.base.BaseLayoutBuilder

Bases: object

Base class for all layout builders

classmethod behavior()

Behaviors necessary to implement this schema (dict)

awkward_zipper.layouts.delphes

class awkward_zipper.layouts.delphes.Delphes(version='latest')

Bases: BaseLayoutBuilder

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()

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()

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

awkward_zipper.layouts.edm4hep

class awkward_zipper.layouts.edm4hep.EDM4HEP

Bases: BaseLayoutBuilder

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()

Behaviors necessary to implement this schema (dict)

copy_links_to_target_datatype = False

edm4hep_version = '01-01'

extra_mixins: ClassVar = {'*idx': 'ObjectID'}

classmethod version(ver='latest')

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.layouts.edm4hep.EDM4HEP_v00_10_01

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 00.10.01

edm4hep_version = '00-10-01'

class awkward_zipper.layouts.edm4hep.EDM4HEP_v00_10_02

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 00.10.02

edm4hep_version = '00-10-02'

class awkward_zipper.layouts.edm4hep.EDM4HEP_v00_10_03

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 00.10.03

edm4hep_version = '00-10-03'

class awkward_zipper.layouts.edm4hep.EDM4HEP_v00_10_04

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 00.10.04

edm4hep_version = '00-10-04'

class awkward_zipper.layouts.edm4hep.EDM4HEP_v00_10_05

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 00.10.05

edm4hep_version = '00-10-05'

class awkward_zipper.layouts.edm4hep.EDM4HEP_v00_99_00

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 00.99.00

edm4hep_version = '00-99-00'

class awkward_zipper.layouts.edm4hep.EDM4HEP_v00_99_01

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 00.99.01

edm4hep_version = '00-99-01'

class awkward_zipper.layouts.edm4hep.EDM4HEP_v00_99_02

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 00.99.02

edm4hep_version = '00-99-02'

class awkward_zipper.layouts.edm4hep.EDM4HEP_v00_99_03

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 00.99.03

edm4hep_version = '00-99-03'

class awkward_zipper.layouts.edm4hep.EDM4HEP_v00_99_04

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 00.99.04

edm4hep_version = '00-99-04'

class awkward_zipper.layouts.edm4hep.EDM4HEP_v01_00

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 01.00

edm4hep_version = '01-00'

class awkward_zipper.layouts.edm4hep.EDM4HEP_v01_01

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 01.01

edm4hep_version = '01-01'

awkward_zipper.layouts.edm4hep.edm4hep_version(ver='latest')

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.layouts.edm4hep.load_edm4hep(version)

Load and parse the edm4hep yaml for a version, caching the result.

The returned (raw, parsed) dicts are treated as read-only by the builder, so a single parse is shared across all builds for a given version.

awkward_zipper.layouts.edm4hep.parse_members_and_relations(members_and_relation_list, target_text=False)

Convert the raw yaml Members/Relations lists into a workable mapping.

awkward_zipper.layouts.edm4hep.parse_yaml(loaded_dict, parsed_dict)

Post-process the loaded edm4hep yaml into the structure the builder needs.

awkward_zipper.layouts.edm4hep.podio_collection_types(tree)

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).

awkward_zipper.layouts.edm4hep.sort_dict(d)

awkward_zipper.layouts.fcc

class awkward_zipper.layouts.fcc.FCC(version='latest')

Bases: object

Choose the required variant of the FCC layout builder.

Example usage:

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

Available versions:

• "latest" -> FCCSchema_edm4hep1

• "pre-edm4hep1" -> FCCSchema

• "edm4hep1" -> FCCSchema_edm4hep1

classmethod get_schema(version='latest')

class awkward_zipper.layouts.fcc.FCCSchema

Bases: BaseLayoutBuilder

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()

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.layouts.fcc.FCCSchema_edm4hep1

Bases: EDM4HEP

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()

Behaviors necessary to implement this schema (dict)

copy_links_to_target_datatype = True

edm4hep_version = '00-99-01'

awkward_zipper.layouts.nanoaod

class awkward_zipper.layouts.nanoaod.NanoAOD(version='latest')

Bases: BaseLayoutBuilder

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()

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()

Build the NanoEvents assuming NanoAODv5

Returns:

out – Schema assuming NanoAODv5

Return type:

NanoAOD

classmethod v6()

Build the NanoEvents assuming NanoAODv6

Returns:

out – Schema assuming NanoAODv6

Return type:

NanoAOD

classmethod v7()

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.layouts.nanoaod.PFNanoAOD(version='latest')

Bases: NanoAOD

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.layouts.nanoaod.ScoutingNanoAOD(version='latest')

Bases: NanoAOD

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.

awkward_zipper.layouts.pdune

class awkward_zipper.layouts.pdune.PDUNE

Bases: BaseLayoutBuilder

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()

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'}

awkward_zipper.layouts.physlite

class awkward_zipper.layouts.physlite.PHYSLITE

Bases: BaseLayoutBuilder

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()

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']

awkward_zipper.layouts.treemaker

class awkward_zipper.layouts.treemaker.TreeMaker

Bases: BaseLayoutBuilder

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()

Behaviors necessary to implement this schema (dict)

Module contents

class awkward_zipper.layouts.BaseLayoutBuilder

Bases: object

Base class for all layout builders

classmethod behavior()

Behaviors necessary to implement this schema (dict)

class awkward_zipper.layouts.Delphes(version='latest')

Bases: BaseLayoutBuilder

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()

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()

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

class awkward_zipper.layouts.EDM4HEP

Bases: BaseLayoutBuilder

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()

Behaviors necessary to implement this schema (dict)

copy_links_to_target_datatype = False

edm4hep_version = '01-01'

extra_mixins: ClassVar = {'*idx': 'ObjectID'}

classmethod version(ver='latest')

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.layouts.EDM4HEP_v00_10_01

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 00.10.01

edm4hep_version = '00-10-01'

class awkward_zipper.layouts.EDM4HEP_v00_10_02

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 00.10.02

edm4hep_version = '00-10-02'

class awkward_zipper.layouts.EDM4HEP_v00_10_03

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 00.10.03

edm4hep_version = '00-10-03'

class awkward_zipper.layouts.EDM4HEP_v00_10_04

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 00.10.04

edm4hep_version = '00-10-04'

class awkward_zipper.layouts.EDM4HEP_v00_10_05

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 00.10.05

edm4hep_version = '00-10-05'

class awkward_zipper.layouts.EDM4HEP_v00_99_00

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 00.99.00

edm4hep_version = '00-99-00'

class awkward_zipper.layouts.EDM4HEP_v00_99_01

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 00.99.01

edm4hep_version = '00-99-01'

class awkward_zipper.layouts.EDM4HEP_v00_99_02

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 00.99.02

edm4hep_version = '00-99-02'

class awkward_zipper.layouts.EDM4HEP_v00_99_03

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 00.99.03

edm4hep_version = '00-99-03'

class awkward_zipper.layouts.EDM4HEP_v00_99_04

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 00.99.04

edm4hep_version = '00-99-04'

class awkward_zipper.layouts.EDM4HEP_v01_00

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 01.00

edm4hep_version = '01-00'

class awkward_zipper.layouts.EDM4HEP_v01_01

Bases: EDM4HEP

EDM4HEP layout builder for edm4hep version 01.01

edm4hep_version = '01-01'

class awkward_zipper.layouts.FCC(version='latest')

Bases: object

Choose the required variant of the FCC layout builder.

Example usage:

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

Available versions:

• "latest" -> FCCSchema_edm4hep1

• "pre-edm4hep1" -> FCCSchema

• "edm4hep1" -> FCCSchema_edm4hep1

classmethod get_schema(version='latest')

class awkward_zipper.layouts.FCCSchema

Bases: BaseLayoutBuilder

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()

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.layouts.FCCSchema_edm4hep1

Bases: EDM4HEP

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()

Behaviors necessary to implement this schema (dict)

copy_links_to_target_datatype = True

edm4hep_version = '00-99-01'

class awkward_zipper.layouts.NanoAOD(version='latest')

Bases: BaseLayoutBuilder

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()

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()

Build the NanoEvents assuming NanoAODv5

Returns:

out – Schema assuming NanoAODv5

Return type:

NanoAOD

classmethod v6()

Build the NanoEvents assuming NanoAODv6

Returns:

out – Schema assuming NanoAODv6

Return type:

NanoAOD

classmethod v7()

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.layouts.PDUNE

Bases: BaseLayoutBuilder

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()

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.layouts.PFNanoAOD(version='latest')

Bases: NanoAOD

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.layouts.PHYSLITE

Bases: BaseLayoutBuilder

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()

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.layouts.ScoutingNanoAOD(version='latest')

Bases: NanoAOD

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.layouts.TreeMaker

Bases: BaseLayoutBuilder

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()

Behaviors necessary to implement this schema (dict)

awkward_zipper.layouts.edm4hep_version(ver='latest')

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.layouts.podio_collection_types(tree)

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).