Utils API

config_verifier

cohere_core.config_verifier

Verification of configuration parameters.

cohere_core.utilities.config_verifier.verify(config_name, conf_map)

Verifies parameters.

Parameters:

  • config_name -- name of config to be verified. Supported: config_data, config_rec, config_disp.

  • conf_map -- dict with the parameters to verify. It defaults to None.

Returns:

0 if successful, -1 otherwise. In debug mode will re-raise exception instead of returning -1.

utils

cohere_core.utils

This module is a suite of utility functions.

cohere_core.utilities.utils.adjust_dimensions(arr, pads, next_fast_len=True, pkg='np')

This function adds to or subtracts from each dimension of the array elements defined by pad. If the pad is positive, the array is padded in this dimension. If the pad is negative, the array is cropped.

Parameters:

  • arr -- ndarray, the array to pad/crop

  • pad -- list of pad values, a tuple of two int for each dimension. The values in each tuple will be added/subtracted to the sides of array in corresponding dimension.

  • next_fast_len -- bool, whether or not to find the next fast length for each dimension

  • pkg -- package acronym: 'cp' for cupy, 'torch' for torch, 'np' for numpy

Returns:

the padded/cropped and adjusted to opencl compatible format array

cohere_core.utilities.utils.binning(array, binsizes)

This function does the binning of the array. The array is binned in each dimension by the corresponding binsizes elements. If binsizes list is shorter than the array dimensions, the remaining dimensions are not binned.

Parameters:

  • array -- ndarray the original array to be binned

  • binsizes -- a list defining binning factors for corresponding dimensions

Returns:

binned array

cohere_core.utilities.utils.center_max(arr)

Finds maximum value in the array, and shifts in each dimension to put the max in a center.

Parameters:

arr -- ndarray, array to be centered

Returns:

centered array

cohere_core.utilities.utils.crop_center(arr, new_shape)

This function crops the array to the new size, keeping the center of the array. The new_size must be smaller or equal to the original size in each dimension.

Parameters:

  • arr -- ndarray, the array to crop

  • new_shape -- tuple, new size

Returns:

cropped array

cohere_core.utilities.utils.get_central_object_extent(fp: numpy.ndarray) → list

Calculates extent of central cluster.

Parameters:

fp -- ndarray tofind extend for

Returns:

list, an extend

cohere_core.utilities.utils.get_good_dim(dim, pkg)

Returns the even dimension that the given package found to be good for fast Fourier transform and not smaller than given dimension. .

Parameters:

  • dim -- int, initial dimension

  • pck -- python package that will be used for reconstruction: 'np' for numpy, 'cp' for cupy, 'torch' for torch.

Returns:

a new dimension

cohere_core.utilities.utils.get_lib(pkg)

Dynamically imports library module specified in input.

Parameters:

pkg -- package acronym

Returns:

object, library module

cohere_core.utilities.utils.get_logger(name, ldir='')

Creates looger instance that will write to default.log file in a given directory.

Parameters:

  • name -- str, logger name

  • ldir -- str, directory where to create log file

Returns:

logger object from logging module

cohere_core.utilities.utils.get_oversample_ratio(fp: numpy.ndarray) → numpy.ndarray

Author: Yudong Yao

Calculates oversampling ratio.

Parameters:

fp -- ndarray to calculate oversampling ratio

Returns:

oversample ratio in each dimension

cohere_core.utilities.utils.join(*args)

Operation on path. Joins arguments in Path string and replaces OS separators with Linux type separators.

Parameters:

args -- variable number of arguments

Returns:

path

cohere_core.utilities.utils.normalize(vec)

Normalizes vector.

Parameters:

vec -- vector

Returns:

normalized vector

cohere_core.utilities.utils.pad_center(arr, new_shape)

This function pads the array with zeros to the new shape with the array in the center.

Parameters:

  • arr -- ndarray, the original array to be padded

  • new_shape -- tuple, new dimensions

Returns:

the zero padded centered array

cohere_core.utilities.utils.read_config(config)

