pwspy.dataTypes.DynCube¶

class pwspy.dataTypes.DynCube(data, metadata, processingStatus=None, dtype=<class 'numpy.float32'>)[source]¶

Bases: pwspy.dataTypes._data.ICRawBase

A class representing a single acquisition of PWS Dynamics. In which the wavelength is held constant and the 3rd dimension of the data is time rather than wavelength. This can be analyzed to reveal information about diffusion rate. Contains methods for loading and saving to multiple formats as well as common operations used in analysis.

Parameters

data – A 3-dimensional array containing the data. The dimensions should be [Y, X, Z] where X and Y are the spatial coordinates of the image and Z corresponds to the index dimension, e.g. wavelength, wavenumber, time, etc.
metadata (DynMetaData) – The metadata object associated with this data object.
processingStatus (Optional[ProcessingStatus]) – An object that keeps track of which processing steps and corrections have been applied to this object.
dtype – the data type that the data should be stored as. The default is numpy.float32.

class ProcessingStatus(cameraCorrected=False, normalizedByExposure=False, extraReflectionSubtracted=False, normalizedByReference=False)¶

Bases: object

Keeps track of which processing steps have been applied to an ICRawBase object. By default none of these things have been done for raw data

correctCameraEffects(correction=None, binning=None)¶

Subtracts the darkcounts from the data. count is darkcounts per pixel. binning should be specified if it wasn’t saved in the micromanager metadata. Both method arguments should be able to be loaded automatically from the metadata but for older data files they will need to be supplied manually.

Parameters

correction (Optional[CameraCorrection]) – The cameracorrection object providing information on how to correct the data.
binning (Optional[int]) – The binning that the raw data was imaged at. 2 = 2x2 binning, 3 = 3x3 binning, etc.

classmethod decodeHdf(d)¶

Load a new instance of ICRawBase from an h5py.Dataset

Parameters: d (h5py.Dataset) – The dataset that the ICBase has been saved to
Returns: data: The 3D array of data index: A tuple containing the index metadata: A dictionary containing metadata. procStatus: The processing status of the object.
Return type: A tuple containing

filterDust(kernelRadius, pixelSize=None)[source]¶

This method blurs the data of the cube along the X and Y dimensions. This is useful if the cube is being used as a reference to normalize other cube. It helps blur out dust and other unwanted small features.

Parameters

kernelRadius (float) – The sigma of the gaussian kernel used for blurring. A greater value results in greater blurring. If pixelSize is provided then this is in units of pixelSize, otherwise it is in units of pixels.
pixelSize (Optional[float]) – The size (usualy in units of microns) of each pixel in the datacube. This can generally be loaded automatically from the metadata.

classmethod fromMetadata(meta, lock=None)[source]¶

Load a new instance of DynCube based on the information contained in a DynMetaData object.

Parameters

meta (DynMetaData) – The metadata object to be used for loading.
lock (Optional[Lock]) – An optional Lock used to synchronize IO operations in multithreaded and multiprocessing applications.

Return type

DynCube

Returns

A new instance of DynCube.

classmethod fromOldPWS(directory, metadata=None, lock=None)[source]¶

Loads from the file format that was saved by the all-matlab version of the Basis acquisition code. Data was saved in raw binary to a file called image_cube. Some metadata was saved to .mat files called info2 and info3.

Parameters

directory – The directory containing the data files.
metadata (Optional[DynMetaData]) – The metadata object associated with this acquisition
lock (Optional[Lock]) – A Lock object used to synchronized IO in multithreading and multiprocessing applications.

Return type

DynCube

Returns

A new instance of DynCube.

classmethod fromTiff(directory, metadata=None, lock=None)[source]¶

Load a dyanmics acquisition from a tiff file. if the metadata for the acquisition has already been loaded then you can provide is as the metadata argument to avoid loading it again. the lock argument is an optional place to provide a multiprocessing.Lock which can be used when multiple files in parallel to avoid giving the hard drive too many simultaneous requests, this is probably not necessary.

Parameters

directory – The directory containing the data files.
metadata (Optional[DynMetaData]) – The metadata object associated with this acquisition
lock (Optional[Lock]) – A Lock object used to synchronized IO in multithreading and multiprocessing applications.

Return type

DynCube

Returns

A new instance of DynCube.

getAutocorrelation()[source]¶

Returns the autocorrelation function of dynamics data along the time axis. The ACF is calculated using fourier transforms using IFFT(FFT(data)*conj(FFT(data)))/length(data).

Return type: ndarray
Returns: A 3D array of the autocorrelation function of the original data.

