tyssue.core package

Submodules

tyssue.core.history module

class tyssue.core.history.History(sheet, save_every=None, dt=None, save_only=None, extra_cols=None, save_all=True)

Bases: object

This class handles recording and retrieving time series of sheet objects.

property cell_h
property edge_h
property face_h
record(time_stamp=None)

Appends a copy of the sheet datasets to the history instance.

time_stamp : float, save specific timestamp

retrieve(time)

Return datasets at time time.

If a specific dataset was not recorded at time time, the closest record before that time is used.

property time_stamps
to_archive(hf5file)

Saves the history to a HDF file

This file can later be accessed again with the HistoryHdf5.from_archive class method

property vert_h
class tyssue.core.history.HistoryHdf5(sheet=None, save_every=None, dt=None, save_only=None, hf5file='', overwrite=False)

Bases: tyssue.core.history.History

This class handles recording and retrieving time series of sheet objects.

classmethod from_archive(hf5file, columns=None, eptm_class=None)
record(time_stamp=None, sheet=None)

Appends a copy of the sheet datasets to the history HDF file.

sheet: a Sheet object which we want to record. This argument can be used if the sheet object is different at each time point.

retrieve(time)

Return datasets at time time.

If a specific dataset was not recorded at time time, the closest record before that time is used.

property time_stamps

tyssue.core.monolayer module

Monolayer epithelium objects

class tyssue.core.monolayer.Monolayer(name, datasets, specs=None, coords=None)

Bases: tyssue.core.objects.Epithelium

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)
get_sub_sheet(segment)

Returns a Sheet object of the corresponding segment

segment: str, the corresponding segment, wether ‘apical’ or ‘basal’

guess_face_segment(face)

Infers the face segment.

guess_vert_segment(vert)

Infers the vertex segment from its surrounding edges.

property lateral_edges
property lateral_faces
property lateral_verts
segment_index(segment, element)
class tyssue.core.monolayer.MonolayerWithLamina(name, datasets, specs=None, coords=None)

Bases: tyssue.core.monolayer.Monolayer

3D monolayer epithelium with a lamina meshing

property lamina_edges

tyssue.core.multisheet module

class tyssue.core.multisheet.MultiSheet(name, layer_datasets, specs)

Bases: object

property Nes
property Nfs
property Nvs
concat_datasets()
property e_idxs
property f_idxs
update_interpolants()
property v_idxs

tyssue.core.objects module

Core definitions

class tyssue.core.objects.Epithelium(identifier, datasets, specs=None, coords=None, maxbackup=5)

Bases: object

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

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)

Returns a copy of the epithelium

deep_copybool, 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)

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

bboxsequence of shape (dim, 2)

the bounding box as (min, max) pairs for each coordinates.

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

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.

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

Returns a mask over self.edge_df for invalid faces.

get_neighborhood(elem_id, order, elem='cell')

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.

neighborspd.DataFrame with two colums, the index

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

get_neighbors(elem_id, elem='cell')

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

elem_idint

the index of the central element (a face or a cell)

element : {‘cell’ | ‘face’}, default ‘cell’

neghborsset

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

get_opposite_faces()

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)

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

centerstr,

the name of the center element for example ‘face’, ‘srce’

periphstr,

the name of the periphery elements, for example ‘trgt’, ‘cell’

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

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

idx_lookup(elem_id, element)

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

elem_idint

id of the element to retrieve

element{“vert”|”edge”|”face”|”cell”}

the corresponding dataset.

remove(edge_out, trim_borders=False, order_edges=False)

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)

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

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

restore()

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)

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)

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)

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

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

sum_face(df)

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

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

sum_srce(df)

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

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

sum_trgt(df)

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

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

triangular_mesh(coords=None, return_mask=False)

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

coordslist of str:

pair of coordinates corresponding to column names for self.face_df and self.vert_df

return_maskbool, optional, default True

if True, returns face_mask

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)

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

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

upcast_dfpd.DataFrame or pd.Series

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

upcast_cols(element, columns)

Syntactic sugar to upcast from the epithelium datasets.

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)

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

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

upcast_dfpd.DataFrame or pd.Series

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

upcast_srce(df)

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

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

upcast_dfpd.DataFrame or pd.Series

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

upcast_trgt(df)

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

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

upcast_dfpd.DataFrame or pd.Series

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

update_num_faces()

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

update_num_sides()

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

update_rank()
update_specs(new, reset=False)

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

returns True if the mesh is validated

e.g. has only closed polygons and polyhedra

validate_closed_cells()

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)

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

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.

tyssue.core.objects.euler_characteristic(edge_df)

Returns the Euler characteristic of the (non oriented) mesh represented by edge_df.

The Euler characteristic is the number of vertices minus the number of edges plus the number of faces

It is equal to 2 for a closed-on-itself mesh (topologicaly eq. to a sphere), 1 to a mesh with a border. It is not unique for monoloyers or bulk epithelia but provides a way to check wether a cell is closed.

tyssue.core.objects.get_next_edges(sheet)

returns a pd.Series with the index of the next edge for each edge

tyssue.core.objects.get_opposite_faces(eptm)
tyssue.core.objects.get_prev_edges(sheet)

returns a pd.Series with the index of the next edge for each edge

tyssue.core.objects.get_simple_index(edge_df)

returns a subset of the edge_df index corresponding to the non oriented edges (aka full edges).

This is faster than get_extra_indices and works also in 3D

tyssue.core.sheet module

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

For purely 2D the geometric properties are defined in

tyssue.geometry.planar_geometry

A dynamical model derived from Fahradifar et al. 2007 is provided in tyssue.dynamics.planar_vertex_model

For 2D in 3D, the geometric properties are defined in

tyssue.geometry.sheet_geometry

A dynamical model derived from Monier, Gettings et al. 2015 is provided in tyssue.dynamics.sheet_vertex_model

class tyssue.core.sheet.Sheet(identifier, datasets, specs=None, coords=None)

Bases: tyssue.core.objects.Epithelium

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'])

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

face_mask : column name in face composed by boolean value coords :

sheet_fold_patch_extract :

subsheet corresponding to the fold patch area.

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

Extracts a new sheet from the embryo sheet

that correspond to boundary coordinate define by the user.

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

subsheet : a new Sheet object

get_extra_indices()

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.

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

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

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 border of the tissue if True

edges_tensions: tension values array if column not define

get_neighborhood(face, order, elem='face')

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.

neighborspd.DataFrame with two colums, the index

of the neighboring face, and it’s neighboring order

get_neighbors(face, elem='face')

Returns the faces adjacent to face.

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

Creates a planar sheet from an hexagonal grid of cells.

identifier : string nx, ny : int

number of cells in the x and y axes

distx, distyfloat,

the distances in x and y between the cells

noisefloat, default None

position noise on the hexagonal grid

planar_sheet: a 2D Sheet instance

in the (x, y) plane

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

Creates a planar sheet from an hexagonal grid of cells.

identifier : string nx, ny : int

number of cells in the x and y axes

distx, distyfloat,

the distances in x and y between the cells

noisefloat, default None

position noise on the hexagonal grid

flat_sheet: a 2.5D Sheet instance

reset_topo()

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

sort_edges_eastwest()

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.

tyssue.core.sheet.get_opposite(edge_df, raise_if_invalid=False)

Returns the indices opposite to the edges in edge_df

tyssue.core.sheet.get_outer_sheet(eptm)

Return a Sheet object formed by all the faces w/o an opposite face.

Module contents