environment.assessment.soundscape

How people hear a place: the soundscape questionnaire and its analysis (ISO/TS 12913-2:2018 Annexes A and C, ISO/TS 12913-3:2019 Annexes A and B).

A soundscape is the acoustic environment as a person perceives it in context (ISO 12913-1). Its study “relies primarily upon human perception and only then turns to physical measurement” (ISO/TS 12913-2, Introduction), which makes this the first module of the library whose input is not a signal but a questionnaire: the boxes people ticked on a soundwalk, turned into numbers and statistics the way ISO/TS 12913-3 prescribes.

What is implemented, in the order a study runs:

• the questionnaires of ISO/TS 12913-2 Annex C as read-only tables: Method A (clause C.3.1, Figures C.2 to C.6), four parts on five-category scales, and the continuous-category scales of Method B (clause C.3.2, Figure C.7), with every question, item and response category as printed, in METHOD_A_SCALES, METHOD_A_ALTERNATIVE_PART_1 and METHOD_B_SCALES; the eight attributes of the perceived affective quality in PERCEIVED_AFFECTIVE_QUALITY_ATTRIBUTES;
• the scale values of Method A (ISO/TS 12913-3 A.2, Table A.1): parts 1 and 4 run 1 to 5 from the left-hand box to the right-hand one, parts 2 and 3 run 5 to 1, method_a_scale_values; and their median and range per site and item, method_a_summary;
• the pleasantness and eventfulness coordinates of Formulas (A.1) and (A.2), per respondent and per site, raw and normalised to $\pm 1$, with the two-dimensional model of Figure A.1 as the plot, pleasantness_eventfulness;
• the correlations that link ratings to acoustic data: Spearman’s rank correlation with the untied Formula (A.3) and the tied Formula (A.4), spearman_rank_correlation, and Pearson’s of Formulas (B.1) and (B.2), pearson_correlation, each with its probability value;
• Method B (Annex B): the scale value of a mark on a continuous-category scale with one decimal, method_b_scale_values; the arithmetic mean, standard deviation and 95 % confidence interval per site, method_b_summary; and the median and range of the rank each recognised sound source was given, method_b_source_ranking;
• the minimum reporting requirements of ISO/TS 12913-2 Annex A (normative), as a record that checks itself when it is built, SoundscapeReport.

The binaural analysis of ISO/TS 12913-3 Annex D is phonometry.environment.assessment.soundscape_binaural.

This module implements the first edition of ISO/TS 12913-3, published in 2019. ISO has since published ISO/TS 12913-3:2025, which revises Annex A; that edition has not been read for this implementation, so nothing here claims to follow it, and a study that cites the 2025 edition should check Formulas (A.1) and (A.2) against it.

Which part feeds Formulas (A.1) and (A.2). Clause A.3 says “the results from part 3 (see A.1) are further processed”, but the eight attributes the formulas use are the perceived affective quality, which is part 2 of the questionnaire everywhere else: in Table A.1, in the paragraph of A.2 that assigns its scale values, and in ISO/TS 12913-2 C.3.1.3 and Figure C.4. Part 3 is the single overall rating of Figure C.5, which has no attributes. The formulas are applied to part 2, and the slip is in docs/ERRATA.md.

Per site. A.3 derives “the values on two dimensions (pleasantness and eventfulness) for each site” from the results of the questionnaire, and A.2 makes the median the central tendency of every Method A scale. The site coordinates are therefore Formulas (A.1) and (A.2) applied to the site medians of the eight attributes. When every respondent answered all eight attributes, the formulas being linear, the alternative central_tendency="mean" gives the same point as the mean of the respondents’ own coordinates. A blank answer breaks that equality: each attribute mean is then taken over the respondents who answered that attribute, while a respondent with a blank in a formula has no coordinate of it. The median of the respondents’ coordinates is a third reading, which the per-respondent values let a caller form.

Formula (A.3). The page prints $r=1-1\frac{6\sum d_i^2}{n(n^2-1)}$, with a stray factor 1; read as a product it is the usual coefficient for untied ranks, which is what is implemented.

