core.utils Module

This module is for the ‘core’ data types.

class skbeam.core.utils.MD_dict(md_dict=None)

Bases: collections.abc.MutableMapping

A class to make dealing with the meta-data scheme for DataExchange easier

Examples

Getting and setting data by path is possible

>>> tt = MD_dict()
>>> tt['name'] = 'test'
>>> tt['nested.a'] = 2
>>> tt['nested.b'] = (5, 'm')
>>> tt['nested.a'].value
2
>>> tt['nested.a'].units is None
True
>>> tt['name'].value
'test'
>>> tt['nested.b'].units
'm'

exception skbeam.core.utils.NotInstalledError

Bases: ImportError

Custom exception that should be subclassed to handle specific missing libraries

class skbeam.core.utils.RCParamDict

Bases: collections.abc.MutableMapping

A class to make dealing with storing default values easier.

RC params is a hold- over from the UNIX days where configuration files are ‘rc’ files. See http://en.wikipedia.org/wiki/Configuration_file

Examples

Getting and setting data by path is possible

>>> tt = RCParamDict()
>>> tt['name'] = 'test'
>>> tt['nested.a'] = 2

skbeam.core.utils.angle_grid(center, shape, pixel_size=None)

Make a grid of angular positions.

Read note for our conventions here – there be dragons!

Parameters

centertuple

point in image where r=0; may be a float giving subpixel precision. Order is (rr, cc).

shape: tuple

Image shape which is used to determine the maximum extent of output pixel coordinates. Order is (rr, cc).

Returns

agridarray

angular position (in radians) of each array element in range [-pi, pi]

skbeam.core.utils.bin_1D(x, y, nx=None, min_x=None, max_x=None)

Bin the values in y based on their x-coordinates

Parameters

xarray

position

yarray

intensity

nxinteger, optional

number of bins to use defaults to default bin value

min_xfloat, optional

Left edge of first bin defaults to minimum value of x

max_xfloat, optional

Right edge of last bin defaults to maximum value of x

Returns

edgesarray

edges of bins, length nx + 1

valarray

sum of values in each bin, length nx

countarray

The number of counts in each bin, length nx

skbeam.core.utils.bin_edges(range_min=None, range_max=None, nbins=None, step=None)

Generate bin edges. The last value in the returned array is the right edge of the last bin, the rest of the values are the left edges of each bin.

If range_max is specified all bin edges will be less than or equal to it’s value.

If range_min is specified all bin edges will be greater than or equal to it’s value

If nbins is specified then there will be than number of bins and the returned array will have length nbins + 1 (as the right most edge is included)

If step is specified then bin width is approximately step (It is not exact due to the nature of floats). The arrays generated by np.cumsum(np.ones(nbins) * step) and np.arange(nbins) * step are not identical. This function uses the second method in all cases where step is specified.

Warning

If the set (range_min, range_max, step) is given there is no guarantee that range_max - range_min is an integer multiple of step. In this case the left most bin edge is range_min and the right most bin edge is less than range_max and the distance between the right most edge and range_max is not greater than step (this is the same behavior as the built-in range()). It is not recommended to specify bins in this manner.

Parameters

range_minfloat, optional

The minimum value that may be included as a bin edge

range_maxfloat, optional

The maximum value that may be included as a bin edge

nbinsint, optional

The number of bins, if specified the length of the returned value will be nbins + 1

stepfloat, optional

The step between the bins

Returns

edgesnp.array

An array of floats for the bin edges. The last value is the right edge of the last bin.

skbeam.core.utils.bin_edges_to_centers(input_edges)

Helper function for turning a array of bin edges into an array of bin centers

Parameters

input_edgesarray-like

N + 1 values which are the left edges of N bins and the right edge of the last bin

Returns

centersndarray

A length N array giving the centers of the bins

skbeam.core.utils.bin_grid(image, r_array, pixel_sizes, statistic='mean', mask=None, bins=None)

Bin and integrate an image, given the radial array of pixels

Parameters

image: np.array

The image in quesion

r_array: np.array

The array which maps pixel positions to tilt/rotation corrected radii

pixel_sizes: tuple

The size of the pixels in the same units as the r_array

statistic: str or func, optional

The statistic to compute over the integration, defaults to mean

mask: bool array, optional

The array of pixels to be removed from the image before integration

