eff-len 0.1.0__py3-none-any.whl

eff_len/__init__.py

@@ -0,0 +1,2 @@
+from .div import *
+from .utils import *

eff_len/div.py

@@ -0,0 +1,262 @@
+"""
+"""
+
+import numpy as np
+from numpy.lib.stride_tricks import as_strided
+from .utils import msa_to_oh
+
+
+def average_dist(X):
+    N, L, k = X.shape
+    X = X.reshape(N, -1)
+    mat_dist = L - X @ X.T
+    avg_dist = mat_dist[np.triu_indices(N, k=1)].mean()
+    return avg_dist
+
+
+def kmers_from_id_matrix(ids, kmer_len):
+    ids = np.asarray(ids)
+    N, L = ids.shape
+
+    n_kmers = L - kmer_len + 1
+    sN, sL = ids.strides
+
+    kmers = as_strided(ids, shape=(N, n_kmers, kmer_len), strides=(sN, sL, sL))
+    return kmers.copy()
+
+
+def kmer_entropy(ids, kmer_len):
+    kmers = kmers_from_id_matrix(ids, kmer_len)    # (N, n_kmers, kmer_len)
+    flat = kmers.reshape(-1, kmer_len)            # all k-mers in one list
+
+    unique_kmers, counts = np.unique(flat, axis=0, return_counts=True)
+    p = counts / counts.sum()
+    H = -np.sum(p * np.log(p + 1e-15))      # numerical safety
+    return np.exp(H)
+
+
+def pos_entropy(X: np.ndarray, pos: bool = False, leff: bool=False, neff: bool = False, eps: float = 1e-12):
+    assert len(X.shape) == 3, "MSA must be NxLxk, where N is the number of sequences, L the length, and k is 5 or 21"
+    N, L, k = X.shape
+    p = X.mean(axis=0)                 # frequency per symbol
+    p = np.clip(p, eps, 1.0)           # avoid log(0)
+    H = -(p * np.log(p)).sum(axis=-1)
+    if neff:
+        return np.exp(H.sum())
+    elif pos:
+        return np.exp(H)
+    elif leff:
+        return H.sum()/np.log(k)
+    else:
+        return np.exp(H.mean())
+
+
+def neff_seq(X: np.ndarray, thres: float = 0.8, wei: bool = False):
+    N, L, k = X.shape
+    X = X.reshape(N, -1)
+    C = X @ X.T / L
+
+    S = (C > thres).astype(float)    # similarity matrix
+    counts = S.sum(axis=1)
+
+    w = 1.0 / counts
+
+    if wei:
+        return w / w.sum()           # normalized weights
+    else:
+        return w.sum()               # effective number of sequences
+
+
+def helmert_basis(k: int) -> np.ndarray:
+    # k x (k-1), columns span {v : 1^T v = 0}, columns orthonormal
+    H = np.zeros((k, k-1), float)
+    for j in range(k-1):
+        H[:j+1, j] = 1.0
+        H[j+1, j] = -(j+1)
+        H[:j+2, j] /= np.sqrt((j+1)*(j+2))
+    return H
+
+
+def to_zero_sum(X: np.ndarray, L: int, k: int) -> np.ndarray:
+    # X: N x (kL) one-hot, L positions, k symbols
+    Q = helmert_basis(k)                 # k x (k-1)
+    T = np.kron(np.eye(L), Q)            # (kL) x (L*(k-1))
+    return X @ T                         # N x L*(k-1)
+
+
+def weighted_covariance(Z, w):
+    # Z: N×M,  w: N, sum(w)=1
+    Zt = Z * np.sqrt(w[:, None])          # weighted data: diag(√w) Z
+    mu = (w @ Z)                 # μ_w ∈ ℝ^{M×1}
+    C  = Zt.T @ Zt - np.outer(mu, mu)          # Zᵀ diag(w) Z − μ_w μ_wᵀ
+    return C, mu, Zt
+
+
+def get_center_data(X, w):
+    mu = w @ X                        # (M,)
+    Zx = X - mu                       # center
+    Zw = np.sqrt(w)[:, None] * Zx     # sqrt(W) Zc
+    return Zw
+
+
+def effective_length(
+    Z, w=None, tol=1e-12, signal_frac=None,
+    zs=True, neff=False, reg=0., svd=True
+):
+    """
+    Estimate the effective dimensional length of a dataset via the entropy of
+    its variance spectrum.
+
+    Parameters
+    ----------
+    Z : array_like, shape (N, L, k)
+        Input tensor of N samples with L positions and k features per position.
+    w : array_like, optional
+        Sample weights of length N. If None, uniform weights are used.
+    tol : float, optional
+        Absolute numerical eigenvalue threshold. Components below this value
+        are discarded before any signal-fraction truncation.
+    signal_frac : float or None, optional
+        Fraction of total retained variance to preserve. If in (0, 1], the
+        spectrum is sorted in decreasing order and truncated to the smallest
+        number of components whose cumulative variance is at least
+        `signal_frac`. For example, `signal_frac=0.99` retains components
+        explaining 99% of the variance.
+    zs : bool, optional
+        If True, apply zero-sum mean-removal constraint across features.
+    neff : bool, optional
+        If True, return a support estimate of the sequence space spanned by
+        the MSA.
+    reg : float, optional
+        Diagonal regularization added to covariance in eigenvalue mode.
+    svd : bool, optional
+        If True, or when N < 5M, use SVD of centered data; otherwise use
+        weighted covariance eigenvalues.
+
+    Returns
+    -------
+    float
+        Entropy-based effective rank of the feature space, optionally scaled
+        to an effective alphabet-size support when `neff=True`.
+
+    Notes
+    -----
+    The method computes the Shannon entropy of normalized singular values or
+    covariance eigenvalues and converts it to an effective dimension called
+    `L_eff`.
+    """
+    N, L, k = Z.shape
+    Z = Z.reshape(N, -1)
+
+    if zs:
+        Z = to_zero_sum(Z, L, k)
+
+    N, M = Z.shape
+
+    if w is None:
+        w = np.ones(N) / N
+
+    if svd or N < 5 * M:
+        Zw = get_center_data(Z, w)
+        vals = np.linalg.svd(Zw, full_matrices=False, compute_uv=False)
+        vals = (vals ** 2) / Zw.shape[0]
+    else:
+        C, mu, Zt = weighted_covariance(Z, w)
+        vals = np.linalg.eigvalsh((C + C.T) / 2.0 + reg * np.eye(M))
+
+    vals = vals[vals > tol]
+
+    if vals.size == 0:
+        return 0.0
+
+    vals = np.sort(vals)[::-1]
+
+    if signal_frac is not None:
+        if not (0.0 < signal_frac <= 1.0):
+            raise ValueError("signal_frac must be in (0, 1].")
+
+        frac = np.cumsum(vals) / np.sum(vals)
+        n_keep = np.searchsorted(frac, signal_frac) + 1
+        vals = vals[:n_keep]
+
+    p = vals / vals.sum()
+    H = -np.sum(p * np.log(p))
+
+    denom = k - 1 if zs else k
+    Leff = np.exp(H) / denom
+
+    if neff:
+        return k ** Leff
+    return float(Leff)
+
+
+def spectral_entropy(C, tol=1e-12):
+    lam_full, U_full = np.linalg.eigh(C)  # M eigenvalues, M×M eigenvectors
+    mask = lam_full > tol
+    lam = lam_full[mask]                  # r
+    U   = U_full[:, mask]                 # M×r
+
+    S = lam.sum()
+    p = lam / S
+    H = -np.sum(p * np.log(p))
+    return H, lam, U
+
+
+def cross_effective_length(X, Y, wx=None, wy=None, tol=1e-12, zs=True, alpha=1.):
+    """
+    Cross isotropy between two *independent* sample sets.
+    X: (Nx, Lx, k)
+    Y: (Ny, Ly, k)
+    """
+
+    Nx, Lx, k = X.shape
+    Ny, Ly, k = Y.shape
+
+    X = to_zero_sum(X.reshape(Nx, -1), Lx, k) if zs else X
+    Y = to_zero_sum(Y.reshape(Ny, -1), Ly, k) if zs else Y
+
+    if wx is None: wx = np.ones(Nx) / Nx
+    if wy is None: wy = np.ones(Ny) / Ny
+    wx = wx / wx.sum()
+    wy = wy / wy.sum()
+
+    Xc, Yc = get_center_data(X, wx), get_center_data(Y, wy)
+    # independent cross moment
+    Cxy = Xc @ Yc.T
+
+    # singular spectrum
+    s = np.linalg.svd(Cxy, compute_uv=False)
+    s = s[s > tol]
+    if s.size == 0:
+        return 0.0
+
+    p = s / s.sum()
+
+    if alpha == 1:
+        H = -np.sum(p * np.log(p))
+        eff_rank = np.exp(H)
+    else:
+        eff_rank = np.sum(p**alpha) ** (1.0 / (1.0 - alpha))
+
+    return float(eff_rank / (k - 1))
+
+
+def average_min_dist(Y, X):
+    if len(X.shape) == 3:
+        Xf, Yf = X.reshape(len(X), -1), Y.reshape(len(Y), -1)
+    else:
+        Xf, Yf = X, Y
+
+    XY = Xf @ Yf.T
+    XX = Xf @ Xf.T
+    np.fill_diagonal(XX, 0)
+    return (XY.max(1)[XX.max(1)>0] / XX.max(1)[XX.max(1)>0]).mean()
+
+
+def leff(msa: list, seq_type: str, **kwargs) -> float:
+    return effective_length(msa_to_oh(msa, seq_type=seq_type), **kwargs)
+
+
+def cross_leff(msa_x: list, msa_y: list, seq_type: str, **kwargs) -> float:
+    return cross_effective_length(msa_to_oh(msa_x, seq_type=seq_type), msa_to_oh(msa_y, seq_type=seq_type), **kwargs)
+

