Skip to content
ngodzikPublic

About

Cells, oxygen and proteins simulated together: tissues that grow, starve, mutate, call for blood and meet immune cells, set against public data. Experimental (0.x), with a course.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

cellweave

CI Security Release

A tissue that grows, starves, mutates, calls for blood and is hunted by immune cells, simulated cell by cell from a hypothesis written in a file, and set against real measurements.

A spheroid growing in a volume from a ball of cells, cut open through the middle: a thin rim of dividing cells, arrested cells beneath it, and a dead core that breaks down, until it stops

Status: experimental, version 0.x. cellweave is a research and teaching tool in early development, and anything in it may change from one version to the next. What it produces are hypotheses worth testing, not facts about real tumours. It gets better through feedback from people who know the biology or the modelling: a mechanism that is wrong or too simple, public data it should be set against, a value that should be different. If that is you, please open a scientific feedback issue. Every comment is read.

What it does

Every cell is a set of pixels with a shape, pressing on its neighbours. Inside each one runs a network of proteins, written in a plain file, that decides whether it grows, waits, divides, leaves or dies. Around the cells, oxygen and signals diffuse, taken up and released wherever the cells are. Nothing in the code says what shape the tissue takes: it follows from those three scales acting on each other, and changing the hypothesis is changing the file.

White immune cells arriving through the vessel at the centre of a tumour cord and killing the tumour cells around it A renewing layer of cells, each clone a colour, the clones coarsening as some are lost and mutants spread
Killers that come for the tumour. Immune cells arrive through the vessel, follow the trail the tumour cells leave, and kill the cells they touch, at measured rates. Chapter 22 A normal tissue that ages. A renewing layer in which every cell starts a clone of its own; clones are lost by chance, mutants compete for room, and the layer keeps its size. Chapter 7
A tumour growing against a capillary: a new vessel sprouts from it and branches into the tissue, the cells around it dividing and those far from it arrested A tumour cord whose cells mutate, each new clone a colour, one line escaping and taking over
Vessels that grow. Starving cells call for vessels, and a sprout climbs the call, branching into the tissue; with flow switched on, blood then goes where pressure drives it. Chapter 14, 19 A tumour that evolves. A daughter is not always a copy: each mutation founds a clone, nothing says which is good, and selection finds the ones that grow. Chapter 6

The animations are sped up: a few seconds stand for days to months of a tissue's life. Each says in its corner what its colours mean.

Also in it: the spheroid at the top, grown in a volume, which stops near the size measured spheroids stop at once the medium of its well is still (chapter 27), the same spheroid in the plane (chapter 25), a lethal stress and the resistance it selects, rewinding a history to see what one mutation changed, and campaigns that run many histories side by side.

Set against real data

The values below are fixed by public measurements, and every comparison is in the course with the prediction written before it ran, the ones that failed included; what no public data fixes yet is listed in its last chapter. The data are never copied here: each dataset is a recipe saying where its authors published it, and scripts/fetch-dataset.py downloads it to your machine.

A spheroid growing from one cell, turning in relief: a rim of dividing cells around arrested ones, and a dead core forming where oxygen runs out

what public data how close
a tumour's oxygen 994 melanoma spheroids (Browning 2021) one number fitted; arrest then starts where the spheroids' does; their late cycling rim is thinner
a spheroid's end, in a volume the same spheroids; oxygen's diffusion in tissue (Grote 1977) and in culture medium (Place 2017) stops at 368 µm against 348, one number set inside the bracket the two diffusions leave; its core grows with size half as much as theirs
cords of tissue around a vessel Tannock 1968 69 µm against 60 to 120, nothing fitted
immune killing Weigelin 2021, Halle 2016 set on the measured rates
clones in a normal tissue 1,222 clones of the mouse oesophagus (Piedrafita 2020) a third too large at a month, five times at six: a mechanism is missing

Try it

Download the command line for Linux, macOS or Windows from the releases, or build it with Rust 1.97 or newer:

git clone https://github.com/ngodzik/cellweave && cd cellweave
cargo build --release

# a tumour cord around a vessel; numbers per step in output-cord/measurements.csv
./target/release/cellweave --config examples/cord.toml --mcs 1000

# ten histories of the same tumour, with and without immune cells, compared pair by pair
./target/release/cellweave --config examples/cord-wide.toml --versus examples/cord-immune.toml --seeds 1-10 --mcs 1000

Every scenario is a file in examples/, and every chapter of the course says which file and which command give its results.

Watching it

The viewer draws a run live, in relief, from the same simulation and the same seed. It is a workspace of its own, so the simulator never needs anything graphical; on Linux it needs libwayland-dev and libxkbcommon-dev.

cd viewer
cargo run --release -- --config ../examples/cord-angiogenic.toml
cargo run --release -- --config ../examples/capillary-delivery.toml --view flow
cargo run --release -- --config ../examples/epithelium-mutating.toml --view clone

Space pauses, N takes one step, R restarts, H flattens the relief, A turns the camera, the mouse turns and zooms it. The panel colours the cells by fate, protein, oxygen, stress, the call for vessels, clone or blood flow, and plots the population as it goes.

A click on a cell opens it. A window draws the cell's network as it stands, every protein at its level and every link as thick as it is pushing, says in words what the cell does with them and why, and colours the tissue by any protein clicked. spheroid-fuller.toml is the calibrated spheroid with a fuller cell: eighteen proteins, from the growth factor's receptor through RAF and MEK to the cell cycle, and from damage through p53, MDM2, p21 and BAX to apoptosis, tuned to decide where the simpler network does (chapter 28). This opens the cell at its centre at step 300 and follows it as it is arrested and starved:

cargo run --release -- --config ../examples/spheroid-fuller.toml --open 400,400 --open-at 300 --follow --zoom 3

--record <dir> saves every step as an image, taken from what the viewer draws rather than from the screen, and --until <step> stops there; with --no-panel, --spin and --batch <steps>, that is how the animations above were made:

cargo run --release -- --config ../examples/cord-immune.toml --no-panel --batch 3 --record frames --until 1000
ffmpeg -framerate 30 -pattern_type glob -i 'frames/*.png' run.mp4

Learn how it works

The course explains the program from the biology up, in 29 chapters, each answering one question: what a thing is in the body, what cellweave makes of it, which choices were made and why, where in the code it lives, and what is still a placeholder. It is kept in step with the code, and its last chapter lists what the model does not say.

Under the hood

Rust, in four crates whose dependency graph enforces the layering: cellweave-core (types, no I/O, no computation), cellweave-engine (the lattice, the networks, the fields, the loop), cellweave-io (configuration and output) and the command line; the viewer sits on top in a workspace of its own. The same seed gives the same run, byte for byte, on any machine and any number of threads, and the CI checks it on every push, with fmt, clippy, docs, 223 tests green on Linux, macOS and Windows, the oldest supported Rust, and cargo-deny.

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace

Contributing, data, citing

CONTRIBUTING.md says how, and how to contribute a calibration. The repository holds no data of anyone else's and never any about a person. To cite cellweave, use CITATION.cff (GitHub's "Cite this repository"), with the version you used.

Who is behind it

A personal project. I am a software engineer, not a biologist, and I started cellweave to learn multiscale modelling by building it. I write it with AI assistance, and I review and own everything in it, mistakes included. Mature, validated tools exist for this kind of work, among them PhysiCell, CompuCell3D, Morpheus and Chaste; cellweave overlaps with them by design.

License

MIT. See LICENSE.

About

Cells, oxygen and proteins simulated together: tissues that grow, starve, mutate, call for blood and meet immune cells, set against public data. Experimental (0.x), with a course.

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages