azimuthalaverage¶

This module contains the azimuthal average data class and the method to compute the azimuthal average from the image structure function.

The azimuthal average can be computed from the image structure function as

import fastddm as fddm

# compute image structure function dqt
...

# compute azimuthal average masking out the central cross
mask = fddm.mask.central_cross_mask(dqt.full_shape()[1:])
aa = fddm.azimuthal_average(dqt, bins=bins, range=(0, dqt.ky[-1]), mask=mask)

The AzimuthalAverage object is used to store and retrieve information about the azimuthal average of the image structure function computed in DDM.

The AzimuthalAverage.data contains the values of the azimuthal average of the image structure function in \((k, \Delta t)\) order. For instance, the azimuthal average at the 20th wave vector can be accessed via

aa.data[19]

Note

Remember that Python uses zero-based indexing.

The AzimuthalAverage can then be saved into a binary file by using AzimuthalAverage.save() (it will have a .aa.ddm extension) and later retrieved from the memory using AAReader.load(), which you can call directly from fastddm as

# load image structure function
dqt = fastddm.load('path/to/my_aa_file.aa.ddm')

Loading the AzimuthalAverage from disk is not as demanding as for the ImageStructureFunction. However, also in this case we provide a fast reader through the AAReader, which can be used to access directly from the disk the relevant data, for example:

from fastddm.azimuthalaverage import AAReader

# open file
r = AAReader('path/to/my_aa_file.aa.ddm')

# access quantities
# access tau array
tau = r.get_tau()
# access data for 20th k bin
y = r.get_k_slice(k_index=19)

class fastddm.azimuthalaverage.AAParser(fh: BinaryIO)¶

Azimuthal average file parser class. Inherits from Parser.

read_metadata() → dict¶

Read metadata from the binary file.

Returns:: The metadata dictionary.
Return type:: dict

class fastddm.azimuthalaverage.AAReader(file: str)¶

FastDDM azimuthal average reader class. Inherits from Reader.

get_bin_edges() → ndarray¶

Read bin_edges array from file.

Returns:: The bin_edges array.
Return type:: numpy.ndarray

get_k() → ndarray¶

Read k array from file.

Returns:: The k array.
Return type:: numpy.ndarray

get_k_slice(k_index: int) → ndarray¶

Read a slice at k_index from data.

Parameters:: k_index (int) – The k index
Returns:: The data at k vs tau.
Return type:: numpy.ndarray
Raises:: IndexError – If k_index is out of range.

get_k_slice_err(k_index: int) → ndarray¶

Read a slice of uncertainty at k_index from data.

Parameters:: k_index (int) – The k index
Returns:: The uncertainty of data at k vs tau.
Return type:: numpy.ndarray
Raises:: IndexError – If k_index is out of range.

get_tau() → ndarray¶

Read tau array from file.

Returns:: The tau array.
Return type:: numpy.ndarray

load() → AzimuthalAverage¶

Load azimuthal average from file.

Returns:: The AzimuthalAverage object.
Return type:: AzimuthalAverage
Raises:: IOError – If file version not supported.

class fastddm.azimuthalaverage.AAWriter(file: str)¶

Azimuthal average writer class. Inherits from Writer.

It adds the unique method write_obj.

Defines the functions to write AzimuthalAverage object to binary file.

The structure of the binary file is the following:

Header:

bytes 0-1: endianness, string, utf-8 encoding ["LL" = ‘little’, "BB" = ‘big’]
bytes 2-3: file identifier, 16-bit integer, unsigned short [22 for azimuthal average]
bytes 4-5: file version, pair of 8-bit integers as (major_version, minor_version), unsigned char
byte 6: dtype, string, utf-8 encoding ["d" = float64, "f" = float32]
bytes 7-14: data height, 64-bit integer, unsigned long long
bytes 15-22: data width, 64-bit integer, unsigned long long
bytes 23-30: extra slices, 64-bit integer, unsigned long long
byte 31: flag for standard deviation of data, 8-bit integer, unsigned char [0 if err is None, 1 if it is stored in the dataclass]

The data is stored in ‘C’ order and dtype format as follows:

from byte data_offset: _data
from byte err_offset: _err
from byte k_offset: k array
from byte tau_offset: tau array
from byte bin_edges_offset: bin_edges array

From the end of the file, the byte offsets are stored as unsigned long long 64-bit integers in this order:

data_offset
err_offset
k_offset
tau_offset
bin_edges_offset

write_obj(obj: AzimuthalAverage) → None¶

Write AzimuthalAverage object to binary file.

Parameters:: obj (AzimuthalAverage) – AzimuthalAverage object.

class fastddm.azimuthalaverage.AzimuthalAverage(_data: ndarray, _err: ndarray, k: ndarray, tau: ndarray, bin_edges: ndarray)¶

Azimuthal average container class.

Parameters:

_data (numpy.ndarray) – The packed data (azimuthal average of image structure function, power spectrum, and variance).
_err (numpy.ndarray) – The packed uncertainties (uncertainty of the azimuthal average, power spectrum, and variance).
k (numpy.ndarray) – The array of reference wavevector values in the bins.
tau (numpy.ndarray) – The array of time delay values.
bin_edges (numpy.ndarray) – The array of bin edges.

resample(tau: ndarray) → AzimuthalAverage¶

Resample with new tau values and return a new AzimuthalAverage.

Parameters:: tau (numpy.ndarray) – New values of tau.
Returns:: The resampled azimuthal average.
Return type:: AzimuthalAverage

save(fname: str = 'analysis_blob') → None¶

Save AzimuthalAverage to binary file.

Parameters:: fname (str, optional) – The full file name, by default “analysis_blob”.

property data: ndarray¶

The azimuthal average of the 2D image structure function.

