Open the front door, and say what each section is not - #509
Merged
Conversation
Work in progress on the entry points, the section overviews and the glossary. English only: the Spanish edition follows. Getting Started now calibrates. It recovered a sound pressure level from an uncalibrated synthetic signal, 46 dB low, and told the reader that the output of wavfile.read can be fed in as it stands, which is 90.3 dB high for integer WAV. A 94 dB calibrator tone now recovers the sensitivity, and every number on the page was re-measured. The site is organised by subject, which is right for looking something up and wrong for arriving. A reader arrives with a task, so there is now a page that maps a task to the guide that answers it, and the landing page's last onboarding step routes into a measurement run end to end rather than into the generated API reference. All thirty-seven overviews now state what their section does not cover, which none of them did. Without it the absence of a method is ambiguous between the library not having it and the reader looking in the wrong place. The seven stubs went from 64-128 words to 608-857. The theory pages were reachable from their own index and almost nowhere else: back-links went from 25 of 105 guides to 74, and the subjects that have no theory section say so on their overview. The glossary went from 121 terms to 198, in 16 groups, over 70 guide slugs. Four cards were wrong. The bibliography gained the 24 cited works that appeared nowhere on it, and is regrouped by area. Two citation defects found while verifying: the McFadden 1987 DOI in the synchronous averaging frontmatter does not resolve, and the Craik 1996 ISBN carried the wrong check digit. EN/ES parity is deliberately red until the Spanish twin of the new task page is written.
One hundred and twelve pages, including one that did not exist: the task-shaped entry page has no Spanish twin until now, and the EN/ES parity gate was red on purpose waiting for it. All ten of its deep links resolve against real Spanish headings rather than translated guesses. The overviews gained their statement of what each section does not cover. The wording is the same on all of them, chosen to echo the block the corpus already uses on a hundred and five guides rather than inventing a second formula for the same job. Two Spanish pages were behind by a whole earlier commit, not by this one: the signals and filter overviews still said a filter bank puts its band edges on the standard's own edges whichever architecture computes them. That claim was corrected in English before this branch existed and never crossed over. Parity is with the English page as it stands, not with one commit's diff, so they are corrected here. The bibliography was regrouped into the twelve areas and gained the works it cited without listing. The prose of the hundred and fifty six entries that were already right was carried across untouched: reorganising a page is not a reason to re-translate the parts of it that were not wrong. Three divergences inside the Spanish tree are recorded rather than fixed. Link texts that drifted between pages, one section that says the coincidence dip falls where its own guide says it is a valley, and a thousands separator that can break across a line. None is a wrong number, and none of them belongs to this change.
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
|
You've reached the fair usage limit for the Bito Code Review Agent trial. Upgrade to a paid plan or contact support@bito.in for assistance. Learn more |
1 similar comment
|
You've reached the fair usage limit for the Bito Code Review Agent trial. Upgrade to a paid plan or contact support@bito.in for assistance. Learn more |
github-actions
Bot
added
documentation
|
Important Review skippedToo many files! This PR contains 310 files, which is 210 over the limit of 100. To get a review, reduce the PR to 100 files or fewer by splitting it into smaller PRs or changing its base branch. Upgrade to a paid plan to raise the limit. Usage-priced reviews support at most 300 files. ⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (310)
You can disable this status message by setting the Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #509 +/- ##
=======================================
Coverage 97.05% 97.05%
=======================================
Files 295 295
Lines 39146 39146
=======================================
Hits 37992 37992
Misses 1154 1154 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
|
Contributor
Numerical conformance report✅ 533/533 conformance checks pass across 57 domains and 362 standards - filters class 1 - weightings within IEC 61672-1 class 1. Each row pins a standard clause to its expected normative value and the value the library computes. Every section below is collapsible and stays collapsed while all of its rows pass; a section with any failing row opens automatically. ✅ Numerical validation - filters & weightings: class showcase (IEC 61260-1 · IEC 61672-1 · ISO 7196)IEC 61260-1:2014 class per filter architecture (order 6, one-third-octave, 100 Hz-10 kHz, fs = 48 kHz). For each architecture the table shows, at its binding band, the measured relative attenuation and the class-1 limit it must clear, so the number and the range it must sit in are both visible. A positive margin means the acceptance limits are met with that much room.
Only Butterworth (the library default) and Chebyshev-II are class-compliant architectures. Chebyshev-I and elliptic trade the mask for passband ripple, and Bessel for a maximally-flat group delay (soft rolloff); they cannot satisfy the IEC 61260-1 Class 1/2 attenuation mask by construction, so they are labelled By design - this is expected, not a failure or regression. Frequency-weighting conformance (A/C: IEC 61672-1 Table 3; G: ISO 7196 A.3). The max deviation from nominal is informational (it falls at a frequency extreme where the tolerance is widest and asymmetric); compliance is judged at the binding frequency - the one with the least headroom - where the deviation, the applicable tolerance band and the headroom are shown together.
✅ Filters & weightings: 100% (10/10)
✅ Levels & dosimetry: 100% (9/9)
✅ Room & building acoustics: 100% (72/72)
✅ Room acoustics: 100% (16/16)
✅ Psychoacoustics: 100% (14/14)
✅ Speech transmission (IEC 60268-16): 100% (10/10)
✅ System measurement (Golay / Kirkeby / Mueller-Massarani): 100% (5/5)
✅ Intensity & sound power: 100% (10/10)
✅ Building prediction & uncertainty: 100% (15/15)
✅ Outdoor propagation & occupational exposure: 100% (10/10)
✅ Materials: absorption, airflow & impedance: 100% (6/6)
✅ Scattering & diffusion (ISO 17497): 100% (14/14)
✅ In-situ road absorption (ISO 13472): 100% (3/3)
✅ Precision sound power (ISO 3745 / 9614-3): 100% (4/4)
✅ Human vibration (ISO 8041 / 2631 / 5349): 100% (15/15)
✅ Speech intelligibility (ANSI S3.5-1997): 100% (24/24)
✅ Objective intelligibility (STOI / ESTOI): 100% (3/3)
✅ Impulsive-sound prominence (NT ACOU 112): 100% (2/2)
✅ Impulsive-sound prominence (ISO/PAS 1996-3): 100% (2/2)
✅ Room noise (ANSI S12.2-2019): 100% (3/3)
✅ Hearing threshold (ISO 7029 / ISO 389-7): 100% (3/3)
✅ Measurement uncertainty (GUM / Supplement 1): 100% (7/7)
✅ Noise-induced hearing loss (ISO 1999): 100% (6/6)
✅ Multiple-shock whole-body vibration (ISO 2631-5): 100% (6/6)
✅ Sound absorption in enclosed spaces (EN 12354-6): 100% (2/2)
✅ Prominent discrete tones (ECMA-418-1): 100% (2/2)
✅ Tonal audibility (ISO/PAS 20065): 100% (11/11)
✅ Psychoacoustic annoyance & fluctuation strength (Fastl & Zwicker): 100% (3/3)
✅ Electroacoustics: distortion & frequency response: 100% (20/20)
✅ Calibrated spectral analysis (Bendat & Piersol): 100% (12/12)
✅ Multiple-input coherence (Bendat & Piersol): 100% (5/5)
✅ Time-frequency analysis (Bendat & Piersol): 100% (3/3)
✅ Correlation, time delay and envelope (B&P / Knapp & Carter): 100% (7/7)
✅ Cepstrum, liftering and envelope spectrum (Havelock / B&P): 100% (3/3)
✅ Time synchronous averaging (McFadden 1987): 100% (5/5)
✅ Data qualification and Rice statistics (Bendat & Piersol): 100% (8/8)
✅ Underwater acoustics (ISO 18405/17208/18406): 100% (6/6)
✅ Underwater sound propagation (transmission loss): 100% (16/16)
✅ Underwater propagation regimes (Weston flux theory): 100% (3/3)
✅ Marine-mammal auditory weighting (NMFS / Southall): 100% (4/4)
✅ Underwater numerical propagation (modes / rays / PE): 100% (4/4)
✅ Aircraft noise (ICAO Annex 16 / IEC 61265): 100% (15/15)
✅ Rotorcraft noise (ECAC Doc 32 / NORAH2): 100% (12/12)
✅ CNOSSOS-EU road source (Directive 2002/49/EC Annex II): 100% (6/6)
✅ Wind-turbine noise (IEC 61400-11): 100% (3/3)
✅ Porous & multilayer absorbers (Mechel / Bies / Cox & D'Antonio): 100% (20/20)
✅ Slow-sound perfect absorbers (Jimenez et al. Appl. Sci. 2017): 100% (3/3)
✅ Program loudness (ITU-R BS.1770 / EBU R 128): 100% (8/8)
✅ 2D FDTD wave simulation (Attenborough & Van Renterghem 2021, Ch. 4): 100% (4/4)
✅ Swept-sine distortion & phase utilities (Farina / Novak): 100% (7/7)
✅ Spherical ground & barriers (Attenborough / Salomons / Bies): 100% (7/7)
✅ Panel & aperture sound insulation (Bies / Hopkins / Cremer): 100% (17/17)
✅ Bending-wave plate-junction transmission (Cremer / Craik / Hopkins): 100% (6/6)
✅ Atmospheric refraction (Salomons rays / GFPE): 100% (3/3)
✅ Electroacoustics: 100% (9/9)
✅ Industrial noise control: 100% (22/22)
✅ CNOSSOS-EU railway source (Directive 2002/49/EC Annex II): 100% (8/8)
Tests & coverage — 48204 tests, 0 failures (✅ all green)
Conformance harness: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The library's documentation is organised by subject, which is right for looking something up and wrong for arriving. This is the arrival half: the entry points, the thirty-seven section overviews, and the glossary.
The first page taught the worst habit
Getting Started printed a column headed "SPL [dB]" from an uncalibrated synthetic signal, 46 dB below the real level, and told the reader that the output of
wavfile.readcan be fed in as it stands, which is 90.3 dB high for integer WAV. Between those two, a reader following the page arrives at a number that is wrong in both directions and looks plausible.It now calibrates. A 94 dB calibrator tone (1.0024 Pa, not 1 Pa) recovers the sensitivity exactly, band levels come back at 90.71 and 90.95 dB SPL against 44.93 dB uncalibrated, and every number on the page was re-measured rather than carried over.
There was no task-shaped door
A reader arrives with a task, not with a taxonomy. There is now a page that maps a task to the guide that answers it, and the landing page's last onboarding step routes into a measurement run end to end instead of into the generated API reference, which is a wall of signatures.
The theory pages were reachable from their own index and almost nowhere else: back-links went from 25 of 105 guides to 74. The subjects that have no theory section say so on their overview rather than leaving the reader to wonder.
No overview said what its section is not
All thirty-seven now do. Without it the absence of a method is ambiguous between the library not having it and the reader looking in the wrong place, and only one of those is worth acting on. The seven stub overviews went from 64 to 128 words up to 608 to 857.
Glossary
From 121 terms in 12 groups to 198 in 16, covering 70 guide slugs instead of 46. Four cards were wrong, which is worse than missing: a glossary is consulted precisely when the reader is unsure. Every card carries its Spanish definition, and both locales render 198 cards with no KaTeX errors. The mirror at
docs/reference/glossary.mddid not exist and is now generated, with its own staleness check.Found while verifying
Two citation defects that no finding predicted: the McFadden 1987 DOI in the synchronous averaging frontmatter does not resolve on doi.org or Crossref (the correct one is 10.1016/0888-3270(87)90085-9), and the Craik 1996 ISBN carried the wrong check digit in both languages.
Three claims proposed for these pages were checked against the code and corrected before writing:
verify_weighting_classdoes not refuse the G and D curves, it is that neither reaches the class limit; the diffuser guides do measure scattering; and the underwater impedance ratio is 3726, not 3600.IEC 60268-3:2013clause 3.1.3 puts its 10 dB reduction on the source e.m.f. rather than on the output, which is what the electroacoustics overview now says, with the clause number.Both languages
One hundred and twelve Spanish pages, including the new entry page written in full. Two Spanish overviews turned out to be behind an earlier commit rather than this one, still carrying a filter claim corrected in English before this branch existed; parity is with the English page as it stands, so they are corrected here.
Checks
The full CI set was run locally before pushing: the thirteen Python gates, and the eleven the site job runs, including the build, HTML validation, the KaTeX pass, the accessibility audit, the sidebar check and the visual audit. Twenty five of twenty five.