intermediatescatteringfunction#

This module contains the intermediate scattering function data class, and auxiliary classes & 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)#

FastDDM intermediate scattering function writer class.

Inherits from Writer. It adds the unique method write_obj.

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

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, optional) – Custom noise array, by default None. Required if noise_est is ‘custom’

  • noise_err (np.ndarray, 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, optional) – Custom plateau array, by default None. Required if plateau_est is ‘custom’

  • plateau_err (np.ndarray, 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