SAM {AIUQ}

Scattering analysis of microscopy

Description

Fast parameter estimation in scattering analysis of microscopy, using either AIUQ or DDM method.

Usage

SAM(
  intensity = NA,
  intensity_str = "T_SS_mat",
  pxsz = 1,
  sz = c(NA, NA),
  mindt = 1,
  AIUQ_thr = c(1, 1),
  model_name = "BM",
  sigma_0_2_ini = NaN,
  param_initial = NA,
  num_optim = 1,
  msd_fn = NA,
  msd_grad_fn = NA,
  num_param = NA,
  uncertainty = FALSE,
  M = 50,
  sim_object = NA,
  msd_truth = NA,
  method = "AIUQ",
  index_q_AIUQ = NA,
  index_q_DDM = NA,
  message_out = TRUE,
  A_neg = "abs",
  square = FALSE,
  output_dqt = FALSE,
  output_isf = FALSE,
  output_modeled_isf = FALSE,
  output_modeled_dqt = FALSE
)

Arguments

intensity

intensity profile. See 'Details'.

intensity_str

structure of the intensity profile, options from ('SST_array','S_ST_mat','T_SS_mat'). See 'Details'.

pxsz

size of one pixel in unit of micron, 1 for simulated data

sz

frame size of the intensity profile in x and y directions, number of pixels contained in each frame equals sz_x by sz_y.

mindt

minimum lag time, 1 for simulated data

AIUQ_thr

threshold for wave number selection, numeric vector of two elements with values between 0 and 1. See 'Details'.

model_name

fitted model, options from ('BM','OU','FBM','OU+FBM', 'user_defined'), with Brownian motion as the default model. See 'Details'.

sigma_0_2_ini

initial value for background noise. If NA, use minimum value of absolute square of intensity profile in reciprocal space.

param_initial

initial values for param estimation.

num_optim

number of optimization.

msd_fn

user defined mean squared displacement(MSD) structure, a function of parameters and lag times. NA if model_name is not 'user_defined'.

msd_grad_fn

gradient for user defined mean squared displacement structure. If NA, then numerical gradient will be used for parameter estimation in 'user_defined' model.

num_param

number of parameters need to be estimated in the intermediate scattering function, need to be non-NA value for user_defined' model.

uncertainty

a logical evaluating to TRUE or FALSE indicating whether parameter uncertainty should be computed.

M

number of particles. See 'Details'.

sim_object

NA or an S4 object of class simulation.

msd_truth

true MSD or reference MSD value.

method

methods for parameter estimation, options from ('AIUQ','DDM_fixedAB','DDM_estAB').

index_q_AIUQ

index range for wave number when using AIUQ method. See 'Details'.

index_q_DDM

index range for wave number when using DDM method. See 'Details'.

message_out

a logical evaluating to TRUE or FALSE indicating whether or not to output the message.

A_neg

controls modification for negative A(q), options from ('abs','zero'), with setting negative A(q) to its absolute value as the default.

square

a logical evaluating to TRUE or FALSE indicating whether or not to crop the original intensity profile into square image.

output_dqt

a logical evaluating to TRUE or FALSE indicating whether or not to compute observed dynamic image structure function(Dqt).

output_isf

a logical evaluating to TRUE or FALSE indicating whether or not to compute empirical intermediate scattering function(ISF).

output_modeled_isf

a logical evaluating to TRUE or FALSE indicating whether or not to compute modeled intermediate scattering function(ISF).

output_modeled_dqt

a logical evaluating to TRUE or FALSE indicating whether or not to compute modeled dynamic image structure function(Dqt).

Details

For simulated data using simulation in AIUQ package, intensity will be automatically extracted from simulation class.

By default intensity_str is set to 'T_SS_mat', a time by space\timesspace matrix, which is the structure of intensity profile obtained from simulation class. For intensity_str='SST_array' , input intensity profile should be a space by space by time array, which is the structure from loading a tif file. For intensity_str='S_ST_mat', input intensity profile should be a space by space\timestime matrix.

By default AIUQ_thr is set to c(1,1), uses information from all complete q rings. The first element affects maximum wave number selected, and second element controls minimum proportion of wave number selected. By setting 1 for the second element, if maximum wave number selected is less than the wave number length, then maximum wave number selected is coerced to use all wave number unless user defined another index range through index_q_AIUQ.

If model_name equals 'user_defined', or NA (will coerced to 'user_defined'), then msd_fn and num_param need to be provided for parameter estimation.

Number of particles M is set to 50 or automatically extracted from simulation class for simulated data using simulation in AIUQ package.

By default, using all wave vectors from complete q ring, unless user defined index range through index_q_AIUQ or index_q_DDM.

Value

Returns an S4 object of class SAM.

Author(s)

Yue He [aut], Xubo Liu [aut], Mengyang Gu [aut, cre]

References

Gu, M., He, Y., Liu, X., & Luo, Y. (2023). Ab initio uncertainty quantification in scattering analysis of microscopy. arXiv preprint arXiv:2309.02468.

Gu, M., Luo, Y., He, Y., Helgeson, M. E., & Valentine, M. T. (2021). Uncertainty quantification and estimation in differential dynamic microscopy. Physical Review E, 104(3), 034610.

Cerbino, R., & Trappe, V. (2008). Differential dynamic microscopy: probing wave vector dependent dynamics with a microscope. Physical review letters, 100(18), 188102.

Examples

library(AIUQ)
# Example 1: Estimation for simulated data
sim_bm = simulation(len_t=100,sz=100,sigma_bm=0.5)
show(sim_bm)
sam = SAM(sim_object = sim_bm)
show(sam)