bstore package

Submodules

bstore.batch module

class bstore.batch.BatchProcessor

Bases: object

Batch processor metaclass. All batch processors must inherit this.

datasetList
go()
class bstore.batch.CSVBatchProcessor(inputDirectory, pipeline, useSameFolder=False, outputDirectory='processed_data', suffix='.dat', delimiter=', ')

Bases: bstore.batch.BatchProcessor

Batch processing and saving for SMLM data in CSV files.

datasetList

list of Path – List of Path objects pointing to all the identified localization files in a directory or a directory tree.

pipeLine

list of Processors – List of Processor objects to process the data.

datasetList

A list of all pathlib Path objects to the datasets to process.

go(processedFlag='processed')

Initiate batch processing on all the files.

Parameters:processedFlag (str) – The string to append to the input filenames for naming output files. Files will have the same name as the inputs with this string appended to the end. For example, an input of “Cells_Results.dat” will produce an output named “Cells_Results_processed.dat”.
class bstore.batch.HDFBatchProcessor(inputDatastore, pipeline, outputDirectory='processed_data', searchString='Localizations')

Bases: bstore.batch.BatchProcessor

Automatic processing of localizations stored in a HDF datastore.

datasetList

A list of all datasets to process.

go()
exception bstore.batch.ProcessedFolderExists(value)

Bases: Exception

Attempting to write processed output to an existing folder.

bstore.config module

bstore.database module

class bstore.database.Dataset(datasetIDs={})

Bases: object

Metaclass for a Dataset. Use this to create new Datasets.

Parameters:
  • data – The actual data held by the dataset.
  • datasetIDs (dict) – The ID fields and their values that identify the datset inside the datastore.
data

The actual data held by the dataset.

datasetIDs

dict – The ID fields and their values that identify the datset inside the datastore.

attributeOf
data
datasetIDs
datasetType
get()
put()
readFromFile()
class bstore.database.DatasetID(prefix, acqID, datasetType, attributeOf, channelID, dateID, posID, sliceID, replicateID)

Bases: tuple

Dataset IDs used by the HDFDatastore

prefix = The descriptive name given to the dataset by the user. acqID = Acquisition ID number; an integer. datasetType = The type specified by datasetType. attributeOf = The type of dataset that this one describes. channelID = (optional) String for the channel (color). dateID = (optional) The date the dataset was acquired. posID = (optional) One or two-tuple of integers. sliceID = (optional) Single integer of the axial slice. replicateID = (optional) Integer specifying a replicate expierment.

acqID

Alias for field number 1

attributeOf

Alias for field number 3

channelID

Alias for field number 4

datasetType

Alias for field number 2

dateID

Alias for field number 5

posID

Alias for field number 6

prefix

Alias for field number 0

replicateID

Alias for field number 8

sliceID

Alias for field number 7

exception bstore.database.DatasetIDError(value)

Bases: Exception

Error raised when a bad or missing dataset IDs are supplied.

exception bstore.database.DatasetTypeError(value)

Bases: Exception

Error raised when a bad or unregistered DatasetType is used.

class bstore.database.Datastore(dsName)

Bases: object

Metaclass representing the datastore structure.

Parameters:dsName (str or Path) – The name of the datastore file.
build()

Create new datastore from a list of datasets.

get()

Retrieve dataset from the datastore.

put()

Place a dataset into the datastore.

query()

Return a list of datasets in the datastore.

exception bstore.database.FileNotLocked(value)

Bases: Exception

Raised when trying to write to an unlocked file.

exception bstore.database.HDF5KeyDoesNotExist(value)

Bases: Exception

Attempting to get a dataset that doesn’t exist.

exception bstore.database.HDF5KeyExists(value)

Bases: Exception

Attempting to write to an existing key in the datastore.

class bstore.database.HDFDatastore(dsName, widefieldPixelSize=None)

Bases: bstore.database.Datastore

A HDFDatastore structure for managing SMLM data.

Parameters:
  • dsName (str or Path) – The name of the datastore file.
  • widefieldPixelSize (2-tuple of float or None) – The x- and y-size of a widefield pixel in microns. This information is used to write attributes to the widefield image for opening with other software libraries, such as the HDF5 Plugin for ImageJ and FIJI. Setting it will override all metadata information.
widefieldPixelSize

2-tuple of float or None – The x- and y-size of a widefield pixel in microns. This informationis used to write attributes to the widefield image for opening with other software libraries.

Notes

The only HDF attribute currently written directly to the image data, i.e. to the HDF dataset (not group) is:

