This vignette summarises the principal PscanR functions for motif enrichment analysis in promoter sequences. The package reference manual provides complete argument descriptions and examples.
PscanR is being prepared for Bioconductor submission. After acceptance, install it with the following command (not executed while building this vignette):
For pre-submission installation from source, see the package README.
The bundled sequences are 90 human hg38 promoters from the historical NRF1 example used by the original Pscan web interface. The promoters and background both use the -200/+50 window.
We select the JASPAR 2020 motifs for NRF1 (MA0506.1) and
CTCF (MA0139.1) to illustrate enriched and background-like
motif scores in these sequences. The adjusted p-values cover only these
two motifs; use the complete motif collection for an analysis-wide
multiple-testing adjustment.
library(PscanR)
motifs <- readRDS(system.file("extdata", "J2020.rds", package = "PscanR"))
background <- ps_retrieve_bg_from_file(system.file(
"extdata", "J2020_hg38_200u_50d_UCSC.psbg.txt", package = "PscanR"
), motifs)
background <- background[c("MA0506.1", "MA0139.1")] # NRF1 and CTCF
sequences <- readRDS(system.file("extdata", "prom_seq.rds", package = "PscanR"))
ps_results_table(pscan(sequences, background))## NAME BG_AVG BG_STDEV FG_AVG ZSCORE P.VALUE
## MA0506.1 NRF1 0.8252333 0.07623113 0.9626850 17.1056257 6.737349e-66
## MA0139.1 CTCF 0.7608479 0.04620913 0.7640513 0.6576541 2.553802e-01
## FDR
## MA0506.1 1.347470e-65
## MA0139.1 2.553802e-01NRF1 is strongly enriched (\(p \approx 6.7 \times 10^{-66}\)), whereas CTCF has foreground scores close to background and is not significantly enriched (p approximately 0.26).
| Function | Description |
|---|---|
pscan()
|
Computes the best match to each motif in each promoter and tests motif enrichment against the supplied background score distributions. |
pscan_full_bg()
|
Retrieves stored motif hits for foreground identifiers from a full background and calculates enrichment without rescanning the DNA sequences. |
pscan_filtered()
|
Selects promoters whose best match to a specified motif meets a threshold defined from its background distribution, then scans the selected promoters against the supplied motif collection. |
ps_select_promoters()
|
Selects one promoter per mapped gene from supplied sequences and annotation, using transcript preferences or rules appropriate to the identifier scheme. Reports the scheme and the reason for each selection. |
ps_selection_summary()
|
Summarises a mapping produced by ps_select_promoters(),
including identifier schemes, selection rules, genes with multiple
candidates, and selections requiring a tie-breaking rule after ranking.
|
ps_load_select_transcripts()
|
Downloads and caches human hg38 MANE Select and RefSeq Select metadata
from UCSC for use with ps_select_promoters(). Other
organisms require an appropriate user-supplied selection table or
representative selection.
|
A background describes the distribution of best motif scores across a defined reference set of promoters. A standard background stores the number of promoters, mean score, and score standard deviation for each motif; a full background also retains the individual hits. Foreground and background must use matching promoter definitions and motif matrices.
| Function | Description |
|---|---|
ps_build_bg()
|
Scans the supplied reference sequences and computes background statistics for each motif after sequence filtering and deduplication. |
ps_retrieve_bg()
|
Retrieves a precomputed background and associates its statistics with
the matching motif matrices in a PSMatrixList.
|
ps_available_bg()
|
Displays the names of all available precomputed backgrounds, with options to filter by keywords. |
ps_retrieve_bg_from_file()
|
Reads a background text file and associates the stored size, mean score, and standard deviation with the supplied motif matrices by identifier. |
ps_build_bg_from_table()
|
Associates background parameters held in a data.frame with
a list of position frequency matrices and returns the result as a
PSMatrixList.
|
ps_get_bg_table()
|
Extracts the background statistics (size, mean and standard deviation)
from a PSMatrixList as a data.frame, which is
the inverse of ps_build_bg_from_table().
|
ps_write_bg_to_file()
|
Writes the background statistics of a PSMatrixList to a
text file, in the format ps_retrieve_bg_from_file() reads
back.
|
ps_build_bg(fullBG = TRUE)
|
Builds a full background containing summary statistics and the best hit’s score, position, strand, and matched oligonucleotide for each retained promoter and motif. Full backgrounds require substantially more storage; the package includes small demonstration objects. |
pscan_full_bg()
|
Uses foreground transcript identifiers to retrieve hits stored in a full background. Reusing these hits reduces computation for repeated analyses against the same reference set. |
ps_transcript_legend()
|
Retrieves the mapping from original sequence names to representatives
retained after deduplication. This allows pscan_full_bg()
to resolve identifiers associated with identical promoter sequences.
|
| Function | Description |
|---|---|
ps_results_table()
|
Returns motif-level results ordered by increasing p-value, with decreasing z-score used to resolve ties. Motifs can be selected using a specified false discovery rate (FDR) threshold. |
ps_z_table()
|
Returns a matrix of standardised best-hit scores, with promoters as rows
and motifs as columns, from a PSMatrixList.
|
ps_zscore_heatmap()
|
Displays a heatmap of per-promoter motif z-scores after motif selection by FDR. By default, rows are scaled and both axes are clustered using correlation distances; the cells are not pairwise correlation coefficients. |
ps_hitpos_map()
|
Displays the position of each promoter’s best motif match as a heatmap to compare positional patterns across motifs. |
ps_density_plot()
|
Estimates the positional density of a motif’s best hits, optionally restricted by a score threshold. A supplied promoter window enables boundary correction, and optional bins show a histogram on the same density scale. |
ps_hit_score_plot()
|
Plots best-hit score against position for each promoter, allowing joint assessment of match strength and positional concentration. |
ps_motif_barplot()
|
Displays the highest-ranked motifs as horizontal bars, optionally coloured by a grouping such as transcription factor structural class. |
ps_motif_class()
|
Extracts the transcription factor structural class associated with each
motif, for example “Basic leucine zipper factors (bZIP)”,
for annotation or grouping in ps_motif_barplot().
|
The installed inst/scripts/fixture-provenance.md
describes the sources, selection rules, serialization, and reproduction
recipes for the bundled example data. inst/DATA_SOURCES.md
records attribution and reuse terms. The large published analyses use
saved results; small workflow examples are executed during the build.
Reproducing a full analysis requires the matching annotation and
promoter window, not just the same gene identifiers.
## R version 4.6.1 (2026-06-24)
## Platform: x86_64-pc-linux-gnu
## Running under: Ubuntu 26.04.1 LTS
##
## Matrix products: default
## BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
## LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.32.so; LAPACK version 3.12.0
##
## locale:
## [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
## [3] LC_TIME=en_US.UTF-8 LC_COLLATE=en_US.UTF-8
## [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
## [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
## [9] LC_ADDRESS=C LC_TELEPHONE=C
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
##
## time zone: Etc/UTC
## tzcode source: system (glibc)
##
## attached base packages:
## [1] stats4 stats graphics grDevices utils datasets methods
## [8] base
##
## other attached packages:
## [1] org.Hs.eg.db_3.23.1 AnnotationDbi_1.75.2 Biobase_2.73.2
## [4] Biostrings_2.81.9 Seqinfo_1.3.2 XVector_0.53.0
## [7] IRanges_2.47.5 S4Vectors_0.51.10 BiocGenerics_0.59.12
## [10] generics_0.1.4 PscanR_0.99.0 BiocStyle_2.41.0
##
## loaded via a namespace (and not attached):
## [1] tidyselect_1.2.1 dplyr_1.2.1
## [3] farver_2.1.2 blob_1.3.0
## [5] filelock_1.0.3 S7_0.2.2
## [7] bitops_1.1-0 fastmap_1.2.0
## [9] RCurl_1.98-1.20 BiocFileCache_3.3.0
## [11] GenomicAlignments_1.49.2 XML_3.99-0.25
## [13] digest_0.6.39 DirichletMultinomial_1.55.1
## [15] lifecycle_1.0.5 pwalign_1.9.1
## [17] KEGGREST_1.53.6 RSQLite_3.53.3
## [19] magrittr_2.0.5 compiler_4.6.1
## [21] rlang_1.3.0 sass_0.4.10
## [23] tools_4.6.1 yaml_2.3.12
## [25] rtracklayer_1.73.0 knitr_1.52
## [27] labeling_0.4.3 bit_4.6.0
## [29] curl_8.0.0 RColorBrewer_1.1-3
## [31] BiocParallel_1.47.0 withr_3.0.3
## [33] purrr_1.2.2 sys_3.4.3
## [35] grid_4.6.1 caTools_1.18.4
## [37] ggplot2_4.0.3 scales_1.4.0
## [39] gtools_3.9.5 cli_3.6.6
## [41] rmarkdown_2.32 crayon_1.5.3
## [43] otel_0.2.0 TFMPvalue_1.0.0
## [45] httr_1.4.9 rjson_0.2.23
## [47] BiocBaseUtils_1.15.1 DBI_1.3.0
## [49] cachem_1.1.0 parallel_4.6.1
## [51] BiocManager_1.30.27 restfulr_0.0.17
## [53] matrixStats_1.5.0 vctrs_0.7.3
## [55] Matrix_1.7-6 jsonlite_2.0.0
## [57] bit64_4.8.6 seqLogo_1.79.0
## [59] maketools_1.3.2 jquerylib_0.1.4
## [61] glue_1.8.1 TFBSTools_1.51.0
## [63] codetools_0.2-20 gtable_0.3.6
## [65] BiocIO_1.23.3 GenomicRanges_1.65.4
## [67] tibble_3.3.1 pillar_1.11.1
## [69] htmltools_0.5.9 JASPAR2020_0.99.10
## [71] BSgenome_1.81.1 httr2_1.3.0
## [73] dbplyr_2.6.0 R6_2.6.1
## [75] evaluate_1.0.5 lattice_0.23-1
## [77] png_0.1-9 Rsamtools_2.29.0
## [79] cigarillo_1.3.1 pheatmap_1.0.13
## [81] memoise_2.0.1 bslib_0.12.0
## [83] Rcpp_1.1.2 xfun_0.61
## [85] buildtools_1.0.0 pkgconfig_2.0.3