act.transform.transform_dataset#

act.transform.transform_dataset(ds, target=None, dim=None, transform=None, qc_prefix='qc_', qc_mask=None, target_ds=None, per_var_transform=None, per_var_kwargs=None, **kwargs)[source]#

Apply a transform to every variable in ds that contains dim.

For each variable, if a companion QC variable named {qc_prefix}<var> exists in the dataset it is used automatically.

Parameters:

  • ds (xarray.Dataset) – Input Dataset.

  • target (xarray.DataArray or numpy.ndarray, optional) – Target coordinate values. Mutually exclusive with target_ds.

  • dim (str) – Dimension name along which to transform.

  • transform ({“bin_average”, “interpolate”, “subsample”}) – Default transform to apply to every matching variable.

  • qc_prefix (str) – Prefix used to find companion QC variables (default "qc_").

  • qc_mask (int, str, list[str], or None) – Integer bitmask, QC assessment name, or None. An assessment name is matched against each QC companion’s flag_assessments metadata; None selects "Bad", which requires flag_masks metadata on each QC companion (a ValueError is raised otherwise).

  • target_ds (xarray.Dataset, optional) – Source dataset containing the target coordinate. If its coordinate declares a CF bounds variable, that target-grid bounds variable is included in the output; input bounds are only consumed for the transform and are not copied.

  • per_var_transform (dict, optional) – Mapping of variable name to a transform override.

  • per_var_kwargs (dict, optional) – Mapping of variable name to keyword argument overrides.

  • **kwargs – Additional keyword arguments forwarded to the underlying transform (e.g. t_range, std_bad_max).

Returns:

xarray.Dataset – New dataset with transformed variables on the target coordinate. Each transformed variable has a companion QC variable included.

See also

act.transform.bin_average

Bin-average a single DataArray.

act.transform.interpolate

Interpolate a single DataArray.

act.transform.subsample

Subsample a single DataArray.

Examples

Bin-average every time-dependent variable onto a 30-minute time base. Each variable’s qc_<var> companion is found and honored automatically, and for bin_average the coordinate’s CF bounds variable is picked up as input_bounds. The bounds variable itself is not transformed.

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')

new_ds = act.transform.transform_dataset(
    ds, target=target, dim='time', transform='bin_average', qc_mask=4
)

One transform is rarely right for every variable in a file, which is the usual reason to use this instead of looping yourself. per_var_transform overrides the transform for named variables and per_var_kwargs overrides their keyword arguments – here a categorical present-weather code is subsampled rather than averaged, since averaging two codes yields a value that corresponds to no weather condition.

new_ds = act.transform.transform_dataset(
    ds,
    target=target,
    dim='time',
    transform='bin_average',  # default for everything else
    qc_mask=4,
    per_var_transform={'pwd_pw_code_inst': 'subsample'},
    per_var_kwargs={'wspd_arith_mean': {'std_ind_max': 0.8}},
)

Transform onto another Dataset’s coordinate instead of an explicit target, which is convenient for putting two datastreams on a common time base. target and target_ds are mutually exclusive.

new_ds = act.transform.transform_dataset(
    ds, target_ds=other_ds, dim='time', transform='interpolate'
)