atlas-schema 0.2.3__py3-none-any.whl → 0.2.4__py3-none-any.whl

atlas_schema/_version.py

@@ -12,5 +12,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.2.4'
+__version_tuple__ = version_tuple = (0, 2, 4)

atlas_schema/methods.py

@@ -230,12 +230,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/schema.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import difflib
 import warnings
 from collections.abc import KeysView, ValuesView
 from typing import Any, ClassVar
@@ -10,33 +11,131 @@ from atlas_schema.typing_compat import Behavior, Self
 
 
 class NtupleSchema(BaseSchema):  # type: ignore[misc]
-    """Ntuple schema builder
+    """The schema for building ATLAS ntuples following the typical centralized formats.
 
-    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:
+    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
 
-    - n/a
+    .. 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__ = True
+    __dask_capable__: ClassVar[bool] = True
+
+    warn_missing_crossrefs: ClassVar[bool] = True
 
-    warn_missing_crossrefs = True
-    error_missing_event_ids = False
+    #: 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",
@@ -48,9 +147,10 @@ class NtupleSchema(BaseSchema):  # type: ignore[misc]
         "weight": "Weight",
     }
 
-    # These are stored as length-1 vectors unnecessarily
+    #: 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",
@@ -60,6 +160,9 @@ class NtupleSchema(BaseSchema):  # type: ignore[misc]
         "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
@@ -91,6 +194,31 @@ class NtupleSchema(BaseSchema):  # type: ignore[misc]
         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):
@@ -135,7 +263,6 @@ class NtupleSchema(BaseSchema):  # type: ignore[misc]
 
         # next, go through and start grouping up collections
         for name in collections:
-            mixin = self.mixins.get(name, "NanoCollection")
             content = {}
             used = set()
 
@@ -165,7 +292,7 @@ class NtupleSchema(BaseSchema):  # type: ignore[misc]
 
             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.",
+                    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,
                 )
@@ -173,14 +300,27 @@ class NtupleSchema(BaseSchema):  # type: ignore[misc]
                 output[name] = branch_forms[name]
 
             else:
-                output[name] = zip_forms(content, name, record_name=mixin)
+                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":
-                parameters = output[name]["content"]["fields"]
-                contents = output[name]["content"]["contents"]
+                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"]
@@ -190,6 +330,7 @@ class NtupleSchema(BaseSchema):  # type: ignore[misc]
             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):
@@ -208,7 +349,57 @@ class NtupleSchema(BaseSchema):  # type: ignore[misc]
 
     @classmethod
     def behavior(cls) -> Behavior:
-        """Behaviors necessary to implement this schema"""
+        """Behaviors necessary to implement this schema
+
+        Returns:
+            dict[str | tuple['*', str], type[awkward.Record]]: an :data:`awkward.behavior` dictionary
+        """
         from atlas_schema.methods import behavior as roaster
 
         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/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/utils.py

@@ -21,12 +21,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 (dask_awkward.Array or ak.Array): input array of values.
+        test_elements (dask_awkward.Array or 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*
+        dask_awkward.Array or ak.Array: result of comparison for test_elements in *element*
 
     Example:
         >>> import awkward as ak

{atlas_schema-0.2.3.dist-info → atlas_schema-0.2.4.dist-info}/METADATA

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: atlas-schema
-Version: 0.2.3
+Version: 0.2.4
 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.2.4/
 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>
@@ -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.2.4
 
 [![Actions Status][actions-badge]][actions-link]
 [![Documentation Status][rtd-badge]][rtd-link]

atlas_schema-0.2.4.dist-info/RECORD

@@ -0,0 +1,13 @@
+atlas_schema/__init__.py,sha256=ebY-rTiwSGnfvt1yWATze2GE7K3fVgJj6fT64Sl4sH8,469
+atlas_schema/_version.py,sha256=4gL0W4-u58XR5lRLpeoIPrGhcewTk0-527de6uTNmkg,411
+atlas_schema/_version.pyi,sha256=j5kbzfm6lOn8BzASXWjGIA1yT0OlHTWqlbyZ8Si_o0E,118
+atlas_schema/enums.py,sha256=hwgOvFBmITNxL0MQkrNpbiPv9VMezFoE-eyGgjzem8E,3688
+atlas_schema/methods.py,sha256=hFdtKXnyCcx4M05WhAM24fKwzEhh_ubA7jNa6_xv67k,7238
+atlas_schema/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+atlas_schema/schema.py,sha256=4OAvuPrOds-taVES32y4K8dvNDf8PKdu83DZqAlTdp8,20621
+atlas_schema/typing_compat.py,sha256=3G8h4WfLoDmrtWZvtYKLCwEpCQ_O4Fwygb2WlDRSE4E,488
+atlas_schema/utils.py,sha256=IqMbWqq0ib_kZdJCaM5ghURZatmb8pKidlewx3dpy0A,2164
+atlas_schema-0.2.4.dist-info/METADATA,sha256=KZDH5fsZon5wFXuU-iSUeqgjoplOwAoqTM1I9LgaTiM,20107
+atlas_schema-0.2.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+atlas_schema-0.2.4.dist-info/licenses/LICENSE,sha256=snem82NV8fgAi4DKaaUIfReaM5RqIWbH5OOXOvy40_w,11344
+atlas_schema-0.2.4.dist-info/RECORD,,

atlas_schema-0.2.3.dist-info/RECORD

@@ -1,13 +0,0 @@
-atlas_schema/__init__.py,sha256=ebY-rTiwSGnfvt1yWATze2GE7K3fVgJj6fT64Sl4sH8,469
-atlas_schema/_version.py,sha256=AaQEeqeDwmZAHoPuwg2C0ulADePbIYLSFanZzt0cytQ,411
-atlas_schema/_version.pyi,sha256=j5kbzfm6lOn8BzASXWjGIA1yT0OlHTWqlbyZ8Si_o0E,118
-atlas_schema/enums.py,sha256=hwgOvFBmITNxL0MQkrNpbiPv9VMezFoE-eyGgjzem8E,3688
-atlas_schema/methods.py,sha256=K7u6HGKXrtpMg7jjCjKPwIEnknOShUH4HQ1ibKBzkZ0,6832
-atlas_schema/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-atlas_schema/schema.py,sha256=s3bcSa5DH5iILPD_2BD3co8MSTsXNs1rYBmn44388Kc,8082
-atlas_schema/typing_compat.py,sha256=RwkxiiYbXO9yxkeaL8CdRaOHH7wq6vO_epg1YD7RbRs,439
-atlas_schema/utils.py,sha256=spk7KIMBbXSPpZBTltyxaHWvyitkEGSVldfuKFoyavk,2137
-atlas_schema-0.2.3.dist-info/METADATA,sha256=xtXdXa-9ra8TTtZSXLycUKPvBLPzXCIPa5cueuv0w90,20107
-atlas_schema-0.2.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-atlas_schema-0.2.3.dist-info/licenses/LICENSE,sha256=snem82NV8fgAi4DKaaUIfReaM5RqIWbH5OOXOvy40_w,11344
-atlas_schema-0.2.3.dist-info/RECORD,,