DLITE package

Submodules

DLITE.AICS_data module

class DLITE.AICS_data.data(v, t)

Bases: object

add_edge(node_a, node_b, index=None, x=None, y=None)

Define an edge given a branch index and end nodes of class node Calls fit() to fit a curve to the data set ———– :Parameters: * node_a - node object at one end of the edge

• node_b - node object at other end of the edge
• index = Branch location. If this is specified, can get the x and y co-ordinates
• of this branch location from data
• If index is not specified, x and y need to be provided.
• x - x co-ordinates along the edge
• y - y co-ordinates along the edge

add_node(index, f_or_l)

Define a node on branch “index” and location on branch “f_or_l” (str)

compute(cutoff, nodes=None, edges=None)

Computation process. Steps -> (1) Call post_processing() -> returns nodes and edges (2) Call which_cell() for each edge -> returns cells (3) Define colony (4) Call calculate_tension() - find tensions

1. If any bad edges (> 3 std away, call remove_outliers() and repeat computation)

5. Call calculate_pressure() - find pressure

static find_cycles(edges)

Find cycles given a list of edges. Takes a list of edges and for every edge, gives a maximum of 2 cells that its connected to This method calls which_cell which in turn calls recursive_cycle_finder

fit(x, y)

Parameters:x, y

plot(ax, type=None, num=None, **kwargs)

Parameters:

• ax - axes to be plotted on
• type - “edge_and_node”, “node”, “edge”, “image” - specifying what you want to plot
• num - number of branches to be plotted

post_processing(cutoff, num=None)

post process the data to merge nodes that are within a distance specified as ‘cutoff’. Also calls functions (1) remove_dangling_edges (2) remove_two_edge_connections ———- :Parameters: * cutoff - distance within which we merge nodes

• num (optional) - Number of branches to consider (default - all of them)

remove_dangling_edges(nodes, edges)

Clean up nodes connected to 1 edge Do this by - Removing edges that are really small and connected to 2 other edges at a nearly 90 deg angle Also remove edges that are connected to nobody else

remove_small_cells(nodes, edges)

Clean up small cells that have a small perimeter

remove_two_edge_connections(nodes, edges)

Clean up nodes connected to 2 edges

x(index, f_or_l)

Returns x co-ordinate of branch number “index” at branch end “f_or_l” If f_or_l (str value - ‘first’, or ‘last’) not specified,

returns all x co-ordinates along the branch

Parameters:

• index - index of branch in the list of branches in the data
• f_or_l - either first or last index on a branch

y(index, f_or_l)

Returns y co-ordinate of branch number “index” at branch end “f_or_l” If f_or_l (str value - ‘first’, or ‘last’) not specified, returns all y co-ordinates along the branch ————- :Parameters: * index - index of branch in the list of branches in the data

• f_or_l (str) - either “first” or “last” index on a branch

DLITE.Lloyd_relaxation_class module

class DLITE.Lloyd_relaxation_class.Atlas(points=array([], dtype=float64), dimensions=(None, None), granularity=None)

Bases: object

