Toolbox: The Redding Lab analysis package

The point_fitting module

The point_fitting module contains functions used in measuring single particles. for more info see the fitting guassians or the finding local maxima tutorials.

point_fitting.two_d_gaussian(span, amplitude, mu_x, mu_y, sigma_x, sigma_y, theta, offset)

Two dimensional Gaussian function, specifically for use with point-fitting functions.

Parameters:
  • span – tuple containing arrays for the range of the gaussian function in x and y.
  • amplitude – Height of the gaussian
  • mu_x – mean in x
  • mu_y – mean in y
  • sigma_x – standard deviation in x
  • sigma_y – standard deviation in y
  • theta – Angular offset of the coordinate axis, in radians counterclockwise from x axis.
  • offset – size of the noise floor
Returns:

1D array of values for the function across the range defined by span

Example:
>>> import numpy as np
>>> from toolbox.point_fitting import two_d_gaussian
>>> x,y = np.linspace(0,5,6), np.linspace(0,5,6)
>>> two_d_gaussian((x,y),1,2.5,2.5,1,1,0,.2)
array([0.20193045, 0.30539922, 0.97880078,
    0.97880078, 0.30539922,0.20193045])
point_fitting.find_maxima(image, size, threshold_method='threshold_otsu')

Locates maxima in an image. See here

Parameters:
  • image – 2-dimensional image array.
  • size – int, size of the maxima and minimum filters used
  • threshold_method – string, type of thresholding filter used. Accepts any filter in the skimmage.filters module. Default is “otsu’s method”
Returns:

1D array of [(x,y),…] defining the locations of each maximum

Example:
>>> import toolbox.point_fitting as pt
>>> import toolbox.testdata as test
>>> im = test.single_max()
>>> print(pt.find_maxima(im,10))
[(17, 14)]
point_fitting.fit_routine(Image, x, y, bbox)

Fits a 2D gaussian function to 2D image array. “x”, “y”, and “bbox” define an ROI fit by two_d_gaussian using scipy.optimaize.curve_fit

Parameters:
  • Image – 2D array containing ROI to be fit
  • x – center of ROI in x
  • x – center of ROI in y
  • bbox – side-length of the ROI. if even, rounds up to next odd integer
Returns:

1D array of optimal parameters from gaussian fit.

Returns:

None

if ROI falls (partially or otherwise) outside Image. Or, if curve_fit raises RuntimeError

Example:
>>> import toolbox.point_fitting as pt
>>> import toolbox.testdata as test
>>> im = test.single_max()
>>> x,y = pt.find_maxima(im,10)[0]
>>> fit = pt.fit_routine(im, x, y, 10)
>>> print(Fit)
array([ 1.01462278, 16.74464408, 14.28216362,  0.78958828,  1.14957256,
2.25853845,  0.11157521])

The alignment module

The alignment module contains functions used in aligning two channel data. See our walkthrough of the alignment module’s usage.

alignment.FD_rule_bins(data)

Finds the optimal spacing of histogram bins based on the Freedman-Diaconis rule. https://en.wikipedia.org/wiki/Freedman%E2%80%93Diaconis_rule

Parameters:

data – 1D array of data points

Returns:

1D array of bin edges. passes directly to numpy.histogram or matplotlib.pyplot.hist

Example:
>>> import numpy as np
>>> from toolbox.alignment import FD_rule_bins
>>> x = np.random.normal(size=100)
>>> FD_rule_bins(x)
array([-2.25503346, -1.75181888, -1.2486043 , -0.74538972, -0.24217514,
        0.26103944,  0.76425402,  1.2674686 ,  1.77068318,  2.27389776,
        2.77711234])
alignment.scrub_outliers(data)
Removes outliers from data. Works in two steps:
  • First, data is binned using FD_rule_bins and only the most highly populated bins are retained
  • Second, any datum more than two standard deviations away from the mean are filtered out
Parameters:

data – 1D array or list of data points

Returns:

Filtered result, 1D array

Example:
>>> import numpy as np
>>> from toolbox.alignment import scrub_outliers
>>> x = np.concatenate((np.random.normal(size=200),np.random.uniform(-10,10,size=20)))
>>> scrubed_x = scrub_outliers(x)
>>> len(x),len(scrubed_x)
(220, 179)
>>> import matplotlib.pyplot as plt
>>> from toolbox.alignment import FD_rule_bins
>>> plt.figure()
>>> plt.hist(x,FD_rule_bins(x),fc = "m")
>>> plt.hist(scrubed_x,FD_rule_bins(x), fc = "g")
>>> plt.show()
alignment.im_split(Image, splitstyle='hsplit')

Image passed to this function is split into two channels based on “splitstyle”. *note* micromanager images and numpy arrays are indexed opposite of one another.

Parameters:
  • Image – 2D image array
  • splitstyle – str, accepts “hsplit”, “vsplit”. Default is “hsplit”
Returns:

The two subarrays of Image split along specified axis.

Example:
>>> from toolbox.alignment import im_split
>>> import toolbox.testdata as test
>>> im = test.image_stack()[0]
>>> ch1,ch2 = im_split(im)
>>> ch1.shape,ch2.shape
((512, 256), (512, 256))
>>> ch1,ch2 = im_split(im,"vsplit")
>>> ch1.shape,ch2.shape
((256, 512), (256, 512))
alignment.get_offset_distribution(Image, bbox=9, splitstyle='hsplit', fsize=10)
This function in order:
  • splits the image into channels
  • locates and fits all of the points in each channel
  • pairs up associated points from each channel, uses cDKTree
  • and determines their offset
Parameters:
  • Image – 2D image array
  • bbox – int, passed to point_fitting.fit_routine, size of ROI around each point to apply gaussian fit. Default is 9.
  • splitstyle – string, passed to im_split; accepts “hsplit”, “vsplit”. Default is “hsplit”
  • fsize – int, passed to point_fitting.find_maxima, size of average filters used in maxima determination. Default is 10.
Returns:

Two lists containing all of the measured x- and y- offsets

Example:
>>> from toolbox.alignment import get_offset_distribution
>>> import toolbox.testdata as test
>>> import matplotlib.pyplot as plt
>>> import numpy as np
>>> im = test.image_stack()[0]
>>> x_dist,y_dist = get_offset_distribution(im)
>>> print(np.mean(x_dist),np.mean(y_dist))
-1.9008888233326608 -2.042675546813981
alignment.find_global_offset(im_list, bbox=9, splitstyle='hsplit', fsize=10)

This function finds the optimal x-offset and y-offset of the data using scrub_outliers to filter the data collected from get_offset_distribution. The filtered data are then fit using scipy.stats.skewnorm

Parameters:
  • im_list – 1D list of image arrays to be used in determination of the offset
  • bbox – int, passed to point_fitting.fit_routine, size of ROI around each point to apply gaussian fit. Default is 9.
  • splitstyle – string, passed to im_split; accepts “hsplit”, “vsplit”. Default is “hsplit”
  • fsize – int, passed to point_fitting.find_maxima, size of average filters used in maxima determination. Default is 10.
Returns:

Mean x- and y-offset values.

Example:
>>> from toolbox.alignment import find_global_offset
>>> import toolbox.testdata as test
>>> im = test.image_stack()
>>> print(find_global_offset(im))
(5.624042070667237, -2.651128775580636)
alignment.plot_assigned_maxima(Image, splitstyle='hsplit', fsize=10)

This function spits out a matplotlib plot with lines drawn between each of the assigned pairs of maxima. The purpose of this function is more for a sanity check than anything useful.

Parameters:
  • Image – 2D image array
  • splitstyle – string, passed to im_split; accepts “hsplit”, “vsplit”. Default is “hsplit”
  • fsize – int, passed to point_fitting.find_maxima, size of average filters used in maxima determination. Default is 10.
Returns:

fancy plot of assigned points.

Example:
>>> from toolbox.alignment import plot_assigned_maxima
>>> import toolbox.testdata as test
>>> im = test.image_stack()[0]
>>> plot_assigned_maxima(im)
alignment.align_by_offset(Image, shift_x, shift_y, splitstyle='hsplit', shift_channel=1)

This function shifts one channel of the array based supplied offset values. Retains the single image structure.

Parameters:
  • Image – 2D image array
  • shift_x – float, offset in x
  • shift_y – float, offset in y
  • splitstyle – string, passed to im_split; accepts “hsplit”, “vsplit”. Default is “hsplit”
  • shift_channel – int, which channel to shift by offsets, default is channel 1.
Returns:

2D image array of aligned image

Example:
>>> from toolbox.alignment import find_global_offset, align_by_offset
>>> import toolbox.testdata as test
>>> import matplotlib.pyplot as plt
>>> im = test.image_stack()
>>> dx,dy = find_global_offset(im)
>>> new_image = align_by_offset(im[0],dx,dy)
>>> plt.imshow(new_image),plt.show()
alignment.overlay(Image, rot=True, invert=False)

Overlays the two channels derived from Image. Converts Image to an 8-bit RGB array, with one channel colored magenta and the other green.

Parameters:
  • Image – 2D image array
  • rot – bool, if True, image is rotated 90 degrees
  • invert – bool, if True, inverts the channel color assignment.
Returns:

8-bit RGB image

Example:
>>> from toolbox.alignment import overlay
>>> import toolbox.testdata as test
>>> import matplotlib.pyplot as plt
>>> im = test.image_stack()
>>> dx,dy = find_global_offset(im)
>>> aligned_image = align_by_offset(im[0],dx,dy)
>>> overlayed = overlay(aligned_image)
>>> plt.imshow(overlayed),plt.show()