hySAINT

Hybrid Genetic Algorithm and Simulated Annealing for High-Dimensional Linear Models with Interaction Effects

Overview

hySAINT is an R package for variable selection in high-dimensional linear regression models with two-way interaction effects. It combines a genetic algorithm with simulated annealing and minimizes the ABC criterion of Ye and Yang (2019). The method supports strong, weak, and no-heredity model structures and includes screening tools for settings where the number of predictors is large.

This repository contains the R package source code, documentation, simulation replication scripts, and public-use examples. The real dataset used in the manuscript analysis is not publicly available and is therefore not included in this GitHub repository. Instead, we provide the R code used for the real-data workflow so that users can inspect the analysis structure and adapt it to their own data.

Repository Structure

The current repository is organized as follows:

hySAINT/
+-- .Rbuildignore
+-- DESCRIPTION
+-- NAMESPACE
+-- README.md
+-- hySAINT_2.3.0_reference_manual.pdf
+-- hySAINT_2.3.0.tar.gz
+-- R/
|   +-- ABC.R
|   +-- GA_operators.R
|   +-- Screening.R
|   +-- hySAINT.R
+-- man/
|   +-- ABC.Rd
|   +-- crossover.Rd
|   +-- evaluate_individual.Rd
|   +-- generate_initial_population.Rd
|   +-- generate_inter_pool.Rd
|   +-- hySAINT.Rd
|   +-- mutate.Rd
|   +-- screen_main_effects.Rd
+-- Replicate/
    +-- section4_usage_examples.R
    +-- simulation.R
    +-- real_data_analysis.R
    +-- results/
        +-- simulation_all_heredity/
            +-- manuscript_hysaint_all_heredity_table.csv
            +-- manuscript_ramp_comparison_table.csv
            +-- run_log.csv
            +-- simulation_all_heredity_raw.csv
            +-- simulation_all_heredity_summary.csv
            +-- simulation_errors.csv
            +-- total_runtime_by_method.csv
            +-- total_runtime_summary.csv

Reference Manual

A CRAN-style package reference manual has been rendered from the package .Rd help files:

hySAINT_2.3.0_reference_manual.pdf

This PDF is generated with R CMD Rd2pdf and contains the help pages for the exported package functions.

Important Note

The manuscript real-data analysis expects a private Replicate/prog/ folder with files such as market.csv and ProductIDName.csv. These files are not distributed here because the real data are not publicly available. As a result:

• Replicate/real_data_analysis.R is included as reproducible analysis code only.
• The private real-data input files are intentionally excluded from the repository.
• Users who have access to their own data can adapt the script by placing their data in the expected structure or by editing the input paths.
• Publicly shareable simulation code and simulation result summaries are included under Replicate/.

Installation

Install the package from GitHub:

install.packages("remotes")
# remotes::install_github("lli289/hySAINT")
install.packages("hySAINT", repos = c('https://lli289.r-universe.dev', 'https://cloud.r-project.org'))

Or install from a local checkout:

setwd("path/to/hySAINT")
install.packages(c("Matrix", "glmnet"))
devtools::install()

You can also install from the source:

install.packages("hySAINT_2.3.0.tar.gz", repos = NULL, type = "source")

Quick Start

library(hySAINT)

set.seed(123)
n <- 160
p <- 20
X <- matrix(rnorm(n * p), nrow = n, ncol = p)
y <- 2 * X[, 1] - 1.5 * X[, 2] + 1.25 * X[, 3] +
  2 * X[, 1] * X[, 2] - 1.5 * X[, 2] * X[, 3] +
  rnorm(n, sd = 0.75)

fit <- hySAINT(
  X = X,
  y = y,
  heredity = "Strong",
  r1 = 5,
  r2 = 2,
  sigma = 0.75,
  pop_size = 40,
  max_iter = 100,
  patience = 30,
  verbose = FALSE
)

fit$main_effects
fit$interactions
round(fit$coefficients, 3)
fit$ABC_score

Main Function

The primary user-facing function is:

hySAINT(
  X,
  y,
  heredity = c("Strong", "Weak", "No"),
  r1,
  r2,
  sigma = NULL,
  lambda = NULL,
  pop_size = 50,
  max_iter = 100,
  patience = 30,
  verbose = TRUE
)

Required Inputs

• X: numeric predictor matrix with n rows and p columns.
• y: numeric response vector of length n.
• r1: maximum number of main effects to select.
• r2: maximum number of interaction effects to select.

Common Options

• heredity: heredity constraint for interactions. Use "Strong", "Weak", or "No".
• sigma: noise standard deviation. If NULL, hySAINT estimates it automatically.
• lambda: ABC penalty parameter. If NULL, hySAINT uses the theoretical default 5.1 / log(2).
• pop_size: genetic algorithm population size.
• max_iter: maximum number of genetic algorithm iterations.
• patience: early-stopping patience when the best score stops improving.
• verbose: whether to print progress messages.

Output

hySAINT() returns an object of class "hySAINT" with components including:

• main_effects: selected main-effect indices.
• interactions: selected interaction pairs.
• ABC_score: final ABC score of the selected model.
• coefficients: fitted OLS coefficients for the selected model.
• sigma: estimated or provided noise standard deviation.
• lambda: ABC penalty value used by the algorithm.
• runtime: total computation time.
• convergence: convergence details from the search.

Replication Scripts

The Replicate/ folder contains scripts used for package examples and manuscript replication workflows.

Section 4 Package Examples

Run the package usage examples with:

source("Replicate/section4_usage_examples.R", echo = TRUE, print.eval = TRUE)

This script demonstrates the main hySAINT() function, the ABC() scoring function, screening, and genetic-operator utilities.

Simulation Study

Run the simulation workflow from the package root:

source("Replicate/simulation.R")

The script reproduces the seven simulation settings at three noise levels and writes outputs to:

Replicate/results/simulation_all_heredity/

The script checks for the manuscript package versions:

• hySAINT 2.3.0
• RAMP 2.0.2

Real-Data Analysis Code

The real-data workflow is provided in:

Replicate/real_data_analysis.R

This script is included for transparency, but it cannot be run directly from the public repository because the underlying real-data files are not public and are not included. With authorized data access, the script expects input files under:

Replicate/prog/

Citation

If you use this package in your research, please cite:

L. Li, Z. You, Z. Wang, and C. Ye (2026). hySAINT: Hybrid Genetic Algorithm and Simulated Annealing for High-Dimensional Linear Models with Interaction Effects. R package version 2.3.0. https://github.com/lli289/hySAINT

The ABC criterion is based on:

Ye, C. and Yang, Y. (2019). High-dimensional adaptive minimax sparse estimation with interactions. IEEE Transactions on Information Theory, 65(9), 5367-5379. doi:10.1109/TIT.2019.2913417

Authors

• Leiyue Li, maintainer: lli289.git@gmail.com
• Zhengzhong You: ricky.you.or@gmail.com
• Zeya Wang: zeya.wang@uky.edu
• Chenglong Ye: chenglong.ye@uky.edu

Help

After installation, view function documentation in R:

?hySAINT
?ABC
?screen_main_effects

Please report package issues through the GitHub issue tracker or email package maintainer, Leiyue Li: lli289.git@gmail.com.