Creates a voronoi object, relaxes it as needed, and returns it as a layout. Implements Fortune’s Algorithm (https://en.wikipedia.org/wiki/Fortune%27s_algorithm) in python. 1. Takes in a 2D numpy array (or generates points with given boundaries) 2. Creates a tuple of two graphs (with networkx) representing the Delaunay triangulation (https://en.wikipedia.org/wiki/Delaunay_triangulation) 3. Relaxes the points through Lloyd’s Algorithm (https://en.wikipedia.org/wiki/Lloyd%27s_algorithm) 4. Returns a Voronoi diagram (http://www.voronoi.com/wiki/index.php?title=Main_Page)

generate_voronoi()

Uses scipy.spatial.Voronoi to generate a voronoi diagram. Filters viable regions and stashes them in filtered_regions, see https://stackoverflow.com/questions/28665491/getting-a-bounded-polygon-coordinates-from-voronoi-cells :return: A voronoi diagram based on the points :rtype: scipy.spatial.Voronoi

relax_points(times=1)

Relaxes the points after an initial Voronoi is created to refine the graph. See: https://stackoverflow.com/questions/17637244/voronoi-and-lloyd-relaxation-using-python-scipy :param times: Number of times to relax, default is 1 :type times: int :return: the final voronoi diagrama :rtype: scipy.spatial.Voronoi

DLITE.ManualTracing module

class DLITE.ManualTracing.ManualTracing(x, y, ground_truth_tensions=None)

Bases: DLITE.AICS_data.data

cleanup(cutoff)

post process the data to merge nodes that are within a distance specified as ‘cutoff’. Also calls functions (1) remove_dangling_edges (2) remove_two_edge_connections ———- :Parameters: * cutoff - distance within which we merge nodes

• num (optional) - Number of branches to consider (default - all of them)

co_ordinates(edge_num)

Get X and Y co-ordinates for specified edge number

fit_X_Y(edge_num)

Fit a circular arc to an edge. Call self.fit - .fit is a function in the data class

DLITE.ManualTracingMultiple module

class DLITE.ManualTracingMultiple.ManualTracingMultiple(numbers, name_first=None, name_last=None, type=None)

Bases: object

alternative_computation_based_on_prev(numbers, colonies=None, index=None, old_dictionary=None, solver=None, **kwargs)

Same as above, except can store colonies in a dictionary numbered as their input time points

assign_intial_guesses(now_nodes, now_cells, old_cells, edges2, old_edges)

Process - (1) Call track_timestep - this assigns a generic labeling of nodes and cells to number_old (by calling initial_numbering) and also retrieves a dictionary relating each labelled node to its connected edge vectors. It then assigns labels to nodes, edges and cells in number_now based on this older timestep. Summary This function gives you labelled nodes and cells for number_now and number_old (edges saved in dictionary - combined_dict) (2) Assign ‘guess tension/pressure’ (for number_now) based on the ‘true tension/pressure’ (for number_old) by matching labels

first_computation(number_first, solver=None, type=None, **kwargs)

Main first computation Retuns a colony at number_first :Parameters: number_first - number specifying first time step

get_nodes_edges_cells(number)

Get nodes, edges and cells at time point number these nodes, edges and cells do not have any labels CHECK - cutoff values used, need to go to every frame and check to see if cutoff works or not

get_x_y_data(number)

Retrieve X and Y co-ordinates of a colony at a time point specified by number

initial_numbering(number0)

Assign random labels to nodes, edges and cells in the colony specified by number0 Returns labeled nodes, edges and cells. Also returns a dictionary defined as {node.label: edges connected to node label, vectors of edges connected to node label}

label_cells(old_cells, now_cells)

Now_nodes is the list of nodes at the current time step These nodes have labels based on previous time steps old_cells - cells from prev time step now_cells - cells in current time step

main_computation_based_on_prev(numbers, colonies=None, index=None, old_dictionary=None, solver=None, **kwargs)

Recursive loop that cycles through all the time steps Steps - (1) Call self.first_computation() - returns first colony with generic labeling (2) Call self.track_timestep() - returns new colony that used info in the old colony to assign some initial guesses for tensions and pressures. saved in edge.guess_tension and cell.guess_pressure (3) Calculate tension and pressure on the new colony (4) Call this function again. Keep doing this till we reach the max number (5) Return colonies

track_timestep(old_colony, old_dictionary, number_now)

We want to output a dictionary that contains a list of edges in number_now that is the same (almost) as the edges in old_colony ———– :Parameters: * old_colony - colony instance for the previous time step

• old_dictionary - dictionary for the colony instance in old_colony {node.label (edges, vectors})
• number_now - number of current time point

DLITE.PlottingFunctions module

class DLITE.PlottingFunctions.PlottingFunctions

Bases: object

all_perims_areas_lengths(colonies)

Return all unique edge tensions, edge radii and cell pressures in all colonies Used in plotting functions

all_tensions_and_radius_and_pressures(colonies)

Return all unique edge tensions, edge radii and cell pressures in all colonies Used in plotting functions

check_repeat_labels(colonies, max_num)

Find node labels that are present in a specified number of colonies Used in plotting functions

get_min_max_by_outliers_iqr(ys, type=None)

Get the maximum and minimum of a data set by ignoring outliers uses interquartile method code from - http://colingorrie.github.io/outlier-detection.html

get_repeat_cell(colonies)

Get a list of cell_labels that are present in all colonies provided (repeat labels) used in plotting functions

get_repeat_edge(colonies)

Get a list of edge_labels that are present in all colonies provided (repeat labels) used in plotting functions

get_repeat_nodes(colonies)

Get a list of node_labels that are present in all colonies provided (repeat labels) used in plotting functions

outliers_modified_z_score(ys, y)

Alternative outlier check. Not used currently useful for plotting

plot_abnormal_edges(fig, ax, colonies_1, abnormal)

PLOTTING FUNCTION Abnormal edges defined as edges with large stochasticity :Parameters: * colonies_1 - colony class with calculated tensions and pressures

• abnormal - of the form [[edge_label, time]]

plot_both_tension_pressure(fig, ax, colonies, specify_aspect=None, specify_color=None, **kwargs)

PLOTTING FUNCTION Make a combined tension + pressure movie over colonies

plot_compare_single_edge_tension(fig, ax, ax1, colonies_1, colonies_2, edge_label, type=None, ground_truth=None, xlim_end=None)

PLOTTING FUNCTION Plot single edge over time specified by edge label (dont really use node_label) Also plots Tension of that edge store2 in colonies_1 Tension of that edge stored in colonies_2 Meant to be used as a comparison of 2 methods - CELLFIT, unconstrained

plot_guess_pressures(fig, ax, ax1, colonies, cell_label)

Plot single cell over time specified by cell_label ALso plots Pressure of that cell, guess pressure of that cell

plot_guess_tension(fig, ax, ax1, colonies, node_label, edge_label)

PLOTTING FUNCTION Plot edge over time specified by edge_label Also plots Tension of that edge, guess tension of that edge Should be offset

plot_histogram(fig, ax, ax1, ax2, colonies)

PLOTTING FUNCTION Plots a histogram of tensions and pressures over time

plot_pressures(fig, ax, colonies, specify_aspect=None, specify_color=None, **kwargs)

PLOTTING FUNCTION Make a pressure movie over colonies

plot_single_cells(fig, ax, ax1, ax3, colonies, cell_label)

PLOTTING FUNCTION Make a movie tracking showing the evolution of a single cell over time, specified by cell_label Also plots Pressure, Perimeter, Area and Change in area of that cell over time

plot_single_edges(fig, ax, ax1, ax3, colonies, node_label, edge_label)

PLOTTING FUNCTION Plots a single edge over time specified by edge_label (dont really use node_label, used it before when i wasnt tracking edge labels explicitly) Also plots tension, straight_length, radius and change in straight_length of that edge

plot_single_nodes(fig, ax, label, colonies, max_num)

PLOTTING FUNCTION Plot the edges connected to a node specified by label :Parameters: * label - label of node that is present in all colonies specified by colonies

• colonies - dictionary of colonies

plot_tensions(fig, ax, colonies, min_x=None, max_x=None, min_y=None, max_y=None, min_ten=None, max_ten=None, specify_aspect=None, specify_color=None, type=None, **kwargs)

PLOTTING FUNCTION Make a tension movie (colormap) for all timepoints of the colony

plot_tensor_dataframe(ax, colonies, tensor_dataframe)

PLOTTING FUNCTION Make strain rate movie

seaborn_cells_dataframe_tensor(colonies, jump_number=1, data=None)

DATAFRAME FUNCTION Make a tensor dataframe, tracks movement over time calculates strain, rotation, velocities etc.

seaborn_nodes_dataframe(colonies, data, old_labels=None, counter=None)

DATAFRAME FUNCTION Make nodes_dataframe which containts node related information like number of connected edges, tension residual, average curvature of conn edges etc.

seaborn_plot(ax, colonies, common_edge_labels, common_cell_labels, data=None, cell_data=None, old_labels=None, old_cell_labels=None, counter=None, min_ten=None, max_ten=None, min_pres=None, max_pres=None, ground_truth=None)

DATAFRAME FUNCTION Make an edges_dataframe and cells_dataframe Edges dataframe has information about tension, stochasticity in tension etc. Cells dataframe has information about pressure, stochasticity in pressure etc.

single_edge_plotting(fig, ax, ax1, ax3, colonies, node_label, edge_label)

PLOTTING FUNCTION This is a function that is called by plot_single_edges (the next function)

DLITE.SaveSurfEvolFile module

class DLITE.SaveSurfEvolFile.SaveFile(filename, voronoi)

Bases: object

add_gogo3(tension, begin_id, end_id)

Function to add gogo3 function to the end of .txt file It sets a specified tension to all edge labels within a specified range (begin_id, end_id)

save()

Save method that saves a given filename and Voronoi tessellation in Surface Evolver format This format is defined as

SRING space_dimension vertices … edges … faces … bodies … gogo …

DLITE.SurfaceEvolver module

class DLITE.SurfaceEvolver.SurfaceEvolver(name_first, name_end)

Bases: object

FOV_Drift(number, num_of_frames=1.8, cleanup_cutoff=0.5, Whole_FOV_colony=None, colonies=None, index=None, old_dictionary=None, solver=None, minx=None, maxx=None, miny=None, maxy=None, step_x=None, step_y=None, **kwargs)

Calculation tensions in different FOV’s of a given Surface Evolver colony

assign_intial_guesses(now_nodes, now_cells, old_cells, edges2, old_edges)

Process - (1) Call track_timestep - this assigns a generic labeling of nodes and cells to number_old (by calling initial_numbering) and also retrieves a dictionary relating each labelled node to its connected edge vectors. It then assigns labels to nodes, edges and cells in number_now based on this older timestep. Summary This function gives you labelled nodes and cells for number_now and number_old (edges saved in dictionary - combined_dict) (2) Assign ‘guess tension/pressure’ (for number_now) based on the ‘true tension/pressure’ (for number_old) by matching labels

computation_based_on_prev_surface_evolver(numbers, cleanup_cutoff=0.5, colonies=None, index=None, old_dictionary=None, solver=None, **kwargs)

Recursive loop that cycles through all the time steps Steps - (1) Call self.first_computation() - returns first colony with generic labeling (2) Call self.track_timestep() - returns new colony that used info in the old colony to assign some initial guesses for tensions and pressures. saved in edge.guess_tension and cell.guess_pressure (3) Calculate tension and pressure on the new colony (4) Call this function again. Keep doing this till we reach the max number (5) Return colonies

compute(name, solver='KKT')

Conpute tensions and pressure for a single colony

first_computation(number_first, cleanup_cutoff=0.5, min_x=None, max_x=None, min_y=None, max_y=None, Whole_FOV_colony=None, solver=None, type=None, **kwargs)

Main first computation Retuns a colony at number_first :Parameters: number_first - number specifying first time step

static get_FOV(whole_FOV_colony, min_x, max_x, min_y, max_y)

Given a colony, return nodes, edges and cells within a specified FOV

get_X_Y_data_only_junction(name, cleanup_cutoff=0.5)

Read Surface Evolver .txt file and save as colony class

initial_numbering(number0, min_x=None, max_x=None, min_y=None, max_y=None, Whole_FOV_colony=None, cleanup_cutoff=0.5)

Assign random labels to nodes and cells in the colony specified by number0 Returns labeled nodes and cells. Also returns a dictionary defined as {node.label: edges connected to node label, vectors of edges connected to node label} Also returns the edge list (not labeled)

label_cells(old_cells, now_cells)

Now_nodes is the list of nodes at the current time step These nodes have labels based on previous time steps old_cells - cells from prev time step now_cells - cells in current time step

track_timestep(old_colony, old_dictionary, number_now, min_x=None, min_y=None, max_x=None, max_y=None, Whole_FOV_colony=None, cleanup_cutoff=0.5)

We want to output a dictionary that contains a list of edges in number_now that is the same (almost) as the edges in old_colony ———– :Parameters: * old_colony - colony instance for the previous time step

• old_dictionary - dictionary for the colony instance in old_colony {node.label (edges, vectors})
• number_now - number of current time point

DLITE.cell_describe module

class DLITE.cell_describe.cell(nodes, edges)

Bases: object

area()

Calculate area of this cell, got this online

centroid()

Centroid of this cell, calculated as a mean of co-ordinates of all nodes that make up this cell

colony_cell

The colony that this cell is a part of (only one colony, this is not really useful)

ground_truth_pressure

guess_pressure

Guess pressure used as an initial condition during optimization

label

Assign a label to this cell to track it over time

perimeter()

Perimeter of this cell (calculated as sum of straight lengths of every edge, need to add curvature of this edge)

plot(ax, **kwargs)

Plot the cell on a given axis

pressure

Pressure of this cell

class DLITE.cell_describe.colony(cells, edges, nodes)

Bases: object

add_cell(c)

Add a cell to the colony, dont really use this anywhere

calculate_pressure(solver=None, **kwargs)

Calculate pressure using calculated tensions and edge curvatures (radii). Pressure is unique to every cell

calculate_tension(nodes=None, edges=None, solver=None, **kwargs)

Calls a solver to calculate tension. Cellfit paper used (1) self.solve_constrained_lsq We use (2) self.scipy_opt_minimize This optimization is slower but allows us to set initial conditions, bounds, constraints

dictionary

edges connected to node label: edge vector with horizontal}

