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

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

## Overview

IDConverter converts identifiers within and between biological databases.
Core use cases:

- **TCGA/ICGC/PCAWG** sample ID conversion
- **Human ↔ Mouse** gene ortholog mapping
- **Gene symbol ↔ Ensembl ID** conversion
- **Gene alias** resolution
- **GDC manifest** parsing and tumor-normal pairing

## ID Conversion

```{r}
library(IDConverter)

# TCGA sample ID → patient ID
convert_tcga("TCGA-02-0001-10")

# ICGC specimen → donor
convert_icgc("SP29019")

# PCAWG specimen → donor
convert_pcawg("SP1677")
```

## Gene ID Conversion

```{r eval=FALSE}
# Symbol → Ensembl (human)
convert_hm_genes(c("TP53", "KRAS"), type = "symbol")

# Ensembl → Symbol (human)
convert_hm_genes("ENSG00000141510")

# Human → Mouse orthologs
convert_hm_orthologs(c("TP53", "KRAS"))
```

## Gene Annotation Tables

```{r eval=FALSE}
# List available tables
ls_annotables()

# Load from Zenodo (fixed version, works offline)
grch38 <- load_data("grch38")

# Or build from Ensembl BioMart (latest, requires biomaRt + internet)
grch38_latest <- build_annotables("grch38", tx2gene = FALSE)
```

## Working with Custom Databases

```{r}
dt <- data.table::data.table(
  UpperCase = LETTERS[1:5],
  LowerCase = letters[1:5]
)
convert_custom(c("B", "C", "E"), from = "UpperCase", to = "LowerCase", dt = dt)
```