# Core objects¶

## The Epithelium object¶

class tyssue.Epithelium(identifier, datasets, specs=None, coords=None, maxbackup=5)[source]

Base class defining a connective tissue in 2D or 3D.

Creates an epithelium

Parameters
• identifier (string) –

• datasets (dictionary of dataframes) –

The keys correspond to the different geometrical elements constituting the epithelium:

• vert contains a dataframe of vertices,

• edge contains a dataframe of oriented half-edges between vertices,

• face contains a dataframe of polygonal faces enclosed by half-edges,

• cell contains a dataframe of polyhedral cells delimited by faces,

• specs (nested dictionnary of specifications) –

The first key designs the element name: (vert, edge, face, cell), corresponding to the respective dataframes attribute in the dataset. The second level keys design column names of the above dataframes. For exemple: .. code:

specs = {
"face": {
## Face Geometry
"perimeter": 0.,
"area": 0.,
## Coordinates
"x": 0.,
"y": 0.,
"z": 0.,
## Topology
"num_sides": 6,
"is_alive": 1},
"vert": {
## Coordinates
"x": 0.,
"y": 0.,
"z": 0.,
"is_active": 1},
"edge": {
## Connections
"srce": 0,
"trgt": 1,
"face": 0,
"cell": 0,
## Coordinates
"dx": 0.,
"dy": 0.,
"dz": 0.,
"length": 0.,
## Normals
"nx": 0.,
"ny": 0.,
"nz": 1.}
"settings":
## Custom values
"geometry": "flat"
}


Note

For efficiency reasons, we have to maintain a monotonous RangeIndex for each dataset. Thus, the index of an element can change, and should not be used as an identifier.

property Nc

The number of cells in the epithelium

property Ne

The number of edges in the epithelium

property Nf

The number of faces in the epithelium

property Nv

The number of vertices in the epithelium

backup()[source]

Creates a copy of self and keeps a reference to it in the self._backups deque.

property cell_df

The cell pd.DataFrame containing cell associated data e.g. the position of their center or their volume

copy(deep_copy=True)[source]

Returns a copy of the epithelium

Parameters

deep_copy (bool, default True) – if True, use a copy of the original object’s datasets to create the new object. If False, datasets are not copied

cut_out(bbox, coords=None)[source]

Returns the index of edges with at least one vertex outside of the bounding box

Parameters
• bbox (sequence of shape (dim, 2)) – the bounding box as (min, max) pairs for each coordinates.

• coords (list of str of len dim, default None) – the coords corresponding to the bbox.

property edge_df

The edge pd.DataFrame containing edge associated data e.g. their length.This dataframe also contains the whole connexion of the epithelium through the “srce”, “trgt”, “face”, “cell” indices. In 2D, a half-edge is associated with a single (face, srce, trgt) positively oriented triangle. In 3D, the (cell, face, srce, trgt) positively oriented terahedron is also unique.

property face_df

The face pd.DataFrame containing face associated data e.g. the position of their center or their area

face_polygons(coords=None)[source]

Returns a pd.Series of arrays with the coordinates the face polygons

Each element of the Series is a (num_sides, num_dims) array of points ordered counterclockwise.

Note

Vertices are assumed to be ordered in a face. If you are not sure it is the case, you can run sheet.reset_index(order=True) before calling this function.

get_invalid()[source]

Returns a mask over self.edge_df for invalid faces

get_neighborhood(elem_id, order, elem='cell')[source]

Returns elem_id neighborhood up to a degree of order

For example, if order is 2, it wil return the adjacent cells (or faces) and theses cells neighbors.

Returns

neighbors – of the neighboring cell (face), and it’s neighboring order

Return type

pd.DataFrame with two colums, the index

get_neighbors(elem_id, elem='cell')[source]

Returns the indexes of the adjacent elements (cells or faces) of the element of index elem_id.

Parameters
• elem_id (int) – the index of the central element (a face or a cell)

• element ({'cell' | 'face'}, default 'cell') –

Returns

neghbors – the cells (or faces) sharing an edge with the central cell (face)

Return type

set

get_opposite_faces()[source]

Populates the ‘opposite’ column of self.face_df with the index of the opposite face or -1 if the face has no opposite.

get_orbits(center, periph)[source]

Returns a dataframe with a (center, edge) MultiIndex with periph elements.

Parameters
• center (str,) – the name of the center element for example ‘face’, ‘srce’

• periph (str,) – the name of the periphery elements, for example ‘trgt’, ‘cell’

Example

>>> cell_verts = sheet.get_orbits('face', 'srce')
>>> cell_verts.loc[45]
edge
218    75
219    78
220    76
221    81
222    90
223    87
Name: srce, dtype: int64

get_valid()[source]

Set the ‘is_valid’ column to true if the faces are all closed polygons, and the cells closed polyhedra.

idx_lookup(elem_id, element)[source]

returns the current index of the element with the “id” column equal to elem_id

Parameters
• elem_id (int) – id of the element to retrieve

• element ({"vert"|"edge"|"face"|"cell"}) – the corresponding dataset.

remove(edge_out, trim_borders=False, order_edges=False)[source]

Remove the edges indexed by edge_out associated with all the cells and faces containing those edges

If trim_borders is True (defaults to False), there will be a single border edge per border face.

reset_index(order=False)[source]

Resets the datasets to have continuous indices

If order is True (the default), sorts the edges such that for each face, vertices are ordered clockwize

reset_topo()[source]

Recomputes the number of sides for the faces and the number of faces for the cells.

restore()[source]

Resets the eptithelium data to its last backed up state

A copy of the current state prior to restoring is kept in the _bad attribute for inspection. Calling this method multiple times (without calling backup) will go back in the epithelium backups.

sanitize(trim_borders=False, order_edges=False)[source]

Removes invalid faces and associated vertices

If trim_borders is True (defaults to False), there will be a single border edge per border face.

set_bbox(margin=0.0)[source]

Sets the attribute bbox with pairs of values bellow and above the min and max of the vert coords, with a margin.

property settings

Accesses the specs[‘settings’] dictionnary

sum_cell(df)[source]

Sums the values of the edge-indexed dataframe df grouped by the values of self.edge_df[“cell”]

Returns

summed

Return type

pd.DataFrame the summed data, indexed by the source vertices.

sum_face(df)[source]

Sums the values of the edge-indexed dataframe df grouped by the values of self.edge_df[“face”]

Returns

summed

Return type

pd.DataFrame the summed data, indexed by the source vertices.

sum_srce(df)[source]

Sums the values of the edge-indexed dataframe df grouped by the values of self.edge_df[“srce”]

Returns

summed

Return type

pd.DataFrame the summed data, indexed by the source vertices.

sum_trgt(df)[source]

Sums the values of the edge-indexed dataframe df grouped by the values of self.edge_df[“trgt”]

Returns

summed

Return type

pd.DataFrame the summed data, indexed by the source vertices.

triangular_mesh(coords=None, return_mask=False)[source]

Return a triangulation of an epithelial sheet (2D in a 3D space), with added edges between face barycenters and junction vertices.

Parameters
• coords (list of str:) – pair of coordinates corresponding to column names for self.face_df and self.vert_df

Returns

• vertices ((self.Nf+self.Nv, 3) ndarray) – all the vertices’ coordinates

• triangles ((self.Ne, 3) ndarray of ints) – triple of the vertices’ indexes forming the triangular elements. For each junction edge, this is simply the index (srce, trgt, face). This is correctly oriented.

• face_mask ((self.Nf + self.Nv,) mask with 1 iff the vertex corresponds) – to a face center

upcast_cell(df)[source]

Reindexes input data to self.edge_df.index by repeating the values for each cell entry

Parameters

df (pd.DataFrame, pd.Series np.ndarray or string) – The data to be upcasted. If array like, should have self.Nc elements. If a string is passed it should be a column of self.cell_df

Returns

upcast_df – The value repeated like the values of self.edge_df[“cell”]

Return type

pd.DataFrame or pd.Series

upcast_cols(element, columns)[source]

Syntactic sugar to upcast from the epithelium datasets.

Parameters
• element ({'srce'|'trgt'|'face'|'cell'}) – corresponding self.edge_df column over which to index if element is ‘srce’ or ‘trgt’, the upcast data will be taken form self.vert_df

• columns (index) – the column(s) to be taken from the input dataset.

upcast_face(df)[source]

Reindexes input data to self.edge_df.index by repeating the values for each face entry

Parameters

