filters.compliance

IEC 61260-1:2014 band-filter class verification.

Acceptance limits on relative attenuation transcribed from the official text (BS EN 61260-1:2014, Table 1, standard pages 15-16): octave-band breakpoint frequencies with class 1 and class 2 minimum/maximum limits. Fractional-octave-band breakpoints are derived with Formulas (9) and (10) (subclauses 5.10.3-5.10.4) and limits between breakpoints are interpolated linearly in ${\log }_{10}\Omega$ per Formula (11) (subclause 5.10.6). Relative attenuation is $\Delta A(\Omega )=A(\Omega )-A_{\mathrm{ref}}$ (Formula 8) with $A=L_{\mathrm{in}}-L_{\mathrm{out}}$ (Formula 7); here $A_{\mathrm{ref}}$ is the attenuation at the exact mid-band frequency (subclause 5.9: the pass-band reference attenuation).

IEC 61260-1:2014 defines only classes 1 and 2. Class 0 (the tightest, laboratory-grade class) lives only in the withdrawn IEC 61260:1995 / EN 61260:1995 Table 1 and its US twin ANSI S1.11-2004 Table 1, whose class 1/2 masks differ numerically from the 2014 edition (e.g. the 2014 pass-band reference tolerance is ±0.4 dB for class 1 vs ±0.3 dB in 1995, and the 2014 stop-band edge minimum is +1.2 dB vs +2.0 dB in 1995). The two editions are therefore kept as separate mask tables selected by the edition argument ("2014" default -> classes 1/2; "1995" -> classes 0/1/2). The 1995 / ANSI-2004 octave-band table was transcribed digit-for-digit and cross-checked between the two standards (they agree exactly).

One subject: the class of a band-filter design, graded against what IEC 61260-1:2014 requires of the transfer function of a set of filters and run the way IEC 61260-2:2016 (pattern evaluation) says the requirement is tested. Besides the Table 1 mask there are two more requirements, both computed from the same designed sections:

• Effective bandwidth deviation (61260-1 5.11 and 5.12). The normalized effective bandwidth $B_{\mathrm{e}}$ is the integral of Formula (13), $\int (1/\Omega )10^{-0.1\Delta A(\Omega )}\mathrm{d}\Omega$, evaluated as IEC 61260-2 7.2.3.2 recommends: by the trapezoidal rule of its Formula (2) over the test frequencies of its Formula (1), ${\Omega }_i=G^{i/(bS)}$, with $S\ge 24$ frequencies per bandwidth (7.2.1.4). Its deviation from the reference $B_{\mathrm{r}}=(1/b)\ln G$ (Formula (15)) is $\Delta B=10\lg (B_{\mathrm{e}}/B_{\mathrm{r}})$ (Formula (16)), within $\pm 0.4$ dB for class 1 and $\pm 0.6$ dB for class 2 (5.12.2).
• Summation of output signals (61260-1 5.16). At the test frequencies ${\Omega }_i$, $|i|\le \lfloor S/2\rfloor$, inside a band, the outputs of that band and of its two neighbours are summed on an energy basis, IEC 61260-2 Formula (3): $\Delta P_j=10\lg \left[10^{-0.1\Delta A_{j-1}}+10^{-0.1\Delta A_j}+10^{-0.1\Delta A_{j+1}}\right]$, for every band that has a neighbour on both sides (7.2.4.4). The limits are $+0.8$ dB and $-1.8$ dB for class 1 and $+1.8$ dB and $-3.8$ dB for class 2. They are applied to Formula (3) as printed, as 7.2.4.5 instructs; the words of 7.2.4.3 and of 5.16 name the difference the other way round, “input minus reference attenuation, and the summed output”, which with limits this asymmetric is not the same test (see the errata registry).

Both are graded for edition="2014" only, whose Part 2 prescribes them; a 1995-edition verdict remains the Table 1 mask.

The time-invariant operation of 5.14, tested with an exponential sweep (IEC 61260-2 7.4), is phonometry.filters.verify_time_invariance: it runs the bank itself, decimation included, rather than reading its transfer functions.

The acceptance limits of the A/B/C/AU/Z frequency weightings, which qualify a network applied to the whole signal against a design-goal response, live in phonometry.filters.weighting_compliance.

Auto-generated from the source docstrings by scripts/generate_api_docs.py (make api-docs). Do not edit by hand.

class_limits(
    fraction: float,
    filter_class: int,
    omega: np.ndarray,
    *,
    edition: str = '2014',
) -> tuple[np.ndarray, np.ndarray]

Acceptance limits on relative attenuation at normalized frequencies.

Parameters

Returns: Tuple (minimum, maximum) relative attenuation in dB per point; the maximum is +inf outside the pass-band.

FilterComplianceResult(
    overall_class: int | None,
    bands: tuple[dict[str, Any], ...],
    fraction: int,
    edition: str,
    sos: tuple[np.ndarray, ...],
    band_frequencies: np.ndarray,
    factors: tuple[int, ...],
    fs: float,
    num_points: int,
    *,
    range_limited: bool = False,
    points_per_bandwidth: int = 24,
)

IEC 61260-1 class-compliance verdict of an OctaveFilterBank.

