Package {EWAScaller}

Title: Query and Analyse the 'EWAS Atlas' Database
Version: 0.1.0
Description: Provides a client for the 'EWAS Atlas' web services (https://ngdc.cncb.ac.cn/ewas/; Li et al. (2019) <doi:10.1093/nar/gky1027>), allowing users to query epigenome-wide association study (EWAS) data by CpG (cytosine-phosphate-guanine) probe identifier, gene symbol, or genomic region, and to run trait, Gene Ontology, KEGG (Kyoto Encyclopedia of Genes and Genomes) pathway, and genomic location enrichment analyses on a set of CpG probes. Query functions support concurrent, rate-limited requests to the remote service. Results are returned as tidy data frames with dedicated summary and plotting methods, including word clouds of enriched 'EWAS Atlas' trait terms.
License: MIT + file LICENSE
URL: https://github.com/SAADAT-Abu/EWAScaller
BugReports: https://github.com/SAADAT-Abu/EWAScaller/issues
Depends: R (≥ 4.1.0)
Imports: httr, jsonlite, digest, parallel, ggplot2, ggwordcloud, stats, utils
Suggests: testthat (≥ 3.0.0), knitr, rmarkdown
Encoding: UTF-8
Config/testthat/edition: 3
VignetteBuilder: knitr
LazyData: true
Config/roxygen2/version: 8.0.0
NeedsCompilation: no
Packaged: 2026-07-27 09:13:18 UTC; saadat
Author: Saadat Abu [aut, cre]
Maintainer: Saadat Abu <saadatabu1996@gmail.com>
Repository: CRAN
Date/Publication: 2026-08-05 08:40:09 UTC

EWAScaller: Query and Analyse the EWAS Atlas Database

Description

Tools to query the EWAS Atlas (https://ngdc.cncb.ac.cn/ewas/) by CpG probe, gene symbol, or genomic region, and to run enrichment analyses on probe sets. Query functions dispatch requests concurrently across a small worker pool with configurable pacing to stay within reasonable request rates. Results are returned as tidy data frames with summary and plotting helpers, including trait-term word clouds.

Main functions

Author(s)

Maintainer: Saadat Abu saadatabu1996@gmail.com

Authors:

See Also

Useful links:

Plot an EWAS Atlas enrichment result

Description

Draws a dot plot of enrichment significance, mirroring the EWAS Atlas toolkit's trait-enrichment chart: one row per term, position given by -log10(p) and point size by the differentially-methylated CpG count.

Usage

## S3 method for class 'ewas_enrichment'
autoplot(object, type = "trait", top_n = 20L, ...)

Arguments

object

An ewas_enrichment object.

type

Which analysis result to plot (default "trait").

top_n

Number of top terms to display.

...

Unused.

Value

A ggplot object.

Plot summary statistics for an EWAS Atlas query result

Description

Plot summary statistics for an EWAS Atlas query result

Usage

## S3 method for class 'ewas_result'
autoplot(
  object,
  type = c("traits", "chromosome", "direction"),
  top_n = 15L,
  ...
)

Arguments

object

An ewas_result object.

type

One of "traits" (top trait frequency), "chromosome" (probes per chromosome), or "direction" (hyper-/hypomethylation balance).

top_n

Number of categories to show for type = "traits" or type = "chromosome".

...

Unused.

Value

A ggplot object.

Run EWAS Atlas enrichment analysis on a set of CpG probes

Description

Submits a probe set to the EWAS Atlas toolkit and retrieves one or more enrichment analyses run against it: EWAS trait-term enrichment, genomic location enrichment, Gene Ontology enrichment, KEGG pathway enrichment, tissue-specificity enrichment, and gene-expression correlation.

Usage

ewas_enrichment(
  probes,
  background = c("450K", "850K"),
  types = "trait",
  poll_interval = 5,
  timeout = 300,
  progress = interactive()
)

Arguments

probes

Character vector of CpG probe identifiers (20-5000).

background

One of "450K", "850K", or a character vector of probe identifiers to use as a custom background set.

types

Character vector of analyses to run: any of "trait" (EWAS Atlas trait-term enrichment), "genomic_location" (enrichment across gene/CpG-island-relative locations), "gene_ontology" (GO term enrichment), or "kegg" (KEGG pathway enrichment). Defaults to "trait".

poll_interval

Seconds between job-status polls.

timeout

Maximum seconds to wait for each analysis to finish.

progress

Logical; print progress messages while polling.

Details

The EWAS Atlas toolkit requires between 20 and 5000 probes per submission and computes results asynchronously; this function submits the job and polls for completion.

Value

An ewas_enrichment object.

Examples


probes <- c(
  "cg05575921", "cg00240195", "cg16419584", "cg11903855", "cg21566642",
  "cg23771366", "cg19859270", "cg00382138", "cg25648203", "cg01940273",
  "cg23576855", "cg00401753", "cg00300637", "cg12803068", "cg09935388",
  "cg01899089", "cg04180046", "cg00050873", "cg02228185", "cg18147296"
)
enr <- ewas_enrichment(probes, background = "850K", types = "trait")
top_traits(enr)

EWAS Atlas enrichment result

Description

An ewas_enrichment bundles the analyses run by ewas_enrichment().

Usage

## S3 method for class 'ewas_enrichment'
summary(object, top_n = 10L, ...)

## S3 method for class 'ewas_enrichment'
as.data.frame(x, row.names = NULL, optional = FALSE, type = "trait", ...)

Arguments

object

An ewas_enrichment object.

top_n

Number of top rows to report per analysis type.

...

Unused.

x

An ewas_enrichment object.

row.names, optional

Unused; present for S3 consistency.

type

Which analysis result to extract (default "trait").

Value

An object of class ewas_enrichment: a named list with the results, job, probes, background, and failed elements described above. summary.ewas_enrichment() invisibly returns the object it was called on (after printing a summary), and as.data.frame.ewas_enrichment() returns the requested analysis's result data frame on its own.

Fields

results

Named list of data frames, one per requested analysis type (e.g. results$trait).

job

The EWAS Atlas toolkit job identifier.

probes

The probe identifiers submitted.

background

The background set used ("450K", "850K", or "other").

failed

Named list of analysis types that could not be retrieved, with an explanatory message.

EWAS Atlas query result

Description

An ewas_result bundles the tables returned by query_cpg(), query_gene(), or query_region().

Usage

## S3 method for class 'ewas_result'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

row.names, optional

Passed on for S3 consistency; unused.

Value

An object of class ewas_result: a named list with the associations, probes, failed, query_type, and n_queries elements described above. as.data.frame.ewas_result() returns the associations data frame on its own.

Fields

associations

One row per probe-trait association, with columns probeId, studyId, trait, correlation, rank, pmid, and query (the input term that returned this row).

probes

One row per unique probe, with columns probeId, chrHg19, posHg19, cpgIsland, gene, and query.

failed

Input terms that could not be resolved, with an error message column.

query_type

One of "cpg", "gene", "region".

n_queries

Number of input terms submitted.

Example CpG probe list

Description

A small example dataset of Illumina CpG probe identifiers, useful for trying out query_cpg() and ewas_enrichment() without needing to supply your own probe list.

Usage

example_cpgs

Format

A data frame with 30 rows and 1 variable:

query_cpg

Character. CpG probe identifier.

Source

Illustrative subset of probes with known EWAS Atlas trait associations.

Examples

data(example_cpgs)
head(example_cpgs)

Word cloud of EWAS Atlas trait terms

Description

Draws a word cloud sized by association frequency (for ewas_result objects) or by enrichment significance (for ewas_enrichment objects).

Usage

plot_wordcloud(x, max_words = 75L, colors = NULL, ...)

## S3 method for class 'ewas_result'
plot_wordcloud(x, max_words = 75L, colors = NULL, ...)

## S3 method for class 'ewas_enrichment'
plot_wordcloud(
  x,
  max_words = 75L,
  colors = NULL,
  type = "trait",
  weight = c("neglog10p", "count"),
  ...
)

Arguments

x

An ewas_result or ewas_enrichment object.

max_words

Maximum number of trait terms to display.

colors

A vector of colors to cycle through.

...

Passed to methods.

type

Which enrichment analysis to plot the word cloud for (default "trait").

weight

Weighting statistic: "neglog10p" (default, significance) or "count" (differentially methylated CpG/gene count for the term).

Value

A ggplot object.

Query the EWAS Atlas by CpG probe identifier

Description

Retrieves trait associations and annotation for one or more Illumina CpG probe identifiers (e.g. "cg05575921") from the EWAS Atlas.

Usage

query_cpg(cpgs, workers = 2L, delay = 1, progress = interactive())

Arguments

cpgs

Character vector of CpG probe identifiers. Duplicates and missing values are dropped before querying.

workers

Integer; maximum number of concurrent requests. Defaults to 2, a conservative value intended to avoid overloading the remote service.

delay

Numeric; seconds to pause between batches of workers requests.

progress

Logical; print a simple progress message as batches complete.

Value

An ewas_result object.

Examples


res <- query_cpg(c("cg05575921", "cg11903855"), workers = 1, delay = 1)
summary(res)

Query the EWAS Atlas by gene symbol

Description

Retrieves probes and trait associations linked to one or more gene symbols (e.g. "AHRR") from the EWAS Atlas.

Usage

query_gene(genes, workers = 2L, delay = 1, progress = interactive())

Arguments

genes

Character vector of gene symbols.

workers

Integer; maximum number of concurrent requests. Defaults to 2, a conservative value intended to avoid overloading the remote service.

delay

Numeric; seconds to pause between batches of workers requests.

progress

Logical; print a simple progress message as batches complete.

Value

An ewas_result object.

Examples


res <- query_gene("AHRR", workers = 1, delay = 1)
summary(res)

Query the EWAS Atlas by genomic region

Description

Retrieves probes and trait associations located within one or more genomic intervals (hg19 coordinates) from the EWAS Atlas.

Usage

query_region(
  chr,
  start = NULL,
  end = NULL,
  workers = 2L,
  delay = 1,
  progress = interactive()
)

Arguments

chr

Chromosome (e.g. "1", "X"), or a data frame with columns chr, start, end giving one or more regions, in which case start and end are ignored.

start

Start position (hg19, 1-based).

end

End position (hg19, 1-based).

workers

Integer; maximum number of concurrent requests. Defaults to 2, a conservative value intended to avoid overloading the remote service.

delay

Numeric; seconds to pause between batches of workers requests.

progress

Logical; print a simple progress message as batches complete.

Value

An ewas_result object.

Examples


res <- query_region(chr = "5", start = 373000, end = 374000, workers = 1)
summary(res)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

ggplot2

autoplot()

Summarise an EWAS Atlas query result

Description

Summarise an EWAS Atlas query result

Usage

## S3 method for class 'ewas_result'
summary(object, top_n = 10L, ...)

Arguments

object

An ewas_result object.

top_n

Number of top traits to report.

...

Unused.

Value

Invisibly, a list with summary statistics; also printed.

Rank traits by association frequency

Description

Rank traits by association frequency

Usage

## S3 method for class 'ewas_enrichment'
top_traits(x, n = 10L, ...)

top_traits(x, n = 10L, ...)

## S3 method for class 'ewas_result'
top_traits(x, n = 10L, ...)

Arguments

x

An ewas_result or ewas_enrichment object.

n

Number of top traits to return.

...

Passed to methods.

Value

A data frame with columns trait and n (or p/OR for enrichment results), ordered from most to least significant/frequent.