tyssue

What it simulates

tyssue is a Python library for mechanical models of epithelia. Its main focus is vertex models. A vertex model draws a sheet of cells as polygons that share corners (vertices). Each cell has an area, a perimeter and edges. An energy function sums the mechanical terms. The solver moves the vertices to lower that energy.

The example builds a flat sheet from a 6 by 6 grid, trims the border cells, and gets 20 cells with 38 vertices and 100 half-edges. It then applies three energy terms and relaxes the sheet to a local energy minimum:

• Line tension on every edge, with random noise on each edge.
• Perimeter contractility per cell.
• Area elasticity, which pulls each cell toward a preferred area.

The key assumption is that the tissue is a 2D sheet at the apical surface, in a quasi-static state. The solver finds an energy minimum. It does not follow time. The result is the shape of the sheet at that minimum.

When to use it

Use tyssue to ask how cell-level mechanics set tissue shape:

• How do tension and contractility change cell area and the number of sides?
• Where does the sheet settle for a given set of parameters?
• Which cells shrink first when a few edges are stiffer?

On biosimhub, pyafv models cells as active Voronoi cells that can detach and move, which fits migrating or fragmenting tissue. Artistoo fits cells that deform and crawl on a pixel grid. tyssue fits a fixed network of polygons with a defined energy.

Install it yourself

The conda-forge package is tyssue. The dry run micromamba create -n t --dry-run -c conda-forge -c bioconda tyssue=0.9.0 resolves tyssue 0.9.0 with Python 3.9.23.

conda create -n tyssue -c conda-forge python=3.9 "numpy<2" "pandas<2" scipy matplotlib-base pytables quantities
conda activate tyssue
conda install -c conda-forge --no-deps tyssue=0.9.0

The recipe's image pins numpy<2 and pandas<2. tyssue 0.9.0 still calls DataFrame.append, which pandas marks as deprecated. The minimal script below is the recipe's helper script without the CSV and plot code. It uses tyssue's own API:

from tyssue import Sheet
from tyssue.dynamics import effectors, model_factory
from tyssue.geometry.sheet_geometry import SheetGeometry as geom
from tyssue.solvers.quasistatic import QSSolver

sheet = Sheet.planar_sheet_3d("epithelium", nx=6, ny=6, distx=1.0, disty=1.0)
sheet.sanitize(trim_borders=True, order_edges=True)
geom.update_all(sheet)
sheet.update_specs({
    "edge": {"is_active": 1, "line_tension": 0.12},
    "face": {"is_alive": 1, "contractility": 0.04, "prefered_area": 1.0,
             "area_elasticity": 1.0, "prefered_vol": 1.0, "vol_elasticity": 0.0},
    "vert": {"is_active": 1},
}, reset=True)
geom.update_all(sheet)
model = model_factory([effectors.LineTension, effectors.FaceContractility,
                       effectors.FaceAreaElasticity])
res = QSSolver().find_energy_min(sheet, geom, model)

Reading the output

The recipe's helper script run_tyssue.py wraps the script above. It adds noise to the edge tensions (line_tension *= 1 + noise * N(0,1), clipped to plus or minus 2), then writes files and a picture.

The log (tyssue_log.txt, 184 bytes) has three result lines. 20 cells, 38 vertices, 100 half-edges is the sheet. energy 10.08372 -> 8.92660, solver success: True is the energy before and after the relaxation. mean area 0.7812 -> 0.5042; sd 0.2769 -> 0.1275 is the cell area. The mean area is below the preferred area of 1 because line tension and contractility pull cells smaller. The spread of areas halves. The first log line, C++ extension are not available for this version, is a warning from the conda build.

faces.csv (2177 bytes) has one row per cell with x,y,z,num_sides,area,perimeter and the area_before and perimeter_before columns. Cell 0 has 4 sides and went from area 0.5 to 0.397. Cell 1 has 5 sides and went from 0.875 to 0.570. vertices.csv (1673 bytes) holds the 38 vertex positions, and tissue.png colors each polygon by area.

Your own runs

Copy the docker run line from the recipe and change values.

1. No noise. Set --tension_noise 0. The energy went from 10.15994 to 9.00786. The mean area ended at 0.5014 and the standard deviation at 0.1203. Less variation in the starting tension gave a slightly lower spread of areas.
2. Stronger tension. Set --line_tension 0.5. The energy went from 22.93773 to 10.04602 and the solver still reported success. Mean area and its standard deviation both printed 0.0000. The cells collapsed.
3. Bigger sheet. Set --nx 10 --ny 10. The log reads 72 cells, 142 vertices, 396 half-edges and energy 36.22168 -> 31.07401. The mean area went from 0.8976 to 0.5393. The recipe accepts 3 to 16 cells per side.

Pitfalls

• Solver success can hide collapsed cells. The line tension 0.5 run reported solver success: True with zero-area cells. Check area in faces.csv.
• The final area differs from the preferred area. With the defaults, the mean area ended at 0.50 against a preferred 1.0. Raise --prefered_area or lower the tension to move it back. The parameter name is spelled prefered_area, as in tyssue.
• Border cells are removed. A 6 by 6 grid gives 20 cells. Count cells in faces.csv.
• The seed drives only the noise. In the helper it sets the random edge tensions. Compare runs at one seed.
• pandas version. The recipe's image pins pandas<2. The log prints FutureWarning lines about DataFrame.append and level= arguments from tyssue 0.9.0. Keep the pins from the install section.

Further reading

• Documentation: https://tyssue.readthedocs.io/en/latest/
• Source and README: https://github.com/DamCB/tyssue
• Theis S, Suzanne M, Gay G (2021). Tyssue, an epithelium simulation library. J Open Source Softw 6(62):2973. https://doi.org/10.21105/joss.02973