Retrieve the differential expression results for a given gene among datasets matching the provided query and filter

get_gene_differential_expression_values(
  gene,
  query = NA_character_,
  taxa = NA_character_,
  uris = NA_character_,
  filter = NA_character_,
  threshold = 1,
  raw = getOption("gemma.raw", FALSE),
  memoised = getOption("gemma.memoised", FALSE),
  file = getOption("gemma.file", NA_character_),
  overwrite = getOption("gemma.overwrite", FALSE)
)

Arguments

gene

An ensembl gene identifier which typically starts with ensg or an ncbi gene identifier or an official gene symbol approved by hgnc

query

The search query. Queries can include plain text or ontology terms They also support conjunctions ("alpha AND beta"), disjunctions ("alpha OR beta") grouping ("(alpha OR beta) AND gamma"), prefixing ("alpha*"), wildcard characters ("BRCA?") and fuzzy matches ("alpha~").

taxa

A vector of taxon common names (e.g. human, mouse, rat). Providing multiple species will return results for all species. These are appended to the filter and equivalent to filtering for taxon.commonName property

uris

A vector of ontology term URIs. Providing multiple terms will return results containing any of the terms and their children. These are appended to the filter and equivalent to filtering for allCharacteristics.valueUri

filter

Filter results by matching expression. Use filter_properties function to get a list of all available parameters. These properties can be combined using "and" "or" clauses and may contain common operators such as "=", "<" or "in". (e.g. "taxon.commonName = human", "taxon.commonName in (human,mouse), "id < 1000")

threshold

number

raw

TRUE to receive results as-is from Gemma, or FALSE to enable parsing. Raw results usually contain additional fields and flags that are omitted in the parsed results.

memoised

Whether or not to save to cache for future calls with the same inputs and use the result saved in cache if a result is already saved. Doing options(gemma.memoised = TRUE) will ensure that the cache is always used. Use forget_gemma_memoised to clear the cache.

file

The name of a file to save the results to, or NULL to not write results to a file. If raw == TRUE, the output will be the raw endpoint from the API, likely a JSON or a gzip file. Otherwise, it will be a RDS file.

overwrite

Whether or not to overwrite if a file exists at the specified filename.

Value

A data.table containing differential expression results. This table is stripped down some relevant information for speed of execution. Details about the contrasts can be accessesed via get_result_sets function

The fields of the output data.table are:

  • result.ID: Result set ID of the differential expression analysis. May represent multiple factors in a single model.

  • contrast.ID: Id of the specific contrast factor. Together with the result.ID they uniquely represent a given contrast.

  • experiment.ID: Id of the source experiment

  • factor.coefficient: Model coefficient calculated for the specific contrast factor

  • factor.logfc: Log 2 fold change calculated for the specific contrast factor

  • factor.pvalue: p values calculated for the specific contrast factor

Examples

# get all differential expression results for ENO2
# from datasets marked with the ontology term for brain
head(get_gene_differential_expression_values(2026, uris = "http://purl.obolibrary.org/obo/UBERON_0000955"))
#>    result.ID contrast.ID experiment.ID pvalue correctedPValue   rank
#>        <int>      <char>         <int>  <num>           <num>  <num>
#> 1:    565737         118            18 0.4213          0.8083 0.5213
#> 2:    560596      135393           134 0.5214          0.9999 0.4142
#> 3:    560598        1060           134 0.0450          0.5422 0.0829
#> 4:    560599        1060           134 0.1648          0.9985 0.1480
#> 5:    560738       15628           233 0.1751          0.4526 0.3869
#> 6:    560738       15629           233 0.1751          0.4526 0.3869
#>    factor.coefficient factor.logfc factor.pvalue baseline.ID
#>                 <num>        <num>         <num>      <char>
#> 1:            -0.1185      -0.1185        0.4213         119
#> 2:            -0.2146      -0.2146        0.5300      135392
#> 3:             0.4842       0.4842        0.2025        1059
#> 4:             0.4842       0.4842        0.1648        1059
#> 5:            -0.1005      -0.1005        0.6375      117789
#> 6:             0.2426       0.2426        0.1294      117789