Detailed API reference table with parameters and returns

[jmrplens]

This PR enhances the "Quick API Reference" section in the README.md:

1. Detailed Descriptions: Included all input parameters for every function/class, along with their types, units, and default values.
2. Complete Usage Snippets: Updated snippets to show all possible arguments.
3. Return Values: Added a bulleted list under each snippet explaining what variables are returned and their formats (e.g., "1D array of levels [dB]").
4. Formatting: Used HTML line breaks (<br>) within the table to maintain a clean and readable layout.

[gemini-code-assist]

Summary of Changes

Hello @jmrplens, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly improves the documentation within the README.md file by expanding the 'Quick API Reference' section. The goal is to provide a much clearer and more comprehensive guide for users, detailing function parameters, complete usage examples, and explicit return values, thereby making the API easier to understand and utilize.

Highlights

• Enhanced API Reference Descriptions: The 'Quick API Reference' section in README.md now includes detailed descriptions for all input parameters for every function and class, specifying their types, units, and default values.
• Complete Usage Snippets: Usage snippets have been updated to demonstrate all possible arguments for each function, providing a more comprehensive example of how to use the API.
• Return Value Documentation: A bulleted list has been added under each usage snippet to clearly explain what variables are returned by the functions and their respective formats (e.g., '1D array of levels [dB]').
• Improved Table Formatting: HTML line breaks (<br>) are now utilized within the API reference table to ensure a clean, readable, and well-structured layout for the detailed information.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[github-actions]

CI Results 🚀

Test Summary

Python Version	Tests	Failures	Coverage	Status
3.10	66	0	100.0%	✅ Passed
3.11	66	0	100.0%	✅ Passed
3.12	66	0	100.0%	✅ Passed
3.13	66	0	100.0%	✅ Passed
3.9	66	0	100.0%	✅ Passed

Filter Architecture Benchmark Report

This report compares the performance and characteristics of the available filter types.

1. Spectral Isolation (at 1kHz)

Filter Type	Peak SPL (dB)	Atten. -1 Oct (dB)	Atten. +1 Oct (dB)	Atten. -2 Oct (dB)	Atten. +2 Oct (dB)
butter	90.96	40.0	32.3	46.8	57.7
cheby1	90.96	39.8	40.2	46.5	57.2
cheby2	90.96	42.5	50.4	49.2	61.6
ellip	90.95	39.9	45.1	46.6	57.1
bessel	90.54	41.6	33.6	48.4	60.1

2. Stability and Performance

Filter Type	Max IR Tail Energy	Stability Status	Avg. Execution Time (s)
butter	1.29e-09	✅ Stable	0.1187
cheby1	2.04e-07	✅ Stable	0.1132
cheby2	2.12e-07	✅ Stable	0.1185
ellip	4.95e-07	✅ Stable	0.1172
bessel	4.21e-15	✅ Stable	0.1382

3. Analysis Summary

• Butterworth: Best compromise, maximally flat passband.
• Chebyshev I: Steeper roll-off than Butterworth but with passband ripple.
• Chebyshev II: Flat passband, ripple in the stopband.
• Elliptic: Steepest transition but ripples in both passband and stopband.
• Bessel: Best phase response and minimal ringing (group delay), but slowest roll-off.

Generated Graphs

🔍 View crossover_lr4.png

🔍 View filter_bessel_fraction_1_order_6.png

🔍 View filter_bessel_fraction_3_order_6.png

🔍 View filter_butter_fraction_1_order_6.png

🔍 View filter_butter_fraction_3_order_6.png

🔍 View filter_cheby1_fraction_1_order_6.png

🔍 View filter_cheby1_fraction_3_order_6.png

🔍 View filter_cheby2_fraction_1_order_6.png

🔍 View filter_cheby2_fraction_3_order_6.png

🔍 View filter_ellip_fraction_1_order_6.png

🔍 View filter_ellip_fraction_3_order_6.png

🔍 View filter_fraction_1.5_order_16.png

🔍 View filter_fraction_1.5_order_6.png

🔍 View filter_fraction_12_order_6.png

🔍 View filter_fraction_1_order_16.png

🔍 View filter_fraction_1_order_6.png

🔍 View filter_fraction_24_order_6.png

🔍 View filter_fraction_3_order_16.png

🔍 View filter_fraction_3_order_6.png

🔍 View filter_type_comparison.png

🔍 View signal_decomposition.png

🔍 View signal_response_fraction_1.png

🔍 View signal_response_fraction_3.png

🔍 View signal_response_multichannel.png

🔍 View time_weighting_analysis.png

🔍 View weighting_responses.png

View Full Artifacts

[gemini-code-assist]

Code Review