element_size_um

which is required for opening images directly from the HDF file by the HDF5 Plugin for ImageJ and FIJI[1]_.

References

[1]http://lmb.informatik.uni-freiburg.de/resources/opensource/imagej_plugins/hdf5.html
attrPrefix
build(*args, **kwargs)
Parameters:self (HDFDatastore instance) –
get(dsID)

Returns a Dataset from the datastore.

Parameters:dsID (DatasetID) – A namedtuple belonging to the HDFDatastore class.
Returns:dataset – A complete dataset.
Return type:Dataset
put(*args, **kwargs)
Parameters:self (HDFDatastore instance) –
query(datasetType='Localizations')

Returns a list of datasets inside this datastore.

Parameters:datasetType (str) – The type of data to search for..
Returns:dsIDs – All of the dataset ids matching the datasetType
Return type:list of Dataset
exception bstore.database.LocResultsDoNotExist(value)

Bases: Exception

Attempting to attach locMetadata to non-existing locResults.

exception bstore.database.SearchDirectoryDoesNotExist(value)

Bases: Exception

The search directory for a datastore build does not exist.

bstore.database.hdfLockCheck(writeFunc)

Checks whether a HDF file is locked for writing; raises an error if not.

Place this decorator before functions like build() and put() that require a file to be locked before writing data to the file. This prevents multiple HDFDatastore instances from writing to the same file at the same time.

Parameters:writeFunc (function) – The function call of the Datastore to be called.
Returns:lockCheck
Return type:function
bstore.database.pp = <pprint.PrettyPrinter object>

bstore.multiprocessors module

Process multiple inputs from a SMLM experiment.

A multiprocessor is similar to a processor except that it takes more than just one DataFrame as its input. Multiprocessors can, for example, take multiple DataFrames, such as localizations in multiple channels, widefield images, etc.

class bstore.multiprocessors.AlignToWidefield(coordCols=['x', 'y'], pixelSize=108.0, upsampleFactor=5)

Bases: object

Aligns localizations to a corresponding widefield image.

AlignToWidefield is a multiprocessor that estimates by how much a set of localizations is shifted relative to a corresponding widefield image. It works by computing a 2D histogram from the localizations and cross-correlating it with an upsampled version of the widefield image. The result is a two-element tuple of the estimated shifts in units of the x- and y-localization coordinates.

The cross-correlation is performed using fftconvolve from scipy.signal; this means it is an estimate of the global offset between the 2D histogram and the widefield image. Small, field- dependent deviations between the localizations and widefield image should therefore be expected.

Parameters:
  • coordCols (list of str) – The x- and y-coordinate column labels in the format [‘x’, ‘y’].
  • pixelSize (float) – The linear size of a pixel in the same units as the localizations.
  • upsampleFactor (int) – The amount of upsampling to perform on the widefield image. For example, a factor of 5 means 1 pixel is transformed into 5.
coordCols

list of str – The x- and y-coordinate column labels.

pixelSize

float – The linear size of a pixel in the same units as the localizations.

upsampleFactor

int – The amount of upsampling to perform on the widefield image. For example, a factor of 5 means 1 pixel is transformed into 5.

class bstore.multiprocessors.EstimatePhotons(spotMaskRadius=4, bgMaskSize=11, aduOffset=100, cameraGain=0.5, bgCorrect=True)

Bases: object

Estimate the number of photons coming from regions of an image.

EstimatePhotons performs a (optionally) background-corrected estimate of the number of photons collected from a region of an image. It is useful for estimating photon counts from individual fluorescent spots with approximately circular symmetry.

Parameters:
  • spotMaskRadius (int) – The size of the circular mask in pixels.
  • bgMaskSize (int) – The length of a side of the square background mask in pixels.
  • aduOffset (int) – The camera-specific offset applied to each pixel. Units are ADU.
  • cameraGain (float) – The camera-specific gain. Units are ADU per photoelectron.
spotMaskRadius

int – The size of the circular mask in pixels.

bgMaskSize

int – The length of a side of the square background mask in pixels. This is ignored if bgCorrect is False.

aduOffset

int – The camera-specific offset applied to each pixel. Units are ADU.

cameraGain

float – The camera-specific gain. Units are ADU per photoelectron.

bgCorrect

bool – Determines whether the background will be estimated and corrected for.

Notes

Due to the nature of computing masks of discrete arrays, this class works best when spotMaskRadius and bgMaskSize are even and odd, respectively.

The background is estimated by computing the median photon count over all the pixels in a square window centered on the input regions and excluding pixels inside the spot mask. The background size, bgMaskSize, should therefore be greater than twice the spotMaskRadius.

class bstore.multiprocessors.OverlayClusters(annotateCol=None, clusterIDCol='cluster_id', coordCols=['x', 'y'], coordCenterCols=['x_center', 'y_center'], filterCol=None, pixelSize=108, showAll=False, xShift=0, yShift=0, zoomSize=21)

Bases: object

Produces overlays of clustered localizations on widefield images.

The OverlayClusters processor is used to overlay clustered localizations onto widefield images. It shows both the full image and a zoomed region around the current cluster at the same time. The user can interactively step through each cluster with the keyboard.

It also allows for annotating clusters by labeling clusters with a numeric ID between 1 and 9 or a True/False value, allowing users to perform manual filtering or classification, for example.

Parameters:
  • annotateCol (str) – Name of the column in stats for deciding whether a cluster is retained for analysis.
  • clusterIDCol (str) – Name of the column containing the cluster id number.
  • coordCols (list of str) – The x- and y-coordinate column labels in the format [‘x’, ‘y’].
  • coordCenterCols (list of str) – The x- and y-center column labels. This should be not be changed unless you provide your own stats DataFrame when calling this class and the labels are different than the default.
  • filterCol (str) – The name of a column containing boolean data in the ‘stats’ DataFrame. Only rows with a value of True in this column will be displayed.
  • pixelSize (float) – The physical size of a pixel. For converting the localization units to pixels.
  • xShift (float) – Offset to apply to the localizations and clusters in x.
  • yShift (float) – Offset to apply to the localizations and clusters in y.
  • zoomSize (int) – The linear size of the zoomed region around a cluster in pixels.
annotateCol

str – Name of the column in stats for deciding whether a cluster is retained for analysis.

clusterIDCol

str – Name of the column containing the cluster id number.

coordCols

list of str – The x- and y-coordinate column labels.

coordCenterCols

list of str – The x- and y-center column labels. This should be not be changed unless you provide your own stats DataFrame when calling this class and the labels are different than the default.

currentCluster

int – The index of the cluster being analyzed.

filterCol

str – The name of a column containing boolean data in the ‘stats’ DataFrame. Only rows with a value of True in this column will be displayed.

pixelSize

float – The physical size of a pixel. For converting the localization units to pixels.

showAll

boolean – If False, only localizations for the current cluster will be displayed. If True, all localizations will be displayed, though the current cluster will appear in a different color.

xShift

float – Offset to apply to the localizations and clusters in x.

yShift

float – Offset to apply to the localizations and clusters in y.

zoomSize

int – The linear size of the zoomed region around a cluster in pixels.

bstore.parsers module

exception bstore.parsers.DatasetTypeError(value)

Bases: Exception

Error raised when a bad datasetTypeName is passed to Parser.

class bstore.parsers.FormatMap(init_dict=None)

Bases: dict

Two-way map for mapping one localization file format to another.

FormatMap subclasses dict and acts like a two-way mapping between key-value pairs, unlike dict which provides only a one-way relationship. In the case where a key is missing, the dict returns the input key. This functionality greatly assists in converting header files for which no translation between column names is defined.

To use this class, simply pass a dict to the FormatMap’s constructor. Alternatively, create a FormatMap, which creates an empty dict. Then add fields as you wish.

Parameters:init_dict (dict) – The dictionary to convert to a two-way mapping.

References

[1] http://stackoverflow.com/questions/1456373/two-way-reverse-map

exception bstore.parsers.ParseFilenameFailure(value)

Bases: Exception

Raised when Parser fails to parser a filename.

class bstore.parsers.Parser

Bases: object

Translates SMLM files to machine-readable data structures.

dataset

Dataset – A Dataset object for insertion into a B-Store Datastore.

requiresConfig

bool – Does parser require configuration before use? This is primarily used by the GUI to determine whether the parser has attributes that are set by its __init__() method or must be set before parsing files.

dataset
parseFilename()

Parses a file for conversion to a Dataset.

requiresConfig
exception bstore.parsers.ParserNotInitializedError(value)

Bases: Exception

Raised when Parser is requested to return data but is not initialized.

class bstore.parsers.PositionParser(positionIDs={0: 'prefix', 1: 'acqID'}, sep='_')

Bases: bstore.parsers.Parser

Reads a filename whose dataset IDs are determined by their positions.

Parameters:
  • positionIDs (dict) – Integer/string pairs denoting the position in the filename (starting from zero on the left) and the ID field at that position. If a position should be skipped, set its value to None.
  • sep (str) – The character (or characters) that separate the different fields in the filename.
requiresConfig

bool – Does parser require configuration before use?

positionIDs

dict – Integer/string pairs denoting the position in the filename (starting from zero on the left) and the ID field at that position. If a position should be skipped, set its value to None.

sep

str – The character (or characters) that separate the different fields in the filename.

gui(parent)

Configure the parser for the GUI interface.

Parameters:parent (tkinter.Tk object) – The parent window for this dialog.
parseFilename(filename, datasetType='Localizations', **kwargs)

Converts a filename into a Dataset.

Parameters:
  • filename (str or Path) – A string or pathlib Path object containing the dataset’s filename.
  • datasetType (str) – The type of the dataset being parsed. This tells the Parser how to interpret the data.
requiresConfig
class bstore.parsers.SimpleParser

Bases: bstore.parsers.Parser

A simple parser for extracting acquisition information.

The SimpleParser converts files of the format prefix_acqID.* into Datasets for insertion into a datastore. * represents filename extensions like .csv, .json, and .tif.

requiresConfig

bool – Does parser require configuration before use?

parseFilename(filename, datasetType='Localizations', **kwargs)

Converts a filename into a Dataset.

Parameters:
  • filename (str or Path) – A string or pathlib Path object containing the dataset’s filename.
  • datasetType (str) – The type of the dataset being parsed. This tells the Parser how to interpret the data.
requiresConfig

bstore.processors module

class bstore.processors.AddColumn(columnName, defaultValue=True)

Bases: object

Adds a column to a DataFrame.

AddColumn adds a column to a DataFrame and initializes every row to the same value.

Parameters:
  • columnName (str) – The name of the new column.
  • defaultValue (mixed datatype) – The default value to assign to each row of the new column.
columnName

str – The name of the new column.

defaultValue

mixed datatype – The default value to assign to each row of the new column.

class bstore.processors.CalibrateAstigmatism(interactiveSearch=True, coordCols=['x', 'y'], sigmaCols=['sigma_x', 'sigma_y'], zCol='z', startz=None, stopz=None, astigmatismComputer=None, wobbleComputer=None)

Bases: bstore.processors.SelectLocalizations

Computes calibration curves for astigmatic imaging from bead stacks.

Parameters:
  • interactiveSearch (bool) – Determines whether the user will interactively find fiducials. Setting this to False means that fiducials are found automatically, although this is not always reliable.
  • coordCols (list of str) – List of strings identifying the x- and y-coordinate column names in that order.
  • sigmaCols (list of str) – List of strings identifying the column names containing the PSF widths in x and y.
  • zCol (str) – Name of the column identifying the z-coordinate values.
  • astigmatismComputer (ComputeTrajectories) – Algorithm for computing astigmatic calibration curves.
  • wobbleComputer (ComputeTrajectories) – Algorithm for computing wobble calibration curves.
interactiveSearch

bool – Determines whether the user will interactively find fiducials. Setting this to False means that fiducials are found automatically, although this is not always reliable.

astigmatismComputer

AstigComputer – Algorithm for computing astigmatic calibration curves.

calibrationCurves

func, func – The calibration curves for astigmatic 3D imaging. The first element contains the PSF width in x as a function of z and the second contains the width in y as a function of z.

wobbleCurves

func, func – The wobble curves for astigmatic 3D imaging. These map the PSF centroid positions as a function of z. See Ref. 1 for more information.

References

1. Carlini, et al., “Correction of a Depth-Dependent Lateral Distortion in 3D Super-Resolution Imaging,” PLoS One 10(11):e0142949 (2015).

class bstore.processors.CleanUp

Bases: object

Performs regular clean up routines on imported data.

The cleanup processor encapsulates a few common steps that are performed on imported datasets. Currently, these steps are:

  1. Convert rows containing strings to numeric data types
  2. Drop rows containing strings that cannot be parsed to numeric types
  3. Drop rows with Inf’s and NaN’s
class bstore.processors.Cluster(minSamples=50, eps=20, coordCols=['x', 'y'])

Bases: object

Clusters the localizations into spatial clusters.

Parameters:
  • minSamples (int) – Minimum number of samples within one neighborhood radius.
  • eps (float) – The neighborhood radius defining a cluster.
  • coordCols (list of str) – The columns of the data to be clustered in the format [‘x’, ‘y’].
