dspeed.processors package¶

Contains a list of DSP processors, implemented using Numba’s numba.guvectorize() to implement NumPy’s numpy.ufunc interface. In other words, all of the functions are void functions whose outputs are given as parameters. The ufunc interface provides additional information about the function signatures that enables broadcasting the arrays and SIMD processing. Thanks to the ufunc interface, they can also be called to return a NumPy array, but if this is done, memory will be allocated for this array, slowing things down.

The dspeed processors use the ufunc framework, which is designed to encourage highly performant python practices. These functions have several advantages:

They work with numpy.array. NumPy arrays are arrays of same-typed objects that are stored adjacently in memory (equivalent to a dynamically allocated C-array or a C++ vector). Compared to standard Python lists, they perform computations much faster. They are ideal for representing waveforms and transformed waveforms.
They perform vectorized operations. Vectorization causes commands to perform the same operation on all components of an array. For example, the ufunc np.add(a, b, out=c) (equivalently c=a+b) is equivalent to:
```
for i in range(len(c)): c[i] = a[i] + b[i]
```
Loops are slow in python since it is an interpreted language; vectorized commands remove the loop and only call the Python interpreter once.

Furthermore, ufuncs are capable of broadcasting their dimensions. This involves a safety check to ensure the dimensions of a and b are compatible sizes. It also will automatically replicate a size-1 dimension over another one, enabling the addition of a scalar to a vector quantity. This is useful, as it allows us to process multiple waveforms at once.

One of the biggest advantages of vectorized ufuncs is that many of them will take advantage of SIMD (same input-multiple data) vectorization on a vector-CPU. Modern CPUs typically have 256- or 512-bit wide processing units, which can accommodate multiple 32- or 64-bit numbers. Programming with these, however, is quite difficult and requires specialized commands to be called. Luckily for us, many NumPy ufuncs will automatically use these for us, speeding up our code!
ufuncs are capable of calculating their output in place, meaning they can place calculated values in pre-allocated memory rather than allocating and returning new values. This is important because memory allocation is one of the slowest processes computers can perform, and should be avoided. With ufuncs, this can be done using the out keyword in arguments (ex numpy.add(a, b, out=c), or more succinctly, numpy.add(a, b, c)). While this may seem counterintuitive at first, the alternative (c = np.add(a,b) or c = a+b) causes an entirely new array to be allocated, with c pointing at that. These array allocations can add up very quickly: e = a*b + c*d, for example, would allocate 3 different arrays: one for a*b, one for c*d, and one for the sum of those two. As we write ufuncs, it is important that we try to use functions that operate in place as much as possible!

Submodules¶

dspeed.processors.arithmetic module¶

@numba.guvectorize dspeed.processors.arithmetic.mean_below_threshold(w_in, threshold, result)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ff->f, dd->d

Calculate the mean of waveform values that are below a threshold.

Parameters:

w_in (ndarray) – the input waveform.
threshold (float) – the threshold value. Only waveform values below this threshold are included in the mean calculation.
result (float) – the mean of all values in w_in that are below the threshold. Returns NaN if no values are below the threshold.

YAML Configuration Example

wf_mean_below_threshold:
  function: mean_below_threshold
  module: dspeed.processors
  args:
    - waveform
    - 100
    - wf_mean_below_threshold
  unit:
    - ADC

dspeed.processors.bl_subtract module¶

DSP processors for subtracting a constant baseline from waveforms.

