Flat-field correction#

The intensity cross section of a laser beam is usually not flat, but of Gaussian shape or worse. That means that fluorophores closer to the edges of the image will appear dimmer simply because they do not receive so much exciting laser light.

A camera’s pixels may differ in efficiency so that even a homogeneously illuminated sample will not look homogeneous.

Errors as these can corrected for to some extent by flat-field correction. The error is determined by recording a supposedly homogeneous (flat) sample (e.g. a homogeneously fluorescent surface) and can later be removed from other/real experimental data.

Examples

First, load images that show the error, e.g. images of a surface with homogenous fluorescence label.

>>> baseline = 200.  # camera baseline
>>> # Load homogenous sample image sequences
>>> img1 = io.ImageSequence("flat1.tif").open()
>>> img2 = io.ImageSequence("flat2.tif").open()

These can now be used to create the Corrector object:

>>> corr = Corrector([img1, img2], bg=baseline)

With help of corr, other images or even whole image sequences (when using io.ImageSequence to load them) can now be corrected.

>>> img3 = io.ImageSequence("experiment_data.tif").open()
>>> img3_flat = corr(img3)

The brightness values of single molecule data may be corrected as well:

>>> sm_data = io.load("data.h5")
>>> sm_data_flat = corr(sm_data)

Programming reference#

class sdt.flatfield.Corrector(data, bg=0.0, gaussian_fit=True, shape=None, density_weight=False, smooth_sigma=0.0, columns={})[source]#

Flat field correction

This works by multiplying features’ integrated intensities (“mass”) by a position-dependent correction factor. The factor can be calculated from a series of images of a fluorescent surface or from single molecule data.

The factor is calculated in case of a fluorescent surface by

  • Taking the averages of the pixel intensities of the images

  • If requested, doing a 2D Gaussian fit

  • Normalizing, so that the maximum of the Gaussian or of the average image (if on Gaussian fit was performed) equals 1.0

or in the case of single molecule data by fitting a 2D Gaussian to their “mass” values. Single molecule density fluctuations are take into account by weighing data points inversely to their density in the fit.

The “signal” and “mass” of a feature at position (x, y) are then divided by the value of the Gaussian at the positon (x, y) (or the pixel intensity of the image) to yield a corrected value. Also, image data can be corrected analogously in a pixel-by-pixel fashion.

Images (both for deterimnation of the correction and those to be corrected) need to have their background subtracted for this to work properly. This can be done by telling the Corrector object what the background is (or of course, before passing the data to the Corrector.)

Parameters:

  • data (ndarray | Sequence[ndarray] | Sequence[Sequence[ndarray]] | DataFrame | Sequence[DataFrame]) – Collections of images fluorescent surfaces or single molecule data to use for determining the correction function.

  • bg (float | numpy.ndarray) – Background that is subtracted from each image. It is not used on single molecule data. Also sets the :py:attr`bg` attribute.

  • gaussian_fit (bool) – Whether to fit a Gaussian to the averaged image. This is ignored if data is single molecule data.

  • shape (Tuple[int, int] | None) – If data is single molecule data, use this to specify the height and width (in this order) of the image region. It allows for calculation of the correct normalization in case the maximum of the fitted Gaussian does not lie within the region. Furthermore, avg_img and corr_img can be created from the fit.

  • density_weight (bool) – If data is single molecule data, weigh data points inversely to their density for fitting so that areas with higher densities don’t have a higher impact on the result.

  • smooth_sigma (float) – If > 0, smooth the image used for flatfield correction. Only applicable if gaussian_fit=False.

  • columns (Dict) – Override default column names as defined in config.columns. Only applicable of data are single molecule DataFrames. The relevant names are coords and mass. That means, if the DataFrames have coordinate columns “x” and “z” and a mass column “alt_mass”, set columns={"coords": ["x", "z"], "mass": "alt_mass"}.

bg: float | ndarray#

Background to be subtracted from image data.

avg_img: ndarray#

Pixel-wise average image from data argument to __init__().

fit_result: Dict | None#

If a Gaussian fit was done, this holds the result. Otherwise, it is None.

corr_img: ndarray#

Pixel data used for correction of images. Any image to be corrected is divided pixel-wise by corr_img.

fit_amplitude: float#

If a Gaussian fit was done, this holds the maximum of the Gaussian within the image region. See also the shape argument to the constructor.

__call__(data, inplace=False, bg=None, columns={})[source]#

Do brightness correction on features intensities

Parameters:

  • data (DataFrame | Slicerator | ndarray) – data to be processed. If a pandas.Dataframe, correct the “mass” column according to the particle position in the laser beam. Otherwise, pipeline is used to correct raw image data.

  • inplace (bool) – Only has an effect if data is a DataFrame. If True, the feature intensities will be corrected in place.

  • bg (float | ndarray | None) – Background to be subtracted from image data. If None, use the bg attribute. Ignored for single molecule data.

  • columns (dict, optional) – Override default column names as defined in config.columns. Only applicable of data are single molecule DataFrames. The relevant names are coords, signal, and mass. That means, if the DataFrames have coordinate columns “x” and “z” and a mass column “alt_mass”, set columns={"coords": ["x", "z"], "mass": "alt_mass"}. It is also possible to give a list of columns to correct by adding the “corr” key, e.g. columns={"corr": ["mass", "alt_mass"]}.

Returns:

  • If data is a DataFrame and inplace is False, return the

  • corrected frame. If data is raw image data, return corrected

  • images

Return type:

DataFrame | Slicerator | ndarray

get_factors(x, y)[source]#

Get correction factors at positions x, y

Depending on whether gaussian_fit was set to True or False in the constructor, the correction factors for each feature that described by an x and a y coordinate is calculated either from the Gaussian fit or the average image itself.

Parameters:

  • x (ndarray) – x and y coordinates of features

  • y (ndarray) – x and y coordinates of features

Returns:

1D array of correction factors corresponding to the features

Return type:

numpy.ndarray

save(file)[source]#

Save instance to disk

Parameters:

file (str | Path | BinaryIO) – Where to save. If str, the extension “.npz” will be appended if it is not present.

classmethod load(file)[source]#

Load from disk

Parameters:

file (str | Path | BinaryIO) – Where to load from

Returns:

Loaded instance

Return type:

sdt.flatfield.Corrector