ADQ digitizers¤

extra.components.AdqRawChannel ¤

AdqRawChannel(data, channel, digitizer=None, pulses=None, interleaved=None, clock_ratio=None, sample_dim='sample', first_pulse_offset=10000, single_pulse_length=25000, cm_period=None, baselevel=None, baseline=np.s_[:1000], extra_cm_period=list())

A high-level interface to raw output of ADQ digitizer channels.

Fast ADQ digitizers are used to acquire analog signals at GHz sample rates. Their onboard FPGA are able to generate different kinds of output from the signal they acquire, like raw data, zero suppressed data or peak integration.

This component is able to access the raw data saved with these devices in various representations Tand data formats.

All retrieval methods can perform implicit corrections and other steps like pulse separation, which can be controlled by parameters when initializing this component.

By default, common mode corrections are applied to compensate for non-uniform baselines as a result of the ADQ's parallel readout architecture. The used sample periodicity is 8 samples, or 16 samples if interleaved. To disable, the component can be initialized with cm_period being 0 or less. These corrections also pull the baseline to zero unless specified otherwise with baselevel. If common mode corrections are disabled, the signal is still pulled to a baselevel if specified. If no baselevel is specified and common mode corrections are disabled, the data remains unchanged.

Typical configurations for these corrections are therefore:

cm_period > 0 and baselevel is not None: Common mode correction is performed with baseline pulled to baselevel.
cm_period > 0 and baselevel is None (default): Common mode correction is performed with baseline at 0.
cm_period == 0 and baselevel is not None: Baseline is pulled to baselevel.
cm_period == 0 and baselevel is None: No modification is done.

The baseline can be any contiguous slice of the raw data, by default the first 1000 samples are used.

All processing performed implicitly by the retrieval methods is also available to run explicitly on a set of data.

Parameters:

Name	Type	Description	Default
`data`	`DataCollection`	Data to access digitizer from.	required
`channel`	`str`	Channel name with or without underscore, e.g. 1_A or 3C.	required
`digitizer`	`str`	Source name of an ADQ digitizer, only needed if the data includes more than one such device or none could be detected automatically.	`None`
`pulses`	`PulsePattern`	Pulse component to pull pulse information, by default a XrayPulses object is constructed unless pulse information are explicitly disabled by passing `False`. Most pulse separation operations require this to be present.	`None`
`interleaved`	`bool`	Whether this digitizer channel was interleaving samples or not, only needed if it could not be detected automatically.	`None`
`clock_ratio`	`int`	Digitizer sampling clock as multiple of the bunch repetition rate (4.5 MHz).	`None`
`sample_dim`	`sample or time`	Coordinates for sample dimension if a labelled result is returned, sample by default.	`'sample'`
`first_pulse_offset`	`int`	Sample where the first pulse begins, 10000 by default. This is used to locate the beginning of the first pulse when pulse separation is used.	`10000`
`single_pulse_length`	`int`	Samples per pulse for the case all trains only contain a single pulse, when it cannot be inferred from pulse repetition rate.	`25000`
`cm_period`	`int`	Apply common mode correction with specified sample periodicity, disabled for non-positive values and by default 8 or 16 when interleaved.	`None`
`baseline`	`slice or ArrayLike`	Contiguous 1D slice of the trace of each train to determine common mode or baseline or direct baseline data to use, :1000 by default.	`s_[:1000]`
`baselevel`	`float`	ADU value to pull the baseline to, None by default. Note that common mode corrections if enabled always pull the baselevel to zero unless specified otherwise here.	`None`
`extra_cm_period`	`list`	Apply the common mode correction sequentially with the settings in the list.	`list()`

control_source `property` ¤

control_source

Control source of this digitizer, if found in data.

instrument_source `property` ¤

instrument_source

Instrument source of this digitizer.

board `property` ¤

board

Board number.

letter `property` ¤

letter

Channel letter.

number `property` ¤

number

Channel number.

name `property` ¤

name

Full channel name, e.g. 4_C

raw_samples_key `property` ¤

raw_samples_key

Raw samples key.

interleaved `property` ¤

interleaved

Whether this channel is interleaved.

clock_ratio `property` ¤

