### Updating the map example

Source: https://waldronlab.io/HGNChelper/reference/checkGeneSymbols.html

This example shows how to update the default map by fetching the current human map from the interactive example. It also demonstrates saving the map to a file and loading it back.

```r
if (interactive()) {
    currentHumanMap <- getCurrentHumanMap()
    checkGeneSymbols(human, map=currentHumanMap)

    # You should save this if you're going to use it multiple times,   
    # then load it from file rather than burdening HGNC's servers.
    save(hgnc.table, file="hgnc.table.rda", compress="bzip2")
    load("hgnc.table.rda")
    checkGeneSymbols(human, map=hgnc.table)
}
```

--------------------------------

### Example: Using findExcelGeneSymbols with human and mouse maps

Source: https://waldronlab.io/HGNChelper/reference/findExcelGeneSymbols.html

Loads the human and mouse mogrification maps from the package, defines a regex to match Excel-mogrified symbols, and applies the function to example vectors. The output shows warnings and corrected symbols.

```R
## Available maps from this package:
human <- read.csv(system.file("extdata/mog_map.csv", 
                              package = "HGNChelper"), as.is=TRUE)
mouse <- read.csv(system.file("extdata/HGNChelper_mog_map_MGI_AMC_2016_03_30.csv", 
                              package = "HGNChelper"), as.is=TRUE)
## This regex is based that provided by Zeeberg et al.,
##  Mistaken Identifiers: Gene name errors can be introduced
## inadvertently when using Excel in bioinformatics.  BMC
##  Bioinformatics 2004, 5:80.
re <- "[0-9]\-(JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC)|[0-9]\.[0-9][0-9]E\+[[0-9][0-9]"
findExcelGeneSymbols(c("2-Apr", "APR2"), mog.map=human, regex=re)
#> Warning: Transmogrified gene symbols found.  Returning the following corrections: 2-Apr to 2-Apr
#> [1] "2-Apr" "APR2" 
findExcelGeneSymbols(c("1-Feb", "Feb1"), mog.map=mouse)
#> Warning: Transmogrified gene symbols found.  Returning the following corrections: 1-Feb to Feb1
#> [1] "Feb1" "Feb1"
```

--------------------------------

### Correct gene symbols using current maps

Source: https://waldronlab.io/HGNChelper/reference/getCurrentMaps.html

Example usage of getCurrentHumanMap and getCurrentMouseMap with checkGeneSymbols. For mouse, set species to "mouse" (or NULL) in checkGeneSymbols. The example is wrapped in \dontrun and will not run automatically.

```r
if (FALSE) { # \dontrun{
## human
new.hgnc.table <- getCurrentHumanMap()
checkGeneSymbols(c("3-Oct", "10-3", "tp53"), map=new.hgnc.table)

## mouse
new.mouse.table <- getCurrentMouseMap()
## Set species to NULL or "mouse" 
checkGeneSymbols(c("Gm46568", "1-Feb"), map=new.mouse.table, species="mouse")
} # }
```

--------------------------------

### Correcting human gene symbols with checkGeneSymbols

Source: https://waldronlab.io/HGNChelper/articles/index.html

Example of running checkGeneSymbols on a vector of human gene symbols, including outdated symbols and Excel date artifacts. The output warnings and resulting data.frame are displayed.