bins: array, optional

The bins to use in the integration, if none given the function will give its best assessment based on the pixel_size and r_array

Returns

bin_centersarray

The center of each bin in R

int_statarray

Radial integrated statistic of the image.

See also

circular_average

circularly average an image, assuming linear radial spacing (less general)

skbeam.core.utils.d_to_q(d)

Helper function to convert \(d\) to \(q\). The point of this function is to prevent fat-fingered typos.

By definition the relationship is:

\[d = \frac{2 \pi}{q}\]

Parameters

darray

An array of d (plane) spacing

Returns

qarray

An array of q values in the inverse of the units of d

skbeam.core.utils.geometric_series(common_ratio, number_of_images, first_term=1)

This will provide the geometric series for the integration. Last values of the series has to be less than or equal to number of images ex: number_of_images = 100, first_term =1 common_ratio = 2, geometric_series = 1, 2, 4, 8, 16, 32, 64 common_ratio = 3, geometric_series = 1, 3, 9, 27, 81

Parameters

common_ratiofloat

common ratio of the series

number_of_imagesint

number of images

first_termfloat, optional

first term in the series

Notes

\[a + ar + ar^2 + ar^3 + ar^4 + ...\]

a - first term in the series

r - is the common ratio

skbeam.core.utils.grid3d(q, img_stack, nx=None, ny=None, nz=None, xmin=None, xmax=None, ymin=None, ymax=None, zmin=None, zmax=None, binary_mask=None)

Grid irregularly spaced data points onto a regular grid via histogramming

This function will process the set of reciprocal space values (q), the image stack (img_stack) and grid the image data based on the bounds provided, using defaults if none are provided.

Parameters

qndarray

(Qx, Qy, Qz) - HKL values - Nx3 array

img_stackndarray

Intensity array of the images dimensions are: [num_img][num_rows][num_cols]

nxint, optional

Number of voxels along x

nyint, optional

Number of voxels along y

nzint, optional

Number of voxels along z

xminfloat, optional

Minimum value along x. Defaults to smallest x value in q

yminfloat, optional

Minimum value along y. Defaults to smallest y value in q

zminfloat, optional

Minimum value along z. Defaults to smallest z value in q

xmaxfloat, optional

Maximum value along x. Defaults to largest x value in q

ymaxfloat, optional

Maximum value along y. Defaults to largest y value in q

zmaxfloat, optional

Maximum value along z. Defaults to largest z value in q

binary_maskndarray, optional

The binary mask provides a mechanism to remove unwanted pixels from the images. Binary mask can be two different shapes. - 1: 2-D with binary_mask.shape == np.asarray(img_stack[0]).shape - 2: 3-D with binary_mask.shape == np.asarray(img_stack).shape

Returns

meanndarray

intensity grid. The values in this grid are the mean of the values that fill with in the grid.

occupancyndarray

The number of data points that fell in the grid.

std_errndarray

This is the standard error of the value in the grid box.

boundslist

tuple of (min, max, step) for x, y, z in order: [x_bounds, y_bounds, z_bounds]

skbeam.core.utils.img_to_relative_xyi(img, cx, cy, pixel_size_x=None, pixel_size_y=None)

Convert the 2D image to a list of x y I coordinates where x == x_img - detector_center[0] and y == y_img - detector_center[1]

Parameters

img: `ndarray`

2D image

cxfloat

Image center in the x direction

cyfloat

Image center in the y direction

pixel_size_xfloat, optional

Pixel size in x

pixel_size_yfloat, optional

Pixel size in y

**kwargs: dict

Bucket for extra parameters in an unpacked dictionary

Returns

xndarray

x-coordinate of pixel. shape (N, )

yndarray

y-coordinate of pixel. shape (N, )

Indarray

intensity of pixel. shape (N, )

class skbeam.core.utils.md_value(value, units)

Bases: tuple

property units

Alias for field number 1

property value

Alias for field number 0

skbeam.core.utils.multi_tau_lags(multitau_levels, multitau_channels)

Standard multiple-tau algorithm for finding the lag times (delay times).

Parameters

multitau_levelsint

number of levels of multiple-taus

multitau_channelsint

number of channels or number of buffers in auto-correlators normalizations (must be even)

Returns

total_channelsint

total number of channels ( or total number of delay times)