class bstore.processors.ComputeClusterStats(idLabel='cluster_id', coordCols=['x', 'y'], zCoord='z', statsFunctions=None)

Bases: object

Computes statistics for clusters of localizations.

Parameters:
  • idLabel (str) – The column name containing cluster ID’s.
  • coordCols (list of string) – A list containing the column names containing the transverse localization coordinates.
  • zCoord (str) – The column name of the axial coordinate.
  • statsFunctions (dict of name/function pairs) – A dictionary containing column names and functions for computing custom statistics from the clustered localizations. The keys in dictionary determine the name of the customized column and the value contains a function that computes a number from the coordinates of the localizations in each cluster.
centerName = '_center'
class bstore.processors.ComputeTrajectories

Bases: object

Basic functionality for computing trajectories from localizations.

This is used to compute trajectories from regions of a dataset containing localizations, such as fiducial drift trajectories (position vs. frame number)or astigmatic calibration curves (PSF width vs. z).

regionLocs

Pandas DataFrame – The localizations for individual regions.

clearRegionLocs()

Clears any currently held localization data.

computeTrajectory()

Computes the trajectory.

regionLocs

DataFrame holding the localizations for individual fiducials.

reset()

Resets the drift computer to its initial value.

class bstore.processors.ComputeZPosition(zFunc, zCol='z', coordCols=['x', 'y'], sigmaCols=['sigma_x, sigma_y'], fittype='diff', scalingFactor=1, wobbleFunc=None)

Bases: object

Computes the localizations’ z-positions from calibration curves.

Parameters:
  • zFunc (func) – Function(s) mapping the PSF widths onto Z. Supply this argument as a tuple in the order (fx, fy).
  • zCol (str) – The name to assign to the new column of z-positions.
  • coordCols (list of str) – The x- and y-coordinate column names, in that order. This is only used for the wobble correction if wobbleFunc is not None.
  • sigmaCols (list of str) – The column names containing the PSF widths in the x- and y-directions, respectively.
  • fittype (str) – String indicating the type of fit to use when deriving the z-positions. Can be either ‘huang’, which minimizes a distance-like objective function, or ‘diff’, which interpolates a curve based on the difference between PSF widths in x and y.
  • scalingFactor (float) – A scaling factor that multiples the computed z-values to account for a refractive index mismatch at the coverslip. See [1] for more details. This can safely be left at one and the computed z-values rescaled later if you are uncertain about the value to use.
  • wobbleFunc (func) – Function(s) mapping the PSF centroids onto Z. Supply this argument as a tuple in the order (fx, fy). See [2] for more details.

References

  1. Huang, et al., Science 319, 810-813 (2008)
  2. Carlini, et al., PLoS One 10(11):e0142949 (2015).
class bstore.processors.ConvertHeader(mapping={'background': 'offset [photon]', 'dx': 'dx [nm]', 'dx [nm]': 'dx', 'dy': 'dy [nm]', 'dy [nm]': 'dy', 'frame': 'frame', 'intensity [photon]': 'photons', 'length': 'length [frames]', 'length [frames]': 'length', 'loglikelihood': 'loglikelihood', 'offset [photon]': 'background', 'photons': 'intensity [photon]', 'precision': 'uncertainty [nm]', 'sigma': 'sigma [nm]', 'sigma [nm]': 'sigma', 'uncertainty [nm]': 'precision', 'x': 'x [nm]', 'x [nm]': 'x', 'y': 'y [nm]', 'y [nm]': 'y', 'z': 'z [nm]', 'z [nm]': 'z'})

Bases: object

Converts the column names in a localization file to a different format.

Parameters:mapping (FormatMap) – A two-way dictionary for converting from column name to another.
mapping

FormatMap – A two-way dictionary for converting from column name to another.

class bstore.processors.DefaultAstigmatismComputer(coordCols=['x', 'y'], sigmaCols=['sigma_x', 'sigma_y'], zCol='z', smoothingWindowSize=20, smoothingFilterSize=3, useTrajectories=[], startz=None, stopz=None, zeroz=None)

Bases: bstore.processors.ComputeTrajectories

Default algorithm for computing astigmatic calibration curves.

Parameters:
  • coordCols (list of str) – List of strings identifying the x- and y-coordinate column names in that order.
  • sigmaCols (list of str) – List of strings identifying the column names containing the PSF widths in x and y.
  • zCol (str) – Name of the column identifying the z-coordinate values.
  • smoothingWindowSize (float) – Moving average window size in slices for spline fitting.
  • smoothingFilterSize (float) – Moving average Gaussian kernel width in slices for spline fitting.
  • useTrajectories (list of int or empty list) – List of integers corresponding to the fiducial trajectories to use when computing the average trajectory. If [], all trajectories are used.
  • startz (float) – The start point of the z-fitting range.
  • stopz (float) – The end point of the z-fitting range.
  • zeroz (None or float) – The z-position corresponding to the focal plane. This is used only for the calculation of the wobble curves and NOT the astigmatism curves. Set to None if this computer is intended to compute astigmatism curves; set to a number to compute wobble curves.
combineCurves(startz, stopz)

Average the splines from different fiducials together.

Parameters:
  • startz (float) – Minimum frame number in full dataset
  • stopz (float) – Maximum frame number in full dataset
computeTrajectory(locs)

Computes the final drift trajectory from fiducial localizations.

Parameters:locs (Pandas DataFrame) – DataFrame containing the localizations belonging to beads.
Returns:avgSpline – A dataframe containing z-positions and PSF widths in x- and y- for calibrating an astigmatic imaging measurement.
Return type:Pandas DataFrame
fitCurves()

Fits individual splines to each z-scan.

plotBeads(curveNumber=None)

Make a plot of each bead’s z-stack and the average spline fit.

plotBeads allows the user to check the individual beads and their fits against the average spline fit.

Parameters:curveNumber (int) – Index of the spline to plot. (0-index)
reset()

Resets the astigmatism computer to its initial state.

class bstore.processors.DefaultDriftComputer(coordCols=['x', 'y'], frameCol='frame', maxRadius=None, smoothingWindowSize=600, smoothingFilterSize=400, useTrajectories=[], zeroFrame=1000)

Bases: bstore.processors.ComputeTrajectories

The default algorithm for computing a drift trajectory.

The default drift computer fits a cubic smoothing spline to localizations from fiducial regions and averages the splines from multiple fiducials. It allows users to set the frame where the trajectories are equal to zero in x and y, to adjust the smoothing window parameters, and to select what trajectories are used to compute the final trajectory that is stored inside the avgSpline attribute.

Parameters:
  • coordCols (list str) – List of strings identifying the x- and y-coordinate column names in that order.
  • frameCol (str) – Name of the column identifying the column containing the frames.
  • maxRadius (float) – The maximum distance that a localization may lie from the center of a cluster of fiducial localizations; localizations farther than this distance are not included in the fit. Set to None to include all fiducials. Units are the same as in coordCols.
  • smoothingWindowSize (float) – Moving average window size in frames for spline fitting.
  • smoothingFilterSize (float) – Moving average Gaussian kernel width in frames for spline fitting.
  • useTrajectories (list of int) – List of integers corresponding to the fiducial trajectories to use when computing the average trajectory. If empty, all trajectories are used.
  • zeroFrame (int) – Frame where all individual drift trajectories are equal to zero. This may be adjusted to help correct fiducial trajectories that don’t overlap well near the beginning.
avgSpline

Pandas DataFrame – DataFrame with ‘frame’ index column and ‘xS’ and ‘yS’ position coordinate columns representing the drift of the sample during the acquisition.

coordCols

list str – List of strings identifying the x- and y-coordinate column names in that order.

regionLocs

Pandas DataFrame – DataFrame with a ‘region_id’ column denoting localizations from different regions of the original dataset. This is created by the parent ComputeTrajectories class.

frameCol

str – Name of the column identifying the column containing the frames.

maxRadius

float – The maximum distance that a localization may lie from the center of a cluster of fiducial localizations; localizations farther than this distance are not included in the fit. Set to None to include all fiducials. Units are the same as in coordCols.

smoothingWindowSize

float – Moving average window size in frames for spline fitting.

smoothingFilterSize

float – Moving average Gaussian kernel width in frames for spline fitting.

splines

list of dict of 2x UnivariateSpline, 2x int – Individual splines fit to the fiducial trajectories. Key names are ‘xS’, ‘yS’, ‘minFrame’, and ‘maxFrame’.

useTrajectories

list of int or empty list – List of integers corresponding to the fiducial trajectories to use when computing the average trajectory. If [], all trajectories are used.

zeroFrame

int – Frame where all individual drift trajectories are equal to zero. This may be adjusted to help correct fiducial trajectories that don’t overlap well near the beginning.

combineCurves(startFrame, stopFrame)

Average the splines from different fiducials together.

