tyssue.core package¶
Submodules¶
tyssue.core.history module¶
-
class
tyssue.core.history.
History
(sheet, save_every=None, dt=None, extra_cols=None, save_all=True)[source]¶ Bases:
object
This class handles recording and retrieving time series of sheet objects.
Creates a SheetHistory instance.
- Parameters
sheet (a
Sheet
object which we want to record) –save_every (float, set every time interval to save the sheet) –
dt (float, time step) –
extra_cols (dictionnary with sheet.datasets as keys and list of) – columns as values. Default None
save_all (bool) – if True, saves all the data at each time point
-
property
cell_h
¶
-
property
edge_h
¶
-
property
face_h
¶
-
record
(to_record=None, time_stamp=None)[source]¶ Appends a copy of the sheet datasets to the history instance.
- Parameters
to_report (deprecated) –
-
retrieve
(time)[source]¶ 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)[source]¶ 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, extra_cols=None, hf5file='', overwrite=False)[source]¶ Bases:
tyssue.core.history.History
This class handles recording and retrieving time series of sheet objects.
Creates a SheetHistory instance.
- Parameters
sheet (a
Sheet
object which we want to record) –save_every (float, set every time interval to save the sheet) –
dt (float, time step) –
extra_cols (dictionnary with sheet.datasets as keys and list of) – columns as values. Default None
hf5file (string, define the path of the HDF5 file) –
overwrite (bool, Overwrite or not the file if it is already exist. Default False) –
-
record
(to_record=None, time_stamp=None, sheet=None)[source]¶ Appends a copy of the sheet datasets to the history HDF file.
- Parameters
to_report (Deprecated - list of strings) – the datasets from self.sheet to be saved
sheet (a
Sheet
object which we want to record. This argument can) –used if the sheet object is different at each time point. (be) –
-
retrieve
(time)[source]¶ 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)[source]¶ Bases:
tyssue.core.objects.Epithelium
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, ## Masks "is_alive": 1}, "vert": { ## Coordinates "x": 0., "y": 0., "z": 0., ## Masks "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
¶
-
get_sub_sheet
(segment)[source]¶ Returns a
Sheet
object of the corresponding segment- Parameters
segment (str, the corresponding segment, wether 'apical' or 'basal') –
-
property
lateral_edges
¶
-
property
lateral_faces
¶
-
property
lateral_verts
¶
-
class
tyssue.core.monolayer.
MonolayerWithLamina
(name, datasets, specs=None, coords=None)[source]¶ Bases:
tyssue.core.monolayer.Monolayer
3D monolayer epithelium with a lamina meshing
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, ## Masks "is_alive": 1}, "vert": { ## Coordinates "x": 0., "y": 0., "z": 0., ## Masks "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
lamina_edges
¶
tyssue.core.multisheet module¶
tyssue.core.objects module¶
Core definitions
-
class
tyssue.core.objects.
Epithelium
(identifier, datasets, specs=None, coords=None, maxbackup=5)[source]¶ Bases:
object
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, ## Masks "is_alive": 1}, "vert": { ## Coordinates "x": 0., "y": 0., "z": 0., ## Masks "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
-
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_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
orpd.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
orpd.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
orpd.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
orpd.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_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
-
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.
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)[source]¶ 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
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
-
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