---
title: "PscanR Background Resources"
author: "Federico Zambelli"
date: "`r Sys.Date()`"
package: PscanRBackgrounds
output:
  BiocStyle::html_document:
    toc_float: true
vignette: >
  %\VignetteIndexEntry{PscanR Background Resources}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```

# Introduction

`PscanRBackgrounds` provides the precomputed promoter backgrounds used by the
[PscanR](https://github.com/Federico77z/PscanR) motif enrichment package.
PscanR compares the motif scores of a set of foreground promoters against the
distribution of the same scores over all promoters of an organism. Computing
that distribution means scanning every promoter of a genome with every motif
of a JASPAR collection, which takes hours; this package distributes the
result for the most common combinations.

Version 2 of the backgrounds covers three JASPAR CORE releases (2020, 2022,
2024), seven genome assemblies of five organisms, and five promoter windows,
for 105 backgrounds. Each background is a separate ExperimentHub resource.
The files are hosted on Zenodo, in one record per JASPAR release:
<https://doi.org/10.5281/zenodo.23183695> (2020),
<https://doi.org/10.5281/zenodo.23183713> (2022) and
<https://doi.org/10.5281/zenodo.23183720> (2024). All 105 files are also
archived as a single ZIP in <https://doi.org/10.5281/zenodo.21821764>.

# Installation

```{r installation, eval=FALSE}
if (!require("BiocManager", quietly = TRUE))
    install.packages("BiocManager")
BiocManager::install("PscanRBackgrounds")
```

```{r load-package}
library(PscanRBackgrounds)
```

# Available resources

The metadata of all resources is installed with the package and can be
inspected without network access.

```{r metadata}
metadata <- read.csv(system.file(
    "extdata", "metadata.csv", package = "PscanRBackgrounds"
))
nrow(metadata)
head(metadata[c("Title", "Genome", "Species", "TaxonomyId")])
table(metadata$Genome)
```

Titles follow the pattern
`PscanR_bg_v2_J<release>_<assembly>_<up>u_<down>d_<source>`. The installed
catalog records the provenance of every background: annotation source and
retrieval date, promoter, motif and annotation hashes, scanner version and
commit, and the SHA-256 checksum of the file.

```{r catalog}
catalog <- read.delim(system.file(
    "extdata", "catalog_v2.tsv", package = "PscanRBackgrounds"
))
table(catalog$assembly, catalog$jaspar_release)
catalog[1, c("artifact", "motif_count", "promoter_count",
    "annotation_source", "pscanr_version")]
```

# Retrieval through ExperimentHub

Each resource uses the `FilePath` dispatch class: retrieval downloads the
text file once, caches it, and returns its local path.

```{r access, eval=FALSE}
library(ExperimentHub)
eh <- ExperimentHub()
backgrounds <- query(eh, "PscanRBackgrounds")
hg38 <- query(backgrounds, c("hg38", "JASPAR2020", "200u_50d"))
hg38
path <- hg38[[1]]
readLines(path, n = 3)
```

PscanR users normally do not open the files directly: PscanR selects the
background matching the requested JASPAR release, organism, assembly and
promoter window, verifies its checksum, and combines it with the JASPAR
matrices into the object its enrichment functions take.

# License and provenance

The backgrounds are distributed under CC BY 4.0. Cite the Zenodo record and
the Pscan method (Zambelli, Pesole and Pavesi, 2009,
<https://doi.org/10.1093/nar/gkp464>). The installed `DATA_SOURCES.md` lists
the upstream sources; `scripts/make-data.R` describes how the backgrounds
were generated, and `scripts/make-metadata.R` builds the ExperimentHub
metadata. The generation pipeline is maintained at
<https://github.com/Federico77z/PscanRBackgrounds-pipeline>.

# Session information

```{r session-info}
sessionInfo()
```