act.transform.bin_average#

act.transform.bin_average(data, target, dim, qc=None, qc_mask=None, input_bounds=None, output_bounds=None, weights=None, std_bad_max=inf, std_ind_max=inf, goodfrac_bad_min=0.0, goodfrac_ind_min=0.0)[source]#

Bin-average data onto target coordinate values along dim.

Parameters:

  • data (xarray.DataArray) – Input DataArray.

  • target (xarray.DataArray or numpy.ndarray) – Target coordinate values to average 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.

  • input_bounds (numpy.ndarray, optional) – Shape (ni, 2) array of [start, end] bounds for each input bin. Inferred from midpoints if None.

  • output_bounds (numpy.ndarray, optional) – Shape (nt, 2) array of [start, end] bounds for each output bin. Inferred from midpoints if None. Every bin must have nonzero width, so a single target point requires explicit bounds.

  • weights (numpy.ndarray, optional) – Per-input-sample weights, one per input point along dim. Defaults to ones.

  • std_bad_max (float) – Stdev above which output is flagged QC_BAD_STD.

  • std_ind_max (float) – Stdev above which output is flagged QC_INDETERMINATE_STD.

  • goodfrac_bad_min (float) – Coverage fraction below which output is flagged QC_BAD_GOODFRAC.

  • goodfrac_ind_min (float) – Coverage fraction below which output is flagged QC_INDETERMINATE_GOODFRAC.

Returns:

  • result (xarray.DataArray) – Transformed 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.interpolate

Linear interpolation onto the target coordinate.

act.transform.subsample

Nearest-neighbor selection onto the target coordinate.

act.transform.transform_dataset

Apply a transform to every variable in a Dataset.

Examples

Average 1-minute data onto a 30-minute time base. make_coord builds the target coordinate, and the returned QC variable describes each output bin.

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.bin_average(ds['temp_mean'], target, dim='time')

Honor the input QC variable so flagged samples are excluded from the average. qc_mask is a bitmask, not a bit number, so bit 3 is 4. Output bins that lost input are flagged QC_SOME_BAD_INPUTS.

from act.transform.constants import QC_SOME_BAD_INPUTS

result, result_qc = act.transform.bin_average(
    ds['temp_mean'], target, dim='time', qc=ds['qc_temp_mean'], qc_mask=4
)
affected = (result_qc.values & QC_SOME_BAD_INPUTS).astype(bool)

Use the bin bounds declared by the file rather than bounds inferred from the coordinate midpoints, so samples straddling an output bin edge are split across both bins in proportion to their overlap.

result, result_qc = act.transform.bin_average(
    ds['temp_mean'], target, dim='time', input_bounds=ds['time_bounds'].values
)

Flag output bins whose input was too variable, or too sparse, to be represented by a single mean. Both threshold families default to a no-op – the std_* thresholds to infinity and the goodfrac_* thresholds to zero – so their bits only appear once a threshold is set.

from act.transform.constants import QC_BAD_STD, QC_INDETERMINATE_STD

result, result_qc = act.transform.bin_average(
    ds['wspd_arith_mean'],
    target,
    dim='time',
    std_ind_max=0.8,  # within-bin stdev above this -> QC_INDETERMINATE_STD
    std_bad_max=1.5,  # ... and above this -> QC_BAD_STD
    goodfrac_ind_min=0.99,  # good coverage below this -> QC_INDETERMINATE_GOODFRAC
)
gusty = (result_qc.values & QC_INDETERMINATE_STD).astype(bool)