Skip to content

pyhiperta.calibration

Calibration of R0 data: going from 2 gain ADC counts to number of photo-electrons.

Functions:

Name Description
calibrate

Apply pedestal and gain calibration to waveforms.
select_channel

Select values to use in waveforms high/low gain and corresponding gains and pedestals based on threshold.

calibrate 

calibrate(waveform, gains, pedestals)

Apply pedestal and gain calibration to waveforms.

Parameters:

Name Type Description Default
waveform ndarray

Batch or single video samples of the shower events. Shape: (N_batch, N_frames, N_pixels)

 required
gains ndarray

For each waveform, the gains to apply to each pixel. The same gain is applied for all frames of a shower pixel. Shape: (N_batch, N_pixels).

 required
pedestals ndarray

For each waveform, the pedestals to apply to each pixel. The same pedestal is applied for all frames of a shower pixel. Shape (N_batch, N_pixels)

 required

Returns:

Type Description
ndarray

Calibrated waveforms (number of photo-electrons). Shape is identical to waveform.
Source code in src/pyhiperta/calibration.py 
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
def calibrate(waveform: np.ndarray, gains: np.ndarray, pedestals: np.ndarray) -> np.ndarray:
    """Apply pedestal and gain calibration to waveforms.

    Parameters
    ----------
    waveform : np.ndarray
        Batch or single video samples of the shower events. Shape: (N_batch, N_frames, N_pixels)
    gains : np.ndarray
        For each waveform, the gains to apply to each pixel. The same gain is applied for all
        frames of a shower pixel. Shape: (N_batch, N_pixels).
    pedestals : np.ndarray
        For each waveform, the pedestals to apply to each pixel. The same pedestal is applied for
        all frames of a shower pixel. Shape (N_batch, N_pixels)

    Returns
    -------
    np.ndarray
        Calibrated waveforms (number of photo-electrons). Shape is identical to `waveform`.
    """
    return (waveform - pedestals[..., np.newaxis, :]) * gains[..., np.newaxis, :]

select_channel 

select_channel(waveform_high, waveform_low, gains, pedestals, window_integration_correction, threshold)

Select values to use in waveforms high/low gain and corresponding gains and pedestals based on threshold.

The choice is independent per shower and per pixel, but shared in time for a given pixel: For each pixel, if any value of waveform_high is above threshold then the low gain and corresponding waveform channel and pedestal is chosen. Otherwise the high gain is chosen.

Parameters:

Name Type Description Default
waveform_high ndarray

R0 waveform high gain. Shape: (N_batch, N_frames, N_pixels)

 required
waveform_low ndarray

R0 waveform low gain. Shape: (N_batch, N_frames, N_pixels)

 required
gains ndarray

Per-pixel high and low gains. gains[0] is high gain, gains[1] is low gains. shape (2, N_pixels)

 required
pedestals ndarray

Per-pixel pedestal for low and high gains. pedestals[0] corresponds to high gain, pedestals[1] corresponds to low gain. Shape (2, N_pixels)

 required
window_integration_correction ndarray

Array of shape (2,) containing the correction to apply after a windowed integration, for each gain.

 required
threshold float

Threshold to chose the waveform channel. A value above threshold indicates that the high gain waveform saturated and low gain should be used.

 required

Returns:

Type Description
Tuple[ndarray, ndarray, ndarray, ndarray]

The waveform selected from each gains based on threshold, associated gains, pedestals and integration correction to used. The order is: - waveform : np.ndarray waveform where the appropriate gain has been selected. Shape (N_batch, N_frames, N_pixels) - gains : np.ndarray Gain to use to calibrate waveform (high gain when waveform_high wasn't above threshold and low gain otherwise). Shape (N_batch, N_pixels) - pedestals : np.ndarray Pedestals to use to calibrate waveform. Shape (N_batch, N_pixels) - window_integration_correction : np.ndarray Correction to use after the integration. Shape(N_batch, N_pixels)
Source code in src/pyhiperta/calibration.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
def select_channel(
    waveform_high: np.ndarray,
    waveform_low: np.ndarray,
    gains: np.ndarray,
    pedestals: np.ndarray,
    window_integration_correction: np.ndarray,
    threshold: float,
) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
    """Select values to use in waveforms high/low gain and corresponding gains and pedestals based on threshold.

    The choice is independent per shower and per pixel, but shared in time for a given pixel:
    For each pixel, if any value of `waveform_high` is above `threshold` then the low gain and
    corresponding waveform channel and pedestal is chosen. Otherwise the high gain is chosen.

    Parameters
    ----------
    waveform_high : np.ndarray
        R0 waveform high gain. Shape: (N_batch, N_frames, N_pixels)
    waveform_low : np.ndarray
        R0 waveform low gain. Shape: (N_batch, N_frames, N_pixels)
    gains : np.ndarray
        Per-pixel high and low gains. `gains[0]` is high gain, `gains[1]` is low gains. shape (2, N_pixels)
    pedestals : np.ndarray
        Per-pixel pedestal for low and high gains. `pedestals[0]` corresponds to high gain, `pedestals[1]`
        corresponds to low gain. Shape (2, N_pixels)
    window_integration_correction : np.ndarray
        Array of shape (2,) containing the correction to apply after a windowed integration, for each gain.
    threshold : float
        Threshold to chose the waveform channel. A value above `threshold` indicates that the high gain waveform
        saturated and low gain should be used.

    Returns
    -------
    Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]
        The waveform selected from each gains based on `threshold`, associated gains, pedestals and integration
        correction to used. The order is:
        - waveform : np.ndarray
          waveform where the appropriate gain has been selected. Shape (N_batch, N_frames, N_pixels)
        - gains : np.ndarray
          Gain to use to calibrate `waveform` (high gain when waveform_high wasn't above `threshold` and
          low gain otherwise). Shape (N_batch, N_pixels)
        - pedestals : np.ndarray
          Pedestals to use to calibrate `waveform`. Shape (N_batch, N_pixels)
        - window_integration_correction : np.ndarray
          Correction to use after the integration. Shape(N_batch, N_pixels)
    """
    idx_saturated = (waveform_high > threshold).any(axis=-2, keepdims=True)
    return (
        np.where(idx_saturated, waveform_low, waveform_high),
        np.where(np.squeeze(idx_saturated, -2), gains[1], gains[0]),
        np.where(np.squeeze(idx_saturated, -2), pedestals[1], pedestals[0]),
        np.where(np.squeeze(idx_saturated, -2), window_integration_correction[1], window_integration_correction[0]),
    )