---
title: "HGNChelper Introduction"
author: "Levi Waldron and Markus Riester"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{HGNChelper Introduction}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Why HGNChelper?

Physicians and biologists like gene symbols and bioinformaticians hate'em. Why? For one thing, they change constantly and are given new names or aliases. For another, some get munged into dates when imported into spreadsheet programs - and not only Excel (Thank you [\@karawoo](https://twitter.com/kara_woo) for the [picture](https://twitter.com/kara_woo/status/1020054225022173184)!):

![](0DaysSince.png)

Myself (Levi speaking), I don't mind them. It's way easier to remember [TP53](http://www.genenames.org/cgi-bin/gene_symbol_report?hgnc_id=11998) than to remember [7157](http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?db=gene&cmd=Retrieve&dopt=full_report&list_uids=7157) or [ENSG00000141510](http://www.ensembl.org/Homo_sapiens/geneview?gene=ENSG00000141510). They're a fact of life. So Markus Riester and I wrote HGNChelper to make them a little more pleasant to bioinformaticians. 

## HGNChelper functionality

HGNChelper has several functions that seemed useful back in the day when we first wrote it, but really one has withstood the test of time and remained useful:

```{r, eval=FALSE}
checkGeneSymbols(x, unmapped.as.na = TRUE, map = NULL, species = "human")
```

`checkGeneSymbols` identifies HGNC human or MGI mouse gene symbols which are outdated or may have been mogrified by Excel or other spreadsheet programs. It returns a data.frame of the same number of rows as the input, with a second column indicating whether the symbols are valid and a third column with a corrected gene list. 

```{r}
library(HGNChelper)
human = c("FN1", "tp53", "UNKNOWNGENE","7-Sep", "9/7", "1-Mar", "Oct4", "4-Oct",
      "OCT4-PG4", "C19ORF71", "C19orf71")
checkGeneSymbols(human)
```

As you see, it even helps fix capitalization. How does it fix those Excel dates? I imported a column of all human gene symbols into Excel, then exported using a whole bunch of available date formats. Then I kept any that differed from the originals for HGNChelper's map. 

## Mouse gene symbols

**Warning** the list of valid mouse symbols seems to be incomplete, see below. Mouse genes work the same way, but you need to specify the argument `species=mouse`:

```{r}
checkGeneSymbols(c("1-Feb", "Pzp", "A2m"), species="mouse")
```

I don't work with mouse data, so use this functionality with care and please let me know if you have any suggestions. For one thing, [Pzp](http://www.informatics.jax.org/marker/MGI:87854) in the above example is a valid gene symbol, but it is not in the [MGI_EntrezGene.rpt](http://www.informatics.jax.org/downloads/reports/MGI_EntrezGene.rpt) file I used to build a map. [Suggestions welcome](https://github.com/waldronlab/HGNChelper/issues) about how to build a more complete map of valid symbols. To be on the safe side, you could set `unmapped.as.na = FALSE` to keep unrecognized symbols as-is and only correct ones that have a definitive correction.

## What exactly checkGeneSymbols does

HGNChelper does the following corrections:

1. fix capitalization (for human only). Only **orf** genes are allowed to have lower-case letters.
2. fix Excel-mogrified symbols
3. fix symbols that are listed as aliases to a more recent symbol in the [HGNC](https://www.genenames.org/) or [MGI](http://www.informatics.jax.org/) (MGI_EntrezGene_rpt) database.

Numbers 2 and 3 are done by comparing to a complete map of both valid and invalid but mappable symbols, shipped with HGNChelper:

```{r}
dim(mouse.table)
dim(hgnc.table)
```

These are a combination of manually generated Excel mogrifications that remain constant, and aliases that can become out of date with time.

## Updating maps of aliased gene symbols

Gene symbols are aliased much more frequently than I can update this package, like every day. If you want the most current maps of aliases, you can either:

1. use the `getCurrentHumanMap()` or `getCurrentMouseMap()` function, and provide the returned result through the `map=` argument of `checkGeneSymbols()`, or
2. See the instructions for updating your package locally at https://github.com/waldronlab/HGNChelper (it's just one command-line command as long as you have R and [roxygen2](https://cran.r-project.org/package=roxygen2) installed)

## Where do I find HGNChelper?

* CRAN: https://cran.r-project.org/package=HGNChelper
* GitHub: https://github.com/waldronlab/HGNChelper

Please report any issues at https://github.com/waldronlab/HGNChelper/issues