```r
library(HGNChelper)
#> Please cite our software :) 
#>  
#>  Sehyun Oh et al. HGNChelper: identification and correction of invalid gene symbols for human and mouse. F1000Research 2020, 9:1493. DOI: https://doi.org/10.12688/f1000research.28033.1 
#>  
#>  Type `citation('HGNChelper')` for a BibTeX entry.
human = c("FN1", "tp53", "UNKNOWNGENE","7-Sep", "9/7", "1-Mar", "Oct4", "4-Oct",
      "OCT4-PG4", "C19ORF71", "C19orf71")
checkGeneSymbols(human)
#> Maps last updated on: Sat Nov 16 10:35:32 2024
#> Warning in checkGeneSymbols(human): Human gene symbols should be all upper-case
#> except for the 'orf' in open reading frames. The case of some letters was
#> corrected.
#> Warning in checkGeneSymbols(human): x contains non-approved gene symbols
#>              x Approved   Suggested.Symbol
#> 1          FN1     TRUE                FN1
#> 2         tp53    FALSE               TP53
#> 3  UNKNOWNGENE    FALSE               <NA>
#> 4        7-Sep    FALSE            SEPTIN7
#> 5          9/7    FALSE            SEPTIN7
#> 6        1-Mar    FALSE MARCHF1 /// MTARC1
#> 7         Oct4    FALSE             POU5F1
#> 8        4-Oct    FALSE             POU5F1
#> 9     OCT4-PG4    FALSE           POU5F1P4
#> 10    C19ORF71    FALSE            TEKTIP1
#> 11    C19orf71    FALSE            TEKTIP1
```

--------------------------------

### Correcting mouse gene symbols with species="mouse"

Source: https://waldronlab.io/HGNChelper/articles/index.html

Example of running checkGeneSymbols on mouse gene symbols, specifying species="mouse". Demonstrates that symbols with internal capital letters (e.g., E430008G22Rik) cannot be fixed, and the unmap.as.na option can be used to keep unrecognized symbols as-is.

```r
checkGeneSymbols(c("1-Feb", "Pzp", "A2m", "E430008G22Rik"), species="mouse")
#> Maps last updated on: Sat Nov 16 10:35:32 2024
#> Warning in checkGeneSymbols(c("1-Feb", "Pzp", "A2m", "E430008G22Rik"), species
#> = "mouse"): x contains non-approved gene symbols
#>               x Approved Suggested.Symbol
#> 1         1-Feb    FALSE             Feb1
#> 2           Pzp     TRUE              Pzp
#> 3           A2m     TRUE              A2m
#> 4 E430008G22Rik    FALSE             <NA>
```

--------------------------------

### Get current human and mouse gene symbol maps

Source: https://waldronlab.io/HGNChelper/reference/getCurrentMaps.html

Call these functions to retrieve the latest valid gene symbol tables. Use getCurrentHumanMap for HGNC human symbols and getCurrentMouseMap for MGI mouse symbols. The returned data.frame can be passed to the map argument of checkGeneSymbols.

```r
getCurrentHumanMap()
getCurrentMouseMap()
```

--------------------------------

### Load and preview hgnc.table

Source: https://waldronlab.io/HGNChelper/reference/hgnc.table.html

Load the hgnc.table dataset and display the first six rows. The output shows the Symbol, Approved.Symbol, and chromosome columns for the first entries.

```r
data("hgnc.table", package="HGNChelper")
head(hgnc.table)
#>        Symbol Approved.Symbol chromosome
#>        <char>          <char>     <char>
#> 1:       A1BG            A1BG         19
#> 2:   A1BG-AS1        A1BG-AS1         19
#> 3:   FLJ23569        A1BG-AS1         19
#> 4:     A1BGAS        A1BG-AS1         19
#> 5:    A1BG-AS        A1BG-AS1         19
#> 6: NCRNA00181        A1BG-AS1         19
```

--------------------------------

### Load and preview mouse.table dataset

Source: https://waldronlab.io/HGNChelper/reference/mouse.table.html

Loads the mouse.table dataset from the HGNChelper package and displays the first six rows, showing the mapping of symbols to approved MGI symbols.

```r
data("mouse.table", package="HGNChelper")
head(mouse.table)
#>   Symbol Approved.Symbol
#> 1  1-Feb            Feb1
#> 2    2/1            Feb1
#> 3  02/01            Feb1
#> 4   2/01            Feb1
#> 5   02/1            Feb1
#> 6   02-1            Feb1
```

--------------------------------

### findExcelGeneSymbols function usage

Source: https://waldronlab.io/HGNChelper/reference/findExcelGeneSymbols.html

Shows the function signature and default arguments. The mog.map defaults to the package's human map, and the regex defaults to a pattern that matches nothing.