df (pd.DataFrame, pd.Series np.ndarray or string) – The data to be upcasted. If array like, should have self.Nf elements. If a string is passed it should be a column of self.face_df

Returns

upcast_df – The value repeated like the values of self.edge_df[“face”]

Return type

pd.DataFrame or pd.Series

upcast_srce(df)[source]

Reindexes input data to self.edge_df.index by repeating the values for each source entry.

Parameters

df (pd.DataFrame, pd.Series np.ndarray or string) – The data to be upcasted. If array like, should have self.Nv elements. If a string is passed it should be a column of self.vert_df

Returns

upcast_df – The value repeated like the values of self.edge_df[“srce”]

Return type

pd.DataFrame or pd.Series

upcast_trgt(df)[source]

Reindexes input data to self.edge_df.index by repeating the values for each target entry

Parameters

df (pd.DataFrame, pd.Series np.ndarray or string) – The data to be upcasted. If array like, should have self.Nv elements. If a string is passed it should be a column of self.vert_df

Returns

upcast_df – The value repeated like the values of self.edge_df[“trgt”]

Return type

pd.DataFrame or pd.Series

update_num_faces()[source]

Updates the number of faces around the cells. The data is registered in the “num_faces” column of self.cell_df.

update_num_sides()[source]

Updates the number of half-edges around the faces. The data is registered in the “num_sides” column of self.face_df.

update_rank()[source]
update_specs(new, reset=False)[source]

Recursively updates the self.specs nested dictionnary, and set the new values to the corresponding columns in the datasets. If reset is True, existing values will be overwritten.

validate()[source]

returns True if the mesh is validated

e.g. has only closed polygons and polyhedra

validate_closed_cells()[source]
property vert_df

The face pd.DataFrame containing vertex associated data e.g. the position of each vertex.

vertex_mesh(coords, vertex_normals=True)[source]

Returns the vertex coordinates and a list of vertex indices for each face of the tissue. If vertex_normals is True, also returns the normals of each vertex (set as the average of the vertex’ edges), suitable for .OBJ export

Note

Vertices are assumed to be ordered in a face. If you are not sure it is the case, you can run sheet.reset_index() before calling this function.

## Sheet object¶

class tyssue.Sheet(identifier, datasets, specs=None, coords=None)[source]

An epithelial sheet, i.e a 2D mesh in a 2D or 3D space, akin to a HalfEdge data structure in CGAL.

The geometric properties are defined in tyssue.geometry.sheet_geometry A dynamical model derived from Fahradifar et al. 2007 is provided in tyssue.dynamics.sheet_vertex_model

Creates an epithelium sheet, such as the apical junction network.

Parameters
• identifier (str, the tissue name) –

• face_df (pandas.DataFrame indexed by the faces indexes) – this df holds the vertices associated with

extract(face_mask, coords=['x', 'y', 'z'])[source]

Extract a new sheet from the sheet that correspond to a key word that define a face.

Parameters
• face_mask (column name in face composed by boolean value) –

• coords

Returns

subsheet corresponding to the fold patch area.

Return type

sheet_fold_patch_extract

extract_bounding_box(x_boundary=None, y_boundary=None, z_boundary=None, coords=['x', 'y', 'z'])[source]

Extracts a new sheet from the embryo sheet

that correspond to boundary coordinate define by the user.

Parameters
• x_boundary (pair of floats) –

• y_boundary (pair of floats) –

• z_boundary (pair of floats) –

• coords (list of strings, default ['x', 'y', 'z']) – coordinates over which to crop the sheet

Returns

subsheet

Return type

a new Sheet object

get_extra_indices()[source]

Computes extra indices:

• self.free_edges: half-edges at the epithelium boundary

• self.dble_edges: half-edges inside the epithelium, with an opposite

• self.east_edges: half of the dble_edges, pointing east (figuratively)

• self.west_edges: half of the dble_edges, pointing west

(the order of the east and west edges is conserved, so that the ith west half-edge is the opposite of the ith east half-edge)

• self.sgle_edges: joint index over free and east edges, spanning

the entire graph without double edges

• self.wrpd_edges: joint index over free edges followed by the
east edges twice, such that a vector over the whole half-edge

dataframe is wrapped over the single edges

• self.srtd_edges: index over the whole half-edge sorted such that

the free edges come first, then the east, then the west

Also computes: - self.Ni: the number of inside full edges

(i.e. len(self.east_edges))

• self.No: the number of outside full edges (i.e. len(self.free_edges))

• self.Nd: the number of double half edges (i.e. len(self.dble_edges))

• self.anti_sym: pd.Series with shape (self.Ne,) with 1 at the free and east half-edges and -1 at the opposite half-edges.

Notes

• East and west is resepctive to some orientation at the moment the indices are computed the partition stays valid as long as there are no changes in the topology, so due to vertex displacement, ‘east’ and ‘west’ might not stay valid. This is just a practical naming convention.

• As the name suggest, this method is not working for edges in 3D pointing exactly north or south, ie iff edge[‘dx’] == edge[‘dy’] == 0. Until we need or find a better solution, we’ll just assert it worked.

get_neighborhood(face, order)[source]

Returns face neighborhood up to a degree of order

For example, if order is 2, it wil return the adjacent, faces and theses faces neighbors.

Returns

neighbors – of the neighboring face, and it’s neighboring order

Return type

pd.DataFrame with two colums, the index

get_neighbors(face)[source]

Returns the faces adjacent to face

get_opposite()[source]
classmethod planar_sheet_2d(identifier, nx, ny, distx, disty, noise=None)[source]

Creates a planar sheet from an hexagonal grid of cells.

Parameters
• identifier (string) –

• nx (int) – number of cells in the x and y axes

• ny (int) – number of cells in the x and y axes

• distx (float,) – the distances in x and y between the cells

• disty (float,) – the distances in x and y between the cells

• noise (float, default None) – position noise on the hexagonal grid

Returns

planar_sheet – in the (x, y) plane

Return type

a 2D Sheet instance

classmethod planar_sheet_3d(identifier, nx, ny, distx, disty, noise=None)[source]

Creates a planar sheet from an hexagonal grid of cells.

Parameters
• identifier (string) –

• nx (int) – number of cells in the x and y axes

• ny (int) – number of cells in the x and y axes

• distx (float,) – the distances in x and y between the cells

• disty (float,) – the distances in x and y between the cells

• noise (float, default None) – position noise on the hexagonal grid

Returns

flat_sheet

Return type

a 2.5D Sheet instance

reset_topo()[source]

Recomputes the number of sides for the faces and the number of faces for the cells.

sort_edges_eastwest()[source]

reorder edges such the free edges are first, then the first half of the double edges, then the other half of the double edges, this way, each subset of the edges dataframe are contiguous.

## Monolayer object¶

class tyssue.Monolayer(name, datasets, specs=None, coords=None)[source]

3D monolayer epithelium

Creates an epithelium

Parameters
• identifier (string) –

• datasets (dictionary of dataframes) –

The keys correspond to the different geometrical elements constituting the epithelium:

• vert contains a dataframe of vertices,

• edge contains a dataframe of oriented half-edges between vertices,

• face contains a dataframe of polygonal faces enclosed by half-edges,

• cell contains a dataframe of polyhedral cells delimited by faces,

• specs (nested dictionnary of specifications) –

The first key designs the element name: (vert, edge, face, cell), corresponding to the respective dataframes attribute in the dataset. The second level keys design column names of the above dataframes. For exemple: .. code:

specs = {
"face": {
## Face Geometry
"perimeter": 0.,
"area": 0.,
## Coordinates
"x": 0.,
"y": 0.,
"z": 0.,
## Topology
"num_sides": 6,
"is_alive": 1},
"vert": {
## Coordinates
"x": 0.,
"y": 0.,
"z": 0.,
"is_active": 1},
"edge": {
## Connections
"srce": 0,
"trgt": 1,
"face": 0,
"cell": 0,
## Coordinates
"dx": 0.,
"dy": 0.,
"dz": 0.,
"length": 0.,
## Normals
"nx": 0.,
"ny": 0.,
"nz": 1.}
"settings":
## Custom values
"geometry": "flat"
}


Note

For efficiency reasons, we have to maintain a monotonous RangeIndex for each dataset. Thus, the index of an element can change, and should not be used as an identifier.

property apical_edges
property apical_faces
property apical_verts
property basal_edges
property basal_faces
property basal_verts
classmethod from_flat_sheet(name, apical_sheet, specs, thickness=1)[source]
get_sub_sheet(segment)[source]

