CHANGELOG.md

Changelog

All notable changes to the Soundscapy project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.7.6] - 2024-11-06

Changed

• Improved handling of optional dependencies to provide better error messages and IDE support
• Audio components (like Binaural) can now be imported directly from the top-level package (from soundscapy import Binaural) while maintaining helpful error messages when dependencies are missing
• Centralized optional dependency configuration in _optionals.py for better maintainability

Developer Notes

• No changes required to existing code using audio components
• The new system provides better IDE completion support while maintaining the same runtime behavior
• Optional components can still be imported from their original location (from soundscapy.audio import Binaural) or from the top level (from soundscapy import Binaural)

[0.7.5]

Added

Support for Optional Dependencies

Soundscapy splits its functionality into optional modules to reduce the number of dependencies required for basic functionality. By default, Soundscapy includes the survey data processing and plotting functionality.

If you would like to use the binaural audio processing and psychoacoustics functionality, you will need to install the optional audio dependency:

pip install soundscapy[audio]

To install all optional dependencies, use the following command:

pip install soundscapy[all]

Developer notes

Dev Container Configuration

• Added a new devcontainer.json file to configure the development container with specific features and VSCode extensions. (.devcontainer/devcontainer.json .devcontainer/devcontainer.jsonR1-R69)
• Updated .dockerignore to exclude the virtual environment directory. (.devcontainer/.dockerignore .devcontainer/.dockerignoreR1)

GitHub Workflows:

• Removed old CI, release, and test-release workflows. (.github/workflows/ci.yml [1] .github/workflows/release.yml [2] .github/workflows/test-release.yml [3]
• Added a new workflow for tagged releases to automate the release process, including building and publishing to PyPI and TestPyPI. (.github/workflows/tag-release.yml .github/workflows/tag-release.ymlR1-R138)
• Added a new workflow for testing tagged releases, including installation from TestPyPI and running tests. (.github/workflows/test-tag-release.yml .github/workflows/test-tag-release.ymlR1-R114)
• Added new workflows for running tests on the main codebase and tutorial notebooks. (.github/workflows/test.yml [1] .github/workflows/test-tutorials.yml [2]

[0.7.3]

Improved

• Allowed the user to request files to be resampled upon loading. This is necessary for Mosqito metrics, which requires (and will itself resample) the audio files to be 48 kHz. The user can specify the desired sample rate in Binaural.from_wav() and higher level functions like AudioAnalysis.analyse_file, AudioAnalysis.analyse_folder.

[0.7.0]

Complete refactoring of Soundscapy, splitting it into multiple modules (surveys, databases, audio, plotting), and improving the overall structure and functionality of the package. Also added more comprehensive documentation and test coverage.

General Changes

Added

• New soundscapy/surveys/survey_utils.py for shared utilities
  • Implemented PAQ enum for Perceptual Attribute Questions
  • Added return_paqs function for filtering PAQ columns
  • Created rename_paqs function for standardizing PAQ column names
• Centralized logging configuration in soundscapy/logging.py
  • Added support for environment variables to configure logging:
    • SOUNDSCAPY_LOG_LEVEL for setting log level
    • SOUNDSCAPY_LOG_FILE for specifying a log file
  • Implemented checks for Jupyter notebook environment in logging configuration
  • Added set_log_level function to allow dynamic adjustment of log level at runtime
  • Introduced global variable GLOBAL_LOG_LEVEL to manage log level across different environments
    • Implemented setup_logger function for initializing the logger with custom options
    • Set default logger to WARNING level with console output
    • Created get_logger function to retrieve the configured logger
• New processing module soundscapy/surveys/processing.py with enhanced functionality
  • Implemented ISOCoordinates and SSMMetrics dataclasses
  • Added calculate_iso_coords function for ISO coordinate calculations
  • Created add_iso_coords function to add ISO coordinates to DataFrames
  • Implemented likert_data_quality function for data quality checks
  • Added simulation function for generating random PAQ responses
  • Created ssm_metrics function for Structural Summary Method calculations
• Comprehensive docstrings and doctest examples in isd.py and satp.py
• New test cases in test_isd.py to cover refactored functionality

Changed

• Modified default logging level to WARNING for better control over log output
• Refactored isd.py to use new processing and survey utility functions
  • Updated load, load_zenodo, and validate functions
  • Refactored selection functions (select_record_ids, select_group_ids, etc.)
  • Updated describe_location and soundscapy_describe functions
• Refactored satp.py to align with new package structure
  • Updated load_zenodo and load_participants functions
  • Added doctest examples for all functions
• Modified __init__.py to initialize the logger when the package is imported
• Updated import statements across modules to use the new package structure
• Standardized function signatures and return types across all modules
• Changed to Rye as the dependency and environment manager for the project

Improved

• Enhanced error handling and input validation in database modules
  • Added type hints to all functions for better code readability and IDE support
  • Implemented more specific exception handling
• Optimized data processing functions for better performance
• Improved code organization and modularity
  • Separated concerns between data loading, processing, and analysis
• Enhanced documentation with more detailed explanations and examples
• Standardized coding style across all modules (using Black formatter)

Deprecated

• Removed remove_lockdown function in isd.py (redundant since the release of ISD v1.0)

Removed

• Eliminated redundant code and unused functions across modules

Fixed

• Resolved issues with inconsistent PAQ naming conventions
• Fixed bugs in ISO coordinate calculations and SSM metric computations
• Resolved issue where Jupyter notebooks were overriding the default log level

Security

• Implemented input validation to prevent potential security vulnerabilities

Development

• Implemented a more robust logging system using loguru
  • Added ability to easily change log levels for debugging and development
  • Enabled file logging for persistent log storage
• Enhanced test coverage for core functionality
• Added doctest examples to ensure documentation accuracy and serve as functional tests
• Implemented consistent error messages and logging across the package

Documentation

• Added comprehensive docstrings to all functions and classes
• Included usage examples in function docstrings
• Updated README with new package structure and usage instructions
• Created this CHANGELOG to track all significant changes to the project

Changes to Plotting Module

Code Structure:

• Split the original circumplex.py into multiple files: backends.py, circumplex_plot.py, plot_functions.py, stylers.py, and plotting_utils.py (implied).
• Introduced abstract base class PlotBackend and concrete implementations SeabornBackend and PlotlyBackend.

New Features:

• Added support for Plotly backend alongside Seaborn.
• Introduced CircumplexPlot class for creating and managing plots.
• Added StyleOptions dataclass for better style management.
• Implemented simple_density plot type.

Improved Customization:

• Created CircumplexPlotParams dataclass for better parameter management.
• Added more customization options for plots (e.g., incl_outline, fill, alpha).

Enhancements:

• Improved type hinting throughout the codebase.
• Added docstrings to classes and functions.
• Implemented PlotType and Backend enums for better type safety.

Refactoring:

• Moved plotting logic from functions to methods in backend classes.
• Simplified scatter and density functions by leveraging CircumplexPlot class.

Removed Features:

• Removed jointplot function (marked as TODO in CircumplexPlot class).

Constants and Utilities:

• Moved constants (e.g., DEFAULT_XLIM, DEFAULT_YLIM) to a separate utilities file.
• Created ExtraParams TypedDict for additional plotting parameters.

[0.6.2]

Added

• Changed the name of the calculate_paq_coords to calculate_iso_coords to better reflect the function's purpose.
• Updated the formula for calculate_iso_coords to the more generalised form given in Aletta et. al. (2024).