atlas-schema 0.2.3__tar.gz → 0.3.0__tar.gz

{atlas_schema-0.2.3 → atlas_schema-0.3.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: atlas-schema
-Version: 0.2.3
+Version: 0.3.0
 Summary: Helper python package for ATLAS Common NTuple Analysis work.
 Project-URL: Homepage, https://github.com/scipp-atlas/atlas-schema
 Project-URL: Bug Tracker, https://github.com/scipp-atlas/atlas-schema/issues
 Project-URL: Discussions, https://github.com/scipp-atlas/atlas-schema/discussions
-Project-URL: Documentation, https://atlas-schema.readthedocs.io/en/v0.2.3/
+Project-URL: Documentation, https://atlas-schema.readthedocs.io/en/v0.3.0/
 Project-URL: Releases, https://github.com/scipp-atlas/atlas-schema/releases
 Project-URL: Release Notes, https://atlas-schema.readthedocs.io/en/latest/history.html
 Author-email: Giordon Stark <kratsg@gmail.com>
@@ -227,7 +227,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering
 Classifier: Typing :: Typed
 Requires-Python: >=3.9
-Requires-Dist: coffea[dask]>=2024.4.1
+Requires-Dist: coffea[dask]>=2025.7.0
 Requires-Dist: particle>=0.25.0
 Provides-Extra: dev
 Requires-Dist: pytest-cov>=3; extra == 'dev'
@@ -251,7 +251,7 @@ Requires-Dist: tbump>=6.7.0; extra == 'test'
 Requires-Dist: twine; extra == 'test'
 Description-Content-Type: text/markdown
 
-# atlas-schema v0.2.3
+# atlas-schema v0.3.0
 
 [![Actions Status][actions-badge]][actions-link]
 [![Documentation Status][rtd-badge]][rtd-link]
@@ -335,11 +335,9 @@ like below:
 
 ```python
 import awkward as ak
-import dask
-import hist.dask as had
+from hist import Hist
 import matplotlib.pyplot as plt
 from coffea import processor
-from coffea.nanoevents import NanoEventsFactory
 from distributed import Client
 
 from atlas_schema.schema import NtupleSchema
@@ -352,7 +350,7 @@ class MyFirstProcessor(processor.ProcessorABC):
     def process(self, events):
         dataset = events.metadata["dataset"]
         h_ph_pt = (
-            had.Hist.new.StrCat(["all", "pass", "fail"], name="isEM")
+            Hist.new.StrCat(["all", "pass", "fail"], name="isEM")
             .Regular(200, 0.0, 2000.0, name="pt", label="$pt_{\gamma}$ [GeV]")
             .Int64()
         )
@@ -376,17 +374,18 @@ class MyFirstProcessor(processor.ProcessorABC):
 if __name__ == "__main__":
     client = Client()
 
-    fname = "ntuple.root"
-    events = NanoEventsFactory.from_root(
-        {fname: "analysis"},
-        schemaclass=NtupleSchema,
-        metadata={"dataset": "700352.Zqqgamma.mc20d.v1"},
-    ).events()
-
-    p = MyFirstProcessor()
-    out = p.process(events)
-    (computed,) = dask.compute(out)
-    print(computed)
+    fileset = {"700352.Zqqgamma.mc20d.v1": {"files": {"ntuple.root": "analysis"}}}
+
+    run = processor.Runner(
+        executor=processor.IterativeExecutor(compression=None),
+        schema=NtupleSchema,
+        savemetrics=True,
+    )
+
+    out, metrics = run(fileset, processor_instance=MyFirstProcessor())
+
+    print(out)
+    print(metrics)
 
     fig, ax = plt.subplots()
     computed["700352.Zqqgamma.mc20d.v1"]["ph_pt"].plot1d(ax=ax)

{atlas_schema-0.2.3 → atlas_schema-0.3.0}/README.md

@@ -1,4 +1,4 @@
-# atlas-schema v0.2.3
+# atlas-schema v0.3.0
 
 [![Actions Status][actions-badge]][actions-link]
 [![Documentation Status][rtd-badge]][rtd-link]
@@ -82,11 +82,9 @@ like below:
 
 ```python
 import awkward as ak
-import dask
-import hist.dask as had
+from hist import Hist
 import matplotlib.pyplot as plt
 from coffea import processor
-from coffea.nanoevents import NanoEventsFactory
 from distributed import Client
 
 from atlas_schema.schema import NtupleSchema
@@ -99,7 +97,7 @@ class MyFirstProcessor(processor.ProcessorABC):
     def process(self, events):
         dataset = events.metadata["dataset"]
         h_ph_pt = (
-            had.Hist.new.StrCat(["all", "pass", "fail"], name="isEM")
+            Hist.new.StrCat(["all", "pass", "fail"], name="isEM")
             .Regular(200, 0.0, 2000.0, name="pt", label="$pt_{\gamma}$ [GeV]")
             .Int64()
         )
@@ -123,17 +121,18 @@ class MyFirstProcessor(processor.ProcessorABC):
 if __name__ == "__main__":
     client = Client()
 
-    fname = "ntuple.root"
-    events = NanoEventsFactory.from_root(
-        {fname: "analysis"},
-        schemaclass=NtupleSchema,
-        metadata={"dataset": "700352.Zqqgamma.mc20d.v1"},
-    ).events()
-
-    p = MyFirstProcessor()
-    out = p.process(events)
-    (computed,) = dask.compute(out)
-    print(computed)
+    fileset = {"700352.Zqqgamma.mc20d.v1": {"files": {"ntuple.root": "analysis"}}}
+
+    run = processor.Runner(
+        executor=processor.IterativeExecutor(compression=None),
+        schema=NtupleSchema,
+        savemetrics=True,
+    )
+
+    out, metrics = run(fileset, processor_instance=MyFirstProcessor())
+
+    print(out)
+    print(metrics)
 
     fig, ax = plt.subplots()
     computed["700352.Zqqgamma.mc20d.v1"]["ph_pt"].plot1d(ax=ax)

{atlas_schema-0.2.3 → atlas_schema-0.3.0}/pyproject.toml

@@ -28,7 +28,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dynamic = ["version"]
-dependencies = ["coffea[dask] >= 2024.4.1", "particle >= 0.25.0"]
+dependencies = ["coffea[dask] >= 2025.7.0", "particle >= 0.25.0"]
 
 [project.optional-dependencies]
 test = [
@@ -60,7 +60,7 @@ docs = [
 Homepage = "https://github.com/scipp-atlas/atlas-schema"
 "Bug Tracker" = "https://github.com/scipp-atlas/atlas-schema/issues"
 Discussions = "https://github.com/scipp-atlas/atlas-schema/discussions"
-Documentation = "https://atlas-schema.readthedocs.io/en/v0.2.3/"
+Documentation = "https://atlas-schema.readthedocs.io/en/v0.3.0/"
 Releases = "https://github.com/scipp-atlas/atlas-schema/releases"
 "Release Notes" = "https://atlas-schema.readthedocs.io/en/latest/history.html"
 
@@ -111,14 +111,19 @@ addopts = [
 ]
 xfail_strict = true
 filterwarnings = [
-  "error",
+    "error",
+    "ignore:In version 2025.1.0 .*, this will be an error:FutureWarning",
 ]
+
 log_cli_level = "INFO"
 testpaths = [
   "src",
   "tests",
   "docs",
 ]
+norecursedirs = [
+  "tests/helpers"
+]
 
 [tool.coverage]
 run.source = ["atlas_schema"]

{atlas_schema-0.2.3 → atlas_schema-0.3.0}/src/atlas_schema/_version.py

@@ -1,8 +1,13 @@
-# file generated by setuptools_scm
+# file generated by setuptools-scm
 # don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
 TYPE_CHECKING = False
 if TYPE_CHECKING:
-    from typing import Tuple, Union
+    from typing import Tuple
+    from typing import Union
+
     VERSION_TUPLE = Tuple[Union[int, str], ...]
 else:
     VERSION_TUPLE = object
@@ -12,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.2.3'
-__version_tuple__ = version_tuple = (0, 2, 3)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)

{atlas_schema-0.2.3 → atlas_schema-0.3.0}/src/atlas_schema/methods.py

@@ -8,7 +8,6 @@ from operator import ior
 import awkward
 import particle
 from coffea.nanoevents.methods import base, candidate, vector
-from dask_awkward import dask_method
 
 from atlas_schema.enums import PhotonID
 from atlas_schema.typing_compat import Behavior
@@ -63,22 +62,9 @@ class Particle(vector.PtEtaPhiMLorentzVector):
     - '{obj}_select'
     """
 
-    @property
-    def mass(self):
-        r"""Invariant mass (+, -, -, -)
-
-        :math:`\sqrt{t^2-x^2-y^2-z^2}`
-        """
-        return self["mass"] / 1.0e3
-
-    @dask_method
     def passes(self, name):
         return self[f"select_{name}"] == 1
 
-    @passes.dask
-    def passes(self, dask_array, name):
-        return dask_array[f"select_{name}"] == 1
-
     # NB: fields with the name 'pt' take precedence over this
     # @dask_property
     # def pt(self):
@@ -166,8 +152,8 @@ behavior.update(awkward._util.copy_behaviors("Particle", "Electron", behavior))
 class Electron(Particle, base.NanoCollection, base.Systematic):
     @property
     def mass(self):
-        """Electron mass in GeV"""
-        return particle.literals.e_minus.mass / 1.0e3
+        """Electron mass in MeV"""
+        return awkward.ones_like(self.pt) * particle.literals.e_minus.mass
 
 
 _set_repr_name("Electron")
@@ -184,8 +170,8 @@ behavior.update(awkward._util.copy_behaviors("Particle", "Muon", behavior))
 class Muon(Particle, base.NanoCollection, base.Systematic):
     @property
     def mass(self):
-        """Muon mass in GeV"""
-        return particle.literals.mu_minus.mass / 1.0e3
+        """Muon mass in MeV"""
+        return awkward.ones_like(self.pt) * particle.literals.mu_minus.mass
 
 
 _set_repr_name("Muon")
@@ -202,8 +188,8 @@ behavior.update(awkward._util.copy_behaviors("Particle", "Tau", behavior))
 class Tau(Particle, base.NanoCollection, base.Systematic):
     @property
     def mass(self):
-        """Tau mass in GeV"""
-        return particle.literals.tau_minus.mass / 1.0e3
+        """Tau mass in MeV"""
+        return awkward.ones_like(self.pt) * particle.literals.tau_minus.mass
 
 
 _set_repr_name("Tau")
@@ -218,7 +204,14 @@ behavior.update(awkward._util.copy_behaviors("Particle", "Jet", behavior))
 
 
 @awkward.mixin_class(behavior)
-class Jet(Particle, base.NanoCollection, base.Systematic): ...
+class Jet(Particle, base.NanoCollection, base.Systematic):
+    @property
+    def mass(self):
+        r"""Invariant mass (+, -, -, -)
+
+        :math:`\sqrt{t^2-x^2-y^2-z^2}`
+        """
+        return self["m"]
 
 
 _set_repr_name("Jet")
@@ -230,12 +223,24 @@ JetArray.MomentumClass = vector.LorentzVectorArray  # noqa: F821
 
 __all__ = [
     "Electron",
+    "ElectronArray",  # noqa: F822
+    "ElectronRecord",  # noqa: F822
     "Jet",
+    "JetArray",  # noqa: F822
+    "JetRecord",  # noqa: F822
     "MissingET",
+    "MissingETArray",  # noqa: F822
+    "MissingETRecord",  # noqa: F822
     "Muon",
+    "MuonArray",  # noqa: F822
+    "MuonRecord",  # noqa: F822
     "NtupleEvents",
     "Particle",
+    "ParticleArray",  # noqa: F822
+    "ParticleRecord",  # noqa: F822
     "Pass",
     "Photon",
+    "PhotonArray",  # noqa: F822
+    "PhotonRecord",  # noqa: F822
     "Weight",
 ]

atlas_schema-0.3.0/src/atlas_schema/schema.py

@@ -0,0 +1,427 @@
+from __future__ import annotations
+
+import difflib
+import warnings
+from collections.abc import KeysView, ValuesView
+from typing import Any, ClassVar
+
+from coffea.nanoevents.schemas.base import BaseSchema, zip_forms
+
+from atlas_schema.methods import behavior as roaster
+from atlas_schema.typing_compat import Behavior, Self
+
+
+class NtupleSchema(BaseSchema):  # type: ignore[misc]
+    """The schema for building ATLAS ntuples following the typical centralized formats.
+
+    This schema is built from all branches found in a tree in the supplied
+    file, based on the naming pattern of the branches. This naming pattern is
+    typically assumed to be
+
+    .. code-block:: bash
+
+       {collection:str}_{subcollection:str}_{systematic:str}
+
+    where:
+      * ``collection`` is assumed to be a prefix with typical characters, following the regex ``[a-zA-Z][a-zA-Z0-9]*``; that is starting with a case-insensitive letter, and proceeded by zero or more alphanumeric characters,
+      * ``subcollection`` is assumed to be anything with typical characters (allowing for underscores) following the regex ``[a-zA-Z_][a-zA-Z0-9_]*``; that is starting with a case-insensitive letter or underscore, and proceeded by zero or more alphanumeric characters including underscores, and
+      * ``systematic`` is assumed to be either ``NOSYS`` to indicate a branch with potential systematic variariations, or anything with typical characters (allowing for underscores) following the same regular expression as the ``subcollection``.
+
+    Here, a collection refers to the top-level entry to access an item - a collection called ``el`` will be accessible under the ``el`` attributes via ``events['el']`` or ``events.el``. A subcollection called ``pt`` will be accessible under that collection, such as ``events['el']['pt']`` or ``events.el.pt``. This is the power of the schema providing a more user-friendly (and programmatic) access to the underlying branches.
+
+    The above logic means that the following branches below will be categorized as follows:
+
+    +-------------------------------+-------------------+-----------------------+------------------+
+    | branch                        | collection        | subcollection         | systematic       |
+    +===============================+===================+=======================+==================+
+    | ``'eventNumber'``             | ``'eventNumber'`` | ``None``              | ``None``         |
+    +-------------------------------+-------------------+-----------------------+------------------+
+    | ``'runNumber'``               | ``'runNumber'``   | ``None``              | ``None``         |
+    +-------------------------------+-------------------+-----------------------+------------------+
+    | ``'el_pt_NOSYS'``             | ``'el'``          | ``'pt'``              | ``'NOSYS'``      |
+    +-------------------------------+-------------------+-----------------------+------------------+
+    | ``'jet_cleanTightBad_NOSYS'`` | ``'jet'``         | ``'cleanTightBad'``   | ``'NOSYS'``      |
+    +-------------------------------+-------------------+-----------------------+------------------+
+    | ``'jet_select_btag_NOSYS'``   | ``'jet'``         | ``'select_btag'``     | ``'NOSYS'``      |
+    +-------------------------------+-------------------+-----------------------+------------------+
+    | ``'jet_e_NOSYS'``             | ``'jet'``         | ``'e'``               | ``'NOSYS'``      |
+    +-------------------------------+-------------------+-----------------------+------------------+
+    | ``'truthel_phi'``             | ``'truthel'``     | ``'phi'``             | ``None``         |
+    +-------------------------------+-------------------+-----------------------+------------------+
+    | ``'truthel_pt'``              | ``'truthel'``     | ``'pt'``              | ``None``         |
+    +-------------------------------+-------------------+-----------------------+------------------+
+    | ``'ph_eta'``                  | ``'ph'``          | ``'eta'``             | ``None``         |
+    +-------------------------------+-------------------+-----------------------+------------------+
+    | ``'ph_phi_SCALE__1up'``       | ``'ph'``          | ``'phi'``             | ``'SCALE__1up'`` |
+    +-------------------------------+-------------------+-----------------------+------------------+
+    | ``'mu_TTVA_effSF_NOSYS'``     | ``'mu'``          | ``'TTVA_effSF'``      | ``'NOSYS'``      |
+    +-------------------------------+-------------------+-----------------------+------------------+
+    | ``'recojet_antikt4PFlow_pt'`` | ``'recojet'``     | ``'antikt4PFlow_pt'`` | ``'NOSYS'``      |
+    +-------------------------------+-------------------+-----------------------+------------------+
+    | ``'recojet_antikt10UFO_m'``   | ``'recojet'``     | ``'antikt10UFO_m'``   | ``None``         |
+    +-------------------------------+-------------------+-----------------------+------------------+
+
+    Sometimes this logic is not what you want, and there are ways to teach ``NtupleSchema`` how to group some of these better for atypical cases. We can address these case-by-case.
+
+    **Singletons**
+
+     Sometimes you have particular branches that you don't want to be treated as a collection (with subcollections). And sometimes you will see warnings about this (see :ref:`faq`). There are some pre-defined ``singletons`` stored under :attr:`event_ids`, and these will be lazily treated as a _singleton_. For other cases where you add your own branches, you can additionally extend this class to add your own :attr:`singletons`:
+
+     .. code-block:: python
+
+        from atlas_schema.schema import NtupleSchema
+
+
+        class MySchema(NtupleSchema):
+            singletons = {"RandomRunNumber"}
+
+     and use this schema in your analysis code. The rest of the logic will be handled for you, and you can access your singletons under ``events.RandomRunNumber`` as expected.
+
+    **Mixins (collections, subcollections)**
+
+     In more complicated scenarios, you might need to teach :class:`NtupleSchema` how to handle collections that end up having underscores in their name, or other characters that make the grouping non-trivial. In some other scenarios, you want to tell the schema to assign a certain set of behaviors to a collection - rather than the default :class:`atlas_schema.methods.Particle` behavior. This is where :attr:`mixins` comes in. Similar to how :attr:`singletons` are handled, you extend this schema to include your own ``mixins`` pointing them at one of the behaviors defined in :mod:`atlas_schema.methods`.
+
+     Let's demonstrate both cases. Imagine you want to have your ``truthel`` collections above treated as :class:`atlas_schema.methods.Electron`, then you would extend the existing :attr:`mixins`:
+
+     .. code-block:: python
+
+        from atlas_schema.schema import NtupleSchema
+
+
+        class MySchema(NtupleSchema):
+            mixins = {"truthel": "Electron", **NtupleSchema.mixins}
+
+     Now, ``events.truthel`` will give you arrays zipped up with :class:`atlas_schema.methods.Electron` behaviors.
+
+     If instead, you run into problems with mixing different branches in the same collection, because the default behavior of this schema described above is not smart enough to handle the atypical cases, you can explicitly fix this by defining your collections:
+
+     .. code-block:: python
+
+        from atlas_schema.schema import NtupleSchema
+
+
+        class MySchema(NtupleSchema):
+            mixins = {
+                "recojet_antikt4PFlow": "Jet",
+                "recojet_antikt10UFO": "Jet",
+                **NtupleSchema.mixins,
+            }
+
+     Now, ``events.recojet_antikt4PFlow`` and ``events.recojet_antikt10UFO`` will be separate collections, instead of a single ``events.recojet`` that incorrectly merged branches from each of these collections.
+    """
+
+    __dask_capable__: ClassVar[bool] = True
+
+    warn_missing_crossrefs: ClassVar[bool] = True
+
+    #: Treat missing event-level branches as error instead of warning (default is ``False``)
+    error_missing_event_ids: ClassVar[bool] = False
+    #: Determine closest behavior for a given branch or treat branch as :attr:`default_behavior` (default is ``True``)
+    identify_closest_behavior: ClassVar[bool] = True
+
+    #: event IDs to expect in data datasets
+    event_ids_data: ClassVar[set[str]] = {
+        "lumiBlock",
+        "averageInteractionsPerCrossing",
+        "actualInteractionsPerCrossing",
+        "dataTakingYear",
+    }
+    #: event IDs to expect in MC datasets
+    event_ids_mc: ClassVar[set[str]] = {
+        "mcChannelNumber",
+        "runNumber",
+        "eventNumber",
+        "mcEventWeights",
+    }
+    #: all event IDs to expect in the dataset
+    event_ids: ClassVar[set[str]] = {*event_ids_data, *event_ids_mc}
+
+    #: mixins defining the mapping from collection name to behavior to use for that collection
+    mixins: ClassVar[dict[str, str]] = {
+        "el": "Electron",
+        "jet": "Jet",
+        "met": "MissingET",
+        "mu": "Muon",
+        "pass": "Pass",
+        "ph": "Photon",
+        "trigPassed": "Trigger",
+        "weight": "Weight",
+    }
+
+    #: additional branches to pass-through with no zipping or additional interpretation (such as those stored as length-1 vectors)
+    singletons: ClassVar[set[str]] = set()
+
+    #: docstrings to assign for specific subcollections across the various collections identified by this schema
+    docstrings: ClassVar[dict[str, str]] = {
+        "charge": "charge",
+        "eta": "pseudorapidity",
+        "met": "missing transverse energy [MeV]",
+        "mass": "invariant mass [MeV]",
+        "pt": "transverse momentum [MeV]",
+        "phi": "azimuthal angle",
+    }
+
+    #: default behavior to use for any collection (default ``"NanoCollection"``, from :class:`coffea.nanoevents.methods.base.NanoCollection`)
+    default_behavior: ClassVar[str] = "NanoCollection"
+
+    def __init__(self, base_form: dict[str, Any], version: str = "latest"):
+        super().__init__(base_form)
+        self._version = version
+        if version == "latest":
+            pass
+        else:
+            pass
+        self._form["fields"], self._form["contents"] = self._build_collections(
+            self._form["fields"], self._form["contents"]
+        )
+        self._form["parameters"]["metadata"]["version"] = self._version
+
+    @classmethod
+    def v1(cls, base_form: dict[str, Any]) -> Self:
+        """Build the NtupleEvents
+
+        For example, one can use ``NanoEventsFactory.from_root("file.root", schemaclass=NtupleSchema.v1)``
+        to ensure NanoAODv7 compatibility.
+        """
+        return cls(base_form, version="1")
+
+    def _build_collections(
+        self, field_names: list[str], input_contents: list[Any]
+    ) -> tuple[KeysView[str], ValuesView[dict[str, Any]]]:
+        branch_forms = dict(zip(field_names, input_contents))
+
+        # parse into high-level records (collections, list collections, and singletons)
+        collections = {
+            k.split("_")[0] for k in branch_forms if k not in self.singletons
+        }
+        collections -= self.event_ids
+        collections -= set(self.singletons)
+
+        # now handle any collections that we identified that are substrings of the items in the mixins
+        # convert all valid branch_forms into strings to make the lookups a bit faster
+        bf_str = ",".join(branch_forms.keys())
+        for mixin in self.mixins:
+            if mixin in collections:
+                continue
+            if f",{mixin}_" not in bf_str and not bf_str.startswith(f"{mixin}_"):
+                continue
+            if "_" in mixin:
+                warnings.warn(
+                    f"I identified a mixin that I did not automatically identify as a collection because it contained an underscore: '{mixin}'. I will add this to the known collections. To suppress this warning next time, please create your ntuples with collections without underscores. [mixin-underscore]",
+                    RuntimeWarning,
+                    stacklevel=2,
+                )
+            collections.add(mixin)
+            for collection in list(collections):
+                if mixin.startswith(f"{collection}_"):
+                    warnings.warn(
+                        f"I found a misidentified collection: '{collection}'. I will remove this from the known collections. To suppress this warning next time, please create your ntuples with collections that are not similarly named with underscores. [collection-subset]",
+                        RuntimeWarning,
+                        stacklevel=2,
+                    )
+                    collections.remove(collection)
+                    break
+
+        # rename needed because easyjet breaks the AMG assumptions
+        # https://gitlab.cern.ch/easyjet/easyjet/-/issues/246
+        for k in list(branch_forms):
+            if "NOSYS" not in k:
+                continue
+            branch_forms[k.replace("_NOSYS", "") + "_NOSYS"] = branch_forms.pop(k)
+
+        # these are collections with systematic variations
+        try:
+            subcollections = {
+                k.split("__")[0].split("_", 1)[1].replace("_NOSYS", "")
+                for k in branch_forms
+                if "NOSYS" in k and k not in self.singletons
+            }
+        except IndexError as exc:
+            msg = "One of the branches does not follow the assumed pattern for this schema. [invalid-branch-name]"
+            raise RuntimeError(msg) from exc
+
+        # Check the presence of the event_ids
+        missing_event_ids = [
+            event_id for event_id in self.event_ids if event_id not in branch_forms
+        ]
+
+        missing_singletons = [
+            singleton for singleton in self.singletons if singleton not in branch_forms
+        ]
+
+        if len(missing_event_ids) > 0:
+            if self.error_missing_event_ids:
+                msg = f"There are missing event ID fields: {missing_event_ids} \n\n\
+                    The event ID fields {self.event_ids} are necessary to perform sub-run identification \
+                    (e.g. for corrections and sub-dividing data during different detector conditions),\
+                    to cross-validate MC and Data (i.e. matching events for comparison), and to generate event displays. \
+                    It's advised to never drop these branches from the dataformat.\n\n\
+                    This error can be demoted to a warning by setting the class level variable error_missing_event_ids to False."
+                raise RuntimeError(msg)
+            warnings.warn(
+                f"Missing event_ids : {missing_event_ids}",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+
+        if len(missing_singletons) > 0:
+            # These singletons are simply branches we do not parse or handle
+            # explicitly in atlas-schema (e.g. they are copied directly to the
+            # output structure we provide you), however there can be false
+            # positives when you submit multiple files with different branch
+            # structures and this warning could be safely ignored.
+            warnings.warn(
+                f"Missing singletons : {missing_singletons}. [singleton-missing]",
+                RuntimeWarning,
+                stacklevel=2,
+            )
+
+        output = {}
+
+        # first, register singletons (event-level, others)
+        for name in {*self.event_ids, *self.singletons}:
+            if name in [*missing_event_ids, *missing_singletons]:
+                continue
+
+            output[name] = branch_forms[name]
+
+        # next, go through and start grouping up collections
+        for name in collections:
+            content = {}
+            used = set()
+
+            for subname in subcollections:
+                prefix = f"{name}_{subname}_"
+                used.update({k for k in branch_forms if k.startswith(prefix)})
+                subcontent = {
+                    k[len(prefix) :]: branch_forms[k]
+                    for k in branch_forms
+                    if k.startswith(prefix)
+                }
+                if subcontent:
+                    # create the nominal version
+                    content[subname] = branch_forms[f"{prefix}NOSYS"]
+                    # create a collection of the systematic variations for the given variable
+                    content[f"{subname}_syst"] = zip_forms(
+                        subcontent, f"{name}_syst", record_name="NanoCollection"
+                    )
+
+            content.update(
+                {
+                    k[len(name) + 1 :]: branch_forms[k]
+                    for k in branch_forms
+                    if k.startswith(name + "_") and k not in used
+                }
+            )
+
+            if not used and not content:
+                warnings.warn(
+                    f"I identified a branch that likely does not have any leaves: '{name}'. I will treat this as a 'singleton'. To suppress this warning next time, please define your singletons explicitly. [singleton-undefined]",
+                    RuntimeWarning,
+                    stacklevel=2,
+                )
+                self.singletons.add(name)
+                output[name] = branch_forms[name]
+
+            else:
+                behavior = self.mixins.get(name, "")
+                if not behavior:
+                    behavior = self.suggested_behavior(name)
+                    warnings.warn(
+                        f"I found a collection with no defined mixin: '{name}'. I will assume behavior: '{behavior}'. To suppress this warning next time, please define mixins for your custom collections. [mixin-undefined]",
+                        RuntimeWarning,
+                        stacklevel=2,
+                    )
+
+                output[name] = zip_forms(content, name, record_name=behavior)
+
+            output[name].setdefault("parameters", {})
+            output[name]["parameters"].update({"collection_name": name})
+
+            if output[name]["class"] == "ListOffsetArray":
+                if output[name]["class"] == "RecordArray":
+                    parameters = output[name]["content"]["fields"]
+                    contents = output[name]["content"]["contents"]
+                else:
+                    # these are also singletons of another kind that we just pass through
+                    continue
+            elif output[name]["class"] == "RecordArray":
+                parameters = output[name]["fields"]
+                contents = output[name]["contents"]
+            elif output[name]["class"] == "NumpyArray":
+                # these are singletons that we just pass through
+                continue
+            else:
+                msg = f"Unhandled class {output[name]['class']}"
+                raise RuntimeError(msg)
+
+            # update docstrings as needed
+            # NB: must be before flattening for easier logic
+            for index, parameter in enumerate(parameters):
+                if "parameters" not in contents[index]:
+                    continue
+
+                parsed_name = parameter.replace("_NOSYS", "")
+                contents[index]["parameters"]["__doc__"] = self.docstrings.get(
+                    parsed_name,
+                    contents[index]["parameters"].get(
+                        "__doc__", "no docstring available"
+                    ),
+                )
+
+        return output.keys(), output.values()
+
+    @classmethod
+    def behavior(cls) -> Behavior:
+        """Behaviors necessary to implement this schema
+
+        Returns:
+            dict[str | tuple['*', str], type[awkward.Record]]: an :data:`awkward.behavior` dictionary
+        """
+        return roaster
+
+    @classmethod
+    def suggested_behavior(cls, key: str, cutoff: float = 0.4) -> str:
+        """
+        Suggest e behavior to use for a provided collection or branch name.
+
+        Default behavior: :class:`~coffea.nanoevents.methods.base.NanoCollection`.
+
+        Note:
+            If :attr:`identify_closest_behavior` is ``False``, then this function will return the default behavior ``NanoCollection``.
+
+        Warning:
+            If no behavior is found above the *cutoff* score, then this function will return the default behavior.
+
+        Args:
+            key (str): collection name to suggest a matching behavior for
+            cutoff (float): o ptional argument cutoff (default ``0.4``) is a float in the range ``[0, 1]``. Possibilities that don't score at least that similar to *key* are ignored.
+
+        Returns:
+            str: suggested behavior to use by string
+
+        Example:
+            >>> from atlas_schema.schema import NtupleSchema
+            >>> NtupleSchema.suggested_behavior("truthjet")
+            'Jet'
+            >>> NtupleSchema.suggested_behavior("SignalElectron")
+            'Electron'
+            >>> NtupleSchema.suggested_behavior("generatorWeight")
+            'Weight'
+            >>> NtupleSchema.suggested_behavior("aVeryStrangelyNamedBranchWithNoMatch")
+            'NanoCollection'
+        """
+        if cls.identify_closest_behavior:
+            # lowercase everything to do case-insensitive matching
+            behaviors = [b for b in cls.behavior() if isinstance(b, str)]
+            behaviors_l = [b.lower() for b in behaviors]
+            results = difflib.get_close_matches(
+                key.lower(), behaviors_l, n=1, cutoff=cutoff
+            )
+            if not results:
+                return cls.default_behavior
+
+            behavior = results[0]
+            # need to identify the index and return the unlowered version
+            return behaviors[behaviors_l.index(behavior)]
+        return cls.default_behavior

{atlas_schema-0.2.3 → atlas_schema-0.3.0}/src/atlas_schema/typing_compat.py

@@ -5,7 +5,7 @@ Typing helpers.
 from __future__ import annotations
 
 import sys
-from typing import Annotated
+from typing import Annotated, Literal, Union
 
 import awkward
 
@@ -19,6 +19,6 @@ if sys.version_info >= (3, 11):
 else:
     from typing_extensions import Self
 
-Behavior: TypeAlias = dict[str, type[awkward.Record]]
+Behavior: TypeAlias = dict[Union[str, tuple[Literal["*"]], str], type[awkward.Record]]
 
 __all__ = ("Annotated", "Behavior", "Self")

{atlas_schema-0.2.3 → atlas_schema-0.3.0}/src/atlas_schema/utils.py

@@ -1,16 +1,15 @@
 from __future__ import annotations
 
 from enum import Enum
-from typing import TypeVar, Union, cast
+from typing import TypeVar, cast
 
 import awkward as ak
-import dask_awkward as dak
 
-Array = TypeVar("Array", bound=Union[dak.Array, ak.Array])
+Array = TypeVar("Array", bound=ak.Array)
 _E = TypeVar("_E", bound=Enum)
 
 
-def isin(element: Array, test_elements: dak.Array | ak.Array, axis: int = -1) -> Array:
+def isin(element: Array, test_elements: ak.Array, axis: int = -1) -> Array:
     """
     Find test_elements in element. Similar in API as :func:`numpy.isin`.
 
@@ -21,12 +20,12 @@ def isin(element: Array, test_elements: dak.Array | ak.Array, axis: int = -1) ->
     comparison.
 
     Args:
-        element (dak.Array or ak.Array): input array of values.
-        test_elements (dak.Array or ak.Array): one-dimensional set of values against which to test each value of *element*.
+        element (ak.Array): input array of values.
+        test_elements (ak.Array): one-dimensional set of values against which to test each value of *element*.
         axis (int): the axis along which the comparison is performed
 
     Returns:
-        dak.Array or ak.Array: result of comparison for test_elements in *element*
+        ak.Array: result of comparison for test_elements in *element*
 
     Example:
         >>> import awkward as ak

atlas_schema-0.2.3/src/atlas_schema/schema.py

@@ -1,214 +0,0 @@
-from __future__ import annotations
-
-import warnings
-from collections.abc import KeysView, ValuesView
-from typing import Any, ClassVar
-
-from coffea.nanoevents.schemas.base import BaseSchema, zip_forms
-
-from atlas_schema.typing_compat import Behavior, Self
-
-
-class NtupleSchema(BaseSchema):  # type: ignore[misc]
-    """Ntuple schema builder
-
-    The Ntuple schema is built from all branches found in the supplied file, based on
-    the naming pattern of the branches. The following additional arrays are constructed:
-
-    - n/a
-    """
-
-    __dask_capable__ = True
-
-    warn_missing_crossrefs = True
-    error_missing_event_ids = False
-
-    event_ids_data: ClassVar[set[str]] = {
-        "lumiBlock",
-        "averageInteractionsPerCrossing",
-        "actualInteractionsPerCrossing",
-        "dataTakingYear",
-    }
-    event_ids_mc: ClassVar[set[str]] = {
-        "mcChannelNumber",
-        "runNumber",
-        "eventNumber",
-        "mcEventWeights",
-    }
-    event_ids: ClassVar[set[str]] = {*event_ids_data, *event_ids_mc}
-
-    mixins: ClassVar[dict[str, str]] = {
-        "el": "Electron",
-        "jet": "Jet",
-        "met": "MissingET",
-        "mu": "Muon",
-        "pass": "Pass",
-        "ph": "Photon",
-        "trigPassed": "Trigger",
-        "weight": "Weight",
-    }
-
-    # These are stored as length-1 vectors unnecessarily
-    singletons: ClassVar[set[str]] = set()
-
-    docstrings: ClassVar[dict[str, str]] = {
-        "charge": "charge",
-        "eta": "pseudorapidity",
-        "met": "missing transverse energy [MeV]",
-        "mass": "invariant mass [MeV]",
-        "pt": "transverse momentum [MeV]",
-        "phi": "azimuthal angle",
-    }
-
-    def __init__(self, base_form: dict[str, Any], version: str = "latest"):
-        super().__init__(base_form)
-        self._version = version
-        if version == "latest":
-            pass
-        else:
-            pass
-        self._form["fields"], self._form["contents"] = self._build_collections(
-            self._form["fields"], self._form["contents"]
-        )
-        self._form["parameters"]["metadata"]["version"] = self._version
-
-    @classmethod
-    def v1(cls, base_form: dict[str, Any]) -> Self:
-        """Build the NtupleEvents
-
-        For example, one can use ``NanoEventsFactory.from_root("file.root", schemaclass=NtupleSchema.v1)``
-        to ensure NanoAODv7 compatibility.
-        """
-        return cls(base_form, version="1")
-
-    def _build_collections(
-        self, field_names: list[str], input_contents: list[Any]
-    ) -> tuple[KeysView[str], ValuesView[dict[str, Any]]]:
-        branch_forms = dict(zip(field_names, input_contents))
-
-        # parse into high-level records (collections, list collections, and singletons)
-        collections = {k.split("_")[0] for k in branch_forms}
-        collections -= self.event_ids
-        collections -= set(self.singletons)
-
-        # rename needed because easyjet breaks the AMG assumptions
-        # https://gitlab.cern.ch/easyjet/easyjet/-/issues/246
-        for k in list(branch_forms):
-            if "NOSYS" not in k:
-                continue
-            branch_forms[k.replace("_NOSYS", "") + "_NOSYS"] = branch_forms.pop(k)
-
-        # these are collections with systematic variations
-        subcollections = {
-            k.split("__")[0].split("_", 1)[1].replace("_NOSYS", "")
-            for k in branch_forms
-            if "NOSYS" in k
-        }
-
-        # Check the presence of the event_ids
-        missing_event_ids = [
-            event_id for event_id in self.event_ids if event_id not in branch_forms
-        ]
-
-        if len(missing_event_ids) > 0:
-            if self.error_missing_event_ids:
-                msg = f"There are missing event ID fields: {missing_event_ids} \n\n\
-                    The event ID fields {self.event_ids} are necessary to perform sub-run identification \
-                    (e.g. for corrections and sub-dividing data during different detector conditions),\
-                    to cross-validate MC and Data (i.e. matching events for comparison), and to generate event displays. \
-                    It's advised to never drop these branches from the dataformat.\n\n\
-                    This error can be demoted to a warning by setting the class level variable error_missing_event_ids to False."
-                raise RuntimeError(msg)
-            warnings.warn(
-                f"Missing event_ids : {missing_event_ids}",
-                RuntimeWarning,
-                stacklevel=2,
-            )
-
-        output = {}
-
-        # first, register singletons (event-level, others)
-        for name in {*self.event_ids, *self.singletons}:
-            if name in missing_event_ids:
-                continue
-            output[name] = branch_forms[name]
-
-        # next, go through and start grouping up collections
-        for name in collections:
-            mixin = self.mixins.get(name, "NanoCollection")
-            content = {}
-            used = set()
-
-            for subname in subcollections:
-                prefix = f"{name}_{subname}_"
-                used.update({k for k in branch_forms if k.startswith(prefix)})
-                subcontent = {
-                    k[len(prefix) :]: branch_forms[k]
-                    for k in branch_forms
-                    if k.startswith(prefix)
-                }
-                if subcontent:
-                    # create the nominal version
-                    content[subname] = branch_forms[f"{prefix}NOSYS"]
-                    # create a collection of the systematic variations for the given variable
-                    content[f"{subname}_syst"] = zip_forms(
-                        subcontent, f"{name}_syst", record_name="NanoCollection"
-                    )
-
-            content.update(
-                {
-                    k[len(name) + 1 :]: branch_forms[k]
-                    for k in branch_forms
-                    if k.startswith(name + "_") and k not in used
-                }
-            )
-
-            if not used and not content:
-                warnings.warn(
-                    f"I identified a branch that likely does not have any leaves: '{name}'. I will treat this as a 'singleton'. To suppress this warning next time, please define your singletons explicitly.",
-                    RuntimeWarning,
-                    stacklevel=2,
-                )
-                self.singletons.add(name)
-                output[name] = branch_forms[name]
-
-            else:
-                output[name] = zip_forms(content, name, record_name=mixin)
-
-            output[name].setdefault("parameters", {})
-            output[name]["parameters"].update({"collection_name": name})
-
-            if output[name]["class"] == "ListOffsetArray":
-                parameters = output[name]["content"]["fields"]
-                contents = output[name]["content"]["contents"]
-            elif output[name]["class"] == "RecordArray":
-                parameters = output[name]["fields"]
-                contents = output[name]["contents"]
-            elif output[name]["class"] == "NumpyArray":
-                # these are singletons that we just pass through
-                continue
-            else:
-                msg = f"Unhandled class {output[name]['class']}"
-                raise RuntimeError(msg)
-            # update docstrings as needed
-            # NB: must be before flattening for easier logic
-            for index, parameter in enumerate(parameters):
-                if "parameters" not in contents[index]:
-                    continue
-
-                parsed_name = parameter.replace("_NOSYS", "")
-                contents[index]["parameters"]["__doc__"] = self.docstrings.get(
-                    parsed_name,
-                    contents[index]["parameters"].get(
-                        "__doc__", "no docstring available"
-                    ),
-                )
-
-        return output.keys(), output.values()
-
-    @classmethod
-    def behavior(cls) -> Behavior:
-        """Behaviors necessary to implement this schema"""
-        from atlas_schema.methods import behavior as roaster
-
-        return roaster