pigmentation-boolean-sim

A sign-aware Boolean network simulator for the UV-mediated human skin-pigmentation signalling network curated by Raghunath et al. (2015), BMC Research Notes.

The repository ships two things that share the same model and update logic:

1. pigsim — a small Python package implementing the Boolean engine (deterministic synchronous or stochastic asynchronous update, attractor detection, knockout/forced-node perturbation, phenotype readout).
2. web/simulator.html — a self-contained interactive browser tool (D3 force-directed graph) for clicking nodes on/off, knocking them out, and watching the network propagate to a steady state.

Scope note. This is a faithful Boolean re-implementation of a 2015 signalling network. It is a research scaffold and teaching tool, not a validated genotype-to-phenotype predictor. The network's documented limitations (see docs/FINDINGS.md) are part of the point: they motivate a multi-layer extension that incorporates melanosome biochemistry, trafficking, and regulatory variation.

---

Quick start

# 1. install dependencies (Python 3.10+)
pip install -r requirements.txt

# 2. (optional) regenerate the processed network from the raw supplementary files
python scripts/build_network.py

# 3. run the test suite
PYTHONPATH=src pytest -q

# 4. run an example analysis
PYTHONPATH=src python scripts/knockout_screen.py

To use the browser tool, just open web/simulator.html in any modern browser (no server or build step required).

---

Using the Python API

from pigsim import BooleanNetwork

net = BooleanNetwork.from_json("data/processed/network.json")

# Apply a UVB stimulus and run to steady state
result = net.simulate(inputs={"UVB": 1})
print(result.attractor)          # 'fixed point'
print(result.phenotypes())       # {'Eumelanin_melan': 1, ...}

# Knock out tyrosinase and see which phenotype readouts change
print(net.knockout_effect("TYR_melan", inputs={"UVB": 1}))
# {'Pheomelanin_melan': (1, 0)}   <- note: Eumelanin is unchanged (redundancy)

# Force a node ON instead of off, run asynchronously
net.simulate(inputs={"UVB": 1}, forced={"MITF_melan"}, async_update=True, seed=0)

---

The update rule

For each node that is not clamped (knocked out / forced):

score = (number of ON activators) − (number of ON inhibitors)
score > 0  → ON
score < 0  → OFF
score == 0 → hold previous state

Complex-formation edges count as activating. Source nodes with no incoming edges hold whatever value the caller sets. The browser tool implements the identical rule, so the two stay in agreement.

---

Repository layout

pigmentation-boolean-sim/
├── data/
│   ├── raw/           # Raghunath 2015 supplementary spreadsheets (source of truth)
│   └── processed/     # network.json (regenerable via scripts/build_network.py)
├── src/pigsim/        # the Boolean engine (importable package)
├── scripts/           # build + example analyses
├── web/               # standalone interactive simulator (open in browser)
├── tests/             # pytest suite (network integrity + known behaviours)
└── docs/              # findings, model card, data provenance

See docs/ for the data provenance, the documented findings, and the model's known limitations.

---

Citing

If you use this tool, please cite the underlying network:

Raghunath A, Sambarey A, Sharma N, Mahadevan U, Chandra N. A molecular systems approach to modelling human skin pigmentation: identifying underlying pathways and critical components. BMC Research Notes. 2015;8:170. doi:10.1186/s13104-015-1128-6

The Raghunath supplementary data are distributed under CC BY 4.0; the original article is open access. See data/raw/README.md.

License

Code in this repository is released under the MIT License (see LICENSE). The bundled raw data retains its original CC BY 4.0 license.