Skip to content

room.spatial_decay

Spatial sound distribution curves in workrooms (ISO 14257:2001).

A workroom is not a reverberation room and it is not a free field. Put a known source in it, walk away from it with a meter, and the level falls off somewhere between the 6 dB per distance doubling of a free field and the nothing at all of a perfectly diffuse room. That curve is what this standard measures, and the two numbers it derives from it are what a room is judged by:

  • , the rate of spatial decay per distance doubling, which says how much quieter it gets by walking away, and
  • , the excess of sound pressure level, which says how much louder the room is than a free field would have been.

The quantity everything is built on is the sound distribution value, the level at a point less the sound power level of the source that produced it, so that the curve belongs to the room and not to the source:

The reference curve is the same quantity in a free field, which is the inverse square law written as a level:

with = 1 m. The two derived quantities are a least-squares slope over a range of positions,

with , and the difference from the reference curve,

averaged over a distance range by Equation (7) or read off the regression line at one conventional distance by Equation (8).

The 0.3 of Equation (5). The slope of a least-squares fit of against is a rate per decade; a doubling is of a decade, which is 0.301 03. The clause prints 0.3, and that is what DECADE_TO_DOUBLING carries, because the printed constant is what reproduces the printed results. Equation (8) prints in full a page later, so the two are not the same number in the same document; the difference is 0.3 % of a slope and the errata registry records it.

Two spectra. A curve measured in octave bands can be collapsed onto the spectrum of a real machine by Equation (3), or onto the A-weighted pink noise of Table 1 by Equation (4), which is what a room gets judged by when nobody knows yet what will be installed in it.

The 6.2 of Equation (4). The constant is the energy sum of the A-weighting curve over the six octaves, 6.23 dB, printed to one decimal, and it is there so that a flat curve comes back unchanged. Table 1 prints the same curve to one decimal weight by weight, and the six printed weights sum to 6.251 5 dB, so the printed equation returns a flat curve 0.05 dB high. NORMALIZED_OFFSET_DB carries the printed 6.2 on the same rule as the 0.3 above: four printings print it and a reader checking against the page will use it. Annex C was normalised exactly: its normalized column and its Table C.10 land inside the printed rounding under Equation (3) with the Table 1 weights and one unit high in the last place under the printed constant, so every value this module normalizes stands 0.05 dB above the annex. The errata registry records it. Equation (3) with the Table 1 weights as the machine spectrum is Equation (4) normalised exactly, for whoever needs the annex’s reading.

Annex B. In a room whose own excess is small, what the measurement sees is partly the source’s own directivity and the reflection off the floor rather than the room. The annex corrects for that with a reference curve measured for that source in a free field over a reflecting plane, Equation (B.1), against the theoretical floor-reflected curve of Equations (B.2) to (B.4).

Read from BS EN ISO 14257:2001, which endorses ISO 14257:2001 without modification.

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

Constant (float).

ADJACENT_BAND_LIMIT_DB = 8.0
BackgroundMarginCheck(margins_db: NDArray[np.float64])

Whether the levels clear the background by what 5.1.4 asks.

The verdicts are read from the margins and the 10 dB and 6 dB of 5.1.4, so they are not fields.

Attributes

Name Description
margins_db The level of the source less the background at each position and band given, in decibels, in the shape they came in.

property

True where the margin is under the preferred 10 dB and over the 6 dB.

ISO14257_PREFERRED_BACKGROUND_MARGIN_DB and ISO14257_MIN_BACKGROUND_MARGIN_DB bound the window where the clause asks for the ISO 3744 background correction.

property

The verdict: every margin clears ISO14257_PREFERRED_BACKGROUND_MARGIN_DB.

That is the only case that needs nothing done to it.

property

True where the margin is at or under ISO14257_MIN_BACKGROUND_MARGIN_DB.

The clause offers no correction for those. Judged settled.

check_background_margin(
levels: NumericArrayLike,
background_levels: NumericArrayLike,
) -> BackgroundMarginCheck

Does the source stand clear of the background? 5.1.4.

