abstract type AbstractRadFIRFilter <: AbstractRadLinearFilter

Abstract type for FIR filters.

abstract type AbstractRadIIRFilter <: AbstractRadSigFilter{LinearFiltering}

Abstract type for IIR filters.

abstract type AbstractRadSigFilter{FT<:FilteringType} <: Function

Abstract type for signal filters.

Filters are callable as (flt::AbstractRadSigFilter)(input) and come with specialized broadcasting.

Subtypes of AbstractRadSigFilter must implement

fltinstance(flt::AbstractRadSigFilter, si::SamplingInfo)::[`AbstractRadSigFilterInstance`](@ref)

Invertible filters should also implement

• InverseFunctions.inverse(flt::SomeFilter)

Note that while a filter may have an inverse, it may, depending on the filter paramters, be very unstable in the presence of additional noise. Filters with a high-pass characteristic pass high-frequency noise, so their inverses pass such noise as well without amplifying it (substantially). Filters with a low-pass characteristic, on the other hand, attentuate high-frequency noise, so their inverses amplify such noise and are typically not useful to deconvolve signals in practical applications.

abstract type AbstractRadSigFilterInstance{FT<:FilteringType}

Abstract type for signal filter instances. Filter instances are specilized to a specific length and numerical type of input and output.

Filter instances are callable as (fi::SomeFilterInstance)(input) and come with specialized broadcasting.

Subtypes of AbstractRadSigFilterInstance must implement

• RadiationDetectorDSP.rdfilt!(output, fi::SomeFilterInstance, input)

• RadiationDetectorDSP.flt_output_smpltype(fi::SomeFilterInstance)

• RadiationDetectorDSP.flt_input_smpltype(fi::SomeFilterInstance)

• RadiationDetectorDSP.flt_output_length(fi::SomeFilterInstance)

• RadiationDetectorDSP.flt_input_length(fi::SomeFilterInstance)

• RadiationDetectorDSP.flt_output_time_axis(fi::SomeFilterInstance, time::AbstractVector{<:RealQuantity})

Invertible filter instances should implement

• InverseFunctions.inverse(fi::SomeFilterInstance)

Default methods are implemented for

• RadiationDetectorDSP.rdfilt(fi::AbstractRadSigFilterInstance, x::AbstractSamples)
• RadiationDetectorDSP.rdfilt(fi::AbstractRadSigFilterInstance, wf::RDWaveform)
• RadiationDetectorDSP.bc_rdfilt(fi::AbstractRadSigFilterInstance, inputs)

The default methods that operate on RadiationDetectorSignals.RDWaveforms require RadiationDetectorDSP.flt_output_time_axis.

const AbstractSamples{T<:RealQuantity} = AbstractVector{T}

A vector of signal samples.

const ArrayOfSimilarSamples{T<:RealQuantity} = ArrayOfSimilarVectors{T}

An array of similar sample vectors.

struct BiquadFilter{T<:RealQuantity} <: AbstractRadIIRFilter

A biquad filter.

Constructors:

• BiquadFilter(fields...)

Fields:

• b_012::Tuple{T, T, T} where T<:(Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real): Coefficients b0 to b2

• a_12::Tuple{T, T} where T<:(Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real): Coefficients a1 to a2, a_0 equals one implicitly

RadiationDetectorDSP.CPUNormAdaptor

To be used with Adapt.adapt.

Adapt.adapt(RadiationDetectorDSP.CPUNormAdaptor, x) adapts x to reside on the CPU and tries to ensure that arrays are stored in column-major order.

struct CRFilter <: AbstractRadIIRFilter

A first-order CR highpass filter.

The inverse filter is InvCRFilter, this is typically stable even in the presence of additional noise. This is because a CR filter passes high-frequency noise and so it's inverse passes such noise as well without amplifying it.

Constructors:

• CRFilter(fields...)

Fields:

• cr::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: CR time constant

struct CUSPChargeFilter <: AbstractRadFIRFilter

CUSP filter.

For the definition the filter and a discussion of the filter properties, see

Constructors:

• CUSPChargeFilter(; fields...)

Fields:

• sigma::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: equivalent of shaping time (τₛ) Default: 450

• toplen::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: length of flat top (FT) Default: 10

• tau::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: decay constant of the exponential Default: 20

• length::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: total length of the filter (L) Default: 100

• beta::AbstractFloat: scaling factor Default: 100.0

struct ConvolutionFilter{T<:RealQuantity} <: AbstractRadFIRFilter

A FIR filter defined by it's filter taps, applied via convolution with the input signal.

Constructors:

• ConvolutionFilter(fields...)

Fields:

• method::RadiationDetectorDSP.ConvolutionMethod: Convolution method

• coeffs::AbstractVector{T} where T<:(Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real): Filter taps

• offset::Int64: Time axis offset

abstract type ConvolutionMethod

Indended as a type parameter to designate the behavior of a filter as linear or nonlinear.

Subtypes are DirectConvolution and FFTConvolution.

abstract type DNIMethod

Abstract type for denoising and interpolation methods.

struct DifferentiatorFilter <: AbstractRadIIRFilter

An integrator filter. It's inverse is IntegratorFilter.

Constructors:

• DifferentiatorFilter(fields...)

Fields:

• gain::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: Filter gain

DirectConvolution() isa ConvolutionMethod

Compute filter convolutions directly, without FFT.

FFTConvolution() isa ConvolutionMethod

Compute filter convolutions via FFT.

abstract type FilteringType

Indended as a type parameter to designate the behavior of a filter as linear or nonlinear.

Subtypes are LinearFiltering and NonlinearFiltering.

struct FirstOrderIIR{T<:RealQuantity} <: AbstractRadIIRFilter

A biquad filter.

Constructors:

• FirstOrderIIR(fields...)

Fields:

• b_01::Tuple{T, T} where T<:(Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real): Coefficients b0 to b1

• a_1::Tuple{T} where T<:(Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real): Coefficient a1, a0 equals one implicitly

struct Gauss1DFilter <: AbstractRadFIRFilter

One dimensional gaussian filter defined as: f(x) = beta * exp(-0.5*(x/sigma)^2) / length

where x is in the interval [-alphasigma, alphasigma]

Constructors:

• Gauss1DFilter(; fields...)

Fields:

• sigma::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: standard deviation Default: 1.0

• length::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: total length of the filter Default: 100.0

• alpha::AbstractFloat: the amount of standard deviations to cover in the gaussian window Default: 1.0

• beta::AbstractFloat: scaling factor Default: 100.0

struct IntegratorCRFilter <: AbstractRadIIRFilter

A modified CR-filter. The filter has an inverse.

Constructors:

• IntegratorCRFilter(fields...)

Fields:

• gain::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: Filter gain

• cr::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: CR time constant

struct IntegratorFilter <: AbstractRadIIRFilter

An integrator filter. It's inverse is DifferentiatorFilter.

Constructors:

• IntegratorFilter(fields...)

Fields:

• gain::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: Filter gain

struct IntegratorModCRFilter <: AbstractRadIIRFilter

A modified CR-filter. The filter has an inverse.

Constructors:

• IntegratorModCRFilter(fields...)

Fields:

• gain::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: Filter gain

• cr::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: CR time constant

struct Intersect <: Function

Finds the intersects of a Y with a threshold

Constructors:

• Intersect(; fields...)

Fields:

• mintot::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: minimum time-over-threshold

struct InvCRFilter <: AbstractRadIIRFilter

Inverse of CRFilter.

Constructors:

• InvCRFilter(fields...)

Fields:

• cr::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: CR time constant

struct InvModCRFilter <: AbstractRadIIRFilter

Inverse of ModCRFilter.

Constructors:

• InvModCRFilter(fields...)

Fields:

• cr::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: CR time constant

struct InvRCFilter <: AbstractRadIIRFilter

Inverse of RCFilter.

Constructors:

• InvRCFilter(fields...)

Fields:

• rc::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: RC time constant

struct InvSecondOrderCRFilter <: AbstractRadIIRFilter

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