Checks if the file exists and parses it into a dictionary.

Parameters:

config -- str, configuration file name

Returns:

dictionary containing parsed configuration, None if the given file does not exist

cohere_core.utilities.utils.read_tif(filename)

This method reads tif type file and returns the data as ndarray.

Parameters:

filename -- file name

Returns:

ndarray with the tif file data

cohere_core.utilities.utils.resample(IN, dim)

Author: Yudong Yao

Resamples to new dimensions.

Parameters:

  • IN -- ndarray

  • dim -- new dim

Returns:

resampled array

cohere_core.utilities.utils.save_metrics(errs, dir, metrics=None)

Saves arrays metrics and errors by iterations in text file.

Parameters:

  • errs -- list of "chi" error by iteration

  • dir -- directory to write the file containing array metrics

  • metrics -- dictionary with metric type keys, and metric values

cohere_core.utilities.utils.save_tif(arr, filename)

Saves array in tif format file.

Parameters:

  • arr -- ndarray, array to save

  • filename -- file name

cohere_core.utilities.utils.select_central_object(fp: numpy.ndarray) → numpy.ndarray

Author: Yudong Yao

Returns array with central object from input array.

Parameters:

fp -- array

Returns:

central object array

cohere_core.utilities.utils.threshold_by_edge(fp: numpy.ndarray) → numpy.ndarray

Author: Yudong Yao

Parameters:

fp

Returns:

cohere_core.utilities.utils.write_config(param_dict, config)

Writes configuration to a file.

Parameters:

  • param_dict -- dictionary containing configuration parameters

  • config -- configuration file name the parameters will be written into

cohere_core.utilities.utils.write_plot_errors(save_dir)

Creates python executable that draw plot of error by iteration. It assumes that the given directory contains "errors.npy" file

Parameters:

save_dir -- directory containing errors.npy file

dvc_utils

cohere_core.utilities.dvc_utils

This module is a suite of utility functions.

The function in this module operate on arrays loaded on device. The array can be in CPU memory or GPU memory, and is in format related to the package used to create the array. Therefore, before using functions from this module user must set the global variable devlib by calling function set_lib_from_pkg.

cohere_core.utilities.dvc_utils.align_arrays_pixel(ref, arr, shift=None, CC=None)

Aligns two arrays of the same dimensions with the pixel resolution. Used in reciprocal space.

Parameters:

  • ref -- ndarray, array to align with

  • arr -- ndarray, array to align

Returns:

aligned array

cohere_core.utilities.dvc_utils.align_arrays_subpixel(ref_arr, arr)

Shifts array to align with reference array.

Parameters:

  • ref_arr -- ndarray, reference array

  • arr -- ndarray, array to shift

Returns:

aligned array

cohere_core.utilities.dvc_utils.all_metrics(image, errs)

Calculates array characteristic based on various formulas and additional input. Is used to quntify result of image reconstruction.

Parameters:

  • image -- ndarray, array to get characteristic

  • errs -- list of floats

Returns:

dict, calculated metrics for different formulas

cohere_core.utilities.dvc_utils.arr_property(arr)

Used only in development. Prints array statistics.

Parameters:

arr -- ndarray, array to find max

cohere_core.utilities.dvc_utils.breed(breed_mode, alpha, image)

Aligns the image to breed from with the alpha image, and applies breed formula, to obtain a 'child' image.

Parameters:

  • breed_mode -- str, literal defining the breeding process

  • alpha -- array, the best image in the generation

  • image -- array, the image to breed with alpha

Returns:

array, the bred child

cohere_core.utilities.dvc_utils.center_sync(image, support, center_phase=True)

Shifts the image and support arrays so the center of mass is in the center of array.

Parameters:

  • image -- array, the image to shift

  • support -- array, the support array to shift along with image

Returns:

shifted arrays

cohere_core.utilities.dvc_utils.check_get_conj_reflect(arr1, arr2)

It returns the array of interest or conjugate reflection of that array depending whether it is reflection of the reference array.

