# From PLINK to HIrisPlex

## Overview

`hirisplexr` converts a PLINK 1.9 binary dataset (`.bed/.bim/.fam`) into the CSV format required by the HIrisPlex / HIrisPlex-S web application.

- Output columns: `SampleID` + one `rsID_Allele` per SNP in the chosen panel.
- Cell values: allele counts `0 / 1 / 2`, or `NA` if missing.
- Panels: IrisPlex (6 SNP), HIrisPlex (24 SNP), HIrisPlex-S (41 SNP).

## Installation

    # Install runtime deps
    install.packages(c("BEDMatrix", "data.table"))
    # Install this package from source tarball or local folder

## Quick start

    library(hirisplexr)
    prefix <- "/path/to/your/prefix"  # without extension
    outfile <-  tempfile(fileext = ".csv")
    write_hirisplex_csv(prefix, panel = "hirisplexs", out = outfile)

## How allele mapping works

- `BEDMatrix::BEDMatrix()` yields the genotype dosage of A1 from the `.bim` file (values: 0/1/2).
- For each required `rsID_Allele`:
  - If the requested allele equals `A1`, we use the dosage directly.
  - If it equals `A2`, we take `2 - dosage`.
  - If `allow_strand_flip = TRUE`, we also try the complement (A↔︎T, C↔︎G) to account for strand orientation; if no match is possible we write `NA` and emit a warning.

### Palindromic SNPs

For A/T or C/G SNPs, complements equal the original bases. The function still uses the `.bim` allele pair (A1/A2) to determine the mapping. You should ensure that your BIM file uses a consistent reference across datasets.

## Panels and order

The complete list of SNPs and their required input alleles is packaged in `inst/extdata/hirisplex_panels.csv`. The order of columns in the output CSV matches exactly the order used by the web application.

    # Inspect packaged panel metadata
    loader <- getFromNamespace(".load_hirisplex_panels", "hirisplexr")
    head(loader())
    #>        panel order        rsid input_allele   column_name
    #> 42 hirisplex     1 rs312262906            A rs312262906_A
    #> 43 hirisplex     2  rs11547464            A  rs11547464_A
    #> 44 hirisplex     3    rs885479            T    rs885479_T
    #> 45 hirisplex     4   rs1805008            T   rs1805008_T
    #> 46 hirisplex     5   rs1805005            T   rs1805005_T
    #> 47 hirisplex     6   rs1805006            A   rs1805006_A

## Reproducibility tips

- Keep `.bed/.bim/.fam` together under the same prefix.
- If you update your PLINK files, regenerate the CSV to keep alleles consistent.
- Track the package version used to produce the CSV in your analysis records.

## Session info

    sessionInfo()
    #> R version 4.3.3 (2024-02-29)
    #> Platform: x86_64-pc-linux-gnu (64-bit)
    #> Running under: TUXEDO OS
    #>
    #> Matrix products: default
    #> BLAS:   /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
    #> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so;  LAPACK version 3.12.0
    #>
    #> locale:
    #>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C
    #>  [3] LC_TIME=it_IT.UTF-8        LC_COLLATE=C
    #>  [5] LC_MONETARY=it_IT.UTF-8    LC_MESSAGES=en_US.UTF-8
    #>  [7] LC_PAPER=it_IT.UTF-8       LC_NAME=C
    #>  [9] LC_ADDRESS=C               LC_TELEPHONE=C
    #> [11] LC_MEASUREMENT=it_IT.UTF-8 LC_IDENTIFICATION=C
    #>
    #> time zone: Europe/Rome
    #> tzcode source: system (glibc)
    #>
    #> attached base packages:
    #> [1] stats     graphics  grDevices utils     datasets  methods   base
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] digest_0.6.34     R6_2.5.1          fastmap_1.1.1     xfun_0.41
    #>  [5] cachem_1.0.8      knitr_1.45        htmltools_0.5.7   rmarkdown_2.25
    #>  [9] lifecycle_1.0.4   cli_3.6.2         hirisplexr_0.1.0  sass_0.4.8
    #> [13] jquerylib_0.1.4   compiler_4.3.3    rstudioapi_0.15.0 tools_4.3.3
    #> [17] evaluate_0.23     bslib_0.6.1       yaml_2.3.8        rlang_1.1.3
    #> [21] jsonlite_1.8.8