pow_coord

function of dascore.proc.basic source

pow_coord(
    patch: Patch ,
    relative: bool = True,
    **kwargs ,
)-> ‘PatchType’

Scale the data by coordinate values raised to a power.

This is the deterministic counterpart of automatic gain control (see normalize): the gain depends only on where a sample sits along a coordinate, not on the amplitudes around it, so amplitudes stay comparable from one trace to the next. Raising time to a power of one or two is the usual correction for the geometric spreading and attenuation which make later arrivals weaker.

Parameters

Parameter Description
patch The patch to scale.
relative If True, count the coordinate from its own start, so the gain curve
begins at one and the first sample keeps its amplitude. If False,
use the coordinate’s absolute values, which raises the data units to
match.
**kwargs Dimension names and the power to raise each to, e.g. time=2.
Note

  • The relative curve is ((coord - coord[0]) / step + 1) ** power, which is one, two, three … raised to the power. Counting from one rather than zero is what keeps a power from zeroing the first sample.

  • An unevenly sampled coordinate has no one step, so its first is used: the curve is the offset from the start measured in first steps, plus one. Every sample still gets a distinct gain, but the spacing of the curve no longer follows the spacing of the coordinate.

  • That makes the curve a function of the sample, not of the physical span, so the same patch resampled gains differently: the sample one second in is the 250th at 250 Hz and the 125th at 125 Hz. Within one patch every trace is gained identically, which is what makes their amplitudes comparable; across patches of different sample rates they are not, so gain before resampling or not at all.

  • That curve is a ratio of coordinate values and so carries no units, which is why relative=True leaves the data units alone. An absolute curve does carry them, so relative=False multiplies the data units by the coordinate’s, raised to the same power.

  • relative=False is refused for time coordinates. Their absolute values count from an epoch, and a power of the seconds since 1970 says nothing about the data.

Examples

import dascore as dc
patch = dc.get_example_patch()

# Correct for spreading which grows as the square of traveltime.
gained = patch.pow_coord(time=2)

# Along the fiber instead.
gained = patch.pow_coord(distance=1)

# Both at once.
gained = patch.pow_coord(time=2, distance=1)