eff_len/utils.py

@@ -0,0 +1,93 @@
+"""
+"""
+
+import numpy as np
+import re
+
+# alphabets
+NUC = {'-': 0, 'A': 1, 'U': 2, 'C': 3, 'G': 4}
+INDEX_TO_NUC = {v: k for k, v in NUC.items()}
+
+AA = {'-': 0, 'A': 1, 'R': 2, 'N': 3, 'D': 4, 'C': 5, 'Q': 6, 'E': 7, 'G': 8,
+      'H': 9, 'I': 10, 'L': 11, 'K': 12, 'M': 13, 'F': 14, 'P': 15, 'S': 16,
+      'T': 17, 'W': 18, 'Y': 19, 'V': 20}
+INDEX_TO_AA = {v: k for k, v in AA.items()}
+
+
+def hamming_distance(s1, s2):
+    return sum(a != b for a, b in zip(s1, s2))
+
+
+def seq_to_indices(sequence, seq_type="nuc"):
+    if seq_type == "nuc":
+        alphabet = NUC
+    elif seq_type == "prot":
+        alphabet = AA
+    else:
+        raise ValueError("seq_type must be 'nuc' or 'prot'")
+    return np.array([alphabet[x] for x in sequence], dtype=int)
+
+
+def get_one_hot(data, num_classes):
+    N, L = data.shape
+    oh = np.zeros((N, L, num_classes), dtype=float)
+    oh[np.arange(N)[:, None], np.arange(L), data] = 1.0
+    return oh
+
+
+def read_fasta(infile, seq_type="prot"):
+    results = {}
+    with open(infile, 'r') as f:
+        name = None
+        for l in f:
+            l = l.strip()
+            if l.startswith(">"):
+                name = l[1:]
+                results[name] = ""
+            elif name:
+                if seq_type == "nuc":
+                    cleaned = re.sub(r'[^ACGUT]', '-', l.upper()).replace("T", "U")
+                elif seq_type == "prot":
+                    cleaned = re.sub(r'[^ACDEFGHIKLMNPQRSTVWY]', '-', l.upper())
+                else:
+                    cleaned = l.upper()
+                results[name] += cleaned
+    return results
+
+
+def msa_to_oh(msa, seq_type="nuc"):
+    if seq_type == "nuc":
+        k = len(NUC)       # 5
+    elif seq_type == "prot":
+        k = len(AA)        # 21
+    else:
+        raise ValueError("seq_type must be 'nuc' or 'prot'")
+
+    if isinstance(msa, dict):
+        msa_l = [seq_to_indices(seq, seq_type) for seq in msa.values()]
+    else:
+        msa_l = [seq_to_indices(seq, seq_type) for seq in msa]
+    msa_arr = np.stack(msa_l)              # (N, L)
+    return get_one_hot(msa_arr, num_classes=k)  # (N, L, k)
+
+
+def oh_to_msa(msa_oh, seq_type="nuc"):
+    if seq_type == "nuc":
+        idx_to_sym = INDEX_TO_NUC
+    elif seq_type == "prot":
+        idx_to_sym = INDEX_TO_AA
+    else:
+        raise ValueError("seq_type must be 'nuc' or 'prot'")
+
+    idxs = np.argmax(msa_oh, axis=-1)     # (N, L)
+    return [''.join(idx_to_sym[i] for i in row) for row in idxs]
+
+
+def msa_to_ind(msa, seq_type="nuc"):
+    if type(msa) is dict:
+        msa = msa.values()
+    return np.stack([seq_to_indices(seq, seq_type) for seq in msa])
+
+
+def ind_to_msa(ind_array):
+    return ["".join(INDEX_TO_NUC[i] for i in row) for row in ind_array]