lag_stepsndarray

delay or lag steps for the multiple tau analysis

dict_lagsdict

dictionary of delays for each multitau_levels

Notes

The multi-tau correlation scheme was used for finding the lag times (delay times).

References: text [1]

1

K. Schätzela, M. Drewela and S. Stimaca, “Photon correlation measurements at large lag times: Improving statistical accuracy,” J. Mod. Opt., vol 35, p 711–718, 1988.

skbeam.core.utils.pairwise(iterable)

s -> (s0,s1), (s1,s2), (s2, s3), …

skbeam.core.utils.q_to_d(q)

Helper function to convert \(d\) to \(q\). The point of this function is to prevent fat-fingered typos.

By definition the relationship is:

\[q = \frac{2 \pi}{d}\]

Parameters

qarray

An array of q values

Returns

darray

An array of d (plane) spacing in the inverse of the units of q

skbeam.core.utils.q_to_twotheta(q, wavelength)

Helper function to convert q to two-theta.

By definition the relationship is:

\[\sin\left(\frac{2\theta}{2}\right) = \frac{\lambda q}{4 \pi}\]

thus

\[2\theta_n = 2 \arcsin\left(\frac{\lambda q}{4 \pi}\right)\]

Parameters

qarray

An array of \(q\) values

wavelengthfloat

Wavelength of the incoming x-rays

Returns

two_thetaarray

An array of \(2\theta\) values in radians

skbeam.core.utils.radial_grid(center, shape, pixel_size=None)

Convert a cartesian grid (x,y) to the radius relative to some center

Parameters

centertuple

point in image where r=0; may be a float giving subpixel precision. Order is (rr, cc).

shapetuple

Image shape which is used to determine the maximum extent of output pixel coordinates. Order is (rr, cc).

pixel_sizesequence, optional

The physical size of the pixels. len(pixel_size) should be the same as len(shape) defaults to (1,1)

Returns

rarray

The distance of each pixel from center Shape of the return value is equal to the shape input parameter

skbeam.core.utils.radius_to_twotheta(dist_sample, radius)

Converts radius from the calibrated center to scattering angle (2:math:2theta) with known detector to sample distance.

Parameters

dist_samplefloat

distance from the sample to the detector (mm)

radiusarray

The L2 norm of the distance of each pixel from the calibrated center.

Returns

two_thetaarray

An array of \(2\theta\) values

skbeam.core.utils.subtract_reference_images(imgs, is_reference)

Function to subtract a series of measured images from background/dark current/reference images. The nearest reference image in the reverse temporal direction is subtracted from each measured image.

Parameters

imgsnumpy.ndarray

Array of 2-D images

is_reference1-D boolean array

true : image is reference image false : image is measured image

Returns

img_corrnumpy.ndarray

len(img_corr) == len(img_arr) - len(is_reference_img == true) img_corr is the array of measured images minus the reference images.

Raises

ValueError

Possible causes:

is_reference contains no true values Raised when the first image in the array is not a reference image.

skbeam.core.utils.twotheta_to_q(two_theta, wavelength)

Helper function to convert two-theta to q

By definition the relationship is

\[\sin\left(\frac{2\theta}{2}\right) = \frac{\lambda q}{4 \pi}\]

thus

\[q = \frac{4 \pi \sin\left(\frac{2\theta}{2}\right)}{\lambda}\]

Parameters

two_thetaarray

An array of \(2\theta\) values

wavelengthfloat

Wavelength of the incoming x-rays

Returns

qarray

An array of \(q\) values in the inverse of the units of wavelength

class skbeam.core.utils.verbosedict

Bases: dict

A sub-class of dict which raises more verbose errors if a key is not found.

skbeam.core.utils.wedge_integration(src_data, center, theta_start, delta_theta, r_inner, delta_r)

Implementation of caking.

Parameters

scr_datandarray

The source-data to be integrated

centerndarray

The center of the ring in pixels

theta_startfloat

The angle of the start of the wedge from the image y-axis in degrees

delta_thetafloat

The angular width of the wedge in degrees. Positive angles go clockwise, negative go counter-clockwise.

r_innerfloat

The inner radius in pixel units, Must be non-negative

delta_rfloat

The length of the wedge in the radial direction in pixel units. Must be non-negative

Returns

float

The integrated intensity under the wedge