Convert PLINK Binary Files to GDS Format

Source: R/plink_to_gds.R

Converts PLINK binary format files (.bed/.bim/.fam) to Genomic Data Structure (GDS) format, which serves as the unified data format for GLOWpipeline. Supports optional chromosome-based splitting or region filtering for parallelized downstream analysis (e.g., FAVOR annotation).

plink_to_gds(
  plink_prefix,
  output_gds,
  split_by_chr = FALSE,
  chromosomes = NULL,
  regions = NULL,
  output_prefix = NULL,
  chr.conv = TRUE,
  parallel = FALSE,
  verbose = 1,
  ...
)

Arguments

Character. Path to PLINK files without extension. The function expects three files: {prefix}.bed, {prefix}.bim, {prefix}.fam. If the user provides a path with extension (e.g., "data.bed"), the extension is stripped automatically.

output_gds

Character. Path for the output GDS file, or a directory path. If a directory is provided in default mode (no splitting/filtering), the function auto-generates the filename from the PLINK prefix (e.g., providing "output/" with plink_prefix "data/mydata" creates "output/mydata.gds"). In split/filter modes, this is always treated as a directory path.

split_by_chr

Logical. If TRUE, create separate GDS files per chromosome. In this case, output_gds is treated as a directory path. Default: FALSE.

chromosomes

Character or numeric vector. Specific chromosomes to include. Only used when split_by_chr = TRUE. NULL (default) includes all chromosomes found in the input data.

regions

List. Genomic regions to filter. Mutually exclusive with split_by_chr. See Details for format specification. Default: NULL.

output_prefix

Character. Override the file prefix for output files. Default: NULL (extracted from plink_prefix).

chr.conv

Logical. If TRUE (default), convert chromosome codes: 23 -> X, 24 -> Y, 25 -> XY, 26 -> MT. This matches the default behavior of seqBED2GDS. When split_by_chr = TRUE, the same conversion is applied to chromosome names from the .bim file to ensure filtering works correctly.

parallel

Logical, integer, or cluster object. Controls parallel processing for seqBED2GDS:

  • FALSE (default): Serial processing

  • TRUE: Auto-detect number of cores

  • Integer: Specific number of cores

  • Cluster object: For distributed computing

verbose

Integer. Verbosity level: 0=silent, 1=messages (default).

...

Additional arguments passed to seqBED2GDS. Useful options include:

  • compress.geno: Compression for genotype data (default "LZMA_RA")

  • compress.annotation: Compression for annotations (default "LZMA_RA")

  • optimize: Optimize GDS access efficiency (default TRUE)

  • digest: Add hash codes for integrity (default TRUE)

Value

  • Default mode: Character string with path to created GDS file.

  • Split/region mode: Character vector of created file paths.

Details

Splitting and Filtering:

This function supports three modes of operation:

  1. Default mode: Convert PLINK to a single GDS file (original behavior).

  2. Split by chromosome: Create per-chromosome GDS files for parallel processing.

  3. Region filter: Create GDS file(s) for specific genomic regions.

split_by_chr and regions are mutually exclusive; specifying both raises an error.

Region Specification:

The regions parameter accepts two formats:

Single region (shorthand):

regions = list(chr = "21", start = 1000000, end = 5000000)

Multiple regions (list of lists):

regions = list(
  list(chr = "1", start = 1000000, end = 2000000),
  list(chr = "2", start = 5000000, end = 6000000)
)

Output Naming:

ModeNaming Pattern
Defaultoutput_gds (user-specified path)
Split by chr{output_dir}/{prefix}_chr{CHR}.gds
Region filter{output_dir}/{prefix}_chr{CHR}_{START}_{END}.gds

Chromosome Naming:

Chromosome names are preserved from the input .bim file. If input uses "X", output uses "chrX"; if input uses "23", output uses "chr23".

PLINK convention reference:

NumericLetterDescription
1-221-22Autosomes
23XX chromosome
24YY chromosome
25XYPseudo-autosomal region
26MTMitochondrial

References

Zheng X, et al. (2012). A high-performance computing toolset for relatedness and principal component analysis of SNP data. Bioinformatics 28(24):3326-3328. DOI: 10.1093/bioinformatics/bts606

See also

seqBED2GDS for the underlying conversion function prepare_PI_control_data for control variant preparation using GDS

For HPC batch annotation, see inst/scripts/annotate_favor_hpc.sh

Examples

if (FALSE) { # \dontrun{
# Example 1: Basic conversion (unchanged from original)
gds_path <- plink_to_gds(
  plink_prefix = "data/my_data",
  output_gds = "data/my_data.gds"
)

# Example 2: Split by chromosome for parallel annotation
gds_files <- plink_to_gds(
  plink_prefix = "data/my_data",
  output_gds = "output/",
  split_by_chr = TRUE
)
# Creates: output/my_data_chr1.gds, output/my_data_chr2.gds, ...

# Example 3: Split specific chromosomes only
gds_files <- plink_to_gds(
  plink_prefix = "data/my_data",
  output_gds = "output/",
  split_by_chr = TRUE,
  chromosomes = c(21, 22)
)
# Creates: output/my_data_chr21.gds, output/my_data_chr22.gds

# Example 4: Filter to a specific genomic region
gds_path <- plink_to_gds(
  plink_prefix = "data/my_data",
  output_gds = "output/",
  regions = list(chr = "21", start = 1000000, end = 5000000)
)
# Creates: output/my_data_chr21_1000000_5000000.gds

# Example 5: Multiple regions
gds_files <- plink_to_gds(
  plink_prefix = "data/my_data",
  output_gds = "output/",
  regions = list(
    list(chr = "1", start = 1000000, end = 2000000),
    list(chr = "2", start = 5000000, end = 6000000)
  )
)

# Example 6: Custom output prefix
gds_files <- plink_to_gds(
  plink_prefix = "data/my_data",
  output_gds = "output/",
  split_by_chr = TRUE,
  output_prefix = "als_study"
)
# Creates: output/als_study_chr1.gds, output/als_study_chr2.gds, ...
} # }