The clause asks for 10 dB at every position and in every octave band the curve is measured over. Between 10 dB and 6 dB it asks for the background correction of ISO 3744 (phonometry.emission.background_correction) before the levels are used; at 6 dB or less it asks for neither, because there is no longer a source level to correct towards.

The verdict is returned rather than applied: correcting the levels here would change a measured number behind the caller’s back, and the correction the clause names belongs to the standard that prints it. A margin under 10 dB anywhere also emits SpatialDecayWarning, so a curve computed from levels nobody checked says so on the way past.

One octave band at a time, as every other function of clause 6 takes its positions: the clause asks the same 10 dB of every band, and a curve is read band by band.

Parameters

Name Description
levels with the test source running, in decibels, one value per measured position of one octave band.
background_levels The background at the same positions, in decibels, as a scalar or one value per position.

Returns: The verdict, as a BackgroundMarginCheck.

Raises

Exception When
ValueError For inputs that are not finite or do not match position for position.
TypeError if background_levels or levels holds a text or a value that is not a real number.
corrected_distribution_value(
distribution_levels: float | np.floating[Any] | np.integer[Any],
measured_reference_levels: float | np.floating[Any] | np.integer[Any],
distances: float | np.floating[Any] | np.integer[Any],
*,
source_height_m: float = ...,
path_height_m: float | None = ...,
) -> float
corrected_distribution_value(
distribution_levels: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
measured_reference_levels: NumericArrayLike,
distances: NumericArrayLike,
*,
source_height_m: float = ...,
path_height_m: float | None = ...,
) -> NDArray[np.float64]
corrected_distribution_value(
distribution_levels: float | np.floating[Any] | np.integer[Any],
measured_reference_levels: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
distances: NumericArrayLike,
*,
source_height_m: float = ...,
path_height_m: float | None = ...,
) -> NDArray[np.float64]
corrected_distribution_value(
distribution_levels: float | np.floating[Any] | np.integer[Any],
measured_reference_levels: float | np.floating[Any] | np.integer[Any],
distances: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
source_height_m: float = ...,
path_height_m: float | None = ...,
) -> NDArray[np.float64]
corrected_distribution_value(
distribution_levels: NumericArrayLike,
measured_reference_levels: NumericArrayLike,
distances: NumericArrayLike,
*,
source_height_m: float = ...,
path_height_m: float | None = ...,
) -> float | NDArray[np.float64]

The Annex B correction for the source’s own curve, Equation (B.1).

What the annex does is swap one reference curve for another: it takes the source’s measured free-field-over-a-reflecting-plane curve out of the measurement and puts the theoretical one back, so that what is left is the room. It matters where the room’s own excess is small, which is where the source’s directivity and the floor reflection are a large part of what the meter saw.

Parameters

Name Description
distribution_levels in the room, in decibels.
measured_reference_levels measured for this source over a reflecting plane, in decibels.
distances at each position, in metres.
source_height_m , in metres.
path_height_m , in metres.

Returns: , in decibels. A float when distribution_levels, measured_reference_levels and distances are all numbers, an array when one of them is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError For inputs that do not match position for position, or a correction that leaves no energy at all.
TypeError if distances, distribution_levels or measured_reference_levels holds a text or a value that is not a real number.

Constant (float).

DECADE_TO_DOUBLING = 0.3
distance_region(
distance: float,
*,
near_limit_m: float = 5.0,
far_limit_m: float = 16.0,
) -> str

Which of the three regions of 6.2 a distance falls in.

The near region runs from 1 m to , the middle from to and the far one from out. The typical boundaries are 5 m and 16 m; other values may be used and are then recorded and reported, which is why they are arguments here.

Parameters

Name Description
distance The distance from the acoustical centre, in metres.
near_limit_m , in metres.
far_limit_m , in metres.

Returns: "near", "middle" or "far".

Raises

Exception When
ValueError For a non-positive distance, boundaries that do not increase, a near boundary inside the first metre, which would leave the near region empty, or a distance inside that first metre, which the clause does not evaluate.
TypeError if distance, far_limit_m or near_limit_m is not a single number.

Constant (mapping).

