---
title: "Getting started with ggvariant"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with ggvariant}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse  = TRUE,
  comment   = "#>",
  fig.width = 7,
  fig.height = 4.5,
  out.width = "100%"
)
```

## Overview

This vignette walks through a complete `ggvariant` workflow: loading variant
data from a VCF file or a data frame, plotting variant positions along a
gene, summarising consequences across samples and genes, and visualising the
mutational spectrum. By the end you will have produced each of the package's
core plot types against the bundled example data and know how to point them
at your own.

## Installation

```{r install, eval = FALSE}
# Install from CRAN
install.packages("ggvariant")

# Or install the development version from GitHub
# remotes::install_github("yourname/ggvariant")
```

```{r load}
library(ggvariant)
```

## Loading variant data

### Option 1: From a VCF file

`read_vcf()` parses standard VCF v4.x files — including gzipped files and
multi-sample VCFs — and returns a tidy data frame called a `gvf` object.
Functional annotations from SnpEff (`ANN`) or VEP (`CSQ`) INFO fields are
extracted automatically.

```{r read-vcf}
vcf_file <- system.file("extdata", "example.vcf", package = "ggvariant")
variants  <- read_vcf(vcf_file)

head(variants)
```

The result is a plain data frame with one row per variant per sample, with
columns for chromosome, position, alleles, consequence, gene, and sample name.
Because it is a standard data frame, you can filter, subset, and manipulate it
with any R tools you already know.

### Option 2: From a data frame or Excel export

If your variants are in a spreadsheet or the output of another tool, use
`coerce_variants()` to map your column names onto the format `ggvariant`
expects. You only need to specify the columns that differ from the defaults.

```{r coerce, eval = FALSE}
# Example: data exported from a custom pipeline or Excel
my_df <- read.csv("my_variants.csv")

variants <- coerce_variants(my_df,
  chrom       = "Chr",
  pos         = "Position",
  ref         = "Ref_Allele",
  alt         = "Alt_Allele",
  consequence = "Variant_Class",
  gene        = "Hugo_Symbol",
  sample      = "Tumor_Sample"
)
```

Any extra columns in your data frame are carried over automatically, so you
never lose information.

## Lollipop plot

The lollipop plot shows where variants fall along a gene, coloured by
consequence. It is particularly useful for identifying mutational hotspots —
positions that are recurrently mutated across samples.

```{r lollipop-basic}
plot_lollipop(variants, gene = "TP53")
```

### Adding protein domain annotations

Overlaying known protein domains helps interpret *where* variants fall
functionally. Provide a data frame with `name`, `start`, and `end` columns
(in amino acid coordinates):

```{r lollipop-domains}
tp53_domains <- data.frame(
  name  = c("Transactivation", "DNA-binding", "Tetramerization"),
  start = c(1,   102, 323),
  end   = c(67,  292, 356)
)

# Scale genomic positions to protein coordinates
tp53 <- variants[variants$gene == "TP53", ]
tp53$pos <- round(
  (tp53$pos - min(tp53$pos)) /
  (max(tp53$pos) - min(tp53$pos)) * 393
) + 1

plot_lollipop(tp53, gene = "TP53",
              domains        = tp53_domains,
              protein_length = 393)
```

### Colouring by sample

To see which sample each variant comes from instead of its consequence,
change `color_by`:

```{r lollipop-sample}
plot_lollipop(variants, gene = "TP53", color_by = "sample")
```

### Customising further

Because every `ggvariant` function returns a standard `ggplot` object, you
can add any `ggplot2` layers on top:

```{r lollipop-custom}
library(ggplot2)

plot_lollipop(variants, gene = "KRAS") +
  labs(subtitle = "KRAS mutations across TUMOR_S1 and TUMOR_S2") +
  theme(legend.position = "bottom")
```

## Consequence summary

`plot_consequence_summary()` gives an overview of what *types* of variants are
present — missense, frameshift, synonymous, and so on — broken down by sample
or gene.

### By sample

```{r consequence-sample}
plot_consequence_summary(variants)
```

Each bar represents one sample, stacked by consequence type. This immediately
reveals whether two samples have similar or very different mutational profiles.

### Proportional view

To compare samples with different total variant counts fairly, use
`position = "fill"`:

```{r consequence-fill}
plot_consequence_summary(variants, position = "fill")
```

### By gene

To see which genes carry the most variants and what types they are:

```{r consequence-gene}
plot_consequence_summary(variants, group_by = "gene", top_n = 7)
```

TP53 stands out immediately as the most mutated gene, a pattern typical of
many cancer cohorts.

## Mutational spectrum

The mutational spectrum shows the relative frequency of each of the six
single-base substitution (SBS) classes — C>A, C>G, C>T, T>A, T>C, T>G —
normalised to the pyrimidine base (so A>G is represented as T>C, matching
COSMIC convention).

```{r spectrum}
plot_variant_spectrum(variants)
```

C>T substitutions are the most common class in this example. In real data, a strongly C>T-dominant spectrum can point to processes such as UV damage or age-related deamination, though interpreting a signature reliably requires many more mutations than this small example contains.

### Faceted by sample

To compare mutational processes between samples side by side:

```{r spectrum-facet}
plot_variant_spectrum(variants, facet_by_sample = TRUE)
```

## Interactive plots

All plot functions support `interactive = TRUE`, which wraps the output in
a `plotly` interactive plot. This is ideal for sharing with collaborators
who don't use R — simply save as an HTML file and send it.

```{r interactive, eval = FALSE}
# Requires the plotly package
# install.packages("plotly")

p <- plot_lollipop(variants, gene = "TP53", interactive = TRUE)
p  # opens in RStudio viewer or browser
```

## Colour palettes and theming

### Access the built-in palettes

```{r palette}
# See the consequence colour palette
gv_palette("consequence")

# See the COSMIC SBS spectrum palette
gv_palette("spectrum")
```

### Apply the theme to your own plots

`theme_ggvariant()` is exported so you can apply the same clean look to
any ggplot2 figure in your analysis:

```{r theme, eval = FALSE}
ggplot(my_data, aes(x, y)) +
  geom_point() +
  theme_ggvariant()
```

## Summary

| Function | Input | Output |
|---|---|---|
| `read_vcf()` | VCF file path | `gvf` data frame |
| `coerce_variants()` | Any data frame | `gvf` data frame |
| `plot_lollipop()` | `gvf` + gene name | Lollipop `ggplot` |
| `plot_consequence_summary()` | `gvf` | Stacked bar `ggplot` |
| `plot_variant_spectrum()` | `gvf` | SBS spectrum `ggplot` |
| `gv_palette()` | palette type | Named colour vector |
| `theme_ggvariant()` | — | `ggplot2` theme |

All plot functions return a `ggplot` object — extend them freely with
standard `ggplot2` syntax, and use `interactive = TRUE` with any of them
to get a `plotly` interactive version.

## Session information

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