This pull request is a great step towards improving the API documentation in the README.md. The new detailed table is much more user-friendly. However, my review found several critical discrepancies between the new documentation and the actual function signatures in the source code. These inaccuracies could lead to confusion and incorrect usage of the library. I've provided specific comments and suggestions to align the documentation with the implementation, particularly for calculate_sensitivity, getansifrequencies, and normalizedfreq, which have significant errors. Addressing these will make the API reference accurate and reliable.

[gemini-code-assist]

There's a critical mismatch between the documentation for calculate_sensitivity and its actual implementation in the source code.

1. Incorrect Parameters: The function signature is calculate_sensitivity(ref_signal, target_spl=94.0, ref_pressure=2e-5). It does not take an fs parameter.
2. Missing Parameter: The ref_pressure parameter is not documented.
3. Inconsistent Naming: The documentation uses x_ref while the code uses ref_signal.

I recommend rewriting this entry to accurately reflect the function's signature and purpose.

Suggested change

	| `calculate_sensitivity` | `function`| **SPL Calibration.**<br>• `x_ref`: Calibration signal<br>• `fs`: Sample rate [Hz]<br>• `target_spl`: Level of calibrator (Default: 94.0) | `s = calculate_sensitivity(x_ref, fs, target_spl=94.0)`<br><br>• `s`: Float (multiplier for pressure) |
	| `calculate_sensitivity` | `function`| **SPL Calibration.**<br>• `ref_signal`: Calibration signal array<br>• `target_spl`: Level of calibrator [dB] (Default: 94.0)<br>• `ref_pressure`: Reference pressure [Pa] (Default: 2e-5) | `s = calculate_sensitivity(ref_signal, target_spl=94.0)`<br><br>• `s`: Float (sensitivity multiplier) |

[gemini-code-assist]

The documentation for getansifrequencies has a couple of critical inaccuracies:

1. No Default for fraction: The fraction parameter is required and does not have a default value of 1.
2. Incorrect Return Value: The function returns a tuple of three lists: (center_frequencies, lower_band_edges, upper_band_edges). The documentation incorrectly states it only returns a single list of center frequencies.

The usage snippet f = getansifrequencies(...) is also misleading, as it would only capture the first of the three return values. This should be corrected to freq, freq_d, freq_u = getansifrequencies(...) to reflect the actual output.

Suggested change

	| `getansifrequencies` | `function` | **ANSI Frequency generator.**<br>• `fraction`: 1, 3, etc. (Default: 1)<br>• `limits`: [f_min, f_max] (Default: [12, 20000]) | `f = getansifrequencies(fraction=3, limits=[20, 20000])`<br><br>• `f`: List of center frequencies [Hz] |
	| `getansifrequencies` | `function` | **ANSI Frequency generator.**<br>• `fraction`: 1, 3, etc.<br>• `limits`: [f_min, f_max] (Default: [12, 20000]) | `freq, freq_d, freq_u = getansifrequencies(fraction=3, limits=[20, 20000])`<br><br>• `freq`: List of center frequencies [Hz]<br>• `freq_d`: List of lower edge frequencies [Hz]<br>• `freq_u`: List of upper edge frequencies [Hz] |

[gemini-code-assist]

This documentation entry for normalizedfreq is incorrect and describes a function that doesn't match the source code.

The actual normalizedfreq(fraction) function takes a single integer argument (1 or 3) and returns a predefined list of standard IEC center frequencies for that fraction. It does not calculate band edges.

The current description, parameters, and return values seem to belong to a different (or non-existent) function. This entire row should be rewritten to accurately describe what normalizedfreq does.

Suggested change

	| `normalizedfreq` | `function` | **Band edge calculator.**<br>• `freq`: Center frequency [Hz]<br>• `fraction`: 1, 3, etc. | `f_low, f_up = normalizedfreq(1000, 3)`<br><br>• `f_low`: Lower cut-off frequency [Hz]<br>• `f_up`: Upper cut-off frequency [Hz] |
	| `normalizedfreq` | `function` | **Standard Frequencies.**<br>• `fraction`: 1 or 3 | `freq = normalizedfreq(fraction=3)`<br><br>• `freq`: List of standard IEC center frequencies [Hz] |

[gemini-code-assist]

The documentation for octavefilter is missing several important parameters that are available through **kwargs. For completeness and user clarity, I recommend adding them.

Missing parameters include:

• limits: Frequency limits [f_min, f_max].
• ripple: Passband ripple for cheby1 and ellip filters.
• attenuation: Stopband attenuation for cheby2 and ellip filters.
• calibration_factor: For physical SPL calculation.
• dbfs: To get results in dBFS.
• mode: To select 'rms' or 'peak' level calculation.

