tmc-pbp

Pseudo-Boolean Polynomial (PBP) decomposition for data analysis. Training-free, deterministic algebraic decomposition of data matrices into multilinear polynomials over binary variables.

What it does

Given a data matrix (rows = variables, columns = observations), PBP decomposes it into a multilinear polynomial where each term represents a specific combination of variables and its coefficient quantifies the interaction strength. The decomposition is:

• Training-free -- no learned parameters, no optimization
• Deterministic -- same input always produces the same output
• Fast -- sub-millisecond per sample, 15K genes in 1.7 seconds
• Interpretable -- each coefficient names a specific variable interaction
• Mathematically equivalent to the Walsh-Hadamard spectral transform

Install

pip install tmc-pbp            # core (numpy, pandas, scipy, bitarray, scikit-learn)
pip install "tmc-pbp[all]"     # plus matplotlib, OpenCV, Pillow and Flask for the viz, image and server modules

The package is imported as pbp. A pure-Python core is always available (pbp.core). The optional C backend (pbp.core_c) is shipped as source; compile it once in the installed package directory to enable it:

bash "$(python -c 'import pbp, os; print(os.path.dirname(pbp.__file__))')/build_pbp.sh"

Quick start

Python API

from pbp.core import create_pbp, pbp_vector

import numpy as np
matrix = np.array([
    [5.2, 4.8, 3.1, 2.0],  # Gene A
    [3.0, 3.5, 4.2, 4.8],  # Gene B
    [1.0, 1.5, 2.8, 4.5],  # Gene C
])

# Full decomposition -> DataFrame with (y, coeffs, degree)
pbp = create_pbp(matrix)

# Fixed-length vector representation (2^m - 1 elements)
vec = pbp_vector(matrix)

CLI

pbp analyze matrix.csv --output results/   # Full decomposition + energy profile
pbp vector matrix.csv                       # Fixed-length PBP vector
pbp hasse matrix.csv --format dot           # Hasse diagram (Graphviz DOT)
pbp info matrix.csv                         # Matrix stats
pbp version                                 # Package version

Web application

bash pbp/webapp/run.sh
# Open http://localhost:8430

6-tab interface covering decomposition, epistasis, quorum sensing, sequential inference, structural comparison, and anomaly detection. 25 API endpoints. OpenAPI docs at /docs.

Modules

Applications

Genetic epistasis (Perturb-seq)

PBP spectral profiles characterize interaction structure in combinatorial perturbation screens. Degree-wise energy separates interaction type from magnitude. Validated on 4 datasets from 4 labs (Norman, Wessels, Dixit, Joung).

from pbp.pertpy_integration import pbp_score, pbp_classify_type
scores = pbp_score(adata, groupby='perturbation', reference='control')

Quorum sensing signal integration

Decompose factorial QS experiments into main effects (a1, a2) and interaction (a12) per gene. Gate classification: AND, OR, antagonistic, mixed.

Sequential inference

Predict activation order from expression matrices using greedy sampling through the PBP Hasse diagram.

from pbp.inference import pbp_dag_sample
result = pbp_dag_sample(pbp_df, m, mode='greedy')
print(result['sequence'])  # Predicted activation order

Anomaly detection

PBP total energy flags samples with disrupted interaction structure. Interpretable: identifies which specific interactions are affected.

Structural comparison

Pairwise Hasse diagram distance compares interaction architectures across samples, conditions, or organisms.

Key functions

Mathematical identity

PBP decomposition is mathematically identical to:

• Walsh-Hadamard spectral transform (Fourier analysis on {0,1}^m)
• Epistatic interaction coefficients (Poelwijk et al. 2019)
• Multilinear extension of pseudo-Boolean functions (Hammer & Rudeanu 1968, Boros & Hammer 2002)

Citation

@article{chikake2025compoptics,
  author  = {Chikake, Tendai M. and Goldengorin, Boris I. and Pardalos, Panos M.},
  title   = {Pseudo-Boolean Polynomial Approach to Solving Computer Vision Tasks},
  journal = {Computer Optics},
  volume  = {49},
  number  = {6},
  pages   = {1191--1201},
  year    = {2025},
  doi     = {10.18287/COJ1815},
}

License

MIT