[DOC] Improve example quality and API doc clarity

[nbara]

Summary

This PR improves the documentation quality of the package in two ways:

• rewrites and extends several example scripts to make them more didactic
• tightens public API docstrings so parameters/returns are clearer and more consistent with the code

What changed

• improved the teaching narrative of the example gallery, with clearer goals, interpretation hints, and simple quantitative checks
• added a new ASR example focused on calibration sensitivity
• regenerated the corresponding example notebooks
• cleaned up docstrings across core public utilities and methods

[codecov]

Codecov Report

❌ Patch coverage is 83.33333% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 83.29%. Comparing base (2c09b8f) to head (5a48c91).

Files with missing lines	Patch %	Lines
meegkit/utils/testing.py	83.33%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #124      +/-   ##
==========================================
- Coverage   83.30%   83.29%   -0.02%     
==========================================
  Files          25       25              
  Lines        2857     2861       +4     
==========================================
+ Hits         2380     2383       +3     
- Misses        477      478       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR focuses on improving the package’s documentation and example gallery by making example scripts more didactic (added interpretation guidance + simple quantitative checks) and by tightening/expanding docstrings across many public utilities.

Changes:

• Expanded docstrings across meegkit utilities to clarify parameters/returns and improve narrative consistency.
• Updated multiple example scripts with clearer interpretation hints and simple quantitative diagnostics; added a new ASR calibration-sensitivity example (+ notebook).
• Extended create_line_data to accept an optional RNG for reproducible examples.

Reviewed changes

Copilot reviewed 30 out of 40 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
meegkit/utils/testing.py	Adds rng parameter and updates docstring for synthetic line-noise data generation.
meegkit/utils/stats.py	Expands docstrings for rms and robust_mean; clarifies rolling_corr API compatibility.
meegkit/utils/sig.py	Adds/repairs docstrings for signal utilities (e.g., envelope, slope-sum, prony); fixes a parameter name typo in docs.
meegkit/utils/matrix.py	Improves docstrings for shape helpers and fold/unfold/matmul utilities.
meegkit/utils/denoise.py	Expands docstrings for trial means, weighted power, and outlier-sample detection.
meegkit/utils/covariances.py	Clarifies parameter docs for covariance functions (padding/estimator, X vs Y).
meegkit/utils/coherence.py	Expands docstrings for spectrogram/polycoherence plotting helpers and synthetic signal docs.
meegkit/utils/base.py	Adds parameter/return docs for mrdivide and mldivide.
meegkit/utils/auditory.py	Expands docstrings for ERB conversions and filterbank class init params.
meegkit/utils/asr.py	Expands docstrings for ASR helpers (yulewalk, polystab, numf, denf) and parameter naming.
meegkit/trca.py	Adds documentation updates for TRCA-related functions (one doc mismatch noted in comments).
meegkit/sns.py	Expands docstring for sns1 with parameters/returns.
meegkit/detrend.py	Corrects/expands docstrings for detrending and ringing reduction APIs.
meegkit/cca.py	Clarifies parameter docs for nt_cca; expands whitening function docstrings.
meegkit/asr.py	Expands docstrings for ASR entry points and state/weight handling; adds sfreq/show/sample_weight docs.
examples/example_trca.py	Adds post-run summary plots and interpretation text for TRCA performance stability.
examples/example_star.py	Adds narrative and quantitative correlation checks vs clean reference; improves plot labeling.
examples/example_star_dss.py	Adds narrative and quantitative “corr with target” comparisons for DSS vs STAR+DSS.
examples/example_ress.py	Adds narrative + target-bin vs neighboring SNR quantitative checks and labeling.
examples/example_phase_estimation.py	Removes test-import dependency by inlining helpers and adds printed mean absolute errors (indentation consistency noted).
examples/example_mcca.py	Refactors repeated plotting into a helper and adds didactic narration (indentation consistency noted).
examples/example_mcca_2.py	Adds didactic framing and prints correlation with the known target signal.
examples/example_mcca_2.ipynb	Regenerated notebook to match updated script narrative and outputs.
examples/example_dss.py	Adds quantitative correlation checks vs ground truth and improves plot labeling.
examples/example_dss_line.py	Uses seeded RNG via create_line_data(rng=...) and adds a simple PSD line-bin metric + interpretation.
examples/example_dering.py	Improves narrative and adds a simple quantitative ringing proxy metric.
examples/example_asr.py	Adds workflow narration + RMS attenuation summary plot and calibration-retention reporting.
examples/example_asr_calibration_sensitivity.py	New tutorial example comparing ASR attenuation across calibration windows.
examples/example_asr_calibration_sensitivity.ipynb	New notebook generated from the calibration-sensitivity example.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.