nuget
Scans biological sequences with motif PWMs to identify candidate TFBS loci. Each candidate carries a log-odds score and an exact null-model p-value computed by dynamic programming.
MotifScanner
01 Syntax
SMRUCC.genomics.Analysis.SequenceTools.SequencePatterns.MotifScanner
02 Methods
| Name | Overloads | Summary |
|---|---|---|
| .ctor | 2 | Construct a scanner with uniform background. |
| Scan | 1 | Scan a sequence with a single motif and return all TFBS matches satisfying both the score and p-value thresholds. |
| ScanMultiple | 1 | Scan a sequence with multiple motifs. |
| FilterByScore | 2 | Filter a list of TFBS matches using a null-distribution-derived score cutoff, then keep the top-N by a computed quality score. |
| GetNullDistribution | 1 | Compute (or retrieve from cache) the null score distribution for a motif. |
| ScoreWindow | 1 | Score a specific window of a sequence against the motif. |
| PValueForScore | 1 | Compute the p-value for a given score against the motif's null distribution. |
| BuildLogOddsMatrix | 1 | Build a log-odds matrix [position, alphabet-index] from the motif PWM. |
| BuildAlphabetIndex | 1 | Build a case-insensitive char -> alphabet-index lookup for the motif. |
| GetOrComputeDistribution | 1 | Return the cached null distribution for a motif, or compute and cache it. |
| ComputeNullDistribution | 1 | Compute the exact null distribution of the log-odds score by dynamic programming. |
| ReverseComplement | 1 | Compute the reverse complement of a DNA sequence. |
| ComplementBase | 1 | Complement of a single base (IUPAC-aware). |
03 Properties
| Name | Overloads | Summary |
|---|---|---|
| Background | 1 |
04 Members
#ctor
Construct a scanner with uniform background.
Construct a scanner with a custom background model.
Parameters
| Name | Type | Description |
|---|---|---|
background | BackgroundModel | Nucleotide background frequencies (must sum to 1). |
pseudocount | Double | Pseudocount added to every PWM cell to avoid log(0). |
numBins | Int32 | Number of bins for score-distribution discretization. |
Scan(
MotifPWM, String, Double, Double, Boolean, Int32)Scan a sequence with a single motif and return all TFBS matches satisfying both the score and p-value thresholds.
Parameters
| Name | Type | Description |
|---|---|---|
motif | MotifPWM | The motif PWM to scan with. |
sequence | String | The biological sequence (DNA) to scan. |
scoreThreshold | Double | Minimum log-odds score to report (default: no filter). |
pValueThreshold | Double | Maximum p-value to report (default: no filter). |
scanReverseStrand | Boolean | If True, also scan the reverse complement strand. |
Returns
List of matches, sorted by p-value ascending.
ScanMultiple(
IEnumerable(Of MotifPWM), String, Double, Double, Boolean)Scan a sequence with multiple motifs. Returns all matches from all motifs, sorted by p-value ascending.
FilterByScore(
IEnumerable(Of MotifMatch), Int32, Func(Of MotifMatch, Double))Filter a list of TFBS matches by a computed quality score, keeping the top-N matches with the highest score (higher = better). The list is sorted by score descending before truncation.
Parameters
| Name | Type | Description |
|---|---|---|
matches | IEnumerable(Of MotifMatch) | Candidate matches (e.g. from Scan / ScanMultiple). |
topN | Int32 | Maximum number of matches to keep. |
scoreFunc | Func(Of MotifMatch, Double) | Optional function mapping a match to its quality score. If omitted, a default composite score is used: score1 + score2 - log10(pvalue) where score1 is the log-odds score, score2 is the information content (bits), and a smaller p-value yields a larger (more significant) contribution. Higher scores are considered better. |
Returns
A new list containing the top-N matches, sorted by score descending.
FilterByScore(
IEnumerable(Of MotifMatch), Int32, ScoreDistribution, Double, Func(Of MotifMatch, Double))Filter a list of TFBS matches using a null-distribution-derived score cutoff, then keep the top-N by a computed quality score.
A minimum-score cutoff is derived from distribution via its upper-tail quantile at significanceLevel (e.g. 0.05 yields the score below which only 5% of the null model falls). Matches whose score1 is below this cutoff are discarded as not significant; the survivors are then sorted by the quality score (higher = better) and the top-N are returned.
Parameters
| Name | Type | Description |
|---|---|---|
matches | IEnumerable(Of MotifMatch) | Candidate matches (e.g. from Scan / ScanMultiple). |
topN | Int32 | Maximum number of matches to keep. |
distribution | ScoreDistribution | The motif's null score distribution (from GetNullDistribution). If Nothing, no distribution-based cutoff is applied (pure ranking). |
significanceLevel | Double | Upper-tail mass for the cutoff, in (0,1). |
scoreFunc | Func(Of MotifMatch, Double) | Optional quality-score function (see other overload). |
Returns
Top-N significant matches sorted by quality score descending.
GetNullDistribution(
MotifPWM)Compute (or retrieve from cache) the null score distribution for a motif. The returned distribution can be used to derive statistically grounded score cutoffs, e.g. via ScoreDistribution.Quantile.
Parameters
| Name | Type | Description |
|---|---|---|
motif | MotifPWM | The motif PWM. |
Returns
The null score distribution, or Nothing if the motif is invalid.
ScoreWindow(
MotifPWM, String)Score a specific window of a sequence against the motif. Returns the log-odds score, or Double.NaN if the window contains characters outside the motif alphabet.
PValueForScore(
MotifPWM, Double)Compute the p-value for a given score against the motif's null distribution. Useful for evaluating scores obtained externally.
BuildLogOddsMatrix(
MotifPWM)Build a log-odds matrix [position, alphabet-index] from the motif PWM. Each cell is: log2( (PWM[i][j] + pseudo) / (bg[alphabet[j]] + pseudo) ) The pseudocount avoids log(0) when a PWM cell or background is zero.
BuildAlphabetIndex(
MotifPWM)Build a case-insensitive char -> alphabet-index lookup for the motif.
GetOrComputeDistribution(
MotifPWM, Double[0:,0:])Return the cached null distribution for a motif, or compute and cache it. The cache key is the motif name (falls back to a hash of the PWM if the name is empty).
ComputeNullDistribution(
MotifPWM, Double[0:,0:])Compute the exact null distribution of the log-odds score by dynamic programming.
At each motif position i, the per-position score contribution is a random variable taking value logOdds[i][j] with probability bg[alphabet[j]]. The total score is the sum of these independent per-position contributions; its distribution is the convolution of the per-position distributions, computed iteratively on a discretized score grid.
ReverseComplement(
String)Compute the reverse complement of a DNA sequence. Supports IUPAC ambiguity codes; unknown characters are passed through unchanged.
ComplementBase(
Char)Complement of a single base (IUPAC-aware).
Background