WaveCalibrator

I3WaveCalibrator is a module that applies calibration constants to transform the contents of raw DOMLaunches (ADC counts) into calibrated waveforms (mV), while correcting for known effects of the electronics. It is a reimplementation of an earlier module called I3DOMcalibrator.

The following transformations are applied to the digitized waveform to obtain the final calibrated output:

1. A baseline measured from beacon-launch data is subtracted from the ADC counts.
2. The baseline-subtracted ADC counts are multiplied by the bin-specific gain to obtain a voltage.
3. The PMT high voltage setting is used to correct the start time of the waveform for the transit time, the average time it takes a pulse to propagate through the entire PMT. Waveforms from the second ATWD chip and the FADC are corrected for their delay with respect to the first ATWD chip.
4. Finally, all waveforms are corrected for the effects of droop in the transformer that couples the mainboard to the PMT output. This is done by calculating the expected reaction voltage from the toroid at each time, and adding the reaction voltage to the calibrated waveform to compensate. The reaction voltages are made to decay exponentially according to a temperature-dependent model of the transformer’s behavior. When a readout contains consecutive launches from the same DOM, the reaction voltages at the end of the last launch are used to correct for the residual droop in the follow-on launch.

There are a few key differences between I3WaveCalibrator and its predecessor, I3DOMcalibrator:

1. I3WaveCalibrator uses the baseline measured in data-taking mode from beacon launches for voltage calibration. This is more reliable than the value measured by DOMCal and used by DOMcalibrator for voltage calibration.
2. I3WaveCalibrator keeps better records of what it’s done. Every waveform is tagged with the chip and channel it came from, so that the transformation can be inverted or checked for sanity by downstream modules.
3. I3WaveCalibrator outputs a single I3WaveformSeriesMap containing all the calibrated waveforms from its input. If separate maps for each digitizer/channel are needed, they can be extracted from the output with I3WaveformSplitter.
4. I3WaveCalibrator applies droop correction to all waveforms from a single readout in one pass, so that the residual droop in follow-on launches can be corrected as well. As such, no launch cleaning should be applied to the DAQ payload before calibration. If waveforms need to be separated by digitizer/chip or LC condition for later processing, this can be done using I3WaveformSplitter.
5. I3WaveCalibrator takes a different approach to droop correction for undershot or saturated waveforms. Instead of assuming a downward-ramping input voltage when the digitizer is floored at 0 counts, it assumes zero input voltage and allows the reaction voltages to decay until the end of the undershot region, where it resumes normal droop correction. When the FADC saturates within the ATWD window, the measured ATWD waveform is used to reconstruct what the FADC would have measured and calculate the appropriate droop correction. The same is done for high-gain ATWD channels (0 and 1) when they saturate. In the extremely rare cases where the FADC saturates outside the ATWD window or ATWD channel 2 saturates, all bets are off, and WaveCalibrator marks the waveform series for that DOM as unrecoverable.

I3WaveCalibrator

Parameters

Launches:

Name of the I3DOMLaunchSeriesMap to get from the frame, e.g. “InIceRawData”.

Waveforms:

Name of the I3WaveformSeriesMap to put in the frame. This map contains all ATWD/FADC/SLC waveforms obtained from the input; if desired, they can be split out into separate maps using I3WaveformSplitter.

Errata:

Name of the std::vector<OMKey> to put in the frame, containing the OMs for which the calibration failed in one or more waveforms, and should be considered unreliable.

ATWDSaturationMargin:

Saturation threshold of the ATWD, in ADC counts below the maximum value; e.g. a saturation margin of 123 means that ATWDs with any bins above 1023-123=900 counts will be considered saturated.

FADCSaturationMargin:

Saturation threshold of the FADC, in ADC counts below the maximum value.

Note

The ATWDMode parameter is no longer supported. I3WaveCalibrator will always calibrate all channels present in each DOMLaunch. If you need to have only the highest-gain unsaturated channel it can be split out using I3WaveformSplitter.

OutBoxes

One.

Example

from icecube import icetray, dataio, WaveCalibrator
import I3Tray

tray = I3Tray.I3Tray()

tray.AddModule("I3Reader","reader",
    Filename="data.i3.gz"
    )