clock_ratio

Ratio between bunch repetition clock (4.5 MHz) and sample clock.

first_pulse_offset `property` ¤

first_pulse_offset

Sample position of first pulse on digitizer trace.

single_pulse_length `property` ¤

single_pulse_length

Length in samples in case of a single pulse.

sampling_rate `property` ¤

sampling_rate

Sampling rate in Hz.

sampling_period `property` ¤

sampling_period

Period between samples in seconds.

trace_shape `property` ¤

trace_shape

Shape of a single trace.

trace_duration `property` ¤

trace_duration

Duration of a single trace in seconds.

pulses `property` ¤

pulses: PulsePattern | None

The pulse pattern if available, None if not.

board_parameters `property` ¤

board_parameters

All board-related parameters.

channel_parameters `property` ¤

channel_parameters

All channel-related parameters.

channel_key ¤

channel_key(suffix)

Instrument KeyData object of this channel.

select_trains ¤

select_trains(trains)

Select a subset of trains in this data.

This method accepts the same type of arguments as DataCollection.select_trains.

samples_per_pulse ¤

samples_per_pulse(pulse_period=None, pulse_duration=None, repetition_rate=None, pulse_ids=None, fractional=False)

Get number of samples per pulse.

Digitizer traces are acquired by train, by may contain the data of several pulses, with each pulse covering a certain number of samples depending on the digitizer and machine repetition rates.

This method may be called with any of its arguments to determine the number of samples per pulse, with the first argument not identical with None being used in argument order. Calling it with no arguments uses the pulse information the component was initialized with.

Parameters:

Name	Type	Description	Default
`pulse_period`	`int`	Pulse period in PPT units of 4.5 MHz.	`None`
`pulse_duration`	`float`	Pulse duration in seconds.	`None`
`repetition_rate`	`float`	Pulse repetition rate in Hz.	`None`
`pulse_ids`	`ArrayLike`	Pulse IDs of a single train.	`None`
`fractional`	`bool`	Whether to round to possible EuXFEL repetition rates (default) or return the full fractional value.	`False`

Returns:

Name	Type	Description
`samples_per_pulse`	`int or float`	Number of samples per pulse, float if `fractional=True`.

correct_common_mode ¤

correct_common_mode(data, cm_period, baseline, baselevel=None)

Correct common mode.

For ADQ digitizers, a common mode is present for every Nth sample due to the parallel readout architecture, typically with N = 8 or N = 16 with interleaving. This method allows to correct this behaviour by computing a baseline for every Nth sample up to the configured period within the baseline region and substract it from every Nth pixel across the entire trace.

If no additional baselevel is passed, the baseline is always pulled to 0 by this method.

Parameters:

Name	Type	Description	Default
`data`	`ArrayLike`	Input data to preprocess.	required
`cm_period`	`int`	Sample periodicity of the common mode, generally 8 or 16 with interleaving.	required
`baseline`	`slice or ArrayLike`	Contiguous 1D slice of the trace of each train to determine baselevel or direct baseline data to use.	required
`baselevel`	`float or None`	ADU value to pull the baseline to, None by default which implicitly pulls the baseline to 0.	`None`

Returns:

Name	Type	Description
`out`	`ndarray`	Corrected input data, same dtype as input data if floating otherwise `float32`.

pull_baseline ¤

pull_baseline(data, baseline, baselevel)

Pull baseline to certain level.

The signal baseline may be at different values than 0 either by intention to make optimal use of ADC range or through external means. In the absence of common mode correction, this method can pull the baseline to any desired level.

Parameters:

Name	Type	Description	Default
`data`	`ArrayLike`	Input data to preprocess, will be converted to np.ndarray currently.	required
`baseline`	`slice or ArrayLike`	Contiguous 1D slice of the trace of each train to determine baselevel or direct baseline data to use.	required
`baselevel`	`float`	ADU value to pull the baseline to.	required

Returns:

Name	Type	Description
`out`	`ndarray`	Modified input data.

reshape_to_pulses ¤

reshape_to_pulses(data, first_pulse_offset=None)

Reshape train data to pulse data.

This method performs pulse separation by splitting the trace acquired by train into individual traces by pulse based on the pulse information the component is initialized with.