Parameters:

  • arr1 -- array, reference array

  • arr2 -- array, array of interest

Returns:

arr2 or conjugate reflection of it

cohere_core.utilities.dvc_utils.conj_reflect(arr)

This function computes conjugate reflection of array.

Parameters:

arr -- array, input array

Returns:

conjugate reflection array

cohere_core.utilities.dvc_utils.correlation_err(refarr, arr, CC=None)

author: Paul Frosik The method is based on "Invariant error metrics for image reconstruction" by J. R. Fienup. Returns correlation error between two arrays.

Parameters:

  • refarr -- reference array

  • arr -- array to measure likeness with reference array

  • CC -- cross-correlation, if computed before, defaults to None

Returns:

float, correlation error

cohere_core.utilities.dvc_utils.cross_correlation(a, b)

This function computes cross correlation of two arrays.

Parameters:

  • a -- input array for cross correlation

  • b -- input array for cross correlation

Returns:

cross correlation array

cohere_core.utilities.dvc_utils.dftregistration(ref_arr, arr, usfac=2)

Efficient subpixel image registration by crosscorrelation. Based on Matlab dftregistration by Manuel Guizar (Portions of this code were taken from code written by Ann M. Kowalczyk and James R. Fienup.)

Parameters:

  • ref_arr -- 2D array, Fourier transform of reference image

  • arr -- 2D array, Fourier transform of image to register

  • usfac -- int, upsampling factor

Returns:

pixel shifts between images: (row_shift, col_shift)

cohere_core.utilities.dvc_utils.dftups(arr, nor=-1, noc=-1, usfac=2, roff=0, coff=0)

Upsample DFT by array multiplies.

Parameters:

  • arr -- array, the subject of upsampling

  • nor -- int, number of pixels in the output upsampled DFT, in units of upsampled pixels

  • noc -- int, number of pixels in the output upsampled DFT, in units of upsampled pixels

  • usfac -- int, upsampling factor (default usfac = 1)

  • roff -- int, row offset, allow to shift the output array to a region of interest on the DFT

  • coff -- int, column offsets, allow to shift the output array to a region of interest on the DFT

Returns:

upsampled array

cohere_core.utilities.dvc_utils.fast_shift(arr, shifty, fill_val=0)

Shifts array by the shifty parameter.

Parameters:

  • arr -- array to shift

  • shifty -- an array of integers/shifts in each dimension

  • fill_val -- float, value to fill shifted, defaults to 0

Returns:

shifted array

cohere_core.utilities.dvc_utils.gauss_conv_fft(arr, distribution)

Calculates convolution of array and gaussian distribution.

Parameters:

  • arr -- array

  • distribution -- gaussian distribution array

Returns:

convolution array

cohere_core.utilities.dvc_utils.get_ccamax_cc(ref, arr, mode='same', method='fft', CC=None)

Calculates index of max cross correlation and correlation

Parameters:

  • ref -- referrence array

  • arr -- array

  • mode

  • method

  • CC -- cross correlation array if exists

Returns:

index of max in cross correlation array and correlation

cohere_core.utilities.dvc_utils.get_metric(image, errs, metric_type)

Callculates array quantified characteristic for given metric type. Is used to quntify result of image reconstruction.

Parameters:

  • arr -- array to get the metric

  • errs -- list of "chi" errors by iteration

  • metric_type -- str defining metric type

Returns:

calculated metric for a given type

cohere_core.utilities.dvc_utils.get_norm(arr)

Calculates norm of array.

Parameters:

arr -- array to calculate norm for

Returns:

float, norm value

cohere_core.utilities.dvc_utils.histogram2d(arr1, arr2, n_bins=100, log=False)

Returns histogram.

Parameters:

  • arr1 -- array

  • arr2 -- array

  • n_bins -- number of bins, defaults to 100

  • log -- boolean, if True, return logarhitmic histogram, linear otherwise

Returns:

histogram

cohere_core.utilities.dvc_utils.lucy_deconvolution(pristine, blurred, kernel, iterations, diffbreak=0)