Additionally, when sigbands=True, the function returns a third value: a list of the time-domain signals for each band. This should also be documented in the 'Outputs' section.

[gemini-code-assist]

This documentation entry is a bit confusing. The 'Outputs' section describes the bank object itself, but the usage example correctly shows that the useful output comes from the bank.filter(x) method.

I suggest two improvements:

1. Add the missing parameters for the OctaveFilterBank constructor, such as ripple, attenuation, dbfs, etc., along with their defaults.
2. Change the 'Outputs' section to describe the return values of bank.filter(x), which are spl and freq, similar to how it's done for the octavefilter function. This would make the documentation much clearer for the user.

[gemini-code-assist]

The mode parameter has a default value that isn't mentioned in the documentation. To make the API reference more complete, please consider adding (Default: 'fast') to its description.

Suggested change

	| `time_weighting` | `function` | **Energy capture.**<br>• `x`: Signal array<br>• `fs`: Sample rate [Hz]<br>• `mode`: 'fast', 'slow', or 'impulse' | `env = time_weighting(x, fs, mode='fast')`<br><br>• `env`: 1D array of energy envelope (Mean Square) |
	| `time_weighting` | `function` | **Energy capture.**<br>• `x`: Signal array<br>• `fs`: Sample rate [Hz]<br>• `mode`: 'fast', 'slow', or 'impulse' (Default: 'fast') | `env = time_weighting(x, fs, mode='fast')`<br><br>• `env`: 1D array of energy envelope (Mean Square) |

[github-actions]

CI Results 🚀

Test Summary

Python Version	Tests	Failures	Coverage	Status
3.10	66	0	100.0%	✅ Passed
3.11	66	0	100.0%	✅ Passed
3.12	66	0	100.0%	✅ Passed
3.13	66	0	100.0%	✅ Passed
3.9	66	0	100.0%	✅ Passed

Filter Architecture Benchmark Report

This report compares the performance and characteristics of the available filter types.

1. Spectral Isolation (at 1kHz)

Filter Type	Peak SPL (dB)	Atten. -1 Oct (dB)	Atten. +1 Oct (dB)	Atten. -2 Oct (dB)	Atten. +2 Oct (dB)
butter	90.96	40.0	32.3	46.8	57.7
cheby1	90.96	39.8	40.2	46.5	57.2
cheby2	90.96	42.5	50.4	49.2	61.6
ellip	90.95	39.9	45.1	46.6	57.1
bessel	90.54	41.6	33.6	48.4	60.1

2. Stability and Performance

Filter Type	Max IR Tail Energy	Stability Status	Avg. Execution Time (s)
butter	1.29e-09	✅ Stable	0.0391
cheby1	2.04e-07	✅ Stable	0.0397
cheby2	2.12e-07	✅ Stable	0.0401
ellip	4.95e-07	✅ Stable	0.0413
bessel	4.21e-15	✅ Stable	0.0512

3. Analysis Summary

• Butterworth: Best compromise, maximally flat passband.
• Chebyshev I: Steeper roll-off than Butterworth but with passband ripple.
• Chebyshev II: Flat passband, ripple in the stopband.
• Elliptic: Steepest transition but ripples in both passband and stopband.
• Bessel: Best phase response and minimal ringing (group delay), but slowest roll-off.

Generated Graphs

🔍 View crossover_lr4.png

🔍 View filter_bessel_fraction_1_order_6.png

🔍 View filter_bessel_fraction_3_order_6.png

🔍 View filter_butter_fraction_1_order_6.png

🔍 View filter_butter_fraction_3_order_6.png

🔍 View filter_cheby1_fraction_1_order_6.png

🔍 View filter_cheby1_fraction_3_order_6.png

🔍 View filter_cheby2_fraction_1_order_6.png

🔍 View filter_cheby2_fraction_3_order_6.png

🔍 View filter_ellip_fraction_1_order_6.png

🔍 View filter_ellip_fraction_3_order_6.png

🔍 View filter_fraction_1.5_order_16.png

🔍 View filter_fraction_1.5_order_6.png

🔍 View filter_fraction_12_order_6.png

🔍 View filter_fraction_1_order_16.png

🔍 View filter_fraction_1_order_6.png

🔍 View filter_fraction_24_order_6.png

🔍 View filter_fraction_3_order_16.png

🔍 View filter_fraction_3_order_6.png

🔍 View filter_type_comparison.png

🔍 View signal_decomposition.png

🔍 View signal_response_fraction_1.png

🔍 View signal_response_fraction_3.png

🔍 View signal_response_multichannel.png

🔍 View time_weighting_analysis.png

🔍 View weighting_responses.png

View Full Artifacts

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud