Skip to content

Sequence Analysis

Functions for extracting and analyzing DNA sequences, including reverse complement operations, k-mer counting, and position weight matrix scoring.

pymisha.gseq_extract

gseq_extract(intervals: DataFrame | str, pad: bool = False) -> list[str]

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: DataFrame

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: bool DEFAULT: False

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

gseq_rev(seq: str | list[str]) -> str | list[str]

Reverse DNA sequence(s).

PARAMETER DESCRIPTION
seq

DNA sequence(s) to reverse.

TYPE: str or list of str

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

gseq_comp(seq: str | list[str]) -> str | list[str]

Return complement of DNA sequence(s).

PARAMETER DESCRIPTION
seq

DNA sequence(s) to complement.

TYPE: str or list of str

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

gseq_revcomp(seq: str | list[str]) -> str | list[str]

Return reverse complement of DNA sequence(s).

PARAMETER DESCRIPTION
seq

DNA sequence(s) to reverse complement.

TYPE: str or list of str

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: str or list of str

kmer

K-mer pattern to search for (only A, C, G, T characters).

TYPE: str

mode

"count" returns raw counts, "frac" returns the fraction of the allowed anchors that match.

TYPE: str DEFAULT: "count"

strand

0 = both strands, summed, 1 = forward only, -1 = reverse complement only.

TYPE: int DEFAULT: 0

start_pos

1-based start of the ROI, per sequence (recycled); 1 by default.

TYPE: int or list of int DEFAULT: None

end_pos

1-based end of the ROI (inclusive), per sequence (recycled); the sequence end by default.

TYPE: int or list of int DEFAULT: None

extend

How many bases a match may run past end_pos: False for none (only k-mers inside the ROI), True for len(kmer) - 1 (every anchor in the ROI), or a non-negative number of bases. It never moves the first anchor before start_pos; a number above len(kmer) - 1 also counts k-mers that start after end_pos (and frac counts their starts).

TYPE: bool or int DEFAULT: False

skip_gaps

If True, gap characters are removed before scanning; windows are k consecutive non-gap bases, and extend and the frac denominator count non-gap bases and windows.

TYPE: bool DEFAULT: True

gap_chars

Characters to treat as gaps. Default: ["-", "."].

TYPE: list of str DEFAULT: None

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:

>>> import pymisha as pm

Count CG dinucleotides on the forward strand (CG is its own reverse complement, so strand=0 would count each site twice, with a warning):

>>> pm.gseq_kmer(["CGCGCGCGCG", "ATATATATAT"], "CG", strand=1)
array([5., 0.])

Get fraction instead of count:

>>> pm.gseq_kmer(["CGCGCGCGCG"], "CG", mode="frac", strand=1)
array([0.555...])

Count in a specific region:

>>> pm.gseq_kmer("ATCGATCG", "AT", strand=1, start_pos=1, end_pos=4)
array([1.])
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: DataFrame

k

K-mer size (1-10).

TYPE: int DEFAULT: 6

mask

Intervals to exclude: a k-mer with any base in one is not counted.

TYPE: DataFrame DEFAULT: None

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: str or list of str

pssm

Position-specific scoring matrix. If ndarray, shape (w, 4) with columns ordered [A, C, G, T]. If DataFrame, must contain columns A, C, G, T (extra columns are ignored).

TYPE: ndarray or DataFrame

mode

Scoring mode:

  • "lse": log-sum-exp of all per-position scores.
  • "max": maximum per-position score.
  • "pos": 1-based position of best match.
  • "count": number of positions with score >= score_thresh.

TYPE: str DEFAULT: ``"lse"``

bidirect

If True, score both forward and reverse complement strands. Overrides strand.

TYPE: bool DEFAULT: True

strand

Used only when bidirect=False, and required there: 1 for the forward strand, -1 for the reverse complement. 0 is refused, since exactly one strand is read and 0 cannot name it. Under bidirect=True both strands are read and this is ignored.

TYPE: int DEFAULT: 1

score_thresh

Threshold for "count" mode, where it is required: PWM scores are log-likelihoods, so no default suits every PSSM. Ignored otherwise.

TYPE: float DEFAULT: None

start_pos

1-based inclusive start of the region of interest (ROI), per sequence (recycled); 1 by default.

TYPE: int, list of int or None DEFAULT: None

end_pos

1-based inclusive end of the ROI, per sequence (recycled); the sequence end by default.

TYPE: int, list of int or None DEFAULT: None

extend

How many bases a window may run past end_pos: False for none (only windows inside the ROI), True for w - 1 (every anchor in the ROI), or a non-negative number of bases; never past the end of the sequence. As in the pwm virtual tracks, a window on either strand is anchored at its first base, which never lies before start_pos; a number above w - 1 also scores windows that start after end_pos. With skip_gaps, extend counts non-gap bases.

TYPE: bool or int DEFAULT: False

spat_factor

Spatial weighting factors, one per spatial bin. When provided, the score at each window position is shifted in log-space by log(spat_factor[bin]) where bin = offset // spat_bin and offset is the 0-based position of the window start relative to the ROI start. Values must be non-negative.

TYPE: array - like or None DEFAULT: None

spat_bin

Number of consecutive positions that share the same spatial weight. Position offset maps to bin offset // spat_bin.

TYPE: int DEFAULT: 1

spat_min

1-based position, counted from start_pos, where the scanning window starts (>= 1); spatial bins are counted from it.

TYPE: float or None DEFAULT: None

spat_max