@numba.guvectorize dspeed.processors.bl_subtract.bl_subtract(w_in, a_baseline, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ff->f, dd->d

Subtract the constant baseline from the entire waveform.

Parameters:

w_in (ndarray) – the input waveform.
a_baseline (float) – the baseline value to subtract.
w_out (ndarray) – the output waveform with the baseline subtracted.

YAML Configuration Example

wf_bl:
  function: bl_subtract
  module: dspeed.processors
  args:
    - waveform
    - baseline
    - wf_bl

dspeed.processors.convolutions module¶

Convolution-based waveform filter processors.

@numba.guvectorize dspeed.processors.convolutions.convolve_damped_oscillator(w_in, tau, omega, phase, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fddd->f, dddd->d

Convolve waveform with damped oscillator kernel.

Notes

kernel is normalized to have a maximum amplitude of 1. To normalize by area instead, divide result by tau.

Parameters:

w_in (ndarray) – the input waveform
tau (float) – decay time of exponential
omega (float) – angular frequency of oscillation
phase (float) – starting phase of oscillation
w_out (ndarray) – output waveform after convolution

@numba.guvectorize dspeed.processors.convolutions.convolve_exp(w_in, tau, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fd->f, dd->d

Convolve waveform with exponential kernel.

Notes

kernel is normalized to have a maximum amplitude of 1. To normalize by area instead, divide result by tau.

Parameters:

w_in (ndarray) – the input waveform
tau (float) – decay time of exponential kernel
w_out (ndarray) – output waveform after convolution

@numba.guvectorize dspeed.processors.convolutions.convolve_wf(w_in, kernel, mode_in, w_out)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: ffbf->, ddbd->

Parameters:

w_in (ndarray) – the input waveform.
kernel (array) – the kernel to convolve with
mode – mode of convolution options are f : full, v : valid or s : same, explained here: https://numpy.org/doc/stable/reference/generated/numpy.convolve.html
w_out (ndarray) – the filtered waveform.

@numba.guvectorize dspeed.processors.convolutions.reflected_convolve_wf(w_in, kernel, w_out)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: fff->, ddd->

Convolve a waveform with a kernel using reflection padding at the boundaries.

This function extends the input waveform by reflecting its edges before convolution to minimize boundary artifacts. The reflection length is determined by the kernel size.

Parameters:

w_in (np.ndarray) – The input waveform to be convolved.
kernel (np.ndarray) – The convolution kernel. Must be shorter than or equal to w_in.
w_out (np.ndarray) – Output array for the filtered waveform. Will be filled with the convolution result, or NaN if inputs are invalid.

Raises:

DSPFatal – If the kernel length exceeds the input waveform length.

Notes

If either w_in or kernel contains NaN values, w_out is set to NaN.
Uses ‘reflect’ mode padding to extend the signal at boundaries.
The extension length is (len(kernel) // 2) + 1 on each side.

dspeed.processors.dwt module¶

Discrete wavelet transform processors for waveform analysis.

@numba.guvectorize dspeed.processors.dwt.discrete_wavelet_transform(w_in, level, wave_type, coeff, w_out)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: fibbf->, dlbbd->

Apply a discrete wavelet transform to the waveform and return only the detailed or approximate coefficients.

Parameters:

w_in (ndarray) – The input waveform
level (int) – The level of decompositions to be performed (1, 2, ...)
wave_type (int) – The wavelet type for discrete convolution ('h' = 'haar', 'd' = 'db1').
coeff (int) – The coefficients to be saved ('a', 'd')
w_out (ndarray) – The approximate coefficients. The dimension of this array can be calculated by out_dim = len(w_in)/(filter_length^level), where filter_length can be obtained via pywt.Wavelet(wave_type).dec_len

YAML Configuration Example

dwt_haar:
  function: discrete_wavelet_transform
  module: dspeed.processors
  args:
    - wf_blsub
    - 5
    - "'h'"
    - "'a'"
    - "dwt_haar(256, 'f')"
  prereqs:
    - wf_blsub

dspeed.processors.energy_kernels module¶

Energy estimation kernels for DSP pipelines.

@numba.guvectorize dspeed.processors.energy_kernels.cusp_filter(sigma, flat, decay, kernel)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: ffff->, dddd->

Calculates CUSP kernel.

Parameters:

sigma (float) – the curvature of the rising and falling part of the kernel.
flat (int) – the length of the flat section.
decay (int) – the decay constant of the exponential to be convolved.
kernel (array) – the calculated kernel

YAML Configuration Example

kern_cusp:
  function: cusp_filter
  module: dspeed.processors
  args:
    - "10*us"
    - "3*us"
    - "400*us"
    - kern_cusp

@numba.guvectorize dspeed.processors.energy_kernels.dplms(noise_mat, reference, a1, a2, a3, ff, kernel)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: ffffff->f, dddddd->d

Calculate and apply an optimum DPLMS filter to the waveform.

The processor takes the noise matrix and the reference signal as input and calculates the optimum filter according to the provided length and penalized coefficients [DPLMS].

[DPLMS]

V. D’Andrea et al. “Optimum Filter Synthesis with DPLMS Method for Energy Reconstruction” Eur. Phys. J. C 83, 149 (2023). https://doi.org/10.1140/epjc/s10052-023-11299-z

Parameters:

noise_mat (list) – noise matrix
reference (list) – reference signal
a1 (float) – penalized coefficient for the noise matrix
a2 (float) – penalized coefficient for the reference matrix
a3 (float) – penalized coefficient for the zero area matrix
ff (int) – flat top length for the reference signal
kernel (array) – output kernel

YAML Configuration Example

kern_dplms:
  function: dplms
  module: dspeed.processors
  args:
    - db.dplms.noise_matrix
    - db.dplms.reference
    - 50
    - 0.1
    - 1
    - 1
    - kern_dplms

@numba.guvectorize dspeed.processors.energy_kernels.zac_filter(sigma, flat, decay, kernel)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: ffff->, dddd->

Calculates ZAC (Zero Area CUSP) kernel.

Parameters:

sigma (float) – the curvature of the rising and falling part of the kernel.
flat (int) – the length of the flat section.
decay (int) – the decay constant of the exponential to be convolved.
kernel (array) – the calculated kernel

YAML Configuration Example

kern_zac:
  function: zac_filter
  module: dspeed.processors
  args:
    - "10*us"
    - "3*us"
    - "400*us"
    - kern_zac

dspeed.processors.fft module¶

Fast fourier transform processors

@numba.vectorize dspeed.processors.fft.abs2norm(x, norm)¶

Precompiled signatures: DI->d, FI->f

Helper for psd

@numba.guvectorize dspeed.processors.fft.fft(w_in, dft_out)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: fF->, dD->

Perform a discrete fourier transform from a real waveform to a complex fourier spectrum

Parameters:

w_in – input waveform
dft_out – output discrete fourier transform

YAML Configuration Example

dft:
    function: dspeed.processors.fft
    args:
      - wf
      - dft(len(wf)//2+1, period=1/wf.period/len(wf)

@numba.guvectorize dspeed.processors.fft.ifft(dft_in, w_out)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: Ff->, Dd->

Perform an inverse discrete fourier transform from a complex discrete fourier spectrum to a real waveform to a complex

Parameters:

dft_in – input discrete fourier transform
w_out – output waveform

YAML Configuration Example

waveform:
    function: dspeed.processors.ifft
    args:
      - dft
      - waveform((len(dft)-1)*2, period=2/dft.period/len(dft)

@numba.guvectorize dspeed.processors.fft.psd(w_in, psd_out)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: ff->, dd->

Perform a discrete fourier transform from a real waveform and extract the power spectral density

Parameters:

w_in – input waveform
psd_out – output discrete power spectrum

YAML Configuration Example

psd:
    function: dspeed.processors.psd
    args:
      - wf
      - psd(len(wf)//2+1, period=1/wf.period/len(wf)

dspeed.processors.fixed_time_pickoff module¶

Processors computing fixed-time pick-off metrics.

@numba.guvectorize dspeed.processors.fixed_time_pickoff.fixed_time_pickoff(w_in, t_in, mode_in, a_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ffb->f, ddb->d

Pick off the waveform value at the provided time.

For non-integral times, interpolate between samples using the method selected using mode_in. If the provided index t_in is out of range, return numpy.nan.

Parameters:

w_in (ndarray) – the input waveform.
t_in (float) – the waveform index to pick off.
mode_in (int8) –
character selecting which interpolation method to use. Note this must be passed as a int8, e.g. ord('i'). Options:
- i – integer t_in; equivalent to fixed_sample_pickoff()
- n – nearest-neighbor interpolation; defined at all values, but not continuous
- f – floor, or value at previous neighbor; defined at all values but not continuous
- c – ceiling, or value at next neighbor; defined at all values, but not continuous
- l – linear interpolation; continuous at all values, but not differentiable
- h – Hermite cubic spline interpolation; continuous and differentiable at all values but not twice-differentiable
- s – natural cubic spline interpolation; continuous and twice-differentiable at all values. This method is much slower than the others because it utilizes the entire input waveform!
a_out (float) – the output pick-off value.

Examples

trapEftp:
  function: fixed_time_pickoff
  module: dspeed.processors
  args:
    - wf_trap
    - "tp_0+10*us"
    - "'h'"
    - trapEftp

dspeed.processors.gaussian_filter1d module¶

Processors applying one-dimensional Gaussian smoothing filters.

@numba.guvectorize dspeed.processors.gaussian_filter1d.gaussian_filter1d(sigma, truncate, weights)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: fff->, ddd->

1-D Gaussian filter.

Note

This processor is composed of a factory function that is called using the init_args argument. The input and output waveforms are passed using args.

Parameters:

sigma (int) – standard deviation for Gaussian kernel
truncate (float) – truncate the filter at this many standard deviations.

dspeed.processors.get_multi_local_extrema module¶

Processors finding multiple local extrema in waveforms.

@numba.guvectorize dspeed.processors.get_multi_local_extrema.get_multi_local_extrema(w_in, a_delta_max_in, a_delta_min_in, search_direction, a_abs_max_in, a_abs_min_in, vt_max_out, vt_min_out, n_max_out, n_min_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ffffffffII->, ddddddddII->

Get lists of indices of the local maxima and minima of data.

Converted from a MATLAB script by E. Billauer. See the parameters description for details about search modes and further settings.

Parameters:

w_in (ndarray) – the array of data within which extrema will be found.
a_delta_min_in (float) – the relative level by which data must vary (in the search direction) about a candidate minimum in order for it to be tagged.
a_delta_max_in (float) – the relative level by which data must vary (in the search direction) about a candidate maximum in order for it to be tagged.
search_direction (int) –
the direction in which the input waveform is processed.
- 0: one sweep, first to last sample
- 1: one sweep, last to first sample
- 2: two sweeps, in both directions. Largest common set of found extrema is returned (logical AND)
- 3: two sweeps, in both directions. Union of found extrema is returned (logical OR)
a_abs_min_in (float) – a candidate minimum is tagged only if its value is smaller than this.
a_abs_max_in (float) – a candidate maximum is tagged only if its value is larger than this.
vt_min_out (ndarray) – arrays of fixed length (padded with numpy.nan) that hold the indices of the identified minima.
vt_max_out (ndarray) – arrays of fixed length (padded with numpy.nan) that hold the indices of the identified maxima.
n_min_out (int) – the number of minima found in a waveform.
n_max_out (int) – the number of maxima found in a waveform.

YAML Configuration Example

vt_max_out, vt_min_out, n_max_out, n_min_out:
  function: get_multi_local_extrema
  module: dspeed.processors
  args:
    - waveform
    - 5
    - 0.1
    - 1
    - 20
    - 0
    - "vt_max_out(20)"
    - "vt_min_out(20)"
    - n_max_out
    - n_min_out
  unit:
    - ns
    - ns
    - none
    - none

dspeed.processors.get_wf_centroid module¶

Processors estimating waveform centroids.

@numba.guvectorize dspeed.processors.get_wf_centroid.get_wf_centroid(w_in, shift, centroid)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ff->f, dd->d

Calculate waveform centroid.

Note

This processor calculate the centroid position when provided the convolution product with a step function.

Parameters:

w_in (ndarray) – the input waveform.
shift (int) – shift.
centroid (int) – centroid position.

YAML Configuration Example

centroid:
  function: get_wf_centroid
  module: dspeed.processors
  args:
    - waveform
    - shift
    - centroid

dspeed.processors.histogram module¶

Histogramming utilities for waveform-derived quantities.

@numba.guvectorize dspeed.processors.histogram.histogram(w_in, weights_out, borders_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fff->, ddd->

Produces and returns an histogram of the waveform.

Parameters:

w_in (ndarray) – Data to be histogrammed.
weights_out (ndarray) – The output histogram weights.
borders_out (ndarray) – The output histogram bin edges of the histogram. Length must be len(weights_out)+1

YAML Configuration Example

hist_weights, hist_borders:
  function: histogram
  module: dspeed.processors.histogram
  args:
    - waveform
    - "hist_weights(100)"
    - "hist_borders(101)"
  unit:
    - none
    - ADC

Note

This implementation is significantly faster than just wrapping numpy.histogram().

See also

histogram_stats

@numba.guvectorize dspeed.processors.histogram.histogram_around_mode(w_in, center, bin_width, weights_out, borders_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fffff->, ddddd->

Creates a histogram centered at a specified point. If no point given, use the mode of the input data, resulting in two histogramming passes: 1. using the full min-max range to determine the mode 2. histogramming around the mode to determine the final output histogram. If a valid center is given, only step 2 is performed. The number of samples is determined from the size of the output arrays. The histogram will always be aligned such that the center is in the center of a bin, even if an even number of bins is requested.

Parameters:

w_in (ndarray) – Data to be histogrammed.
center (float) – center of the final output histogram; best a integer if histogramming ADC values. If NAN, use the mode instead
bin_width (float) – the bin width of the output histogram (not used for determining the mode). Best to use integer values to avoid aliasing.
weights_out (ndarray) – The output histogram weights.
borders_out (ndarray) – The output histogram bin edges of the histogram. Length must be len(weights_out)+1

YAML Configuration Example

hist_weights, hist_borders:
  function: histogram
  module: dspeed.processors.histogram
  args:
    - waveform
    - np.nan
    - 1
    - "hist_weights(101)"
    - "hist_borders(102)"
  unit:
    - none
    - ADC

See also

histogram

dspeed.processors.histogram_stats module¶

Processors computing summary statistics from histograms.

@numba.guvectorize dspeed.processors.histogram_stats.histogram_peakstats(weights_in, edges_in, max_in, skip_zeroes, width_type, mode_out, width_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fffii->ff, dddii->dd

Compute peak statistics for a histogram, including mode and width. The mode is determined either by the global maximum or by a user-specified value. The width is computed according to the selected width_type (FWHM or a HWHM option). Best to use the histogram from histogram_around_mode.

Parameters:

weights_in (ndarray) – Histogram weights (bin contents).
edges_in (ndarray) – Histogram bin edges.
max_in (float) – If not numpy.nan, the mode is derived as the bin center closest to max_in. Otherwise, the mode is computed automatically.
skip_zeroes (int) – If 1, zero bins are skipped when computing the width. If 0, zeroes are not skipped; not possible if aliasing is present; use histogram_around_mode instead of histogram then!
width_type (int) – Determines the method for width calculation: 0: FWHM 1: Minimum of HWHM 2: Maximum of HWHM 3: left HWHM (towards lower ADC) 4: right HWHM (towards higher ADC)
mode_out (float) – Output: the computed mode value; always in the center of a bin.
width_out (float) – Output: the computed width value.

YAML Configuration Example

mode_out, width_out:
  function: histogram_peakstats
  module: dspeed.processors
  args:
    - hist_weights
    - hist_borders
    - np.nan
    - 0
    - 0
    - mode_out
    - width_out
  unit:
    - ADC
    - ADC

See also

histogram_around_mode

@numba.guvectorize dspeed.processors.histogram_stats.histogram_stats(weights_in, edges_in, mode_out, max_out, fwhm_out, max_in)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ffffff->, dddddd->

Compute useful histogram-related quantities. Be careful, since outputs are biased, as the computed mode is aligned with the left edge of the bin.

Parameters:

weights_in (ndarray) – histogram weights.
edges_in (ndarray) – histogram bin edges.
max_in (float) – if not numpy.nan, the mode is derived as the bin edge closest to max_in. Otherwise the mode is computed automatically.
mode_out (int) – The index of the mode.
max_out (float) – the computed mode of the histogram. If max_in is not numpy.nan then the closest edge to max_in is returned.
fwhm_out (float) – is actually the HALF width at half maximum (HWHM) of the histogram. The calculations starts from the mode and descends left and right, taking the largest HWHM found in either direction.

YAML Configuration Example

hwhm, idx_out, mode_out:
  function: histogram_stats
  module: dspeed.processors
  args:
    - hist_weights
    - hist_borders
    - idx_out
    - mode_out
    - hwhm
    - np.nan
  unit:
    - ADC
    - none
    - ADC

See also

histogram

dspeed.processors.iir_filter module¶

Helpers for constructing IIR filter processors.

dspeed.processors.iir_filter.iir_filter(freq, order, rp=None, rs=None, f_samp=None, ftype='butter', btype='lowpass')¶

Generator function for an iir filter based on ‘’scipy.signal.iirfilter’’.

Parameters:

freq (Quantity | float | Collection) – critical frequency(s) of filter. If no f_samp is provided, express as fraction of nyquist frequency. If bandpass or bandstop, provide array of 2 values
order (int) – order of filter
rp (float | None) – for Chebyshev and elliptical, maximum ripple in the passband (dB)
rs (float | None) – for Chebyshev and elliptical, minimum attenuation in the stopband (dB)
f_samp (Quantity | float | ProcChainVar | None) – sampling frequency for input waveform or ProcessingChain variable representing waveform
ftype (str) – design of filter: {‘butter’, ‘cheby1’, ‘cheby2’, ‘ellip’, ‘bessel’} (default to butter)
btype (str) – type of filter: {‘lowpass’, ‘highpass’, ‘bandpass’, ‘bandstop’} (default to lowpass)

YAML Configuration Example

wf_lp:
  function: iir_filter
  module: dspeed.processors
  init_args:
    - "15*MHz"
    - 4
    - wf
    - "ftype=butter"
    - "btype=lowpass"
  args:
    - wf
    - "wf_lp(unit=ADC)"

dspeed.processors.iir_filter.notch_filter(freq, bandwidth, f_samp=None)¶

Generator function for a notch filter

Parameters:

freq (Quantity | float) – frequency of notch filter. If no f_samp is provided, express as fraction of nyquist frequency
bandwidth (Quantity | float) – bandwidth of notch filter
f_samp (Quantity | float | ProcChainVar | None) – sampling frequency for input waveform or ProcessingChain variable representing waveform

YAML Configuration Example

wf_notch:
  function: notch_filter
  module: dspeed.processors
  init_args:
    - "15*MHz"
    - "1.5*MHz"
    - wf
  args:
    - wf
    - "wf_notch(unit=ADC)"

dspeed.processors.iir_filter.peak_filter(freq, bandwidth, f_samp=None)¶

Generator function for a peak filter

Parameters:

freq (Quantity | float) – frequency of peak filter. If no f_samp is provided, express as fraction of nyquist frequency
bandwidth (Quantity | float) – bandwidth of peak filter
f_samp (Quantity | float | ProcChainVar | None) – sampling frequency for input waveform or ProcessingChain variable representing waveform

YAML Configuration Example

wf_peak:
  function: peak_filter
  module: dspeed.processors
  init_args:
    - "15*MHz"
    - "1.5*MHz"
    - wf
  args:
    - wf
    - "wf_peak(unit=ADC)"

dspeed.processors.inject_ringing module¶

Processors injecting damped oscillatory ringing into waveforms.

@numba.guvectorize dspeed.processors.inject_ringing.inject_damped_oscillation(w_in, tau, omega, phase, frac, w_out)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: fdddd->f, ddddd->d

Inject a damped oscillation component/pole into the electronics response

Parameters:

w_in (ndarray) – the input waveform.
tau (float) – time constant of decay
omega (float) – angular frequency of oscillation
phase (float) – phase shift of oscillation
frac (float) – fraction of amplitude in injected pole
w_out (ndarray) – output waveform after injecting decay component

dspeed.processors.inl_correction module¶

Integral non-linearity correction processors.

@numba.guvectorize dspeed.processors.inl_correction.inl_correction(w_in, inl, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: if->f, id->d

INL correction.

Note

This processor correct the input waveform by applying the INL.

Parameters:

w_in (ndarray) – the input waveform.
inl (ndarray) – inl correction array.
w_out (ndarray) – corrected waveform.

YAML Configuration Example

"wf_corr": {
    "function": "inl_correction",
    "module": "dspeed.processors",
    "args": ["w_in", "inl", "w_out"],
    "unit": "ADC"
 }

dspeed.processors.kernels module¶

Kernel generator utilities for DSP filters.

@numba.guvectorize dspeed.processors.kernels.moving_slope(kernel)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: f->, d->

Calculates the linear slope of kernel

Parameters:

length – the length of the section to calculate slope
kernel – the output kernel

YAML Configuration Example

kern_slopes:
  function: moving_slope
  module: dspeed.processors
  args:
    - 12
    - kern_slopes

@numba.guvectorize dspeed.processors.kernels.step(weight_pos, kernel)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: ff->, dd->

Process waveforms with a step function.

Parameters:

weight_pos (int) – relative weight of positive step side.
kernel (array) – output kernel

YAML Configuration Example

kern_step:
  function: step
  module: dspeed.processors
  args:
    - 16
    - kern_step

@numba.guvectorize dspeed.processors.kernels.t0_filter(rise, fall, kernel)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: fff->, ddd->

Apply a modified, asymmetric trapezoidal filter to the waveform.

Parameters:

rise (int) – the length of the rise section. This is the linearly increasing section of the filter that performs a weighted average.
fall (int) – the length of the fall section. This is the simple averaging part of the filter.
kernel (array) – the output kernel

YAML Configuration Example

t0_filter:
  function: t0_filter
  module: dspeed.processors
  args:
    - "128*ns"
    - "2*us"
    - t0_filter
  init_args:
    - "128*ns"
    - "2*us"

dspeed.processors.linear_slope_fit module¶

Processors for fitting a linear slope to waveform segments.

@numba.guvectorize dspeed.processors.linear_slope_fit.linear_slope_diff(w_in, slope, intercept, mean, rms)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fff->ff, ddd->dd

Calculate the mean and rms of the waveform after subtracting out the provided slope and intercept.

Uses Welford’s method and linear regression.

Parameters:

w_in (ndarray) – the input waveform.
slope (float) – the slope of the linear fit.
intercept (float) – the intercept of the linear fit.
mean (float) – the mean of the waveform after subtracting the slope/intercept.
stdev – the standard deviation of the waveform after subtracting the slope/intercept.

YAML Configuration Example

bl_slope_diff , bl_slope_rms:
  description: "finds mean and rms relative to linear fit of the baseline section"
  function: linear_slope_diff
  module: dspeed.processors
  args:
    - "wf_presum[0: round(44.5*us, wf_presum.period)]"
    - bl_slope
    - bl_intercept
    - bl_slope_diff
    - bl_slope_rms
  unit:
    - ADC
    - ADC

@numba.guvectorize dspeed.processors.linear_slope_fit.linear_slope_fit(w_in, mean, stdev, slope, intercept)¶

Options: boundscheck=False, cache=True
Precompiled signatures: f->ffff, d->dddd

Calculate the mean and standard deviation of the waveform using Welford’s method as well as the slope an intercept of the waveform using linear regression.

Parameters:

w_in (ndarray) – the input waveform.
mean (float) – the mean of the waveform.
stdev (float) – the standard deviation of the waveform.
slope (float) – the slope of the linear fit.
intercept (float) – the intercept of the linear fit.

YAML Configuration Example

bl_mean, bl_std, bl_slope, bl_intercept:
  function: linear_slope_fit
  module: dspeed.processors
  args:
    - "wf_blsub[0:round(44.5*us, wf_blsub.period)]"
    - bl_mean
    - bl_std
    - bl_slope
    - bl_intercept
  unit:
    - ADC
    - ADC
    - ADC
    - ADC

dspeed.processors.log_check module¶

Processors performing logarithmic consistency checks on waveforms.

@numba.guvectorize dspeed.processors.log_check.log_check(w_in, w_log)¶

Options: boundscheck=False, cache=True
Precompiled signatures: f->f, d->d

Calculate the logarithm of the waveform if all its values are positive; otherwise, return NaN.

Parameters:

w_in (ndarray) – the input waveform.
w_log (ndarray) – the output waveform with logged values.

YAML Configuration Example

wf_logged:
  function: log_check
  module: dspeed.processors
  args:
    - "wf_blsub[2100:]"
    - wf_logged

dspeed.processors.min_max module¶

Processors computing minimum and maximum waveform statistics.

@numba.guvectorize dspeed.processors.min_max.min_max(w_in, t_min, t_max, a_min, a_max)¶

Options: boundscheck=False, cache=True
Precompiled signatures: f->ffff, d->dddd

Find the value and index of the minimum and maximum values in the waveform.

Note

The first found instance of each extremum in the waveform will be returned.

Parameters:

w_in (ndarray) – the input waveform
t_min (int) – the index of the minimum value
t_max (int) – the index of the maximum value
a_min (float) – the minimum value
a_max (float) – the maximum value

YAML Configuration Example

tp_min, tp_max, wf_min, wf_max:
  function: min_max
  module: dspeed.processors
  args:
    - waveform
    - tp_min
    - tp_max
    - wf_min
    - wf_max
  unit:
    - ns
    - ns
    - ADC
    - ADC

@numba.guvectorize dspeed.processors.min_max.min_max_norm(w_in, a_min, a_max, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fff->f, ddd->d

Normalize waveform by minimum or maximum value, whichever is greater in absolute value.

Parameters:

w_in (ndarray) – the input waveform
a_min (float) – the minimum value
a_max (float) – the maximum value
w_out (ndarray) – the normalized output waveform

YAML Configuration Example

wf_norm:
  function: min_max_norm
  module: dspeed.processors
  args:
    - wf_blsub
    - wf_min
    - wf_max
    - wf_norm
  unit:
    - ADC

dspeed.processors.ml module¶

Module containing ml processors, the dsp config can be used to combine these into a neural network a simple example would be:

layer_1:
  function: normalisation_layer
  module: dspeed.processors
  args:
    - wf_blsub
    - db.mean
    - db.variance
    - layer_1
layer_2:
  function: dense_layer_with_bias
  module: dspeed.processors
  args:
    - layer_1
    - db.kernel
    - db.bias
    - "'r'"
    - layer_2
classifier:
  function: dense_layer_with_bias
  module: dspeed.processors
  args:
    - layer_2
    - db.kernel
    - db.bias
    - "'s'"
    - classifier

@numba.guvectorize dspeed.processors.ml.classification_layer_no_bias(x_in, kernel, activation_func, x_out)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: ffb->f, ddb->d

This is the same as dense_layer_no_bias but the final output is a single number f(x.W)

Parameters:

w_in – the input waveform shape n.
kernel (ndarray) – the matrix of weights shape (n x 1).
activation_func (int8) – the activation function to use specify with char: s - sigmoid r - relu l - leaky relu m - softmax t - tanh
x_out (float) – the output value.

YAML Configuration Example

classifier:
  function: dense_layer_with_bias
  module: dspeed.processors
  args:
    - wf_blsub
    - db.kernel
    - "'s'"
    - classifier

@numba.guvectorize dspeed.processors.ml.classification_layer_with_bias(x_in, kernel, bias, activation_func, x_out)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: fffb->f, dddb->d

this is the same as dense_layer_with_bias but the final output is a single number f(x.W+bs)

Parameters:

w_in – the input waveform shape n.
kernel (ndarray) – the matrix of weights shape (n x 1).
bias (ndarray) – the bias in this case a single value.
activation_func (int8) – the activation function to use specify with char: s - sigmoid r - relu l - leaky relu m - softmax t - tanh
x_out (float) – the output value.

YAML Configuration Example

classifier:
  function: dense_layer_with_bias
  module: dspeed.processors
  args:
    - wf_blsub
    - db.kernel
    - db.bias
    - "'s'"
    - classifier

@numba.guvectorize dspeed.processors.ml.dense_layer_no_bias(x_in, kernel, activation_func, x_out)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: ffb->f, ddb->d

Dense neural network layer without a bias term.

Parameters:

x_in (ndarray) – Input vector with length n.
kernel (ndarray) – Matrix of weights with shape (n, m).
activation_func (int8) – Character flag indicating which activation to apply. Supported values are s (sigmoid), r (ReLU), l (leaky ReLU), m (softplus), and t (hyperbolic tangent).
x_out (ndarray) – Output vector with length m.

YAML Configuration Example

layer_1:
  function: dense_layer_no_bias
  module: dspeed.processors
  args:
    - wf_blsub
    - db.kernel
    - "'s'"
    - layer_1

@numba.guvectorize dspeed.processors.ml.dense_layer_with_bias(x_in, kernel, bias, activation_func, x_out)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: fffb->f, dddb->d

Dense neural network layer with an additive bias term.

Parameters:

x_in (ndarray) – Input vector with length n.
kernel (ndarray) – Matrix of weights with shape (n, m).
bias (ndarray) – Bias vector with length m.
activation_func (int8) – Character flag indicating which activation to apply. Supported values are s (sigmoid), r (ReLU), l (leaky ReLU), m (softplus), and t (hyperbolic tangent).
x_out (ndarray) – Output vector with length m.

YAML Configuration Example

layer_1:
  function: dense_layer_with_bias
  module: dspeed.processors
  args:
    - wf_blsub
    - db.kernel
    - db.bias
    - "'s'"
    - layer_1

@numba.guvectorize dspeed.processors.ml.leaky_relu(x_in, x_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: f->f, d->d

Apply a leaky ReLU activation with a 0.01 negative slope.

@numba.guvectorize dspeed.processors.ml.normalisation_layer(x_in, means, variances, x_out)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: fff->f, ddd->d

Normalisation layer, (x_in - mu)/np.sqrt(variance) Note this is variance not standard deviation

Parameters:

w_in – the input waveform shape n.
means (ndarray) – array of means for each input value shape n.
variances (ndarray) – array of variances for each input value shape n.
x_out (ndarray) – the output vector shape n.

YAML Configuration Example

wf_normed:
  function: normalisation_layer
  module: dspeed.processors
  args:
    - wf_blsub
    - db.mean
    - db.variance
    - wf_normed

@numba.guvectorize dspeed.processors.ml.relu(x_in, x_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: f->f, d->d

Apply the rectified linear unit activation function.

@numba.guvectorize dspeed.processors.ml.sigmoid(x_in, x_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: f->f, d->d

Apply the logistic sigmoid activation function.

@numba.guvectorize dspeed.processors.ml.softmax(x_in, x_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: f->f, d->d

Apply a numerically stable softplus-style activation.

dspeed.processors.moving_windows module¶

Processors for applying moving window average convolution to waveforms.

@numba.guvectorize dspeed.processors.moving_windows.avg_current(w_in, length, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fff->, ddd->

Calculate the derivative of a waveform, averaged across length samples.

Parameters:

w_in (ndarray) – the input waveform.
length (float) – length of the moving window to be applied.
w_out (ndarray) – output waveform after derivation.

YAML Configuration Example

curr:
  function: avg_current
  module: dspeed.processors
  args:
    - wf_pz
    - 1
    - "curr(len(wf_pz)-1, f)"
  unit: ADC/sample

@numba.guvectorize dspeed.processors.moving_windows.moving_window_left(w_in, length, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ff->f, dd->d

Applies a moving average window to the waveform.

Note

Starts from the left and assumes that the baseline is at zero.

Parameters:

w_in (ndarray) – the input waveform.
length (float) – length of the moving window to be applied.
w_out (ndarray) – output waveform after moving window applied.

YAML Configuration Example

wf_mw:
  function: moving_window_left
  module: dspeed.processors
  args:
    - wf_pz
    - "96*ns"
    - wf_mw

@numba.guvectorize dspeed.processors.moving_windows.moving_window_multi(w_in, length, num_mw, mw_type, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fffi->f, dddi->d

Apply a series of moving-average windows to the waveform, alternating its application between the left and the right.

Parameters:

w_in (ndarray) – the input waveform.
length (float) – length of the moving window to be applied.
num_mw (int) – the number of moving windows.
mw_type (int) –
- 0 – alternate moving windows right and left
- 1 – only left
- 2 – only right
w_out (ndarray) – the windowed waveform.

YAML Configuration Example

curr_av:
  function: moving_window_multi
  module: dspeed.processors
  args:
    - curr
    - "96*ns"
    - 3
    - 0
    - curr_av
  unit: ADC/sample

@numba.guvectorize dspeed.processors.moving_windows.moving_window_right(w_in, length, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ff->f, dd->d

Applies a moving average window to the waveform from the right.

Parameters:

w_in (ndarray) – the input waveform.
length (float) – length of the moving window to be applied.
w_out (ndarray) – output waveform after moving window applied.

YAML Configuration Example

wf_mw:
  function: moving_window_right
  module: dspeed.processors
  args:
    - wf_pz
    - "96*ns"
    - wf_mw

dspeed.processors.multi_a_filter module¶

Processors for identifying multiple maxima and their amplitudes in a waveform.

@numba.guvectorize dspeed.processors.multi_a_filter.multi_a_filter(w_in, vt_maxs_in, va_max_out)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: ff->f, dd->d

Finds the maximums in a waveform and returns the amplitude of the wave at those points.

Parameters:

w_in – the array of data within which amplitudes of extrema will be found.
vt_maxs_in – the array of max positions for each waveform.
va_max_out – an array (in-place filled) of the amplitudes of the maximums of the waveform.

dspeed.processors.multi_t_filter module¶

Processors for identifying multiple leading edges in waveforms.

@numba.guvectorize dspeed.processors.multi_t_filter.multi_t_filter(w_in, a_threshold_in, vt_max_in, vt_min_in, t_out)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: fffff->, ddddd->

Gets list of indices of the start of leading edges of multiple peaks within a waveform.

Is built to handle afterpulses/delayed cross-talk and trains of pulses. Works by calling the vectorized functions get_multi_local_extrema() which returns a list of the maxima and minima in a waveform, and then the list of maxima is fed into time_point_thresh() which returns the final times that waveform is less than a specified threshold.

Parameters:

w_in (ndarray) – the array of data within which the list of leading edge times will be found.
a_threshold_in (float) – threshold to search for using time_point_thresh().
vt_max_in (ndarray) – the array of maximum positions for each waveform.
vt_min_in (ndarray) – the array of minimum positions for each waveform.
t_out (ndarray) – output array of fixed length (padded with numpy.nan) that hold the indices of the identified initial rise times of peaks in the signal.

See also

time_point_thresh

@numba.guvectorize dspeed.processors.multi_t_filter.remove_duplicates(t_in, vt_min_in, t_out)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: ff->f, dd->d

Helper function to remove duplicate peak positions.

time_point_thresh() has issues with afterpulsing in waveforms that causes an aferpulse peak position to be sent to zero or the same index as the first pulse. This only happens when the relative minimum between the first pulse and the afterpulse is greater than the threshold. So, we sweep through the array again to ensure there are no duplicate indices. If there are duplicate indices caused by a misidentified position of an afterpulse, we replace its index by that of the corresponding minimum found using get_multi_local_extrema(). It also checks to make sure that the maximum of a waveform isn’t right at index 0.

Parameters:

t_in (ndarray) – the array of indices that we want to remove duplicates from.
vt_min_in (ndarray) – list of indices of minima that we want to replace duplicates in t_out with.
t_out (ndarray) – the array we want to return that will have no duplicate indices in it.

See also

multi_t_filter

dspeed.processors.nnls module¶

Helpers for running non-negative least-squares optimizations.

@numba.guvectorize dspeed.processors.nnls.optimize_nnls(a, b, maxiter, tol, allow_singularity, min_value, x)¶

Options: nopython=True, boundscheck=False, cache=True
Precompiled signatures: ffff?ff->, dddf?fd->

Solve argmin_x || ax - b ||_2 for x>=0. Based on scipy.optimize.nnls() implementation. Which in turn is based on the algorithm in Bro, R. and De Jong, S. (1997), A fast non-negativity-constrained least squares algorithm. J. Chemometrics, 11: 393-401

Parameters:

a ((m, n) ndarray) – Coefficient matrix
b ((m,) ndarray, float) – Right-hand side vector.
maxiter (int) – Maximum number of iterations.
tol (float) – Tolerance value used in the algorithm to assess closeness to zero in the projected residual (a.T @ (a x - b) entries. Increasing this value relaxes the solution constraints.
allow_singularity (bool) – If matrix is not solvable (e.g. because of non full rank caused by float precision), no error is raised but all elements of the solution vector are set NaN
x (ndarray) – Solution vector.

YAML Configuration Example

nnls_solution:
  function: optimize_nnls
  module: dspeed.processors
  args:
    - db.coefficient_matrix
    - wf_blsub
    - 1000
    - 1e-6
    - True
    - nnls_solution

dspeed.processors.optimize module¶

Processors for identifying optimal pole-zero coefficients.

class dspeed.processors.optimize.Model(func, w_in, baseline, beg, end)¶

Bases: object

A class representing the function to minimize.

errordef = 1.0¶

@numba.guvectorize dspeed.processors.optimize.optimize_1pz(w_in, a_baseline_in, t_beg_in, t_end_in, p0_in, val0_out)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: fffff->f, ddddd->d

Find the optimal, single pole-zero cancellation’s parameter by minimizing the slope in the waveform’s specified time range.

Parameters:

w_in (ndarray) – the input waveform.
a_baseline_in (float) – the resting baseline.
t_beg_in (int) – the lower bound’s index for the time range over which to optimize the pole-zero cancellation.
t_end_in (int) – the upper bound’s index for the time range over which to optimize the pole-zero cancellation.
p0_in (float) – the initial guess of the optimal time constant.
val0_out (float) – the output value of the best-fit time constant.

YAML Configuration Example

tau0:
  function: optimize_1pz
  module: dspeed.processors
  args:
    - waveform
    - baseline
    - 0
    - "20*us"
    - "500*us"
    - tau0
  unit: us

See also

pole_zero, double_pole_zero

@numba.guvectorize dspeed.processors.optimize.optimize_2pz(w_in, a_baseline_in, t_beg_in, t_end_in, tau_upper_bound, frac_upper_bound, p0_in, p1_in, p2_in, val0_out, val1_out, val2_out)¶

Options: boundscheck=False, forceobj=True, cache=True
Precompiled signatures: fffffffff->fff, ddddddddd->ddd

Find the optimal, double pole-zero cancellation’s parameters by minimizing the slope in the waveform’s specified time range.

Parameters:

w_in (ndarray) – the input waveform.
a_baseline_in (float) – the resting baseline.
t_beg_in (int) – the lower bound’s index for the time range over which to optimize the pole-zero cancellation.
t_end_in (int) – the upper bound’s index for the time range over which to optimize the pole-zero cancellation.
tau_upper_bound (float) – the upper bound for the fit for the two time constants.
frac_upper_bound (float) – the upper bound for the fit for the frac.
p0_in (float) – the initial guess of the optimal, longer time constant.
p1_in (float) – the initial guess of the optimal, shorter time constant.
p2_in (float) – the initial guess of the optimal fraction.
val0_out (float) – the output value of the best-fit, longer time constant.
val1_out (float) – the output value of the best-fit, shorter time constant.
val2_out (float) – the output value of the best-fit fraction.

YAML Configuration Example

tau1, tau2, frac:
  function: optimize_2pz
  module: dspeed.processors
  args:
    - waveform
    - baseline
    - 0
    - "20*us"
    - "500*us"
    - "20*us"
    - 0.02
    - tau1
    - tau2
    - frac
  unit: us

dspeed.processors.param_lookup module¶

Processors for looking up parameters from calibration tables.

dspeed.processors.param_lookup.param_lookup(param_dict, default_val, dtype)¶

Generate the numpy.ufunc lookup(channel, val), which returns a NumPy array of values corresponding to various channels that are looked up in the provided param_dict. If there is no key, use default_val instead.

Return type:: ufunc

dspeed.processors.peak_snr_threshold module¶

Processors for identifying significant local minima.

@numba.guvectorize dspeed.processors.peak_snr_threshold.peak_snr_threshold(w_in, idx_in, ratio_in, width_in, idx_out, n_idx_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ffff->fI, dddd->dI

Search for local minima in a window around the provided indices.

If a minimum is found it is checked whether amplitude of the minimum divided by the amplitude of the waveform at the index is smaller then the given ratio. If this is the case the index is copied to the output.

Parameters:

w_in (ndarray) – the input waveform.
idx_in (ndarray) – the array of indices of possible signal candidates.
ratio_in (float) – ratio threshold value.
width_in (int) – width of the local search window.
idx_out (ndarray) – indices of local minima.
n_idx_out (int) – number of non-numpy.nan indices in idx_out.

dspeed.processors.pmt_pulse_injector module¶

Processors that inject parameterized photomultiplier pulses into waveforms.

@numba.guvectorize dspeed.processors.pmt_pulse_injector.inject_general_logistic(wf_in, a, t0, rt, q, v, decay, wf_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fffffff->f, ddddddd->d

Inject sigmoid pulse into existing waveform to simulate pileup.

\[s(t) = \frac{A}{(1 + q \exp[-4 \log(99) (t - t_0 - t_r/2) / t_r])^{1/v}} e^{-(t-t_0)/\tau}\]

Parameters:

wf_in (ndarray) – the input waveform.
a (float) – the amplitude \(A\) of the injected waveform.
t0 (float) – the position \(t_0\) of the injected waveform.
rt (float) – the rise time \(t_r\) of the injected waveform.
q (float) – shaping parameter of the logistic function.
v (float) – shaping parameter of the logistic function.
decay (float) – the decay parameter \(\tau\) of the injected waveform.
wf_out (ndarray) – the output waveform.

@numba.guvectorize dspeed.processors.pmt_pulse_injector.inject_gumbel(wf_in, a, t0, beta, wf_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ffff->f, dddd->d

Injects a Gumbel distribution into the waveform wf_in, modifying it in place in wf_out.

Parameters: - wf_in: Input waveform (1D array). - a: Amplitude of the Gumbel distribution. - t0: Temporal centroid of the Gumbel distribution. - beta: Scale parameter (controls spread of the Gumbel distribution). - wf_out: Output waveform (1D array), modified by adding the Gumbel distribution.

dspeed.processors.pole_zero module¶

Pole-zero cancellation processors for waveform shaping.

@numba.guvectorize dspeed.processors.pole_zero.double_pole_zero(w_in, t_tau1, t_tau2, frac, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ffff->f, dddd->d

Apply a double pole-zero cancellation using the provided time constants to the waveform.

Parameters:

w_in (ndarray) – the input waveform.
t_tau1 (float) – the time constant of the first exponential to be deconvolved.
t_tau2 (float) – the time constant of the second exponential to be deconvolved.
frac (float) – the fraction which the second exponential contributes.
w_out (ndarray) – the pole-zero cancelled waveform.

Return type:

ndarray

YAML Configuration Example

wf_pz:
  function: double_pole_zero
  module: dspeed.processors
  args:
    - wf_bl
    - "400*us"
    - "20*us"
    - "0.02"
    - "True"
    - wf_pz

Notes

This algorithm is an IIR filter to deconvolve the function

\[s(t) = A \left[ f \cdot \exp\left(-\frac{t}{\tau_2} \right) + (1-f) \cdot \exp\left(-\frac{t}{\tau_1}\right) \right]\]

(\(f\) = frac) into a single step function of amplitude \(A\). This filter is derived by \(z\)-transforming the input (\(s(t)\)) and output (step function) signals, and then determining the transfer function. For shorthand, define \(a=\exp(-1/\tau_1)\) and \(b=\exp(-1/\tau_2)\), the transfer function is then:

\[H(z) = \frac{1 - (a+b)z^{-1} + abz^{-2}} {1 + (fb - fa - b - 1)z^{-1}-(fb - fa - b)z^{-2}}\]

By equating the transfer function to the ratio of output to input waveforms \(H(z) = w_\text{out}(z) / w_\text{in}(z)\) and then taking the inverse \(z\)-transform yields the filter as run in the function, where \(f\) is the frac parameter:

\[\begin{split}w_\text{out}[n] =& w_\text{in}[n] - (a+b)w_\text{in}[n-1] + abw_\text{in}[n-2] \\ & -(fb - fa - b - 1)w_\text{out}[n-1] + (fb - fa - b)w_\text{out}[n-2]\end{split}\]

@numba.guvectorize dspeed.processors.pole_zero.pole_zero(w_in, t_tau, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ff->f, dd->d

Apply a pole-zero cancellation using the provided time constant to the waveform.

Parameters:

w_in (ndarray) – the input waveform.
t_tau (float) – the time constant of the exponential to be deconvolved.
w_out (ndarray) – the pole-zero cancelled waveform.

YAML Configuration Example

wf_pz:
  function: pole_zero
  module: dspeed.processors
  args:
    - wf_bl
    - "400*us"
    - wf_pz

dspeed.processors.poly_fit module¶

Polynomial fitting processors for waveforms.

@numba.guvectorize dspeed.processors.poly_fit._poly_fitter(w_in, inv, poly_pars)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fd->f, dd->d

Helper function that fits w_in to order len(poly_pars)-1 polynomial, while providing necessary inverse matrix.

@numba.guvectorize dspeed.processors.poly_fit.poly_diff(w_in, poly_pars, mean, rms)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ff->ff, dd->dd

@numba.guvectorize dspeed.processors.poly_fit.poly_exp_rms(w_in, poly_pars, mean, rms)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ff->ff, dd->dd

dspeed.processors.poly_fit.poly_fit(length, deg)¶

Factory function for generating a polynomial fitter for an input of length length to a polynomial of order deg.

YAML Configuration Example

fit_pars:
    function: dspeed.processors.poly_fit
    args: ["wf_logged", "fit_pars(shape=4)"]
    init_args: ["len(wf_logged)", 3]

dspeed.processors.presum module¶

Processors for down-sampling waveform using pre-summing.

@numba.guvectorize dspeed.processors.presum.presum(w_in, do_norm, ps_fact, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ffff->, dddd->

Presum the waveform.

Combine bins in chunks of len(w_in) / len(w_out), which is hopefully an integer. If it isn’t, then some samples at the end will be omitted.

Parameters:

w_in (ndarray) – the input waveform.
do_norm (int) –
a flag for setting returned chunks are normalized
- 0: chunks are not normalized
- 1: chunks are normalized
ps_fact (int) – the presum factor/rate, determined by len(w_in) // len(w_out)
w_out (ndarray) – the output waveform.

dspeed.processors.pulse_injector module¶

Processors that inject analytic pulses into waveforms.

@numba.guvectorize dspeed.processors.pulse_injector.inject_exp_pulse(wf_in, t0, rt, a, decay, wf_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fffff->f, ddddd->d

Inject exponential pulse into existing waveform to simulate pileup.

Parameters:

wf_in (ndarray) – the input waveform.
t0 (int) – the position of the injected waveform.
rt (float) – the rise time of the injected waveform.
a (float) – the amplitude of the injected waveform.
decay (float) – the exponential decay constant of the injected waveform.
wf_out (ndarray) – the output waveform.

@numba.guvectorize dspeed.processors.pulse_injector.inject_sig_pulse(wf_in, t0, rt, a, decay, wf_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fffff->f, ddddd->d

Inject sigmoid pulse into existing waveform to simulate pileup.

\[s(t) = \frac{A}{1 + \exp[-4 \log(99) (t - t_0 - t_r/2) / t_r]} e^{-(t-t_0)/\tau}\]

Parameters:

wf_in (ndarray) – the input waveform.
t0 (int) – the position \(t_0\) of the injected waveform.
rt (float) – the rise time \(t_r\) of the injected waveform.
a (float) – the amplitude \(A\) of the injected waveform.
decay (float) – the decay parameter \(\tau\) of the injected waveform.
wf_out (ndarray) – the output waveform.

dspeed.processors.rc_cr2 module¶

Processors implementing RC-CR^2 shaping filters.

@numba.guvectorize dspeed.processors.rc_cr2.rc_cr2(w_in, t_tau, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ff->f, dd->d

Apply a RC-CR^2 filter with the provided time constant to the waveform. Useful for determining pileup and trigger times. The filter was computed using a matched z-transform to keep the poles/zeroes of the analog transfer function in the same location.

Parameters:

w_in (array) – the input waveform.
t_tau (float) – the time constant of the integration and differentiaion
w_out (array) – the RC-CR^2 filtered waveform.

YAML Configuration Example

wf_RC_CR2:
  function: rc_cr2
  module: dspeed.processors
  args:
    - wf_bl
    - "300*ns"
    - wf_RC_CR2

dspeed.processors.recursive_filter module¶

Generic processors used to implement recursive digital filters from poles and zeros.

@numba.guvectorize dspeed.processors.recursive_filter.recursive_filter(w_in, a, b, init_in, init_out, w_out)¶

Options: nopython=True, boundscheck=False, cache=True
Precompiled signatures: fffff->f, ddddd->d

Apply a recursive filter using a and b as the feedforward and feedback coefficients, respectively:

\[w_{out}[i] = (a[0]*w_{in}[i] + a[1]*w_{in}[i-1] + a[2]*w_{in}[i-2] + ... - b[1]*w_{out}[i-1] - b[2]*w_{out}[i-2] - ...)/b[0]\]

When performing a z-transform, a and b represent the polynomial coefficients of the numerator and denominator, respectively:

..math::: F(z) = frac{a[0] + a[1]*z^{-1} + a[2]*z^{-2} + …}{b[0] + b[1]*z^{-1} + b[2]*z^{-2} + …}

See scipy.signal.iir_filter for an example of how to generate these coefficients (using 'ba' output).

The initial conditions for the filter are set using init_in and init_out to pad the starts of w_in and w_out. These should be set appropriately to minimize edge effects.

Parameters:

w_in – the input waveform
a – feedforward (numerator) coefficients
b – feedback (denominator) coefficients
init_in – initial value to pad at front of w_in
init_out – initial value of w_out memory
w_out – the output waveform

dspeed.processors.round_to_nearest module¶

Processors for rounding values to multiples of provided value.

@numba.vectorize dspeed.processors.round_to_nearest.ceil_to_nearest(val, to_nearest)¶

Precompiled signatures: BB->B, HH->H, II->I, LL->L, bb->b, hh->h, ii->i, ll->l, ff->f, dd->d

Return smallest multiple of to_nearest that is >= val.

Parameters:

val (ndarray) – value to be ceiled
to_nearest (int | float) – ceil to multiple of this
out – ceiled value

YAML Configuration Example

Note: this processor is aliased using ceil in ProcessingChain. The following two examples are equivalent.

# Equivalent forms:
t_ceil:
  function: ceil_to_nearest
  module: dspeed.processors
  args:
    - t_in
    - "1*us"
    - t_ceil
  unit:
    - ns

t_ceil: "ceil(t_in, 1*us)"

@numba.vectorize dspeed.processors.round_to_nearest.floor_to_nearest(val, to_nearest)¶

Precompiled signatures: BB->B, HH->H, II->I, LL->L, bb->b, hh->h, ii->i, ll->l, ff->f, dd->d

Return largest multiple of to_nearest that is <= val

Parameters:

val (ndarray) – value to be floored
to_nearest (int | float) – floor to multiple of this
out – floored value

YAML Configuration Example

Note: this processor is aliased using floor in ProcessingChain. The following two examples are equivalent.

# Equivalent forms:
t_floor:
  function: floor_to_nearest
  module: dspeed.processors
  args:
    - t_in
    - "1*us"
    - t_floor
  unit:
    - ns

t_floor: "floor(t_in, 1*us)"

@numba.vectorize dspeed.processors.round_to_nearest.round_to_nearest(val, to_nearest)¶

Precompiled signatures: BB->B, HH->H, II->I, LL->L, bb->b, hh->h, ii->i, ll->l, ff->f, dd->d

Round value to nearest multiple of to_nearest.

Parameters:

val (ndarray) – value to be rounded
to_nearest (int | float) – round to multiple of this
out – rounded value

YAML Configuration Example

Note: this processor is aliased using round in ProcessingChain. The following two examples are equivalent.

# Equivalent forms:
t_rounded:
  function: round_to_nearest
  module: dspeed.processors
  args:
    - t_in
    - "1*us"
    - t_rounded
  unit:
    - ns

t_rounded: "round(t_in, 1*us)"

@numba.vectorize dspeed.processors.round_to_nearest.trunc_to_nearest(val, to_nearest)¶

Precompiled signatures: BB->B, HH->H, II->I, LL->L, bb->b, hh->h, ii->i, ll->l, ff->f, dd->d

Return multiple of to_nearest that is closest to val, towards zero

Parameters:

val (ndarray) – value to be truncated
to_nearest (int | float) – truncate to multiple of this
out – truncated value

YAML Configuration Example

Note: this processor is aliased using ceil in ProcessingChain. The following two examples are equivalent.

# Equivalent forms:
t_trunc:
  function: trunc_to_nearest
  module: dspeed.processors
  args:
    - t_in
    - "1*us"
    - t_trunc
  unit:
    - ns

t_trunc: "trunc(t_in, 1*us)"

dspeed.processors.saturation module¶

Processors that check for samples at saturation limit.

@numba.guvectorize dspeed.processors.saturation.saturation(w_in, bit_depth_in, n_lo_out, n_hi_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ff->ff, dd->dd

Count the number of samples in the waveform that are saturated at the minimum and maximum possible values based on the bit depth.

Parameters:

w_in (ndarray) – the input waveform
bit_depth_in (int) – the bit depth of the analog-to-digital converter
n_lo_out (int) – the output number of samples at the minimum
n_hi_out (int) – the output number of samples at the maximum

YAML Configuration Example

sat_lo, sat_hi:
  function: saturation
  module: dspeed.processors
  args:
    - waveform
    - 16
    - sat_lo
    - sat_hi

dspeed.processors.soft_pileup_corr module¶

Processors implementing soft pile-up corrections.

@numba.guvectorize dspeed.processors.soft_pileup_corr.soft_pileup_corr(w_in, n_in, tau_in, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fff->f, ddd->d

Fit the baseline to an exponential with the provided time constant and then subtract the best-fit function from the entire waveform.

Parameters:

w_in (ndarray) – The input waveform.
n_in (int) – The number of samples at the beginning of the waveform to fit to an exponential.
tau_in (float) – The fixed, exponential time constant.
w_out (ndarray) – The output waveform with the exponential subtracted.

YAML Configuration Example

wf_bl:
  function: soft_pileup_corr
  module: dspeed.processors
  args:
    - waveform
    - "1000"
    - "500*us"
    - wf_bl

@numba.guvectorize dspeed.processors.soft_pileup_corr.soft_pileup_corr_bl(w_in, n_in, tau_in, b_in, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ffff->f, dddd->d

Fit the baseline to an exponential with the provided time constant and then subtract the best-fit function from the entire waveform.

Parameters:

w_in (ndarray) – the input waveform.
n_in (int) – the number of samples at the beginning of the waveform to fit to an exponential.
tau_in (float) – the fixed, exponential time constant.
b_in (float) – the fixed, exponential constant.
w_out (ndarray) – the output waveform with the exponential subtracted.

YAML Configuration Example

wf_bl:
  function: soft_pileup_corr_bl
  module: dspeed.processors
  args:
    - waveform
    - "1000"
    - "500*us"
    - baseline
    - wf_bl

dspeed.processors.sort module¶

@numba.guvectorize dspeed.processors.sort.sort(w_in, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: f->f, d->d

Return a sorted array.

Parameters:

w_in (ndarray) – the input waveform.
w_out (ndarray) – the output sorted waveform.

YAML Configuration Example

wf_sorted:
  function: sort
  module: dspeed.processors
  args:
    - waveform
    - wf_sorted

dspeed.processors.svm module¶

Support vector machine inference processors.

dspeed.processors.svm.svm_predict(svm_file)¶

Apply a Support Vector Machine (SVM) to an input waveform to predict a data cleaning label.

Note

This processor is composed of a factory function that is called using the init_args argument. The input waveform and output label are passed using args.

Parameters:: svm_file (str) – The name of the file with the trained SVM svm_p*_r*_T***Z.sav
Return type:: Callable

YAML Configuration Example

svm_label:
  function: svm_predict
  module: dspeed.processors
  args:
    - dwt_norm
    - svm_label
  unit: ""
  prereqs:
    - dwt_norm
  init_args:
    - "'svm_p*_r*_T***Z.sav'"

dspeed.processors.tf_model module¶

Generate a processor from a tensorflow model stored in a keras file.

dspeed.processors.tf_model.tf_model(filepath)¶

Initializer to load a TensorFlow model to use in a ProcessingChain.

Parameters:: filepath (str) – name of keras file containing model
Return type:: GUFuncWrapper

YAML Configuration Example

classifier:
  function: dspeed.processors.tf_model
  args:
    - input
    - output
  init_args:
    - "'model.keras'"

dspeed.processors.time_over_threshold module¶

Processors computing time-over-threshold metrics.

@numba.guvectorize dspeed.processors.time_over_threshold.time_over_threshold(w_in, a_threshold, n_samples)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ff->f, dd->d

Calculates the number of samples in the input waveform over a_threshold

Parameters:

w_in (ndarray) – the input waveform.
a_threshold (float) – the threshold value.
n_samples (float) – the number of samples over the threshold.

YAML Configuration Example

t_sat:
  function: time_over_threshold
  module: dspeed.processors
  args:
    - wf_pz
    - a_threshold
    - t_sat
  unit: ns

dspeed.processors.time_point_thresh module¶

Processors locating waveform time points via thresholding.

@numba.guvectorize dspeed.processors.time_point_thresh.bi_level_zero_crossing_time_points(w_in, a_pos_threshold_in, a_neg_threshold_in, gate_time_in, t_start_in, n_crossings_out, polarity_out, t_trig_times_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fffffIff->, dddddIdd->

Find the indices where a waveform value crosses 0 after crossing the threshold and reaching the next threshold within some gate time. Works on positive and negative polarity waveforms. Useful for finding pileup events with the RC-CR^2 filter.

Parameters:

w_in (ndarray) – the input waveform.
a_pos_threshold_in (float) – the positive threshold value.
a_neg_threshold_in (float) – the negative threshold value.
gate_time_in (int) – The number of samples that the next threshold crossing has to be within in order to count a 0 crossing
t_start_in (int) – the starting index.
n_crossings_out (int) – the number of zero-crossings found. Note: if there are more zeros than elements in output arrays, this will continue to increment but the polarity and trigger time will not be added to the output buffers
polarity_out (array) – An array holding the polarity of identified pulses. 0 for negative and 1 for positive
t_trig_times_out (array) – the indices where the waveform value has crossed the threshold and returned to 0. Arrays of fixed length (padded with numpy.nan) that hold the indices of the identified trigger times.

YAML Configuration Example

trig_times_out:
  function: multi_trigger_time
  module: dspeed.processors
  args:
    - wf_rc_cr2
    - 5
    - -10
    - 0
    - n_crossings
    - "polarity_out(20, vector_len=n_crossings)"
    - "trig_times_out(20, vector_len=n_crossings)"
  unit: ns

@numba.guvectorize dspeed.processors.time_point_thresh.interpolated_time_point_thresh(w_in, a_threshold, t_start, walk_forward, mode_in, t_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ffflb->f, dddlb->d

Find the time where the waveform value crosses the threshold

Search performed walking either forward or backward from the starting index. Use interpolation to estimate a time between samples. Interpolation mode selected with mode_in.

Parameters:

w_in (ndarray) – the input waveform.
a_threshold (float) – the threshold value.
t_start (int) – the starting index.
walk_forward (int) – the backward (0) or forward (1) search direction.
mode_in (int8) –
Character selecting which interpolation method to use. Note this must be passed as a int8, e.g. ord('i'). Options:
- i – integer t_in; equivalent to fixed_sample_pickoff()
- b – before; closest integer sample before threshold crossing
- a – after; closest integer sample after threshold crossing
- r – round; round to nearest integer sample to threshold crossing
- l – linear interpolation
The following modes are meant to mirror the options dspeed.upsampler
- f – floor; interpolated values are at previous neighbor. Equivalent to a
- c – ceiling, interpolated values are at next neighbor. Equivalent to b
- n – nearest-neighbor interpolation; threshold crossing is half-way between samples
- h – Hermite cubic spline interpolation (not implemented)
- s – natural cubic spline interpolation (not implemented)
t_out (float) – the index where the waveform value crosses the threshold.

YAML Configuration Example

tp_0:
  function: time_point_thresh
  module: dspeed.processors
  args:
    - wf_atrap
    - bl_std
    - tp_start
    - 0
    - "'l'"
    - tp_0
  unit: ns

@numba.guvectorize dspeed.processors.time_point_thresh.multi_time_point_thresh(w_in, a_threshold, t_start, polarity, mode_in, t_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ffffb->f, ddddb->d

Find the time where the waveform value crosses the threshold

Search performed walking either forward or backward from the starting index. Use interpolation to estimate a time between samples. Interpolation mode selected with mode_in.

Parameters:

w_in (ndarray) – the input waveform.
a_threshold (ndarray) – list of threshold values.
t_start (int) – the starting index.
polarity (int) – is the average slope of the waveform up (>0) or down (<0) in the search region; only sign matters, not value. Raise Exception if 0.
mode_in (int8) –
Character selecting which interpolation method to use. Note this must be passed as a int8, e.g. ord('i'). Options:
- i – integer t_in; equivalent to fixed_sample_pickoff()
- b – before; closest integer sample before threshold crossing
- a – after; closest integer sample after threshold crossing
- r – round; round to nearest integer sample to threshold crossing
- l – linear interpolation
The following modes are meant to mirror the options dspeed.upsampler
- f – floor; interpolated values are at previous neighbor. Equivalent to a
- c – ceiling, interpolated values are at next neighbor. Equivalent to b
- n – nearest-neighbor interpolation; threshold crossing is half-way between samples
- h – Hermite cubic spline interpolation (not implemented)
- s – natural cubic spline interpolation (not implemented)
t_out (ndarray) – the index where the waveform value crosses the threshold.

YAML Configuration Example

tp_0:
  function: time_point_thresh
  module: dspeed.processors
  args:
    - wf_atrap
    - bl_std
    - tp_start
    - 0
    - "'l'"
    - tp_0
  unit: ns

@numba.guvectorize dspeed.processors.time_point_thresh.time_point_thresh(w_in, a_threshold, t_start, walk_forward, t_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ffff->f, dddd->d

Find the index where the waveform value crosses the threshold, walking either forward or backward from the starting index. Find crossings where the waveform crosses through the threshold in either direction when moving forward in time. Return the waveform index just before the threshold crossing.

Parameters:

w_in (ndarray) – the input waveform.
a_threshold (float) – the threshold value.
t_start (int) – the starting index.
walk_forward (int) – the backward (0) or forward (1) search direction.
t_out (float) – the index where the waveform value crosses the threshold.

YAML Configuration Example

tp_0:
  function: time_point_thresh
  module: dspeed.processors
  args:
    - wf_atrap
    - bl_std
    - tp_start
    - 0
    - tp_0
  unit: ns

dspeed.processors.trap_filters module¶

Trapezoidal filter utilities and processors.

@numba.guvectorize dspeed.processors.trap_filters.asym_trap_filter(w_in, rise, flat, fall, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fiii->f, diii->d

Apply an asymmetric trapezoidal filter to the waveform, normalized by the number of samples averaged in the rise and fall sections.

Parameters:

w_in (ndarray) – the input waveform.
rise (int) – the number of samples averaged in the rise section.
flat (int) – the delay between the rise and fall sections.
fall (int) – the number of samples averaged in the fall section.
w_out (ndarray) – the normalized, filtered waveform.

YAML Configuration Example

wf_af:
  function: asym_trap_filter
  module: dspeed.processors
  args:
    - wf_pz
    - "128*ns"
    - "64*ns"
    - "2*us"
    - wf_af

@numba.guvectorize dspeed.processors.trap_filters.trap_filter(w_in, rise, flat, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fii->f, dii->d

Apply a symmetric trapezoidal filter to the waveform.

Parameters:

w_in (ndarray) – the input waveform.
rise (int) – the number of samples averaged in the rise and fall sections.
flat (int) – the delay between the rise and fall sections.
w_out (ndarray) – the filtered waveform.

YAML Configuration Example

wf_tf:
  function: trap_filter
  module: dspeed.processors
  args:
    - wf_pz
    - "10*us"
    - "3*us"
    - wf_tf

@numba.guvectorize dspeed.processors.trap_filters.trap_norm(w_in, rise, flat, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fii->f, dii->d

Apply a symmetric trapezoidal filter to the waveform, normalized by the number of samples averaged in the rise and fall sections.

Parameters:

w_in (ndarray) – the input waveform.
rise (int) – the number of samples averaged in the rise and fall sections.
flat (int) – the delay between the rise and fall sections.
w_out (ndarray) – the normalized, filtered waveform.

YAML Configuration Example

wf_tf:
  function: trap_norm
  module: dspeed.processors
  args:
    - wf_pz
    - "10*us"
    - "3*us"
    - wf_tf

@numba.guvectorize dspeed.processors.trap_filters.trap_pickoff(w_in, rise, flat, t_pickoff, a_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fiif->f, diid->d

Pick off the value at the provided index of a symmetric trapezoidal filter to the input waveform, normalized by the number of samples averaged in the rise and fall sections.

Parameters:

w_in (ndarray) – the input waveform.
rise (int) – the number of samples averaged in the rise and fall sections.
flat (int) – the delay between the rise and fall sections.
t_pickoff (float) – the waveform index to pick off.
a_out (float) – the output pick-off value of the filtered waveform.

YAML Configuration Example

ct_corr:
  function: trap_pickoff
  module: dspeed.processors
  args:
    - wf_pz
    - "1.5*us"
    - 0
    - tp_0
    - ct_corr

dspeed.processors.unit_conversion module¶

Unit conversion helpers for processing chain coordinate systems.

@numba.vectorize dspeed.processors.unit_conversion.convert(buf_in, offset_in, offset_out, period_ratio)¶

Precompiled signatures: fddd->f, dddd->d

@numba.vectorize dspeed.processors.unit_conversion.convert_ceil(buf_in, offset_in, offset_out, period_ratio)¶

Precompiled signatures: Bddd->B, Hddd->H, Iddd->I, Lddd->L, bddd->b, hddd->h, iddd->i, lddd->l, fddd->f, dddd->d

@numba.vectorize dspeed.processors.unit_conversion.convert_floor(buf_in, offset_in, offset_out, period_ratio)¶

Precompiled signatures: Bddd->B, Hddd->H, Iddd->I, Lddd->L, bddd->b, hddd->h, iddd->i, lddd->l, fddd->f, dddd->d

@numba.vectorize dspeed.processors.unit_conversion.convert_int(buf_in, offset_in, offset_out, period_ratio)¶

Precompiled signatures: Bddd->B, Hddd->H, Iddd->I, Lddd->L, bddd->b, hddd->h, iddd->i, lddd->l

@numba.vectorize dspeed.processors.unit_conversion.convert_round(buf_in, offset_in, offset_out, period_ratio)¶

Precompiled signatures: Bddd->B, Hddd->H, Iddd->I, Lddd->L, bddd->b, hddd->h, iddd->i, lddd->l, fddd->f, dddd->d

@numba.vectorize dspeed.processors.unit_conversion.convert_trunc(buf_in, offset_in, offset_out, period_ratio)¶

Precompiled signatures: Bddd->B, Hddd->H, Iddd->I, Lddd->L, bddd->b, hddd->h, iddd->i, lddd->l, fddd->f, dddd->d

dspeed.processors.upsampler module¶

Processors for upsampling waveforms via interpolation.

@numba.guvectorize dspeed.processors.upsampler.interpolating_upsampler(w_in, mode_in, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fbf->, dbd->

Upsamples the waveform.

Resampling ratio is set by size of w_out and w_in. Using the interpolation technique specified by mode_in to fill newly added samples.

Parameters:

w_in (ndarray) – waveform to upsample.
mode_in (int8) –
character selecting which interpolation method to use. Note this must be passed as a int8, e.g. ord('i'). Options:
- i – only set values at original samples; fill in between with zeros. Requires integer resampling ratio
- n – nearest-neighbor interpolation; defined at all values, but not continuous
- f – floor, or value at previous neighbor; defined at all values but not continuous
- c – ceiling, or value at next neighbor; defined at all values, but not continuous
- l – linear interpolation; continuous at all values, but not differentiable
- h – Hermite cubic spline interpolation; continuous and differentiable at all values but not twice-differentiable
- s – natural cubic spline interpolation; continuous and twice- differentiable at all values. This method is much slower than the others because it utilizes the entire input waveform!
w_out (ndarray) – output array for upsampled waveform.

YAML Configuration Example

wf_up:
  function: interpolating_upsampler
  module: dspeed.processors
  args:
    - wf
    - "'s'"
    - "wf_up(len(wf)*10, period=wf.period/10)"

@numba.guvectorize dspeed.processors.upsampler.upsampler(w_in, upsample, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fff->, ddd->

Upsamples the waveform by the number specified.

Note

A series of moving windows should be applied afterwards for smoothing.

Parameters:

w_in (ndarray) – waveform to upsample.
upsample (float) – number of samples to increase each sample to.
w_out (ndarray) – output array for upsampled waveform.

dspeed.processors.wf_alignment module¶

Processors for waveform alignment and interpolation.

@numba.guvectorize dspeed.processors.wf_alignment.wf_alignment(w_in, centroid, shift, size, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fffff->, ddddd->

Align waveform.

Note

This processor align the input waveform by setting the centroid position at the center of the output waveform.

Parameters:

w_in (ndarray) – the input waveform.
centroid (int) – centroid.
shift (int) – shift.
size (int) – size of output waveform.
w_out (ndarray) – aligned waveform.

YAML Configuration Example

wf_align:
  function: wf_alignment
  module: dspeed.processors
  args:
    - waveform
    - centroid
    - shift
    - size
    - wf_align

dspeed.processors.wf_correction module¶

@numba.guvectorize dspeed.processors.wf_correction.wf_correction(w_in, w_corr, start_idx, stop_idx, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: ffii->f, ddii->d

Waveform correction.

Note

This processor correct the input waveform by applying a correction.

Parameters:

w_in (ndarray) – the input waveform.
w_corr (ndarray) – correction array.
start_idx (int) – index to start the correction.
stop_idx (int) – index to stop the correction.
w_out (ndarray) – corrected waveform.

YAML Configuration Example

"w_corr": {
    "function": "wf_correction",
    "module": "dspeed.processors",
    "args": ["w_in", "w_corr", 0, 2, "w_out"],
    "unit": "ADC"
 }

dspeed.processors.where module¶

Conditional selection processor that wraps numpy.where().

@numba.guvectorize dspeed.processors.where.where(condition, a, b, out)¶

Options: nopython=True, boundscheck=False, cache=True
Precompiled signatures: ?BB->B, ?HH->H, ?II->I, ?LL->L, ?bb->b, ?hh->h, ?ii->i, ?ll->l, ?ff->f, ?dd->d

Return elements chosen from a or b depending on condition.

Parameters:

condition – Boolean mask that selects which input to use.
a – Value to emit wherever condition is True.
b – Value to emit wherever condition is False.
out – Destination array that receives the selected values.

YAML Configuration Example

Note: this processor is aliased using where in ProcessingChain and the a if b else c syntax. The following examples are equivalent.

a_or_b:
  function: dspeed.processors.where
  args:
    - condition
    - a
    - b
    - a_or_b
a_or_b: "where(condition, a, b)"
a_or_b: "a if condition else b"

dspeed.processors.wiener_filter module¶

Wiener filter processors for waveform denoising.

dspeed.processors.wiener_filter.wiener_filter(file_name_array)¶

Apply a Wiener filter to the waveform.

Note

The convolution is performed in the frequency domain. This processor is composed of a factory function that is called using the init_args argument. The input and output waveforms are passed using args. The input must be the Fourier transform of the waveform. The output is the filtered waveform in the frequency domain.

Parameters:: file_name_array (list[str]) – Array with path to an HDF5 file containing the time domain version of the superpulse in one column and noise waveform in another, the superpulse HDF5 group must be titled spms/processed/superpulse and the noise waveform must be called spms/processed/noise_wf.
Return type:: ndarray

YAML Configuration Example

wf_wiener:
  function: wiener_filter
  module: dspeed.processors
  args:
    - wf_bl_fft
    - "wf_wiener(2000,f)"
  unit: dB
  init_args:
    - /path/to/file/wiener.lh5

dspeed.processors.windower module¶

Windowing utility processors for waveform preparation.

@numba.guvectorize dspeed.processors.windower.windower(w_in, t0_in, w_out)¶

Options: boundscheck=False, cache=True
Precompiled signatures: fff->, ddd->

Return a shorter sample of the waveform, starting at the specified index.

Note

The length of the output waveform is determined by the length of w_out rather than an input parameter. If the the length of w_out plus t0_in extends past the end of w_in or if t0_in is negative, remaining values are padded with numpy.nan.

Parameters:

w_in (ndarray) – the input waveform.
t0_in (int) – the starting index of the window.
w_out (ndarray) – the windowed waveform.