---
title: "PscanR Quick Overview"
author:
    - Diana Betelli
    - Federico Zambelli
date: "`r Sys.Date()`"
output:
    BiocStyle::html_document:
        toc: true
        toc_depth: 2
vignette: >
    %\VignetteIndexEntry{1. PscanR Quick Overview}
    %\VignetteEngine{knitr::rmarkdown}
    %\VignetteEncoding{UTF-8}
---

```{css, echo=FALSE}
table.ps-functions { border-collapse: collapse; width: 100%; }
table.ps-functions th { border-bottom: 2px solid #ccc; }
table.ps-functions td { border-bottom: 1px solid #ddd; }
```

# Introduction

This vignette summarises the principal PscanR functions for motif enrichment
analysis in promoter sequences. The package reference manual provides complete
argument descriptions and examples.

<hr />

# Installation

PscanR is being prepared for Bioconductor submission. After acceptance, install
it with the following command (not executed while building this vignette):

```{r installation, eval=FALSE}
BiocManager::install("PscanR")
```

For pre-submission installation from source, see the package README.

# An executable workflow

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.

```{r quick-scan}
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))
```

NRF1 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).

# Table 1: Motif enrichment analysis and input preparation

<table class="ps-functions">
    <thead>
    <tr>
        <th style="width:20%;">Function</th>
        <th style="width:80%;">Description</th>
    </tr>
    </thead>
    <tbody>
    <tr>
        <td><code>pscan()</code></td>
        <td>
    Computes the best match to each motif in each promoter and tests motif
    enrichment against the supplied background score distributions.
</td>
    </tr>
    <tr>
        <td>
    <code>pscan_full_bg()</code>
</td>
        <td>
    Retrieves stored motif hits for foreground identifiers from a full
    background and calculates enrichment without rescanning the DNA sequences.
</td>
    </tr>
    <tr>
        <td><code>pscan_filtered()</code></td>
        <td>
    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.
</td>
    </tr>
    <tr>
        <td><code>ps_select_promoters()</code></td>
        <td>
    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.
</td>
    </tr>
    <tr>
        <td><code>ps_selection_summary()</code></td>
        <td>
    Summarises a mapping produced by <code>ps_select_promoters()</code>,
    including
    identifier schemes, selection rules, genes with multiple candidates, and
    selections requiring a tie-breaking rule after ranking.
</td>
    </tr>
    <tr>
        <td><code>ps_load_select_transcripts()</code></td>
        <td>
    Downloads and caches human hg38 MANE Select and RefSeq Select metadata from
    UCSC for use with <code>ps_select_promoters()</code>. Other organisms
    require
    an appropriate user-supplied selection table or representative selection.
</td>
    </tr>
    </tbody>
</table>

<hr />

# Table 2: Background construction

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.

<table class="ps-functions">
    <thead>
    <tr>
        <th style="width:30%;">Function</th>
        <th style="width:70%;">Description</th>
    </tr>
    </thead>
    <tbody>
    <tr>
        <td>
            <code>ps_build_bg()</code>
        </td>
        <td>
    Scans the supplied reference sequences and computes background statistics
    for each motif after sequence filtering and deduplication.
</td>
    </tr>
    <tr>
        <td>
    <code>ps_retrieve_bg()</code>
</td>
        <td>
    Retrieves a precomputed background and associates its statistics with the
    matching motif matrices in a <code>PSMatrixList</code>.
</td>
    </tr>
    <tr>
        <td>
    <code>ps_available_bg()</code>
</td>
        <td>
    Displays the names of all available precomputed backgrounds, with options to
    filter by keywords.
</td>
    </tr>
    <tr>
        <td><code>ps_retrieve_bg_from_file()</code></td>
        <td>
    Reads a background text file and associates the stored size, mean score,
    and standard deviation with the supplied motif matrices by identifier.
</td>
    </tr>
    <tr>
        <td><code>ps_build_bg_from_table()</code></td>
        <td>
    Associates background parameters held in a <code>data.frame</code> with a
    list of position frequency matrices and returns the result as a
    <code>PSMatrixList</code>.
</td>
    </tr>
    <tr>
        <td><code>ps_get_bg_table()</code></td>
        <td>
    Extracts the background statistics (size, mean and standard deviation) from
    a <code>PSMatrixList</code> as a <code>data.frame</code>, which is the
    inverse of <code>ps_build_bg_from_table()</code>.
</td>
    </tr>
    <tr>
        <td><code>ps_write_bg_to_file()</code></td>
        <td>
    Writes the background statistics of a <code>PSMatrixList</code> to a text
    file, in the format <code>ps_retrieve_bg_from_file()</code> reads back.
</td>
    </tr>
    <tr>
        <td><code>ps_build_bg(fullBG = TRUE)</code></td>
        <td>
    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.
</td>
    </tr>
    <tr>
        <td><code>pscan_full_bg()</code></td>
        <td>
    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.
</td>
    </tr>
    <tr>
        <td><code>ps_transcript_legend()</code></td>
        <td>
    Retrieves the mapping from original sequence names to representatives
    retained after deduplication. This allows <code>pscan_full_bg()</code> to
    resolve identifiers associated with identical promoter sequences.
</td>
    </tr>
    </tbody>
</table>

<hr />

# Table 3: Result summaries and visualisation

<table class="ps-functions">
    <thead>
    <tr>
        <th style="width:25%;">Function</th>
        <th style="width:85%;">Description</th>
    </tr>
    </thead>
    <tbody>
    <tr>
        <td>
    <code>ps_results_table()</code>
</td>
        <td>
    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.
</td>
    </tr>
    <tr>
        <td>
            <code>ps_z_table()</code>
        </td>
        <td>
    Returns a matrix of standardised best-hit scores, with promoters as rows
    and motifs as columns, from a <code>PSMatrixList</code>.
</td>
    </tr>
    <tr>
        <td>
    <code>ps_zscore_heatmap()</code>
</td>
        <td>
    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.
</td>
    </tr>
    <tr>
        <td>
    <code>ps_hitpos_map()</code>
</td>
        <td>
        Displays the position of each promoter's best motif match as a heatmap
        to compare positional patterns across motifs.
        </td>
    </tr>
    <tr>
        <td>
    <code>ps_density_plot()</code>
</td>
        <td>
        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.
        </td>
    </tr>
    <tr>
        <td><code>ps_hit_score_plot()</code></td>
        <td>
    Plots best-hit score against position for each promoter, allowing joint
    assessment of match strength and positional concentration.
</td>
    </tr>
    <tr>
        <td><code>ps_motif_barplot()</code></td>
        <td>
    Displays the highest-ranked motifs as horizontal bars, optionally coloured
    by a grouping such as transcription factor structural class.
</td>
    </tr>
    <tr>
        <td><code>ps_motif_class()</code></td>
        <td>
    Extracts the transcription factor structural class associated with each
    motif, for example <code>"Basic leucine zipper factors (bZIP)"</code>, for
    annotation or grouping in <code>ps_motif_barplot()</code>.
</td>
    </tr>
    </tbody>
</table>

<hr />

# Data provenance

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.

# Session information

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