spateo.digitization.utils

Written by @Jinerhal, adapted by @Xiaojieqiu.

Functions

fill_grid_label(→ Tuple[numpy.ndarray, numpy.ndarray])

Assign the interior/exterior layer, column and grid to each bucket.

order_borderline(→ Tuple[List, numpy.ndarray])

Retrieve the borderline segment given the start end end point with the coordinates ordered.

draw_seg_grid(→ Optional[numpy.ndarray])

Draw the grid lines for each layer and column.

euclidean_dist(→ float)

Caluate the euclidean distance between two points.

segment_bd_line(borderline_list, column_num)

Segment the borderline into column_num even segments based on the arclength along the borderline.

extend_layer(→ Tuple[numpy.ndarray, List])

Extend the layer to both interior ane exterior sides.

field_contour_line(→ list)

Retrieve the field contour line give min and max values from an ordered set of contour points.

field_contours(→ Tuple[numpy.ndarray, numpy.ndarray, ...)

Identify four boundary lines according to given corner points.

add_eh_boundary(→ None)

Set equal heat value to the boundary line on the heat field.

add_gh_boundary(→ None)

Increase heat value progressively along the boundary line on the heat field.

effective_L2_error(→ float)

Calculate effective L2 error between two fields.

domain_heat_eqn_solver(→ numpy.ndarray)

Given the boundaries and boundary conditions of a close spatial domain, solve heat equation (a simple partial

digitize_general(→ numpy.ndarray)

Calculate the "heat" for a general point cloud of interests by solving a PDE, partial differential equation,

Module Contents

spateo.digitization.utils.fill_grid_label(adata: anndata.AnnData, spatial_key: str, seg_grid_img: numpy.ndarray, bdl_seg_coor_x: numpy.ndarray, bdl_seg_coor_y: numpy.ndarray, curr_layer: int, curr_sign: int, layer_label_key: str = 'layer_label', column_label_key: str = 'column_label', init: bool = False) Tuple[numpy.ndarray, numpy.ndarray][source]

Assign the interior/exterior layer, column and grid to each bucket.

Parameters:
adata

The adata object to be used for assign the interior/exterior layers, columns and grid.

spatial_key

The key name in adata.obsm of the spatial coordinates. Default to “spatial”. Passed to fill_grid_label function.

seg_grid_img

The matrix that stores the image information of the borderline between the source and target cluster(s), as well as the i and i+1-th borderlines.

bdl_seg_coor_x

The numpy array of the coordinates of the i-th borderline.

bdl_seg_coor_y

The numpy array of the coordinates of the i+1-th borderline.

curr_layer

The number of the current layer.

curr_sign

The sign of the current layer.

layer_label_key

The key in .obs that points to the key of the layer labels.

column_label_key

The key in .obs that points to the key of the column labels.

init

Whether to generate (and potentially overwrite) the layer_label_key and column_label_key in fill_grid_label function.

Returns:

A numpy array that store the image of the layers and layer grids. column_grid_img: A numpy array that store the image of the columns and column grids.

Return type:

layer_grid_img

spateo.digitization.utils.order_borderline(borderline_img: numpy.ndarray, pt_start: Tuple[int, int], pt_end: Tuple[int, int]) Tuple[List, numpy.ndarray][source]

Retrieve the borderline segment given the start end end point with the coordinates ordered.

Parameters:
borderline_img

The matrix that stores the image of the borderline.

pt_start

The coordinate tuple of the start point.

pt_end

The coordinate tuple of the start point.

Returns:

List of points along the borderline segment. ordered_bdl_img: A numpy aray that stores the image of the borderline segment.

Return type:

ordered_bdl_list

spateo.digitization.utils.draw_seg_grid(borderline_img, bdl_seg_coor_x, bdl_seg_coor_y, gridline_width=1, mode='grid') numpy.ndarray | None[source]

Draw the grid lines for each layer and column.

Parameters:
borderline_img

The matrix that stores the image information of the borderline between the source and target cluster(s).

bdl_seg_coor_x

The coordinate of i-th layer.

bdl_seg_coor_y

The coordinate of i+1-th (the consecutive) layer.

gridline_width

Linewidth of the grid.

mode

The mode to draw the grid line.

Returns:

When mode is set to be grid, a matrix with the gridlines is created.

spateo.digitization.utils.euclidean_dist(point_x: Tuple, point_y: Tuple) float[source]

Caluate the euclidean distance between two points.

spateo.digitization.utils.segment_bd_line(borderline_list: List, column_num: int)[source]

Segment the borderline into column_num even segments based on the arclength along the borderline.

Parameters:
borderline_list

An order list of np.arrays of coordinates of the borderlines.

column_num

Number of columns to segment for each layer.

Returns:

The list of the segmentation points.

Return type:

seg_point_ls

spateo.digitization.utils.extend_layer(borderline_img: numpy.ndarray, borderline_list: List, extend_width=10) Tuple[numpy.ndarray, List][source]

Extend the layer to both interior ane exterior sides.

Parameters:
borderline_img

The matrix that stores the image information of the borderline between the source and target cluster(s).

borderline_list

An order list of np.arrays of coordinates of the borderlines.

extend_width

The layer width to extend.

Returns:

The matrix that stores the extended layer image. extend_layer_bdl: The list of extended layer borderline.

Return type:

extend_layer_img

spateo.digitization.utils.field_contour_line(ctr_seq: numpy.ndarray, pnt_pos: numpy.ndarray, min_pnt: Tuple[int, int], max_pnt: Tuple[int, int]) list[source]

Retrieve the field contour line give min and max values from an ordered set of contour points.

Parameters:
ctr_seq

The numpy array that stores the ordered list of points on the contour.

pnt_pos

The array that tags the position of all four corner points.

min_pnt

The point corresponds to the position with minimal heat value.

max_pnt

The point corresponds to the position with maximal heat value.

Returns:

The line segment that starts from the point with the minimal heat value to the point with maximal heat value.

Return type:

line_seq

spateo.digitization.utils.field_contours(contour: numpy.ndarray, pnt_xy: Tuple[int, int], pnt_Xy: Tuple[int, int], pnt_xY: Tuple[int, int], pnt_XY: Tuple[int, int]) Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray][source]

Identify four boundary lines according to given corner points.

Parameters:
contour

Contours generated by cv2.findContours.

pnt_xy

Corner point to define an area of interest. pnt_xy corresponds to the point with minimal layer and minimal column value.

pnt_Xy

Corner point corresponds to the point with maximal column value but minimal layer value.

pnt_xY

Corner point corresponds to the point with minimal column value but maximal layer value.

pnt_XY

Corner point corresponds to the point with maximal layer and maximal columns value.

Returns:

The np array of the points on the layer with minimal layer heat values. max_line_l: The np array of the points on the layer with maximal layer heat values. min_line_c: The np array of the points on the layer with minimal column heat values. max_line_c: The np array of the points on the layer with maximal column heat values.

Return type:

min_line_l

spateo.digitization.utils.add_eh_boundary(heat_field: numpy.ndarray, field_line: numpy.ndarray, value: float) None[source]

Set equal heat value to the boundary line on the heat field.

Parameters:
heat_field

The field of the spatial domain of interests.

field_line

The isoline on the field of the spatial domain of interests.

value

The value that will be assigned to the isoline.

Returns:

Nothing but set the provided isoline to the specific value.

spateo.digitization.utils.add_gh_boundary(heat_field: numpy.ndarray, field_line: numpy.ndarray, value_s: float, value_e: float) None[source]

Increase heat value progressively along the boundary line on the heat field.

Parameters:
heat_field

the field of the spatial domain of interest

field_line

The line on the field of the spatial domain of interests that should have increasing heat values.

value_s

Source heat value.

value_e

End heat value.

Returns:

Nothing but set the provided line to the growing heat value.

spateo.digitization.utils.effective_L2_error(heat_field_i: numpy.ndarray, heat_field_j: numpy.ndarray, field_mask: numpy.ndarray) float[source]

Calculate effective L2 error between two fields.

Parameters:
heat_field_i

The target field used in solving the heat equation.

heat_field_j

The source field used in solving the heat equation.

field_mask

The domain of interests (1 if inside the domain and 0 otherwise).

Returns:

A float variable of the L2 difference between two fields, normalized by the source field.

spateo.digitization.utils.domain_heat_eqn_solver(heat_field: numpy.ndarray, min_line: numpy.ndarray, max_line: numpy.ndarray, edge_line_a: numpy.ndarray, edge_line_b: numpy.ndarray, field_border: numpy.ndarray, field_mask: numpy.ndarray, max_err: float = 1e-20, max_itr: float = 1000000.0, lh: float = 1, hh: float = 100) numpy.ndarray[source]

Given the boundaries and boundary conditions of a close spatial domain, solve heat equation (a simple partial differential equation) to define the “heat” for each spatial pixel which can be used to digitize the spatial domain into different layers or columns. Diffusitivity is set to be 1/4, thus the update rule is defined as:

grid_field[1:-1, 1:-1] = 0.25 * (

grid_field_pre[1:-1, 2:] + grid_field_pre[1:-1, :-2] + grid_field_pre[2:, 1:-1] + grid_field_pre[:-2, 1:-1]

)

Parameters:
heat_field

The field of the spatial domain of interests.

min_line

The np array of the isoline points with minimal heat values.

max_line

The np array of the isoline points with maximal heat values.

edge_line_a

The np array of the points with increasing heat values, orthogonal to the isolines.

edge_line_b

The np array of the points with increasing heat values, orthogonal to the isolines.

field_border

The border of the field of the spatial domain of interests.

field_mask

The field of the spatial domain of interests, used for masking.

max_err

The maximal tolerated error. Default to 1e-5.

max_itr

The maximal diffusion iteration error. Default to 1e5.

lh

Lowest heat value. Defaults to 1.

hh

Highest heat value. Defaults to 100.

Returns:

The resultant field filled with final values after solving the heat equation.

Return type:

grid_field

spateo.digitization.utils.digitize_general(pc: numpy.ndarray, adj_mtx: numpy.ndarray, boundary_lower: numpy.ndarray, boundary_upper: numpy.ndarray, max_itr: int = 1000000.0, lh: float = 1, hh: float = 100) numpy.ndarray[source]

Calculate the “heat” for a general point cloud of interests by solving a PDE, partial differential equation, the heat equation. The two polar boundaries are given by their indices within the point cloud. The neighbor network of the point cloud is given as an adjacency matrix.

Parameters:
pc

An array of 3-D coordinates, representing the point cloud.

adj

A 2-D adjacency matrix of the neighbor network.

boundary_low

The indices of points selected as lower boundary in the point cloud.

boundary_low

The indices of points selected as upper boundary in the point cloud.

max_itr

Maximum number of iterations dedicated to solving the heat equation.

lh

lowest digital-heat (temperature). Defaults to 1.

hh

highest digital-heat (temperature). Defaults to 100.

Returns:

An array of “heat” values of each point in the point cloud.