combineSplines(self, framesdf) relies on the assumption that fiducial trajectories span a significant portion of the full number of frames in the acquisition. Under this assumption, it uses the splines found in fitSplines() to extrapolate values outside of their tracks using the boundary value. It next evaluates the splines at each frame spanning the input DataFrame, shifts the evaluated splines to zero at the first frame, and then computes the average across different fiducials.

Parameters:
  • startFrame (int) – Minimum frame number in full dataset
  • stopFrame (int) – Maximum frame number in full dataset
computeTrajectory(regionLocs, startFrame, stopFrame)

Computes the final drift trajectory from fiducial localizations.

Parameters:
  • regionLocs (Pandas DataFrame) – DataFrame containing the localizations belonging to fiducials.
  • startFrame (int) – The minimum frame number in the full dataset.
  • stopFrame (int) – The maximum frame number in the full dataset.
Returns:

self.avgSpline – DataFrame with ‘frame’ index column and ‘xS’ and ‘yS’ position coordinate columns representing the drift of the sample during the acquisition.

Return type:

Pandas DataFrame

Notes

computeTrajectory() requires the start and stop frames because the fiducial localizations may not span the full range of frames in the dataset.

fitCurves()

Fits individual splines to each fiducial.

plotFiducials(curveNumber=None)

Make a plot of each fiducial track and the average spline fit.

plotFiducials allows the user to check the individual fiducial tracks against the average spline fit.

Parameters:curveNumber (int) – Index of the spline to plot. (0-index)
reset()

Resets the drift computer to its initial state.

class bstore.processors.DriftCorrect

Bases: object

Basic functionality for a drift correction processor.

correctorType

string – Identifies the type of drift corrector for a specific class.

driftTrajectory

Pandas DataFrame – x,y pairs each possessing a unique frame number.

correctLocalizations()

Corrects a DataFrame of localizations for drift.

correctorType

Identifies the type of drift corrector for a specific class.

driftTrajectory

A list of x,y pairs with each possessing a unique frame number.

readSettings()

Sets the state of the drift corrector.

writeSettings()

Writes the state of the drift corrector to a file.

class bstore.processors.FiducialDriftCorrect(interactiveSearch=True, coordCols=['x', 'y'], frameCol='frame', removeFiducials=True, driftComputer=None)

Bases: bstore.processors.DriftCorrect, bstore.processors.SelectLocalizations

Correct localizations for lateral drift using fiducials.

Parameters:
  • interactiveSearch (bool) – Determines whether the user will interactively find fiducials. Setting this to False means that fiducials are found automatically, although this is not always reliable.
  • coordCols (list str) – List of strings identifying the x- and y-coordinate column names in that order.
  • frameCol (str) – Name of the column identifying the column containing the frames.
  • removeFiducials (bool) – Determines whether localizations belonging to fiducials are dropped from the input DataFrame when the processor is called. This is ignored if interactiveSearch is False.
  • driftComputer (instance of ComputeTrajectories) – Function for computing the drift trajectory from fiducial localizations. If ‘None’, the default function utilizing smoothing splines is used.
driftComputer

ComputeTrajectories – The algorithm for determining trajectories from fiducials.

interactiveSearch

bool – Should a window open allowing the user to identify fiducials when this processor is called?

correctLocalizations(df)

Correct the localizations using the spline fits to fiducial tracks.

WARNING: To keep memory usage efficient, the input DataFrame is deleted immediately after it’s copied.

Parameters:df (Pandas DataFrame) – The input DataFrame for processing.
Returns:corrdf – The corrected DataFrame.
Return type:Pandas DataFrame
correctorType

Identifies the type of drift corrector for a specific class.

driftTrajectory

A list of x,y pairs with each possessing a unique frame number.

readSettings()

Sets the state of the drift corrector.

writeSettings()

Writes the state of the drift corrector to a file.

class bstore.processors.Filter(columnName, operator, filterParameter, resetIndex=True)

Bases: object

Processor for filtering DataFrames containing localizations.

A filter processor works by selecting a dolumn of the input DataFrame and creating a logical mask by applying the operator and parameter to each value in the column. Rows that correspond to a value for ‘False’ in the mask are removed from the DataFrame.

Parameters:
  • columnName (str) –
  • operator (str) – A string matching an operator defined in the _operatorMap dict. Examples include ‘+’, ‘<=’ and ‘>’.
  • filterParameter (float) –
  • resetIndex (bool) – Should the returned index be reset?
class bstore.processors.Merge(tOff=1, mergeRadius=50, autoFindMergeRadius=False, statsComputer=None, precisionColumn='precision', coordCols=['x', 'y'])

Bases: object

