cdiutils.simulation.add_noise#

cdiutils.simulation.add_noise(data, gaussian_mean=0.0, gaussian_std=0.0, poisson_background=None, poisson_statistics=False, scale=1.0)[source]#

Add noise to data with configurable Gaussian and Poisson components.

This general-purpose function allows flexible noise modelling by combining Gaussian and Poisson noise sources. It can be called multiple times to build up complex noise models from different physical sources (dark current, readout noise, air scattering, fluorescence, etc.).

Parameters:

  • data (ndarray) – Input data array (any shape).

  • gaussian_mean (float) – Mean of Gaussian noise to add. Default is 0.0.

  • gaussian_std (float) – Standard deviation of Gaussian noise. Default is 0.0.

  • poisson_background (ndarray | float | None) –

    Background for Poisson sampling. Can be: - None: no Poisson background added - float: uniform background value - np.ndarray: spatially-varying background (must match

    data shape)

    Default is None.

  • poisson_statistics (bool) – If True, apply Poisson statistics to the data itself (photon counting). Default is False.

  • scale (float) – Multiplicative factor applied to data before adding noise. Useful for unit conversions or intensity scaling. Default is 1.0.

Returns:

Data with added noise, same shape as input. Values are converted to float64 for accumulation and clipped to non-negative.

Raises:

  • TypeError – If data is not a numpy array or if poisson_background has invalid type.

  • ValueError – If gaussian_std is negative, or if poisson_background array shape doesn’t match data shape, or if scale is not positive, or if background values are negative.

Return type:

ndarray

Example

>>> # add dark current (Gaussian thermal noise)
>>> noisy = add_noise(
...     data,
...     gaussian_mean=0.5,
...     gaussian_std=0.75,
... )
>>>
>>> # add readout noise (Gaussian electronics noise)
>>> noisy = add_noise(noisy, gaussian_std=0.5)
>>>
>>> # add uniform air scattering (Poisson background)
>>> noisy = add_noise(noisy, poisson_background=2.0)
>>>
>>> # add spatially-varying air scattering
>>> beam_profile = create_beam_profile(data.shape)
>>> noisy = add_noise(
...     noisy,
...     poisson_background=beam_profile,
... )
>>>
>>> # apply Poisson statistics to signal
>>> noisy = add_noise(data, poisson_statistics=True)
>>>
>>> # scale data and add noise
>>> noisy = add_noise(
...     data,
...     scale=1.5,
...     gaussian_std=1.0,
... )
>>>
>>> # combine multiple sources in one call
>>> noisy = add_noise(
...     data,
...     gaussian_mean=0.5,
...     gaussian_std=0.75,
...     poisson_background=2.0,
...     scale=1.2,
... )

Notes

This function can be called multiple times sequentially to build up complex noise models. Each call adds additional noise to the input data. The order matters when combining Poisson statistics with other noise sources.

For frame-by-frame noise in rocking curves, use this function within a loop or use the BCDISimulator class which handles realistic detector simulation automatically.