knitr::opts_chunk$set(collapse = F, comment = '', collapse = TRUE)

library(magrittr)
library(hgnc)

quick start

For impatient people, you can convert a probe-ensembl map like the following [^probe2ensembl]

probe2ensembl <- tibble::tribble(
  ~ID,           ~Ensembl,                                                 
  "200064_at",   "ENSG00000096384",                                        
  "200066_at",   "ENSG00000113141",                                        
  "200068_s_at", "ENSG00000127022",                                        
  "200069_at",   "ENSG00000075856",                                        
  "200071_at",   "ENSG00000119953",                                        
  "200076_s_at", "ENSG00000105700",                                        
  "200077_s_at", "ENSG00000104904",                                        
  "200078_s_at", "ENSG00000117410",                                        
  "200082_s_at", "ENSG00000171863 /// ENSG00000183405 /// ENSG00000213326",
  "200084_at",   "ENSG00000110696"
)

probe2ensembl

[^probe2ensembl]: how I create probe2ensembl

```r
# read probe annotation from a GSE SOFT file
soft_table <- system.file("extdata/GSE19161_family.soft.gz", package = "rGEO") %>% 
    rGEO::parse_gse_soft(verbose = F) %>% {.$table}
# subset part of the table for the purpose of demostration
probe2ensembl <- soft_table %>% dplyr::select(1, 9) %>% dplyr::slice(41:50)
```

to a probe-symbol map ^[Ensembl IDs which don't have corresponding HUGO symbol are discarded.]

probe2_symbol <- probe2ensembl %>% melt_map("ID", "Ensembl", " /// ") %>%
    dplyr::mutate("symbol" = as_symbol_from_ensembl(Ensembl)) %>%
    cast_map("ID", "symbol", " /// ")

probe2_symbol

Other common ID like entrez gene ID, Unigene ID, RefSeq accession are also supported.

innovation

the problem

probe2id <- tibble::tribble(  
    ~probe, ~id,
    "probe1", "id1 | id2",
    "probe2", "id3"
)

probe2symbol <- tibble::tribble(  
    ~probe, ~symbol,
    "probe1", "symbol1 | symbol2",
    "probe2", "symbol3"
)

To master this package, you need to understand the problem it aims to solve. That is, to turn something like

probe2id

to

probe2symbol

solve a simpler one

probe2id_easy <- tibble::tribble(  
    ~probe, ~id,
    "probe4", "id4",
    "probe5", "id5",
    "probe6", "id6"
)

probe2symbol_easy <- tibble::tribble(  
    ~probe, ~symbol,
    "probe4", "symbol4",
    "probe5", "symbol5",
    "probe6", "symbol6"
)

To point out the key difficulty, let's contrast it with a simpler one --- to turn something like

probe2id_easy

to

probe2symbol_easy

That's quite easy, you just need a id-symbol map,

id2symbol <- tibble::tibble(  
    id = paste0("id", 1:6),
    symbol = paste0("symbol", 1:6)
) %>% dplyr::sample_frac()

id2symbol

and use the following code ^[I deliberately shuffle the rows of id2symbol to show that id2symbol just need to provide the correct relationship between id and symbol, i.e, it doesn't necessarily maintain the same order as probe2id.]

dplyr::transmute(probe2id_easy, probe, symbol = id2symbol$symbol[match(id, id2symbol$id)])

In the above code, we map probe to symbol in three steps:

  1. dplyr::transmute preserves probe2id$probe - probe2id$id relationship by position
  2. match() finds probe2id$id - id2symbol$id relationship by value
  3. [] finds id2symbol$id - id2symbol$symbol relationship by position

Let's us understand the example by a concrete example of "probe4" to "symbol4":

  1. 1st element of probe2id$probe -> 1st element of probe2id$id:
    "probe4" is the 1st element of probe2id$probe, so we look for the 1st element of probe2id$id, "id4".

  2. "id4" in probe2id$id -> "id4" in id2symbol$id:
    "id4" is the 1st element of probe2id$id, then we look for the 1st element of match() (which gives the position of probe2id$id in id2symbol$id --- c(`r match(probe2id$id, id2symbol$id)`) in this case). We get 3, so we look for the 3rd element of id2symbol$id, the exact value of "id4".

  3. 3rd element of id2symbol$id -> 3rd element of id2symbol$symbol:
    finally, "id4" is the 3rd element of `id2symbol$id, thus we look for the 3rd element of id2symbol$symbol, "symbol4".

key difficulty

Back the original problem, you can find that its fairly easy to "replace" "id4" with "symbol4", "id5" with "symbol5", etc (thanks to match()). But how can you "replace" the "id1" and "id2" inside "id1 | id2"?

That is what we meet exactly, as in the 9th line of probe2ensembl.

probe2ensembl %>% dplyr::slice(9)

If you think it's a piece of cake, you may have some misunderstanding:

r hgnc::ensembl2symbol %>% dplyr::sample_n(3)

solution

Inspired by reshape2, I choose to melt the wide map

probe2id_wide <- probe2id

probe2id_wide

to a long map.

probe2id_long <- probe2id_wide %>% melt_map("probe", "id", " \\| ")

probe2id_long

Then map id to symbol to get a new long map, following the way we solve the simpler problem abobe.

probe2symbol_long <- probe2id_long %>% 
    dplyr::transmute(probe, symbol = id2symbol$symbol[match(id, id2symbol$id)])

probe2symbol_long

Finally cast to a new wide map

probe2symbol_wide <- probe2symbol_long %>% cast_map("probe", "symbol", " /// ")

probe2symbol_wide   # now it's identical to probe2symbol

In short, A-B wide map -> A-B long map -> A-C long map -> A-C wide map.

real world

In above discussion, I abstract away many details to focus on core idea. Things get more complicated in real world:

Armed by with above weapon, the package can serves as the workhorse of rGEO to transform any user-supplied GPL file to standard chip file ready for GSEA.



dongzhuoer/hgnc documentation built on Aug. 7, 2020, 8:39 a.m.