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
.
- 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:
- 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
atk
vstau
.- Return type:
- 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
fromdata
.- Parameters:
k_index (int) – The
k
index- Returns:
The uncertainty of
data
atk
vstau
.- Return type:
- Raises:
IndexError – If
k_index
is out of range.
- load() AzimuthalAverage #
Load azimuthal average from file.
- Returns:
The
AzimuthalAverage
object.- Return type:
- Raises:
IOError – If file version not supported.
- class fastddm.azimuthalaverage.AAWriter(file: str)#
FastDDM azimuthal average writer class. Inherits from
Writer
.- 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 newAzimuthalAverage
.- Parameters:
tau (numpy.ndarray) – New values of
tau
.- Returns:
The resampled azimuthal average.
- Return type:
- 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:
- property err: ndarray#
The uncertainty (standard deviation) in the azimuthal average of the 2D image structure function.
- Returns:
The uncertainty.
- Return type:
- 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:
- 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:
- 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:
- fastddm.azimuthalaverage.azimuthal_average(img_str_func: ImageStructureFunction, bins: int | Iterable[float] | None = 10, range: Tuple[float, float] | None = None, mask: ndarray | None = None, weights: ndarray | None = None, eval_err: bool | None = True) AzimuthalAverage #
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). Ifbins
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())
, wherek
is the vector modulus computed fromkx
andky
. 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 ofdata
. Ifmask
is not of boolean type, it is cast to booland awarning
is raised.weights (numpy.ndarray, optional) – An array of weights, of the same
(y, x)
shape asdata
. Each value indata
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:
- fastddm.azimuthalaverage.azimuthal_average_array(data: ndarray, dist: ndarray, bins: int | Iterable[float] | None = 10, range: Tuple[float, float] | None = None, mask: ndarray | None = None, weights: ndarray | None = None, counts: ndarray | None = None, eval_err: bool | None = True) Tuple[ndarray, ...] #
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. Themask
allows to exclude certain pixels from the calculation. A pixel \(i\) is counted as many times as indicated bycounts
. 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). Ifbins
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 ofdist
. Ifmask
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 indata
anddist
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 indata
anddist
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
, orcounts
are not compatible with shape ofdata
.
- 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]
valuethe 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 10tau
of the “slow”az_avg
are obtained via cubic interpolation of the log-log scaled fast dataa multiplicative correction factor is obtained via least squares minimization and the “fast” data points are scaled onto the “slow” ones
The
var
andpower_spec
are taken from the “slow”az_avg
.- Parameters:
az_avg1 (AzimuthalAverage) – One
AzimuthalAverage
object.az_avg2 (AzimuthalAverage) – Another
AzimuthalAverage
object.
- Returns:
The two
AzimuthalAverage
objects, merged into a new one.- Return type:
- fastddm.azimuthalaverage.mergesort(az_avg1: AzimuthalAverage, az_avg2: AzimuthalAverage) AzimuthalAverage #
Merge the values of two azimuthal averages.
Values will then be sorted based on
tau
.- Parameters:
az_avg1 (AzimuthalAverage) – One
AzimuthalAverage
object.az_avg2 (AzimuthalAverage) – Another
AzimuthalAverage
object.
- Returns:
The two
AzimuthalAverage
objects are fused into a new one.- Return type: