intermediatescatteringfunction

Intermediate scattering function data class, and auxiliary classes and methods.

The IntermediateScatteringFunction object is used to store and retrieve information about the intermediate scattering function (ISF). The ISF can be estimated from the azimuthally averaged Image Structure Function, if some assumptions about the functional shape of the Image Structure Function are made. The method intermediatescatteringfunction.azavg2isf_estimate() provides this functionality, by assuming a basic functional shape of the image structure function \(D(q,\Delta t) = A(q)\left[ 1 - ISF(q, \Delta t) \right] + B(q)\). For more information see the docstring.

The IntermediateScatteringFunction.data contains the ISF values in \((k, \Delta t)\) order. For instance, the ISF computed at the 10th k vector bin can be accessed via

isf.data[9]

Note

Remember that Python uses zero-based indexing.

The IntermediateScatteringFunction can then be saved into a binary file by using IntermediateScatteringFunction.save() (by default called analysis_blob, with the extension .isf.ddm) and later retrieved from the memory using ISFReader.load(), which you can call directly from fastddm as

# load intermediate scattering function
isf = fastddm.load("path/to/my_isf_file.isf.ddm")

In order to avoid reading and loading the entire file, we also provide a fast reader through the ISFReader, which can be used to access directly from the disk the relevant data, for example:

from fastddm.intermediatescatteringfunction import ISFReader

# open file
r = ISFReader("path/to/my_isf_file.isf.ddm")

# access quantities
# access k array
k = r.get_k()

# access delays/lags
dt = r.get_tau()

# access a slice of the ISF for the sixth k value
isf_slice = r.get_k_slice(k_index=5)
class fastddm.intermediatescatteringfunction.ISFParser(fh: BinaryIO)

Intermediate scattering function file parser class.

Inherits from Parser.

read_metadata() → dict

Read metadata from the binary file.

Returns:

The metadata dictionary.

Return type:

dict

class fastddm.intermediatescatteringfunction.ISFReader(file: str)

FastDDM intermediate scattering function 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 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 | None

Read a slice of uncertainty at k 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() → IntermediateScatteringFunction

Load intermediate scattering function from file.

Returns:

The IntermediateScatteringFunction object.

Return type:

IntermediateScatteringFunction

Raises:

IOError – If file version not supported.

class fastddm.intermediatescatteringfunction.ISFWriter(file: str)

Intermediate scattering function writer class. Inherits from Writer.

It adds the unique method write_obj.

Defines the functions to write IntermediateScatteringFunction 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 [43 for intermediate scattering function]

  • 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: IntermediateScatteringFunction) → None

Write IntermediateScatteringFunction object to binary file.

Parameters:

obj (IntermediateScatteringFunction) – IntermediateScatteringFunction object.

class fastddm.intermediatescatteringfunction.IntermediateScatteringFunction(_data: ndarray, _err: ndarray | None, k: ndarray, tau: ndarray, bin_edges: ndarray)

Intermediate scattering function container class.

Parameters:

  • _data (numpy.ndarray) – The data (intermediate scattering function).

  • _err (Optional[numpy.ndarray]) – The uncertainties (uncertainty of the intermediate scattering function).

  • 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 (from the azimuthal average of the image structure function).

resample(tau: ndarray) → IntermediateScatteringFunction

Resample with new tau values and return a new IntermediateScatteringFunction.

Parameters:

tau (numpy.ndarray) – New values of tau.

Returns:

A new instance of the resampled intermediate scattering function.

Return type:

IntermediateScatteringFunction

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

Save IntermediateScatteringFunction to binary file.

Parameters:

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

property data: ndarray

The intermediate scattering function.

Returns:

The intermediate scattering function data.

Return type:

numpy.ndarray

property err: ndarray | None

The uncertainty (standard deviation) in the intermediate scattering function.

Returns:

The uncertainty.

Return type:

numpy.ndarray | None

property shape: Tuple[int, int]

The shape of the azimuthal average data.

Returns:

The shape of the data.

Return type:

Tuple[int, int]

fastddm.intermediatescatteringfunction.azavg2isf_estimate(az_avg: AzimuthalAverage, noise_est: str = 'polyfit', plateau_est: str = 'var', noise: ndarray | None = None, noise_err: ndarray | None = None, plateau: ndarray | None = None, plateau_err: ndarray | None = None, **kwargs) → IntermediateScatteringFunction

Convert AzimuthalAverage to IntermediateScatteringFunction.

Parameters:

  • az_avg (AzimuthalAverage) – AzimuthalAverage object

  • noise_est (str, optional) – Noise factor estimate mode, by default ‘polyfit’. Accepted values are the ones supported by the estimate_camera_noise function of fastddm.noise_est module plus ‘custom’. In the latter case, noise input argument is required. Additional keyword arguments are used in the estimate_camera_noise function.

  • plateau_est (str, optional) – Plateau estimate mode, by default ‘var’. Accepted values are ‘var’, ‘power_spec’, or ‘custom’. When ‘var’ (‘power_spec’) mode is selected, the plateau is estimated as twice the az_avg.var (az_avg.power_spec). When ‘custom’ is selected, the plateau input argument is required.

  • noise (np.ndarray | None, optional) – Custom noise array, by default None. Required if noise_est is ‘custom’

  • noise_err (np.ndarray | None, optional) – Custom noise array uncertainty, by default None. Used if noise_est is ‘custom’. If None and noise_est is ‘custom’, the noise uncertainty is assumed equal to the noise input array.

  • plateau (np.ndarray | None, optional) – Custom plateau array, by default None. Required if plateau_est is ‘custom’

  • plateau_err (np.ndarray | None, optional) – Custom plateau array uncertainty, by default None. Used if plateau_est is ‘custom’. If None and plateau_est is ‘custom’, the plateau uncertainty is assumed equal to the plateau input array.

Returns:

IntermediateScatteringFunction

Return type:

IntermediateScatteringFunction

Raises:

RuntimeError – If the dimension of the input arrays are not compatible with the azimuthal average or if any of the estimate mode is not supported.

fastddm.intermediatescatteringfunction.melt(isf1: IntermediateScatteringFunction, isf2: IntermediateScatteringFunction) → IntermediateScatteringFunction

Melt two intermediate scattering functions into one object.

Parameters:
Returns:

The two IntermediateScatteringFunction objects, merged into a new one.

Return type:

IntermediateScatteringFunction

fastddm.intermediatescatteringfunction.mergesort(isf1: IntermediateScatteringFunction, isf2: IntermediateScatteringFunction) → IntermediateScatteringFunction

Merge the values of two intermediate scattering functions.

Values will then be sorted based on tau.

Parameters:
Returns:

The two IntermediateScatteringFunction objects are fused into a new one.

Return type:

IntermediateScatteringFunction