ActImg#

Warning

This library and its documentation are still under development.

This section documents the ActImg class and its methods and helpers.

ActImg class and attributes#

meshure.actimg.ActImg(image_stack: tuple, title: str, shape: tuple = None, depth: int = None, deconvolved: bool = None, resolution: float = None, meta: dict = None, manipulated_stack: array = None, manipulated_depth: int = 0) → None#

ActImg is a class which helps manipulate fluorescence microscopy images (originally designed for STED images of actin). The class contains helpers to read in the data and instantiate them as ActImg objects (see: get_actimg()); methods to visualise and manipulate the instances, estimating and summarising parameters relating to the actin mesh. Currently, the original data is kept in the image_stack attribute, and modifications happen on a copy which is internally updated after methods are called on it with the option of nuking (see: actimg.nuke()) the modifications to restore original object. A history of all changes implemented (methods called) are recorded in a hidden attribute ._history. ActImg instances are temporarily created and manipulated by the ActImgCollection class. …

meshure.actimg.image_stack#

A tuple of arrays or a umtidimensional array where axis=0 specifies the frame of an image.

Type:: tuple or np.ndarray (ndim, m, n)

meshure.actimg.title#

The title of the image, also the filename.

Type:: str

meshure.actimg.shape#

Type:: tuple=None

meshure.actimg.depth#

Type:: int=None

meshure.actimg.deconvolved#

Type:: bool=None

meshure.actimg.resolution#

Type:: float=None

meshure.actimg.meta#

Type:: dict=None

meshure.actimg.manipulated_stack#

Type:: np.array=None

meshure.actimg.manipulated_depth#

Type:: int=0

meshure.actimg.manipulated_substack_inds#

Type:: any=None

_projected = None

_history = None

estimated_parameters = {}

_binary_images = {}

ActImg methods#

meshure.actimg.ActImg.visualise(self, imtype: str = 'original', ind: int = 1, save: bool = False, dest_dir: str = '/home/docs/checkouts/readthedocs.org/user_builds/actinmeshure/checkouts/latest/docs/source', colmap: str = 'inferno', scale_bar: bool = True, bar_locate: str = 'upper left')#

Visualise an image or stack slice. Plot saved as {.title}_{._history}.png. …

Parameters:

imtype (str='original') – A string specifying whether to display original or modified data.
ind (int=1) – Index of slice to visualise from z-stack (first frame is n=1, also default value).
save (bool=False) – Save plot to dest_dir. Displayed but not saved by default.
dest_dir (str=os.getcwd()) – Directory to save plot in (defaults to current working directory)
colmap (str='inferno') – Change color map (passed to cmap argument) in matplotlib.pyplot. Perceptually uniform colour map used by default.
scale_bar (bool=True) – Adding a scale bar to images by default (provided, resolution is available).
bar_locate (str='upper_left') – Position of scale bar; upper left by default.

Returns:

Plot of specified slice from parent stack.

Return type:

matplotlib.pyplot

meshure.actimg.ActImg.visualise_stack(self, imtype: str = 'original', substack=None, save: bool = False, dest_dir: str = '/home/docs/checkouts/readthedocs.org/user_builds/actinmeshure/checkouts/latest/docs/source', fig_size: tuple | None = None, colmap: str = 'inferno', scale_bar: bool = True, bar_locate: str = 'upper left')#

Visualise a stack as a tile of all constituent images. By default, all frames will be visualised. …

Parameters:

imtype (str='original') – A string specifying whether to display original or modified data.
substack (list) – A list of length=2, specifying the range [start_index, finish_index] of slices to perform the operation on. Note: indexing is from 1 to n_frames in image stack.
save (bool=False) – Save plot to dest_dir. Displayed but not saved by default.
dest_dir (str=os.getcwd()) – Directory to save plot in (defaults to current working directory)
colmap (str='inferno') – Change color map (passed to cmap argument) in matplotlib.pyplot. Perceptually uniform colour map used by default.
scale_bar (bool=True) – Adding a scale bar to images by default (provided, resolution is available).
bar_locate (str='upper_left') – Position of scale bar; upper left by default.

Returns:

A tiled plot of specified substack from parent stack.

Return type:

matplotlib.pyplot

meshure.actimg.ActImg.normalise(self)#

Normalises every frame in a z-stack (or just image) by minimum pixel intensity in that frame. Resulting frames have values in range [0,1].

Returns:

self.manipulated_stack (np.ndarray) – Normalised image stack.
self.self.manipulated_depth (int) – Attribute matches self.depth.

meshure.actimg.ActImg.z_project_min(self, substack=None)#

Returns the minimum axial projection of a z-stack. Retains the minimum intensity at every position. Can be performed on a sub-range. …

Parameters:

substack (list) – A list of length=2, specifying the range [start_index, finish_index] of slices to perform the operation on. Note: indexing is from 1 to n_frames in image stack.

Returns:

self.manipulated_stack (np.ndarray) – Minimum projection of dimensions=self.shape.
self.self.manipulated_depth (int) – Updated to 1.

See also

z_project_max

meshure.actimg.ActImg.z_project_max(self, substack=None)#

Returns the maximum axial projection of a z-stack. Retains the maximum intensity at every pixel position. Can be performed on a sub-range. …

Parameters:

substack (list) – A list of length=2, specifying the range [start_index, finish_index] of slices to perform the operation on. Note: indexing is from 1 to n_frames in image stack.

Returns:

self.manipulated_stack (np.ndarray) – Minimum projection of dimensions=self.shape.
self.self.manipulated_depth (int) – Updated to 1.

See also

z_project_min

meshure.actimg.ActImg.threshold_manual(self, threshold: float)#

Returns a binary thresholded image. Values < threshold will be labelled as object (1), while the rest discarded as background (0). Note: can be called after normalisation. …

Parameters:

threshold (float) – Values below the threshold are set to 1; the rest are set to 0.

Returns:

self.manipulated_stack (np.ndarray of ints) – Binary image of dimensions=self.shape.
self.self.manipulated_depth (int) – Updated to 1.

meshure.actimg.ActImg.threshold_dynamic(self, std_dev_factor: float = 0.0, return_mean_std_dev: bool = False, line_prof_coords=None)#

Obtains line profiles (of width 5 pixels) specified in boundaries line_prof_coords, returns mean and standard deviation of aggregated profile. …

Parameters:

std_dev_dactor (float=0.0) –
???
return_mean_std_dev (bool=False) –
???
line_prof_coords (nested list of tuples) – List of tuples [[start, end], …] where start = (start_row, start_col) and end = (end_row, end_col) specify the start and end point of the profile, respectively.

Returns:

self.manipulated_stack (np.ndarray of ints) – Binary image of dimensions=self.shape.
self.self.manipulated_depth (int) – Updated to 1.
(mean, std_dev) (tuple of floats (optional)) – Optionally return mean and standard deviation of the aggregated line profiles.

See also

_threshold_preview_cases

meshure.actimg.ActImg.steerable_gauss_2order(self, substack=None, sigma: float = 2.0, theta: float = 0.0, visualise: bool = True, tmp: bool = False)#

Steers an X-Y separable second order Gaussian filter in direction theta. Implemented according to W. T. Freeman and E. H. Adelson, “The Design and Use of Steerable Filters”, IEEE PAMI, 1991. Based on matlab code from Jincheng Pang, Tufts University, 2013. …

Parameters:

substack (list) – A list of length=2, specifying the range [start_index, finish_index] of slices to perform the operation on. Note: indexing is from 1 to n_frames in image stack.
sigma (float=2.0) – The standard deviation of the second-order Gaussian kernel.
theta (float=0.) – The steerable filter orientation, in degrees.
tmp (bool=False) – Optional argument enables returning the response and the oriented filter without updating original object.

Returns:

self.manipulated_stack (np.ndarray) – An n-dimensional array of oriented filter responses for ever .
self.self.manipulated_depth (int) – Updated to according to number of slices processed (specified by substack).
self.manipulated_substack_inds (list=substack) – Substack inds are updated to yield correct visualisation using ActImg.visualise_stack() method
dictionary (optional) – Dictionary maps the response of the theta-rotated derivative and the oriented filter.

meshure.actimg.ActImg.steerable_gauss_2order_thetas(self, thetas, sigma: float = 2.0, substack=None, visualise=False, return_responses=False)#

Applies steerable second order Gaussian filters oriented in multiple directions (specified by thetas). For every frame, the minimum projection of the oriented filter responses is returned in an n-dimensional array. …

Parameters:

thetas (list) – A list of floats or integers, specifying the directions (in degrees) in which the second-order Gaussian should be steered.
sigma (float=2.0) – The standard deviation of the Gaussian.
substack (list) – A list of length=2, specifying the range [start_index, finish_index] of slices to perform the operation on. Note: indexing is from 1 to n_frames in image stack.
visualise (bool=False) – Optionally, visualise the response stack.

Returns:

self.manipulated_stack (np.ndarray) – An n-dimensional array (where n is determined by substacks), where each frame is the minimum projection of the oriented filter responses.
self.self.manipulated_depth (int) – Updated to according to number of slices processed (specified by substack).
self.manipulated_substack_inds (list=substack) – Substack inds are updated to yield correct visualisation using ActImg.visualise_stack() method

See also

steerable_gauss_2order

TODO: input validation, visualisation vmax/vmin

meshure.actimg.ActImg.nuke(self)#

Restores an ActImg instance to it’s pre-manipulated state.

