prepare_digital_filter#

gwpy.signal.filter_design.prepare_digital_filter(
filt: FilterCompatible,
*,
analog: bool = False,
sample_rate: QuantityLike = 1.0,
unit: str | UnitBase = 'Hz',
normalize_gain: bool = False,
output: Literal['ba'] = 'zpk',
) → BAType[source]#
gwpy.signal.filter_design.prepare_digital_filter(
filt: FilterCompatible,
*,
analog: bool = False,
sample_rate: QuantityLike = 1.0,
unit: str | UnitBase = 'Hz',
normalize_gain: bool = False,
output: Literal['zpk'] = 'zpk',
) → ZpkType
gwpy.signal.filter_design.prepare_digital_filter(
filt: FilterCompatible,
*,
analog: bool = False,
sample_rate: QuantityLike = 1.0,
unit: str | UnitBase = 'Hz',
normalize_gain: bool = False,
output: Literal['sos'] = 'zpk',
) → SosType

Prepare a filter for digital filtering.

This function parses the input filter specification, optionally converts an analog filter to digital using prewarping + bilinear transform, and returns the filter in the requested format.

For incoming digital filters, this function basically does nothing.

Parameters:
filtfilter specification

Filter as (b, a), (z, p, k), sos array, or lti object.

For digital filters (analog=False), the input filter coefficients are assumed to already be in digital form (z-domain).

For analog filters (analog=True), the input filter coefficients should be in the units specified by unit (default: Hz).

analogbool, optional

When True, the input filter is analog and will be converted to digital using prewarping + bilinear transform (GDS method). When False (default), the input filter is already digital.

sample_ratefloat, Quantity, optional

Sampling frequency (Hz) of the digital system. Required when analog=True.

unitstr, optional

For analogue ZPK filters, the units in which the zeros and poles are specified. Either 'Hz' or 'rad/s' (default).

normalize_gainbool, optional

Whether to normalize the gain when converting from Hz to rad/s.

  • False (default): Multiply zeros/poles by -2π but leave gain unchanged. This matches the LIGO GDS ‘f’ plane convention (plane='f' in s2z()).

  • True: Normalize gain to preserve frequency response magnitude. Gain is scaled by \(|∏p_i/∏z_i| · (2π)^{(n_p - n_z)}\). Use this when your filter was designed with the transfer function \(H(f) = k·∏(f-z_i)/∏(f-p_i)\) in Hz. This matches the LIGO GDS ‘n’ plane convention (plane='n' in s2z()).

Only used for analogue filters in Hz (analog=True, unit="Hz").

prewarpbool, optional

If True, apply prewarping before bilinear transform (default). If False, skip prewarping (not recommended). Ignored when analog=False.

outputstr, optional

Desired output filter form:

  • 'zpk': zero-pole-gain tuple (default)

  • 'ba': numerator-denominator tuple

  • 'sos': second-order sections array with separated gain

Returns:
filt_outtuple

Filter coefficients in the requested form:

  • output='ba': 2-tuple of (b, a) arrays

  • output='zpk': 3-tuple of (zeros, poles, gain)

  • output='sos': 2-tuple of (sos_array, gain)

For output='sos', the returned SOS array has unit gain in all sections, and the overall gain is returned separately. This must be applied to the filter output: filtered_data * gain.

Raises:
ValueError

If analog=True but sample_rate is not provided.

See also

prepare_analog_filter

Prepare analog filter without digital conversion.

scipy.signal.sosfilt

Apply SOS filter to data.

Notes

Prewarping

Unlike scipy.signal.bilinear and scipy.signal.bilinear_zpk which do NOT perform prewarping, this function applies prewarping by default. Prewarping ensures the digital filter’s frequency response matches the analogue design at the pole/zero frequencies.

Examples

Prepare a digital filter from analog specification:

>>> from gwpy.signal.filter_design import prepare_digital_filter
>>> zpk = ([100], [10], 1.0)  # 100 Hz zero, 10 Hz pole, gain 1.0
>>> sos = prepare_digital_filter(
...     zpk,
...     analog=True,
...     sample_rate=4096,
...     unit='Hz',
...     output='sos',
... )

Apply to data:

>>> from scipy import signal
>>> filtered = signal.sosfilt(sos, data)