```R
findExcelGeneSymbols(
  x,
  mog.map = read.csv(system.file("extdata/mog_map.csv", package = "HGNChelper"), as.is =
    TRUE),
  regex = "impossibletomatch^"
)
```

--------------------------------

### rToAffy(x)

Source: https://waldronlab.io/HGNChelper/reference/rToAffy.html

Converts the output of affyToR back to the original Affymetrix probeset identifiers by stripping the 'affy.' prefix.

```APIDOC
## rToAffy(x)

### Description
This function simply strips the "affy." added by the affyToR function.

### Usage
```r
rToAffy(x)
```

### Arguments
- **x** - the character vector returned by the affyToR function.

### Value
a character vector of Affymetrix probeset identifiers.
```

--------------------------------

### Use expand.ambiguous with checkGeneSymbols for mouse genes Cpamd8 and Mug2

Source: https://waldronlab.io/HGNChelper/articles/index.html

Shows the effect of expand.ambiguous for mouse gene symbols. With FALSE, each symbol is returned as approved; with TRUE, the output includes all mappings, showing that Cpamd8 and Mug2 are ambiguous.

```r
checkGeneSymbols(c("Cpamd8", "Mug2"), species = "mouse", expand.ambiguous = FALSE)
#> Maps last updated on: Sat Nov 16 10:35:32 2024
#>        x Approved Suggested.Symbol
#> 1 Cpamd8     TRUE           Cpamd8
#> 2   Mug2     TRUE             Mug2
checkGeneSymbols(c("Cpamd8", "Mug2"), species = "mouse", expand.ambiguous = TRUE)
#> Maps last updated on: Sat Nov 16 10:35:32 2024
#>        x Approved Suggested.Symbol
#> 1 Cpamd8     TRUE  Cpamd8 /// Mug2
#> 2   Mug2     TRUE  Mug2 /// Cpamd8
```

--------------------------------

### affyToR(x)

Source: https://waldronlab.io/HGNChelper/reference/affyToR.html

Prepends 'affy.' to each element of the input vector to create valid R names. The reverse operation is performed by the rToAffy function.

```APIDOC
## affyToR(x)

### Description
This function simply prepends "affy." to the probeset IDs to create valid R names. Reverse operation is done by the rToAffy function.

### Usage
```r
affyToR(x)
```

### Arguments
- **x** - vector of Affymetrix probeset identifiers, or any identifier which may with a digit.

### Value
A character vector that is simply x with "affy." prepended to each value.
```

--------------------------------

### Use expand.ambiguous with checkGeneSymbols for human gene AAVS1

Source: https://waldronlab.io/HGNChelper/articles/index.html

Demonstrates the expand.ambiguous argument for a human gene symbol. With FALSE, only the approved symbol is returned; with TRUE, all mappings are shown, including aliases that are now approved symbols.

```r
checkGeneSymbols("AAVS1", expand.ambiguous = FALSE)
#> Maps last updated on: Sat Nov 16 10:35:32 2024
#>       x Approved Suggested.Symbol
#> 1 AAVS1     TRUE            AAVS1
checkGeneSymbols("AAVS1", expand.ambiguous = TRUE)
#> Maps last updated on: Sat Nov 16 10:35:32 2024
#>       x Approved   Suggested.Symbol
#> 1 AAVS1     TRUE AAVS1 /// PPP1R12C
```

--------------------------------

### Cite HGNChelper with BibTeX entry

Source: https://waldronlab.io/HGNChelper/authors.html

BibTeX entry for citing the HGNChelper package. Use this in LaTeX documents to cite the F1000Research article by Oh et al. (2020).

```bibtex
@Article{,
  entry = {Article},
  title = {HGNChelper: identification and correction of invalid gene symbols for human and mouse},
  author = {Sehyun Oh and Jasmine Abdelnabi and Ragheed Al-Dulaimi and Ayush Aggarwal and Marcel Ramos and Carmen Rodriguez Cabrera and Tiffany Chan and Sean Davis and Markus Riester and Levi Waldron},
  journal = {F1000 Research},
  year = {2020},
  volume = {9:1493},
}
```

--------------------------------

### Inspect dimensions of mouse.table and hgnc.table