1-based position, counted from start_pos, where the scanning window ends: only windows ending at or before it are scored (>= 1). A spat_min..spat_max window shorter than the PSSM is an error.

TYPE: float or None DEFAULT: None

return_strand

For mode="pos" with bidirectional scoring, return a DataFrame with pos and strand columns instead of a plain array.

TYPE: bool DEFAULT: False

skip_gaps

Skip gap characters when scanning.

TYPE: bool DEFAULT: True

gap_chars

Characters treated as gaps. Default ["-", "."].

TYPE: list of str or None DEFAULT: None

neutral_chars

Characters to score as unknown bases, by neutral_chars_policy, instead of leaving their windows out. Default: none, as in R misha 5.15, so a window holding N or any other non-ACGT base is not scored (an interval with no scorable window gives -inf, or NaN for mode="pos"). Pass ["N", "n", "*"] for the scores of earlier versions.

TYPE: list of str or None DEFAULT: None

neutral_chars_policy

How to score neutral characters:

  • "average": mean log-probability of the PSSM column.
  • "log_quarter": log(0.25).
  • "na": window is invalid (NaN).

TYPE: str DEFAULT: ``"average"``

prior

Pseudocount added to PSSM before normalization, between 0 and 1.

TYPE: float DEFAULT: 0.01

RETURNS DESCRIPTION
ndarray or DataFrame

Array of scores (one per input sequence). For mode="pos" with return_strand=True, returns a DataFrame with columns pos and strand. A sequence whose windows are all unscorable (for example all N) gives 0 for "count", as pwm.count does. A sequence or ROI with no window at all (shorter than the motif, start_pos past end_pos, fewer non-gap bases than the motif), or a None sequence, gives NaN in every mode, "count" included, as the pwm virtual tracks give for an interval without an anchor.

Examples:

>>> import pymisha as pm
>>> import numpy as np

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):

>>> pm.gseq_pwm(["ACGTACGT", "GGGGGGGG"], pssm, mode="lse")
array([...])

Find position of best match:

>>> pm.gseq_pwm(["ACGTACGT"], pssm, mode="pos")
array([...])

Count matches above a threshold:

>>> pm.gseq_pwm(["ACGTACGT"], pssm, mode="count", score_thresh=-5.0)
array([...])
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: str or list of str

model

The energy model, with keys:

  • e -- a (W, 4) numeric array or DataFrame with columns A, C, G, T: the per-position energies.
  • J -- a list of 4x4 arrays, or an (npair, 16) array: the coupling tables, one per row of pairs, indexed with the lower position on the rows.
  • pairs -- an (npair, 2) array of 1-based position pairs, lower position first.
  • intercept -- a single number.

Extra keys named width, pair_strength, attr or link are accepted and ignored, so a fitted model can be passed verbatim; width is cross-checked against the row count of e.

TYPE: dict

mode

"lse" for the log-sum-exp over windows, "max" for the best window, "pos" for the 1-based position of the best window (signed by strand when bidirect=True), "count" for the number of windows scoring at least score_thresh.

TYPE: str DEFAULT: ``"lse"``

bidirect

If True both strands are read. The two strands are combined at each window by log-sum-exp for "lse", "max" and "count", and by the maximum for "pos", which has to name a strand. :func:gseq_pwm splits the two the same way.

TYPE: bool DEFAULT: True

strand

Used only when bidirect=False, and required there: 1 for the forward strand, -1 for the reverse. The default 0 is accepted only under bidirect=True, where both strands are read and it is ignored.

TYPE: int DEFAULT: 0

score_thresh

Required for mode="count" and ignored otherwise. A Potts score is an energy whose usable range depends entirely on the model, so there is no default; read one off mode="max" over your own sequences.

TYPE: float DEFAULT: None

extend

Accepted for signature parity with :func:gseq_pwm and ignored - a bare sequence has no genome to extend into. True or False, as in R.

TYPE: bool DEFAULT: False

RETURNS DESCRIPTION
ndarray

One value per input sequence.

Examples:

>>> import numpy as np
>>> import pymisha as pm

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

gseq_read_meme(file: str) -> dict[str, _pandas.DataFrame]

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 (.meme, .txt).

TYPE: str

RETURNS DESCRIPTION
dict[str, DataFrame]

Keys are motif identifiers, values are DataFrames. Each DataFrame has .attrs with keys: name, alength, w, nsites, E, url, strand, background.

RAISES DESCRIPTION
FileNotFoundError

If file does not exist.

ValueError

If the file is malformed or contains unsupported content.

pymisha.gseq_read_jaspar

gseq_read_jaspar(file: str) -> dict[str, _pandas.DataFrame]

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 (.jaspar, .pfm, .txt).

TYPE: str

RETURNS DESCRIPTION
dict[str, DataFrame]

Keys are motif identifiers, values are DataFrames with columns A, C, G, T. Each DataFrame has .attrs with keys: name, w, nsites, format.

RAISES DESCRIPTION
FileNotFoundError

If file does not exist.

ValueError

If the file is malformed.

pymisha.gseq_read_homer

gseq_read_homer(file: str) -> dict[str, _pandas.DataFrame]

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 (.motif).

TYPE: str

RETURNS DESCRIPTION
dict[str, DataFrame]

Keys are derived from the consensus sequence. Each DataFrame has .attrs with keys: name, consensus, log_odds_threshold, log_p_value, w, source.

RAISES DESCRIPTION
FileNotFoundError

If file does not exist.

ValueError

If the file is malformed.