Formulas (B.1) and (B.2). (B.2) divides the covariance by n, so the standard deviations of (B.1) are taken with n as well; with the n - 1 of a sample standard deviation the coefficient would shrink by $(n-1)/n$.

Probability values. A.4 and B.3 ask for the significance of each coefficient and its probability value without naming a test. Both use the Student $t$ statistic $t=r\sqrt{(n-2)/(1-r^2)}$ with $n-2$ degrees of freedom, which is exact for Pearson’s coefficient of bivariate normal data and the usual large-sample approximation for Spearman’s. The 95 % confidence interval of Method B uses the Student distribution with $n-1$ degrees of freedom about the mean, with the sample standard deviation.

The where-lists of Formulas (A.4) and (B.2). The page defines $t_j$ as “the number of in $t_j$ tied ranks” and $k(x)$ as “the numbers of tied ranks”; the formula needs the size of the $j$-th group of tied values and the number of such groups, which is what is implemented. Under (B.2) the mean is “of the array $x_I$”, for $x_i$. Both slips are in docs/ERRATA.md.

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

Constant (phonometry.environment.assessment.soundscape.QuestionnaireScale).

method_a_scale_values(
    positions: ArrayLike,
    *,
    part: int,
) -> float | NDArray[np.float64]

The scale value of a ticked box of Method A (ISO/TS 12913-3 Table A.1).

A box is counted from the left-hand end of its scale, 1 to 5, as the questionnaire of ISO/TS 12913-2 prints it. Parts 1 and 4 assign the scale values 1 to 5 from left to right, so the value is the position; parts 2 and 3 assign 5 to 1, so “strongly agree” (part 2) and “very good” (part 3) are 5 and the value is 6 - position.

Parameters

Returns: The scale values, a float for a scalar input; an array is always a new one, never a view of positions.

Raises

Constant (mapping).

method_a_summary(
    scale_values: Mapping[str, ArrayLike] | ArrayLike,
    *,
    part: int,
    sites: ArrayLike | Sequence[object] | None = None,
) -> MethodASummary

Median and range of the Method A scale values per site and item (ISO/TS 12913-3 A.2, Table A.1).

Parameters

Returns: A MethodASummary.

Raises

Constant (int).

METHOD_B_MAXIMUM_SOURCES = 8

method_b_scale_values(
    marked_fraction: ArrayLike,
) -> float | NDArray[np.float64]

The scale value of a mark on a Method B scale (ISO/TS 12913-3 B.2).

A continuous-category scale of Figure C.7 runs from its left-hand tick (“not at all”, or “never” on the fourth scale), scale value 1, to its right-hand one (“extremely”, or “very often”), scale value 5, and a mark may fall anywhere along it. Its position is measured with a ruler, or on screen, as a fraction of the distance between the two end ticks, and the value is $1+4f$ rounded to one decimal, the resolution B.2 requires (“determined at least with one decimal place”).

Parameters

Returns: The scale values, a float for a scalar input.

Raises

Constant (tuple).

METHOD_B_SCALES = (QuestionnaireScale(method='B', part=1, figure='C.7', subject='assessment of the sound environment', question='How loud is it here?', instruction='Mark your impression at any location on the scale below.', items=(), categories=('not at all', 'slightly', 'moderately', 'very', 'extremely'), scale_values=(1, 2, 3, 4, 5), continuous=True), QuestionnaireScale(method='B', part=1, figure='C.7', subject='assessment of the sound environment', question='How unpleasant is it here?', instruction='Mark your impression at any location on the scale below.', items=(), categories=('not at all', 'slightly', 'moderately', 'very', 'extremely'), scale_values=(1, 2, 3, 4, 5), continuous=True), QuestionnaireScale(method='B', part=1, figure='C.7', subject='assessment of the sound environment', question='How appropriate is the sound to the surrounding?', instruction='Mark your impression at any location on the scale below.', items=(), categories=('not at all', 'slightly', 'moderately', 'very', 'extremely'), scale_values=(1, 2, 3, 4, 5), continuous=True), QuestionnaireScale(method='B', part=1, figure='C.7', subject='assessment of the sound environment', question='How often would you like to visit this place again?', instruction='Mark your impression at any location on the scale below.', items=(), categories=('never', 'rarely', 'sometimes', 'often', 'very often'), scale_values=(1, 2, 3, 4, 5), continuous=True))

method_b_source_ranking(
    rankings: Sequence[Sequence[str]],
    *,
    sites: ArrayLike | Sequence[object] | None = None,
) -> SourceRanking

Median and range of the rank of each recognised sound source per site (ISO/TS 12913-3 B.2, ISO/TS 12913-2 C.3.2.4 and Figure C.8).

Parameters

Returns: A SourceRanking.

Raises

method_b_summary(
    scale_values: Mapping[str, ArrayLike] | ArrayLike,
    *,
    sites: ArrayLike | Sequence[object] | None = None,
    confidence_level: float = 0.95,
) -> MethodBSummary

Mean, standard deviation and confidence interval of Method B ratings per site (ISO/TS 12913-3 B.2, Table B.1).

The confidence interval of the mean is $\bar{x}\pm t_{(1+\gamma )/2,n-1}s/\sqrt{n}$, with $s$ the sample standard deviation and $\gamma$ the confidence level, 95 % as B.2 asks.

Parameters

Returns: A MethodBSummary.

Raises

MethodASummary(
    part: int,
    items: tuple[str, ...],
    sites: tuple[str, ...],
    medians: NDArray[np.float64],
    minima: NDArray[np.float64],
    maxima: NDArray[np.float64],
    ranges: NDArray[np.float64],
    counts: NDArray[np.int64],
)

Median and range of Method A responses per site and item (ISO/TS 12913-3 A.2 and Table A.1).

The level of measurement of every Method A scale is ordinal, so the median is the measure of central tendency and the range, the largest scale value given less the smallest, the measure of dispersion. A blank answer is left out of both; a site where nobody answered an item has NaN there and a count of zero.

Attributes

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

Plot the median of each item per site, with its range as a bar.

Parameters

Returns: The axes. Requires matplotlib (pip install phonometry[plot]).

MethodBSummary(
    items: tuple[str, ...],
    sites: tuple[str, ...],
    means: NDArray[np.float64],
    standard_deviations: NDArray[np.float64],
    confidence_lower: NDArray[np.float64],
    confidence_upper: NDArray[np.float64],
    medians: NDArray[np.float64],
    counts: NDArray[np.int64],
    confidence_level: float,
)

Arithmetic mean, standard deviation and confidence interval of Method B ratings per site and scale (ISO/TS 12913-3 B.2 and Table B.1).

The level of measurement of the continuous-category scales is interval, so B.2 reports the arithmetic mean with its standard deviation and 95 % confidence interval. “Statistics for an ordinal scale level may be additionally applied”, so the median is here too. A blank answer is left out; a site with fewer than two answers to a scale has no standard deviation or interval there (NaN).

Attributes

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

Plot the mean of each scale per site with its confidence interval.

Parameters

Returns: The axes. Requires matplotlib (pip install phonometry[plot]).

pearson_correlation(
    x: ArrayLike,
    y: ArrayLike,
    *,
    alternative: Literal['two-sided', 'greater', 'less'] = 'two-sided',
) -> SoundscapeCorrelation

Pearson’s correlation coefficient, for interval data (ISO/TS 12913-3 B.3, Formulas (B.1) and (B.2)).

Formula (B.2) divides by n, so the standard deviations are taken with n too, which makes $r$ the usual coefficient; with the n - 1 of a sample standard deviation it would shrink by $(n-1)/n$. The probability value is that of the Student statistic $r\sqrt{(n-2)/(1-r^2)}$ with $n-2$ degrees of freedom, exact for bivariate normal data.

Parameters

Returns: A SoundscapeCorrelation.

Raises

Constant (tuple).

