---
title: "Getting started with GeneTrackR"
author: "Shuchao Ren"
date: "2026-08-31"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{01 Getting started with GeneTrackR}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
gtr_pkgdown <- tolower(Sys.getenv("GENETRACKR_PKGDOWN", "false")) %in%
  c("1", "true", "yes")
gtr_vignette_dpi <- if (gtr_pkgdown) 300 else 144

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 10.5,
  fig.height = 6,
  dpi = gtr_vignette_dpi,
  fig.retina = 1,
  out.width = "100%",
  fig.align = "center"
)
```

## 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`:

```{r installation, eval=FALSE}
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

```{r load-package}
library(GeneTrackR)
```

## Locate the bundled example data

The core demo files are installed under `extdata`:

```{r demo-paths}
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
)
```

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

```{r read-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.

```{r inspect-gene}
genea <- retrieve_feature(
  gp,
  gene_id = "GeneA"
)

genea$genes
```

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

```{r plot-gene}
plot_gene(
  gp,
  gene_id = "GeneA",
  text_size = 10
)
```

## Retrieve variants for the same locus

```{r retrieve-variants}
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
)]
```

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

## Build gene haplotypes

```{r build-haplotypes}
hap <- hap_gene_variant(
  vcf,
  annotation = gp,
  gene_id = "GeneA",
  genotype_mode = "string"
)

hap$haplotypes[, c(
  "hap_id",
  "sample_n",
  "samples"
), with = FALSE]
```

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

```{r haplotype-phenotype}
hap_pheno <- plot_hap_pheno(
  hap,
  phenotype = pheno,
  traits = "protein_content",
  min_hap_samples = 3,
  text_size = 10
)

hap_pheno$pvalue
```

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:

1. **Getting started with GeneTrackR** — installation and the minimal analysis above.
2. **GeneTrackR deterministic example data** — file inventory, coordinate conventions, sample design, and known positive/negative controls.
3. **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

```{r session-info}
sessionInfo()
```