Merge pull request #34 from legend-exp/dev

Add a couple more interesting examples to Kitchen Sink

docs/source/kitchen-sink.rst

@@ -34,6 +34,15 @@ or, alternatively:
 
    >>> # get only HPGe channels by mapping for "system"
    >>> geds = lmeta.channelmap(datetime.now()).map("system", unique=False).geds
+                exposures[gedet.name] += (
+                    gedet.production.mass_in_g
+                    * runinfo.livetime_in_s
+                    / 1000
+                    / 60
+                    / 60
+                    / 24
+                    / 365
+                )
    >>> # collect and sum up masses
    >>> masses = [v.production.mass_in_g for v in geds.values()]
    >>> numpy.cumsum(masses)[-1]
@@ -71,3 +80,49 @@ Which channel IDs correspond to detectors in string 1?
     ``ids`` can be directly given to
     :meth:`pygama.flow.data_loader.DataLoader.set_datastreams` to load LEGEND
     data from the channel.
+
+When did physics run 3 of LEGEND-200 period 4 start?
+----------------------------------------------------
+
+.. code-block:: python
+
+   >>> from legendmeta import to_datetime
+   >>> to_datetime(lmeta.dataprod.runinfo.p04.r003.phy.start_key)
+   datetime.datetime(2023, 5, 1, 20, 59, 51)
+
+What is the exposure of each single HPGe usable for analysis over a selection of runs?
+--------------------------------------------------------------------------------------
+
+.. code-block:: python
+   :linenos:
+
+   runs = {
+       "p03": ["r000", "r001", "r002", "r003", "r004", "r005"],
+       "p04": ["r000", "r001", "r002", "r003"],
+   }
+
+   exposures = {}
+
+   for period, v in runs.items():
+       for run in v:
+           runinfo = lmeta.dataprod.runinfo[period][run].phy
+           chmap = lmeta.channelmap(runinfo.start_key)
+
+           chmap = (
+               chmap.map("system", unique=False).geds
+               .map("analysis.usability", unique=False).on
+           )
+
+           for _, gedet in chmap.items():
+               exposures.setdefault(gedet.name, 0)
+               exposures[gedet.name] += (
+                   gedet.production.mass_in_g
+                   / 1000
+                   * runinfo.livetime_in_s
+                   / 60
+                   / 60
+                   / 24
+                   / 365
+               )
+
+   print(exposures)

src/legendmeta/__init__.py

@@ -16,8 +16,15 @@
 """A package to access `legend-metadata <https://github.com/legend-exp/legend-metadata>`_ in Python."""
 
 from legendmeta._version import version as __version__
+from legendmeta.catalog import to_datetime
 from legendmeta.core import LegendMetadata
 from legendmeta.jsondb import JsonDB
 from legendmeta.slowcontrol import LegendSlowControlDB
 
-__all__ = ["__version__", "LegendMetadata", "LegendSlowControlDB", "JsonDB"]
+__all__ = [
+    "__version__",
+    "LegendMetadata",
+    "LegendSlowControlDB",
+    "JsonDB",
+    "to_datetime",
+]

src/legendmeta/catalog.py

@@ -25,6 +25,11 @@
 from string import Template
 
 
+def to_datetime(value):
+    """Convert a LEGEND timestamp (or key) to :class:`datetime.datetime`."""
+    return datetime.strptime(value, "%Y%m%dT%H%M%SZ")
+
+
 def unix_time(value):
     if isinstance(value, str):
         return datetime.timestamp(datetime.strptime(value, "%Y%m%dT%H%M%SZ"))

tests/test_catalog.py

@@ -0,0 +1,7 @@
+from datetime import datetime
+
+from legendmeta import to_datetime
+
+
+def test_to_datetime():
+    assert to_datetime("20230501T205951Z") == datetime(2023, 5, 1, 20, 59, 51)