HVTMSMoptimization: HVT-MSM Optimization Function

In HVT: Constructing Hierarchical Voronoi Tessellations and Overlay Heatmaps for Data Analysis

HVT-MSM Optimization Function

Description

This function runs multiple iterations/experiments over the dataset across different cell counts, and computes the MAE. If a given cell configuration not results in problematic states, the baseline simulation is used; otherwise, the simulation proceeds with problematic state handling. This process helps identify the best-performing model (lowest MAE). In essence, it performs trainHVT → scoreHVT → transition probability estimation on the training data, followed by msm simulation on the ex-post (test) dataset. Note: This is not applicable for ex-ante analysis.

Usage

HVTMSMoptimization(
  entire_dataset,
  expost_forecasting,
  time_column,
  ncell_range = 3:5,
  k_range = 2:9,
  nn_range = 2:7,
  num_simulations = 10,
  mae_metric,
  hvt_params = list(depth = 1, quant.err = 0.2, normalize = TRUE, distance_metric =
    "L1_Norm", error_metric = "max", dim_reduction_method = "sammon"),
  parallel = TRUE,
  verbose = TRUE,
  parallel_strategy = "multisession",
  max_workers = NULL
)

Arguments

entire_dataset	Dataframe. Train dataset for model training
expost_forecasting	Dataframe. Test dataset for ex-post forecasting
time_column	Character. Name of the time column
ncell_range	Numeric vector. Range of cells to run experiments (default 3:5)
k_range	Numeric vector. Range of clusters to run experiments (default: 2:9)
nn_range	Numeric vector. Range of nearest neighbors to run experiments (default: 2:7)
num_simulations	Integer. Number of simulations (default: 10)
mae_metric	Character. MAE calculation method(s): "mean", "median", "mode", or "all" (default: "median")
hvt_params	List. Set of parameters for Model Training (refer trainHVT)
parallel	Character. Whether to use parallel processing (default: TRUE)
verbose	Character. Whether to print progress information (default: TRUE)
parallel_strategy	Character. Parallel processing strategy: "multisession", "multicore", etc. (default: "multisession")
max_workers	Maximum number of parallel workers (default: NULL for auto-detect)

Value

List containing optimization results for each MAE metric:

[[successful_results]]	All successful parameter combinations
[[nclust_best_results]]	Best combination for each cell
[[overall_best]]	Overall best parameter combination
[[all_results]]	All attempted combinations with status

Author(s)

Vishwavani <[e-mail]>, Nithya <[e-mail]>

HVT documentation built on Dec. 18, 2025, 5:06 p.m.