Returns:: The azimuthal average data.
Return type:: numpy.ndarray

property err: ndarray¶

The uncertainty (standard deviation) in the azimuthal average of the 2D image structure function.

Returns:: The uncertainty.
Return type:: numpy.ndarray

property power_spec: ndarray¶

The azimuthal average of the average 2D power spectrum of the input images.

Returns:: The azimuthal average of the power spectrum.
Return type:: numpy.ndarray

property power_spec_err: ndarray¶

The uncertainty in the azimuthal average of the average 2D power spectrum of the input images.

Returns:: The uncertainty in the azimuthal average of the power spectrum.
Return type:: numpy.ndarray

property shape: Tuple[int, int]¶

The shape of the azimuthal average data.

Returns:: The shape of the data.
Return type:: Tuple[int, int]

property var: ndarray¶

The azimuthal average of the 2D variance (over time) of the Fourier transformed input images.

Returns:: The azimuthal average of the variance.
Return type:: numpy.ndarray

property var_err: ndarray¶

The uncertainty in the azimuthal average of the 2D variance (over time) of the Fourier transformed input images.

Returns:: The uncertainty in the azimuthal average of the variance.
Return type:: numpy.ndarray

Compute the azimuthal average of the image structure function.

For every bin \(i\), the average is calculated as

\[\bar{x}_i = \frac{\sum_k w_k x_k}{\sum_k w_k} ,\]

where \(w_k\) is the weight given to the wavevector \(k\). The sum runs over the elements \(k \in \mathcal{S}_i\), where \(\mathcal{S}_i\) is the subset of wavevector \(k\) with modulus in the bin \(i\). The mask allows to exclude certain wavevectors from the calculation. The uncertainty is calculated as the square root of the unbiased variance for weighed measures

\[\text{VAR}(x_i) = \frac{\sum_k w_k (x_k - \bar{x}_i)^2}{\sum_k w_k - \sum_k w_k^2 / \sum_k w_k}.\]

Parameters:

img_str_func (ImageStructureFunction) – The image structure function.
bins (Union[int, Iterable[float]], optional) – If bins is an int, it defines the number of equal-width bins in the given range (10, by default). If bins is a sequence, it defines a monotonically increasing array of bin edges, including the rightmost edge, allowing for non-uniform bin widths.
range (Tuple[float, float], optional) – The lower and upper range of the bins. If not provided, range is simply (k.min(), k.max()), where k is the vector modulus computed from kx and ky. Values outside the range are ignored. The first element of the range must be less than or equal to the second.
mask (numpy.ndarray, optional) – If a boolean mask is given, it is used to exclude grid points from the azimuthal average (where False is set). The array must have the same (y, x) shape of data. If mask is not of boolean type, it is cast to booland a warning is raised.
weights (numpy.ndarray, optional) – An array of weights, of the same (y, x) shape as data. Each value in data only contributes its associated weight towards the bin count (instead of 1).
eval_err (bool, optional) – If True, the uncertainty is computed. Default is True.

Returns:

The azimuthal average.

Return type:

AzimuthalAverage

Compute the azimuthal average of a 3D array.

For every bin \(k\), the average is calculated as

\[\bar{x}_k = \frac{\sum_i w_i x_i}{\sum_i w_i} ,\]

where \(w_i\) is the weight given to the pixel \(i\). The sum runs over the elements \(i \in \mathcal{S}_k\), where \(\mathcal{S}_k\) is the subset of elements \(i\) with distance dist in the bin. The mask allows to exclude certain pixels from the calculation. A pixel \(i\) is counted as many times as indicated by counts. The uncertainty is calculated as the square root of the unbiased variance for weighed measures

\[\text{VAR}(x_k) = \frac{\sum_i w_i (x_i - \bar{x}_k)^2}{\sum_i w_i - \sum_i w_i^2 / \sum_i w_i}.\]

Parameters:

data (numpy.ndarray) – The 3D input array.
dist (numpy.ndarray) – A 2D array storing the distances from a center. The array must have the same y, x shape as data.
bins (Union[int, Iterable[float]], optional) – If bins is an int, it defines the number of equal-width bins in the given range (10, by default). If bins is a sequence, it defines a monotonically increasing array of bin edges, including the rightmost edge, allowing for non-uniform bin widths.
range ((float, float), optional) – The lower and upper range of the bins. If not provided, range is simply (dist.min(), dist.max()). Values outside the range are ignored.
mask (numpy.ndarray, optional) – If a boolean mask is given, it is used to exclude points from the azimuthal average (where False is set). The array must have the same shape of dist. If mask is not of boolean type, it is cast and a warning is raised.
weights (numpy.ndarray, optional) – An array of non-negative weights, of the same shape as dist. Each value in data and dist only contributes its associated weight (instead of 1).
counts (numpy.ndarray, optional) – An array of bin counts, of the same shape as dist. Each value in data and dist is sampled its associated number of counts (instead of 1).
eval_err (bool, optional) – If True, the uncertainty is computed. Default is True.

Returns:

The azimuthal average, its uncertainty, the distances, and the bin edges.

Return type:

Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

Raises:

ValueError – If dist, mask, weights, or counts are not compatible with shape of data.

fastddm.azimuthalaverage.melt(az_avg1: AzimuthalAverage, az_avg2: AzimuthalAverage) → AzimuthalAverage¶

Melt two azimuthal averages into one object.

The melt is performed as follows:

the “slow” acquisition is identified as the az_avg having the largest .tau[0] value
the first 10 data points are taken from the “slow” az_avg
data points from the “fast” az_avg at the time delays of the first 10 tau of the “slow” az_avg are obtained via cubic interpolation of the log-log scaled fast data
a multiplicative correction factor is obtained via least squares minimization and the “fast” data points are scaled onto the “slow” ones