Getting started with GeneTrackR

Introduction

GeneTrackR is an R package for annotation, genomic signal, variant, haplotype, phenotype, linkage-disequilibrium, and variant-effect workflows. This page is the shortest path from installation to a first reproducible analysis. The examples use the deterministic gtr_demo_* files shipped with the package, so no external data download is required.

Package documentation: https://renscq.github.io/GeneTrackR/.

Installation

After Bioconductor acceptance, install GeneTrackR with BiocManager:

if (!requireNamespace("BiocManager", quietly = TRUE)) {
  install.packages("BiocManager")
}
BiocManager::install("GeneTrackR")
library(GeneTrackR)

The development version remains available from the GeneTrackR GitHub repository.

Load GeneTrackR

library(GeneTrackR)

Locate the bundled example data

The core demo files are installed under extdata:

gp_file <- system.file(
  "extdata",
  "gtr_demo.genePredExt",
  package = "GeneTrackR"
)

vcf_file <- system.file(
  "extdata",
  "gtr_demo_variants.vcf",
  package = "GeneTrackR"
)

pheno_file <- system.file(
  "extdata",
  "gtr_demo_pheno.tsv",
  package = "GeneTrackR"
)

c(
  annotation = gp_file,
  variants = vcf_file,
  phenotype = pheno_file
)
#>                                                                  annotation 
#>  "/tmp/RtmpqlTpMr/Rinstda455e980cc/GeneTrackR/extdata/gtr_demo.genePredExt" 
#>                                                                    variants 
#> "/tmp/RtmpqlTpMr/Rinstda455e980cc/GeneTrackR/extdata/gtr_demo_variants.vcf" 
#>                                                                   phenotype 
#>    "/tmp/RtmpqlTpMr/Rinstda455e980cc/GeneTrackR/extdata/gtr_demo_pheno.tsv"

The complete demo also includes GTF/GFF3/BED annotation files and strand-specific RNA-seq/Ribo-seq bedGraph tracks. See the GeneTrackR deterministic example data article for the complete data model and designed truth.

Read the three core inputs

gp <- read_genepred(
  gp_file,
  format = "genePredExt",
  verbose = FALSE,
  progress = FALSE
)

vcf <- read_vcf(
  vcf_file,
  mode = "memory",
  keep_genotype = TRUE,
  verbose = FALSE,
  progress = FALSE
)

pheno <- read_pheno(
  pheno_file,
  verbose = FALSE,
  progress = FALSE
)

These objects preserve the data needed by downstream modules. In particular, keep VCF genotype columns when the analysis will include haplotypes or LD.

Inspect a candidate gene

GeneA is the primary positive-strand demo locus.

genea <- retrieve_feature(
  gp,
  gene_id = "GeneA"
)

genea$genes
#>    gene_id  chrom strand gene_start gene_end n_transcripts gene_type
#>     <char> <char> <char>      <int>    <int>         <int>    <char>
#> 1:   GeneA   chr1      +   12340001 12352000             2    coding

A gene model can be drawn directly from the same annotation object:

plot_gene(
  gp,
  gene_id = "GeneA",
  text_size = 10
)

Retrieve variants for the same locus

genea_variants <- retrieve_vcf(
  vcf,
  annotation = gp,
  gene_id = "GeneA",
  as = "data.table",
  verbose = FALSE,
  progress = FALSE
)

genea_variants[, .(
  variant_id,
  chrom,
  pos,
  ref,
  alt,
  variant_type
)]
#>     variant_id  chrom      pos    ref    alt variant_type
#>         <char> <char>    <int> <char> <char>       <char>
#>  1:     varA01   chr1 12340250      A      G          SNP
#>  2:     varA02   chr1 12340600      T      C          SNP
#>  3:     varA03   chr1 12342550      C      G          SNP
#>  4:    varLD01   chr1 12342620      G      A          SNP
#>  5:    varLD02   chr1 12342710      A      T          SNP
#>  6:    varLD03   chr1 12342805      C      T          SNP
#>  7:    varLD04   chr1 12342920      G      C          SNP
#>  8:    varLD05   chr1 12343040      T      G          SNP
#>  9:    varLD06   chr1 12343180      A      C          SNP
#> 10:     varA04   chr1 12344500      A    ATG          INS
#> 11:     varA05   chr1 12351050    ATG      A          DEL

The annotation object defines the interval; no manual coordinate copy is needed.

Build gene haplotypes

hap <- hap_gene_variant(
  vcf,
  annotation = gp,
  gene_id = "GeneA",
  genotype_mode = "string"
)
#> [GeneTrackR] Retrieved variants: 11.

