Sequence Analysis¶
Functions for extracting and analyzing DNA sequences, including reverse complement operations, k-mer counting, and position weight matrix scoring.
pymisha.gseq_extract ¶
Extract DNA sequences for given intervals.
Returns an array of sequence strings for each interval from 'intervals'. If intervals contain an additional 'strand' column and its value is -1, the reverse-complementary sequence is returned.
By default (pad=False) each interval must lie within its chromosome:
an interval that starts before 0 or ends past the end of the chromosome
is an error.
With pad=True an interval may run past either end of its chromosome
(start below 0, end above the chromosome length). The positions
outside the chromosome come back as "N", so each sequence is
end - start long, and an interval wholly outside its chromosome comes
back as all "N". start must still be below end, and the chromosome
must exist. For a row with strand -1 the padded sequence is reverse
complemented as a whole, so the "N" run of the chromosome start comes
last. The bases inside the chromosome are returned as stored, lowercase
included. This gives fixed-width windows near chromosome ends, e.g. for
sequence models (see the examples).
| PARAMETER | DESCRIPTION |
|---|---|
intervals
|
Intervals for which DNA sequence is returned. Must have 'chrom', 'start', and 'end' columns. Optional 'strand' column (-1 for reverse complement).
TYPE:
|
pad
|
If True, the part of an interval outside its chromosome is returned as "N". If False, an interval that runs past a chromosome end is an error.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
list of str
|
Array of character strings representing DNA sequence. |
Examples:
>>> import pymisha as pm
>>> _ = pm.gdb_init_examples()
>>> intervs = pm.gintervals(["1", "2"], [10000, 10000], [10020, 10020])
>>> pm.gseq_extract(intervs)
[...]
Fixed-width windows centred on positions. The second window starts 30 bp before the start of chr1, so its first 30 bases are N.
>>> import pandas as pd
>>> w = 100
>>> centers = [250000, 20]
>>> windows = pd.DataFrame({"chrom": "chr1", "start": [c - w // 2 for c in centers],
... "end": [c + w // 2 for c in centers]})
>>> seqs = pm.gseq_extract(windows, pad=True)
>>> [len(s) for s in seqs]
[100, 100]
>>> seqs[1][:30] == "N" * 30
True
See Also
gseq_rev, gseq_comp, gseq_revcomp, gseq_kmer
pymisha.gseq_rev ¶
Reverse DNA sequence(s).
| PARAMETER | DESCRIPTION |
|---|---|
seq
|
DNA sequence(s) to reverse.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
str or list of str
|
Reversed sequence(s). |
Examples:
>>> import pymisha as pm
>>> pm.gseq_rev("ACGT")
'TGCA'
>>> pm.gseq_rev(["ACGT", "TATA"])
['TGCA', 'ATAT']
See Also
gseq_comp, gseq_revcomp, gseq_extract
pymisha.gseq_comp ¶
Return complement of DNA sequence(s).
| PARAMETER | DESCRIPTION |
|---|---|
seq
|
DNA sequence(s) to complement.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
str or list of str
|
Complemented sequence(s). |
Examples:
>>> import pymisha as pm
>>> pm.gseq_comp("ACGT")
'TGCA'
>>> pm.gseq_comp(["ACGT", "AAAA"])
['TGCA', 'TTTT']
See Also
gseq_rev, gseq_revcomp, gseq_extract
pymisha.gseq_revcomp ¶
Return reverse complement of DNA sequence(s).
| PARAMETER | DESCRIPTION |
|---|---|
seq
|
DNA sequence(s) to reverse complement.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
str or list of str
|
Reverse complemented sequence(s). |
Examples:
>>> import pymisha as pm
>>> pm.gseq_revcomp("AACG")
'CGTT'
>>> pm.gseq_revcomp(["AACG", "AAAA"])
['CGTT', 'TTTT']
See Also
gseq_rev, gseq_comp, gseq_extract
pymisha.gseq_kmer ¶
gseq_kmer(seqs: str | list[str], kmer: str, mode: str = 'count', strand: int = 0, start_pos: int | list[int] | None = None, end_pos: int | list[int] | None = None, extend: bool | int = False, skip_gaps: bool = True, gap_chars: list[str] | None = None) -> _numpy.ndarray
Count k-mer occurrences in DNA sequences.
Counts the k-mer as the kmer.count and kmer.frac virtual tracks do,
with the region of interest (ROI) in the interval's place: a match on
either strand is anchored at its first (leftmost) base, which must not lie
before start_pos, and extend sets how many bases past end_pos
it may run, never past the end of the sequence. With strand=0 the
matches on the two strands are summed, so a palindromic k-mer (its own
reverse complement) counts twice per site, and a warning is given; use
strand=1 or -1 to count it once. mode="frac" divides by the
number of allowed anchors, doubled with strand=0, so the fraction stays
in [0, 1].
| PARAMETER | DESCRIPTION |
|---|---|
seqs
|
DNA sequence(s) to search (case-insensitive).
TYPE:
|
kmer
|
K-mer pattern to search for (only A, C, G, T characters).
TYPE:
|
mode
|
"count" returns raw counts, "frac" returns the fraction of the allowed anchors that match.
TYPE:
|
strand
|
0 = both strands, summed, 1 = forward only, -1 = reverse complement only.
TYPE:
|
start_pos
|
1-based start of the ROI, per sequence (recycled); 1 by default.
TYPE:
|
end_pos
|
1-based end of the ROI (inclusive), per sequence (recycled); the sequence end by default.
TYPE:
|
extend
|
How many bases a match may run past
TYPE:
|
skip_gaps
|
If True, gap characters are removed before scanning; windows are k
consecutive non-gap bases, and
TYPE:
|
gap_chars
|
Characters to treat as gaps. Default: ["-", "."].
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ndarray
|
Array of counts or fractions, one per input sequence: 0 for a sequence shorter than the k-mer or an empty ROI, NaN for a None sequence. |
Examples:
Count CG dinucleotides on the forward strand (CG is its own reverse
complement, so strand=0 would count each site twice, with a warning):
Get fraction instead of count:
Count in a specific region:
See Also
gseq_kmer_dist, gseq_pwm, gseq_extract
pymisha.gseq_kmer_dist ¶
gseq_kmer_dist(intervals: DataFrame | str, k: int = 6, mask: DataFrame | None = None) -> _pandas.DataFrame
Compute k-mer distribution in genomic intervals.
Counts all k-mers of size k within the specified genomic intervals, optionally excluding masked regions.
| PARAMETER | DESCRIPTION |
|---|---|
intervals
|
Genomic intervals to analyze. Overlapping intervals are unified first, so each position is counted once; a k-mer that crosses from an interval into an adjacent one is not counted.
TYPE:
|
k
|
K-mer size (1-10).
TYPE:
|
mask
|
Intervals to exclude: a k-mer with any base in one is not counted.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
DataFrame
|
DataFrame with columns 'kmer' (str) and 'count' (int). Only k-mers with count > 0 are included. |
Examples:
>>> import pymisha as pm
>>> _ = pm.gdb_init_examples()
>>> intervs = pm.gintervals(1, 0, 10000)
>>> result = pm.gseq_kmer_dist(intervs, k=2)
>>> list(result.columns)
['kmer', 'count']
See Also
gseq_kmer, gseq_pwm, gseq_extract
pymisha.gseq_pwm ¶
gseq_pwm(seqs: str | list[str], pssm: ndarray | DataFrame, mode: str = 'lse', bidirect: bool = True, strand: int = 1, score_thresh: float | None = None, start_pos: int | list[int] | None = None, end_pos: int | list[int] | None = None, extend: bool | int = False, spat_factor: ndarray | list[float] | None = None, spat_bin: int = 1, spat_min: float | None = None, spat_max: float | None = None, return_strand: bool = False, skip_gaps: bool = True, gap_chars: list[str] | None = None, neutral_chars: list[str] | None = None, neutral_chars_policy: str = 'average', prior: float = 0.01) -> _numpy.ndarray | _pandas.DataFrame
Score DNA sequences with a position weight matrix (PWM/PSSM).
Scans each input sequence with a sliding window of PSSM width and computes per-position log-probability scores, then aggregates them according to mode.
| PARAMETER | DESCRIPTION |
|---|---|
seqs
|
DNA sequence(s) to score.
TYPE:
|
pssm
|
Position-specific scoring matrix. If ndarray, shape
TYPE:
|
mode
|
Scoring mode:
TYPE:
|
bidirect
|
If True, score both forward and reverse complement strands. Overrides strand.
TYPE:
|
strand
|
Used only when
TYPE:
|
score_thresh
|
Threshold for
TYPE:
|
start_pos
|
1-based inclusive start of the region of interest (ROI), per sequence (recycled); 1 by default.
TYPE:
|
end_pos
|
1-based inclusive end of the ROI, per sequence (recycled); the sequence end by default.
TYPE:
|
extend
|
How many bases a window may run past
TYPE:
|
spat_factor
|
Spatial weighting factors, one per spatial bin. When provided,
the score at each window position is shifted in log-space by
TYPE:
|
spat_bin
|
Number of consecutive positions that share the same spatial
weight. Position offset maps to bin
TYPE:
|
spat_min
|
1-based position, counted from
TYPE:
|
spat_max
|
1-based position, counted from
TYPE:
|
return_strand
|
For
TYPE:
|
skip_gaps
|
Skip gap characters when scanning.
TYPE:
|
gap_chars
|
Characters treated as gaps. Default
TYPE:
|
neutral_chars
|
Characters to score as unknown bases, by
TYPE:
|
neutral_chars_policy
|
How to score neutral characters:
TYPE:
|
prior
|
Pseudocount added to PSSM before normalization, between 0 and 1.
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ndarray or DataFrame
|
Array of scores (one per input sequence). For |
Examples:
Create a simple PSSM (frequency matrix):
>>> pssm = np.array([
... [0.7, 0.1, 0.1, 0.1],
... [0.1, 0.7, 0.1, 0.1],
... [0.1, 0.1, 0.7, 0.1],
... [0.1, 0.1, 0.1, 0.7],
... ])
Score sequences using log-sum-exp (default mode):
Find position of best match:
Count matches above a threshold:
See Also
gseq_kmer, gseq_kmer_dist, gseq_extract
pymisha.gseq_potts ¶
gseq_potts(seqs: str | list[str], model: dict, mode: str = 'lse', bidirect: bool = True, strand: int = 0, score_thresh: float | None = None, extend: bool = False) -> _numpy.ndarray
Score DNA sequences under a Potts (pairwise energy) model.
The sequence-level entry point of the potts family, the way
:func:gseq_pwm is the pwm family's. The score of one width-W
window is intercept + sum_i e[i, x_i] + sum_k J_k[x_i, x_j], and a
sequence longer than W is reduced over every window by mode.
The parameterisation is not unique: adding a constant to a position's four
e entries, or a row or column shift to a J block, changes no score,
so e is comparable across positions only in the zero-sum gauge, where
each row of e sums to 0 and every J block has zero row and column
sums.
A Potts carries energies, not probabilities, so there is no prior and
no fallback for an ambiguous base: a window containing any non-ACGT base is
not scored and is left out of the reduction. A sequence that has windows
but none of them scorable returns nan, and 0 for mode="count":
it counted, and found none. A sequence shorter than the model returns
nan for every mode including "count" - there was no window to count.
| PARAMETER | DESCRIPTION |
|---|---|
seqs
|
DNA sequence(s) to score (case-insensitive).
TYPE:
|
model
|
The energy model, with keys:
Extra keys named
TYPE:
|
mode
|
TYPE:
|
bidirect
|
If True both strands are read. The two strands are combined at each
window by log-sum-exp for
TYPE:
|
strand
|
Used only when
TYPE:
|
score_thresh
|
Required for
TYPE:
|
extend
|
Accepted for signature parity with :func:
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
ndarray
|
One value per input sequence. |
Examples:
A W=2 model with a real coupling. On the per-position energies alone
the model prefers "AC", but the pair term penalises A-then-C and
rewards G-then-T, so "GT" wins instead:
>>> e = np.array([[1.0, 0, 0, 0], [0, 1.0, 0, 0]])
>>> J = [np.array([[0, -3.0, 0, 0], [0, 0, 0, 0], [0, 0, 0, 3.0], [0, 0, 0, 0]])]
>>> model = {"e": e, "J": J, "pairs": np.array([[1, 2]]), "intercept": 0.0}
>>> pm.gseq_potts(["AC", "GT"], model, mode="max", bidirect=False, strand=1)
array([-1., 3.])
See Also
gseq_pwm : the same reduction for a position weight matrix.
gvtrack_create : the potts virtual track functions.
Motif Import¶
Functions to import motifs from standard motif format files (MEME, JASPAR, HOMER).
pymisha.gseq_read_meme ¶
Read motifs from a MEME minimal motif format file.
Parses a MEME minimal motif format file and returns a dict of position
probability matrices (PPM). Each DataFrame has columns A, C,
G, T with one row per motif position. Metadata is stored in the
DataFrame's .attrs dict.
| PARAMETER | DESCRIPTION |
|---|---|
file
|
Path to a MEME format file (
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
dict[str, DataFrame]
|
Keys are motif identifiers, values are DataFrames. Each DataFrame
has |
| RAISES | DESCRIPTION |
|---|---|
FileNotFoundError
|
If file does not exist. |
ValueError
|
If the file is malformed or contains unsupported content. |
pymisha.gseq_read_jaspar ¶
Read motifs from a JASPAR PFM format file.
Parses a JASPAR Position Frequency Matrix (PFM) file and returns a dict
of position probability matrices (PPM). Supports both the standard JASPAR
header format (>ID NAME followed by labeled A/C/G/T rows) and the
simple 4-row PFM format. Counts are converted to probabilities.
| PARAMETER | DESCRIPTION |
|---|---|
file
|
Path to a JASPAR format file (
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
dict[str, DataFrame]
|
Keys are motif identifiers, values are DataFrames with columns
|
| RAISES | DESCRIPTION |
|---|---|
FileNotFoundError
|
If file does not exist. |
ValueError
|
If the file is malformed. |
pymisha.gseq_read_homer ¶
Read motifs from a HOMER motif format file.
Parses a HOMER .motif format file and returns a dict of position
probability matrices (PPM). Each DataFrame has columns A, C,
G, T.
| PARAMETER | DESCRIPTION |
|---|---|
file
|
Path to a HOMER motif file (
TYPE:
|
| RETURNS | DESCRIPTION |
|---|---|
dict[str, DataFrame]
|
Keys are derived from the consensus sequence. Each DataFrame has
|
| RAISES | DESCRIPTION |
|---|---|
FileNotFoundError
|
If file does not exist. |
ValueError
|
If the file is malformed. |