Type:Dictionary of the form {node label

edges

Edges is not the total list of edges - that is tot_edges. This gives list of edges that make up cells

equality_constraint_pressure(x)

Assigns equality constraint - i.e mean of pressures = 0

equality_constraint_tension(x)

Assigns equality constraint - i.e mean of tensions = 1

get_adjacent_pressures(e_or_c)

Get a list of adjacent pressures of adjacent tensions if there is no initial guess for this edge tension or cell pressure

initial_conditions(edge_or_cell)

Define initial conditions based on previous solution for tension/pressure :Parameters: edge_or_cell - list of edge or cells (variables)

make_bounds(edge_or_cell)

Define bounds. Possible to be based on the initial guess of tension or pressure :Parameters: edge_or_cell - list of edges or cells (variables)

make_pressure_matrix()

Make pressure matrix A and rhs matrix (AX = rhs) A is m * n matrix m is number of equations - equals number of edges that have 2 cells on either side n is number of cells rhs is m * 1 matrix - each element is tension/radius

make_tension_matrix(nodes=None, edges=None)

Makes a tension matrix A A is the coefficient vectors of all the edges coming into a node A is m * n matrix. m is number of equations, which is 2 * number of nodes that have atleast 3 edges coming into it (2 * because both horizontal and vertical force balance). n is number of edges. This includes stray edges (not part of a cell). Called by self.tot_edges

nodes

Nodes is not the total list of nodes - that is tot_nodes. This gives list of nodes that make up cells

objective_function_pressure(x)

Main objective function to be minimzed in the pressure calculation i.e sum((row - rhs)^2). We need rhs here because in the pressure case rhs is not 0.

objective_function_tension(x)

Main objective function to be minimized in the tension calculation i.e sum(row^2) for every row in tension matrix A + a regularizer based on Tikhonov regularization for overdetermined problems see - https://epubs.siam.org/doi/pdf/10.1137/050624418

plot(ax, fig, tensions, pressures, min_ten=None, max_ten=None, min_pres=None, max_pres=None, specify_color=None, **kwargs)

Plot both tensions and pressures on a single axes

plot_pressures(ax, fig, pressures, min_x=None, max_x=None, min_y=None, max_y=None, min_pres=None, max_pres=None, specify_color=None, cbar='yes', **kwargs)

Plot normalized pressures (mean, std) with colorbar

plot_tensions(ax, fig, tensions, min_x=None, max_x=None, min_y=None, max_y=None, min_ten=None, max_ten=None, specify_color=None, type=None, cbar='yes', **kwargs)

Plot normalized tensions (min, width) with colorbar

pressure_matrix

Store the calculated pressure matrix as a property

pressure_rhs

Save the RHS of pressure equation as a property

remove_outliers(bad_tensions, tensions)

Parameters:

• bad_tensions - values of tensions that are more than 3 std away
• tensions - list of all edge tensions

scipy_opt_minimze(edges, i=[0], **kwargs)

Calls minimize function from scipy optimize. Parameters: ———————- edges - really either edges (for tension calculation) or cells (for pressure calculation). Just give the solver a list of variables and it will give a solution

static solve_constrained_lsq(a, t_or_p, b=None)

Solve constrained least square system PX = Q.

Parameters:

• A is an M * N matrix comprising M equations and N unknowns
• B is an N * 1 matrix comprising RHS of the equations
• Type specifies the Lagrange multiplier we use - 0 or 1
• For type 0 -> (For tension)
• Define a matrix P = [[A^TA, C^T],[C, 0]] - > (N + 1) * (N + 1) matrix – Q = [0…, N] -> (N + 1) * 1 matrix
• For type 1 -> (For pressure)
• Define a matrix P = [[A^TA, C^T],[C, 0]] - > (N + 1) * (N + 1) matrix – Q = [B, 0] -> (N + 1) * 1 matrix

tension_matrix

Store the calculated tension matrix as a property

class DLITE.cell_describe.edge(node_a, node_b, radius=None, xc=None, yc=None, x_co_ords=None, y_co_ords=None)

Bases: object

arc_translation(point1, point2, radius)

Get arc center and angles from endpoints and radius We want to be able to plot circular arcs on matplotlib axes. Matplotlib only supports plotting such by giving the center, starting angle, and stopping angle for such. But we want to plot using two points on the circle and the radius. For explanation, check out https://tinyurl.com/ya7wxoax

cell_coefficients

List of cell co-efficents - not sure where i used this

cell_indices

Make a list of cell indices from list of cells in colony - set during pressure matrix calculation

cell_rhs

RHS of pressure matrix equation, i.e tension/radius

cells

List of cells that this edge is a part of

center_of_circle

Center of circle that sets the radius of this edge

co_ordinates

List of co-ordinates along this edge

connected_edges

The edges connected to nodes a and b

convex_concave(cell1, cell2)

Parameters:

• cell1, cell2
• Returns which of the 2 cells the edge (self) is curving out of

curve_fit_residual

edge_angle(other_edge)

What is the angle between this edge and another edge connected at a node?

ground_truth

Tension of this edge

guess_tension

Initial guess for tension based on the same edge at a previous time point

kill_edge(n)

Kill edge for a specified node i.e kill the edge and tension vector associated with the specified node Parameters - n (a node)

label

Give a label to a node so we can track it over time

nodes

Set of nodes that comprise this edge

plot(ax, **kwargs)

Plot edges using matplotlib.patches.arc, requires a circle center, radius of arc and starting and ending angle

plot_fill(ax, resolution=50, **kwargs)

Similar to plot, only difference is arc is now filled, needed for pressure colormap diagram

previous_label

Label of this edge at the previous time point

recursive_cycle_finder(edge1, edge2, ty, cell_nodes, cell_edges, p, max_iter)

Apply a recursion algorithm until we find a cycle This function is called by which_cell() ———- :Parameters: * edge1 and edge2 - 2 edges connected by a common node

• ty - 0 or 1 - decides which direction to search (0 for max negative angle, 1 for min positive)
• cell_nodes - list of current cell nodes
• cell_edges - list of current cell edges
• p - A count of iterations - only for use in this function
• max_iter - A specified value of max iterations to be performed after which we stop recursion

straight_length

The distance from node A to node B

tension

Tension of this edge

unit_vectors()

What are the unit vectors of the angles the edge makes as it goes into nodes A and B? Unlike _edge_angle, this accounts for the curvature of the edge.

which_cell(list_of_edges, ty, max_iter)

Find which cell the current edge is a part of. Algorithm starts from node_a and looks for a cycle that reaches node_b

Parameters:

• List_of_edges - List of all the edges in the colony
• ty – 0 for choosing only the minimum positive angles – – 1 for choosing only the maximum negative angles
• Return -
• ———-
• Cell -> smallest cell that self is a part of

class DLITE.cell_describe.node(loc)

Bases: object

edge_indices

Indices of edges connected to this node in the list of all edges in colony

edges

List of edges connected to this node

horizontal_vectors

List of x-component of tension vectors connected to this node

label

Give a label to a node so we can track it over time

plot(ax, **kwargs)

Plot node as a point

previous_label

Label of this node at previous time point

previous_tension_vectors

Tension vectors connected to this node at previous time point

remove_edge(edge)

Remove an edge and tension vector connected to this node

residual_vector

Give a label to a node so we can track it over time

tension_vectors

Tension vectors connected to this node

velocity_vector

Velocity vector computed from distance traveled in time from previous time point

vertical_vectors

List of y-component of tension vectors connected to this node

x

x co-ordinate of node

y

y co-ordinate of node

Module contents

Top-level package for DLITE.

DLITE.get_module_version()