Returns:: self – Returns the same instance of ActImg but without any manipulation and history.
Return type:: ActImg

meshure.actimg.ActImg.save(self, dest_dir: str = '/home/docs/checkouts/readthedocs.org/user_builds/actinmeshure/checkouts/latest/docs/source')#

Save ActImg object using pickle.

Parameters:: dest_dir (str or Path) – Path where the ActImg object should be saved in .pkl format; defaults to current working directory.
Return type:: A pickle file (.pkl) with original image title in filename.

meshure.actimg.ActImg.save_estimated_params(self, dest_dir: str = '/home/docs/checkouts/readthedocs.org/user_builds/actinmeshure/checkouts/latest/docs/source')#

Saves estimated parameters in JSON format.

Parameters:: dest_dir (str or Path) – Path of destination where the JSON file should be saved; defaults to current working directory.
Return type:: A JSON file with the estimated parameters in the ActImg object and the resolution-related parameters from self.resolution.

ActImg hidden methods#

meshure.actimg.ActImg._threshold_preview_cases(self, mean: float | None = None, std_dev: float | None = None, factors=None, max_proj_substack=None, save: bool = False, dest_dir: str = '/home/docs/checkouts/readthedocs.org/user_builds/actinmeshure/checkouts/latest/docs/source')#

Helper previews the outputs of several degrees of thresholding mean-factor*std_dev. Note: must be applied after steerable filter. …

Parameters:

mean (float, optional) – Mean of line profiles, optionally returned by ActImg.threshold_dynamic()
std_dev (float, optional) – Standard deviation of line profiles, optionally returned by ActImg.threshold_dynamic()
factors (list of floats or ints) – The factors where threshold = mean-factor*std_dev for factor in factors
save (bool=False) – Plot is displayed but not saved by default. True displays and saves plot.
dest_dir (str=os.getcwd()) – Destination where the plot is saved if save=True; defaults to current working directory.

Returns:

Plots a tile comparing the minimum projection of oriented filter responses to the different thresholds.

Return type:

matplotlib.pyplot

See also

threshold_dynamic

meshure.actimg.ActImg._aggregate_line_profiles(self, line_prof_coords=None, return_mean_st_dev: bool = False)#

meshure.actimg.ActImg._get_oriented_filter(self, theta: float, sigma: float)#

Helper method; returns a second-order Gaussian filter with sigma=`sigma` oriented clockwise by angl=`theta`. …

Parameters:

theta (float=0.) – The steerable filter orientation, in degrees.
sigma (float=2.0) – The standard deviation of the second-order Gaussian kernel.

Returns:

oriented_filter – The kernel of an oriented/steered second-order Gaussian.

Return type:

np.ndarray

TODO: input validation

meshure.actimg.ActImg._visualise_oriented_filters(self, thetas: list, sigma: float, save: bool = False, dest_dir: str = '/home/docs/checkouts/readthedocs.org/user_builds/actinmeshure/checkouts/latest/docs/source', return_filters=False)#

Helper method; tile of plots shows the oriented filters; optionally, the plot can be saved or the oriented filters can be returned as a dictionary. …

Parameters:

thetas (list) – A list of floats or integers, specifying the directions (in degrees) in which the second-order Gaussian should be steered.
sigma (float=2.0) – The standard deviation of the Gaussian.
save (bool=False) – Plot is displayed but not saved by default. True displays and saves plot.
dest_dir (str=os.getcwd()) – Destination where the plot is saved if save=True; defaults to current working directory.
return_filters (bool=False) – Optionally, return the oriented filter as a dictionary.

Returns:

matplotlib.pyplot – Plot of specified slice from parent stack.
png (optional) – A png of the plot can be saved to the dest_dir.
all_filters_dict (dictionary (optional)) – A dictionary which maps all thetas to oriented filters.

TODO: input validation, visualisation vmax/vmin

meshure.actimg.ActImg._call_hist(self, action)#

Helper records performed manipulations (called methods) in a list.

Returns:: self._history – A list of strings which specify the processing steps applied (firstt to latest).
Return type:: list of str

meshure.actimg.ActImg._update_log(self, key, value)#: Helper updates the self._log attribute with any pertinent information.

ActImg helpers#

meshure.actimg.get_ActImg(image_name: str, image_dir: str)#

Creates an ActImg instance.

Parameters:

image_name (str) – A string specifies the name of the image contained in image_dir. Used for instance title attribute.
image_dir (str) – The root directory where image_name is contained.

Returns:

An instance of the ActImg class.

Return type:

ActImg

meshure.actimg.load_ActImg(obj_path: str)#

Imports a saved ActImg object.

Parameters:: obj_path (str or Path) – Path where ActImg object is stored in pickle format (must have the .pkl extension.)
Returns:: actimg – An instance of the ActImg class.
Return type:: ActImg object