Parameters:

Name	Type	Description	Default
`data`	`ArrayLike`	Digitizer trace(s) for one or more trains, last axis is assumed to be samples within a train.	required
`first_pulse_offset`	`int`	Sample where the first pulse begins, by default the value the component was initialized with.	`None`

Returns:

Name	Type	Description
`out`	`ndarray`	Reshaped pulse traces.

unstack_pulses ¤

unstack_pulses(data)

Unstack pulse axis into train and pulse.

This method unstacks the pulse axis introduced by pulse_data() into separate axis for train and the pulses for each of these trains.

It is currently limited to 2D data, i.e. expects the first axis to exactly represent pulses and the second axis to contain samples, and the number of pulses per train have to be constant.

Parameters:

Name	Type	Description	Default
`data`	`ArrayLike`	Data separated by pulse.	required

Returns:

Name	Type	Description
`out`	`ndarray or DataArray`	Data separated by train and pulse. If labelled data with a `pulse` index is passed, a labelled result is returned using the correspondig coordinates.

find_edges ¤

find_edges(data, edge_func=None, max_edges=50, parallel=None, **edge_kw)

Find signal edges.

In some cases, not the raw data itself may be of interest but the location (and amplitude) of certain signals in the raw data. One such example is time-of-flight spectroscopy in counting mode, where individual charged particles impact a detection surface and leave a fast signal on the digitizer trace. Fast timing discriminators allow to robustly determine the position of such signals.

By default, it uses the dynamic leading discriminator from the extra.signal package, but other from this package or entirely custom functions may be used as well. The required signatures must include three keyword arguments signal, edges and amplitudes corresponding to those from extra.signal.dled. The default edge finding method requires the threshold parameter to be passed as keyword argument.

The processing is parallelized via pasha.

Parameters:

Name	Type	Description	Default
`data`	`ArrayLike`	Input data to find edges on.	required
`edge_func`	`callable`	Edge finding method to run on each train trace, extra.signal.dled by default.	`None`
`max_edges`	`int`	Maximal number of edges per train, 50 by default.	`50`
`parallel`	`int or None`	Number of parallel processes to use, by default 10 or a quarter of all cores whichever is lower. Any non-positive value or 1 disable parallelization.	`None`
`**edge_kw`	`Any`	Any further keyword arguments are passed to the edge finding method.	`{}`

Returns:

Name	Type	Description
`result`	`DataFrame`	Edge positions and pulse heights.

find_edge_array ¤

find_edge_array(data, labelled=True, squeeze_edges=True, edge_func=None, max_edges=50, parallel=None, **edge_kw)

Find signal edges as ragged array.

Alternative method to find_edges() returning the results as ragged arrays, using np.nan as filler value.

Parameters:

Name	Type	Description	Default
`data`	`ArrayLike`	Input data to find edges on.	required
`labelled`	`bool`	Whether data is returned as a labelled xarray (default) or unlabelled ndarray.	`True`
`squeeze_edges`	`bool`	Whether to minimize the edge axis length to the maxinum number of edges found per row, True by default.	`True`
`edge_func`	`Callable`	Edge finding method to run on each train trace, extra.signal.dled by default.	`None`
`max_edges`	`int`	Maximal number of edges per train, 1/5000 of trace length by default.	`50`
`parallel`	`int or None`	Number of parallel processes to use, by default 10 or a quarter of all cores whichever is lower. Any non-positive value or 1 disable parallelization.	`None`
`**edge_kw`	`Any`	Any further keyword arguments are passed to the edge finding method.	`{}`

Returns:

Name	Type	Description
`result`	`(ndarray, ndarray)`	Tuple of edge positions and amplitudes, only if not labelled.
`result`	`Dataset`	Edge positions and pulse heights, only if labelled

train_data ¤

train_data(labelled=True, roi=(), out=None, parallel=None)

Load this channel's raw data by train.

This method is similar to obtaining the digitized raw traces directly via the channel's KeyData object, but is optimized to perform the ADQ-specific correction steps with minimal CPU and memory impact while reading the data from disk. Additionally, it offers labels for the sample dimension in either samples (default) or time in addition to the train dimension depending on the choice during component initialization.