Source: https://waldronlab.io/HGNChelper/articles/index.html

Shows the dimensions of the built-in mouse and human gene symbol tables shipped with HGNChelper. The mouse table has 790110 rows and 2 columns, while the human table has 103939 rows and 3 columns.

```r
dim(mouse.table)
#> [1] 790110      2
dim(hgnc.table)
#> [1] 103939      3
```

--------------------------------

### checking human and mouse gene symbols

Source: https://waldronlab.io/HGNChelper/reference/checkGeneSymbols.html

The first block runs checkGeneSymbols on human symbols including the output warnings. The second block checks mouse symbols with the species argument set to the third block covers the expand.ambiguous FALSE and TRUE for the human gene AAVS1. The fourth block covers the same for mouse genes with species set

```r
library(HGNChelper)

## Human
human <- c("FN1", "TP53", "UNKNOWNGENE","7-Sep", "9/7", "1-Mar", "Oct4", "4-Oct",
      "OCT4-PG4", "C19ORF71", "C19orf71")
checkGeneSymbols(human)
```

```r
## Mouse
mouse <- c("1-Feb", "Pzp", "A2m")
checkGeneSymbols(mouse, species="mouse")
```

```r
## expand.ambiguous

## Human
human <- "AAVS1"
checkGeneSymbols(human, expand.ambiguous=FALSE)
```

```r
checkGeneSymbols(human, expand.ambiguous=TRUE)
```

```r
## Mouse
mouse <- c("Cpamd8", "Mug2")
checkGeneSymbols(mouse, species = "mouse", expand.ambiguous = FALSE)
```

```r
checkGeneSymbols(mouse, species = "mouse", expand.ambiguous = TRUE)
```

--------------------------------

### Access hgnc.table dataset

Source: https://waldronlab.io/HGNChelper/reference/hgnc.table.html

Access the built-in dataset object. The object is a data.table with 103939 rows and 3 columns: Symbol, Approved.Symbol, and chromosome.

```r
hgnc.table
```

--------------------------------

### checkGeneSymbols function usage

Source: https://waldronlab.io/HGNChelper/reference/checkGeneSymbols.html

Shows the function signature and all arguments. x is a character vector of gene symbols. chromosome is optional, only for human. unmapped.as.na controls NA for unmapped symbols. species defaults to "human" but can be "mouse" or other. expand.ambiguous controls handling of ambiguous mappings.

```r
checkGeneSymbols(
  x,
  chromosome = NULL,
  unmapped.as.na = TRUE,
  map = NULL,
  species = "human",
  expand.ambiguous = FALSE
)
```

--------------------------------

### checkGeneSymbols(x, chromosome, unmapped.as.na, map, species, expand.ambiguous)

Source: https://waldronlab.io/HGNChelper/reference/checkGeneSymbols.html

Checks gene symbols for outdated or Excel-mogrified values and returns a data.frame with validity and suggested corrections.

```APIDOC
## checkGeneSymbols

### Description
Identifies gene symbols which are outdated or may have been mogrified by Excel or other spreadsheet programs. If output is assigned to a variable, 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.

### Usage
```r
checkGeneSymbols(
  x,
  chromosome = NULL,
  unmapped.as.na = TRUE,
  map = NULL,
  species = "human",
  expand.ambiguous = FALSE
)
```

### Arguments
- **x** (character vector) - Required - A character vector of gene symbols to check for modified or outdated values.
- **chromosome** (integer vector) - Optional - An optional integer vector containing the chromosome number of each gene provided through the argument `x`. It should be the same length as the input for `x`. Currently, this argument is implemented only for human gene cases.
- **unmapped.as.na** (logical) - Optional - If `TRUE` (default), unmapped symbols will appear as NA in the `Suggested.Symbol` column. If `FALSE`, the original unmapped symbol will be kept.
- **map** (data.frame) - Optional - Specify if you do not want to use the default maps provided by setting species equal to "mouse" or "human". Map can be any other data.frame with colnames identical to `c("Symbol", "Approved.Symbol")`. The default maps can be updated by running the interactive example below.
- **species** (character) - Optional - A character vector of length 1, either "human" (default) or "mouse". If `NULL`, or anything other than "human" or "mouse", then the map argument must be provided.
- **expand.ambiguous** (logical) - Optional - If `FALSE` (default), genes with multiple mapping will only map to its approved symbol as the correct one. If `TRUE`, genes with multiple/ambiguous mapping will map to all the symbols linked to it.

### Value
Returns a data.frame of the same number of rows as the input, with corrections possible from map.

### Examples
```r
library(HGNChelper)

