P-values and scores¶

Exact P-values and score thresholds, and the scores and probabilities of individual matches. Scores use the motif's PWM on the same integer grid as scanning, with each entry multiplied by 1000 and truncated, so that a score and its P-value always agree with what scan_sequences() reports.

motif_pvalue ¶

motif_pvalue(
    motifs: Motif | Iterable[Motif],
    score: float
    | Sequence[float]
    | Sequence[Sequence[float]]
    | None = None,
    pvalue: float
    | Sequence[float]
    | Sequence[Sequence[float]]
    | None = None,
    bkg_probs: Sequence[float]
    | Mapping[str, float]
    | Sequence[object]
    | None = None,
    nthreads: int = 1,
)

P-values for motif scores, or score thresholds for P-values.

Give either score or pvalue. A motif's P-value for a score is the probability that a random site, drawn from the background, scores at least that much; it is computed exactly from the motif's score distribution. A score above the motif's highest possible score has a P-value of 0, with a warning. Going the other way gives the lowest score reached with at most that probability, or infinity if no score is that unlikely.

Scores are computed on an integer grid, with PWM entries multiplied by 1000 and truncated, so they are exact to 0.001.

Parameters:

Name	Type	Description	Default
`motifs`	`Motif \| Iterable[Motif]`	A motif or a list of motifs. They are converted to PWMs; a motif whose PWM would have infinite values gets its pseudocount reapplied first.	required
`score`	`float \| Sequence[float] \| Sequence[Sequence[float]] \| None`	For a single motif, a number or a sequence of numbers. For a list of motifs, a number used for every motif, one number per motif, or a list of sequences with either one per motif or a single one for all.	`None`
`pvalue`	`float \| Sequence[float] \| Sequence[Sequence[float]] \| None`	For a single motif, a number or a sequence of numbers. For a list of motifs, a number used for every motif, one number per motif, or a list of sequences with either one per motif or a single one for all.	`None`
`bkg_probs`	`Sequence[float] \| Mapping[str, float] \| Sequence[object] \| None`	Background frequencies, either one set for all motifs or a list with one per motif, where a set is a sequence in alphabet order or a mapping from letters. Each motif's own background by default.	`None`
`nthreads`	`int`	Threads to use; 0 means all available.	`1`

Returns:

Type	Description
`float \| ndarray \| list[ndarray]`	A float for one motif and one value, a numpy array when values pair up with motifs, or a list of arrays when each motif gets several values.

Examples:

>>> import universalmotif as um
>>> motifs = um.example_motifs()
>>> wbox = motifs[5]
>>> round(um.motif_pvalue(wbox, score=10), 6)
0.000168
>>> um.motif_pvalue(wbox, score=[5, 8, 10]).round(6).tolist()
[0.002483, 0.000492, 0.000168]

Score thresholds for a P-value of 1e-4, one per motif:

>>> um.motif_pvalue(motifs[:3], pvalue=1e-4).round(3).tolist()
[10.252, 10.419, 10.806]

motif_range ¶

motif_range(
    motif: Motif, allow_nonfinite: bool = False
) -> tuple[float, float]

The lowest and highest scores the motif can give.

Scores use the motif's PWM with each entry truncated to three decimals, as scanning does. Unless allow_nonfinite, a PWM with -inf entries gets a pseudocount first; otherwise the lowest score is -inf.

Examples:

>>> import universalmotif as um
>>> sites = ["TGACTCA", "TGAGTCA", "TGACTCA", "TGAGTCA", "TGACTAA"]
>>> motif = um.create_motif(sites, pseudocount=1)
>>> um.motif_range(motif)
(-18.088, 11.652)

motif_score ¶

motif_score(
    motif: Motif,
    threshold: float | Sequence[float] = (0.0, 1.0),
    threshold_type: str = "total",
    allow_nonfinite: bool = False,
) -> float | npt.NDArray[np.float64]

Scores at fractions of the motif's score range.

With threshold_type="total", 0 is the lowest possible score and 1 the highest; with "fromzero", 0 is a score of zero. A single threshold gives a single score.

Examples:

>>> import universalmotif as um
>>> sites = ["TGACTCA", "TGAGTCA", "TGACTCA", "TGAGTCA", "TGACTAA"]
>>> motif = um.create_motif(sites, pseudocount=1)
>>> round(um.motif_score(motif, 0.9), 3)
8.678
>>> um.motif_score(motif, [0, 0.5, 1]).round(3).tolist()
[-18.088, -3.218, 11.652]

score_match ¶

score_match(
    motif: Motif,
    match: str | Sequence[str],
    allow_nonfinite: bool = False,
) -> float | npt.NDArray[np.float64]

The score of each word, which must be as long as the motif, with each PWM entry truncated to three decimals and then added up, so that a word scores exactly what scan_sequences() reports for it. As in motif_pvalue(), a motif whose PWM would have infinite values, such as a count matrix without a pseudocount, gets its pseudocount reapplied first, or 1 if it has none, unless allow_nonfinite.

Examples:

>>> import universalmotif as um
>>> sites = ["TGACTCA", "TGAGTCA", "TGACTCA", "TGAGTCA", "TGACTAA"]
>>> motif = um.create_motif(sites, pseudocount=1)
>>> um.score_match(motif, "TGACTCA")
11.652
>>> um.score_match(motif, ["TGAGTAA", "AAAAAAA"]).round(3).tolist()
[9.356, -6.985]

get_matches ¶

get_matches(
    motif: Motif,
    score: float,
    allow_nonfinite: bool = False,
) -> list[str]

Every word scoring at least score. A score of inf, which motif_pvalue() gives for an unreachable P-value, has no matches.

Examples:

>>> import universalmotif as um
>>> sites = ["TGACTCA", "TGAGTCA", "TGACTCA", "TGAGTCA", "TGACTAA"]
>>> motif = um.create_motif(sites, pseudocount=1)
>>> um.get_matches(motif, um.motif_score(motif, 0.9))
['TGACTCA', 'TGACTAA', 'TGAGTCA', 'TGAGTAA']

get_scores ¶

get_scores(
    motif: Motif, allow_nonfinite: bool = False
) -> npt.NDArray[np.float64]

Every possible score of the motif, highest first. There are as many as the alphabet size to the power of the width, so this is for small motifs.

Examples:

>>> import universalmotif as um
>>> motif = um.create_motif(["TCA", "TCA", "TGA"], pseudocount=1)
>>> scores = um.get_scores(motif)
>>> len(scores), scores[:3].round(3).tolist()
(64, [4.569, 3.721, 1.4])

prob_match ¶

prob_match(
    motif: Motif,
    match: str | Sequence[str],
    allow_zero: bool = True,
) -> float | npt.NDArray[np.float64]

The probability of each word under the motif's background. Each word must have as many letters as the motif has positions. Unless allow_zero, a background with zeros gets a small pseudocount first.

Examples:

>>> import universalmotif as um
>>> motif = um.create_motif("TCA", bkg=[0.3, 0.2, 0.2, 0.3])
>>> um.prob_match(motif, ["TCA", "GGG"]).round(4).tolist()
[0.018, 0.008]

prob_match_bkg ¶

prob_match_bkg(
    bkg: Mapping[str, float], match: str | Sequence[str]
) -> float | npt.NDArray[np.float64]

The probability of each word under the background frequencies bkg, a mapping from letters to frequencies.

Examples:

>>> import universalmotif as um
>>> bkg = {"A": 0.3, "C": 0.2, "G": 0.2, "T": 0.3}
>>> round(um.prob_match_bkg(bkg, "TATA"), 4)
0.0081
>>> um.prob_match_bkg(bkg, ["AAA", "GCG"]).round(4).tolist()
[0.027, 0.008]

log_string_pval ¶

log_string_pval(pval: str) -> float

The natural logarithm of a P-value written as text, such as "1e-400", which may be far smaller than the smallest float.

Examples:

>>> import universalmotif as um
>>> round(um.log_string_pval("1e-400"), 3)
-921.034
>>> round(um.log_string_pval("0.05"), 3)
-2.996