tray.AddModule("I3WaveCalibrator", "sedan",
    Launches="InIceRawData",
    Waveforms="CalibratedWaveforms",
    Errata="BorkedOMs",
    ATWDSaturationMargin=123,
    FADCSaturationMargin=0,
    )

tray.AddModule("TrashCan", "YesWeCan")
tray.Execute()
tray.Finish()

I3WaveformSplitter

The I3WaveformSplitter module splits a given I3WaveformSeriesMap into multiple maps, one for each waveform source.

Parameters

Input:

Name of the I3WaveformSeriesMap to get from the frame, e.g. “CalibratedWaveforms”.

HLC_ATWD:

Name of the I3WaveformSeriesMap containing the ATWD waveforms from HLC launches to put in the frame, e.g. “CalibratedATWD”.

HLC_FADC:

Name of the I3WaveformSeriesMap containing the FADC waveforms from HLC launches to put in the frame, e.g. “CalibratedFADC_HLC”.

SLC:

Name of the I3WaveformSeriesMap containing the FADC charge stamps from SLC launches to put in the frame, e.g. “CalibratedFADC_SLC”. Note that InIce-style SLC stamps are indistinguishable from IceTop-style SLC stamps and will appear in the same map.

Force:

Place output maps in the frame even if they’re empty. This can be useful if downstream modules are lazy and assume their inputs are always present.

PickUnsaturatedATWD:

Emit only the highest-gain unsaturated ATWD channel. This emulates WaveCalibrator’s former CALIBRATE_UNSATURATED mode.

SplitATWDChannels:

Split waveforms from the three ATWD channels into separate maps numbered 0, 1, and 2.

SplitATWDChips:

Split waveforms from the two ATWD chips into separate maps, marked _Chip0 and _Chip1.

OutBoxes

One.

Example

from icecube import icetray, dataio, WaveCalibrator
import I3Tray

tray = I3Tray.I3Tray()

tray.AddModule("I3Reader","reader",
    Filename="data.i3.gz"
    )

tray.AddModule("I3WaveCalibrator", "sedan",
    Launches="InIceRawData",
    Waveforms="CalibratedWaveforms",
    Errata="BorkedOMs",
    ATWDSaturationMargin=123,
    FADCSaturationMargin=0,
    )

tray.AddModule("I3WaveformSplitter", "splitter",
    Input="CalibratedWaveforms",
    ATWD_HLC="CalibratedATWD",
    FADC_HLC="CalibratedFADC_HLC",
    SLC="CalibratedFADC_SLC",
    PickUnsaturatedATWD=True,
    )

tray.AddModule("TrashCan", "YesWeCan")
tray.Execute()
tray.Finish()

I3WaveformTimeRangeCalculator

Because waveform times are corrected for PMT transit time, the first and last bins of calibrated waveforms are not necessarily within the trigger readout window. I3WaveCalibrator calculates the earliest and latest possible waveform bin edge times for an event so that downstream modules don’t have to guess, and the I3WaveformTimeRangeCalculator module implements a stand-alone version of the calculation that can be used e.g. for SuperDST data.

Parameters

WaveformRange:

Name of the I3TimeWindow to put in the frame, e.g. “CalibratedWaveformRange”.

OutBoxes

One.

Example

from icecube import icetray, dataio, WaveCalibrator
import I3Tray

tray = I3Tray.I3Tray()

tray.AddModule("I3Reader","reader",
    FilenameList=["GCD.i3.gz", "data.i3.gz"]
    )

    tray.AddModule("I3WaveformTimeRangeCalculator", "calcrange",
        WaveformRange="CalibratedWaveformRange")

tray.AddModule("TrashCan", "YesWeCan")
tray.Execute()
tray.Finish()

Determining the baseline

The baseline that WaveCalibrator subtracts from each digitized waveform is measured from beacon-launch waveforms. These have to be harvested (either from raw data or from verification histograms) and inserted into the offline database using the Python classes provided in the BeaconHarvester project.

Adding baselines to old GCD files

GCD files produced prior to May 2011 (and all simulation GCD files to date) do not contain information about the beacon baseline. The script WaveCalibrator/examples/tweak_gcd.py can be used to add beacon baselines to such GCD files. Baselines used for processing real data are measured from beacon launches, while those for simulation are sythesized from the existing constants to match DOMsimulator’s idea of the digitizer baseline.