## Human
human <- c("FN1", "TP53", "UNKNOWNGENE","7-Sep", "9/7", "1-Mar", "Oct4", "4-Oct",
      "OCT4-PG4", "C19ORF71", "C19orf71")
checkGeneSymbols(human)
#> Maps last updated on: Sat Nov 16 10:35:32 2024
#> Warning: Human gene symbols should be all upper-case except for the 'orf' in open reading frames. The case of some letters was corrected.
#> Warning: x contains non-approved gene symbols
#>              x Approved   Suggested.Symbol
#> 1          FN1     TRUE                FN1
#> 2         TP53     TRUE               TP53
#> 3  UNKNOWNGENE    FALSE               <NA>
#> 4        7-Sep    FALSE            SEPTIN7
#> 5          9/7    FALSE            SEPTIN7
#> 6        1-Mar    FALSE MARCHF1 /// MTARC1
#> 7         Oct4    FALSE             POU5F1
#> 8        4-Oct    FALSE             POU5F1
#> 9     OCT4-PG4    FALSE           POU5F1P4
#> 10    C19ORF71    FALSE            TEKTIP1
#> 11    C19orf71    FALSE            TEKTIP1

## Mouse
mouse <- c("1-Feb", "Pzp", "A2m")
checkGeneSymbols(mouse, species="mouse")
#> Maps last updated on: Sat Nov 16 10:35:32 2024
#> Warning: x contains non-approved gene symbols
#>       x Approved Suggested.Symbol
#> 1 1-Feb    FALSE             Feb1
#> 2   Pzp     TRUE              Pzp
#> 3   A2m     TRUE              A2m

## expand.ambiguous

## Human
human <- "AAVS1"
checkGeneSymbols(human, expand.ambiguous=FALSE)
#> Maps last updated on: Sat Nov 16 10:35:32 2024
#>       x Approved Suggested.Symbol
#> 1 AAVS1     TRUE            AAVS1
checkGeneSymbols(human, expand.ambiguous=TRUE)
#> Maps last updated on: Sat Nov 16 10:35:32 2024
#>       x Approved   Suggested.Symbol
#> 1 AAVS1     TRUE AAVS1 /// PPP1R12C

## Mouse
mouse <- c("Cpamd8", "Mug2")
checkGeneSymbols(mouse, species = "mouse", expand.ambiguous = FALSE)
#> Maps last updated on: Sat Nov 16 10:35:32 2024
#>        x Approved Suggested.Symbol
#> 1 Cpamd8     TRUE           Cpamd8
#> 2   Mug2     TRUE             Mug2
checkGeneSymbols(mouse, species = "mouse", expand.ambiguous = TRUE)
#> Maps last updated on: Sat Nov 16 10:35:32 2024
#>        x Approved Suggested.Symbol
#> 1 Cpamd8     TRUE  Cpamd8 /// Mug2
#> 2   Mug2     TRUE  Mug2 /// Cpamd8

## Updating the map
if (interactive()) {
    currentHumanMap <- getCurrentHumanMap()
    checkGeneSymbols(human, map=currentHumanMap)

    # You should save this if you are going to use it multiple times,   
    # then load it from file rather than burdening HGNC's servers.
    save(hgnc.table, file="hgnc.table.rda", compress="bzip2")
    load("hgnc.table.rda")
    checkGeneSymbols(human, map=hgnc.table)
}
```

### See Also
`mouse.table` for the mouse lookup table, `hgnc.table` for the human lookup table
```

--------------------------------

### symbolToR(x)

