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.
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",
source = "zenodo"
)
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, and 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", used above, 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:
Every 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:
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 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