FastGaSP (version 0.6.0)

fit.particle.data: Fit method for particle data

Description

Estimates interaction parameters for particle systems using trajectory data with the IKF-CG (Inverse Kalman Filter - Conjugate Gradient) approach. Supports both simulation and experimental data.

Usage

# S4 method for particle.data
fit(
    object, param, cut_r_max=1, est_param = TRUE, nx=NULL, ny=NULL,
    kernel_type = "matern_5_2", tilde_nu = 0.1, tol = 1e-6,
    maxIte = 1000, output = NULL, ho_output = NULL, 
    testing_inputs=NULL, compute_CI = TRUE, num_interaction = (length(param)-1)/2,
    data_type = object@data_type, model = object@model, 
    apolar_vicsek = FALSE, direction = NULL
  )

Value

Returns an object of class particle.est. See particle.est-class for details.

Arguments

object

An object of class particle.data containing the trajectory data.

param

Numeric vector of parameters. Should contain 2*num_interaction + 1 elements: first num_interaction elements are log of inverse range parameters (beta), next num_interaction elements are log of variance-noise ratios (tau), and the final element is log(radius/(cut_r_max-radius)) where radius is the interaction radius.

cut_r_max

Numeric value specifying the maximum interaction radius to consider during estimation (default: 1).

est_param

If TRUE, param is used as initial values for parameter optimization. If FALSE, param is treated as fixed parameters for prediction (default: TRUE).

nx

An integer specifying the number of grid points along the x-axis (horizontal direction). If NULL, automatically calculated as floor((px_max-px_min)/cut_r_max), where px_max and px_min represent the maximum and minimum x-coordinates of all particles.

ny

An integer specifying the number of grid points along the y-axis (vertical direction). If NULL, automatically calculated as floor((py_max-py_min)/cut_r_max), where py_max and py_min represent the maximum and minimum y-coordinates of all particles.

kernel_type

Character string specifying the kernel type: 'matern_5_2' (default) or 'exp'.

tilde_nu

Numeric value for stabilizing the IKF computation (default: 0.1).

tol

Numeric value specifying convergence tolerance for the conjugate gradient algorithm (default: 1e-6).

maxIte

Integer specifying maximum iterations for the conjugate gradient algorithm (default: 1000).

output

Numerical vector (default = NULL). Used for residual bootstrap when different outputs but same inputs are needed.

ho_output

Numerical vector (default = NULL). Used for residual bootstrap when different hold-out outputs but same inputs are needed.

testing_inputs

Matrix of inputs for prediction (NULL if only performing parameter estimation). Each column represents testing inputs for one interaction.

compute_CI

When TRUE, computes the 95% credible interval for testing_inputs (default: TRUE).

num_interaction

Integer specifying number of interactions to predict (default: (length(param_ini)-1)/2).

data_type

Character string indicating data type ("simulation" or "experiment").

model

Character string specifying the model type (e.g., "Vicsek").

apolar_vicsek

When TRUE, considers only neighboring particles moving in the same direction (default: FALSE).

direction

Modeling direction ('x' or 'y') for experimental data analysis.

References

Fang, X., & Gu, M. (2024). The inverse Kalman filter. arXiv:2407.10089.

Examples

# Simulate data
vx_abs <- 0.5
vy_abs <- 0.5
v_abs <- sqrt(vx_abs^2+vy_abs^2)
sim <- simulate_particle(v_abs=v_abs)
show(sim)

# Set up testing inputs and initial parameters
testing_n <- 200
testing_inputs <- matrix(as.numeric(seq(-pi,pi,(2*pi)/(testing_n-1))),nr=1)
cut_r_max=1.5
param_ini <- log(c(0.3,1000,0.3/(cut_r_max-0.3)))  # Initial parameter values

# Fit model to simulation data
est <- fit(sim,param=param_ini,cut_r_max=1.5, testing_inputs = testing_inputs)
show(est)