hap$haplotypes[, c(
  "hap_id",
  "sample_n",
  "samples"
), with = FALSE]
#> Key: <hap_id>
#>    hap_id sample_n                             samples
#>    <char>    <int>                              <char>
#> 1:   Hap1        9 S10;S11;S12;S13;S14;S15;S16;S17;S18
#> 2:   Hap2        9 S01;S02;S03;S04;S05;S06;S07;S08;S09
#> 3:   Hap3        9 S19;S20;S21;S22;S23;S24;S25;S26;S27
#> 4:   Hap4        9 S28;S29;S30;S31;S32;S33;S34;S35;S36

The deterministic GeneA example contains four balanced haplotype groups. Keep the returned HapVariant object: it carries sample assignments and genotype tables into phenotype, refinement, and variant-effect analyses.

Test a phenotype association

hap_pheno <- plot_hap_pheno(
  hap,
  phenotype = pheno,
  traits = "protein_content",
  min_hap_samples = 3,
  text_size = 10
)

hap_pheno$pvalue
#>              trait group1 group2      p_value        p_adj method
#>             <char> <char> <char>        <num>        <num> <char>
#> 1: protein_content   Hap2   Hap1 1.000000e+00 1.000000e+00 t.test
#> 2: protein_content   Hap2   Hap3 2.707879e-18 4.061818e-18 t.test
#> 3: protein_content   Hap2   Hap4 2.707879e-18 4.061818e-18 t.test
#> 4: protein_content   Hap1   Hap3 2.707879e-18 4.061818e-18 t.test
#> 5: protein_content   Hap1   Hap4 2.707879e-18 4.061818e-18 t.test
#> 6: protein_content   Hap3   Hap4 1.000000e+00 1.000000e+00 t.test

GeneTrackR aligns phenotype and genotype records by sample_id. Row order should never be used as the sample-matching rule.

Where to go next

Use the Getting Started articles in this order:

Getting started with GeneTrackR — installation and the minimal analysis above.
GeneTrackR deterministic example data — file inventory, coordinate conventions, sample design, and known positive/negative controls.
GeneTrackR core workflow — the full candidate-locus workflow from input validation and browser-like inspection through haplotypes, phenotype association, LD, refinement, variant effects, and export.

For signal-specific analyses, continue with Strand-specific RNA-seq and Ribo-seq signal tracks.

Session information

sessionInfo()
#> R version 4.6.1 (2026-06-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 26.04.1 LTS
#> 
#> 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.32.so;  LAPACK version 3.12.0
#> 
#> locale:
#>  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
#>  [3] LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8    
#>  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
#>  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
#>  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
#> 
#> time zone: Etc/UTC
#> tzcode source: system (glibc)
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] GeneTrackR_0.99.2 rmarkdown_2.32   
#> 
#> loaded via a namespace (and not attached):
#>  [1] gtable_0.3.6         jsonlite_2.0.0       crayon_1.5.3        
#>  [4] compiler_4.6.1       zip_3.0.2            Rcpp_1.1.2          
#>  [7] Biostrings_2.81.9    bitops_1.1-0         Rsamtools_2.29.0    
#> [10] GenomicRanges_1.65.4 parallel_4.6.1       jquerylib_0.1.4     
#> [13] IRanges_2.47.5       Seqinfo_1.3.2        scales_1.4.0        
#> [16] BiocParallel_1.47.0  yaml_2.3.12          fastmap_1.2.0       
#> [19] XVector_0.53.0       ggplot2_4.0.3        R6_2.6.1            
#> [22] patchwork_1.3.2      labeling_0.4.3       generics_0.1.4      
#> [25] openxlsx_4.2.9       knitr_1.52           BiocGenerics_0.59.12
#> [28] maketools_1.3.2      bslib_0.12.0         RColorBrewer_1.1-3  
#> [31] rlang_1.3.0          stringi_1.8.9        cachem_1.1.0        
#> [34] xfun_0.61            sass_0.4.10          sys_3.4.3           
#> [37] S7_0.2.2             otel_0.2.0           cli_3.6.6           
#> [40] withr_3.0.3          digest_0.6.39        grid_4.6.1          
#> [43] lifecycle_1.0.5      S4Vectors_0.51.10    vctrs_0.7.3         
#> [46] evaluate_1.0.5       glue_1.8.1           data.table_1.18.6.1 
#> [49] farver_2.1.2         codetools_0.2-20     buildtools_1.0.0    
#> [52] stats4_4.6.1         tools_4.6.1          htmltools_0.5.9