PERCEIVED_AFFECTIVE_QUALITY_ATTRIBUTES = ('pleasant', 'chaotic', 'vibrant', 'uneventful', 'calm', 'annoying', 'eventful', 'monotonous')

pleasantness_eventfulness(
    scale_values: Mapping[str, ArrayLike] | ArrayLike,
    *,
    sites: ArrayLike | Sequence[object] | None = None,
    central_tendency: Literal['median', 'mean'] = 'median',
) -> PleasantnessEventfulness

Pleasantness and eventfulness of a soundscape from its perceived affective quality (ISO/TS 12913-3 A.3, Formulas (A.1) and (A.2)).

The scale values are those of part 2 of Method A, 5 for “strongly agree” down to 1 for “strongly disagree” (Table A.1); method_a_scale_values converts box positions, which run the other way. Every respondent who answered all eight attributes gets a coordinate pair. Each site gets the pair of Formulas (A.1) and (A.2) applied to the site’s median of each attribute (A.2 makes the median the central tendency of the scale), or to its mean with central_tendency="mean". When every respondent answered all eight attributes, that mean point is also the mean of the respondents’ coordinates, the formulas being linear; with blank answers it is not, because each attribute mean is then taken over a different set of respondents.

Clause A.3 says the formulas process “the results from part 3”; the attributes they name are part 2, and that is what they are applied to (see the module docstring and docs/ERRATA.md).

Parameters

Returns: A PleasantnessEventfulness.

Raises

Constant (float).

PLEASANTNESS_EVENTFULNESS_RANGE = 9.65685424949238

PleasantnessEventfulness(
    sites: tuple[str, ...],
    central_tendency: str,
    attribute_values: NDArray[np.float64],
    pleasantness: NDArray[np.float64],
    eventfulness: NDArray[np.float64],
    respondent_sites: tuple[str, ...],
    respondent_pleasantness: NDArray[np.float64],
    respondent_eventfulness: NDArray[np.float64],
    respondent_counts: NDArray[np.int64],
)

Pleasantness and eventfulness of each site and each respondent (ISO/TS 12913-3 A.3, Formulas (A.1) and (A.2)).

on the scale values of the eight attributes of part 2. The coordinates range over $\pm (4+\sqrt{32})\approx \pm 9.66$; the normalized_* properties divide by that, for the $\pm 1$ of A.3.

Attributes

property

$E/(4+\sqrt{32})$ of each site, in $\pm 1$.

property

$P/(4+\sqrt{32})$ of each site, in $\pm 1$.

PleasantnessEventfulness.plot(
    ax: Axes | None = None,
    *,
    normalized: bool = True,
    respondents: bool = False,
    language: str = 'en',
    **kwargs: Any,
) -> Axes

Plot the sites on the two-dimensional model of Figure A.1.

Pleasantness on the horizontal axis and eventfulness on the vertical one, with the eight attributes at the ends of their axes, the diagonal ones at 45 degrees, and every site a point.

Parameters

Returns: The axes. Requires matplotlib (pip install phonometry[plot]).

QuestionnaireScale(
    method: str,
    part: int,
    figure: str,
    subject: str,
    question: str,
    instruction: str,
    items: tuple[str, ...],
    categories: tuple[str, ...],
    scale_values: tuple[int, ...],
    continuous: bool,
)

One scale of the soundscape questionnaire, as ISO/TS 12913-2 prints it.

The text is transcribed from the figure, misprints included: the questions of Figures C.2 to C.4 read “To what extend” and their instructions “reponse alternative”, which docs/ERRATA.md records; a study that prints its own questionnaire from this table should correct them.

Attributes

SoundscapeAcousticEnvironment(
    environment_type: str,
    sound_sources: str,
    weather_and_wind: str,
    time_of_year_and_day: str,
    measurement_points: str,
    measurement_results: Mapping[str, float],
    site_description: str | None = None,
    recording_and_reproduction: str | None = None,
)

The studied acoustic environment (ISO/TS 12913-2 A.3 a) to h)).

Attributes

