scippneutron.smoothing.smooth_relative#

scippneutron.smoothing.smooth_relative(data, *, scale, kernel='gaussian', tail=1e-12, max_grid_points=1000000)[source]#

Smooth sampled data with a kernel of relative width.

The kernel describes a distribution of relative displacements Z, with displaced coordinates given by x' = x * (1 + scale * Z). At the boundaries, the kernel is renormalized over the available finite input domain.

Input that is not geometrically spaced is interpolated to a geometric grid, smoothed, and interpolated back to the original coordinates.

Parameters:

  • data (DataArray) – One-dimensional data to smooth. Must have a positive, strictly increasing dimension coordinate.

  • scale (float | Variable) – Finite, non-negative, dimensionless scale factor for the relative-displacement distribution. May be a real number or a scalar, dimensionless variable. Set to zero to return a copy of the input without smoothing.

  • kernel (smoothing._Kernel (types.str | scippneutron.smoothing._Distribution[str, _Distribution]), default: 'gaussian') – Kernel distribution. The canonical names are 'gaussian', 'boxcar', and 'triangular'. They represent a standard normal distribution, a uniform distribution on [-1, 1], and a symmetric triangular distribution on [-1, 1], respectively. Other aliases are accepted. Alternatively, provide a fully specified distribution with cdf, ppf, and support methods.

  • tail (float, default: 1e-12) – Total probability omitted when truncating a kernel with unbounded support or support reaching the nonpositive coordinate domain. Must be strictly between zero and one.

  • max_grid_points (int, default: 1000000) – Intermediate geometric grids no larger than this are always allowed. Larger grids may be rejected to guard against excessive resampling.

Returns:

DataArray – Smoothed data. Coordinates and units are preserved. Points where no kernel mass falls inside the input domain are NaN; this can occur at the boundaries for one-sided kernels.

Raises:

  • ValueError – If the inputs have invalid values, if a data array has masks, if a string does not identify a supported kernel, or if the required intermediate grid exceeds max_grid_points.

  • scipp.DimensionError – If the input is not one-dimensional or scale is not scalar.

  • scipp.CoordError – If a data array has no dimension coordinate or has a bin-edge coordinate.

  • scipp.DTypeError – If data is binned.

  • scipp.UnitError – If scale is a variable with a non-dimensionless unit.

  • scipp.VariancesError – If the signal or scale has variances.

  • TypeError – If data is not a data array, scale is neither a real number nor a variable, kernel is not a distribution-like object, or max_grid_points is not an integer.

Warns:

UserWarning – If the data contains NaNs or infinities, since smoothing may fall back to a slower method.