act.transform.subsample#

act.transform.subsample(data, target, dim, qc=None, qc_mask=None, t_range=None)[source]#

Nearest-neighbor subsample data onto target coordinate values along dim.

Parameters:

  • data (xarray.DataArray) – Input DataArray.

  • target (xarray.DataArray or numpy.ndarray) – Target coordinate values to subsample onto.

  • dim (str) – Name of the dimension along which to apply the transform.

  • qc (xarray.DataArray, optional) – Optional integer QC DataArray with same shape as data.

  • qc_mask (int, str, list[str], or None) – Integer bitmask, QC assessment name, or None. An assessment name is matched against qc.attrs['flag_assessments']; None selects "Bad", which requires flag_masks metadata on qc (a ValueError is raised otherwise); without qc no QC bits are excluded.

  • t_range (float or numpy.timedelta64, optional) – Maximum distance from a target point to an input point for selection. Must be a timedelta when dim is a datetime coordinate and a number otherwise. Defaults to no limit.

Returns:

  • result (xarray.DataArray) – Subsampled DataArray on the target coordinate.

  • result_qc (xarray.DataArray) – Integer QC DataArray with same shape as result, with CF flag_masks/flag_meanings/flag_assessments attributes set.

See also

act.transform.bin_average

Weighted average over output bins.

act.transform.interpolate

Linear interpolation onto the target coordinate.

act.transform.transform_dataset

Apply a transform to every variable in a Dataset.

Examples

Select the nearest sample to each target point. Because subsampling returns a value that was actually observed rather than a computed one, it is the right choice for codes, flags, states, and other categorical quantities that averaging or interpolating would render meaningless.

import act

ds = act.io.arm.read_arm_netcdf(filename, cleanup_qc=True)
target = act.transform.make_coord('2023-03-01', '2023-03-02', '30min')

result, result_qc = act.transform.subsample(
    ds['pwd_pw_code_inst'], target, dim='time'
)

Honor input QC and cap how far the search may reach. When the nearest sample is excluded by qc_mask a farther one is used instead, and the output is flagged QC_NOT_USING_CLOSEST so the substitution is visible. When the coordinate is a datetime, t_range must be a timedelta; by default there is no limit.

import numpy as np
from act.transform.constants import QC_NOT_USING_CLOSEST

result, result_qc = act.transform.subsample(
    ds['pwd_pw_code_inst'],
    target,
    dim='time',
    qc=ds['qc_pwd_pw_code_inst'],
    qc_mask=4,
    t_range=np.timedelta64(5, 'm'),
)
substituted = (result_qc.values & QC_NOT_USING_CLOSEST).astype(bool)