Making Soundscape Assessment Accessible: The SoundGraphy Tool

Soundscapy: The essential python architecture

Soundscapy is an open-source Python library designed to provide a standardized and accessible framework for the characterization and analysis of soundscape perception, strictly adhering to the ISO 12913 series of standards (Soundscapy: A python package for soundscape assessment and analysis). The software specifically addresses the limitations found in traditional ISO methods, which often struggle to summarize the collective perception of groups or specific locations accurately (5).

Python architecture and core functionalities

The architecture of Soundscapy is built upon a modular ecosystem of scientific Python libraries to ensure both flexibility and performance:

Data Handling and Processing: The package utilizes Pandas as its primary engine for managing large-scale survey datasets, allowing for robust data cleaning and validation (16).

Probabilistic Visualization: Departing from the traditional ‘single-point’ median method, Soundscapy leverages Matplotlib and Seaborn to implement a distribution-based approach (5). It uses bivariate KDEs to visualize the collective perception of a space as a shaded distribution within the two-dimensional circumplex model (Pleasantness vs. Eventfulness) (16).

Acoustic and Psychoacoustic Analysis: For the treatment of binaural recordings, Soundscapy subclasses standard signal classes to provide a dedicated binaural class (16). This class integrates three specialized toolboxes: (i) Python Acoustics: For calculating standard-referenced acoustic indices such as LAeq and LZeq, (ii) Scikit-maad: For extracting ecoacoustic and bioacoustic indices, and (iii) MoSQITo: For computing complex, time-varying psychoacoustic metrics like loudness, sharpness, and roughness (16).

Workflow and reproducibility

A key architectural feature is the focus on research reproducibility through the AnalysisSettings class, which allows users to define and share analysis parameters via YAML files (16). Furthermore, the package is optimized for high-throughput research, supporting parallelized batch processing of multiple recordings to significantly reduce computational time on multi-core systems (16).

Ultimately, Soundscapy serves as a comprehensive ‘modeling and prediction pipeline’ that bridges the gap between raw acoustic data and nuanced human perceptual outcomes (16). However, advanced statistical analyses—such as SSM and ISO—and research requirements, such as plotting of medians or data filtering, as well as a user-friendly graphical environment, are not implemented in Soundscapy.

Intuitive, standalone control interface

Soundscape research is inherently cross-disciplinary, attracting professionals from diverse fields—such as acoustics, building construction, architecture, and environmental physics—many of whom do not possess computer programming backgrounds. SoundGraphy eliminates the technical prerequisite of knowing Python by offering an interactive and highly intuitive GUI built upon CustomTkinter, a Python library that uses Tkinter with the aim of providing enough mechanisms to create modern attractive GUIs. To support the current software usability standards and reduce visual fatigue during long analysis sessions, the interface features fully integrated Light Mode and Dark Mode configurations. Furthermore, by utilizing PyInstaller, the software is compiled and packaged into a self-contained executable application. This allows end-users to install and run the program natively like traditional commercial desktop software, operating seamlessly on their machines without needing a Python installation, shell terminal configurations, or manual package dependency management.

User-friendly data-entry

Graphical profiling in soundscape analysis involves massive datasets that consolidate widespread human perceptual surveys. Traditionally, these datasets are stored across varying spreadsheet structures and platform ecosystems. Powered by the robust Pandas engine, SoundGraphy effortlessly ingests these large, heterogeneous tabular files, supporting both proprietary formats and open-source file categories—including Microsoft Excel (.xlsx), Google Sheets, and plain-text Delimiter-Separated Values, such as standard CSV spreadsheets. Because independent international research teams employ highly customized tabular layouts with varying variable names, the software features an integrated manual mapping utility. Instead of forcing users to rewrite their data to match a rigid template, this utility enables researchers to directly bind each of the eight standardized ISO 12913 perceptual attributes to its corresponding column in their specific spreadsheet via simple drop-down menus (See Figure 2).

Figure 2

Advanced database filtering system

Empirical soundscape databases contain complex, multi-dimensional environmental and social variables that extend far beyond raw emotional metrics. Ingestion profiles contain varied spatial metadata (e.g., different cities, neighborhoods, or specific urban acoustic environments), distinct temporal markers, and diverse demographic participant backgrounds. In practical application, investigators rarely need to target an entire database at once; rather, thorough scientific investigations, require slicing the data to isolate highly specific observational scenarios. For example, a researcher might want to examine the exact acoustic perception profile of an urban square strictly during peak traffic hours on working weekdays between 7:00 AM and 9:00 AM. Previously, investigators had to manually partition, filter, and clean raw data files using external database software prior to running any specialized plot code. SoundGraphy completely automates this pre-processing stage by implementing an integrated, real-time database filtering system, allowing users to instantly segment, refine, and isolate targeted datasets directly inside the application environment before generating any graphical representations.

