# 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.
remove_section(section)[source]

Remove a section from the configuration file

set_value(section, key, value)[source]

Set a configuration key value

Parameters: section (str) – the configuration section key (str) – the configuration key in section value – the configuration key value

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[source]

Ask the user for a configuration key

drymass.cli.dialog.main(path=None, req_meta=[], 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. 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[source]

Obtain the input data set path by parsing the command line

Perform recursive search for supported measurements

drymass.cli.dialog.transfer_meta_data(path_in, path_out)[source]

Read input meta data and write it to the configuration file

### 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.fbool(value)[source]

Boolean value from string or number

drymass.cli.parse_funcs.fintlist(alist)[source]

List of integers from string or list of strings/integers

drymass.cli.parse_funcs.float01(flt)[source]

Float value between 0 and 1

drymass.cli.parse_funcs.float_or_str(flt_or_str)[source]

Float value from string or number

drymass.cli.parse_funcs.floattuple_or_one(fti)[source]

Tuple of two floats or ±1 from a string or a number

drymass.cli.parse_funcs.int_or_path(intpath)[source]

Integer or string from a string or a number

drymass.cli.parse_funcs.lcstr(astr)[source]

Convert a string to lower-case

drymass.cli.parse_funcs.strlist(alist)[source]

List of strings, comma- or space-separated

drymass.cli.parse_funcs.strlist_vsort(alist)[source]

Same as strlist except sorted according to version-representation

drymass.cli.parse_funcs.tupletupleint(items)[source]

A tuple containing x- and y- slice tuples from a string or tuple

### 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. Axis and colorbar. ax [, cbar]
drymass.cli.plot.plot_qpi_phase(qpi, rois=None, path=None, labels_excluded=[])[source]

Plot phase data

drymass.cli.plot.plot_qpi_sphere(qpi_real, qpi_sim, path=None, simtype='simulation')[source]

Plot QPI sphere analysis data

## 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

exception drymass.anasphere.EdgeDetectionFailedWarning[source]
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. max_count (count,) – 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 interest phi_tot, the pixel area deltaA, the refractive index of the medium n_med (stored in qpi.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. dry_mass – The absolute dry mass of the sphere [g] float
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. dry_mass – The relative dry mass of the object [g] float

### 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={}, holo_kw={}, 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) – Meta data (see qpimage.meta.DATA_KEYS) bg_data_pha (bg_data_amp,) – 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 max_count (count,) – 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). bg – The background data. 2d np.ndarray
drymass.converter.h5series2tif(h5in, tifout)[source]

Convert a qpimage.QPSeries file to a phase/amplitude TIFF file

### 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 correction bg_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 correction bg_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). max_count (count,) – 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}$ 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 rois – Found regions list of regionprops

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 slices list of slice

Notes

Description of the heuristic search algorithm:

1. Search phase objects in qpi.raw_pha with a background correction computed from the gaussian-filtered image
2. If no objects were found and qpi.bg_pha is nonzero, search objects in qpi.pha.
3. Search objects in qpi.bg_pha and remove any overlaps with the previously obtained regions.

search_objects_base()
underlying search algorithm
approx_bg()
gaussian-filtered background estimation

### threshold¶

There are two types of thresholding done in DryMass.

1. Thresholding of the sensor image which is required by the detection of the phase object ROIs ([roi]: threshold configuration parameter)
2. 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_li(image)[source]

Li threshold optimized for cells in QPI

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_file(path, blocksize=65536)[source]

Compute sha256 hex-hash of a file

Parameters: path (str) – path to the file blocksize (int) – block size read from the file hex – The first six characters of the hash str
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 str
drymass.util.is_series_file(path)[source]

Return True if path is a qpimage.QPSeries file with identifier

drymass.util.obj2bytes(obj)[source]

String representation of an object for hashing

### 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))]


In [5]: rmg.save("output_rois.txt")

In [6]: rmg2 = ROIManager(identifier="ex")


example_subroi_2.0      2       0       (slice(10, 100, None), slice(50, 140, None))

exception drymass.roi.ROIManagerWarning[source]