EVALUATION_DISTANCES_M = {'near': 4.0, 'middle': 10.0, 'far': 30.0}
floor_reference_value(
distances: float | np.floating[Any] | np.integer[Any],
*,
source_height_m: float = ...,
path_height_m: float | None = ...,
) -> float
floor_reference_value(
distances: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
source_height_m: float = ...,
path_height_m: float | None = ...,
) -> NDArray[np.float64]
floor_reference_value(
distances: NumericArrayLike,
*,
source_height_m: float = ...,
path_height_m: float | None = ...,
) -> float | NDArray[np.float64]

The reference curve over a reflecting plane, Equations (B.2) to (B.4).

With the microphone path at the source height the product becomes , which is Equation (B.3); with the source on the floor the whole bracket becomes 2 and the correction is the 3 dB of Equation (B.4), the free field folded into a half space.

Parameters

Name Description
distances at each position, in metres.
source_height_m , in metres; zero for a source on the floor.
path_height_m , in metres; omit it for a path at the source height.

Returns: , in decibels. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError For a distance that is not strictly positive or a negative height.
TypeError if path_height_m or source_height_m is not a single number, or distances holds a text or a value that is not a real number.

Constant (float).

FREE_FIELD_OFFSET_DB = 11.0

Constant (float).

ISO14257_MIN_BACKGROUND_MARGIN_DB = 6.0

Constant (float).

ISO14257_PREFERRED_BACKGROUND_MARGIN_DB = 10.0

Constant (float).

