Build sparse weight triplets and generate `.grom`, `.gid`, and `.sid` outputs from model weights and PLINK2 genotype inputs.
Usage
grom_impute(
weights_table,
grom_pfx,
pgen_dir,
snp_chunk = 1000L,
sample_subset = integer(0),
CHUNK = 1000L,
exportChunk = 256L,
meanimpute = TRUE,
is_round = TRUE,
threads = NULL,
pgen_threads = NULL,
write_threads = NULL
)Arguments
- weights_table
A `data.frame` or `data.table` of model weights.
- grom_pfx
Output prefix for the generated grom files.
- pgen_dir
Path to a directory containing PLINK2 `.pgen`, `.pvar`, and `.psam` files.
- snp_chunk
Integer chunk size used while streaming SNPs. Specifies how many genotype records are loaded at a time and can be used to control peak and average memory usage.
- sample_subset
Integer vector specifying which samples to load and use for imputation.
- CHUNK
Integer chunk size passed to the low-level imputation engine. Specifies the tile size used during computation and can help maintain efficient CPU-cache utilization.
- exportChunk
Integer chunk size used when exporting results. Specifies how many output columns are written at a time and can be used to control peak and average memory usage.
- meanimpute
Logical indicating whether missing dosages should be mean imputed.
- is_round
Logical indicating whether mean imputation should use rounded means.
- threads
Number of OpenMP threads for GReX computation. Values less than or equal to zero use the engine default.
- pgen_threads
Number of threads for PGEN decoding. `NULL` uses the engine default; values less than or equal to zero inherit `threads`.
- write_threads
Number of threads for RAW output writing. `NULL` uses serial writing; values less than or equal to zero inherit `threads`.
Details
Chromosome-to-file mapping uses the `chromosomes` column in `weights_table`. The basenames of the `.pgen` and `.pvar` files in `pgen_dir` must contain the corresponding chromosome tag. For example:
weights_table$chromosomes:
chr1
chr2
chr10
Matching filenames in pgen_dir:
cohort.chr1.pgen
cohort.chr1.pvar
cohort.chr2.pgen
cohort.chr2.pvar
cohort.chr10.pgen
cohort.chr10.pvar
Matching is unique by chromosome tag, so `chr1` does not match `chr10`. Each chromosome tag must resolve to exactly one `.pgen` and one `.pvar` file. The `.psam` file is discovered separately and is not chromosome-tag matched.
To confirm the resolved mapping after a run, inspect the generated files `meta/chr_to_pgen_map.tsv` and `meta/chr_to_pvar_map.tsv` under the output directory. These record which chromosome tag was matched to which genotype file basename. On completion, `grom_impute()` also reports the output directory path in the console message stream.
Examples
library(gromtools)
pgen_dir <- system.file(
"extdata",
"synthetic_chromosomes",
package = "gromtools"
)
db_directory <- system.file(
"extdata",
"synth_small_variant_weights_db",
package = "gromtools"
)
model_weights_table <- read_db_dir(db_dir = db_directory)
out_dir <- file.path(tempdir(), "tmp_grom_run")
dir.create(out_dir, recursive = TRUE, showWarnings = FALSE)
grom_pfx <- file.path(out_dir, "synth_example")
grom_impute(
weights_table = model_weights_table,
grom_pfx = grom_pfx,
pgen_dir = pgen_dir
)
#> All chromosome tags were uniquely mapped to a .pgen file.
#> ### impute_grom() started at: 2026-08-08 18:30:41
#> grom_axpy_engine timing: chunks=2 waves=6 ops=1341 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=36 output_bytes_written=29088 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.000357577s decoded_variants=1321 decoded_dosages=133421 pgen_load=0.00633025s pgen_dosages_per_sec=2.10767e+07 wave_prepare=0.000533044s parallel_compute=0.00982352s output_flush=0.000221423s output_write_prepare=2.4004e-05s output_write_positioned=0.000183437s output_bytes_per_sec=1.58572e+08 max_wave_ops=256 max_live_gene_columns=36 decoded_buffer_bytes=808000 reader_workspace_bytes=2057168 omp_workers=16
#> grom_axpy_engine timing: chunks=1 waves=2 ops=363 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=15 output_bytes_written=12120 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.000343684s decoded_variants=361 decoded_dosages=36461 pgen_load=8.6629e-05s pgen_dosages_per_sec=4.20887e+08 wave_prepare=0.000141832s parallel_compute=9.0781e-05s output_flush=9.7437e-05s output_write_prepare=9.158e-06s output_write_positioned=8.2237e-05s output_bytes_per_sec=1.47379e+08 max_wave_ops=256 max_live_gene_columns=15 decoded_buffer_bytes=291688 reader_workspace_bytes=1918928 omp_workers=16
#> grom_axpy_engine timing: chunks=1 waves=2 ops=403 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=17 output_bytes_written=13736 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.000781823s decoded_variants=401 decoded_dosages=40501 pgen_load=9.5158e-05s pgen_dosages_per_sec=4.25618e+08 wave_prepare=0.000159925s parallel_compute=0.00010469s output_flush=6.9582e-05s output_write_prepare=1.1568e-05s output_write_positioned=5.1719e-05s output_bytes_per_sec=2.65589e+08 max_wave_ops=256 max_live_gene_columns=17 decoded_buffer_bytes=324008 reader_workspace_bytes=1925072 omp_workers=16
#> grom_axpy_engine timing: chunks=1 waves=3 ops=587 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=21 output_bytes_written=16968 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.00058029s decoded_variants=580 decoded_dosages=58580 pgen_load=0.000449346s pgen_dosages_per_sec=1.30367e+08 wave_prepare=0.000216946s parallel_compute=0.00012667s output_flush=0.000143258s output_write_prepare=1.4591e-05s output_write_positioned=0.000120337s output_bytes_per_sec=1.41004e+08 max_wave_ops=256 max_live_gene_columns=21 decoded_buffer_bytes=468640 reader_workspace_bytes=1950672 omp_workers=16
#> grom_axpy_engine timing: chunks=1 waves=1 ops=83 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=8 output_bytes_written=6464 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.000251596s decoded_variants=83 decoded_dosages=8383 pgen_load=2.8949e-05s pgen_dosages_per_sec=2.89578e+08 wave_prepare=3.8667e-05s parallel_compute=2.2857e-05s output_flush=3.5057e-05s output_write_prepare=6.60101e-06s output_write_positioned=2.4545e-05s output_bytes_per_sec=2.63353e+08 max_wave_ops=83 max_live_gene_columns=8 decoded_buffer_bytes=67064 reader_workspace_bytes=1878992 omp_workers=16
#> grom_axpy_engine timing: chunks=1 waves=3 ops=593 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=18 output_bytes_written=14544 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.000222164s decoded_variants=590 decoded_dosages=59590 pgen_load=0.000139067s pgen_dosages_per_sec=4.28498e+08 wave_prepare=0.000202933s parallel_compute=0.00015498s output_flush=6.2494e-05s output_write_prepare=1.2165e-05s output_write_positioned=4.328e-05s output_bytes_per_sec=3.36044e+08 max_wave_ops=256 max_live_gene_columns=18 decoded_buffer_bytes=476720 reader_workspace_bytes=1951696 omp_workers=16
#> grom_axpy_engine timing: chunks=1 waves=2 ops=354 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=13 output_bytes_written=10504 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.000247418s decoded_variants=337 decoded_dosages=34037 pgen_load=0.000100966s pgen_dosages_per_sec=3.37113e+08 wave_prepare=0.000125692s parallel_compute=8.052e-05s output_flush=8.1629e-05s output_write_prepare=8.00501e-06s output_write_positioned=6.8351e-05s output_bytes_per_sec=1.53677e+08 max_wave_ops=256 max_live_gene_columns=13 decoded_buffer_bytes=272296 reader_workspace_bytes=1915856 omp_workers=16
#> grom_axpy_engine timing: chunks=1 waves=2 ops=335 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=14 output_bytes_written=11312 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.00027126s decoded_variants=331 decoded_dosages=33431 pgen_load=0.000112338s pgen_dosages_per_sec=2.97593e+08 wave_prepare=0.000128523s parallel_compute=8.82e-05s output_flush=4.7821e-05s output_write_prepare=8.563e-06s output_write_positioned=3.4504e-05s output_bytes_per_sec=3.27846e+08 max_wave_ops=256 max_live_gene_columns=14 decoded_buffer_bytes=267448 reader_workspace_bytes=1914832 omp_workers=16
#> grom_axpy_engine timing: chunks=1 waves=3 ops=626 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=32 output_bytes_written=25856 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.0001968s decoded_variants=552 decoded_dosages=55752 pgen_load=0.000124061s pgen_dosages_per_sec=4.49392e+08 wave_prepare=0.000229662s parallel_compute=0.000150424s output_flush=0.000105327s output_write_prepare=1.953e-05s output_write_positioned=7.4365e-05s output_bytes_per_sec=3.4769e+08 max_wave_ops=256 max_live_gene_columns=32 decoded_buffer_bytes=446016 reader_workspace_bytes=1946576 omp_workers=16
#> grom_axpy_engine timing: chunks=1 waves=1 ops=97 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=3 output_bytes_written=2424 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.000184735s decoded_variants=97 decoded_dosages=9797 pgen_load=2.9767e-05s pgen_dosages_per_sec=3.29123e+08 wave_prepare=3.4005e-05s parallel_compute=4.0892e-05s output_flush=1.3537e-05s output_write_prepare=2.965e-06s output_write_positioned=9.11801e-06s output_bytes_per_sec=2.65847e+08 max_wave_ops=97 max_live_gene_columns=3 decoded_buffer_bytes=78376 reader_workspace_bytes=1881040 omp_workers=16
#> grom_axpy_engine timing: chunks=1 waves=3 ops=655 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=19 output_bytes_written=15352 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.000332025s decoded_variants=629 decoded_dosages=63529 pgen_load=0.000191532s pgen_dosages_per_sec=3.31689e+08 wave_prepare=0.00022965s parallel_compute=0.000174698s output_flush=0.000100607s output_write_prepare=1.221e-05s output_write_positioned=8.0489e-05s output_bytes_per_sec=1.90734e+08 max_wave_ops=256 max_live_gene_columns=19 decoded_buffer_bytes=508232 reader_workspace_bytes=1956816 omp_workers=16
#> grom_axpy_engine timing: chunks=1 waves=3 ops=757 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=29 output_bytes_written=23432 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.000298772s decoded_variants=731 decoded_dosages=73831 pgen_load=0.000192958s pgen_dosages_per_sec=3.82627e+08 wave_prepare=0.000345809s parallel_compute=0.000345132s output_flush=0.000129407s output_write_prepare=1.657e-05s output_write_positioned=0.000101396s output_bytes_per_sec=2.31094e+08 max_wave_ops=256 max_live_gene_columns=29 decoded_buffer_bytes=590648 reader_workspace_bytes=1972176 omp_workers=16
#> grom_axpy_engine timing: chunks=1 waves=1 ops=105 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=7 output_bytes_written=5656 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.000146863s decoded_variants=105 decoded_dosages=10605 pgen_load=3.572e-05s pgen_dosages_per_sec=2.96893e+08 wave_prepare=3.9515e-05s parallel_compute=2.4485e-05s output_flush=2.3204e-05s output_write_prepare=4.06e-06s output_write_positioned=1.6337e-05s output_bytes_per_sec=3.46208e+08 max_wave_ops=105 max_live_gene_columns=7 decoded_buffer_bytes=84840 reader_workspace_bytes=1882064 omp_workers=16
#> grom_axpy_engine timing: chunks=1 waves=1 ops=117 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=4 output_bytes_written=3232 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.000202402s decoded_variants=116 decoded_dosages=11716 pgen_load=3.2243e-05s pgen_dosages_per_sec=3.63366e+08 wave_prepare=4.0942e-05s parallel_compute=4.9332e-05s output_flush=2.4053e-05s output_write_prepare=3.17699e-06s output_write_positioned=1.8969e-05s output_bytes_per_sec=1.70383e+08 max_wave_ops=117 max_live_gene_columns=4 decoded_buffer_bytes=93728 reader_workspace_bytes=1883088 omp_workers=16
#> grom_axpy_engine timing: chunks=1 waves=1 ops=173 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=7 output_bytes_written=5656 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.000216919s decoded_variants=172 decoded_dosages=17372 pgen_load=4.1726e-05s pgen_dosages_per_sec=4.16335e+08 wave_prepare=6.7064e-05s parallel_compute=4.7435e-05s output_flush=2.6495e-05s output_write_prepare=4.505e-06s output_write_positioned=1.9442e-05s output_bytes_per_sec=2.90917e+08 max_wave_ops=173 max_live_gene_columns=7 decoded_buffer_bytes=138976 reader_workspace_bytes=1891280 omp_workers=16
#> grom_axpy_engine timing: chunks=2 waves=6 ops=1157 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=39 output_bytes_written=31512 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.000257726s decoded_variants=1121 decoded_dosages=113221 pgen_load=0.000254889s pgen_dosages_per_sec=4.44197e+08 wave_prepare=0.000413078s parallel_compute=0.000269441s output_flush=0.000166467s output_write_prepare=3.2963e-05s output_write_positioned=0.000118639s output_bytes_per_sec=2.65612e+08 max_wave_ops=256 max_live_gene_columns=39 decoded_buffer_bytes=808000 reader_workspace_bytes=2028496 omp_workers=16
#> grom_axpy_engine timing: chunks=1 waves=3 ops=662 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=29 output_bytes_written=23432 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.00019418s decoded_variants=584 decoded_dosages=58984 pgen_load=0.000140702s pgen_dosages_per_sec=4.19212e+08 wave_prepare=0.000239798s parallel_compute=0.000152512s output_flush=7.8412e-05s output_write_prepare=1.6294e-05s output_write_positioned=5.1963e-05s output_bytes_per_sec=4.50936e+08 max_wave_ops=256 max_live_gene_columns=29 decoded_buffer_bytes=471872 reader_workspace_bytes=1951696 omp_workers=16
#> grom_axpy_engine timing: chunks=1 waves=2 ops=408 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=17 output_bytes_written=13736 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.000178161s decoded_variants=405 decoded_dosages=40905 pgen_load=9.7066e-05s pgen_dosages_per_sec=4.21414e+08 wave_prepare=0.000142137s parallel_compute=9.7947e-05s output_flush=4.3996e-05s output_write_prepare=9.29601e-06s output_write_positioned=2.8949e-05s output_bytes_per_sec=4.74489e+08 max_wave_ops=256 max_live_gene_columns=17 decoded_buffer_bytes=327240 reader_workspace_bytes=1925072 omp_workers=16
#> grom_axpy_engine timing: chunks=1 waves=2 ops=452 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=17 output_bytes_written=13736 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.000190253s decoded_variants=432 decoded_dosages=43632 pgen_load=0.000615025s pgen_dosages_per_sec=7.09435e+07 wave_prepare=0.000189044s parallel_compute=9.0522e-05s output_flush=5.0741e-05s output_write_prepare=9.56601e-06s output_write_positioned=3.5159e-05s output_bytes_per_sec=3.90682e+08 max_wave_ops=256 max_live_gene_columns=17 decoded_buffer_bytes=349056 reader_workspace_bytes=1929168 omp_workers=16
#> grom_axpy_engine timing: chunks=1 waves=3 ops=575 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=16 output_bytes_written=12928 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.000218345s decoded_variants=571 decoded_dosages=57671 pgen_load=0.000141964s pgen_dosages_per_sec=4.06237e+08 wave_prepare=0.000188443s parallel_compute=0.00013811s output_flush=5.3269e-05s output_write_prepare=9.33799e-06s output_write_positioned=3.8535e-05s output_bytes_per_sec=3.35487e+08 max_wave_ops=256 max_live_gene_columns=16 decoded_buffer_bytes=461368 reader_workspace_bytes=1948624 omp_workers=16
#> grom_axpy_engine timing: chunks=1 waves=2 ops=487 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=11 output_bytes_written=8888 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.000185983s decoded_variants=462 decoded_dosages=46662 pgen_load=0.000729971s pgen_dosages_per_sec=6.39231e+07 wave_prepare=0.000162521s parallel_compute=0.000311031s output_flush=3.6905e-05s output_write_prepare=7.132e-06s output_write_positioned=2.5559e-05s output_bytes_per_sec=3.47744e+08 max_wave_ops=256 max_live_gene_columns=11 decoded_buffer_bytes=373296 reader_workspace_bytes=1933264 omp_workers=16
#> grom_axpy_engine timing: chunks=1 waves=3 ops=709 compute_threads=16 requested_pgen_threads=0 resolved_pgen_threads=16 requested_write_threads=1 resolved_write_threads=1 write_batches=1 gene_columns_written=23 output_bytes_written=18584 max_active_write_threads=1 duplicate_write_gids=0 reader_init=0.000201918s decoded_variants=674 decoded_dosages=68074 pgen_load=0.00016633s pgen_dosages_per_sec=4.09271e+08 wave_prepare=0.000245966s parallel_compute=0.000165805s output_flush=0.000102862s output_write_prepare=1.3064e-05s output_write_positioned=8.0913e-05s output_bytes_per_sec=2.29679e+08 max_wave_ops=256 max_live_gene_columns=23 decoded_buffer_bytes=544592 reader_workspace_bytes=1963984 omp_workers=16
#> ### impute_grom() completed at: 2026-08-08 18:30:41
#> Results stored under directory /tmp/RtmpHK6cG3/tmp_grom_run