select

function of dascore.proc.coords source

select(
    patch: Patch ,
    copy = False,
    relative = False,
    samples = False,
    **kwargs ,
)-> ‘PatchType’

Return a subset of the patch.

Any dimension name can be passed as key, and the values can be: - a tuple of (min, max) for that dimension, or an equivalent slice. None and … both indicate open intervals, as does an infinite bound pointing away from the data, eg (min, np.inf). - an integer, when samples=True, to select a single row or column. - an array of values to select, which must be a subset of the coordinate array. - an array of booleans of the same length as the coordinate where True indicates values to keep. This form does not support samples=True.

Parameters

Parameter Description
patch The patch object.
copy If True, copy the resulting data. This is needed so the old
array can get gc’ed and memory freed.
relative If True, select ranges are relative to the start of coordinate, if
positive, or the end of the coordinate, if negative.
samples If True, the query meaning is in samples.
**kwargs Used to specify the coordinate on which data are selected.

Examples

import numpy as np
import dascore as dc
from dascore.examples import get_example_patch
patch = get_example_patch()

# select meters 50 to 300
new_distance = patch.select(distance=(50, 300))

# select channels less than 300
lt_dist = patch.select(distance=(..., 300))

# select time (1 second from start to -1 second from end)
t1 = patch.get_coord("time").min() + dc.to_timedelta64(1)
t2 = patch.get_coord("time").max() - dc.to_timedelta64(1)
new_time1 = patch.select(time=(t1, t2))

# this can be accomplished more simply using the relative keyword
new_time2 = patch.select(time=(1, -1), relative=True)

# filter 1 second from start time to 3 seconds from start time
new_time3 = patch.select(time=(1, 3), relative=True)

# filter 6 second from end time to 1 second from end time
new_time4 = patch.select(time=(-6, -1), relative=True)

# Select first 10 distance indices
new_distance1 = patch.select(distance=(..., 10), samples=True)

# Select last time row/column
new_distance2 = patch.select(time=-1, samples=True)

# only include certain rows/columns based on a boolean array.
time = patch.get_array("time")
new_time_5 = patch.select(time=time>time[2])

# Select only specific values along a dimension
distance = patch.get_array("distance")
new_distance_3 = patch.select(distance=distance[1::2])
Note

  • It is important to remember select will not change the order of the patch, only filter values. If the order of the patch should change, or multiple rows/columns need to be repeated, See Patch.order.

  • A range of values includes both of its endpoints, but a range of samples excludes its upper bound, like python’s slicing. This means -1 at the end of a sample range excludes the last sample, even though -1 on its own selects it. Using the example patch, which has 300 distance channels and 2000 time samples:

    import dascore as dc patch = dc.get_example_patch() # Both endpoints included; 11 channels. len(patch.select(distance=(0, 10)).get_array(“distance”)) 11 # Upper bound excluded; 10 samples. len(patch.select(time=(0, 10), samples=True).get_array(“time”)) 10 # -1 as a range end drops the last sample. len(patch.select(time=(0, -1), samples=True).get_array(“time”)) 1999 # But -1 on its own selects it. len(patch.select(time=-1, samples=True).get_array(“time”)) 1

    A slice can be used in place of a tuple, and makes the half-open behavior of sample ranges more obvious:

    len(patch.select(time=slice(0, -1), samples=True).get_array(“time”)) 1999