RelativeLogNormalize

class RelativeLogNormalize(keys=('time',), scale=50.0, max_val=4000.0, out_min=-1.0, out_max=1.0)

Bases: object

Per-event relative log normalization (e.g. for hit times).

For each key in keys, subtracts the per-event minimum, clips to [0, max_val], applies log1p(x / scale) normalized by log1p(max_val / scale), then maps onto [out_min, out_max]. Useful for trigger-offset-removed timing where only relative spacing matters. Raises ValueError if a requested key is missing. Registered as RelativeLogNormalize — use this string as the type in a transform=[...] config list.

Parameters:

• keys (tuple) – Keys to transform; a single string is wrapped into a tuple. Defaults to ("time",).

• scale (float) – Log soft-knee scale (log1p(x / scale)); must be positive. Defaults to 50.0.

• max_val (float) – Upper clip applied before the log; must be positive. Defaults to 4000.0.

• out_min (float) – Lower bound of the output range. Defaults to -1.0.

• out_max (float) – Upper bound of the output range; must exceed out_min. Defaults to 1.0.

Example

>>> import numpy as np
>>> data = {"time": np.array([[100.], [150.], [4100.]], dtype="f4")}
>>> RelativeLogNormalize(keys=("time",), scale=50.0)(data)["time"].round(3)
array([[-1.   ],
       [-0.685],
       [ 1.   ]], dtype=float32)  # per-event min->-1, clipped max->+1

relative_log_transform(x)