Parameters:

Name	Type	Description	Default
`labelled`	`bool`	Whether data is returned as a labelled xarray (default) or unlabelled ndarray.	`True`
`roi`	`slice or tuple`	Part of the trace of each train to read, applied before any preprocessing is performed. The entire train trace is read if omitted.	`()`
`out`	`ArrayLike`	Array to read into, a new is allocated if omitted.	`None`
`parallel`	`int or None`	Number of parallel processes to use, by default 10 or a quarter of all cores whichever is lower. Any non-positive value or 1 disable parallelization.	`None`

Returns:

Name	Type	Description
`data`	`DataArray or ndarray`	Digitizer traces.

pulse_data ¤

pulse_data(labelled=True, pulse_dim='pulseId', train_roi=(), out=None, *, dtype=np.float32, parallel=None)

Load this channel's raw data by pulse.

In addition to [AdqRawChannel.train_data], this method also separates the data belonging to each pulse into their own trace based on the pulse information the component is initialized with.

This process depends on the first_pulse_offset and potentially single_pulse_length the component was initialized with.

If the pulse information refers to data beyond the acquired traces, it is filled by np.nan for floating data types or -1 for integer types.

Parameters:

Name	Type	Description	Default
`labelled`	`bool`	Whether data is returned as a labelled xarray (default) or unlabelled ndarray.	`True`
`pulse_dim`	`pulseId or pulseIndex or pulseTime`	Label for pulse dimension, pulse ID by default.	`'pulseId'`
`train_roi`	`slice or tuple`	Part of the trace of each train to read, applied before any preprocessing is performed. The entire train trace is read if omitted.	`()`
`out`	`ArrayLike`	Array to read into, a new one is allocated if omitted.	`None`
`dtype`		(numpy dtype specifier, optional): dtype to use for the output array. Ignored if out is passed.	`float32`
`parallel`	`int or None`	Number of parallel processes to use, by default 10 or a quarter of all cores whichever is lower. Any non-positive value or 1 disable parallelization.	`None`

Returns:

Name	Type	Description
`data`	`DataArray or ndarray`	Digitizer traces.

train_edges ¤

train_edges(edge_func=None, max_edges=None, parallel=None, **edge_kw)

Load data and find signal edges by train.

This method performs the edge discrimination step while loading the data and only returns those results. It is therefore significantly more memory efficient than performing these operations sequentially from memory.

Please see find_edges() for more details.

Parameters:

Name	Type	Description	Default
`edge_func`	`callable`	Edge finding method to run on each train trace, extra.signal.dled by default.	`None`
`max_edges`	`int`	Maximal number of edges per train, 1/5000 of trace length by default.	`None`
`parallel`	`int or None`	Number of parallel processes to use, by default 10 or a quarter of all cores whichever is lower. Any non-positive value or 1 disable parallelization.	`None`
`**edge_kw`	`Any`	Any further keyword arguments are passed to the edge finding method.	`{}`

Returns:

Name	Type	Description
`result`	`DataFrame`	Edge positions and pulse heights.

train_edge_array ¤

train_edge_array(labelled=True, squeeze_edges=True, edge_func=None, max_edges=None, parallel=None, **edge_kw)

Load data and find signal edges by train as ragged array.

Alternative method to train_edges() returning the results as ragged arrays, using np.nan as filler value.

Parameters:

Name	Type	Description	Default
`labelled`	`bool`	Whether data is returned as a labelled xarray (default) or unlabelled ndarray.	`True`
`squeeze_edges`	`bool`	Whether to minimize the edge axis length to the maxinum number of edges found per row, True by default.	`True`
`edge_func`	`callable`	Edge finding method to run on each train trace, extra.signal.dled by default.	`None`
`max_edges`	`int`	Maximal number of edges per train, 1/5000 of trace length by default.	`None`
`parallel`	`int or None`	Number of parallel processes to use, by default 10 or a quarter of all cores whichever is lower. Any non-positive value or 1 disable parallelization.	`None`
`**edge_kw`	`Any`	Any further keyword arguments are passed to the edge finding method.	`{}`

Returns:

Name	Type	Description
`result`	`(ndarray, ndarray)`	Tuple of edge positions and amplitudes, only if not labelled.
`result`	`Dataset`	Edge positions and pulse heights, only if labelled.

pulse_edges ¤

pulse_edges(pulse_dim='pulseId', edge_func=None, max_edges=10, parallel=None, **edge_kw)

Load data and find signal edges by pulse.

This method performs the edge discrimination step while loading and the data and separating it into pulses, and only returns those results. It is therefore significantly more memory efficient than performing these operations sequentially from memory.

Please see pulse_data() and find_edges() for more details.

Parameters:

Name	Type	Description	Default
`pulse_dim`	`pulseId or pulseIndex or pulseTime`	Label for pulse dimension, pulse ID by default.	`'pulseId'`
`edge_func`	`callable`	Edge finding method to run on each train trace, extra.signal.dled by default.	`None`
`max_edges`	`int`	Maximal number of edges per train, 1/100 of trace length per pulse by default.	`10`
`parallel`	`int or None`	Number of parallel processes to use, by default 10 or a quarter of all cores whichever is lower. Any non-positive value or 1 disable parallelization.	`None`
`**edge_kw`	`Any`	Any further keyword arguments are passed to the edge finding method.	`{}`

Returns:

Name	Type	Description
`result`	`DataFrame`	Edge positions and pulse heights.

pulse_edge_array ¤

pulse_edge_array(labelled=True, squeeze_edges=True, pulse_dim='pulseId', edge_func=None, max_edges=10, parallel=None, **edge_kw)

Load data and find signal edges by pulse as ragged array.

Alternative method to pulse_edges returning the results as ragged arrays, using np.nan as filler value.

Parameters:

Name	Type	Description	Default
`labelled`	`bool`	Whether data is returned as a labelled xarray (default) or unlabelled ndarray.	`True`
`squeeze_edges`	`bool`	Whether to minimize the edge axis length to the maxinum number of edges found per row, True by default.	`True`
`pulse_dim`	`pulseId or pulseIndex or pulseTime`	Label for pulse dimension, pulse ID by default.	`'pulseId'`
`edge_func`	`callable`	Edge finding method to run on each train trace, extra.signal.dled by default.	`None`
`max_edges`	`int`	Maximal number of edges per train, 1/100 of trace length by pulse by default.	`10`
`parallel`	`int or None`	Number of parallel processes to use, by default 10 or a quarter of all cores whichever is lower. Any non-positive value or 1 disable parallelization.	`None`
`**edge_kw`	`Any`	Any further keyword arguments are passed to the edge finding method.	`{}`

Returns:

Name	Type	Description
`result`	`(ndarray, ndarray)`	Tuple of edge positions and amplitudes, only if not labelled.
`result`	`Dataset`	Edge positions and pulse heights, only if labelled.

ADQ digitizers¤

extra.components.AdqRawChannel ¤

control_source property ¤

instrument_source property ¤

board property ¤

letter property ¤

number property ¤

name property ¤

raw_samples_key property ¤

interleaved property ¤

clock_ratio property ¤

first_pulse_offset property ¤

single_pulse_length property ¤

sampling_rate property ¤

sampling_period property ¤

trace_shape property ¤

trace_duration property ¤

pulses property ¤

board_parameters property ¤

channel_parameters property ¤

channel_key ¤

select_trains ¤

samples_per_pulse ¤

correct_common_mode ¤

pull_baseline ¤

reshape_to_pulses ¤

unstack_pulses ¤

find_edges ¤

find_edge_array ¤

train_data ¤

pulse_data ¤

train_edges ¤

train_edge_array ¤

pulse_edges ¤

pulse_edge_array ¤

control_source `property` ¤

instrument_source `property` ¤

board `property` ¤

letter `property` ¤

number `property` ¤

name `property` ¤

raw_samples_key `property` ¤

interleaved `property` ¤

clock_ratio `property` ¤

first_pulse_offset `property` ¤

single_pulse_length `property` ¤

sampling_rate `property` ¤

sampling_period `property` ¤

trace_shape `property` ¤

trace_duration `property` ¤

pulses `property` ¤

board_parameters `property` ¤

channel_parameters `property` ¤