eff_len-0.1.0.dist-info/METADATA

@@ -0,0 +1,91 @@
+Metadata-Version: 2.5
+Name: eff-len
+Version: 0.1.0
+Summary: Spectral measure of diversity for multiple sequence alignments
+Project-URL: Homepage, https://github.com/vaiteaopuu/effective_length
+Project-URL: Issues, https://github.com/vaiteaopuu/effective_length/issues
+Author-email: Vaitea Opuu <vaitea.opuu@cnrs.fr>
+License-Expression: MIT
+Keywords: bioinformatics,diversity,msa,sequence-alignment
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Requires-Dist: numpy
+Description-Content-Type: text/markdown
+
+# eff_len
+
+Spectral measure of diversity for multiple sequence alignments.
+
+## Overview
+
+This repo contains the code to reproduce the results in *"A spectral framework for measuring diversity in multiple sequence alignments"*. It introduces a measure, `L_eff`, that estimates the diversity (or amount of information) contained in a multiple sequence alignment. `L_eff` allows a faithful comparison between MSAs, as well as between generated datasets.
+
+## Install
+
+Requirements: NumPy.
+
+```bash
+pip install eff_len
+```
+
+From source:
+
+```bash
+git clone https://github.com/vaiteaopuu/effective_length
+cd effective_length
+pip install .
+```
+
+## Usage
+
+### Python
+
+```python
+from eff_len import read_fasta, msa_to_oh, effective_length
+
+msa = read_fasta("data/RF00028.fa", seq_type="nuc")
+
+msa_oh = msa_to_oh(msa, seq_type="nuc")
+N, L, k = msa_oh.shape
+L_eff = effective_length(msa_oh)
+
+print(N, L, L_eff, L_eff / L)
+# 2611 251 35.88477058938092 0.14296721350350963
+```
+
+`cross_effective_length` and `leff` are also exported, for comparing two alignments and for the convenience wrapper respectively.
+
+## Repository content
+
+| Path | Description |
+| --- | --- |
+| `src/eff_len/` | The package itself |
+| `analysis/` | Notebooks and scripts |
+| `data/` | Example alignments |
+| `reproducibility.org` | Code snippets reproducing the figures in the paper |
+
+## Data sources
+
+The data used in these analyses were extracted from:
+
+- C. Lambert *et al.* (2025) *Nat. Commun.*
+- F. Calvanese *et al.* (2024) *NAR*
+- M. Mirdita *et al.* (2027) *NAR*
+
+## Citation
+
+If you use this code, please cite:
+
+```bibtex
+@article{opuu_spectral,
+  title   = {A spectral framework for measuring diversity in multiple sequence alignments},
+  author  = {Opuu, Vaitea},
+  year    = {2026}
+}
+```
+
+## License
+
+MIT

eff_len-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+eff_len/__init__.py,sha256=qqpx4c0Vgdu_7ScKZHgWVmk-kFXI6OscP6u_vwKQZl0,40
+eff_len/div.py,sha256=-dpj75TqvG360XODJKPiV6W7U2MRzIIFo87ztGgyZmY,7642
+eff_len/utils.py,sha256=FN81ScLplmNptDItm7et36jaEKRyKrWUSr1SBC5d6f4,2703
+eff_len-0.1.0.dist-info/METADATA,sha256=_LjcQH53z9I4HHZIdXZ31Dgmp4GtDNcYg69vFw7nQpA,2425
+eff_len-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+eff_len-0.1.0.dist-info/RECORD,,

eff_len-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any