Skip to content

Commit 4b056c9

Browse files
d-chambersd-chambers
committed
add doc examples
1 parent 6f098be commit 4b056c9

File tree

10 files changed

+285
-15
lines changed

10 files changed

+285
-15
lines changed

‎dascore/core/coordmanager.py‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,18 @@ def update(self, **kwargs) -> Self:
233233
234234
Input values can be of the same form as initialization.
235235
To drop coordinates, simply pass {coord_name: None}
236+
237+
Examples
238+
--------
239+
>>> import dascore as dc
240+
>>> import numpy as np
241+
>>> patch = dc.get_example_patch()
242+
>>> coords = patch.coords
243+
>>>
244+
>>> # Update time coordinate
245+
>>> new_time = np.arange(len(coords.get_array('time')))
246+
>>> new_coords = coords.update(time=new_time)
247+
>>> assert 'time' in new_coords
236248
"""
237249

238250
def _get_dim_change_drop(coord_map, dim_map):
@@ -589,6 +601,16 @@ def select(
589601
**kwargs
590602
Used to specify dimension and select arguments.
591603
604+
Examples
605+
--------
606+
>>> import dascore as dc
607+
>>> patch = dc.get_example_patch()
608+
>>> coords = patch.coords
609+
>>>
610+
>>> # Select subset of coordinates
611+
>>> new_coords, _ = coords.select(time=(0, 10))
612+
>>> assert 'time' in new_coords
613+
592614
See also [`CoordManager.order`](`dascore.core.CoordManager.order`).
593615
"""
594616
if relative or samples:
@@ -1120,7 +1142,7 @@ def get_coord_manager(
11201142
if dims is None:
11211143
if isinstance(coords, Mapping) and all(isinstance(x, str) for x in coords):
11221144
dims = tuple(i for i, v in coords.items() if not isinstance(v, tuple))
1123-
elif attrs is not None and "dims" in attrs or hasattr(attrs, "dims"):
1145+
elif (attrs is not None and "dims" in attrs) or hasattr(attrs, "dims"):
11241146
dims = tuple(attrs["dims"].split(","))
11251147
else:
11261148
dims = ()

‎dascore/core/patch.py‎

Lines changed: 72 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -210,7 +210,19 @@ def __str__(self):
210210

211211
@property
212212
def dims(self) -> tuple[str, ...]:
213-
"""Return the dimensions contained in patch."""
213+
"""
214+
Return the dimensions contained in patch.
215+
216+
Examples
217+
--------
218+
>>> import dascore as dc
219+
>>> patch = dc.get_example_patch()
220+
>>>
221+
>>> # Get dims from patch.
222+
>>> dims = patch.dims
223+
>>> assert 'time' in dims
224+
>>> assert 'distance' in dims
225+
"""
214226
return self.coords.dims
215227

216228
@property
@@ -225,27 +237,81 @@ def coord_shapes(self) -> dict[str, tuple[int, ...]]:
225237

226238
@property
227239
def attrs(self) -> PatchAttrs:
228-
"""Return the dimensions contained in patch."""
240+
"""
241+
Return the patch attributes.
242+
243+
Examples
244+
--------
245+
>>> import dascore as dc
246+
>>> patch = dc.get_example_patch()
247+
>>>
248+
>>> # Get attrs from patch.
249+
>>> attrs = patch.attrs
250+
>>> assert hasattr(attrs, 'data_type')
251+
"""
229252
return self._attrs
230253

231254
@property
232255
def coords(self) -> CoordManager:
233-
"""Return the dimensions contained in patch."""
256+
"""
257+
Return the patch coordinates.
258+
259+
Examples
260+
--------
261+
>>> import dascore as dc
262+
>>> patch = dc.get_example_patch()
263+
>>> coords = patch.coords
264+
>>>
265+
>>> # Get coords from patch.
266+
>>> assert 'time' in coords
267+
>>> assert 'distance' in coords
268+
"""
234269
return self._coords
235270

236271
@property
237272
def data(self) -> ArrayLike:
238-
"""Return the data contained in patch."""
273+
"""
274+
Return the data contained in patch.
275+
276+
Examples
277+
--------
278+
>>> import dascore as dc
279+
>>> patch = dc.get_example_patch()
280+
>>> data = patch.data
281+
>>> assert data.shape == patch.shape
282+
"""
239283
return self._data
240284

241285
@property
242286
def shape(self) -> tuple[int, ...]:
243-
"""Return the shape of the data array."""
287+
"""
288+
Return the shape of the data array.
289+
290+
Examples
291+
--------
292+
>>> import dascore as dc
293+
>>> patch = dc.get_example_patch()
294+
>>>
295+
>>> # Get shape from patch.
296+
>>> shape = patch.shape
297+
>>> assert len(shape) == len(patch.dims)
298+
"""
244299
return self.coords.shape
245300

246301
@property
247302
def size(self) -> int:
248-
"""Return the size of the data array."""
303+
"""
304+
Return the size of the data array.
305+
306+
Examples
307+
--------
308+
>>> import dascore as dc
309+
>>> patch = dc.get_example_patch()
310+
>>>
311+
>>> # Get size from patch.
312+
>>> size = patch.size
313+
>>> assert size == patch.data.size
314+
"""
249315
return self.coords.size
250316

251317
@property

‎dascore/proc/aggregate.py‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,15 @@ def min(
9393
----------
9494
{params}
9595
96+
Examples
97+
--------
98+
>>> import dascore as dc
99+
>>> patch = dc.get_example_patch()
100+
>>>
101+
>>> # Get minimum along time dimension
102+
>>> min_patch = patch.min(dim='time')
103+
>>> assert min_patch.size < patch.size
104+
96105
{notes}
97106
"""
98107
return aggregate.func(patch, dim=dim, method=np.nanmin, dim_reduce=dim_reduce)
@@ -112,6 +121,15 @@ def max(
112121
----------
113122
{params}
114123
124+
Examples
125+
--------
126+
>>> import dascore as dc
127+
>>> patch = dc.get_example_patch()
128+
>>>
129+
>>> # Get maximum along distance dimension
130+
>>> max_patch = patch.max(dim='distance')
131+
>>> assert max_patch.size < patch.size
132+
115133
{notes}
116134
"""
117135
return aggregate.func(patch, dim=dim, method=np.nanmax, dim_reduce=dim_reduce)
@@ -131,6 +149,15 @@ def mean(
131149
----------
132150
{params}
133151
152+
Examples
153+
--------
154+
>>> import dascore as dc
155+
>>> patch = dc.get_example_patch()
156+
>>>
157+
>>> # Get mean along time dimension
158+
>>> time_mean = patch.mean(dim='time')
159+
>>> assert time_mean.size < patch.size
160+
134161
{notes}
135162
"""
136163
return aggregate.func(patch, dim=dim, method=np.nanmean, dim_reduce=dim_reduce)

‎dascore/proc/basic.py‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,21 @@ def pipe(
7272
Positional arguments that get passed to func.
7373
**kwargs
7474
Keyword arguments passed to func.
75+
76+
Examples
77+
--------
78+
>>> import dascore as dc
79+
>>> patch = dc.get_example_patch()
80+
>>>
81+
>>> # Define a custom function that squares the data
82+
>>> def square_data(patch):
83+
... return patch.new(data=patch.data ** 2)
84+
>>>
85+
>>> # Use pipe to apply the function
86+
>>> squared = patch.pipe(square_data)
87+
>>>
88+
>>> # Can also chain with other methods
89+
>>> result = patch.pipe(square_data).mean(dim="time")
7590
"""
7691
return func(self, *args, **kwargs)
7792

@@ -84,6 +99,17 @@ def update_attrs(self: PatchType, **attrs) -> PatchType:
8499
----------
85100
**attrs
86101
attrs to add/update.
102+
103+
Examples
104+
--------
105+
>>> import dascore as dc
106+
>>> patch = dc.get_example_patch()
107+
>>>
108+
>>> # Update existing attributes
109+
>>> updated = patch.update_attrs(instrument_type="DAS")
110+
>>>
111+
>>> # Add new custom attributes
112+
>>> with_custom = patch.update_attrs(processing_date="2024-01-01")
87113
"""
88114

89115
def _fast_attr_update(self, attrs):
@@ -119,6 +145,23 @@ def equals(self: PatchType, other: Any, only_required_attrs=True, close=False) -
119145
close
120146
If True, the data can be "close" using np.allclose, otherwise
121147
all data must be equal.
148+
149+
Examples
150+
--------
151+
>>> import dascore as dc
152+
>>> patch1 = dc.get_example_patch()
153+
>>> patch2 = dc.get_example_patch()
154+
>>>
155+
>>> # Test equality
156+
>>> are_equal = patch1.equals(patch2)
157+
>>>
158+
>>> # Test with modified patch
159+
>>> modified = patch1.update_attrs(custom_attr="test")
160+
>>> equal_ignoring_custom = patch1.equals(modified, only_required_attrs=True)
161+
>>>
162+
>>> # Test with close comparison for numerical data
163+
>>> noisy = patch1.new(data=patch1.data + 1e-10)
164+
>>> close_equal = patch1.equals(noisy, close=True)
122165
"""
123166
# different types are not equal
124167
if not isinstance(other, type(self)):
@@ -300,6 +343,20 @@ def normalize(
300343
l2 - divide each sample by the l2 of the axis.
301344
max - divide each sample by the maximum of the absolute value of the axis.
302345
bit - sample-by-sample normalization (-1/+1)
346+
347+
Examples
348+
--------
349+
>>> import dascore as dc
350+
>>> patch = dc.get_example_patch()
351+
>>>
352+
>>> # L2 normalization along time dimension
353+
>>> l2_norm = patch.normalize(dim="time", norm="l2")
354+
>>>
355+
>>> # Max normalization along distance dimension
356+
>>> max_norm = patch.normalize(dim="distance", norm="max")
357+
>>>
358+
>>> # Bit normalization (sign only)
359+
>>> bit_norm = patch.normalize(dim="time", norm="bit")
303360
"""
304361
axis = self.get_axis(dim)
305362
data = self.data
@@ -460,8 +517,10 @@ def fillna(patch: PatchType, value, include_inf=True) -> PatchType:
460517
>>> import dascore as dc
461518
>>> # load an example patch which has some NaN values.
462519
>>> patch = dc.get_example_patch("patch_with_null")
520+
>>>
463521
>>> # Replace all occurrences of NaN with 0
464522
>>> out = patch.fillna(0)
523+
>>>
465524
>>> # Replace all occurrences of NaN with 5
466525
>>> out = patch.fillna(5)
467526
"""
@@ -518,11 +577,14 @@ def pad(
518577
--------
519578
>>> import dascore as dc
520579
>>> patch = dc.get_example_patch()
580+
>>>
521581
>>> # Zero pad `time` dimension with 2 patch's time unit (e.g., sec)
522582
>>> # zeros before and 3 zeros after
523583
>>> padded_patch_1 = patch.pad(time=(2, 3))
584+
>>>
524585
>>> # Pad `distance` dimension with 1s 4 samples before and 4 after.
525586
>>> padded_patch_3 = patch.pad(distance=4, constant_values=1, samples=True)
587+
>>>
526588
>>> # Get patch ready for fast fft along time dimension.
527589
>>> padded_fft = patch.pad(time="fft")
528590
"""
@@ -602,10 +664,13 @@ def roll(patch, samples=False, update_coord=False, **kwargs):
602664
--------
603665
>>> import dascore as dc
604666
>>> patch = dc.get_example_patch()
667+
>>>
605668
>>> # roll time dimension 5 elements
606669
>>> rolled_patch = patch.roll(time=5, samples=True)
670+
>>>
607671
>>> # roll distance dimension 30 meters(or units of distance in patch)
608672
>>> rolled_patch2 = patch.roll(distance=30, samples=False)
673+
>>>
609674
>>> # roll time dimension 5 elements and update coordinates
610675
>>> rolled_patch3 = patch.roll(time=5, samples=True, update_coord=True)
611676
"""

0 commit comments

Comments
 (0)