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.

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

  • return_mask (bool, optional, default True) – if True, returns face_mask

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]#

Returns True if all cells of the epithelium are closed.

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

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

extract_bounding_box_2dellipse(r_x, r_y, coords=['x', 'y'])[source]#

Extracts a new sheet from the embryo sheet that correspond to boundary coordinate defined by the user. :param r_x: :type r_x: size of major/minor axis in x-direction :param r_y: :type r_y: size of major/minor axis in y-direction :param coords: coordinates over which to crop the sheet :type coords: list of strings, default [‘x’, ‘y’, ‘z’]

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_force_inference(coords=None, column=None, free_border_edges=False)[source]#

Measure force based on Brodland method.

g_gamma_matrix*tension_vector = 0 Equation is homogenous and to avoid tension_vectors = 0, Construction and solve the constrained least-squares equation system [[g_gamma_matrix.T g_gamma_matrix, C^T_1],

[C_1, 0]] où C1 = {1….1}

shape of g_gamma_matrix = (Ne/2, Nv*len(coords))

Note

Results might not be consistens for highly curved epithelium

Parameters
  • coords (coordinates) –

  • column (None, specify a column name in edge_df to put tension value) –

  • free_border_edges (bool, default False, take into account edges in the) –

  • True (border of the tissue if) –

Returns

edges_tensions

Return type

tension values array if column not define

get_neighborhood(face, order, elem='face')[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, elem='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

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.

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.browse_history(history, coords=['x', 'y'], start=None, stop=None, size=None, draw_func=None, margin=5, **draw_kwds)[source]#

Returns a browser widget with 2D plots of the epithelium

tyssue.draw.plt_draw.create_gif(history, output, num_frames=None, interval=None, 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) –

  • interval (tuples, define begin and end frame of 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

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

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, cbar_axis=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.0, “length_includes_head”: true, “shape”: “right”, “color”: “#2b5d0a”, “alpha”: 0.8, “zorder”: 1, “colormap”: “viridis”

}, “vert”: {

“visible”: false, “s”: 100, “color”: “#000a4b”, “alpha”: 0.3, “zorder”: 2

}, “grad”: {

“color”:”#000a4b”, “alpha”:0.5, “width”:0.04

}, “face”: {

“visible”: false, “color”:”#8aa678”, “alpha”: 1.0, “zorder”: -1

}, “axis”: {

“autoscale”: true, “color_bar”: false, “color_bar_cmap”:”viridis”, “color_bar_range”:false, “color_bar_label”:false, “color_bar_target”:”face”

}

}

Note

Important note for quantitative colormap plots: make sure to normalize your values before getting the colors using

draw_specs[“face”][“color”] = cmap(pandas_holding_quantity_of_interest)

For each plot normalize with respect to the current values (max and min) such that they lie between and including 0 to 1. Note that if you want to keep a constant colorbar range you have to choose the normalization to match the max and min of the color bar range you chose.

Ipyvolume based#

3D visualisation inside the notebook.

tyssue.draw.ipv_draw.browse_history(history, coords=['x', 'y', 'z'], start=None, stop=None, size=None, **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', output_as='edge')[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.

Parameters

output_as (string, default 'edge' Return the (sheet.Ne, 3, 3),) – else ‘face’ Return the (sheet.Nf, 3, 3)

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, output_as='edge')[source]#

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

Parameters

output_as (string, default 'edge' Return the (sheet.Ne, 3, 3),) – else ‘face’ Return the (sheet.Nf, 3, 3)

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, output_as='edge')[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

Parameters

output_as (string, default 'edge' Return the (sheet.Ne, 3, 3),) – else ‘face’ Return the (sheet.Nf, 3, 3)

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_ucoords(eptm)[source]#
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) –

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

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. Returns the index of the new edge if created, otherwise None

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)

Returns the index of the collapsed edge’s remaining vertex (its srce)

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

Note

An indication way to solve this:

faces = condition_4ii(eptm)

pairs = set(frozenset(p) for p in faces)

cols = ['srce', 'trgt', 'face', 'cell', 'length', 'sub_area']
edges = eptm.edge_df[
    eptm.edge_df["face"].isin(faces[0])
][cols].sort_values("face")
all_edges = eptm.edge_df.loc[eptm.edge_df["face"].isin(
    set(faces.ravel())), cols].sort_values("face")

all_edges['single'] = all_edges[["srce", "trgt"]].apply(frozenset, axis=1)

ufaces = set(faces.ravel())

com_vs = set(all_edges.srce)
for face in ufaces:
    com_vs = com_vs.intersection(
        all_edges.loc[all_edges["face"] == face, "srce"]
    )
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.

Returns the index of the new vert that replaces the face.

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.

Returns a list of the new edge’s indices in edge_df. This should be two:

the edge with vert as the srce and the newly created vertex as the trgt and the reverse edge with vert as the trgt and the new one as the srce

