Brightness analysis#

This is a collection of tools to analyze the brightness of fluorophores. It offers

  • The from_raw_image() function which may be used to calculate the brightness of single molecules by extracting the information directly from the raw image data.

  • The Distribution class, with which one can determine the brightness distribution of fluorophores via kernel density estimation.

Examples

To determine single molecule brightness using from_raw_image(), one needs the raw image data and localization data of molecules (which can be determined from the image date e.g. using functionality from the sdt.loc module):

>>> loc = sdt.io.load("localizations.h5")  # Load single molecule localizations
>>> with io.ImageSequence("images.tif") as img_seq:
...     from_raw_image(loc, img_seq, radius=4)

The last line updates the loc DataFrame with the brightness data extracted from the raw image.

The distribution of the brightness of single molecules can be calculated by means of the Distribution class:

>>> loc = [sdt.io.load(f) for f in glob.glob("*.h5")]  # Load sm data
>>> cam_eff = 300 / 15.7  # number of camera counts per photon
>>> bdist = Distribution(loc, cam_eff)
>>> bdist.mean()
314.1592653589793
>>> bdist.std()
31.41592653589793
>>> bdist.plot()

Programming reference#

sdt.brightness.from_raw_image(positions, frames, radius, bg_frame=2, bg_estimator='mean', columns={}, engine='numba', mask='square')[source]#

Determine particle brightness by counting pixel values

Around each localization, pixel values are summed up (see the mask parameter) to determine the brightness (mass). Additionally, local background is determined by calculating the brightness (see bg_estimator parameter in a frame (again, see mask parameter) around this box, where all pixels belonging to any localization are excluded. This background is subtracted from the signal brightness.

Parameters:

  • positions (pandas.DataFrame) – Localization data. “signal”, “mass”, “bg”, and “bg_dev” columns are added and/or replaced directly in this object.

  • frames (iterable of numpy.ndarrays) – Raw image data

  • radius (int) – Half width of the box in which pixel values are summed up. See mask parameter for details.

  • bg_frame (int or infinity, optional) – Width of frame (in pixels) around a feature for background determination. If infinity, background is calculated globally from all pixels that are not part of any feature. Defaults to 2.

  • bg_estimator ({"mean", "median"} or numpy ufunc, optional) – How to determine the background from the background pixels. “mean” will use numpy.mean() and “median” will use numpy.median(). If a function is given (which takes the pixel data as arguments and returns a scalar), apply this to the pixels. Defaults to “mean”.

  • mask ({"square", "circle"} or (array-like, array-like), optional) – If “square”, sum pixels in a 2 * radius + 1 sized square around each localization as the brightness and use bg_estimator in a frame of bg_frame width around it to determine the local background, which is subtracted from the brightness. If “circle”, sum pixels in a 2 * radius + 1 sized circle (a CircleMask with radius radius and extra=0.5 is used) around each localization and get the background from an annulus of width bg_frame. One can also pass a tuple (feat_mask, bg_mask) of boolean arrays for brightness and background detection. In this case, radius and bg_frame are ignored. If bg_mask is None, calculate background globally (per frame) from all pixels that are not part of any feature. In all cases, all pixels belonging to any signal are automatically excluded from the background detection. Defaults to “square”.

  • columns (dict, optional) – Override default column names as defined in config.columns. Relevant names are coords, time, mass, signal, bg, bg_dev. This means, if your DataFrame has coordinate columns “x” and “z” and the time column “alt_frame”, set columns={"coords": ["x", "z"], "time": "alt_frame"}.

  • engine ({"numba", "python"}, optional) – Numba is faster, but only supports 2D data and mean or median bg_estimator. If numba cannot be used, automatically fall back to pure python, which support arbitray dimensions and bg_estimator functions. Defaults to “numba”.

class sdt.brightness.Distribution(data, abscissa=None, bw=2.0, cam_eff=1.0, kern_width=5.0, engine='numba', columns={})[source]#

Brightness distribution of fluorescent signals

Given a list of peak masses (integrated intensities), calculate the masses’ probability density function.

This is a Gaussian KDE with variable bandwith. See the bw parameter documentation for details.

Parameters:

  • data (list of pandas.DataFrame or pandas.DataFrame or numpy.ndarray) – If a DataFrame is given, extract the masses from the “mass” column. A list of DataFrames will be concatenated. Brightness values can also be passed as an one-dimensional ndarray.

  • abscissa (None or numpy.ndarray or float) – The abscissa (x axis) values for the calculated distribution. Providing a float is equivalent to numpy.arange(abscissa + 1). If None, automatically choose something appropriate based on the values of data and the bandwidth.

  • bw (float, optional) – Bandwidth factor. The bandwidth for each data point d is calculated as bw * np.sqrt(d). Defaults to 2.

  • cam_eff (float, optional) – Camera efficiency, i. e. how many camera counts correspond to one photon. The brightness data will be divided by this number. Defaults to 1.

  • kern_width (float, optional) – Calculate kernels only in the range of +/- kern_width times the bandwidth to save computation time. Defaults to 5.

  • engine ({"numba", "python"}, optional) – Whether to use the faster numba-based implementation or the slower pure python one. Defaults to “numba”.

  • columns (dict, optional) – Override default column names as defined in config.columns. The only relevant name is mass.

graph#

numpy.ndarray of shape (2, n); First row is the abscissa, second row is the ordinate of the normalized distribution function.

num_data#

Number of data points (single molecules) used to create the distribution.

mean()[source]#

Mean

Returns:

Mean (1st moment) of the distribution

Return type:

float

std()[source]#

Standard deviation

Returns:

Standard deviation (square root of the 2nd central moment) of the distribution

Return type:

float

most_probable()[source]#

Most probable value (mode)

Returns:

Most probable brightness (brightness value were the distribution function has its maximum)

Return type:

float

mode()#

Most probable value (mode)

Returns:

Most probable brightness (brightness value were the distribution function has its maximum)

Return type:

float

plot(ax=None, label=None)[source]#

Plot the distribution function graph

Parameters:

  • ax (matplotlib.axes.Axes or None, optional) – Axes to draw on. If None, use matplotlib.gca(). Defaults to None.

  • label (str or None, optional) – Label for the legend. Defaults to None