Merges nearby localizations in subsequent frames into one localization.

The merge radius is the distance around a localization that another localization must be in space for the two to become merged. The off time is the maximum number of frames that a localization can be absent from before the its track in time is terminated.

Parameters:
  • autoFindMergeRadius (bool (default: False)) – If True, this will set the merge radius to three times the mean localization precision in the dataset.
  • coordCols (list of str) – List of strings identifying the x- and y-coordinate column names in that order.
  • tOff (int) – The maximum time that a localization can vanish. Units are frames.
  • mergeRadius (float (default: 50)) – The maximum distance between localizations in space for them to be considered as one. Units are the same as x, y, and z. This is ignored if autoFindMergeRadius is True.
  • statsComputer (MergeStats) – Instance of a concrete MergeStats class for computing the merged localization statistics. statsComputer is None by default, which means that only particle ID’s will be appended to the DataFrame and merged statistics will not be calculated. This allows handling of custom DataFrame columns and statistics.
  • precisionColumn (str (default: 'precision')) – The name of the column containing the localization precision. This is ignored if autoFindMergeRadius is False.
autoFindMergeRadius

bool (default: False) – If True, this will set the merge radius to three times the mean localization precision in the dataset.

coordCols

list of str – List of strings identifying the x- and y-coordinate column names in that order.

tOff

int – The maximum time that a localization can vanish. Units are frames.

mergeRadius

float (default: 50) – The maximum distance between localizations in space for them to be considered as one. Units are the same as x, y, and z. This is ignored if autoFindMergeRadius is True.

statsComputer

MergeStats – Instance of a concrete MergeStats class for computing the merged localization statistics. statsComputer is None by default, which means that only particle ID’s will be appended to the DataFrame and merged statistics will not be calculated. This allows handling of custom DataFrame columns and statistics.

precisionColumn

str (default: ‘precision’) – The name of the column containing the localization precision. This is ignored if autoFindMergeRadius is False.

class bstore.processors.MergeFang

Bases: bstore.processors.MergeStats

Merger for localizations computed from Fang’s sCMOS MLE software.

computeStatistics(df, particleCol='particle')

Calculates the statistics of the linked trajectories.

Parameters:
  • df (Pandas DataFrame) – DataFrame containing linked localizations.
  • particleCol (str) – The name of column containing the merged partice ID’s.
Returns:

procdf – DataFrame containing the fully merged localizations.

Return type:

Pandas DataFrame

class bstore.processors.MergeFangTS

Bases: bstore.processors.MergeStats

Merger for localizations computed from Fang’s sCMOS MLE software.

This computer is for DataFrames in the ThunderSTORM column format.

computeStatistics(df, particleCol='particle')

Calculates the statistics of the linked trajectories.

Parameters:
  • df (Pandas DataFrame) – DataFrame containing linked localizations.
  • particleCol (str) – The name of column containing the merged partice ID’s.
Returns:

procdf – DataFrame containing the fully merged localizations.

Return type:

Pandas DataFrame

class bstore.processors.MergeStats

Bases: object

Basic functionality for computing statistics from merged localizations.

computeStatistics()

Computes the merged molecule statistics.

class bstore.processors.SelectLocalizations

Bases: object

Interactively select localizations using rectangular ROI’s.

This class is used to display an image containing information about the local density of localizations within a dataset. From this image, a user may interactively select regions containing localizations for further analysis, such as when performing fiducial drift corrections.

doInteractiveSearch(df, gridSize=100, unitConvFactor=0.001, unitLabel='microns')

Interactively find regions in the histogram images.

Allows the user to select regions and extract localizations.

Parameters:
  • df (Pandas DataFrame) – Data to visualize and search for fiducials.
  • gridSize (float) – The size of the hexagonal grid in the 2D histogram.
  • unitConvFactor (float) – Conversion factor for plotting the 2D histogram in different units than the data. Most commonly used to convert nanometers to microns. In this case, there are unitConvFactor = 1/1000 nm/micron.
  • unitLabel (str) – Unit label for the histogram. This is only used for labeling the axes of the 2D histogram; users may change this depending on the units of their data and unitConvFactor.
exception bstore.processors.UseTrajectoryError(value)

Bases: Exception

Raised when drift computer has invalid indexes to fiducial trajectories.

exception bstore.processors.ZeroFiducialRegions(value)

Bases: Exception

Raised when zero fiducials are present during drift correction.

exception bstore.processors.ZeroRegions(value)

Bases: Exception

Raised when zero regions are present during trajectory computation.

Module contents