Source: https://waldronlab.io/HGNChelper/reference/symbolToR.html

Converts a vector of HGNC gene symbols into valid R names. The function performs reversible transformations to ensure valid R syntax. The result can be converted back using the accompanying `rToSymbol` function.

```APIDOC
## symbolToR(x)

### Description
Converts HGNC gene symbols to valid R names, allowing reversible transformation back to the original symbols.

### Usage
```r
symbolToR(x)
```

### Arguments
- **x** (vector) - Required - A vector of HGNC symbols.

### Value
A vector of valid R names, of the same length as `x`, which can be converted back to the original HGNC symbols using the `rToSymbol` function.
```

--------------------------------

### findExcelGeneSymbols(x, mog.map, regex)

Source: https://waldronlab.io/HGNChelper/reference/findExcelGeneSymbols.html

Identifies gene symbols that may have been mogrified by Excel or other spreadsheet programs. If the output is assigned to a variable, it returns a vector of the same length with corrections applied where possible.

```APIDOC
## findExcelGeneSymbols(x, mog.map, regex)

### Description
Identifies gene symbols which may have been mogrified by Excel or other spreadsheet programs. If output is assigned to a variable, it returns a vector of the same length where symbols which could be mapped have been mapped.

### Usage
```r
findExcelGeneSymbols(
  x,
  mog.map = read.csv(system.file("extdata/mog_map.csv", package = "HGNChelper"), as.is = TRUE),
  regex = "impossibletomatch^"
)
```

### Arguments
- **x** (vector) - Required - Vector of gene symbols to check for mogrified values.
- **mog.map** (dataframe) - Optional - Map of known mogrifications. Should be a dataframe with two columns: `original` and `mogrified`, containing the correct and incorrect symbols, respectively.
- **regex** (character) - Optional - Regular expression, recognized by `base::grep` with `ignore.case=TRUE`, to identify mogrified symbols. The default regex will not match anything.

### Value
If the return value is assigned to a variable, the function returns a vector of the same length as the input, with corrections possible from `mog.map` made.

### Examples
```r
## Available maps from this package:
human <- read.csv(system.file("extdata/mog_map.csv", 
                              package = "HGNChelper"), as.is=TRUE)
mouse <- read.csv(system.file("extdata/HGNChelper_mog_map_MGI_AMC_2016_03_30.csv", 
                              package = "HGNChelper"), as.is=TRUE)
## This regex is based that provided by Zeeberg et al.,
##  Mistaken Identifiers: Gene name errors can be introduced
## inadvertently when using Excel in bioinformatics.  BMC
##  Bioinformatics 2004, 5:80.
re <- "[0-9]\\-(JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC)|[0-9]\\.[0-9][0-9]E\\+[[0-9][0-9]"
findExcelGeneSymbols(c("2-Apr", "APR2"), mog.map=human, regex=re)
#> Warning: Transmogrified gene symbols found.  Returning the following corrections: 2-Apr to 2-Apr
#> [1] "2-Apr" "APR2" 
findExcelGeneSymbols(c("1-Feb", "Feb1"), mog.map=mouse)
#> Warning: Transmogrified gene symbols found.  Returning the following corrections: 1-Feb to Feb1
#> [1] "Feb1" "Feb1"
```
```

--------------------------------

### rToSymbol

Source: https://waldronlab.io/HGNChelper/reference/rToSymbol.html

This function reverses the conversion made by the symbolToR function, converting a character vector of R-compatible names back to HGNC gene symbols.

```APIDOC
## rToSymbol(x)

### Description
Reverses the actions of the symbolToR function.

### Usage
```r
rToSymbol(x)
```

### Arguments
- **x** - the character vector returned by the symbolToR function.

### Value
A character vector of HGNC gene symbols, which are not in general valid R names.

### See Also
`symbolToR`
```

--------------------------------

### checkGeneSymbols function signature

Source: https://waldronlab.io/HGNChelper/articles/index.html

The primary function signature of HGNChelper. It identifies outdated or spreadsheet-mogrified gene symbols for human or mouse. The 'map' and 'species' arguments allow customization.

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

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.