getMeanSpectra(mask=None)¶

Calculate the average spectra within a region of the data.

Parameters: mask (Union[Roi, ndarray, None]) – An optional other.Roi or boolean numpy array used to select pixels from the X and Y dimensions of the data array. If left as None then the full data array will be used as the region.
Return type: Tuple[ndarray, ndarray]
Returns: The average spectra within the region, the standard deviation of the spectra within the region

static getMetadataClass()[source]¶

Return type: Type[DynMetaData]
Returns: The metadata class associated with this subclass of ICRawBase

classmethod loadAny(directory, metadata=None, lock=None)[source]¶

Attempt to load a DynCube for any format of file in directory

Parameters

directory (str) – The directory containing the data files.
metadata (Optional[DynMetaData]) – The metadata object associated with this acquisition
lock (Optional[Lock]) – A Lock object used to synchronized IO in multithreading and multiprocessing applications.

Return type

DynCube

Returns

A new instance of DynCube.

normalizeByExposure()¶: This is one of the first steps in most analysis pipelines. Data is divided by the camera exposure. This way two PwsCube that were acquired at different exposure times will still be on equivalent scales.

normalizeByReference(reference)[source]¶

This method can accept either a DynCube (in which case it’s average over time will be calculated and used for normalization) or a 2d numpy Array which should represent the average over time of a reference DynCube. The array should be 2D and its shape should match the first two dimensions of this DynCube.

Parameters: reference (Union[DynCube, ndarray]) – Reference data for normalization. Usually an image of a blank piece of glass.

performFullPreProcessing(reference, referenceMaterial, extraReflectance, cameraCorrection=None)¶

Use the subtractExtraReflection, normalizeByReference, correctCameraEffects, and normalizeByExposure methods to perform the standard pre-processing that is done before analysis.

Note: This will also end up applying corrections to the reference data. If you want to perform pre-processing on a whole batch of data then you should implement your own script based on what is done here.

Parameters

reference (self.__class__) – A data cube to be used as a reference for normalization. Usually an image of a blank dish with cell media or air.
referenceMaterial (Material) – The material that was imaged in the reference dish. The theoretically expected reflectance will be calculated assuming a “Glass/{Material}” reflective interface.
extraReflectance (ExtraReflectanceCube) – The data cube containing system internal reflectance calibration information about the specific system configuration that the data was taken with.

plotMean()¶

Return type

Tuple[Figure, Axes]

Returns

A figure and attached axes plotting the mean of the data along the index axis.: corresponds to the mean reflectance in most cases.

selIndex(start, stop)[source]¶

Parameters

start – The beginning value of the index in the new object. Pass None to include everything.
stop – The ending value of the index in the new object. Pass None to include everything.

Return type

DynCube

Returns

A new instance of ICBase with only data from start to stop in the index.

selectLassoROI(displayIndex=None, clim=None)¶

Allow the user to draw a freehand ROI on an image of the acquisition.

Parameters: displayIndex (Optional[int]) – Display a particular z-slice of the array for mask drawing. If None then the mean along Z is displayed.
Return type: Roi
Returns: An array of vertices of the polygon drawn.

selectRectangleROI(displayIndex=None)¶

Allow the user to draw a rectangular ROI on an image of the acquisition.

Parameters: displayIndex (int) – is used to display a particular z-slice for mask drawing. If None then the mean along Z is displayed. Returns an array of vertices of the rectangle.
Returns: An array of the 4 XY vertices of the rectangle.
Return type: np.ndarray

subtractExtraReflection(extraReflection)[source]¶

Subtract the portion of the signal that is due to internal reflections of the optical system from the data.

Parameters: extraReflection (ndarray) – A calculated data cube indicating in units of camera counts how much of the data is from unwanted internal reflections of the system.

toHdfDataset(g, name, fixedPointCompression=True)¶

Save this object into an HDF dataset.

Parameters

g (Group) – The h5py.Group object to create a new dataset in.
name (str) – The name of the new dataset.
fixedPointCompression (bool) – If True then the data will be converted from floating point to 16-bit fixed point. This results in approximately half the storage requirements at a very slight loss in precision.

Return type

Group

Returns

A reference to the h5py.Group passed in as g.

property index: Tuple[float, ...]¶

Returns: The values of the datacube’s index

Return type: Tuple[float, ...]

property times: Tuple[float, ...]¶

Unlike PWS where we operate along the dimension of wavelength, in dynamics we operate along the dimension of time.

Return type: Tuple[float, ...]
Returns: A tuple of the time values for each 2d slice along the 3rd axis of the data array.