Constructors:

• InvSecondOrderCRFilter(fields...)

Fields:

• cr::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: time constant of the first exponential to be deconvolved

• cr2::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: time constant of the second exponential to be deconvolved

• f::Real: the fraction faktor which the second exponential contributes

abstract type LinearFiltering <: FilteringType

When used as a type parameter value, marks linear behavior of a filter.

struct ModCRFilter <: AbstractRadIIRFilter

A first-order CR highpass filter, modified for full-amplitude step-signal response.

The resonse of the standard digital CRFilter will not recover the full amplitude of a digital step stignal since a step from one sample to the still has a finite rise time. This version of a CR filter compensates for this loss in amplitude, so it effectively treats a step as having

The inverse filter is InvModCRFilter, this is typically stable even in the presence of additional noise (see CRFilter).

Constructors:

• ModCRFilter(fields...)

Fields:

• cr::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: CR time constant

abstract type NonlinearFiltering <: FilteringType

When used as a type parameter value, marks non linear behavior of a filter.

struct PolynomialDNI <: DNIMethod

Polynomial denoising and interpolation method.

Operates in a similar way as a Savitzky-Golay filter, but interpolates as well.

Constructors:

• PolynomialDNI(; fields...)

Fields:

• degree::Int64: polynomial degree Default: (2, "length")

• length::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real

struct RCFilter <: AbstractRadII>RFilter

A first-order RC lowpass filter.

The inverse filter is InvCRFilter, but note that this is unstable in the presence of additional noise. As an RC filter attenuates high-frequency noise, its inverse amplifies such noise and will typically not be useful to deconvolve signals in practical applications.

Constructors:

• RCFilter(fields...)

Fields:

• rc::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: RC time constant

struct SamplingInfo{T<:RealQuantity,A<:AbstractVector{<:RealQuantity}}

Holds sampling information.

The numerical type of an individual sample is T, the (time) axis is given by the axis field.

Constructors:

• SamplingInfo{T,A}(axis)
• SamplingInfo{T}(axis)

Fields:

• axis::AbstractVector{<:Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real}

struct SavitzkyGolayFilter <: AbstractRadFIRFilter

A Savitzky-Golay filter.

Constructors:

• SavitzkyGolayFilter(; fields...)

Fields:

• length::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: filter length

• degree::Int64: Polynomial defgree

• derivative::Int64: n-th derivative (0 for no derivative)

struct SecondOrderCRFilter <: AbstractRadIIRFilter

A scond order CR highpass filter. The filter has an inverse InvSecondOrderCRFilter.

Constructors:

• SecondOrderCRFilter(fields...)

Fields:

• cr::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: time constant of the first exponential to be deconvolved

• cr2::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: time constant of the second exponential to be deconvolved

• f::Real: the fraction faktor which the second exponential contributes

struct SignalEstimator <: Function

Estimates a signal at a given position x.

Usage:

(f::SamplesOrWaveform)(input::RDWaveform, x::RealQuantity)

Constructors:

• SignalEstimator(; fields...)

Fields:

• dni::DNIMethod: denoising and interpolation method

struct SimpleCSAFilter <: AbstractRadIIRFilter

Simulates the current-signal response of a charge-sensitive preamplifier with resistive reset, the output is a charge signal.

It is equivalent to the composition

CRFilter(cr = tau_decay) ∘
Integrator(gain = gain) ∘
RCFilter(rc = tau_rise)

and maps to a single BiquadFilter.

This filter has an inverse, but the inverse is very unstable in the presence of additional noise if tau_rise is not zero (since the inverse of an RC-filter is unstable under noise). Even if tau_rise is zero the inverse will still amplify noise (since it differentiates), so it should be used very carefully when deconvolving signals in practical applications.

Constructors:

• SimpleCSAFilter(fields...)

Fields:

• tau_rise::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: Rise time constant

• tau_decay::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: Decay time constant

• gain::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: Gain

struct TrapezoidalChargeFilter <: AbstractRadNonlinearFilter

Filter that responds to a step signal with a trapezoidal pulse.

The filter is equivalent to two moving averages separated by a gap.

Constructors:

• TrapezoidalChargeFilter(; fields...)

Fields:

• avgtime::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: pre-rise averaging time

• gaptime::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: gap time

• avgtime2::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: post-rise averaging time

A sharp step on the input will result in a trapezoid with rise time and fall time avgtime and a flat top of length gaptime.

struct TruncateFilter <: AbstractRadSigFilter{LinearFiltering}

Filter that truncates the input signal.

Constructors:

• TruncateFilter(; fields...)

Fields:

• interval::IntervalSets.ClosedInterval{<:Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real}: interval to keep

struct ZACChargeFilter <: AbstractRadFIRFilter

Zero area cusp (ZAC) filter.

For the definition the filter and a discussion of the filter properties, see "Improvement of the energy resolution via an optimized digital signal processing in GERDA Phase I", Eur. Phys. J. C 75, 255 (2015).

Constructors:

• ZACChargeFilter(; fields...)

Fields:

• sigma::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: equivalent of shaping time (τₛ) Default: 450

• toplen::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: length of flat top (FT) Default: 10

• tau::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: decay constant of the exponential Default: 20

• length::Union{Unitful.Quantity{<:var"#s10"}, var"#s10"} where var"#s10"<:Real: total length of the filter (L) Default: 100

• beta::AbstractFloat: scaling factor Default: 100.0

const MaybeWithUnits{T<:Number} = Union{T,Quantity{<:T}}

A numerical value with or without units

const RealQuantity = MaybeWithUnits{<:Real}

A real value with or without units.

const RadiationDetectorDSP.SamplesOrWaveform{T<:RealQuantity} = Union{AbstractSamples{T},RDWaveform{<:Any,T}}

A vector of signal samples or a waveform.

RadiationDetectorDSP::adapt_memlayout(
    fi::AbstractRadSigFilterInstance,
    backend::KernelAbstractions.Backend,
    A::AbstractArray{<:Number}
)

Adapts the memory layout of A in a suitable fashion for fi on computing device backend.

Returns a row-major version of A on all backends by default, filter instance types may specialize this behavior.

add_rect_pulse!(samples::AbstractSamples, start::Integer, pulselen::Integer, amplitude::Real = 1.0)

Add a rectangular pulse to samples.

bc_rdfilt(flt::AbstractRadSigFilter, input)
bc_rdfilt(fi::AbstractRadSigFilterInstance, input)

Broadcast filter instance fi over signals input, return the filtered signals.

bc_rdfilt!(outputs, fi::AbstractRadSigFilterInstance, inputs)

Broadcast filter flt or filter instance fi over signals inputs, storing the results in outputs.

inputs and outputs must be of type AbstractVector{<:AbstractSamples}.

Returns outputs.

charge_trapflt!(samples::AbstractVector{<:RealOrSIMD{<:AbstractFloat}}, navg::Integer, ngap::Integer)

Apply a trapezoidal FIR filter to a charge signal in samples.

cr_filter(CR::Real)

Return a DSP.jl-compatible CR-filter.

crmod_filter(CR::Real)

Return a DSP.jl-compatible modified CR-filter.

cusp_charge_filter_coeffs(N::Int, sigma::U, FT::Int, tau::V, beta::W
) where {U, V, W <: AbstractFloat}

return a vector representing the cusp filter applicaible on a charge signal, where N is the total length of the filter, FT the length of the flat top, sigma the filter shaping time,tau the decay constant and a the scaling factor.

rdfilt!(output, fi::AbstractRadSigFilterInstance, input)

Apply filter flt or filter instance fi to signal input and store the filtered signal in output. Return output.

differentiator_filter(gain::Real)

Return a DSP.jl-compatible differentiator filter.

smplinfo(smpls::AbstractSamples)::SamplingInfo
smplinfo(wf::RDWaveform{T,U})::RDWaveform

Get sampling information an array of vectors of samples, resp. an array of waveform. All elements must have equal samling information.

RadiationDetectorDSP.flt_input_length(fi::AbstractRadSigFilterInstance)::Integer

Get the output signal length of a filter instance fi.

Must be implemented for all subtypes of AbstractRadSigFilterInstance.

RadiationDetectorDSP.flt_input_smpltype(fi::AbstractRadSigFilterInstance)

Get the input sample type of a filter instance fi.

Must be implemented for all subtypes of AbstractRadSigFilterInstance.

RadiationDetectorDSP.flt_output_length(fi::SomeFilterInstance)::Integer

Get the output signal length of filter instance fi.

Must be implemented for all subtypes of AbstractRadSigFilterInstance.

RadiationDetectorDSP.flt_output_smpltype(fi::AbstractRadSigFilterInstance)

Get the output sample type for

• a filter flt given an input sample type input_smpltype
• a filter instance fi

Must be implemented for all subtypes of AbstractRadSigFilter.

RadiationDetectorDSP.flt_output_time_axis(fi::SomeFilterInstance, time::AbstractVector{<:RealQuantity})::AbstractVector{<:RealQuantity}

Get the output time axis of a filter instance fi, given an input time axis time.

Must be implemented for subtypes of AbstractRadSigFilter and AbstractRadSigFilterInstance only if the filter's output time axis can be computed directly from the input time axis.

fltinstance(flt::AbstractRadSigFilter, si::SamplingInfo)::AbstractRadSigFilterInstance

Create a filter instance of the filter flt, specialized for the given input, resp. input characteristics.

gaussian_coeffs(N::Int, sigma::V, alpha::U, beta::U) where {V, U}

compute a gaussian kernel, where N is the total length of the kernel, alpha the amount of standard deviations to cover, sigma the standard deviation and beta the total scaling factor.

gen_rect_pulse(tracelen::Integer, start::Integer, pulselen::Integer, amplitude::Real = 1.0)

Generate a rectangular pulse.

integrator_cr_filter(gain::Real, CR::Real)

Return a DSP.jl-compatible integrator plus CR filter.

integrator_crmod_filter(gain::Real, CR::Real)

Return a DSP.jl-compatible integrator plus modified CR filter.

integrator_filter(gain::Real)

Return a DSP.jl-compatible integrator filter.

inv_cr_filter(CR::Real)

Return a DSP.jl-compatible inverse CR-filter.

inv_crmod_filter(CR::Real)

Return a DSP.jl-compatible inverse modified CR-filter.

inv_rc_filter(RC::Real)

Return a DSP.jl-compatible RC-filter.

multiply_waveform(signal::AbstractSamples, a::RealQuantity)
multiply_waveform(wf::RDWaveform, a::RealQuantity)

Multiplies each sample of a waveform by a.

rc_filter(RC::Real)

Return a DSP.jl-compatible RC-filter.

rdfilt(fi::AbstractRadSigFilterInstance, input)

Apply filter instance fi to signal input, return the filtered signal.

Returns output.

reverse_waveform(signal::AbstractSamples)
reverse_waveform(wf::RDWaveform)

Reverses the order of samples in a waveform.

shift_waveform(signal::AbstractSamples, a::RealQuantity)
shift_waveform(wf::RDWaveform, a::RealQuantity)

Shifts each sample of a waveform up by a.

simplecsaresponsefilter(τrise::Real, τdecay::Real, gain::Real = one(τrise))

Return a DSP.jl-compatible filter that models the response of a typical charge-sensitive amplifier (CSA).

smplinfo(smpls::AbstractSamples)::SamplingInfo
smplinfo(wf::RDWaveform{T,U})::RDWaveform

Get sampling information from a vector of samples, resp. a waveform.

zac_charge_filter_coeffs(
    N::Int, sigma::V, FT::Int, tau::T, beta::U
    ) where {V, T, U <: AbstractFloat}

return a vector representing the zac filter applicaible on a charge signal, where N is the total length of the filter, FT the length of the flat top, sigma the filter shaping time, tau the decay constant and beta an additional scaling factor. (see Eur. Phys. J. C (2015) 75:255).