PscanR is being prepared for Bioconductor submission. After acceptance, install it with the following command (not executed while building this vignette):
BiocManager::install("PscanR")For pre-submission installation from source, see the package README.
PscanR is an R implementation of the algorithm developed by Zambelli et al. (2009) for analysing sequence motif enrichment. It identifies transcription factors (TFs) that are potential regulators of a set of co-regulated or co-expressed genes. By scanning input sequences (e.g., promoters) against a database of known TF binding motifs, PscanR tests for motif enrichment and reports candidate binding sites.
TFBSTools supplies the motif classes that PscanR extends; Biostrings supplies sequence representations and scoring primitives. motifmatchr uses MOODS to find matches across many motifs and sequences. PWMEnrich provides another Biostrings-based toolkit for known-motif scanning and enrichment. These tools address related tasks, but their statistical approach is different.
PscanR implements the specific best-hit model of
Zambelli et al. (2009): each sequence
contributes its best normalized score per motif; the foreground mean is tested
against promoter-background moments for a matching reference and window.
Its PSMatrix and PSMatrixList classes extend TFBSTools objects to retain
those moments and the selected positions, strands, and oligos. Gene-to-promoter
selection and cached immutable backgrounds connect this model to workflows
using annotation packages and DNAStringSet inputs. The full-background path
also supports identifier-based queries without rescanning sequences.
Input: DNA sequences supplied as a DNAStringSet, and transcription factor
binding matrices with matching background statistics supplied as a
PSMatrixList.
Analysis: Calculation of the best motif match in each promoter, followed by comparison of foreground and background scores.
Output: Motif-level z-scores, p-values, and adjusted p-values, together with the best match in each promoter for each motif.
Statistical assessment requires a background model, represented by background
statistics stored in a PSMatrixList object.
PscanR treats the input sequences as a sample from a defined reference population, usually the annotated promoters of the species under investigation. This reference population supplies the background model for statistical analyses.
Because the background is the distribution of scores over the whole promoter
universe, the foreground and the background must describe the same kind of
sequence. A promoter window of 200 bp upstream and 50 bp downstream of the
transcription start site (TSS)
does not yield scores comparable with one of 950 bp upstream and 50 bp
downstream: a longer window offers more candidate matches and can therefore
increase the best score without biological enrichment. Extract foreground
promoters using the background’s window and compatible reference sequences and
annotations. Each precomputed background records its window in its name, as in
950u_50d.
The next section demonstrates the use of a precomputed background. The vignette Building a background for PscanR describes the construction and use of custom backgrounds.
PscanR provides access to precomputed backgrounds for five model organisms: Homo sapiens, Mus musculus, Drosophila melanogaster, Arabidopsis thaliana, and Saccharomyces cerevisiae.
ps_available_bg() lists the available backgrounds, and
ps_retrieve_bg() retrieves the selected background as
a PSMatrixList for use with pscan():
ps_available_bg()
#> [1] "J2020_dm6_200u_50d_UCSC.psbg2.txt"
#> [2] "J2020_dm6_450u_50d_UCSC.psbg2.txt"
#> [3] "J2020_dm6_500u_0d_UCSC.psbg2.txt"
#> [4] "J2020_dm6_950u_50d_UCSC.psbg2.txt"
#> [5] "J2020_dm6_1000u_0d_UCSC.psbg2.txt"
#> [6] "J2020_hg38_200u_50d_UCSC.psbg2.txt"
#> [7] "J2020_hg38_450u_50d_UCSC.psbg2.txt"
#> [8] "J2020_hg38_500u_0d_UCSC.psbg2.txt"
#> [9] "J2020_hg38_950u_50d_UCSC.psbg2.txt"
#> [10] "J2020_hg38_1000u_0d_UCSC.psbg2.txt"
#> [11] "J2020_hs1_200u_50d_UCSC.psbg2.txt"
#> [12] "J2020_hs1_450u_50d_UCSC.psbg2.txt"
#> [13] "J2020_hs1_500u_0d_UCSC.psbg2.txt"
#> [14] "J2020_hs1_950u_50d_UCSC.psbg2.txt"
#> [15] "J2020_hs1_1000u_0d_UCSC.psbg2.txt"
#> [16] "J2020_mm10_200u_50d_UCSC.psbg2.txt"
#> [17] "J2020_mm10_450u_50d_UCSC.psbg2.txt"
#> [18] "J2020_mm10_500u_0d_UCSC.psbg2.txt"
#> [19] "J2020_mm10_950u_50d_UCSC.psbg2.txt"
#> [20] "J2020_mm10_1000u_0d_UCSC.psbg2.txt"
#> [21] "J2020_mm39_200u_50d_UCSC.psbg2.txt"
#> [22] "J2020_mm39_450u_50d_UCSC.psbg2.txt"
#> [23] "J2020_mm39_500u_0d_UCSC.psbg2.txt"
#> [24] "J2020_mm39_950u_50d_UCSC.psbg2.txt"
#> [25] "J2020_mm39_1000u_0d_UCSC.psbg2.txt"
#> [26] "J2020_sacCer3_200u_50d_UCSC.psbg2.txt"
#> [27] "J2020_sacCer3_450u_50d_UCSC.psbg2.txt"
#> [28] "J2020_sacCer3_500u_0d_UCSC.psbg2.txt"
#> [29] "J2020_sacCer3_950u_50d_UCSC.psbg2.txt"
#> [30] "J2020_sacCer3_1000u_0d_UCSC.psbg2.txt"
#> [31] "J2020_TAIR9_200u_50d_TAIR.psbg2.txt"
#> [32] "J2020_TAIR9_450u_50d_TAIR.psbg2.txt"
#> [33] "J2020_TAIR9_500u_0d_TAIR.psbg2.txt"
#> [34] "J2020_TAIR9_950u_50d_TAIR.psbg2.txt"
#> [35] "J2020_TAIR9_1000u_0d_TAIR.psbg2.txt"
#> [36] "J2022_dm6_200u_50d_UCSC.psbg2.txt"
#> [37] "J2022_dm6_450u_50d_UCSC.psbg2.txt"
#> [38] "J2022_dm6_500u_0d_UCSC.psbg2.txt"
#> [39] "J2022_dm6_950u_50d_UCSC.psbg2.txt"
#> [40] "J2022_dm6_1000u_0d_UCSC.psbg2.txt"
#> [41] "J2022_hg38_200u_50d_UCSC.psbg2.txt"
#> [42] "J2022_hg38_450u_50d_UCSC.psbg2.txt"
#> [43] "J2022_hg38_500u_0d_UCSC.psbg2.txt"
#> [44] "J2022_hg38_950u_50d_UCSC.psbg2.txt"
#> [45] "J2022_hg38_1000u_0d_UCSC.psbg2.txt"
#> [46] "J2022_hs1_200u_50d_UCSC.psbg2.txt"
#> [47] "J2022_hs1_450u_50d_UCSC.psbg2.txt"
#> [48] "J2022_hs1_500u_0d_UCSC.psbg2.txt"
#> [49] "J2022_hs1_950u_50d_UCSC.psbg2.txt"
#> [50] "J2022_hs1_1000u_0d_UCSC.psbg2.txt"
#> [51] "J2022_mm10_200u_50d_UCSC.psbg2.txt"
#> [52] "J2022_mm10_450u_50d_UCSC.psbg2.txt"
#> [53] "J2022_mm10_500u_0d_UCSC.psbg2.txt"
#> [54] "J2022_mm10_950u_50d_UCSC.psbg2.txt"
#> [55] "J2022_mm10_1000u_0d_UCSC.psbg2.txt"
#> [56] "J2022_mm39_200u_50d_UCSC.psbg2.txt"
#> [57] "J2022_mm39_450u_50d_UCSC.psbg2.txt"
#> [58] "J2022_mm39_500u_0d_UCSC.psbg2.txt"
#> [59] "J2022_mm39_950u_50d_UCSC.psbg2.txt"
#> [60] "J2022_mm39_1000u_0d_UCSC.psbg2.txt"
#> [61] "J2022_sacCer3_200u_50d_UCSC.psbg2.txt"
#> [62] "J2022_sacCer3_450u_50d_UCSC.psbg2.txt"
#> [63] "J2022_sacCer3_500u_0d_UCSC.psbg2.txt"
#> [64] "J2022_sacCer3_950u_50d_UCSC.psbg2.txt"
#> [65] "J2022_sacCer3_1000u_0d_UCSC.psbg2.txt"
#> [66] "J2022_TAIR9_200u_50d_TAIR.psbg2.txt"
#> [67] "J2022_TAIR9_450u_50d_TAIR.psbg2.txt"
#> [68] "J2022_TAIR9_500u_0d_TAIR.psbg2.txt"
#> [69] "J2022_TAIR9_950u_50d_TAIR.psbg2.txt"
#> [70] "J2022_TAIR9_1000u_0d_TAIR.psbg2.txt"
#> [71] "J2024_dm6_200u_50d_UCSC.psbg2.txt"
#> [72] "J2024_dm6_450u_50d_UCSC.psbg2.txt"
#> [73] "J2024_dm6_500u_0d_UCSC.psbg2.txt"
#> [74] "J2024_dm6_950u_50d_UCSC.psbg2.txt"
#> [75] "J2024_dm6_1000u_0d_UCSC.psbg2.txt"
#> [76] "J2024_hg38_200u_50d_UCSC.psbg2.txt"
#> [77] "J2024_hg38_450u_50d_UCSC.psbg2.txt"
#> [78] "J2024_hg38_500u_0d_UCSC.psbg2.txt"
#> [79] "J2024_hg38_950u_50d_UCSC.psbg2.txt"
#> [80] "J2024_hg38_1000u_0d_UCSC.psbg2.txt"
#> [81] "J2024_hs1_200u_50d_UCSC.psbg2.txt"
#> [82] "J2024_hs1_450u_50d_UCSC.psbg2.txt"
#> [83] "J2024_hs1_500u_0d_UCSC.psbg2.txt"
#> [84] "J2024_hs1_950u_50d_UCSC.psbg2.txt"
#> [85] "J2024_hs1_1000u_0d_UCSC.psbg2.txt"
#> [86] "J2024_mm10_200u_50d_UCSC.psbg2.txt"
#> [87] "J2024_mm10_450u_50d_UCSC.psbg2.txt"
#> [88] "J2024_mm10_500u_0d_UCSC.psbg2.txt"
#> [89] "J2024_mm10_950u_50d_UCSC.psbg2.txt"
#> [90] "J2024_mm10_1000u_0d_UCSC.psbg2.txt"
#> [91] "J2024_mm39_200u_50d_UCSC.psbg2.txt"
#> [92] "J2024_mm39_450u_50d_UCSC.psbg2.txt"
#> [93] "J2024_mm39_500u_0d_UCSC.psbg2.txt"
#> [94] "J2024_mm39_950u_50d_UCSC.psbg2.txt"
#> [95] "J2024_mm39_1000u_0d_UCSC.psbg2.txt"
#> [96] "J2024_sacCer3_200u_50d_UCSC.psbg2.txt"
#> [97] "J2024_sacCer3_450u_50d_UCSC.psbg2.txt"
#> [98] "J2024_sacCer3_500u_0d_UCSC.psbg2.txt"
#> [99] "J2024_sacCer3_950u_50d_UCSC.psbg2.txt"
#> [100] "J2024_sacCer3_1000u_0d_UCSC.psbg2.txt"
#> [101] "J2024_TAIR9_200u_50d_TAIR.psbg2.txt"
#> [102] "J2024_TAIR9_450u_50d_TAIR.psbg2.txt"
#> [103] "J2024_TAIR9_500u_0d_TAIR.psbg2.txt"
#> [104] "J2024_TAIR9_950u_50d_TAIR.psbg2.txt"
#> [105] "J2024_TAIR9_1000u_0d_TAIR.psbg2.txt"J2020_PSBG <- ps_retrieve_bg(
"Jaspar2020", "hs", c(-200, 50), "hg38"
)
J2020_PSBG
#> PSMatrixList of length 746
#> names(746): MA0004.1 MA0006.1 MA0019.1 MA0029.1 ... MA0748.2 MA0528.2 MA0609.2
J2020_PSBG[[4]] # one matrix, with its background statistics
#> An object of class PSMatrix
#> ID: MA0029.1
#> Name: Mecom
#> Matrix Class: C2H2 zinc finger factors
#> strand: +
#> Tags:
#> $alias
#> [1] "MDS1-EVI1,PRDM3"
#>
#> $description
#> [1] "MDS1 and EVI1 complex locus MDS1,EVI1"
#>
#> $family
#> [1] "Factors with multiple dispersed zinc fingers"
#>
#> $medline
#> [1] "8321231"
#>
#> $symbol
#> [1] "MECOM"
#>
#> $tax_group
#> [1] "vertebrates"
#>
#> $tfbs_shape_id
#> [1] "36"
#>
#> $type
#> [1] "SELEX"
#>
#> $collection
#> [1] "CORE"
#>
#> $species
#> 10090
#> "Mus musculus"
#>
#> $acc
#> [1] "A4QPC8"
#>
#> Background:
#> A C G T
#> 0.25 0.25 0.25 0.25
#> Matrix:
#> [,1] [,2] [,3] [,4] [,5] [,6]
#> A -0.6768981 -0.3259156 -4.6443909 -0.02927038 -3.0960407 -0.02927038
#> C -2.5152777 -3.0960407 -3.0960407 -4.64439090 -1.0058306 -4.64439090
#> G -1.4992812 -2.5152777 -0.1054397 -4.64439090 -4.6443909 -4.64439090
#> T -1.6730272 -1.8834438 -3.0960407 -4.64439090 -0.5457347 -4.64439090
#> [,7] [,8] [,9] [,10] [,11] [,12]
#> A -0.06662998 -4.64439090 -0.02927038 -4.6443909 -0.1458166 -0.1878926
#> C -4.64439090 -4.64439090 -4.64439090 -2.1502676 -3.0960407 -4.6443909
#> G -3.09604068 -0.02927038 -4.64439090 -4.6443909 -4.6443909 -1.8834438
#> T -4.64439090 -4.64439090 -4.64439090 -0.1458166 -2.5152777 -4.6443909
#> [,13] [,14]
#> A -1.499281 -0.6091675
#> C -1.351301 -1.4992812
#> G -1.351301 -2.1502676
#> T -1.351301 -2.1502676
#>
#> Pscan Background Average: 0.709093
#> Pscan Foreground (your sample) Average: NA
#> Pscan Background Stdev: 0.06468091
#> Pscan Background Size: 39719
#> Pscan Foreground (your sample) Size: NA
#> Pscan Zscore: NA
#> Pscan pvalue (z-test): NAThe four arguments above identify the JASPAR release, species, promoter window relative to the TSS, and genome assembly. The assembly must be specified for mouse and human, for which multiple assemblies are available. The supported species and assemblies are:
Homo sapiens, assemblies hg38 and hs1
Mus musculus, assemblies mm10 and mm39
Arabidopsis thaliana, TAIR9
Drosophila melanogaster, dm6
Saccharomyces cerevisiae, sacCer3
The available promoter windows span 200 bp upstream and 50 bp downstream, 450 upstream and 50 downstream, 500 upstream and 0 downstream, 950 upstream and 50 downstream, and 1000 upstream and 0 downstream, for the JASPAR 2020, 2022, and 2024 releases. Only JASPAR CORE motifs are used.
Each precomputed background is a separate ExperimentHub resource of the
PscanRBackgrounds data package, which documents the resources and can be
installed with BiocManager::install("PscanRBackgrounds"). The files are
hosted on Zenodo in one record per JASPAR release. By default
ps_retrieve_bg() retrieves a background through ExperimentHub and, if the
Hub cannot be reached, falls back to Zenodo
with a warning; source = "zenodo" downloads the file from Zenodo directly.
If a single file cannot be retrieved, the immutable record
https://doi.org/10.5281/zenodo.21821764, which archives all backgrounds in a
single ZIP, is used instead. Downloads are cached, and every file is verified
against the SHA-256 checksum recorded in the catalog.
For offline use, the package also includes JASPAR 2020 CORE matrices and a
historical human background table for 200 bp upstream and 50 bp downstream of
the TSS, computed on an earlier snapshot of the hg38 annotation.
ps_retrieve_bg_from_file() combines them into a PSMatrixList; the man page
examples use it:
J2020 <- readRDS(system.file("extdata", "J2020.rds", package = "PscanR"))
bg_path <- system.file(
"extdata", "J2020_hg38_200u_50d_UCSC.psbg.txt",
package = "PscanR"
)
j2020_offline <- ps_retrieve_bg_from_file(bg_path, J2020)
length(j2020_offline)
#> [1] 746If no available background matches the required species, window, or motif collection, construct a custom background as described in Building a background for PscanR.
pscan()The two principal inputs to pscan() are a DNAStringSet of promoter sequences
and a background PSMatrixList. The following sections demonstrate promoter
selection from transcript identifiers and from gene identifiers.
For humans, mice, and Drosophila, the available background models are based on RefSeq identifiers; for Arabidopsis, on TAIR; and for yeast, on SGD. Other types of gene identifiers can also be mapped to the annotation used by an existing background. Custom backgrounds can use other annotations, as described in Building a background for PscanR.
PscanR operates on promoter sequences. When transcript identifiers map uniquely within the chosen assembly and annotation, their corresponding promoters can be selected directly without choosing among transcripts of the same gene.
The package includes the historical human NRF1 example list of RefSeq transcripts from the original Pscan web interface. See Zambelli, Pesole and Pavesi (2009) for the software and interface.
file_path <- system.file("extdata", "nrf1100.txt", package = "PscanR")
target <- read.csv(file_path, header = FALSE)
head(target)
#> V1
#> 1 NM_000056.5
#> 2 NM_000375.3
#> 3 NM_000688.6
#> 4 NM_001002880.4
#> 5 NM_001003789.3
#> 6 NM_001003962.3The bundled human promoter sequences span 200 bp upstream and 50 bp downstream of the TSS, matching the background loaded above:
library(Biostrings)
prom_seq <- readRDS(
system.file("extdata", "prom_seq.rds", package = "PscanR")
)
length(prom_seq)
#> [1] 90
unique(width(prom_seq)) # 200 upstream + 50 downstream
#> [1] 250
head(names(prom_seq), 3)
#> [1] "NM_006559.3" "NM_003729.4" "NM_003557.3"The transcript list and promoter names use identical RefSeq identifiers, including version suffixes. The foreground can therefore be selected by exact name matching:
foreground <- prom_seq[names(prom_seq) %in% target[[1]]]
length(foreground)
#> [1] 90Every transcript in the list has a promoter in the bundled set, so all 90 are retained. The same operation can select a foreground from a genome-wide promoter set. The selected sequences are then scanned against the background:
res <- pscan(foreground, J2020_PSBG, BPPARAM = BiocParallel::SerialParam())
head(ps_results_table(res))
#> NAME BG_AVG BG_STDEV FG_AVG ZSCORE P.VALUE
#> MA0506.1 NRF1 0.8251589 0.07617731 0.9626850 17.126980 4.668924e-66
#> MA0615.1 Gmeb1 0.7973130 0.04793133 0.8379526 8.043624 4.361006e-16
#> MA0632.2 TCFL5 0.8134783 0.07204944 0.8739790 7.966200 8.181371e-16
#> MA0641.1 ELF4 0.7559746 0.05849272 0.7983377 6.870800 3.192133e-12
#> MA1483.1 ELF2 0.7660337 0.05823545 0.8081289 6.857510 3.503553e-12
#> MA1560.1 SOHLH2 0.7737551 0.06452663 0.8175457 6.438177 6.045833e-11
#> FDR
#> MA0506.1 3.483017e-63
#> MA0615.1 1.626655e-13
#> MA0632.2 2.034434e-13
#> MA0641.1 5.227301e-10
#> MA1483.1 5.227301e-10
#> MA1560.1 7.516985e-09ps_results_table() returns motifs ordered by increasing p-value, with
decreasing z-score used to resolve ties. NRF1 is the highest-ranked motif,
consistent with the origin of the curated target set.
A differential expression analysis often produces a gene list. A gene may have several transcription start sites and therefore several distinct promoters, so gene identifiers alone do not uniquely specify a promoter set.
This workflow selects one promoter per gene to avoid giving greater weight to
genes with more annotated transcripts. ps_select_promoters() applies an
explicit selection rule and records the selected transcript and the reason for
its selection. This provides reproducibility without establishing which
transcript is active in the experimental condition.
The function requires the genes of interest, candidate promoter sequences, and a gene-to-transcript annotation table. The following subset of genes from the NRF1 target list illustrates the input format:
genes <- c(
"ALAS1", "ARPC1A", "CAPNS1", "CHMP2A",
"EIF2S1", "GTF2F1", "LONP1", "POLR2A"
)org.Hs.eg.db supplies the gene-to-transcript mapping. These eight genes have
more than eight candidate transcripts:
library(org.Hs.eg.db)
annotation <- AnnotationDbi::select(
org.Hs.eg.db,
keys = genes, keytype = "SYMBOL", columns = "REFSEQ"
)
annotation <- annotation[!is.na(annotation$REFSEQ), ]
nrow(annotation)
#> [1] 83
table(annotation$SYMBOL)
#>
#> ALAS1 ARPC1A CAPNS1 CHMP2A EIF2S1 GTF2F1 LONP1 POLR2A
#> 20 4 22 12 2 6 15 2The annotation table contains unversioned RefSeq accessions, whereas promoter
names such as NM_006559.3 include a version suffix. The function recognises
the RefSeq convention and removes the suffix for identifier matching. It
preserves the suffix in TAIR identifiers such as AT1G01110.2, where it
distinguishes transcript variants that may have different start sites.
Thus, RefSeq matching uses the accession after version normalisation, whereas TAIR matching uses the complete transcript identifier. Matching RefSeq versions does not imply that their sequences or annotated start sites are identical; the promoter sequences must still correspond to the chosen reference.
selection <- ps_select_promoters(
genes = genes,
promoter_sequences = prom_seq,
annotation = annotation,
gene_col = "SYMBOL", transcript_col = "REFSEQ",
mode = "representative",
return = "both"
)The returned mapping documents each selection. Protein accessions such as
NP_ are excluded because they do not identify transcripts:
selection$mapping[, c(
"gene", "transcript_id", "promoter_id",
"scheme", "suffix_role", "n_candidates", "decided_by"
)]
#> gene transcript_id promoter_id scheme suffix_role n_candidates
#> 1 ALAS1 NM_000688 NM_000688.6 refseq version 1
#> 2 ARPC1A NM_006409 NM_006409.4 refseq version 1
#> 3 CAPNS1 NM_001003962 NM_001003962.3 refseq version 1
#> 4 CHMP2A NM_014453 NM_014453.4 refseq version 1
#> 5 EIF2S1 NM_004094 NM_004094.5 refseq version 1
#> 6 GTF2F1 NM_002096 NM_002096.3 refseq version 1
#> 7 LONP1 NM_004793 NM_004793.4 refseq version 1
#> decided_by
#> 1 rule
#> 2 rule
#> 3 rule
#> 4 rule
#> 5 rule
#> 6 rule
#> 7 ruleps_selection_summary() summarises the mapping, including the number of genes
with multiple candidates and the number requiring a tie-breaking rule after
transcript ranking:
ps_selection_summary(selection$mapping)
#> $overall
#> scheme genes_requested genes_mapped genes_unmapped genes_with_choice
#> 1 refseq 8 7 1 0
#> genes_decided_by_tie_break candidates_excluded_protein
#> 1 0 41
#>
#> $by_source
#> selection_source promoters
#> 1 RefSeq NM 7The number of unmapped genes is 1 out of 8;
the unmapped identifiers are POLR2A. These genes
have no matching transcript promoter in the bundled set. The
7 selected promoters are returned as a
DNAStringSet, named by gene and transcript so that a result can be traced
back to both:
selection$sequences
#> DNAStringSet object of length 7:
#> width sequence names
#> [1] 250 CGCTTCCTCCTCCCTGCAGGCGA...CGTTTCGTTTGGACTTCTCGACT ALAS1|NM_000688.6
#> [2] 250 AGCACTTGCCAGGCGTTCCGTGG...CCGACGGAGCCTGTTCGCGTCGA ARPC1A|NM_006409.4
#> [3] 250 GGGTGTCGGGAAGACCCCCGCCT...GGACGCTGCGGGAGGCCCGGGAG CAPNS1|NM_0010039...
#> [4] 250 GGGTGGAAAGCGCCCACCCCGGT...GGACCGAGGGGCCTTAGTTGGTG CHMP2A|NM_014453.4
#> [5] 250 CAGAGGCAAGGAATCGGAGTCCT...GCTGAGGAGGATCGGCGGCCGGT EIF2S1|NM_004094.5
#> [6] 250 CAGACTCGGCCTAGGTTTGCTGA...AGAGGCGCCTAGGGTTGGGGTCC GTF2F1|NM_002096.3
#> [7] 250 AAAGGCCTTCAGCGCATAAAGTG...CTGGCTACGTGCGACTGTGGGGA LONP1|NM_004793.4mode = "representative" ranks transcripts by the identifier scheme’s rule.
For RefSeq, it prefers NM_ over NR_, followed by predicted XM_ and XR_
accessions.
For human hg38, MANE Select and RefSeq Select provide curated transcript
preferences. These can be used with mode = "select":
select_tx <- ps_load_select_transcripts("hg38")
selection <- ps_select_promoters(
genes = genes,
promoter_sequences = prom_seq,
annotation = annotation,
select_transcripts = select_tx,
mode = "select",
return = "both"
)ps_load_select_transcripts() retrieves the two tracks through the UCSC API.
This network-dependent example is not evaluated during vignette compilation.
After retrieval, the table is cached under
tools::R_user_dir("PscanR", "cache") for subsequent calls. The
metadata is specific to human hg38, so for other organisms either
mode = "representative" applies, or a species-specific table is supplied
through select_transcripts.
With return = "both", the selected DNAStringSet is available as
selection$sequences and can be passed to pscan(). It contains one promoter
per mapped gene. The sequences and background must use the same window, here
200 bp upstream and 50 bp downstream. A 950u_50d background would require
promoters extracted over the corresponding interval.
pscan() parallelises over motifs through BiocParallel, and the BPPARAM
argument selects the execution strategy:
MulticoreParam(n) on systems supporting forked execution. Workers
inherit the parent process’s memory, which can reduce data-transfer
overhead on Linux and macOS. Suitability also depends on the execution
environment; forked execution is unavailable on Windows.
SnowParam(n) for portable parallel execution. Independent R processes
communicate through sockets on Windows and Unix-like systems. Worker
startup and data transfer introduce additional overhead.
SerialParam() for debugging and small examples. Computation occurs
within the current R process, simplifying error inspection.
The default is BiocParallel::SerialParam(), which uses one R process.
A registered backend does not change this default; pass BPPARAM explicitly
to request multiple workers.
Select the worker count according to the workload and available resources. For short scans, worker startup and data-transfer costs may exceed the benefit of parallel execution.
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.
sessionInfo()
#> R version 4.6.1 (2026-06-24)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04.5 LTS
#>
#> Matrix products: default
#> BLAS: /home/biocbuild/bbs-3.24-bioc/R/lib/libRblas.so
#> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.12.0 LAPACK version 3.12.0
#>
#> locale:
#> [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
#> [3] LC_TIME=en_GB LC_COLLATE=C
#> [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: America/New_York
#> 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.24.4 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.13
#> [10] generics_0.1.4 PscanRBackgrounds_0.99.7 PscanR_0.99.4
#> [13] 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.3
#> [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.1.0 RColorBrewer_1.1-3
#> [31] BiocParallel_1.47.0 withr_3.0.3
#> [33] purrr_1.2.2 grid_4.6.1
#> [35] ExperimentHub_3.3.2 caTools_1.18.4
#> [37] ggplot2_4.0.3 scales_1.4.0
#> [39] gtools_3.9.5 tinytex_0.61
#> [41] dichromat_2.0-1 cli_3.6.6
#> [43] rmarkdown_2.32 crayon_1.5.3
#> [45] otel_0.3.0 TFMPvalue_1.0.0
#> [47] httr_1.4.9 rjson_0.2.23
#> [49] BiocBaseUtils_1.15.1 DBI_1.3.0
#> [51] cachem_1.1.0 parallel_4.6.1
#> [53] BiocManager_1.30.27 restfulr_0.0.17
#> [55] matrixStats_1.5.0 vctrs_0.7.3
#> [57] jsonlite_2.0.0 bookdown_0.48
#> [59] bit64_4.8.6 magick_2.9.1
#> [61] seqLogo_1.79.0 jquerylib_0.1.4
#> [63] glue_1.8.1 TFBSTools_1.51.0
#> [65] codetools_0.2-20 gtable_0.3.6
#> [67] BiocVersion_3.24.0 BiocIO_1.23.3
#> [69] GenomicRanges_1.65.4 tibble_3.3.1
#> [71] pillar_1.11.1 rappdirs_0.3.4
#> [73] htmltools_0.5.9 JASPAR2020_0.99.10
#> [75] BSgenome_1.81.1 httr2_1.3.0
#> [77] dbplyr_2.6.0 R6_2.6.1
#> [79] evaluate_1.0.5 AnnotationHub_4.3.3
#> [81] png_0.1-9 Rsamtools_2.29.0
#> [83] cigarillo_1.3.1 pheatmap_1.0.13
#> [85] memoise_2.0.1 bslib_0.12.0
#> [87] Rcpp_1.1.2 xfun_0.62
#> [89] pkgconfig_2.0.3