add examples to public methods #549
Conversation
WalkthroughAdded example-rich docstrings across multiple modules and clarified boolean precedence in dascore/core/coordmanager.py:get_coord_manager. No public API signatures changed and no runtime behavior modifications beyond the clarified conditional. Changes
Possibly related PRs
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests
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 |
coderabbitai
bot
added
documentation
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
dascore/proc/aggregate.py (1)
152-165: Duplicate Parameters section in mean docstring.The docstring has two "Parameters" sections (lines 161-164 duplicate the earlier Parameters section). This should be cleaned up.
- Examples - -------- - >>> import dascore as dc - >>> patch = dc.get_example_patch() - >>> # Get mean along time dimension - >>> time_mean = patch.mean(dim='time') - >>> time_mean.size < patch.size - True - - Parameters - ---------- - {params} - + Examples + -------- + >>> import dascore as dc + >>> patch = dc.get_example_patch() + >>> # Get mean along time dimension + >>> time_mean = patch.mean(dim='time') + >>> time_mean.size < patch.size + True +
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (8)
dascore/core/coordmanager.py(3 hunks)dascore/core/patch.py(2 hunks)dascore/proc/aggregate.py(3 hunks)dascore/proc/basic.py(4 hunks)dascore/proc/coords.py(1 hunks)dascore/proc/units.py(2 hunks)dascore/transform/fft.py(1 hunks)dascore/viz/spectrogram.py(1 hunks)
🧰 Additional context used
🧬 Code graph analysis (2)
dascore/core/patch.py (1)
dascore/core/coordmanager.py (3)
CoordManager(140-1072)shape(783-789)size(792-794)
dascore/core/coordmanager.py (1)
dascore/core/patch.py (1)
attrs(237-249)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (17)
- GitHub Check: test_code (windows-latest, 3.13)
- GitHub Check: test_code (ubuntu-latest, 3.12)
- GitHub Check: test_code (windows-latest, 3.12)
- GitHub Check: test_code (windows-latest, 3.11)
- GitHub Check: test_code (macos-latest, 3.11)
- GitHub Check: test_code (windows-latest, 3.10)
- GitHub Check: test_code (macos-latest, 3.12)
- GitHub Check: test_code (macos-latest, 3.10)
- GitHub Check: test_code (ubuntu-latest, 3.10)
- GitHub Check: test_code (ubuntu-latest, 3.13)
- GitHub Check: test_code (ubuntu-latest, 3.11)
- GitHub Check: test_code_min_deps (windows-latest, 3.12)
- GitHub Check: test_code_min_deps (windows-latest, 3.13)
- GitHub Check: test_code_min_deps (macos-latest, 3.13)
- GitHub Check: test_code_min_deps (ubuntu-latest, 3.12)
- GitHub Check: test_code_min_deps (macos-latest, 3.12)
- GitHub Check: test_code_min_deps (ubuntu-latest, 3.13)
🔇 Additional comments (20)
dascore/proc/units.py (2)
86-97: LGTM - Good documentation examples added.The examples clearly demonstrate the usage of both
convert_unitsandsimplify_unitsmethods with practical scenarios. The code shows proper setup, method calls, and demonstrates the expected behavior.
120-129: LGTM - Clear and helpful examples.The examples for
simplify_unitsshow a good progression from setting complex units to simplifying them to base units, which helps users understand the method's purpose.dascore/proc/coords.py (1)
662-673: LGTM - Well-structured example for squeeze method.The example demonstrates a realistic use case: creating a length-1 dimension through selection and then squeezing it. This provides clear context for when and how to use the squeeze method.
dascore/viz/spectrogram.py (1)
73-82: LGTM - Simple and effective example.The example shows basic usage of the spectrogram method and includes a verification step. The
show=Falseparameter is appropriately used to prevent display during testing.dascore/proc/basic.py (4)
75-87: LGTM - Excellent pipe method examples.The examples show both basic usage and method chaining, which are the primary use cases for the pipe method. The custom function example is practical and easy to understand.
99-108: LGTM - Good coverage of update_attrs use cases.The examples show both updating existing attributes and adding new custom attributes, covering the main scenarios users would encounter.
143-157: LGTM - Comprehensive equals method examples.The examples demonstrate all the key parameters (
only_required_attrsandclose) with realistic scenarios that help users understand when to use each option.
338-349: LGTM - Clear normalize method examples.The examples show different normalization types with appropriate dimensions, helping users understand the various options available.
dascore/core/patch.py (6)
213-224: LGTM - Concise and effective dims property example.The example demonstrates how to access the dims property and verify the expected dimensions are present.
238-249: LGTM - Good attrs property example.Shows basic usage and demonstrates checking for attribute existence, which is a common use case.
253-266: LGTM - Clear coords property examples.Shows both accessing the coords property and checking for specific coordinates, covering typical usage patterns.
270-281: LGTM - Good data property example.Demonstrates the relationship between patch.data and patch.shape, which is helpful for understanding the data structure.
285-296: LGTM - Clear shape property example.Shows the relationship between shape and dimensions, which is fundamental for users working with patch data.
300-311: LGTM - Appropriate size property example.Demonstrates the equivalence between patch.size and patch.data.size, clarifying this relationship for users.
dascore/transform/fft.py (1)
30-38: LGTM - Simple and clear deprecated method example.The example shows basic usage and verifies the expected output dimension, which is appropriate for a deprecated method. The example helps users understand what the method does while they transition to the recommended alternative.
dascore/proc/aggregate.py (2)
96-104: LGTM - Clear min aggregation example.Shows the method usage and includes a practical verification that the result is smaller than the original, demonstrating the aggregation effect.
124-132: LGTM - Good max aggregation example.Consistent with the min example, showing usage and appropriate verification of the aggregation result.
dascore/core/coordmanager.py (3)
236-248: LGTM - Clear update method example.The example demonstrates updating a coordinate and verifying the result, which is the primary use case for this method.
604-613: LGTM - Good select method example.Shows basic coordinate selection and verification, helping users understand the method's functionality.
1145-1145: Fix boolean operator precedence for dims extraction.The parentheses clarify the intended logic: only extract dims when attrs is not None AND contains "dims", while still allowing hasattr check for attrs with a dims attribute.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #549 +/- ##
=======================================
Coverage 99.92% 99.92%
=======================================
Files 125 126 +1
Lines 10435 10455 +20
=======================================
+ Hits 10427 10447 +20
Misses 8 8
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
|
✅ Documentation built: |
d-chambers
force-pushed
the
more_examples
branch
from
42e3f05 to
4b056c9
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (3)
dascore/proc/basic.py (3)
520-520: Minor formatting improvement needed.Consider removing the extra blank lines for consistency with other examples in the file.
>>> import dascore as dc >>> # load an example patch which has some NaN values. >>> patch = dc.get_example_patch("patch_with_null") ->>> >>> # Replace all occurrences of NaN with 0 >>> out = patch.fillna(0) ->>> >>> # Replace all occurrences of NaN with 5 >>> out = patch.fillna(5)Also applies to: 523-523, 525-525
580-580: Minor formatting improvement needed.Consider removing the extra blank lines for consistency with other examples in the file.
>>> import dascore as dc >>> patch = dc.get_example_patch() ->>> >>> # Zero pad `time` dimension with 2 patch's time unit (e.g., sec) >>> # zeros before and 3 zeros after >>> padded_patch_1 = patch.pad(time=(2, 3)) ->>> >>> # Pad `distance` dimension with 1s 4 samples before and 4 after. >>> padded_patch_3 = patch.pad(distance=4, constant_values=1, samples=True) ->>> >>> # Get patch ready for fast fft along time dimension. >>> padded_fft = patch.pad(time="fft")Also applies to: 584-584, 587-587, 590-590
667-667: Minor formatting improvement needed.Consider removing the extra blank lines for consistency with other examples in the file.
>>> import dascore as dc >>> patch = dc.get_example_patch() ->>> >>> # roll time dimension 5 elements >>> rolled_patch = patch.roll(time=5, samples=True) ->>> >>> # roll distance dimension 30 meters(or units of distance in patch) >>> rolled_patch2 = patch.roll(distance=30, samples=False) ->>> >>> # roll time dimension 5 elements and update coordinates >>> rolled_patch3 = patch.roll(time=5, samples=True, update_coord=True)Also applies to: 670-670, 673-673, 675-675
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (10)
dascore/core/coordmanager.py(3 hunks)dascore/core/patch.py(2 hunks)dascore/proc/aggregate.py(3 hunks)dascore/proc/basic.py(7 hunks)dascore/proc/coords.py(8 hunks)dascore/proc/units.py(3 hunks)dascore/transform/fft.py(1 hunks)dascore/units.py(3 hunks)dascore/utils/misc.py(1 hunks)dascore/viz/spectrogram.py(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- dascore/units.py
🚧 Files skipped from review as they are similar to previous changes (8)
- dascore/proc/units.py
- dascore/utils/misc.py
- dascore/viz/spectrogram.py
- dascore/core/coordmanager.py
- dascore/transform/fft.py
- dascore/proc/aggregate.py
- dascore/proc/coords.py
- dascore/core/patch.py
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (18)
- GitHub Check: test_code (windows-latest, 3.12)
- GitHub Check: test_code (windows-latest, 3.11)
- GitHub Check: test_code (windows-latest, 3.10)
- GitHub Check: test_code (ubuntu-latest, 3.11)
- GitHub Check: test_code (macos-latest, 3.10)
- GitHub Check: test_code (ubuntu-latest, 3.13)
- GitHub Check: test_code (ubuntu-latest, 3.10)
- GitHub Check: test_code (ubuntu-latest, 3.12)
- GitHub Check: test_code (windows-latest, 3.13)
- GitHub Check: test_code (macos-latest, 3.13)
- GitHub Check: test_code (macos-latest, 3.11)
- GitHub Check: test_build_docs
- GitHub Check: test_code_min_deps (ubuntu-latest, 3.12)
- GitHub Check: test_code_min_deps (macos-latest, 3.13)
- GitHub Check: test_code_min_deps (ubuntu-latest, 3.13)
- GitHub Check: test_code_min_deps (macos-latest, 3.12)
- GitHub Check: test_code_min_deps (windows-latest, 3.12)
- GitHub Check: test_code_min_deps (windows-latest, 3.13)
🔇 Additional comments (4)
dascore/proc/basic.py (4)
75-90: LGTM! Clear and practical examples added.The examples demonstrate the pipe functionality effectively, showing both simple usage and method chaining.
102-113: LGTM! Good examples for attribute management.The examples clearly show both updating existing attributes and adding new custom attributes, which covers the main use cases.
148-165: LGTM! Comprehensive examples for equality testing.The examples cover all three main scenarios: basic equality, ignoring custom attributes, and using close comparison for numerical precision issues.
346-360: LGTM! Well-structured examples covering all normalization types.The examples demonstrate each normalization method (l2, max, bit) with clear context and appropriate dimensions.
Description
This PR adds more examples to DASCore's public API, specifically for methods/functions that didn't have any.
Checklist
I have (if applicable):
Summary by CodeRabbit
Documentation
Bug Fixes