To accommodate these diverse data types, SoundGraphy’s integrated filtering engine features dynamic, context-aware logical operators tailored to the specific nature of each selected database column:

- Temporal Data Filtering (Date and Time Columns):

For variables managing chronological data, the system provides specialized operators to easily capture discrete seasonal, weekly, or hourly windows. Researchers can isolate data subsets using intuitive operations such as:

• - Before/after (to segment data chronologically around specific events)

• - Between/outside (ideal for framing precise hourly shifts, such as the 7:00 AM to 9:00 AM peak traffic window)

• - On/not on (to target or exclude exact evaluation dates)

- Numerical Metric Filtering (Continuous and Discrete Variables):

For quantitative variables—such as the age or a Soundscape Quality Index—the platform deploys standard mathematical logical bounds (See Figure 3). This enables precise thresholding through operators including:

• - >, ≥/<, ≤ (to filter out extreme noise levels or quiet background thresholds)

• - =/≠ (for targeting specific rounded response brackets)

• - Between/outside (to capture or isolate data falling within narrow statistical ranges)

- Categorical Domain Selection (Low-Variety Variables):

For columns containing descriptive labels or low-cardinality categorical data, SoundGraphy bypasses rigid text-matching syntax. Instead, it dynamically scans the column and generates a manual checklist interface. This allows researchers to effortlessly check or uncheck specific attributes to include in the active working memory. This utility is perfectly suited for quick segmentation across:

• - Demographic markers (e.g., gender categories such as Male/Female)

• - Temporal conditions (e.g., calendar classifications like Weekday/Holiday)

• - Spatial identifiers (e.g., specific alphanumeric tracking codes designating the exact measuring site or urban square, such as STOP01 or STOP02)

Figure 3

By embedding these tailored multi-type filtering parameters directly into the GUI, SoundGraphy bridges the gap between raw data warehousing and localized perceptual analysis, allowing complex cross-conditional soundscape profiles to be generated in just a few clicks.

Two-dimensional Cartesian projections (The ISO circumplex plane)

This core category focuses on the traditional coordinate space defined by the orthogonal P_ISO and E_ISO axes. While Soundscapy serves as the underlying pipeline for these coordinates, its visualization settings are notoriously difficult to adjust natively. A scatter plot is the basic graphic used in this category, where all the single responses are projected to a single point in the Cartesian axes. However, when datasets are excessively dense, managing individual scatter points becomes unreadable. SoundGraphy solves this by providing some additional features that can be freely combined by the user.

• - Kernel Density Options: Employs probabilistic bivariate KDE to visualize collective perception as shaded distributions. Some custom variants are allowed:

  • Full Percentile Contour Spectrum: Displays the entire distribution range across every decile (from P₁₀ up to P₉₀).

  • Isolated P₅₀ Contour: Limits the visualization exclusively to the core P₅₀ boundary in order to reduce the data shown even more, therefore not overwhelming the end-user.

  • Each decile can be rendered either as a solid filled region or as a clean vector outline.

• - Marginal Axis Distributions: Users can choose whether or not to display the univariate kernel distribution curves along the top and right margins of each axis, providing a quick view of data density for both P_ISO and E_ISO independently.

• - Automated Attribute Labeling: SoundGraphy automatically overlays the eight standardized perceptual attributes (pleasant, vibrant, eventful, chaotic, annoying, monotonous, uneventful, and calm) onto their exact angular locations. The location of these labels has been carefully chosen in order to not be placed where most of the scattered data points are.

• - Integrated Median Representation: Because single-point median representations are highly valued for summarizing an entire environment’s acoustic profile, users can opt to automatically overlay a composite median marker. SoundGraphy calculates this by extracting the statistical median of each of the eight individual perceptual dimensions and subsequently projecting the resulting vector onto the Cartesian plane strictly according to the ISO standard equations. Depending on the user’s aim, a label can optionally be added to that marker.

Box-and-whisker plots

Powered by the Seaborn statistical visualization library, boxplots are essential in soundscape research because they reveal the underlying data distribution, interquartile range (IQR), and outliers that single median points completely obscure. SoundGraphy offers two deployment paths for this format:

• - Classic Approach: Automatically places the eight standardized perceptual attributes along the X-axis to showcase the comparative rating spreads of each emotional index side by side.

• - Personalized Bi-Axis Variables: Allows researchers to explicitly customize what variables occupy the X and Y axes. For instance, a user can chart discrete stimulus evaluation points (e.g., specific measurement locations) against a dependent axis like Eventfulness to analyze structural variance across diverse urban conditions.