Returns a Sheet object of the corresponding segment

Parameters

segment (str, the corresponding segment, wether 'apical' or 'basal') –

guess_face_segment(face)[source]

Infers the face segment from its surrounding edges.

guess_vert_segment(vert)[source]

Infers the vertex segment from its surrounding edges.

property lateral_edges
property lateral_faces
property lateral_verts
segment_index(segment, element)[source]

# Drawing functions¶

## Matplotlib based¶

Matplotlib based plotting

tyssue.draw.plt_draw.create_gif(history, output, num_frames=60, draw_func=None, margin=5, **draw_kwds)[source]

Creates an animated gif of the recorded history.

You need imagemagick on your system for this function to work.

Parameters
• history (a tyssue.History object) –

• output (path to the output gif file) –

• num_frames (int, the number of frames in the gif) –

• draw_func (a drawing function) – this function must take a sheet object as first argument and return a fig, ax pair. Defaults to quick_edge_draw (aka sheet_view with quick mode)

• margin (int, the graph margins in percents, default 5) – if margin is -1, let the draw function decide

• are passed to the drawing function (**draw_kwds) –

tyssue.draw.plt_draw.curved_view(sheet, radius_cutoff=1000.0)[source]
tyssue.draw.plt_draw.draw_edge(sheet, coords, ax, **draw_spec_kw)[source]
tyssue.draw.plt_draw.draw_face(sheet, coords, ax, **draw_spec_kw)[source]

Draws epithelial sheet polygonal faces in matplotlib Keyword values can be specified at the element level as columns of the sheet.face_df

tyssue.draw.plt_draw.draw_vert(sheet, coords, ax, **draw_spec_kw)[source]

Draw junction vertices in matplotlib

tyssue.draw.plt_draw.get_arc_data(sheet)[source]
tyssue.draw.plt_draw.parse_face_specs(face_draw_specs, sheet)[source]
tyssue.draw.plt_draw.plot_forces(sheet, geom, model, coords, scaling, ax=None, approx_grad=None, **draw_specs_kw)[source]

Plot the net forces at each vertex, with their amplitudes multiplied by scaling. To be clear, this is the oposite of the gradient - grad E.

tyssue.draw.plt_draw.plot_junction(eptm, edge_index, coords=['x', 'y'])[source]

Plots local graph around a junction, for debugging purposes

tyssue.draw.plt_draw.plot_scaled_energies(sheet, geom, model, scales, ax=None)[source]

Plot scaled energies

Parameters
• sheet (a:class: Sheet object) –

• geom (a Geometry class) –

• model (a :class:'Model') –

• scales (np.linspace of float) –

Returns

• fig (a :class:matplotlib.figure.Figure instance)

• ax (:class:matplotlib.Axes instance, default None)

tyssue.draw.plt_draw.quick_edge_draw(sheet, coords=['x', 'y'], ax=None, **draw_spec_kw)[source]
tyssue.draw.plt_draw.sheet_view(sheet, coords=['x', 'y'], ax=None, **draw_specs_kw)[source]

Base view function, parametrizable through draw_secs

The default sheet_spec specification is:

{‘edge’: {

‘visible’: True, ‘width’: 0.5, ‘head_width’: 0.2, # arrow head width for the edges ‘length_includes_head’: True, # see matplotlib Arrow artist doc ‘shape’: ‘right’, ‘color’: ‘#2b5d0a’, # can be an array ‘alpha’: 0.8, ‘zorder’: 1, ‘colormap’: ‘viridis’},

‘vert’: {

‘visible’: True, ‘s’: 100, ‘color’: ‘#000a4b’, ‘alpha’: 0.3, ‘zorder’: 2},

‘face’: {

‘visible’: False, ‘color’: ‘#8aa678’, ‘alpha’: 1.0, ‘zorder’: -1} }

## Ipyvolume based¶

3D visualisation inside the notebook.

tyssue.draw.ipv_draw.browse_history(history, coords=['x', 'y', 'z'], **draw_specs_kw)[source]
tyssue.draw.ipv_draw.edge_mesh(sheet, coords, **edge_specs)[source]

Creates a ipyvolume Mesh of the edge lines to be displayed in Jupyter Notebooks

Returns

mesh

Return type

a ipyvolume.widgets.Mesh mesh widget

tyssue.draw.ipv_draw.face_mesh(sheet, coords, **face_draw_specs)[source]

Creates a ipyvolume Mesh of the face polygons

tyssue.draw.ipv_draw.sheet_view(sheet, coords=['x', 'y', 'z'], **draw_specs_kw)[source]

Creates a javascript renderer of the edge lines to be displayed in Jupyter Notebooks

Returns

• fig (a ipyvolume.widgets.Figure widget)

• mesh (a ipyvolume.widgets.Mesh mesh widget)

tyssue.draw.ipv_draw.update_view(fig, meshes)[source]
tyssue.draw.ipv_draw.view_ipv(sheet, coords=['x', 'y', 'z'], **edge_specs)[source]

Creates a javascript renderer of the edge lines to be displayed in Jupyter Notebooks

Returns

• fig (a ipyvolume.widgets.Figure widget)

• mesh (a ipyvolume.widgets.Mesh mesh widget)

# Geometry classes¶

## Planar¶

class tyssue.PlanarGeometry[source]

Geomtetry methods for 2D planar cell arangements

static face_projected_pos(sheet, face, psi)[source]

returns the sheet vertices position translated to center the face face at (0, 0) and rotated in the (x, y) plane by and angle psi radians

classmethod get_phis(sheet)[source]
classmethod update_all(sheet)[source]

Updates the sheet geometry by updating: * the edge vector coordinates * the edge lengths * the face centroids * the normals to each edge associated face * the face areas

static update_areas(sheet)[source]

Updates the normal coordinate of each (srce, trgt, face) face.

static update_normals(sheet)[source]

## Sheet (2D 1/2)¶

class tyssue.SheetGeometry[source]

Geometry definitions for 2D sheets in 3D

static face_projected_pos(sheet, face, psi=0)[source]

Returns the position of a face vertices projected on a plane perpendicular to the face normal, and translated so that the face center is at the center of the coordinate system

Parameters
• sheet (a :class:Sheet object) –

• face (int,) – the index of the face on which to rotate the sheet

• psi (float,) – Optional angle giving the rotation along the z axis

Returns

rot_pos – The rotated, relative positions of the face’s vertices

Return type

pd.DataFrame

static face_rotation(sheet, face, psi=0)[source]

Returns a 3D rotation matrix such that the face normal points in the z axis

Parameters
• sheet (a :class:Sheet object) –

• face (int,) – the index of the face on which to rotate the sheet

• psi (float,) – Optional angle giving the rotation along the new z axis

Returns

rotation – The rotation matrix

Return type

(3, 3) np.ndarray

classmethod face_rotations(sheet, method='normal')[source]

Returns the (sheet.Ne, 3, 3) array of rotation matrices such that each rotation returns a coordinate system (u, v, w) where the face vertices are mostly in the u, v plane.

If method is ‘normal’, face is oriented with it’s normal along w if method is ‘svd’, the u, v, w is determined through singular value decompostion of the face vertices relative positions.

svd is slower but more effective at reducing face dimensionality.

classmethod get_phis(sheet, method='normal')[source]

Returns the angle of the vertices in the plane perpendicular to each face normal. For not-too-deformed faces, sorting vertices by this gives clockwize orientation.

I think not-too-deformed means starconvex here.

The ‘method’ argument is passed to face_rotations

static normal_rotations(sheet)[source]

Returns the (sheet.Ne, 3, 3) array of rotation matrices such that each rotation aligns the coordinate system along each face normals

classmethod reset_scafold(sheet)[source]

Re-centers and (in the case of a rod sheet) resets the a-b parameters and tip masks

static svd_rotations(sheet)[source]

Returns the (sheet.Ne, 3, 3) array of rotation matrices such that each rotation aligns the coordinate system according to each face vertex SVD

classmethod update_all(sheet)[source]

Updates the sheet geometry by updating: * the edge vector coordinates * the edge lengths * the face centroids * the normals to each edge associated face * the face areas * the vertices heights (depends on geometry) * the face volumes (depends on geometry)

static update_areas(sheet)[source]

Updates the normal coordniate of each (srce, trgt, face) face.

classmethod update_height(sheet)[source]

Update the height of the sheet vertices, based on the geometry specified in the sheet settings:

sheet.settings[‘geometry’] can be set to

• cylindrical: the vertex height is

measured with respect to the distance to the the axis specified in sheet.settings[‘height_axis’] (e.g z)

• flat: the vertex height is

measured with respect to the position on the axis specified in sheet.settings[‘height_axis’]

• ‘spherical’: the vertex height is measured with respect to its

distance to the coordinate system centers

• ‘rod’: the vertex height is measured with respect to its

distance to the coordinate height axis if between the focii, and from the closest focus otherwise. The focii positions are updated before the height update.

In all the cases, this distance is shifted by an amount of sheet.vert_df[‘basal_shift’]

static update_normals(sheet)[source]

Updates the face_df coords columns as the face’s vertices center of mass.

static update_vol(sheet)[source]

Note that this is an approximation of the sheet geometry module.

class tyssue.ClosedSheetGeometry[source]

Geometry for a closed 2.5D sheet.

Apart from the geometry update from a normal sheet, the enclosed volume is also computed. The value is stored in sheet.settings[“lumen_vol”]

classmethod update_all(sheet)[source]

Updates the sheet geometry by updating: * the edge vector coordinates * the edge lengths * the face centroids * the normals to each edge associated face * the face areas * the vertices heights (depends on geometry) * the face volumes (depends on geometry)

static update_lumen_vol(sheet)[source]
class tyssue.geometry.sheet_geometry.EllipsoidGeometry[source]
static scale(eptm, scale, coords)[source]

Scales the coordinates coords by a factor delta

static update_height(eptm)[source]

Update the height of the sheet vertices, based on the geometry specified in the sheet settings:

sheet.settings[‘geometry’] can be set to

• cylindrical: the vertex height is

measured with respect to the distance to the the axis specified in sheet.settings[‘height_axis’] (e.g z)

• flat: the vertex height is

measured with respect to the position on the axis specified in sheet.settings[‘height_axis’]

• ‘spherical’: the vertex height is measured with respect to its

distance to the coordinate system centers

• ‘rod’: the vertex height is measured with respect to its

distance to the coordinate height axis if between the focii, and from the closest focus otherwise. The focii positions are updated before the height update.

In all the cases, this distance is shifted by an amount of sheet.vert_df[‘basal_shift’]

## Bulk (3D)¶

class tyssue.BulkGeometry[source]

Geometry functions for 3D cell arangements

classmethod update_all(eptm)[source]

Updates the eptm geometry by updating: * the edge vector coordinates * the edge lengths * the face centroids * the normals to each edge associated face * the face areas * the cell areas * the vertices heights (depends on geometry) * the face volumes (depends on geometry)

static update_areas(eptm)[source]

Updates the normal coordniate of each (srce, trgt, face) face.

static update_centroid(eptm)[source]

Updates the face_df coords columns as the face’s vertices center of mass. Also updates the edge_df fx, fy, fz columns with their upcasted values

static update_dcoords(eptm)[source]

Update the edge vector coordinates on the coords basis (default_coords by default). Modifies the corresponding columns (i.e [‘dx’, ‘dy’, ‘dz’]) in sheet.edge_df.

Also updates the upcasted coordinates of the source and target vertices

static update_vol(eptm)[source]
static validate_face_norms(eptm)[source]
class tyssue.MonolayerGeometry[source]
static basal_apical_axis(eptm, cell)[source]

Returns a unit vector allong the apical-basal axis of the cell

classmethod cell_projected_pos(eptm, cell, psi=0)[source]

Returns the positions of the cell vertices transformed such that the cell center sits at the coordinate system’s origin and the basal-apical axis is the new z axis.

class tyssue.ClosedMonolayerGeometry[source]
classmethod update_all(eptm)[source]

Updates the eptm geometry by updating: * the edge vector coordinates * the edge lengths * the face centroids * the normals to each edge associated face * the face areas * the cell areas * the vertices heights (depends on geometry) * the face volumes (depends on geometry)

static update_lumen_vol(eptm)[source]

# Topology functions¶

## Base¶

tyssue.topology.base_topology.add_vert(eptm, edge)[source]

Adds a vertex in the middle of the edge,

which is split as is its opposite(s)

Parameters
• eptm (a Epithelium instance) –

• edge (int) –

• index of one of the half-edges to split (the) –

Returns

• new_vert (int)

• the index to the new vertex

• new_edges (int or list of ints)

• index to the new edge(s). For a sheet, returns

• a single index, for a 3D epithelium, returns

• the list of all the new parallel edges

• new_opp_edges (int or list of ints)

• index to the new opposite edge(s). For a sheet, returns

• a single index, for a 3D epithelium, returns

• the list of all the new parallel edges

In the simple case whith two half-edge, returns indices to the new edges, with the following convention:

s e t

——>

• <—— *

oe

s e ne t

—— —–>

• <—– * —— *

oe nv noe

where “e” is the passed edge as argument, “s” its source “t” its target and “oe” its opposite. The returned edges are the ones between the new vertex and the input edge’s original target.

tyssue.topology.base_topology.close_face(eptm, face)[source]

Closes the face if a single edge is missing.

This function does not close the adjacent and opposite faces.

tyssue.topology.base_topology.collapse_edge(sheet, edge, reindex=True, allow_two_sided=False)[source]

Collapses edge and merges it’s vertices, creating (or increasing the rank of) a rosette structure.

If reindex is True (the default), resets indexes and topology data. The edge is collapsed on the smaller of the srce, trgt indexes (to minimize reindexing impact)

tyssue.topology.base_topology.condition_4i(eptm)[source]

Return an index over the faces violating condition 4 i in Okuda et al 2013, that is edges (from the same face) sharing two vertices simultaneously.

tyssue.topology.base_topology.condition_4ii(eptm)[source]

Return an array of face pairs sharing more than two half-edges, as defined in Okuda et al. 2013 condition 4 ii

tyssue.topology.base_topology.drop_two_sided_faces(eptm)[source]

Removes all the two (or one?) sided faces from the epithelium

Note that they are not collapsed, but simply eliminated Does not reindex

tyssue.topology.base_topology.get_neighbour_face_pairs(eptm)[source]

Returns a pandas Series of neighboring face pairs (as forzen sets of 2 indexes)

tyssue.topology.base_topology.get_num_common_edges(eptm)[source]

Returns the number of common edges between two neighboring faces this number is set to -1 if those faces are opposite and share the same edges.

tyssue.topology.base_topology.merge_border_edges(sheet, drop_two_sided=True)[source]

Merge edges at the border of a sheet such that no vertex has only one incoming and one outgoing edge.

tyssue.topology.base_topology.merge_vertices(sheet, vert0, vert1, reindex=True)[source]

Merge the two vertices vert0 and vert1 iff they are linked by an edge

If reindex is True (the default), resets indexes and topology data

It is more efficient to call directly collapse_edge

tyssue.topology.base_topology.remove_face(sheet, face)[source]

Removes a face from the mesh

tyssue.topology.base_topology.split_vert(sheet, vert, face, to_rewire, epsilon, recenter=False)[source]

Creates a new vertex and moves it towards the center of face.

The edges in to_rewire will be connected to the new vertex.

Parameters
• sheet (a tyssue.Sheet instance) –

• vert (int, the index of the vertex to split) –

• face (int, the index of the face where to move the vertex) –

• to_rewire (pd.DataFrame a subset of sheet.edge_df) – where all the edges pointing to (or from) the old vertex will point to (or from) the new.

Note

This will leave opened faces and cells

## Sheet¶

tyssue.topology.sheet_topology.cell_division(sheet, mother, geom, angle=None)[source]

Causes a cell to divide

Parameters
• sheet (a 'Sheet' instance) –

• mother (face index of target dividing cell) –

• geom (a 2D geometry) –

• angle (division angle for newly formed edge) –

Returns

daughter

Return type

face index of new cell

Notes

• Function checks for perodic boundaries if there are, it checks if dividing cell rests on an edge of the periodic boundaries if so, it displaces the boundaries by a half a period and moves the target cell in the bulk of the tissue. It then performs cell division normally and reverts the periodic boundaries to the original configuration

tyssue.topology.sheet_topology.face_division(sheet, mother, vert_a, vert_b)[source]

Divides the face associated with edges indexed by edge_a and edge_b, splitting it in the middle of those edes.

tyssue.topology.sheet_topology.get_division_edges(sheet, mother, geom, angle=None, axis='x')[source]
tyssue.topology.sheet_topology.resolve_t1s(sheet, geom, model, solver, max_iter=60)[source]
tyssue.topology.sheet_topology.split_vert(sheet, vert, face=None, multiplier=1.5, reindex=True, recenter=False, epsilon=None)[source]

Splits a vertex towards the center of the face.

This operation removes the face face from the neighborhood of the vertex.

tyssue.topology.sheet_topology.type1_transition(sheet, edge01, *, epsilon=None, remove_tri_faces=True, multiplier=1.5)[source]

Performs a type 1 transition around the edge edge01

See ../../doc/illus/t1_transition.png for a sketch of the definition of the vertices and cells letterings See Finegan et al. for a description of the algotithm https://doi.org/10.1101/704932

Parameters
• sheet (a Sheet instance) –

• edge_01 (int) – index of the edge around which the transition takes place

• epsilon (float, optional, deprecated) – default 0.1, the initial length of the new edge, in case “threshold_length” is not in the sheet.settings

• remove_tri_faces (bool, optional) – if True (the default), will remove triangular cells after the T1 transition is performed

• multiplier (float, optional) – default 1.5, the multiplier to the threshold length, so that the length of the new edge is set to multiplier * threshold_length

## Bulk and Monolayer¶

tyssue.topology.bulk_topology.HI_transition(eptm, face)[source]

H → I transition as defined in Okuda et al. 2013 (DOI 10.1007/s10237-012-0430-7). See tyssue/doc/illus/IH_transition.png for the algorithm

tyssue.topology.bulk_topology.IH_transition(eptm, edge)[source]

I → H transition as defined in Okuda et al. 2013 (DOI 10.1007/s10237-012-0430-7). See tyssue/doc/illus/IH_transition.png for the algorithm

tyssue.topology.bulk_topology.cell_division(eptm, mother, geom, vertices=None)[source]
tyssue.topology.bulk_topology.check_condition4(func)[source]
tyssue.topology.bulk_topology.close_cell(eptm, cell)[source]

Closes the cell by adding a face. Assumes a single face is missing

tyssue.topology.bulk_topology.find_HIs(eptm, shorts=None)[source]
tyssue.topology.bulk_topology.find_IHs(eptm, shorts=None)[source]
tyssue.topology.bulk_topology.find_rearangements(eptm)[source]

Finds the candidates for IH and HI transitions :returns: * edges_HI (set of indexes of short edges)

• faces_IH (set of indexes of small triangular faces)

tyssue.topology.bulk_topology.get_division_edges(eptm, mother, plane_normal, plane_center=None)[source]

Returns an index of the mother cell edges crossed by the division plane, ordered clockwize around the division plane normal.

tyssue.topology.bulk_topology.get_division_vertices(eptm, division_edges=None, mother=None, plane_normal=None, plane_center=None)[source]
tyssue.topology.bulk_topology.remove_cell(eptm, cell)[source]

Removes a tetrahedral cell from the epithelium

tyssue.topology.bulk_topology.split_vert(eptm, vert, face=None, multiplier=1.5)[source]

Splits a vertex towards a face.

Parameters
• eptm (a tyssue.Epithelium instance) –

• vert (int the vertex to split) –

• face (int, optional, the face to split) – if face is None, one face will be chosen at random

• multiplier (float, default 1.5) – length of the new edge(s) in units of eptm.settings[“threshold_length”]

• on the algorithm (Note) –

• ---------------------

• a given face (For) –

• look for the adjacent cell with the lowest number (we) –

• faces converging on the vertex. If this number is higher than 4 (of) –

• raise a ValueError (we) –

• it's 3 (If) –

• do a OI transition (we) –

• in a new edge but no new faces (resulting) –

• it's 4 (If) –

• do a IH transition (we) –

• in a new face and 2 ne edges. (resulting) –

• ./doc/illus/IH_transition.png (see) –

tyssue.topology.monolayer_topology.cell_division(monolayer, mother, orientation='vertical', psi=0)[source]

Divides the cell mother in the monolayer.

Parameters
• monolayer (*) –

• mother (*) –

• orientation (*) – if “horizontal”, performs a division in the equatorial plane of the cell. If “vertical” (the default), performs a division along the basal-apical axis of the cell

• psi (*) – extra rotation angle of the division plane around the basal-apical plane

Returns

* daughter

Return type

int, the index of the daughter cell

tyssue.topology.monolayer_topology.find_basal_edge(monolayer, apical_edge)[source]

Returns the basal edge parallel to the apical edge passed in argument.

Parameters

monolayer (a Monolayer instance) –

tyssue.topology.monolayer_topology.type1_transition(monolayer, apical_edge, epsilon=0.1)[source]

Performs a type 1 transition on the apical and basal meshes

# Dynamic models definitions¶

tyssue.dynamics.base_gradients.length_grad(sheet)[source]

returns -(dx/l, dy/l, dz/l), ie grad_i(l_ij))

tyssue.dynamics.planar_gradients.area_grad(sheet)[source]
tyssue.dynamics.planar_gradients.lumen_area_grad(eptm)[source]

Base gradients for sheet like geometries

tyssue.dynamics.sheet_gradients.area_grad(sheet)[source]
tyssue.dynamics.sheet_gradients.height_grad(sheet)[source]

tyssue.dynamics.bulk_gradients.lumen_volume_grad(eptm)[source]

Calculates the gradient for the volume enclosed by the epithelium.

For a monolayer, it will by default compute the volume enclosed by the basal side (edges whose ‘segment’ column is “basal”). If the polarity is reversed and the apical side faces the lumen, this can be changed by setting eptm.settings[“lumen_side”] to ‘apical’

tyssue.dynamics.bulk_gradients.volume_grad(eptm)[source]

## Effectors and Model factory¶

tyssue.dynamics.factory.model_factory(effectors, ref_effector=None)[source]

Produces a Model class with the provided effectors.

Parameters
• effectors (list of effectors.AbstractEffectors classes.) –

• ref_effector (optional, default None) – if passed, will be used for normalization, by default, the last effector in the list is used

Returns

NewModel – methods

Return type

a Model derived class with compute_enregy and compute_gradient

Generic forces and energies

class tyssue.dynamics.effectors.AbstractEffector[source]

The effector class is used by model factories to construct a model.

dimensions = None
element = None
static energy(eptm)[source]
static get_nrj_norm(specs)[source]
static gradient(eptm)[source]
label = 'Abstract effector'
magnitude = None
spatial_ref = (None, None)
specs = {'cell': {}, 'edge': {}, 'face': {}, 'vert': {}}
temporal_ref = (None, None)
class tyssue.dynamics.effectors.BarrierElasticity[source]

Barrier use to maintain the tissue integrity.

dimensions = array(1.) * fJ/um**2
element = 'vert'
static energy(eptm)[source]
static gradient(eptm)[source]
label = 'Barrier elasticity'
magnitude = 'barrier_elasticity'
specs = {'vert': {'barrier_elasticity': 1.0, 'delta_rho': 0.0, 'is_active': 1}}
class tyssue.dynamics.effectors.BorderElasticity[source]
dimensions = array(1.) * fJ/um**2
element = 'edge'
static energy(eptm)[source]
static get_nrj_norm(specs)[source]
static gradient(eptm)[source]
label = 'Border edges elasticity'
magnitude = 'border_elasticity'
spatial_ref = ('prefered_length', UnitLength('micrometer', 0.001 * mm, 'um'))
specs = {'edge': {'border_elasticity': 1.0, 'is_active': 1, 'is_border': 1.0, 'length': 1.0, 'prefered_length': 1.0}}
class tyssue.dynamics.effectors.CellAreaElasticity[source]
dimensions = array(1.) * fJ/um**4
element = 'cell'
static energy(eptm)[source]
static get_nrj_norm(specs)[source]
static gradient(eptm)[source]
label = 'Area elasticity'
magnitude = 'area_elasticity'
spatial_ref = ('prefered_area', array(1.) * um**2)
specs = {'cell': {'area': 1.0, 'area_elasticity': 1.0, 'is_alive': 1, 'prefered_area': 1.0}}
class tyssue.dynamics.effectors.CellVolumeElasticity[source]
dimensions = array(1.) * fJ/um**6
element = 'cell'
static energy(eptm)[source]
static get_nrj_norm(specs)[source]
static gradient(eptm)[source]
label = 'Volume elasticity'
magnitude = 'vol_elasticity'
spatial_ref = ('prefered_vol', array(1.) * um**3)
specs = {'cell': {'is_alive': 1, 'prefered_vol': 1.0, 'vol': 1.0, 'vol_elasticity': 1.0}}
class tyssue.dynamics.effectors.FaceAreaElasticity[source]
dimensionless = False
dimensions = array(1.) * fJ/um**4
element = 'face'
static energy(eptm)[source]
static get_nrj_norm(specs)[source]
static gradient(eptm)[source]
label = 'Area elasticity'
magnitude = 'area_elasticity'
spatial_ref = ('prefered_area', array(1.) * um**2)
specs = {'edge': {'sub_area': 0.16666666666666666}, 'face': {'area': 1.0, 'area_elasticity': 1.0, 'is_alive': 1, 'prefered_area': 1.0}}
class tyssue.dynamics.effectors.FaceContractility[source]
dimensions = array(1.) * fJ/um**2
element = 'face'
static energy(eptm)[source]
static gradient(eptm)[source]
label = 'Contractility'
magnitude = 'contractility'
spatial_ref = ('mean_perimeter', UnitLength('micrometer', 0.001 * mm, 'um'))
specs = {'face': {'contractility': 1.0, 'is_alive': 1, 'perimeter': 1.0}}
class tyssue.dynamics.effectors.FaceVolumeElasticity[source]
dimensions = array(1.) * fJ/um**6
element = 'face'
static energy(eptm)[source]
static get_nrj_norm(specs)[source]
static gradient(eptm)[source]
label = 'Volume elasticity'
magnitude = 'vol_elasticity'
spatial_ref = ('prefered_vol', array(1.) * um**3)
specs = {'edge': {'sub_area': 0.16666666666666666}, 'face': {'is_alive': 1, 'prefered_vol': 1.0, 'vol': 1.0, 'vol_elasticity': 1.0}, 'vert': {'height': 1.0}}
class tyssue.dynamics.effectors.LengthElasticity[source]

Elastic half edge

dimensions = array(1.) * fJ/um**2
element = 'edge'
static energy(eptm)[source]
static get_nrj_norm(specs)[source]
static gradient(eptm)[source]
label = 'Length elasticity'
magnitude = 'length_elasticity'
spatial_ref = ('prefered_length', UnitLength('micrometer', 0.001 * mm, 'um'))
specs = {'edge': {'is_active': 1, 'length': 1.0, 'length_elasticity': 1.0, 'prefered_length': 1.0, 'ux': 0.5773502691896257, 'uy': 0.5773502691896257, 'uz': 0.5773502691896257}}
class tyssue.dynamics.effectors.LineTension[source]
dimensions = array(1.) * fJ/um
element = 'edge'
static energy(eptm)[source]
static gradient(eptm)[source]
label = 'Line tension'
magnitude = 'line_tension'
spatial_ref = ('mean_length', UnitLength('micrometer', 0.001 * mm, 'um'))
specs = {'edge': {'is_active': 1, 'line_tension': 1.0}}
class tyssue.dynamics.effectors.LineViscosity[source]
dimensions = array(1.) * s*nN/um
element = 'edge'
static gradient(eptm)[source]
label = 'Linear viscosity'
magnitude = 'edge_viscosity'
spatial_ref = ('mean_length', UnitLength('micrometer', 0.001 * mm, 'um'))
specs = {'edge': {'edge_viscosity': 1.0, 'is_active': 1}}
temporal_ref = ('dt', UnitTime('second', 's'))
class tyssue.dynamics.effectors.LumenAreaElasticity[source]

..math:

rac{K_Y}{2}(A_{mathrm{lumen}} - A_{0,mathrm{lumen}})^2

dimensions = array(1.) * fJ/um**4
element = 'settings'
static energy(eptm)[source]
static gradient(eptm)[source]
label = 'Lumen volume constraint'
magnitude = 'lumen_elasticity'
spatial_ref = ('lumen_prefered_vol', array(1.) * um**2)
specs = {'settings': {'lumen_elasticity': 1.0, 'lumen_prefered_vol': 1.0, 'lumen_vol': 1.0}}
class tyssue.dynamics.effectors.LumenVolumeElasticity[source]

Global volume elasticity of the object. For example the volume of the yolk in the Drosophila embryo

dimensions = array(1.) * fJ/um**6
element = 'settings'
static energy(eptm)[source]
static get_nrj_norm(specs)[source]
static gradient(eptm)[source]
label = 'Lumen volume elasticity'
magnitude = 'lumen_vol_elasticity'
spatial_ref = ('lumen_prefered_vol', array(1.) * um**3)
specs = {'settings': {'lumen_prefered_vol': 1.0, 'lumen_vol': 1.0, 'lumen_vol_elasticity': 1.0}}
class tyssue.dynamics.effectors.PerimeterElasticity[source]

From Mapeng Bi et al. https://doi.org/10.1038/nphys3471

dimensions = array(1.) * fJ/um**2
element = 'face'
static energy(eptm)[source]
static gradient(eptm)[source]
label = 'Perimeter Elasticity'
magnitude = 'perimeter_elasticity'
spatial_ref = ('prefered_perimeter', UnitLength('micrometer', 0.001 * mm, 'um'))
specs = {'face': {'is_alive': 1, 'perimeter': 1.0, 'perimeter_elasticity': 0.1, 'prefered_perimeter': 3.81}}
class tyssue.dynamics.effectors.RadialTension[source]

Apply a tension perpendicular to a face.

dimensions = array(1.) * fJ/um
element = 'face'
static energy(eptm)[source]
static gradient(eptm)[source]
label = 'Apical basal tension'
magnitude = 'radial_tension'
specs = {'face': {'height': 1.0, 'radial_tension': 1.0}}
class tyssue.dynamics.effectors.SurfaceTension[source]
dimensions = array(1.) * fJ/um**2
element = 'face'
static energy(eptm)[source]
static gradient(eptm)[source]
label = 'Surface tension'
magnitude = 'surface_tension'
spatial_ref = ('prefered_area', array(1.) * um**2)
specs = {'face': {'area': 1.0, 'is_active': 1, 'surface_tension': 1.0}}
tyssue.dynamics.effectors.dimensionalize(nondim_specs, dim_specs, effector, ref_effector)[source]
tyssue.dynamics.effectors.elastic_energy(element_df, var, elasticity, prefered)[source]
tyssue.dynamics.effectors.elastic_force(element_df, var, elasticity, prefered)[source]
tyssue.dynamics.effectors.normalize(dim_specs, nondim_specs, effector, ref_effector)[source]
tyssue.dynamics.effectors.scaler(nondim_specs, dim_specs, effector, ref_effector)[source]

## Predefined models¶

Vertex model for an Epithelial sheet (see definitions).

Depends on the sheet vertex geometry functions.

Specific functions for apoptosis vertex model

class tyssue.dynamics.apoptosis_model.ApicoBasalTension[source]

Effector for the apical-basal tension.

The energy is proportional to the heigth of the cell

dimensions = array(1.) * fJ/um**2
element = 'vert'
static energy(sheet)[source]
static gradient(sheet)[source]
label = 'Apical-basal tension'
magnitude = 'radial_tension'
specs = {'vert': {'height': 1.0, 'is_active': 1, 'radial_tension': 0.0}}

Dynamical models for monlayer and bulk epithelium.

class tyssue.dynamics.bulk_model.LaminaModel[source]

Not implemented yet

# Epithelium generation utilities¶

The generation module provides utilities to easily create Epithelium objects.

class tyssue.generation.shapes.AnnularSheet(identifier, datasets, specs=None, coords=None)[source]

2D annular model of a cylinder-like monolayer.

Provides syntactic sugar to access the apical, basal and lateral segments of the epithlium

Creates an epithelium sheet, such as the apical junction network.

Parameters
• identifier (str, the tissue name) –

• face_df (pandas.DataFrame indexed by the faces indexes) – this df holds the vertices associated with

property apical_edges
property apical_verts
property basal_edges
property basal_verts
property lateral_edges
reset_topo()[source]

Recomputes the number of sides for the faces and the number of faces for the cells.

segment_index(segment, element)[source]
tyssue.generation.shapes.ellipse_rho(theta, a, b)[source]
tyssue.generation.shapes.ellipsoid_sheet(a, b, c, n_zs, **kwargs)[source]

Creates an ellipsoidal apical mesh.

Parameters
• a (floats) – Size of the ellipsoid half axes in the x, y, and z directions, respectively

• b (floats) – Size of the ellipsoid half axes in the x, y, and z directions, respectively

• c (floats) – Size of the ellipsoid half axes in the x, y, and z directions, respectively

• n_zs (int) – The (approximate) number of faces along the z axis.

• are passed to get_ellipsoid_centers (kwargs) –

Returns

• eptm (a Epithelium object)

• The mesh returned is an Epithelium and not a simpler Sheet

• so that a unique cell data can hold information on the

• whole volume of the ellipsoid.

tyssue.generation.shapes.generate_ring(Nf, R_in, R_out, R_vit=None, apical='in')[source]

Generates a 2D tyssue object aranged in a ring of Nf tetragonal cells with inner diameter R_in and outer diameter R_out

Parameters
• Nf (int) – The number of cells in the tissue

• R_in (float) – The inner ring diameter

• R_out (float) – The outer ring diameter

• R_vit (float) – The vitelline membrane diameter (a non strechable membrane around the annulus)

• apical (str {'in' | 'out'}) – The side of the apical surface if “in”, the apical surface is inside the annulus, facing the lumen as in an organoid; if ‘out’: the apical side is facing the exterior of the tissue, as in an embryo

Returns

eptm – 2D annular tissue. The R_in and R_out parameters are stored in the class settings attribute.

Return type

AnnularSheet

tyssue.generation.shapes.get_ellipsoid_centers(a, b, c, n_zs, pos_err=0.0, phase_err=0.0)[source]

Creates hexagonaly organized points on the surface of an ellipsoid

Parameters
• a (float) – ellipsoid radii along the x, y and z axes, respectively i.e the ellipsoid boounding box will be [[-a, a], [-b, b], [-c, c]]

• b (float) – ellipsoid radii along the x, y and z axes, respectively i.e the ellipsoid boounding box will be [[-a, a], [-b, b], [-c, c]]

• c (float) – ellipsoid radii along the x, y and z axes, respectively i.e the ellipsoid boounding box will be [[-a, a], [-b, b], [-c, c]]

• n_zs (float) – number of cells on the z axis, typical

• pos_err (float, default 0.) – normaly distributed noise of std. dev. pos_err is added to the centers positions

• phase_err (float, default 0.) – normaly distributed noise of std. dev. phase_err is added to the centers angle ϕ

tyssue.generation.shapes.sheet_from_cell_centers(points, noise=0)[source]

Returns a Sheet object from the Voronoï tessalation of the cell centers.

The strategy is to project the points on a sphere, get the Voronoï tessalation on this sphere and reproject the vertices on the original (implicit) surface through linear interpolation of the cell centers.

Works for relatively smooth surfaces (at the very minimum star convex).

Parameters
• points (np.ndarray of shape (Nf, 3)) – the x, y, z coordinates of the cell centers

• noise (float, default 0.0) – addiditve normal noise stdev

Returns

sheet

Return type

a Sheet object with Nf faces

tyssue.generation.shapes.spherical_monolayer(R_in, R_out, Nc, apical='out')[source]

Returns a spherical monolayer with the given inner and outer radii, and approximately the gieven number of cells.

The apical argument can be ‘in’ out ‘out’ to specify wether the apical face of the cells faces inward or outward, reespectively.

tyssue.generation.shapes.spherical_sheet(radius, Nf, **kwargs)[source]

Returns a spherical sheet with the given radius and (approximately) the given number of cells

This module provides utlities to modify an input tissue through extrusion or subdivision

tyssue.generation.modifiers.create_anchors(sheet)[source]

Adds an edge linked to every vertices at the boundary and create anchor vertices

tyssue.generation.modifiers.extrude(apical_datasets, method='homotecy', scale=0.3, vector=[0, 0, - 1])[source]

Extrude a sheet to form a monlayer epithelium

Parameters
• apical_datasets (*) –

• 'vert'

• 'edge'

• 'face'

• method (*) –

• 'homotecy' (default) –

• scale (*) –

• scale factor for homotetic scaling (the) –

• 0.3. (default) –

• vector (*) –

• for the translation (used) –

• [0 (default) –

• 0

• -1]

• method == 'homotecy' (if) –

• basal layer is scaled down from the (the) –

• one homoteticaly w/r to the center of the coordinate (apical) –

• system

• a factor given by scale (by) –

• method == 'translation' (if) –

• basal vertices are translated from (the) –

• apical ones by the vector vect (the) –

• method == 'normals' (if) –

• vertices are translated from (basal) –

• apical ones along the normal of the surface at each vertex (the) –

:param : :param by a vector whose size is given by scale:

tyssue.generation.modifiers.subdivide_faces(eptm, faces)[source]

Adds a vertex at the center of each face, and returns a new dataset

Parameters
• eptm (a Epithelium instance) –

• faces (list,) – indices of the faces to be subdivided

Returns

new_dset – a dataset with the new faces devided

Return type

dict

## Hexagonal grids¶

tyssue.generation.hexagonal_grids.circle(num_t, radius=1.0, phase=0.0)[source]

Returns x and y positions of num_t points regularly placed around a circle of radius radius, shifted by phase radians.

Parameters
• num_t (int) – the number of points around the circle

• phase (float, default 0.0) – angle shift w/r to the x axis in radians

Returns

points

Return type

np.Ndarray of shape (num_t, 2), the x, y positions of the points

tyssue.generation.hexagonal_grids.hexa_cylinder(num_t, num_z, radius=1.0, capped=False, noise=0, orientation='transverse')[source]

Returns an arrays of x, y positions of points evenly spread on a cylinder with num_t points on the periphery and num_z points on its length.

Parameters
• num_t (int,) – The number of points on the periphery

• num_z (int,) – The number of points along the z axis (the length of the cylinder)

• capped (bool, default False) – If True, the tips of the cylinder are capped by a disk of point as generated by the hexa_disk function.

• noise (float, default 0) – normaly distributed position noise around the cell points

• orientation ({'transverse' | 'longitudinal'}, default 'transverse') – the orientation of the cells (with the longueur axis perpendicular or along the length of the cylinder)

tyssue.generation.hexagonal_grids.hexa_disk(num_t, radius=1)[source]

Returns an arrays of x, y positions of points evenly spread on a disk with num_t points on the periphery.

Parameters
• num_t (int) – the number of poitns on the disk periphery, the rest of the disk is filled automaticaly

tyssue.generation.hexagonal_grids.hexa_grid2d(nx, ny, distx, disty, noise=None)[source]

Creates an hexagonal grid of points

tyssue.generation.hexagonal_grids.hexa_grid3d(nx, ny, nz, distx=1.0, disty=1.0, distz=1.0, noise=None)[source]

Creates an hexagonal grid of points

tyssue.generation.hexagonal_grids.three_faces_sheet(zaxis=False)[source]

Creates the apical junctions mesh of three packed hexagonal faces. If zaxis is True (defaults to False), adds a z coordinates, with z = 0.

Faces have a side length of 1.0 +/- 1e-3.

Returns

• face_df (the faces DataFrame indexed from 0 to 2)

• vert_df (the junction vertices DataFrame)

• edge_df (the junction edges DataFrame)

tyssue.generation.hexagonal_grids.three_faces_sheet_array()[source]

Creates the apical junctions mesh of three packed hexagonal faces. If zaxis is True (defaults to False), adds a z coordinates, with z = 0.

Faces have a side length of 1.0 +/- 1e-3.

Returns

• points ((13, ndim) np.array of floats) – the positions, where ndim is 2 or 3 depending on zaxis

• edges ((15, 2) np.array of ints) – indices of the edges

• (Nc, Nv, Ne) (triple of ints) – number of faces, vertices and edges (3, 13, 15)

tyssue.generation.from_voronoi.from_2d_voronoi(voro, specs=None)[source]

Creates 2D (sheet geometry) datasets from a Voronoï tessalation

Parameters

voro (a scipy.spatial.Voronoi object) –

Returns

datasets – datasets suitable for Epithelium implementation

Return type

dict

tyssue.generation.from_voronoi.from_3d_voronoi(voro)[source]

Creates 3D (bulk geometry) datasets from a Voronoï tessalation

Parameters

voro (a scipy.spatial.Voronoi object) –

Returns

datasets – datasets suitable for Epithelium implementation

Return type

dict

# Input/output¶

tyssue.io.hdf5.load_datasets(h5store, data_names=['face', 'vert', 'edge', 'cell', 'settings'])[source]
tyssue.io.hdf5.save_datasets(h5store, eptm)[source]
tyssue.io.csv.write_storm_csv(filename, points, coords=['x', 'y', 'z'], split_by=None, **csv_args)[source]

Saves a point cloud array in the storm format

tyssue.io.obj.save_junction_mesh(filename, eptm)[source]
tyssue.io.obj.save_splitted_cells(fname, sheet, epsilon=0.1)[source]
tyssue.io.obj.save_triangulated(filename, eptm)[source]
tyssue.io.obj.write_splitted_cells(*args, **kwargs)[source]

## Predefined datasets¶

Available predefined datasets:small_hexagonal.hf5 __init__.py __pycache__ before_apoptosis.hf5 with_4sided_cell.hf5 small_ellipsoid.hf5 planar_periodic8x8.hf5 rod_sheet.hf5 15_cells_patch.hf5 sheet6x5.hf5

tyssue.stores.load_datasets(store, **kwargs)[source]

This will soon be deprecated, use the leaner tyssue.stores.stores_dir and tyssue.stores.stores_list

# Collision detection and correction¶

## Detection¶

tyssue.collisions.intersection.self_intersections(sheet)[source]

Checks for self collisions for the sheet

Parameters

sheet (a Sheet object) – This object must have a triangular_mesh method returning a valid triangular mesh.

Returns

edge_pairs – Array of shape (n_intersections, 2) with the indices of the pairs of intersecting edges

Return type

np.ndarray of indices

## Resolution¶

class tyssue.collisions.solvers.CollidingBoxes(sheet, position_buffer, intersecting_edges)[source]

Utility class to manage collisions

Creates a CollidingBoxes instance

Parameters
• sheet (a :clas:Sheet instance) –

• position_buffer (np.array of shape (sheet.Nv, sheet.dim):) – positions of the vertices prior to the collisions

• intersecting_edges (np.ndarray) – pairs of indices of the intersecting edges

get_limits(shyness=1e-10)[source]

Iterator over the position boundaries avoiding the collisions.

Parameters

shyness (float) – the extra distance between two colliding vertices, on each side of the collision plane.

Yields

lower, upper (two pd.Series) – those Series are indexed by the vertices of the colliding faces giving the lower and upper bounds for the vertices

solve_collisions(shyness=1e-10)[source]

Solves the collisions by finding the collision plane.

Modifies the sheet vertex positions inplace such that they rest at a distance shyness apart on each side of the collision plane.

Parameters
• shyness (float, default 1e-10) – the extra distance between two colliding vertices, on each side of the collision plane.

• on Liu (Based) –

• J.-D.

• Ko

• M.-T.

• Chang (&) –

• (1998) (R.-C.) –

:param : :param *A simple self-collision avoidance for cloth animation*.: :param Computers & Graphics: :param 22(1): :param 117–128.: :param DOI <https: :type DOI

tyssue.collisions.solvers.auto_collisions(fun)[source]

Decorator to solve collisions detections after the execution of the decorated function.

It is assumed that the two first arguments of the decorated function are a Sheet object and a geometry class

Note

The function is re-executed with the updated geometry

tyssue.collisions.solvers.revert_positions(sheet, position_buffer, intersecting_edges)[source]
tyssue.collisions.solvers.solve_bulk_collisions(eptm, position_buffer)[source]

Corrects the auto-collisions for the outer surface(s) of a 3D epithelium.

Parameters
• eptm (a Epithelium object) –

• position_buffer (np.array of shape (eptm.Nv, eptm.dim):) – positions of the vertices prior to the collisions

Returns

changedTrue if the positions of some vertices were changed

Return type

bool

tyssue.collisions.solvers.solve_sheet_collisions(sheet, position_buffer)[source]

Corrects the auto-collisions for the outer surface(s) of a 2.5D sheet.

Parameters
• sheet (a Sheet object) –

• position_buffer (np.array of shape (sheet.Nv, sheet.dim):) – positions of the vertices prior to the collisions

Returns

changedTrue if the positions of some vertices were changed

Return type

bool

# Miscellanous utils¶

tyssue.utils.utils.ar_calculation(sheet, coords=['x', 'y'])[source]

Calculates the aspect ratio of each face of the sheet

Parameters
• eptm (a Sheet object) –

• coords (list of str, optional, default ['x', 'y']) – the coordinates on which to compute the aspect ratio

Returns

AR

Return type

pandas series of aspect ratio for all faces.

Note

As is the case in ImageJ, the returned aspect ratio is always higher than 1

tyssue.utils.utils.combine_specs(*specs)[source]
tyssue.utils.utils.data_at_opposite(sheet, edge_data, free_value=None)[source]

Returns a pd.DataFrame with the values of the input edge_data at the opposite edges. For free edges, optionaly replaces Nan values with free_value

Parameters
• sheet (a Sheet instance) –

• edge_data (dataframe contain value of edge) –

Returns

opposite

Return type

pandas series contain value of opposite edge

tyssue.utils.utils.get_next(eptm)[source]

Returns the indices of the next edge for each edge

tyssue.utils.utils.get_sub_eptm(eptm, edges, copy=False)[source]

Define sub-epithelium corresponding to the edges.

Parameters
• eptm (a Epithelium instance) –

• edges (list of edges includes in the sub-epithelium) –

Returns

sub_eptm

Return type

a Epithelium instance

tyssue.utils.utils.modify_segments(eptm, modifiers)[source]

Modifies the datasets of a segmented epithelium according to the passed modifiers.

Parameters

Note

This functions assumes that the epithelium has a segment_index method as implemented in the tyssue.Monolayer.

Example

>>> modifiers = {
>>>     'apical' : {
>>>         'edge': {'line_tension': 1.},
>>>         'face': {'prefered_area': 0.2},
>>>     },
>>>     'basal' : {
>>>         'edge': {'line_tension': 3.},
>>>         'face': {'prefered_area': 0.1},
>>>     }
>>> modify_segments(monolayer, modifiers)
>>> monolayer.ver_df.loc[monolayer.apical_edges,
>>>                      'line_tension'].unique()[0] == 1.
True

tyssue.utils.utils.scaled_unscaled(func, scale, eptm, geom, args=(), kwargs={}, coords=None)[source]

Scales the epithelium by an homotetic factor scale, applies the function func, and scales back to original size.

Parameters
• func (the function to apply to the scaled epithelium) –

• scale (float, the scale to apply) –

• eptm (a Epithelium instance) –

• geom (a Geometry class) –

• args (sequence, the arguments to pass to func) –

• kwargs (dictionary, the keywords arguments) – to pass to func

• coords (the coordinates on which the scaling applies) –

• the execution of function fails (If) –

• scaling is still reverted (the) –

Returns

res

Return type

the result of the function func

tyssue.utils.utils.set_data_columns(datasets, specs, reset=False)[source]

Sets the columns of the dataframes in the datasets dictionnary to the uniform values in the specs sub-dictionnaries.

Parameters
• datasets (dict of dataframes) –

• specs (dict of dicts) –

• reset (bool, default False) –

• each key in specs (For) –

• value is a dictionnary whose (the) –

• are column names for the corresponding dataframe in (keys) –

• If there is no such column in the dataframe (datasets.) –

:param : :param it is created. If the columns allready exists and reset is True: :param : :param the new value is used.:

tyssue.utils.utils.single_cell(eptm, cell, copy=False)[source]

Define epithelium instance for all element to a define cell.

Parameters
• eptm (a Epithelium instance) –

• cell (identifier of a cell) –

• copy (bool, default False) –

Returns

sub_etpm

Return type

class:’Epithelium’ instance corresponding to the cell

tyssue.utils.utils.spec_updater(specs, new)[source]

Add element to the new dictionary to the specs dictionary. Update value if the key already exist.

Parameters
• specs (specification that will be modified) –

• new (dictionary of new specification) –

tyssue.utils.utils.swap_apico_basal(organo)[source]

Swap apical and basal segments of an organoid

tyssue.utils.utils.to_nd(df, ndim)[source]

Give a new shape to an input data by duplicating its column.

Parameters
• df (input data that will be reshape) –

• ndim (dimension of the new reshape data.) –

Returns

df_nd

Return type

return array reshaped in ndim.

## Decorators¶

tyssue.utils.decorators.cell_lookup(func)[source]
tyssue.utils.decorators.do_undo(func)[source]

Decorator that creates a copy of the first argument (usually an epithelium object) and restores it if the function fails.

The first argument in *args should have backup() and restore() methods.

tyssue.utils.decorators.face_lookup(func)[source]
tyssue.utils.decorators.time_exe(func)[source]
tyssue.utils.decorators.validate(func)[source]

Decorator that validate the epithelium after the decorated function was applied. the first argument of func should be an epithelium instance, and is at least assumed to have a validate method.