SoundscapeCorrelation(
    method: str,
    formula: str,
    coefficient: float,
    p_value: float,
    t_statistic: float,
    degrees_of_freedom: int,
    alternative: str,
    x: NDArray[np.float64],
    y: NDArray[np.float64],
    x_ranks: NDArray[np.float64] | None = None,
    y_ranks: NDArray[np.float64] | None = None,
)

A correlation coefficient between two variables and its probability value (ISO/TS 12913-3 A.4 and B.3).

Attributes

property

Number of cases, the pairs the coefficient was computed from.

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

Plot the pairs, as ranks for Spearman, with the coefficient.

Parameters

Returns: The axes. Requires matplotlib (pip install phonometry[plot]).

SoundscapeDataCollection(
    methods: str,
    questions: str,
    language: str,
    instrument_copy: str,
    rating_scale_construction: str | None = None,
    behaviour_observation: str | None = None,
)

How the perception data were collected (ISO/TS 12913-2 A.4 a) to e)).

Attributes

SoundscapeParticipants(
    selection: str,
    residents_or_visitors: str,
    lay_or_expert: str,
    age_and_gender_distribution: str,
    other_relevant_information: str,
)

The participants of a soundscape study (ISO/TS 12913-2 A.2 a) to e)).

Every field is required: “the participants shall be identified and the following information recorded”. Each is free text, because the annex prescribes what is stated and not how.

Attributes

SoundscapeReport(
    participants: SoundscapeParticipants,
    acoustic_environment: SoundscapeAcousticEnvironment,
    data_collection: SoundscapeDataCollection,
)

The minimum reporting requirements of a soundscape study (ISO/TS 12913-2 Annex A, normative, and clause 6).

A.1 lists three things a report shall comprise, and each is one record: the selection and classification of the participants (A.2), the characterization of the studied acoustic environment (A.3), and the data collection on how people perceived it (A.4). Each record refuses to be built with a required item missing, so a SoundscapeReport that exists meets the minimum of Annex A as far as a record can tell; whether what is written is true and sufficient stays with the author.

Attributes

SourceRanking(
    sources: tuple[str, ...],
    sites: tuple[str, ...],
    median_ranks: NDArray[np.float64],
    lowest_ranks: NDArray[np.float64],
    highest_ranks: NDArray[np.float64],
    rank_ranges: NDArray[np.float64],
    mentions: NDArray[np.int64],
    participants: NDArray[np.int64],
)

The rank each recognised sound source was given, per site (ISO/TS 12913-3 B.2, part 2 of Method B, Table B.1).

Every participant lists the sources they noticed from the most noticeable down, at most eight, so a source listed first has rank 1. The level of measurement is ordinal: the median rank is the central tendency and the range the dispersion. Sources are ordered by their median rank over all sites, then by how often they were listed.

Attributes

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

Plot the median rank of each source per site, with its range.

Parameters

Returns: The axes. Requires matplotlib (pip install phonometry[plot]).

spearman_rank_correlation(
    x: ArrayLike,
    y: ArrayLike,
    *,
    alternative: Literal['two-sided', 'greater', 'less'] = 'two-sided',
) -> SoundscapeCorrelation

Spearman’s rank correlation coefficient, for ordinal data (ISO/TS 12913-3 A.4, Formulas (A.3) and (A.4)).

Each variable is ranked, tied values sharing the mean of the ranks they span, and $d_i$ is the difference of the ranks of pair $i$. Without ties Formula (A.3) applies,

and with ties in either variable Formula (A.4),

where $t_j$ is the number of values in the $j$-th group of tied ranks of x and U is the same sum over y. (The page’s where-list garbles these definitions, see docs/ERRATA.md; this is the reading the formula needs.) Formula (A.4) is Pearson’s coefficient of the average ranks, and reduces to (A.3) when nothing is tied.

The probability value is that of the Student statistic $r\sqrt{(n-2)/(1-r^2)}$ with $n-2$ degrees of freedom, the usual approximation for Spearman’s coefficient, which A.4 asks to be reported without naming a test.

Parameters

Returns: A SoundscapeCorrelation.

Raises