Performs Richardson-Lucy deconvolution.

Parameters:

  • pristine -- array, input degraded image

  • blurred -- array, blurred image

  • kernel -- array, point spread function

  • iterations -- number of iteration

Diffbrake:

float, if greater than 0, the iterations will brake if error reaches that value

Returns:

deconvolved array

cohere_core.utilities.dvc_utils.pad_around(arr, shape, val=0)

Pads an array evenly at each side, to the given shape. It is assumed that the new shape is greater than shape of the array in each dimension.

Parameters:

  • arr -- array to pad

  • shape -- list or tuple, new shape

Returns:

padded array

cohere_core.utilities.dvc_utils.pad_to_cube(data, size)

Pads a given 3D array to the cube of a given size. If any dimension is greater than the given size, the array will be cropped.

Parameters:

  • data -- array to shape into cube

  • size -- int, size of the cube

Returns:

the padded/cropped array to the cube

cohere_core.utilities.dvc_utils.register_3d_reconstruction(ref_arr, arr)

Finds pixel shifts between reconstructed images

Parameters:

  • ref_arr -- Fourier transform of reference image

  • arr -- Fourier transform of image to register

Returns:

tuple of floats, pixel shifts between images

cohere_core.utilities.dvc_utils.remove_ramp(arr, ups=1)

Smooths image array.

Parameters:

  • arr -- array to remove ramp

  • ups -- int, upsample factor, defaults to 1

Returns:

smoothed array

cohere_core.utilities.dvc_utils.resample(data, matrix, plot=False)

Resamples data and creates plot.

Parameters:

  • data -- data array

  • matrix -- matrix array

  • plot -- boolean, will plot if True, defaults to False.

Returns:

smoothed array

cohere_core.utilities.dvc_utils.set_lib_from_pkg(pkg)

Sets the devlib according to the package specified in input.

This function must be called before using functions from this module. The global variable devlib becomes the library that will be used in this file. The library is referencing to cohere_core.lib.cplib, orcohere_core.lib.nplib, orcohere_core.lib.torchlib.

Parameters:

pkg -- acronym specifying library: 'cp' for cupy, 'np' for numpy, 'tprch' for torch

Returns:

cohere_core.utilities.dvc_utils.shift_phase(arr, val=0)

Adjusts phase accross the array so the relative phase stays intact, but it shifts towards given value.

Parameters:

  • arr -- array to adjust phase

  • val -- float, a value to adjust the phase toward

Returns:

input array with adjusted phase

cohere_core.utilities.dvc_utils.shrink_wrap(arr, threshold, sigma)

Calculates support array applying gaussian filter to the array. Support is array of 0 and 1 values, determined by threshold applyed to the filtered array.

Parameters:

  • arr -- subject array

  • threshold -- float, support is formed by points above this value

  • sigma -- float, sigma for gaussian filter

Returns:

support array

cohere_core.utilities.dvc_utils.sub_pixel_shift(arr, row_shift, col_shift, z_shift)

Shifts pixels in a regularly sampled LR image with a subpixel precision according to local gradient.

Parameters:

  • arr -- array to shift

  • row_shift -- float, shift in x dimension

  • col_shift -- float, shift in y dimension

  • z_shift -- float, shift in z dimension

Returns:

shifted array

cohere_core.utilities.dvc_utils.use_numpy(func)

Function decorator that converts devlib arrays (e.g. cupy arrays, torch tensors, etc.) into numpy arrays before passing them into the function.

cohere_core.utilities.dvc_utils.zero_phase(arr)

Adjusts phase accross the array so the relative phase stays intact, but it shifts towards zero.

Parameters:

arr -- array to adjust phase

Returns:

input array with adjusted phase

cohere_core.utilities.dvc_utils.zero_phase_cc(arr1, arr2)

Sets avarage phase in array to reference array.

Parameters:

  • arr1 -- array to adjust phase

  • arr2 -- reference array

Returns:

input array with adjusted phase