unselect

function of dascore.proc.coords source

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

Return the patch outside a selection.

The complement of Patch.select: it takes the same selectors and removes the samples that selection would have kept. With one coordinate named that is exactly the complement; with several, each is complemented on its own — see the note below.

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, unselect 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 unselected.

Examples

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

# Drop meters 50 to 300, keeping what lies outside them.
outside = patch.unselect(distance=(50, 300))

# Drop the first ten distance samples.
trimmed = patch.unselect(distance=(..., 10), samples=True)
Note

  • Removing a range from the middle of a coordinate leaves a hole in it, so the result is no longer evenly sampled and the coordinate becomes a monotonic array. That is exactly what Spool.unselect refuses the patches’ own coordinates for: at spool level the complement of a range is a hole in every patch rather than a choice between patches. The coordinates an attached inventory defines along the fiber it does accept, since removing one of those chooses which channels a patch holds.

  • Each named coordinate is complemented on its own. Selecting on two coordinates keeps the samples in both ranges, and everything outside that is a frame around them rather than a block, which no array can hold — so unselect removes each named range instead, which is the part of the complement that is expressible. Two coordinates along one dimension therefore both take their range out of it, leaving what neither removed.