The mapIds method for SomaDb objects

mapIds will retrieve SomaScan annotations (as a named vector) based on the parameters provided by the keys, columns, and keytype arguments. The default keytype is "PROBEID", e.g. the SomaLogic SeqId; this value will be used to tie all annotations back to a SomaScan-specific identifier.

Usage

# S4 method for SomaDb
mapIds(
  x,
  keys,
  column,
  keytype,
  menu = NULL,
  match = FALSE,
  ...,
  multiVals = c("filter", "asNA", "first", "list", "CharacterList")
)

Arguments

x

the AnnotationDb object. But in practice this will mean an object derived from an AnnotationDb object such as a OrgDb or ChipDb object.

keys

the keys to select records for from the database. All possible keys are returned by using the keys method.

column

the column to search on (for mapIds). Different from columns in that it can only have a single element for the value

keytype

the keytype that matches the keys used. For the select methods, this is used to indicate the kind of ID being used with the keys argument. For the keys method this is used to indicate which kind of keys are desired from keys

menu

a character string identifying a SomaScan menu version (optional). Possible options include: "5k","7k", or "11k", as well as the version numbers for those menus ("v4.0", "v4.1", or "v5.0", respectively). May only be used when keytype = "PROBEID". This argument will filter the keys to the specified menu and only return data associated with analytes present in that menu. By default, all annotations from all analytes are available.

match

a logical (TRUE/FALSE). Must be used with the "SYMBOL", "ALIAS", or "GENENAME" keytypes only. If true, the character string provided for keys will be used as a search term. The string will be used to match symbols that also start with that string (ex. a key of "CASP1" will return annotations for both the CASP10 & CASP14 genes).

...

Arguments passed on to AnnotationDbi::mapIds

multiVals

What should mapIds do when there are multiple values that could be returned? Options include:

first:

This value means that when there are multiple matches only the 1st thing that comes back will be returned. This is the default behavior

list:

This will just returns a list object to the end user

filter:

This will remove all elements that contain multiple matches and will therefore return a shorter vector than what came in whenever some of the keys match more than one value

asNA:

This will return an NA value whenever there are multiple matches

CharacterList:

This just returns a SimpleCharacterList object

FUN:

You can also supply a function to the multiVals argument for custom behaviors. The function must take a single argument and return a single value. This function will be applied to all the elements and will serve a 'rule' that for which thing to keep when there is more than one element. So for example this example function will always grab the last element in each result: last <- function(x){x[[length(x)]]}

Value

A named character vector containing the retrieved annotations. Missing values will be returned as NA.

Details

mapIds is similar to select in that it can be used to retrieve annotation information from the database. However, users should be aware that if they call mapIds and request columns that have multiple matches for the specified keys (ex. GO or other pathway-related terms), mapIds will return a named character vector with (by default) only one result for each possible match. This result in some results being truncated. Make sure to specify the appropriate multiVals parameter for each query.

Author

Amanda Hiser

Examples

# Retrieve a set of example keys
keys <- head(keys(SomaScan.db))
keys
#> [1] "10000-28" "10001-7"  "10003-15" "10006-25" "10008-43" "10010-10"

# Only 1 result is returned by default; missing values are returned as `NA`
mapIds(SomaScan.db, keys = keys, column = "UNIPROT")
#> 'select()' returned 1:many mapping between keys and columns
#>     10000-28      10001-7     10003-15     10006-25     10008-43 
#> "A0A0H3W5U0" "A0A0S2Z559"     "P51814"     "B2R7H4"     "B2R9P6" 
#>     10010-10 
#> "A0A024R1X5" 

# Specify `multiVals` to return all results as a list
mapIds(SomaScan.db, keys = keys, column = "UNIPROT", multiVals = "list")
#> 'select()' returned 1:many mapping between keys and columns
#> $`10000-28`
#> [1] "A0A0H3W5U0" "P43320"     "Q9UCM8"     "R4UMM2"    
#> 
#> $`10001-7`
#>  [1] "A0A0S2Z559" "A0A8I5KSV6" "A0A024R2G5" "B0LPH8"     "B2R5N3"    
#>  [6] "L7RRS6"     "P04049"     "Q15278"     "Q9UC20"     "A0A8I5KSB0"
#> [11] "B4E0X2"     "A0A0S2Z4L5" "A0A8I5KQV4" "A0A8I5KTA5"
#> 
#> $`10003-15`
#>  [1] "P51814" "A8K1V6" "B4DH01" "Q96LE8" "Q9UMC4" "Q9UMV5" "Q9UMV6"
#>  [8] "Q9UMV7" "Q9UMV8" "Q9UMV9" "Q9UMW0" "Q9UMW1"
#> 
#> $`10006-25`
#> [1] "B2R7H4" "O75606" "O95058" "P19419" "Q6FG56" "Q969X8" "Q9UJM4"
#> 
#> $`10008-43`
#> [1] "B2R9P6" "B3KWT4" "P43080" "Q7Z6T1" "Q9NU14"
#> 
#> $`10010-10`
#> [1] "A0A024R1X5" "B2R6N7"     "O75595"     "Q14457"     "Q53F78"    
#> [6] "Q9UNA8"     "W0FFG4"     "B4DQ36"     "E7EV84"    
#>