Code reference
Command-line interface
The usage of the command line interface is described in detail here. It consists of these main methods:
cli.config
- drymass.cli.config.FILE_CONFIG = 'drymass.cfg'
DryMass configuration file name
- class drymass.cli.config.ConfigFile(path)[source]
DryMass configuration file management
Manage configuration file of an experimental data set with restrictions imposed by
drymass.cli.definitions.config
.- Parameters
path (str) – path to the configuration file or a folder containing the configuration file
FILE_CONFIG
.
- set_value(section, key, value)[source]
Set a configuration key value
- Parameters
Notes
Valid section and key names are defined in definitions.py
- update(other)[source]
Update the current configuration with data from another
- Parameters
other (ConfigFile) – the configuration file from which data is imported into the current configuration
Notes
None-valued keys are ignored.
cli.definitions
- drymass.cli.definitions.config
The keys and subkeys of the definition dictionary are defined and described in the configuration file section.
cli.dialog
The dialog submodule contains methods for user-interaction.
- drymass.cli.dialog.OUTPUT_SUFFIX = '_dm'
DryMass analysis output suffix (appended to data path)
- drymass.cli.dialog.input_setting(path, section, key, value=None)[source]
Ask the user for a configuration key
- drymass.cli.dialog.main(path=None, req_meta=None, description='DryMass analysis.', profile=None, recursive=False)[source]
Main user dialog with optional “meta” kwargs required
- Parameters
path (str, pathlib.Path, or None) – Path to the measurement data. If set to None, the command-line will be parsed.
req_meta (list of str) – Keyword arguments of the [meta] section in drymass.cfg that are required by the current task.
description (str) – Description of the current task. The description is displayed when the user executes a console_script entry-point with the –help argument.
profile (str, pathlib.Path, or None) – A path to a ‘drymass.cfg’ file or a name of a profile in the local library (see
drymass.cli.profile
). If set to None, the default profile is used and the user is asked for missing values.recursive (bool) – Perform recursive search in path. If path is None, then recursive must be False. Instead, the recursive argument should be set via the command line.
- Returns
path_in (pathlib.Path or list of pathlib.Path) – The measurement path. If a recursive search is performed (see recursive parameter above), then a list of the measurement paths is returned.
path_out (pathlib.Path or None) – The output path, i.e. the path with _dm appended. If a recursive search is performed, path_out is set to None.
- drymass.cli.dialog.parse(description='DryMass analysis.')[source]
Obtain the input data set path by parsing the command line
cli.parse_funcs
These methods are used to parse the values set in the Configuration file and convert them to the correct type.
- drymass.cli.parse_funcs.fintlist(alist)[source]
List of integers from string or list of strings/integers
- drymass.cli.parse_funcs.floattuple_or_one(fti)[source]
Tuple of two floats or ±1 from a string or a number
cli.plot
DryMass plotting functionalities.
- drymass.cli.plot.add_cbar(ax, mapper, fmt='%.2f', units='', loc='right', size='5%', labelloc=None, extend='neither')[source]
Add a colorbar to a plot
- drymass.cli.plot.plot_image(data, ax=None, imtype='phase', cbar=True, px_um=None, ret_cbar=False, cbformat=None, **kwargs)[source]
Plot an image
- Parameters
data (2d np.ndarray) – Input image
ax (matplotlib.Axes) – Axis to plot to
imtype (str) – One of [“intensity”, “phase”, “phase error”, “refractive index”].
cbar (bool) – Whether to add a colorbar.
px_um (float) – Pixel size [µm]
ret_cbar (bool) – Whether to return the colorbar.
kwargs (dict) – Keyword arguments to plt.imshow.
- Returns
Axis and colorbar.
- Return type
ax [, cbar]
Data analysis
anasphere
- drymass.anasphere.FILE_SPHERE_DATA = 'sphere_{}_{}_data.h5'
Output sphere analysis qpimage.QPSeries data
- drymass.anasphere.FILE_SPHERE_STAT = 'sphere_{}_{}_statistics.txt'
Output sphere analysis statistics
- drymass.anasphere.analyze_sphere(h5roi, dir_out, r0=1e-05, method='edge', model='projection', edgekw={}, imagekw={}, alpha=0.18, rad_fact=1.2, ret_changed=False, ret_reused=False, count=None, max_count=None)[source]
Perform sphere analysis
- Parameters
h5series (str) – Path of qpimage.QPSeries hdf5 file
dir_out (str) – Path to output directory
r0 (float) – Initial radius
method (str) – Either “edge” or “image”; see [sphere] Sphere-based image analysis for more information.
model (str) – Propagation model to use; see [sphere] Sphere-based image analysis for more information.
edgekw (dict) – Keyword arguments to
qpsphere.edgefit.contour_canny()
imagekw (dict) – Keyword arguments to
qpsphere.imagefit.alg.match_phase()
alpha (float) – Refraction increment [mL/g]
rad_fact (float) – Radial inclusion factor for dry mass computation
ret_changed (bool) – Return boolean indicating whether the sphere data on disk was created/updated (True) or whether only previously created ROI data was used (False).
ret_reused (bool) – Return integer indicating how many previous fits were reused.
count (multiprocessing.Value) – Can be used to monitor the progress of the algorithm. Initially, the value of max_count.value is incremented by the total number of steps. At each step, the value of count.value is incremented.
max_count (multiprocessing.Value) – Can be used to monitor the progress of the algorithm. Initially, the value of max_count.value is incremented by the total number of steps. At each step, the value of count.value is incremented.
- drymass.anasphere.absolute_dry_mass_sphere(qpi, radius, center, alpha=0.18, rad_fact=1.2)[source]
Compute absolute dry mass of a spherical phase object
The absolute dry mass is computed with
m_abs = m_rel + m_sup m_rel = lambda / (2*PI*alpha) * phi_tot * deltaA m_sup = 4*PI / (3*alpha) * radius^3 (n_med - n_PBS)
with the vacuum wavelength
lambda
, the total phase retardation in the area of interestphi_tot
, the pixel areadeltaA
, the refractive index of the medium n_med (stored inqpi.meta
), and the refractive index of phosphate buffered saline (PBS)n_PBS=1.335
.This is the absolute dry mass, because it takes into account the offset caused by the suppressed density in the phase data.
- Parameters
qpi (qpimage.QPImage) – QPI data
center (tuble (x,y)) – Center of the sphere [px]
radius (float) – Radius of the sphere [m]
wavelength (float) – The wavelength of the light [m]
alpha (float) – Refraction increment [mL/g]
rad_fact (float) – Inclusion factor that scales radius to increase the area used for phase summation; if the backgound phase exhibits a noise phase signal, positive and negative contributions cancel out and rad_fact does not have an effect above a certain critical value.
- Returns
dry_mass – The absolute dry mass of the sphere [g]
- Return type
- drymass.anasphere.relative_dry_mass(qpi, radius, center, alpha=0.18, rad_fact=1.2)[source]
Compute relative dry mass of a circular area in QPI
The dry mass is computed with
m_rel = lambda / (2*PI*alpha) * phi_tot * deltaA
with the vacuum wavelength lambda, the total phase retardation in the area of interest phi_tot, and the pixel area deltaA.
This is the relative dry mass, because it is computed relative to the surrounding medium (phi_tot) and not relative to water.
- Parameters
qpi (qpimage.QPImage) – QPI data
center (tuble (x,y)) – Center of the area of interest [px]
radius (float) – Radius of the area of interest [m]
wavelength (float) – The wavelength of the light [m]
alpha (float) – Refraction increment [mL/g]
rad_fact (float) – Inclusion factor that scales radius to increase the area used for phase summation; if the backgound phase exhibits a noise phase signal, positive and negative contributions cancel out and rad_fact does not have an effect above a certain critical value.
- Returns
dry_mass – The relative dry mass of the object [g]
- Return type
converter
- drymass.converter.FILE_SENSOR_DATA_H5 = 'sensor_data.h5'
Output qpimage.QPSeries sensor data
- drymass.converter.FILE_SENSOR_DATA_TIF = 'sensor_data.tif'
Output phase/amplitude TIFF sensor data
- drymass.converter.convert(path_in, dir_out, meta_data=None, holo_kw=None, qpretrieve_kw=None, bg_data_amp=None, bg_data_pha=None, write_tif=False, ret_dataset=False, ret_changed=False, count=None, max_count=None)[source]
Convert experimental data to qpimage.QPSeries on disk
- Parameters
path_in (str or pathlib.Path) – Input path to file or directory
dir_out (str or pathlib.Path) – Outuput direcory
meta_data (dict) – Metadata (see qpimage.meta.META_KEYS)
qpretrieve_kw (dict) – Keyword arguments passed to qpretrieve for phase retrieval from interferometric data.
holo_kw (dict) – This is deprecated, please use qpretrieve_kw instead.
bg_data_amp (None, int, or path to file) –
The background data for phase and amplitude. One of
None: No background data
int: Image index (starting at 1) of the input data set to use as background data
str, pathlib.Path: Path to a separate file that is used for background correction, relative to the directory in which path_in is located (path_in.parent).
bg_data_pha (None, int, or path to file) –
The background data for phase and amplitude. One of
None: No background data
int: Image index (starting at 1) of the input data set to use as background data
str, pathlib.Path: Path to a separate file that is used for background correction, relative to the directory in which path_in is located (path_in.parent).
write_tif (bool) – Export tif images for use with Fiji/ImageJ (tif images are only created if they don’t already exist or if the analysis changed)
ret_dataset (bool) – Return the qpformat dataset
ret_changed (bool) – Return True if the dataset changed
count (multiprocessing.Value) – Can be used to monitor the progress of the algorithm. Initially, the value of max_count.value is incremented by the total number of steps. At each step, the value of count.value is incremented.
max_count (multiprocessing.Value) – Can be used to monitor the progress of the algorithm. Initially, the value of max_count.value is incremented by the total number of steps. At each step, the value of count.value is incremented.
- drymass.converter.get_background(bg_data, dataset, which='phase')[source]
Obtain the background data for a dataset
- Parameters
bg_data (None, int, str, or pathlib.Path) –
Represents the background data:
None: no background data
int: image with index bg_data - 1 in dataset is used for background correction
str, pathlib.Path: An external file will be used for background correction.
dataset (qpformat.dataset.SeriesData) – The dataset for which the background data is collected. No background correction is performed! dataset is needed for integer bg_data and for path-based bg_data (because of meta data and hologram kwargs).
- Returns
bg – The background data.
- Return type
2d np.ndarray
extractroi
- drymass.extractroi.BG_DEFAULT_KW = {'border_perc': 5, 'border_px': 5, 'fit_offset': 'mean', 'fit_profile': 'tilt'}
Default background correction keyword arguments
- drymass.extractroi.FILE_ROI_DATA_H5 = 'roi_data.h5'
Output ROI qpimage.QPSeries data
- drymass.extractroi.FILE_ROI_DATA_TIF = 'roi_data.tif'
Output phase/amplitude TIFF data
- drymass.extractroi.FILE_SLICES = 'roi_slices.txt'
Output slice locations
- drymass.extractroi.extract_roi(h5series, dir_out, size_m, size_var=0.5, max_ecc=0.7, dist_border=10, pad_border=40, exclude_overlap=30.0, threshold='li', ignore_data=None, force_roi=None, bg_amp_kw={'border_perc': 5, 'border_px': 5, 'fit_offset': 'mean', 'fit_profile': 'tilt'}, bg_amp_bin=None, bg_amp_mask_radial_clearance=None, bg_pha_kw={'border_perc': 5, 'border_px': 5, 'fit_offset': 'mean', 'fit_profile': 'tilt'}, bg_pha_bin=None, bg_pha_mask_radial_clearance=None, bg_sphere_edge_kw={}, search_enabled=True, ret_roimgr=False, ret_changed=False, count=None, max_count=None)[source]
Extract ROIs from a qpimage.QPSeries hdf5 file
- Parameters
h5series (str) – Path of qpimage.QPSeries hdf5 file
dir_out (str) – Path to output directory
size_m (float) – Approximate diameter of the specimen [m]
size_var (float) – Allowed variation relative to specimen size
max_ecc (float) – Allowed maximal eccentricity of the specimen
dist_border (int) – Minimum distance of objects to image border [px]
pad_border (int) – Padding of object regions [px]
exclude_overlap (float) – Allowed distance between two objects [px]
threshold (float or str) – Thresholding value or method used; see
drymass.search.available_thresholds
ignore_data (list of str) – Identifiers for sensor images or ROIs to be excluded from further analysis. These will be labeled in the output tiff file and not written to the output qpseries file.
force_roi (tuple) – A tuple describing the slice of the ROI to be extracted ((x1, x2), (y1, y2)). This option invalidates all other keyword arguments. If set to None (default) an automated search for ROIs is performed.
bg_amp_kw (dict or None) – Amplitude image background correction keyword arguments (see
qpimage.QPImage.compute_bg()
), defaults to BG_DEFAULT_KW, set to None to disable correctionbg_amp_bin (float, str, or None) – The amplitude binary threshold value or the method for binary threshold determination; see
skimage.filters
threshold_* methods. Disabled if set to None.bg_amp_mask_radial_clearance (float or None) – If not NaN, use
qpsphere.cnvnc.bg_phase_mask_for_qpi()
to compute a mask image and use it for amplitude background correction. Disabled if set to None.bg_pha_kw (dict or None) – Phase image background correction keyword arguments (see
qpimage.QPImage.compute_bg()
), defaults to BG_DEFAULT_KW, set to None to disable correctionbg_pha_bin (float, str, or None) – The phase binary threshold value or the method for binary threshold determination; see
skimage.filters
threshold_* methods. Disabled if set to None.bg_pha_mask_radial_clearance (float or None) – If not NaN, use
qpsphere.cnvnc.bg_phase_mask_for_qpi()
to compute a mask image and use it for phase background correction. Disabled if set to None.search_enabled (bool) – If True, perform automated search for ROIs using the parameters above. If False, extract the ROIs from FILE_SLICES and only perform background correction using the bg_* parameters.
ret_roimgr (bool) – Return the ROIManager instance of the found ROIs
ret_changed (bool) – Return boolean indicating whether the ROI data on disk was created/updated (True) or whether previously created ROI data was used (False).
count (multiprocessing.Value) – Can be used to monitor the progress of the algorithm. Initially, the value of max_count.value is incremented by the total number of steps. At each step, the value of count.value is incremented.
max_count (multiprocessing.Value) – Can be used to monitor the progress of the algorithm. Initially, the value of max_count.value is incremented by the total number of steps. At each step, the value of count.value is incremented.
Notes
The output hdf5 file dir_out/FILE_ROI_DATA_H5 is a
qpimage.QPSeries
file with the keyword “identifier” consisting of three hashes in the form “hash_data:hash_roiparms:hash_roisexcl”, where “hash_data” is the hash of the source dataset, “hash_roiparms”, is the hash of the ROI extraction configuration, and “hash_roisexcl” is the hash of the ROI indices excluded.
- drymass.extractroi.is_ignored_roi(roi, ignore_data)[source]
Determine whether a specific ROI should be ignored
- Parameters
roi (drymass.roi.ROI) – ROI instance
ignore_data (list of str) – List of strings of the form “image_index” or “image_index.roi_index” that identify ROIs that should be ignored. For instance [“1.0”, “2.1”, “3”].
Helper classes and methods
search
- drymass.search.approx_bg(data, filter_size=None)[source]
Approximate the image background with Gaussian convolution
- Parameters
data (2d ndarray) – Data from which to compute the background
size (float) –
Approximate size of the objects on the background. The size of the Gaussian is heuristically determined with
\[\sigma = 5 \cdot \texttt{size}\]
- Returns
- Return type
Approximate background of data.
- drymass.search.search_objects_base(image, size=110, size_var=0.5, max_ecc=0.7, dist_border=10, threshold='li', verbose=False)[source]
Search objects in images
The wrapper
search_phase_objects()
implements a more robust (heuristic) way of finding objects.- Parameters
image (2d ndarray) – Input image
size (float) – Approximate diameter of phase objects in pixels
size_var (float) – Allowed variation in size (relative to size) for the detected objects
max_ecc (float in interval [0,1)) –
Maximal eccentricity of the objects. The eccentricity of a circle is zero. For an ellipse it is defined as
\[\varepsilon=\sqrt{\frac{a^2-b^2}{a^2}} = \sqrt{1-\left(\frac{b}{a}\right)^2} = f/a.\]dist_border (float) – Minimum distance of detected regions to the borders of the image in pixels
threshold (float or str) – Thresholding value or method used; see
drymass.threshold.available_thresholds
verbose (bool) – If True, print information about ignored regions
- Returns
rois – Found regions
- Return type
list of regionprops
See also
skimage.filters.threshold_otsu
threshold for finding objects
skimage.segmentation.clear_border
remove regions at the border
skimage.morphology.label
identify regions in binary images
- drymass.search.search_phase_objects(qpi, size_m, size_var=0.5, max_ecc=0.7, dist_border=10, pad_border=40, exclude_overlap=30.0, threshold='li', verbose=False)[source]
Search phase objects in quantitative phase images
- Parameters
qpi (qpimage.QPImage) – Quantitative phase data
size_m (float) – Expected size of the phase objects
size_var (float) – Allowed variation in size (relative to size) for the detected objects
max_ecc (float in interval [0,1)) –
Maximal eccentricity of the objects. The eccentricity of a circle is zero. For an ellipse it is defined as
\[\varepsilon=\sqrt{\frac{a^2-b^2}{a^2}} = \sqrt{1-\left(\frac{b}{a}\right)^2} = f/a.\]dist_border (int) – Minimum distance of detected regions to the borders of the image in pixels
pad_border (int) – Pad the regions of all objects
exclude_overlap (float) – Allowed distance in pixels between two detected regions (without pad_border)
threshold (float or str) – Thresholding value or method used; see
drymass.threshold.available_thresholds
verbose (bool) – If True, print information about ignored regions
- Returns
slices
- Return type
list of slice
Notes
Description of the heuristic search algorithm:
Search phase objects in qpi.raw_pha with a background correction computed from the gaussian-filtered image
If no objects were found and qpi.bg_pha is nonzero, search objects in qpi.pha.
Search objects in qpi.bg_pha and remove any overlaps with the previously obtained regions.
See also
search_objects_base
underlying search algorithm
approx_bg
gaussian-filtered background estimation
threshold
There are two types of thresholding done in DryMass.
Thresholding of the sensor image which is required by the detection of the phase object ROIs (
[roi]: threshold
configuration parameter)Thresholding of the individual ROIs for determining the masked area used for ROI background correction (
[bg]: amplitude binary threshold
and[bg]: phase binary threshold
configuration parameters)
- drymass.threshold.image2mask(image, value_or_method, invert=False)[source]
Convert an image to a binary mask for background correction
If invert is False, the threshold value is included in the resulting array.
- Parameters
image (2d np.ndarray) – Input image
value_or_method (float or str) – Either a threshold value or a string naming a filter method in
skimage.filters
.invert (bool) – Invert the resulting boolean array
- drymass.threshold.threshold_drymass_nuclei(image)[source]
Threshold filter for segmenting cell nuclei in phase images
Cell nuclei have a low refractive index, but the nucleoli within the nuclei usually have a very high refractive index. As a result, conventional thresholding algorithms either cannot detect the nuclei reliably or segment the nucleoli only.
This thresholding filter copes with the situation by “pulling down” the top 1% of the phase data and taking the threshold at 20% of the maximum phase relative to the mean of the original phase data.
- drymass.threshold.threshold_dict = {'dm-nuclei': <function threshold_drymass_nuclei>, 'isodata': <function threshold_isodata>, 'li': <function threshold_li>, 'mean': <function threshold_mean>, 'minimum': <function threshold_minimum>, 'otsu': <function threshold_otsu>, 'triangle': <function threshold_triangle>, 'yen': <function threshold_yen>}
Dictionary containing all thresholding methods available in DryMass
- drymass.threshold.available_thresholds = ['dm-nuclei', 'isodata', 'li', 'mean', 'minimum', 'otsu', 'triangle', 'yen']
Available thresholding method names; The thresholding methods are either defined in this module (see threshold_* methods) or taken from
skimage.filters
.
util
Utility methods
- drymass.util.hash_object(obj)[source]
Compute sha256 hex-hash of a Python object
Objects in dicts/lists/tuples are joined together before hashing using
obj2bytes()
in this module.- Returns
hex – The first six characters of the hash
- Return type
roi
The ROIManager
class is used to manage and save/load ROI positions.
In [1]: from drymass.roi import ROIManager
In [2]: rmg = ROIManager(identifier="example")
In [3]: rmg.add(roi_slice=(slice(10, 100), slice(50, 140)),
...: image_index=2,
...: roi_index=0,
...: identifier="example_subroi_2.0")
...:
In [4]: rmg.get_from_image_index(2)
Out[4]: [example_subroi_2.0 2 0 (slice(10, 100, None), slice(50, 140, None))]
Saving and loading can be done with:
In [5]: rmg.save("output_rois.txt")
In [6]: rmg2 = ROIManager(identifier="ex")
In [7]: rmg2.load("output_rois.txt")
And the content of “output_rois.txt” is:
example_subroi_2.0 2 0 (slice(10, 100, None), slice(50, 140, None))