reboost 0.6.2__py3-none-any.whl → 0.7.0__py3-none-any.whl

reboost/hpge/utils.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
-from typing import Callable, NamedTuple
+from collections.abc import Callable
+from typing import NamedTuple
 
 import lgdo
 import numpy as np

reboost/iterator.py

@@ -107,7 +107,10 @@ class GLMIterator:
             glm_n_rows = self.sto.read_n_rows(f"glm/{self.lh5_group}", self.glm_file)
 
         # get the number of stp rows
-        stp_n_rows = self.sto.read_n_rows(f"{self.stp_field}/{self.lh5_group}", self.stp_file)
+        try:
+            stp_n_rows = self.sto.read_n_rows(f"{self.stp_field}/{self.lh5_group}", self.stp_file)
+        except Exception:
+            stp_n_rows = 0
 
         # heuristics for a good buffer length
         if self.use_glm:

reboost/math/stats.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import logging
-from typing import Callable
+from collections.abc import Callable
 
 import awkward as ak
 import numpy as np
@@ -111,7 +111,7 @@ def gaussian_sample(mu: ArrayLike, sigma: ArrayLike | float, *, seed: int | None
         sigma = sigma.view_as("np")
     elif isinstance(sigma, ak.Array):
         sigma = sigma.to_numpy()
-    elif not isinstance(sigma, (float, int, np.ndarray)):
+    elif not isinstance(sigma, float | int | np.ndarray):
         sigma = np.array(sigma)
 
     rng = np.random.default_rng(seed=seed)  # Create a random number generator

reboost/optmap/cli.py

@@ -162,7 +162,7 @@ def optical_cli() -> None:
     convolve_parser.add_argument(
         "--material",
         action="store",
-        choices=("lar", "pen", "fib"),
+        choices=("lar", "pen", "fiber"),
         default="lar",
         help="default: %(default)s",
     )

reboost/optmap/convolve.py

@@ -2,17 +2,20 @@ from __future__ import annotations
 
 import logging
 import re
+from typing import NamedTuple
 
+import awkward as ak
 import legendoptics.scintillate as sc
 import numba
 import numpy as np
-import pint
-from legendoptics import lar
+from legendoptics import fibers, lar, pen
 from lgdo import lh5
 from lgdo.lh5 import LH5Iterator
 from lgdo.types import Array, Histogram, Table
 from numba import njit, prange
 from numpy.lib.recfunctions import structured_to_unstructured
+from numpy.typing import NDArray
+from pint import Quantity
 
 from .numba_pdg import numba_pdgid_funcs
 
@@ -23,7 +26,16 @@ OPTMAP_ANY_CH = -1
 OPTMAP_SUM_CH = -2
 
 
-def open_optmap(optmap_fn: str):
+class OptmapForConvolve(NamedTuple):
+    """A loaded optmap for convolving."""
+
+    detids: NDArray
+    detidx: NDArray
+    edges: NDArray
+    weights: NDArray
+
+
+def open_optmap(optmap_fn: str) -> OptmapForConvolve:
     maps = lh5.ls(optmap_fn)
     # only accept _<number> (/all is read separately)
     det_ntuples = [m for m in maps if re.match(r"_\d+$", m)]
@@ -37,7 +49,7 @@ def open_optmap(optmap_fn: str):
     ow = np.empty((detidx.shape[0] + 2, *optmap_all.weights.nda.shape), dtype=np.float64)
     # 0, ..., len(detidx)-1 AND OPTMAP_ANY_CH might be negative.
     ow[OPTMAP_ANY_CH] = optmap_all.weights.nda
-    for i, nt in zip(detidx, det_ntuples):
+    for i, nt in zip(detidx, det_ntuples, strict=True):
         optmap = lh5.read(f"/{nt}/p_det", optmap_fn)
         assert isinstance(optmap, Histogram)
         ow[i] = optmap.weights.nda
@@ -69,15 +81,35 @@ def open_optmap(optmap_fn: str):
         if np.isfinite(optmap_multi_det_exp):
             msg = f"found finite _hitcounts_exp {optmap_multi_det_exp} which is not supported any more"
             raise RuntimeError(msg)
-    except KeyError:  # the _hitcounts_exp might not be always present.
+    except lh5.exceptions.LH5DecodeError:  # the _hitcounts_exp might not be always present.
         pass
 
-    return detids, detidx, optmap_edges, ow
+    return OptmapForConvolve(detids, detidx, optmap_edges, ow)
+
+
+def open_optmap_single(optmap_fn: str, spm_det_uid: int) -> OptmapForConvolve:
+    try:
+        # check the exponent from the optical map file
+        optmap_multi_det_exp = lh5.read("/_hitcounts_exp", optmap_fn).value
+        assert isinstance(optmap_multi_det_exp, float)
+        if np.isfinite(optmap_multi_det_exp):
+            msg = f"found finite _hitcounts_exp {optmap_multi_det_exp} which is not supported any more"
+            raise RuntimeError(msg)
+    except lh5.exceptions.LH5DecodeError:  # the _hitcounts_exp might not be always present.
+        pass
+
+    optmap = lh5.read(f"/_{spm_det_uid}/p_det", optmap_fn)
+    assert isinstance(optmap, Histogram)
+    ow = np.empty((1, *optmap.weights.nda.shape), dtype=np.float64)
+    ow[0] = optmap.weights.nda
+    optmap_edges = tuple([b.edges for b in optmap.binning])
+
+    return OptmapForConvolve(np.array([spm_det_uid]), np.array([0]), optmap_edges, ow)
 
 
 def iterate_stepwise_depositions(
     edep_df: np.rec.recarray,
-    optmap_for_convolve,
+    optmap: OptmapForConvolve,
     scint_mat_params: sc.ComputedScintParams,
     rng: np.random.Generator = None,
     dist: str = "poisson",
@@ -95,7 +127,17 @@ def iterate_stepwise_depositions(
 
     rng = np.random.default_rng() if rng is None else rng
     output_map, res = _iterate_stepwise_depositions(
-        edep_df, x0, x1, rng, *optmap_for_convolve, scint_mat_params, dist, mode
+        edep_df,
+        x0,
+        x1,
+        rng,
+        optmap.detids,
+        optmap.detidx,
+        optmap.edges,
+        optmap.weights,
+        scint_mat_params,
+        dist,
+        mode,
     )
     if res["any_no_stats"] > 0 or res["det_no_stats"] > 0:
         log.warning(
@@ -120,6 +162,78 @@ def iterate_stepwise_depositions(
     return output_map
 
 
+def iterate_stepwise_depositions_pois(
+    edep_hits: ak.Array,
+    optmap: OptmapForConvolve,
+    scint_mat_params: sc.ComputedScintParams,
+    det_uid: int,
+    map_scaling: float = 1,
+    rng: np.random.Generator | None = None,
+):
+    if edep_hits.particle.ndim == 1:
+        msg = "the pe processors only support already reshaped output"
+        raise ValueError(msg)
+
+    rng = np.random.default_rng() if rng is None else rng
+    res, output_list = _iterate_stepwise_depositions_pois(
+        edep_hits,
+        rng,
+        np.where(optmap.detids == det_uid)[0][0],
+        map_scaling,
+        optmap.edges,
+        optmap.weights,
+        scint_mat_params,
+    )
+
+    # convert the numba result back into an awkward array.
+    builder = ak.ArrayBuilder()
+    for r in output_list:
+        with builder.list():
+            for a in r:
+                builder.extend(a)
+
+    if res["det_no_stats"] > 0:
+        log.warning(
+            "had edep out in voxels without stats: %d",
+            res["det_no_stats"],
+        )
+    if res["oob"] > 0:
+        log.warning(
+            "had edep out of map bounds: %d (%.2f%%)",
+            res["oob"],
+            (res["oob"] / (res["ib"] + res["oob"])) * 100,
+        )
+    log.debug(
+        "VUV_primary %d ->hits %d (%.2f %% primaries detected in this channel)",
+        res["vuv_primary"],
+        res["hits"],
+        (res["hits"] / res["vuv_primary"]) * 100,
+    )
+    return builder.snapshot()
+
+
+def iterate_stepwise_depositions_scintillate(
+    edep_hits: ak.Array,
+    scint_mat_params: sc.ComputedScintParams,
+    rng: np.random.Generator | None = None,
+    mode: str = "no-fano",
+):
+    if edep_hits.particle.ndim == 1:
+        msg = "the pe processors only support already reshaped output"
+        raise ValueError(msg)
+
+    rng = np.random.default_rng() if rng is None else rng
+    output_list = _iterate_stepwise_depositions_scintillate(edep_hits, rng, scint_mat_params, mode)
+
+    # convert the numba result back into an awkward array.
+    builder = ak.ArrayBuilder()
+    for r in output_list:
+        with builder.list():
+            builder.extend(r)
+
+    return builder.snapshot()
+
+
 _pdg_func = numba_pdgid_funcs()
 
 
@@ -318,6 +432,117 @@ def _iterate_stepwise_depositions(
     return output_map, stats
 
 
+# - run with NUMBA_FULL_TRACEBACKS=1 NUMBA_BOUNDSCHECK=1 for testing/checking
+# - cache=True does not work with outer prange, i.e. loading the cached file fails (numba bug?)
+# - the output dictionary is not threadsafe, so parallel=True is not working with it.
+@njit(parallel=False, nogil=True, cache=True)
+def _iterate_stepwise_depositions_pois(
+    edep_hits,
+    rng,
+    detidx: int,
+    map_scaling: float,
+    optmap_edges,
+    optmap_weights,
+    scint_mat_params: sc.ComputedScintParams,
+):
+    pdgid_map = {}
+    oob = ib = ph_cnt = ph_det2 = det_no_stats = 0  # for statistics
+    output_list = []
+
+    for rowid in range(len(edep_hits)):  # iterate hits
+        hit = edep_hits[rowid]
+        hit_output = []
+
+        assert len(hit.particle) == len(hit.num_scint_ph)
+        # iterate steps inside the hit
+        for si in range(len(hit.particle)):
+            loc = np.array([hit.xloc[si], hit.yloc[si], hit.zloc[si]])
+            # coordinates -> bins of the optical map.
+            bins = np.empty(3, dtype=np.int64)
+            for j in range(3):
+                bins[j] = np.digitize(loc[j], optmap_edges[j])
+                # normalize all out-of-bounds bins just to one end.
+                if bins[j] == optmap_edges[j].shape[0]:
+                    bins[j] = 0
+
+            # note: subtract 1 from bins, to account for np.digitize output.
+            cur_bins = (bins[0] - 1, bins[1] - 1, bins[2] - 1)
+            if cur_bins[0] == -1 or cur_bins[1] == -1 or cur_bins[2] == -1:
+                oob += 1
+                continue  # out-of-bounds of optmap
+            ib += 1
+
+            # get probabilities from map.
+            detp = optmap_weights[detidx, cur_bins[0], cur_bins[1], cur_bins[2]] * map_scaling
+            if detp < 0.0:
+                det_no_stats += 1
+                continue
+
+            pois_cnt = rng.poisson(lam=hit.num_scint_ph[si] * detp)
+            ph_cnt += hit.num_scint_ph[si]
+            ph_det2 += pois_cnt
+
+            # get the particle information.
+            particle = hit.particle[si]
+            if particle not in pdgid_map:
+                pdgid_map[particle] = (_pdgid_to_particle(particle), _pdg_func.charge(particle))
+            part, _charge = pdgid_map[particle]
+
+            # get time spectrum.
+            # note: we assume "immediate" propagation after scintillation.
+            scint_times = sc.scintillate_times(scint_mat_params, part, pois_cnt, rng) + hit.time[si]
+
+            hit_output.append(scint_times)
+
+        output_list.append(hit_output)
+
+    stats = {
+        "oob": oob,
+        "ib": ib,
+        "vuv_primary": ph_cnt,
+        "hits": ph_det2,
+        "det_no_stats": det_no_stats,
+    }
+    return stats, output_list
+
+
+# - run with NUMBA_FULL_TRACEBACKS=1 NUMBA_BOUNDSCHECK=1 for testing/checking
+# - cache=True does not work with outer prange, i.e. loading the cached file fails (numba bug?)
+@njit(parallel=False, nogil=True, cache=True)
+def _iterate_stepwise_depositions_scintillate(
+    edep_hits, rng, scint_mat_params: sc.ComputedScintParams, mode: str
+):
+    pdgid_map = {}
+    output_list = []
+
+    for rowid in range(len(edep_hits)):  # iterate hits
+        hit = edep_hits[rowid]
+        hit_output = []
+
+        # iterate steps inside the hit
+        for si in range(len(hit.particle)):
+            # get the particle information.
+            particle = hit.particle[si]
+            if particle not in pdgid_map:
+                pdgid_map[particle] = (_pdgid_to_particle(particle), _pdg_func.charge(particle))
+            part, _charge = pdgid_map[particle]
+
+            # do the scintillation.
+            num_phot = sc.scintillate_numphot(
+                scint_mat_params,
+                part,
+                hit.edep[si],
+                rng,
+                emission_term_model=("poisson" if mode == "no-fano" else "normal_fano"),
+            )
+            hit_output.append(num_phot)
+
+        assert len(hit_output) == len(hit.particle)
+        output_list.append(hit_output)
+
+    return output_list
+
+
 def get_output_table(output_map):
     ph_count_o = 0
     for _rawid, (_evtid, det, _times) in output_map.items():
@@ -342,25 +567,12 @@ def convolve(
     map_file: str,
     edep_file: str,
     edep_path: str,
-    material: str,
+    material: str | tuple[sc.ScintConfig, tuple[Quantity, ...]],
     output_file: str | None = None,
     buffer_len: int = int(1e6),
     dist_mode: str = "poisson+no-fano",
 ):
-    if material not in ["lar", "pen"]:
-        msg = f"unknown material {material} for scintillation"
-        raise ValueError(msg)
-
-    if material == "lar":
-        scint_mat_params = sc.precompute_scintillation_params(
-            lar.lar_scintillation_params(),
-            lar.lar_lifetimes().as_tuple(),
-        )
-    elif material == "pen":
-        scint_mat_params = sc.precompute_scintillation_params(
-            lar.pen_scintillation_params(),
-            (1 * pint.get_application_registry().ns),  # dummy!
-        )
+    scint_mat_params = _get_scint_params(material)
 
     # special handling of distributions and flags.
     dist, mode = dist_mode.split("+")
@@ -379,7 +591,7 @@ def convolve(
     it = LH5Iterator(edep_file, edep_path, buffer_len=buffer_len)
 
     for it_count, edep_lgdo in enumerate(it):
-        edep_df = edep_lgdo.view_as("pd").to_records()
+        edep_df = _reflatten_scint_vov(edep_lgdo.view_as("ak")).to_numpy()
 
         log.info("start event processing (%d)", it_count)
         output_map = iterate_stepwise_depositions(
@@ -393,3 +605,37 @@ def convolve(
         )
         if output_file is not None:
             lh5.write(tbl, "optical", lh5_file=output_file, group="stp", wo_mode="append")
+
+
+def _reflatten_scint_vov(arr: ak.Array) -> ak.Array:
+    if all(arr[f].ndim == 1 for f in ak.fields(arr)):
+        return arr
+
+    group_num = ak.num(arr["edep"]).to_numpy()
+    flattened = {
+        f: ak.flatten(arr[f]) if arr[f].ndim > 1 else np.repeat(arr[f].to_numpy(), group_num)
+        for f in ak.fields(arr)
+    }
+    return ak.Array(flattened)
+
+
+def _get_scint_params(material: str):
+    if material == "lar":
+        return sc.precompute_scintillation_params(
+            lar.lar_scintillation_params(),
+            lar.lar_lifetimes().as_tuple(),
+        )
+    if material == "pen":
+        return sc.precompute_scintillation_params(
+            pen.pen_scintillation_params(),
+            (pen.pen_scint_timeconstant(),),
+        )
+    if material == "fiber":
+        return sc.precompute_scintillation_params(
+            fibers.fiber_core_scintillation_params(),
+            (fibers.fiber_wls_timeconstant(),),
+        )
+    if isinstance(material, str):
+        msg = f"unknown material {material} for scintillation"
+        raise ValueError(msg)
+    return sc.precompute_scintillation_params(*material)

reboost/optmap/create.py

@@ -4,8 +4,9 @@ import copy
 import gc
 import logging
 import multiprocessing as mp
+from collections.abc import Callable
 from pathlib import Path
-from typing import Callable, Literal
+from typing import Literal
 
 import numpy as np
 import scipy.optimize

reboost/optmap/optmap.py

@@ -112,7 +112,7 @@ class OpticalMap:
         idx = np.zeros(xyz.shape[1], np.int64)  # bin indices for flattened array
         oor_mask = np.ones(xyz.shape[1], np.bool_)  # mask to remove out of range values
         dims = range(xyz.shape[0])
-        for col, ax, s, dim in zip(xyz, self.binning, self._single_stride, dims):
+        for col, ax, s, dim in zip(xyz, self.binning, self._single_stride, dims, strict=True):
             assert ax.is_range
             assert ax.closedleft
             oor_mask &= (ax.first <= col) & (col < ax.last)
@@ -326,4 +326,4 @@ class OpticalMap:
         assert all(isinstance(b, np.ndarray) for b in e1)
         assert all(isinstance(b, np.ndarray) for b in e2)
 
-        return len(e1) == len(e2) and all(np.all(x1 == x2) for x1, x2 in zip(e1, e2))
+        return all(np.all(x1 == x2) for x1, x2 in zip(e1, e2, strict=True))

reboost/shape/cluster.py

@@ -97,9 +97,9 @@ def cluster_by_step_length(
 
     pos = np.vstack(
         [
-            ak.flatten(pos_x).to_numpy(),
-            ak.flatten(pos_y).to_numpy(),
-            ak.flatten(pos_z).to_numpy(),
+            ak.flatten(pos_x).to_numpy().astype(np.float64),
+            ak.flatten(pos_y).to_numpy().astype(np.float64),
+            ak.flatten(pos_z).to_numpy().astype(np.float64),
         ]
     ).T
 
@@ -164,7 +164,7 @@ def cluster_by_distance_numba(
         return np.sqrt(np.sum((a - b) ** 2))
 
     n = len(local_index)
-    out = np.zeros(n, dtype=numba.int32)
+    out = np.zeros((n,), dtype=numba.int32)
 
     trackid_prev = -1
     pos_prev = np.zeros(3, dtype=numba.float64)

reboost/spms/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .pe import detected_photoelectrons, emitted_scintillation_photons, load_optmap
+
+__all__ = ["detected_photoelectrons", "emitted_scintillation_photons", "load_optmap"]

reboost/spms/pe.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import logging
+
+import awkward as ak
+from lgdo import VectorOfVectors
+
+from ..optmap import convolve
+from ..units import units_conv_ak
+
+log = logging.getLogger(__name__)
+
+
+def load_optmap_all(map_file: str) -> convolve.OptmapForConvolve:
+    """Load an optical map file for later use with :py:func:`detected_photoelectrons`."""
+    return convolve.open_optmap(map_file)
+
+
+def load_optmap(map_file: str, spm_det_uid: int) -> convolve.OptmapForConvolve:
+    """Load an optical map file for later use with :py:func:`detected_photoelectrons`."""
+    return convolve.open_optmap_single(map_file, spm_det_uid)
+
+
+def detected_photoelectrons(
+    num_scint_ph: ak.Array,
+    particle: ak.Array,
+    time: ak.Array,
+    xloc: ak.Array,
+    yloc: ak.Array,
+    zloc: ak.Array,
+    optmap: convolve.OptmapForConvolve,
+    material: str,
+    spm_detector_uid: int,
+    map_scaling: float = 1,
+) -> VectorOfVectors:
+    """Derive the number of detected photoelectrons (p.e.) from scintillator hits using an optical map.
+
+    Parameters
+    ----------
+    num_scint_ph
+        array of emitted scintillation photons, as generated by
+        :func:`emitted_scintillation_photons`.
+    particle
+        array of particle PDG IDs of scintillation events.
+    time
+        array of timestamps of scintillation events.
+    xloc
+        array of x coordinate position of scintillation events.
+    yloc
+        array of y coordinate position of scintillation events.
+    zloc
+        array of z coordinate position of scintillation events.
+    optmap
+        the optical map loaded via py:func:`load_optmap`.
+    material
+        scintillating material name.
+    spm_detector_uid
+        SiPM detector uid as used in the optical map.
+    map_scaling
+        scale the detection probability in the map for this detector by this factor.
+    """
+    hits = ak.Array(
+        {
+            "num_scint_ph": num_scint_ph,
+            "particle": particle,
+            "time": units_conv_ak(time, "ns"),
+            "xloc": units_conv_ak(xloc, "m"),
+            "yloc": units_conv_ak(yloc, "m"),
+            "zloc": units_conv_ak(zloc, "m"),
+        }
+    )
+
+    scint_mat_params = convolve._get_scint_params(material)
+    pe = convolve.iterate_stepwise_depositions_pois(
+        hits, optmap, scint_mat_params, spm_detector_uid, map_scaling
+    )
+
+    return VectorOfVectors(pe, attrs={"units": "ns"})
+
+
+def emitted_scintillation_photons(
+    edep: ak.Array, particle: ak.Array, material: str
+) -> VectorOfVectors:
+    """Derive the number of emitted scintillation photons from scintillator hits.
+
+    Parameters
+    ----------
+    edep
+        array of deposited energy in scintillation events.
+    particle
+        array of particle PDG IDs of scintillation events.
+    material
+        scintillating material name.
+    """
+    hits = ak.Array({"edep": units_conv_ak(edep, "keV"), "particle": particle})
+
+    scint_mat_params = convolve._get_scint_params(material)
+    ph = convolve.iterate_stepwise_depositions_scintillate(hits, scint_mat_params)
+    return VectorOfVectors(ph)

reboost/units.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import logging
 from typing import Any
 
+import awkward as ak
 import pint
 import pyg4ometry as pg4
 from lgdo import LGDO
@@ -16,7 +17,7 @@ ureg = pint.get_application_registry()
 ureg.formatter.default_format = "~P"
 
 
-def pg4_to_pint(obj) -> pint.Quantity:
+def pg4_to_pint(obj: pint.Quantity | pg4.gdml.Defines.VectorBase) -> pint.Quantity:
     """Convert pyg4ometry object to pint Quantity."""
     if isinstance(obj, pint.Quantity):
         return obj
@@ -26,32 +27,54 @@ def pg4_to_pint(obj) -> pint.Quantity:
     raise ValueError(msg)
 
 
-def units_convfact(data: Any, target_units: pint.Units) -> float:
+def units_convfact(data: Any | LGDO | ak.Array, target_units: pint.Unit | str) -> float:
     """Calculate numeric conversion factor to reach `target_units`.
 
     Parameters
     ----------
     data
-        starting data structure. If an LGDO, try to determine units by peeking
-        into its attributes. Otherwise, just return 1.
+        starting data structure. If an :class:`LGDO` or :class:`ak.Array`, try to
+        determine units by peeking into its attributes. Otherwise, just return 1.
     target_units
         units you wish to convert data to.
     """
     if isinstance(data, LGDO) and "units" in data.attrs:
         return ureg(data.attrs["units"]).to(target_units).magnitude
+    if isinstance(data, ak.Array) and "units" in ak.parameters(data):
+        return ureg(ak.parameters(data)["units"]).to(target_units).magnitude
     return 1
 
 
-def unwrap_lgdo(data: Any, library: str = "ak") -> tuple(Any, pint.Unit | None):
+def units_conv_ak(data: Any | LGDO | ak.Array, target_units: pint.Unit | str) -> ak.Array:
+    """Calculate numeric conversion factor to reach `target_units`, and apply to data converted to ak.
+
+    Parameters
+    ----------
+    data
+        starting data structure. If an :class:`LGDO` or :class:`ak.Array`, try to
+        determine units by peeking into its attributes. Otherwise, return the data
+        unchanged.
+    target_units
+        units you wish to convert data to.
+    """
+    fact = units_convfact(data, target_units)
+    if isinstance(data, LGDO) and fact != 1:
+        return ak.without_parameters(data.view_as("ak") * fact)
+    if isinstance(data, ak.Array) and fact != 1:
+        return ak.without_parameters(data * fact)
+    return data.view_as("ak") if isinstance(data, LGDO) else data
+
+
+def unwrap_lgdo(data: Any | LGDO | ak.Array, library: str = "ak") -> tuple[Any, pint.Unit | None]:
     """Return a view of the data held by the LGDO and its physical units.
 
     Parameters
     ----------
     data
-        the data container. If not an LGDO, it will be returned as is with
-        ``None`` units.
+        the data container. If not an :class:`LGDO` or :class:`ak.Array`, it will be
+        returned as is with ``None`` units.
     library
-        forwarded to :func:`lgdo.view_as`.
+        forwarded to :meth:`LGDO.view_as`.
 
     Returns
     -------
@@ -64,6 +87,15 @@ def unwrap_lgdo(data: Any, library: str = "ak") -> tuple(Any, pint.Unit | None):
         if "units" in data.attrs:
             ret_units = ureg(data.attrs["units"]).u
 
+    if isinstance(data, ak.Array):
+        if library != "ak":
+            msg = "cannot unwrap an awkward array as a non-awkward type"
+            raise ValueError(msg)
+
+        if "units" in ak.parameters(data):
+            ret_units = ureg(ak.parameters(data)["units"]).u
+            ret_data = ak.without_parameters(data)
+
     return ret_data, ret_units