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:
- Convert rows containing strings to numeric data types
- Drop rows containing strings that cannot be parsed to numeric types
- 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
- Huang, et al., Science 319, 810-813 (2008)
- 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.