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, source, key, digitizer, useRaw, ...])

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[, mnemonics, merge_with, ...])

Automatically computes TIM peaks. Sources can be loaded on the

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

Extracts laser photodiode signal (peak intensity) from Fast ADC

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

Automatically computes digitizer peaks. Sources 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=None, source=None, key=None, digitizer='ADQ412', 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.

  • source (str) – Name of digitizer source, e.g. ‘SCS_UTC1_ADQ/ADC/1:network’. Only required if data is a DataArray or None.

  • key (str) – Key for digitizer data, e.g. ‘digitizers.channel_1_A.raw.samples’. Only required if data is a DataArray or is None.

  • digitizer (string) – name of digitizer, e.g. ‘FastADC’ or ‘ADQ412’. Used to determine the sampling rate.

  • 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 (string or dict) – 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’. Alternatively, a dict with source, key and pattern can be provided, e.g. {‘source’:’SCS_RR_UTC/TSYS/TIMESERVER’, ‘key’:’bunchPatternTable.value’, ‘pattern’:’sase3’}

  • 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, mnemonics=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.

  • mnemonics (str or list of str) – mnemonics for TIM, e.g. “MCP2apd” or [“MCP2apd”, “MCP3raw”]. If None, defaults to “MCP2apd” in case no merge_with dataset is provided.

  • 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 all 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, mnemonics=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.

  • mnemonics (str or list of str) – mnemonics for FastADC corresponding to laser signal, e.g. “FastADC2peaks” or [“FastADC2raw”, “FastADC3peaks”]. If None, defaults to “MCP2apd” in case no merge_with dataset is provided.

  • 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, mnemonics=None, merge_with=None, bunchPattern='None', integParams=None, digitizer=None, keepAllSase=False)[source]

Automatically computes digitizer 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.

  • mnemonics (str or list of str) – mnemonics for FastADC or TIM, e.g. “FastADC2raw” or [“MCP2raw”, “MCP3apd”]. If None and no merge_with dataset is provided, defaults to “MCP2apd” if digitizer is ADQ412 or “FastADC5raw” if digitizer is FastADC.

  • 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’, ‘None’: 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.

  • 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 all Fast ADC variables 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’)