toolbox_scs.detectors.digitizers

Digitizers related sub-routines

Copyright (2021) SCS Team.

(contributions preferrably comply with pep8 code structure guidelines.)

Module Contents

Functions

get_peaks(run, data, mnemonic[, useRaw, autoFind, ...])

Extract peaks from one source (channel) of a digitizer.

get_dig_avg_trace(run, mnemonic[, ntrains])

Compute the average over ntrains evenly spaced accross all trains

check_peak_params(run, mnemonic[, raw_trace, ntrains, ...])

Checks and plots the peak parameters (pulse window and baseline window

get_tim_peaks(run[, mnemonic, merge_with, ...])

Automatically computes TIM peaks. Sources can be loaded on the

get_laser_peaks(run[, mnemonic, merge_with, ...])

Extracts laser photodiode signal (peak intensity) from Fast ADC

get_digitizer_peaks(run, mnemonic[, merge_with, ...])

Automatically computes digitizer peaks. A source can be loaded on the

digitizer_signal_description(run[, digitizer])

Check for the existence of signal description and return all corresponding
toolbox_scs.detectors.digitizers.get_peaks(run, data, mnemonic, useRaw=True, autoFind=True, integParams=None, bunchPattern='sase3', bpt=None, extra_dim=None, indices=None)[source]

Extract peaks from one source (channel) of a digitizer.

Parameters:

  • run (extra_data.DataCollection) – DataCollection containing the digitizer data

  • data (xarray DataArray or str) – array containing the raw traces or peak-integrated values from the digitizer. If str, must be one of the ToolBox mnemonics. If None, the data is loaded via the source and key arguments.

  • mnemonic (str or dict) – ToolBox mnemonic or dict with source and key as in {‘source’: ‘SCS_UTC1_ADQ/ADC/1:network’, ‘key’: ‘digitizers.channel_1_A.raw.samples’}

  • useRaw (bool) – If True, extract peaks from raw traces. If False, uses the APD (or peaks) data from the digitizer.

  • autoFind (bool) – If True, finds integration parameters by inspecting the average raw trace. Only valid if useRaw is True.

  • integParams (dict) – dictionnary containing the integration parameters for raw trace integration: ‘pulseStart’, ‘pulseStop’, ‘baseStart’, ‘baseStop’, ‘period’, ‘npulses’. Not used if autoFind is True. All keys are required when bunch pattern is missing.

  • bunchPattern (str) – match the peaks to the bunch pattern: ‘sase1’, ‘sase3’, ‘scs_ppl’. This will dictate the name of the pulse ID coordinates: ‘sa1_pId’, ‘sa3_pId’ or ‘scs_ppl’.

  • bpt (xarray DataArray) – bunch pattern table

  • extra_dim (str) – Name given to the dimension along the peaks. If None, the name is given according to the bunchPattern.

  • indices (array, slice) – indices from the peak-integrated data to retrieve. Only required when bunch pattern is missing and useRaw is False.

Return type:

xarray.DataArray containing digitizer peaks with pulse coordinates

toolbox_scs.detectors.digitizers.get_dig_avg_trace(run, mnemonic, ntrains=None)[source]

Compute the average over ntrains evenly spaced accross all trains of a digitizer trace.

Parameters:

  • run (extra_data.DataCollection) – DataCollection containing the digitizer data.

  • mnemonic (str) – ToolBox mnemonic of the digitizer data, e.g. ‘MCP2apd’.

  • ntrains (int) – Number of trains used to calculate the average raw trace. If None, all trains are used.

Returns:

trace – The average digitizer trace

Return type:

DataArray

toolbox_scs.detectors.digitizers.check_peak_params(run, mnemonic, raw_trace=None, ntrains=200, params=None, plot=True, show_all=False, bunchPattern='sase3')[source]

Checks and plots the peak parameters (pulse window and baseline window of a raw digitizer trace) used to compute the peak integration. These parameters are either set by the digitizer peak-integration settings, or are determined by a peak finding algorithm (used in get_tim_peaks or get_fast_adc_peaks) when the inputs are raw traces. The parameters can also be provided manually for visual inspection. The plot either shows the first and last pulse of the trace or the entire trace.

Parameters:

  • run (extra_data.DataCollection) – DataCollection containing the digitizer data.

  • mnemonic (str) – ToolBox mnemonic of the digitizer data, e.g. ‘MCP2apd’.

  • raw_trace (optional, 1D numpy array or xarray DataArray) – Raw trace to display. If None, the average raw trace over ntrains of the corresponding channel is loaded (this can be time-consuming).

  • ntrains (optional, int) – Only used if raw_trace is None. Number of trains used to calculate the average raw trace of the corresponding channel.

  • plot (bool) – If True, displays the raw trace and peak integration regions.

  • show_all (bool) – If True, displays the entire raw trace and all peak integration regions (this can be time-consuming). If False, shows the first and last pulse according to the bunchPattern.

  • bunchPattern (optional, str) – Only used if plot is True. Checks the bunch pattern against the digitizer peak parameters and shows potential mismatch.

Return type:

dictionnary of peak integration parameters

toolbox_scs.detectors.digitizers.get_tim_peaks(run, mnemonic=None, merge_with=None, bunchPattern='sase3', integParams=None, keepAllSase=False)[source]

Automatically computes TIM peaks. Sources can be loaded on the fly via the mnemonics argument, or processed from an existing data set (merge_with). The bunch pattern table is used to assign the pulse id coordinates.

Parameters:

  • run (extra_data.DataCollection) – DataCollection containing the digitizer data.

  • mnemonic (str) – mnemonics for TIM, e.g. “MCP2apd”.

  • merge_with (xarray Dataset) – If provided, the resulting Dataset will be merged with this one. The TIM variables of merge_with (if any) will also be computed and merged.

  • bunchPattern (str) – ‘sase1’ or ‘sase3’ or ‘scs_ppl’, bunch pattern used to extract peaks. The pulse ID dimension will be named ‘sa1_pId’, ‘sa3_pId’ or ‘ol_pId’, respectively.

  • integParams (dict) – dictionnary for raw trace integration, e.g. {‘pulseStart’:100, ‘pulsestop’:200, ‘baseStart’:50, ‘baseStop’:99, ‘period’:24, ‘npulses’:500}. If None, integration parameters are computed automatically.

  • keepAllSase (bool) – Only relevant in case of sase-dedicated trains. If True, all trains are kept, else only those of the bunchPattern are kept.

Returns:

  • xarray Dataset with TIM variables substituted by

  • the peak caclulated values (e.g. “MCP2raw” becomes

  • ”MCP2peaks”), merged with Dataset *merge_with if provided.*

toolbox_scs.detectors.digitizers.get_laser_peaks(run, mnemonic=None, merge_with=None, bunchPattern='scs_ppl', integParams=None)[source]

Extracts laser photodiode signal (peak intensity) from Fast ADC digitizer. Sources can be loaded on the fly via the mnemonics argument, and/or processed from an existing data set (merge_with). The PP laser bunch pattern is used to assign the pulse idcoordinates.

Parameters:

  • run (extra_data.DataCollection) – DataCollection containing the digitizer data.

  • mnemonic (str) – mnemonic for FastADC corresponding to laser signal, e.g. “FastADC2peaks” or ‘I0_ILHraw’.

  • merge_with (xarray Dataset) – If provided, the resulting Dataset will be merged with this one. The FastADC variables of merge_with (if any) will also be computed and merged.

  • bunchPattern (str) – ‘sase1’ or ‘sase3’ or ‘scs_ppl’, bunch pattern used to extract peaks.

  • integParams (dict) – dictionnary for raw trace integration, e.g. {‘pulseStart’:100, ‘pulsestop’:200, ‘baseStart’:50, ‘baseStop’:99, ‘period’:24, ‘npulses’:500}. If None, integration parameters are computed automatically.

Returns:

  • xarray Dataset with all Fast ADC variables substituted by

  • the peak caclulated values (e.g. “FastADC2raw” becomes

  • ”FastADC2peaks”).

toolbox_scs.detectors.digitizers.get_digitizer_peaks(run, mnemonic, merge_with=None, bunchPattern='sase3', integParams=None, keepAllSase=False)[source]

Automatically computes digitizer peaks. A source can be loaded on the fly via the mnemonic argument, or processed from an existing data set (merge_with). The bunch pattern table is used to assign the pulse id coordinates.

Parameters:

  • run (extra_data.DataCollection) – DataCollection containing the digitizer data.

  • mnemonic (str) – mnemonic for FastADC or ADQ412, e.g. “I0_ILHraw” or “MCP3apd”. The data is either loaded from the DataCollection or taken from merge_with.

  • merge_with (xarray Dataset) – If provided, the resulting Dataset will be merged with this one.

  • bunchPattern (str or dict) – ‘sase1’ or ‘sase3’ or ‘scs_ppl’, ‘None’: bunch pattern

  • integParams (dict) – dictionnary for raw trace integration, e.g. {‘pulseStart’:100, ‘pulsestop’:200, ‘baseStart’:50, ‘baseStop’:99, ‘period’:24, ‘npulses’:500}. If None, integration parameters are computed automatically.

  • keepAllSase (bool) – Only relevant in case of sase-dedicated trains. If True, all trains are kept, else only those of the bunchPattern are kept.

Returns:

  • xarray Dataset with digitizer peak variables. Raw variables are

  • substituted by the peak caclulated values (e.g. “FastADC2raw” becomes

  • ”FastADC2peaks”).

toolbox_scs.detectors.digitizers.digitizer_signal_description(run, digitizer=None)[source]

Check for the existence of signal description and return all corresponding channels in a dictionnary.

Parameters:

  • run (extra_data.DataCollection) – DataCollection containing the digitizer data.

  • digitizer (str or list of str (default=None)) – Name of the digitizer: one in [‘FastADC’, FastADC2’, ‘ADQ412’, ‘ADQ412_2] If None, all digitizers are used

Returns:

signal_description – the digitizer channels.

Return type:

dictionnary containing the signal description of

Example

import toolbox_scs as tb run = tb.open_run(3481, 100) signals = tb.digitizer_signal_description(run) signals_fadc2 = tb.digitizer_signal_description(run, ‘FastADC2’)