Custom X versus Y scatter plot

For multi-dimensional exploration beyond standard soundscape metrics, SoundGraphy features a highly flexible, custom bivariate plotting tool. This feature allows users to map any two numerical or categorical variables from the imported spreadsheet against each other on a customized Cartesian coordinate system (X-axis vs. Y-axis).

Upon selecting this visualization mode, a dedicated user interface prompts the user to assign specific columns for both axes, providing an unrestricted framework for cross-variable analysis (e.g., examining the relationship between participant age and a specific perceptual attribute response, or comparing different acoustic indicators).

Radar plots (spider charts)

Radar plots provide an alternate circular profile mapping that matches how survey protocols are structured around participants. These charts map the intensity of responses across the eight directional components simultaneously, letting the user directly analyze the eight perceptual attributes and not only their projections.

To prevent visual clutter, SoundGraphy enforces a practical GUI constraint based on a maximum threshold of data rows (or stimuli categories) simultaneously. If the filtered dataset is below this limit, the chart displays every individual response as a separate profile. However, if the dataset exceeds this threshold, the application intelligently adapts: it displays a warning dialog to the user and automatically calculates and plots the median profiles instead. This dynamic aggregation prevents the overlapping shapes from becoming an unreadable web, preserving crisp visual clarity for comparative studies without restricting larger datasets.

Categorical variable differentiation (hue mapping)

One of the most critical visual analytical advancements in SoundGraphy is the native implementation of variable-based color differentiation. Environmental soundscape databases are highly heterogeneous; researchers frequently need to visually compare separate data subsets on a single coordinate canvas. SoundGraphy integrates an automated grouping utility that allows users to pick any categorical metadata column to drive the plot’s color palette. This enables immediate visual comparison across key research parameters:

• - Spatial Tracking: Comparing different physical measurement stations or specific urban squares on a single canvas to see how spatial design alters perception.

• - Temporal Classifications: Evaluating the distinct behavioral shift between Weekdays and Holidays, or analyzing diurnal patterns across changing hours of the day.

• - Demographic Cross-Sections: Slicing spatial clusters by participant background indicators (such as age groups or gender responses) to verify cross-cultural perceptual divergence.

By automating these advanced formatting and grouping routines, SoundGraphy removes the need to write custom Matplotlib or Seaborn color-mapping scripts, letting researchers isolate complex acoustic interactions directly from the interface.

Mathematical foundations and parameter estimation

The SSM serves as a robust statistical procedure designed to evaluate whether empirical soundscape survey responses adhere to the theoretical circumplex geometry dictated by the ISO 12913 standards. Rather than treating the eight perceptual attributes as isolated variables, the SSM treats them as a continuous, interrelated profile ordered around a 360-degree circular space. SoundGraphy leverages the specialized Soundscapy library backend to execute the mathematical regressions. Through this framework, the software evaluates the profile of the data by fitting a sinusoidal cosine curve to the empirical scores. This mathematical optimization outputs three fundamental parameters that parsimoniously summarize the entire acoustic perception profile: Elevation (e), Amplitude (a), and Displacement (d).

Graphical sinusoidal verification layout

Beyond calculating these numerical metrics, SoundGraphy features an automated plotting sub-module to visually verify the goodness of fit. The software automatically constructs a standardized two-dimensional line chart that contrasts empirical observation against the optimized mathematical model:

• - The Horizontal Axis (X-Axis): It maps the eight standardized perceptual attributes. Crucially, they are plotted in a strict, mathematically sequential angular order (which depends on their position in the 2D plane) to allow the data to be fitted to a continuous cosine wave. This order is: pleasant, vibrant, eventful, chaotic, annoying, monotonous, uneventful, and calm.

• - The Vertical Axis (Y-Axis): It represents the response intensity values assigned to each perceptual attribute. On this coordinate system, SoundGraphy projects two distinct lines simultaneously to compare the real and the fitted values for each perceptual attribute:

• The Empirical Profile (Real Data): This represents the direct experimental data, plotted as a series of connected points reflecting the statistical median score calculated for each of the eight individual soundscape attributes.

• The Theoretical Profile (Predicted Fit): This represents the idealized circumplex model curve generated by the SSM regression. For every corresponding octant angle (α), the software uses the parameters supplied by Soundscapy and computes the predicted Y-axis position using the following trigonometric function:

  $Y_{\mathit{\text{Predicted}}}=e+a·\mathit{\text{cos}}\left(\alpha -d\right)$

  The predicted fit can either be represented as a polygonal connected line, or as the actual sinusoidal function.

This visual representation, alongside the R² parameter, provides a streamlined tool for assessing cross-cultural translation shifts and geometric variations across diverse international contexts.