What verify_filter_class returns: the verdict together with the minimal filter-bank data needed to redraw the measured relative-attenuation curve, so the result exposes the standard plot / report pair without holding a reference to the (possibly stateful) bank.

Attributes

For edition="2014" every band entry carries, besides its Table 1 margins margin_class<c>_db, the two requirements IEC 61260-2 tests on the same measurements:

• bandwidth_deviation_db, the effective bandwidth deviation $\Delta B$ of 5.12, and bandwidth_margin_class<c>_db, its distance to each class’s limit;
• summation_min_db and summation_max_db, the range of the summation $\Delta P_j$ of 5.16 across the band, and summation_margin_class<c>_db, the nearer of its distances to each class’s two limits; all three are None on the first and the last band, which have a neighbour on one side only (IEC 61260-2 7.2.4.4).

A band’s class is then the strictest class it meets on all of them.

FilterComplianceResult.available_classes() -> list[int]

The performance classes carried by the per-band verdict dictionaries.

Reads the margin_class<n>_db keys of a band verdict, so it reflects the edition (the 1995 edition adds class 0; the 2014 edition keeps only classes 1 and 2). An empty result (a bank with no bands in range) carries no verdicts, so this returns an empty list.

The first band answers for all of them: construction pins every band to the same margin classes.

FilterComplianceResult.binding_margin_db(
    requirement: str,
    filter_class: int,
) -> float

The smallest margin, in dB, of any band to one class on one requirement.

Parameters

Returns: The binding margin; negative when a band misses the class.

Raises

FilterComplianceResult.plot(
    ax: Axes | None = None,
    *,
    requirement: str = 'relative_attenuation',
    language: str = 'en',
    **kwargs: Any,
) -> Axes

Plot one graded requirement.

"relative_attenuation" (the default) draws the measured relative attenuation of the binding band over the acceptance corridor of the achieved (or, when non-compliant, the loosest) class; see phonometry._plot.filters.plot_filter_class. "effective_bandwidth" draws $\Delta B$ of every band between the limits of 5.12.2, and "summation" the Formula (3) curve of every inner band between the limits of 5.16. Requires matplotlib (pip install phonometry[plot]) and returns the Axes.

Parameters

Raises

FilterComplianceResult.reference_class() -> int

The class whose corridor the fiche/plot overlays.

The achieved overall class when the bank complies, else the loosest class of the edition (the one it comes closest to meeting).

Raises

FilterComplianceResult.report(
    path: str,
    *,
    metadata: ReportMetadata | None = None,
    engine: str = 'reportlab',
    verbose: bool = False,
    language: str = 'en',
) -> str

Render an IEC 61260-1 filter-class-compliance fiche to a PDF.

Writes a one-page accredited report: the standard-basis line, an optional metadata header block, a per-band classification table beside the mask-overlay plot (the result’s own plot), the boxed class-compliance result, an optional verdict row against a supplied required_class and a footer with the fixed disclaimer.

Parameters

Returns: The written path as a str.

Raises

FilterComplianceResult.requirement_class(requirement: str) -> int | None

The strictest class every band meets on one requirement alone.

Parameters

Returns: The class, or None when a band meets none. The bands a requirement does not apply to (the end bands of the summation) do not constrain it.

Raises

property

The requirements of IEC 61260-1:2014 this verdict graded.

"relative_attenuation" (5.10, Table 1) always; for the 2014 edition also "effective_bandwidth" (5.12) and, when the bank has a band with a neighbour on each side, "summation" (5.16), which IEC 61260-2:2016 7.2.4.4 grades on those bands only. Empty for a bank with no bands.

verify_filter_class(
    bank: OctaveFilterBank,
    *,
    num_points: int = 32768,
    edition: str = '2014',
    points_per_bandwidth: int = 24,
) -> FilterComplianceResult

Verify a filter bank against the IEC 61260 class limits.

Each band’s relative attenuation (referenced to the attenuation at its exact mid-band frequency) is checked against every acceptance-limit class of the selected edition’s Table 1, evaluated on a dense frequency grid up to the band’s processing Nyquist. The Table 1 breakpoint frequencies inside that range are always included in the evaluation, so the pass-band constraints are checked even if the grid were coarse. Frequencies beyond the processing Nyquist cannot carry signal energy at the band’s decimated rate (the multirate anti-aliasing filter removes them), so they are treated as compliant; because the Table 1 limits there are nevertheless not demonstrated, the returned range_limited flag is set whenever a band’s stop-band mask extends beyond its processing Nyquist, and the per-band checked_to_omega records how far the check reached.

For edition="2014" two more requirements of IEC 61260-1:2014 are graded on the same sections, the way IEC 61260-2:2016 tests them (see the module docstring): the effective bandwidth deviation of every band (5.12, Formulas (1) and (2) of Part 2) and the summation of the output signals of every band that has a neighbour on each side (5.16, Formula (3) of Part 2). A band’s class, and so the bank’s, is the strictest class met on every requirement graded; FilterComplianceResult.requirement_class gives the class of each requirement on its own.

Parameters

Returns: A FilterComplianceResult, which carries the verdict together with the sections, mid-band frequencies, decimation factors and sampling rate it was measured through, so it can redraw the relative attenuation and render an accredited .report() fiche without keeping a reference to the (possibly stateful) bank.