tyssue.topology.sheet_topology.type1_transition(sheet, edge01, *, 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, recenter=False)[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, recenter=False)[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, mother_verts=None, daughter_verts=None)[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.fix_pinch(eptm)[source]#

Due to rearangements, some faces in an epithelium will have more than one opposite face.

This method fixes the issue so we can have a valid epithelium back.

tyssue.topology.bulk_topology.get_division_edges(eptm, mother, plane_normal, plane_center=None, return_verts=False)[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, return_all=False)[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, recenter=False)[source]#

Splits a vertex towards a face.

Parameters
  • eptm (a tyssue.Epithelium instance) –

  • vert (int the vertex to split) –

  • face (For a given) – 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”]

  • algorithm (Note on the) –

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

  • face

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

  • 4 (If it's) –

  • ValueError (we raise a) –

  • 3 (If it's) –

  • transition (we do a IH) –

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

  • 4

  • transition

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

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

tyssue.topology.monolayer_topology.cell_division(monolayer, mother, orientation='vertical', psi=None)[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. If “apical”, performs a division cutting the apical face perpendicularly to its principal axis

  • 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) –

Dynamic models definitions#

Gradients#

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]#

Base gradients for bulk geometry

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.MidlineBoundary[source]#

Elastic boundary at the x-axis, to be used with MidlineBoundaryGeometry. Intended to use with a high midline_boundary_stiffness to prevent vertices from crossing the midline.

dimensions = array(1.) * fJ/um**2#
element = 'vert'#
static energy(eptm)[source]#
static gradient(eptm)[source]#
label = 'Midline boundary'#
magnitude = 'midline_boundary'#
specs = {'vert': {'boundary_K': 280, 'delta_boundary': 0, 'is_active': 1}}#
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

Quasistatic solver#

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

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.Lloyd_relaxation(sheet, geom, steps=10, coords=None, update_method=None)[source]#

Performs Lloyd relaxation on the sheet.

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.

  • get_ellipsoid_centers (kwargs are passed to) –

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, interp_s=0.0001)[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

  • interp_s (float, default 1e-4) – interpolation smoothing factor (might need to set higher)

Returns

sheet

Return type

a Sheet object with Nf faces

tyssue.generation.shapes.spherical_monolayer(R_in, R_out, Nc, apical='out', Lloyd_relax=False)[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, Lloyd_relax=False, **kwargs)[source]#

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

tyssue.generation.shapes.update_on_sphere(sheet)[source]#

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' (if method ==) –

  • scale (by a factor given by) –

  • scaling (the scale factor for homotetic) –

  • 0.3. (default) –

  • vector (*) –

  • translation (used for the) –

  • [0 (default) –

  • 0

  • -1]

  • 'homotecy'

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

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

  • system

  • scale

  • 'translation' (if method ==) –

  • from (basal vertices are translated) –

  • vect (the apical ones by the vector) –

  • 'normals' (if method ==) –

  • from

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

: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

  • radius (float, default 1.) – the radius of 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)

  • radius (float, default 1) – The radius 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

  • radius (float, default 1.) – the radius of the disk

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=True)[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

Notes

It is important to reset the index of the created epithelium after creation

Example

cells = hexa_grid3d(3, 3, 3) datasets = from_3d_voronoi(Voronoi(cells)) bulk = Epithelium(‘bulk’, datasets) bulk.reset_topo() bulk.reset_index(order=True) bulk.sanitize()

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:15_cells_patch.hf5 __pycache__ small_hexagonal.hf5 planar_periodic8x8.hf5 small_ellipsoid.hf5 rod_sheet.hf5 small_hexagonal_snaped.hf5 with_pinch.hf5 __init__.py with_4sided_cell.hf5 sheet6x5.hf5 before_apoptosis.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

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.

  • Liu (Based on) –

  • 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.cell_centered_patch(eptm, cell, neighbour_order)[source]#

Return subsheet centered on cell with a distance of neighbour order around the cell

Parameters
  • eptm (a Epithelium instance) –

  • face (int, id of the center face) –

  • neighbour_order (int, number of neighbour around the center face) –

Returns

patch

Return type

an object of the same class as the input object

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.elem_centered_patch(eptm, elem_idx, neighbour_order, elem)[source]#

Return subeptm centered on the element (cell or face) with index elem_idx with neighbour_order neighbours around it.

Parameters
  • eptm (a Epithelim instance) –

  • index (int, id of the center element) –

  • neighbour_order (int,) – neighbourhood ‘degree’ around the center element

Returns

patch

Return type

an object with the same class as eptm

tyssue.utils.utils.face_centered_patch(sheet, face, neighbour_order)[source]#

Return subsheet centered on face with a distance of neighbour order around the face

Parameters
  • sheet (a Sheet object) –

  • face (int, id of the center face) –

  • neighbour_order (int, number of neighbour around the center face) –

Returns

patch

Return type

an object of the same class as the input object

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) –

  • fails (If the execution of function) –

  • reverted (the scaling is still) –

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 (For each key in) –

  • reset (bool, default False) –

  • specs

  • whose (the value is a dictionnary) –

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

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

: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.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.