ISO14257_REFERENCE_DISTANCE_M = 1.0
level_excess(
distribution_levels: float | np.floating[Any] | np.integer[Any],
distances: float | np.floating[Any] | np.integer[Any],
) -> float
level_excess(
distribution_levels: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
distances: NumericArrayLike,
) -> NDArray[np.float64]
level_excess(
distribution_levels: float | np.floating[Any] | np.integer[Any],
distances: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
level_excess(
distribution_levels: NumericArrayLike,
distances: NumericArrayLike,
) -> float | NDArray[np.float64]

The excess over a free field at each position, Equation (6).

Parameters

Name Description
distribution_levels at each position, in decibels.
distances at each position, in metres.

Returns: at each position, in decibels. A float when distribution_levels and distances are both numbers, an array when either is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError For inputs that do not match position for position.
TypeError if distances or distribution_levels holds a text or a value that is not a real number.
level_excess_at(
distribution_levels: NumericArrayLike,
distances: NumericArrayLike,
distance: float,
) -> float

The excess read off the regression line at one distance, Equation (8).

This is the height of the fitted line over the free-field line at a conventional distance: 4 m for the near region, 10 m for the middle one and 30 m for the far one (EVALUATION_DISTANCES_M). Unlike Equation (7) it does not average the measured points, it reads the line, so a single outlying position moves it much less.

Note that the clause divides by in full here while Equation (5) multiplies by the rounded 0.3; the two constants differ by 0.3 % and the errata registry records it.

Parameters

Name Description
distribution_levels at the positions of the range, in decibels.
distances at the same positions, in metres.
distance , the distance to read at, in metres.

Returns: , in decibels.

Raises

Exception When
ValueError For inputs that do not match, fewer than two positions, or a non-positive distance.
TypeError if distance is not a single number, or distances or distribution_levels holds a text or a value that is not a real number.

Constant (float).

MAX_DIRECTIVITY_INDEX = 8.0
mean_level_excess(
distribution_levels: NumericArrayLike,
distances: NumericArrayLike,
) -> float

The excess averaged over a distance range, Equation (7).

It is the trapezoidal mean of the excess against the logarithm of the distance, which is the axis the curve is drawn on, so a position twice as far weighs the same as one twice as near rather than twice as much.

Parameters

Name Description
distribution_levels at the positions of the range, in decibels.
distances at the same positions, in metres, in increasing order.

Returns: , in decibels.

Raises

Exception When
ValueError For inputs that do not match, fewer than two positions, or distances that do not increase.
TypeError if distances or distribution_levels holds a text or a value that is not a real number.

Constant (float).

MIN_SOURCE_TO_WALL_M = 3.0

Constant (float).

NEAR_REGION_START_M = 1.0
normalized_distribution_value(
distribution_levels: NumericArrayLike,
*,
frequencies: NumericArrayLike | None = None,
) -> float

The curve collapsed onto A-weighted pink noise, Equation (4).

with from Table 1. It is Equation (3) with one spectrum fixed, and 4.2.3 says why that spectrum is a normalisation and not an average industrial machine: the spectra met in practice are too varied for any average to mean anything.

The 6.2 dB is the energy sum of the A-weighting curve printed to one decimal, and the six printed weights of Table 1 sum to 6.251 5 dB, so the printed equation returns a flat curve 0.05 dB high. It is used as printed: the result is what a hand evaluation of the printed equation gives, which is 0.05 dB above Annex C, normalised exactly (see the errata registry). For the exact normalisation, which returns a flat curve unchanged, call spectrum_distribution_value with the values of PINK_NOISE_WEIGHTS_DB as the machine spectrum.

Parameters

Name Description
distribution_levels in each band, in decibels, in the order of SPATIAL_DECAY_BANDS_HZ unless frequencies says otherwise.
frequencies The nominal octave centres the values belong to, in hertz.

Returns: , in decibels.

Raises

Exception When
ValueError For a count that is not the six bands of Table 1, or a frequency the table does not name.
TypeError if distribution_levels or frequencies holds a text or a value that is not a real number.

Constant (float).

NORMALIZED_OFFSET_DB = 6.2

Constant (tuple).

OMNIDIRECTIONAL_RAMP_HZ = (630.0, 1000.0)

Constant (tuple).

OMNIDIRECTIONAL_TOLERANCE_DB = (2.0, 8.0)
omnidirectionality_tolerance(frequency_hz: float) -> float

The directivity band a qualifying source stays inside, A.1.

The clause states the tolerance in three pieces: +/- 2 dB in the one-third-octave bands from 100 Hz to 630 Hz, a linear increase to +/- 8 dB between 630 Hz and 1 kHz, and +/- 8 dB from 1 kHz to 5 kHz. The increase is taken here across the three one-third-octave bands that span it, so 800 Hz is the midpoint at 5 dB; the clause says “linearly” without saying linear in what, and the band index is the only reading on which the two endpoints land on printed bands.

Parameters

Name Description
frequency_hz The one-third-octave centre, in hertz.

Returns: The largest absolute directivity index allowed, in decibels.

Raises

Exception When
ValueError For a non-positive frequency.
TypeError if frequency_hz is not a single number.

Constant (mapping).

PINK_NOISE_WEIGHTS_DB = {125.0: -16.1, 250.0: -8.6, 500.0: -3.2, 1000.0: 0.0, 2000.0: 1.2, 4000.0: 1.0}

Constant (float).

PREFERRED_MIDDLE_LIMIT_M = 24.0
reference_distribution_value(
distances: float | np.floating[Any] | np.integer[Any],
) -> float
reference_distribution_value(
distances: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
reference_distribution_value(
distances: NumericArrayLike,
) -> float | NDArray[np.float64]

The free-field reference curve, Equation (2).

The clause prints both forms and they are the same number to within the rounding of the 11: is 10.99. The printed 11 is what is used here, because it is the curve the standard draws in its own figures.

Parameters

Name Description
distances at each position, in metres.

Returns: , in decibels. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError For a distance that is not strictly positive.
TypeError if distances holds a text or a value that is not a real number.
sound_distribution_value(
levels: float | np.floating[Any] | np.integer[Any],
sound_power_levels: NumericArrayLike,
) -> float
sound_distribution_value(
levels: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
sound_power_levels: NumericArrayLike,
) -> NDArray[np.float64]
sound_distribution_value(
levels: NumericArrayLike,
sound_power_levels: NumericArrayLike,
) -> float | NDArray[np.float64]

The sound distribution value of a measured point, Equation (1).

Subtracting the source’s own sound power is what makes the curve a property of the room: run the test again with a louder source and every value comes back the same.

Parameters

Name Description
levels at each position, in decibels.
sound_power_levels of the source, in decibels, as a scalar or one value per position.

Returns: , in decibels. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError For inputs that are not finite or do not broadcast.
TypeError if levels or sound_power_levels holds a text or a value that is not a real number.

Constant (float).

SOURCE_ON_FLOOR_HEIGHT_M = 0.5

Constant (tuple).

SPATIAL_DECAY_BANDS_HZ = (125.0, 250.0, 500.0, 1000.0, 2000.0, 4000.0)
spatial_decay_curve(
distribution_levels: NumericArrayLike,
distances: NumericArrayLike,
*,
near_limit_m: float = 5.0,
far_limit_m: float = 16.0,
region: Literal['near', 'middle', 'far', 'whole'] = 'middle',
band: float | None = None,
) -> SpatialDecayResult

The curve of one region with its two descriptors, clause 6.

Parameters

Name Description
distribution_levels at every measured position, in decibels, over the whole path.
distances at the same positions, in metres, in increasing order.
near_limit_m of 6.2, in metres.
far_limit_m of 6.2, in metres.
region "near", "middle", "far" or "whole".
band The octave centre the curve belongs to, in hertz.

Returns: The curve and its descriptors, as a SpatialDecayResult.

Raises

Exception When
ValueError For an unknown region, inputs that do not match, or a region holding fewer than two measured positions.
TypeError if band is not a single number, or distances or distribution_levels holds a text or a value that is not a real number, or region is not a text.
spatial_decay_rate(
distribution_levels: NumericArrayLike,
distances: NumericArrayLike,
) -> float

The rate of spatial decay per distance doubling, Equation (5).

A free field gives 6 dB, a perfectly diffuse room gives 0, and a real workroom sits between them: 4.6 dB in the middle range of the Annex C example, which is a large and moderately fitted shipyard hall.

The sign is the way round a reader expects: the regression slope is negative, so a room that gets quieter with distance returns a positive number of decibels per doubling.

Parameters

Name Description
distribution_levels at the positions of the range, in decibels.
distances at the same positions, in metres.

Returns: , in decibels per distance doubling.

Raises

Exception When
ValueError For inputs that do not match position for position, fewer than two positions, or positions that are all at one distance.
TypeError if distances or distribution_levels holds a text or a value that is not a real number.
SpatialDecayResult(
distances: NDArray[np.float64],
distribution_levels: NDArray[np.float64],
reference_distribution_levels: NDArray[np.float64],
level_excess: NDArray[np.float64],
decay_rate_db: float,
mean_level_excess: float,
region: Literal['near', 'middle', 'far', 'whole'],
band: float | None = None,
)

A spatial sound distribution curve and what clause 6 reads off it.

Parameters

Name Description
distances The distance of each microphone position from the acoustical centre of the source, in metres.
distribution_levels at each position, in decibels.
reference_distribution_levels at each position, in decibels.
level_excess at each position, in decibels.
decay_rate_db over the range, in decibels per distance doubling.
mean_level_excess over the range, in decibels.
region "near", "middle", "far" or "whole".
band The nominal octave centre the curve belongs to, in hertz, or None for a curve that stands for a spectrum.
SpatialDecayResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Draw the curve, the free-field reference and the fitted slope.

Parameters

Name Description
ax Axes to draw on; a new figure is made when omitted.
language "en" (default) or "es" for the labels.
kwargs Passed to the renderer.

Returns: The axes drawn on.

The measurement is outside a condition ISO 14257 states.

spectrum_distribution_value(
distribution_levels: NumericArrayLike,
machine_power_levels: NumericArrayLike,
) -> float

The curve collapsed onto one machine’s spectrum, Equation (3).

The octave-band curve says what the room does to each band; this says what the room does to one particular machine, which is the number a layout decision is made on.

Parameters

Name Description
distribution_levels in each band, in decibels.
machine_power_levels of the machine in the same bands, in decibels.

Returns: , in decibels.

Raises

Exception When
ValueError For inputs that do not match band for band.
TypeError if distribution_levels or machine_power_levels holds a text or a value that is not a real number.

Constant (mapping).

STABILITY_TOLERANCE_DB = {(100.0, 160.0): 1.0, (200.0, 5000.0): 0.5}

Constant (float).

TYPICAL_FAR_LIMIT_M = 16.0

Constant (float).

TYPICAL_NEAR_LIMIT_M = 5.0