topact.spatial

Classes and methods for array-based spatial transcriptomics analysis.

Module Contents

Classes

ExpressionGrid

A spatial grid equipped with gene expressions.

Worker

Process objects represent activity that is run in a separate process

CountGrid

A spatial transcriptomics object with associated methods.

Functions

combine_coords(coords)

Combines a tuple of ints into a unique string identifier.

split_coords(ident)

Splits a unique identifier into its corresponding coordinates.

first_coord(ident)

Obtains the first coordinate from a unique identifier.

second_coord(ident)

Obtains the first coordinate from a unique identifier.

cartesian_product(x, y)

Computes the cartesian products of two 1-d vectors.

square_nbhd(point, scale, x_range, y_range)

All coordinates in a square neighbourhood about a point.

square_nbhd_vec(point, scale, x_range, y_range)

Returns a 2D array of all coords in a square nbhd about a point

extract_classifications(confidence_matrix, threshold)

Extracts a dictionary of all spot classifications given the threshold.

extract_image(confidence_matrix, threshold)

topact.spatial.combine_coords(coords)

Combines a tuple of ints into a unique string identifier.

Parameters

coords (Iterable[int]) –

Return type

str

topact.spatial.split_coords(ident)

Splits a unique identifier into its corresponding coordinates.

Parameters

ident (str) – A string of the form ‘{x1},{x2},…,{xn}’.

Returns

A tuple of integers (x1, x2, …, xn).

Return type

tuple[int, Ellipsis]

topact.spatial.first_coord(ident)

Obtains the first coordinate from a unique identifier.

Parameters

ident (str) – A string of the form ‘{x1},{x2},…,{xn}’ where n>=1.

Returns

The integer x1.

Return type

int

topact.spatial.second_coord(ident)

Obtains the first coordinate from a unique identifier.

Parameters

ident (str) – A string of the form ‘{x1},{x2},…,{xn}’ where n >= 2.

Returns

The integer x2.

Return type

int

topact.spatial.cartesian_product(x, y)

Computes the cartesian products of two 1-d vectors.

Parameters

  • x (numpy.typing.ArrayLike) – The first vector

  • y (numpy.typing.ArrayLike) – The second vector

Returns

An array of shape (len(x) * len(y), 2) whose rows are precisely all possible tuples with first value in x and second value in y.

Return type

numpy.typing.NDArray

topact.spatial.square_nbhd(point, scale, x_range, y_range)

All coordinates in a square neighbourhood about a point.

Parameters

  • point (tuple[int, int]) – the (x,y) coordinates of the point

  • scale (int) – the radius of the square

  • x_range (tuple[int, int]) – the least and greatest acceptable x values

  • y_range (tuple[int, int]) – the least and greated acceptable y values

Yields

All tuples (i,j) satisfying the following – - x_range[0] <= i <= x_range[1] - y_range[0] <= j <= y_range[1] - d(x,i) <= scale - d(y,j) <= scale

Return type

Iterator[tuple[int, int]]

topact.spatial.square_nbhd_vec(point, scale, x_range, y_range)

Returns a 2D array of all coords in a square nbhd about a point

Parameters

  • point (tuple[int, int]) – the (x,y) coordinates of the point

  • scale (int) – the radius of the square

  • x_range (tuple[int, int]) – the least and greatest acceptable x values

  • y_range (tuple[int, int]) – the least and greated acceptable y values

Returns

An array A of shape (n*m, 2) where n = x_range[1] - x_range[0] + 1 and m = y_range[1] - y_range[0] + 1, whose rows are precisely the elements of square_nbhd(point, scale, x_range, y_range).

Return type

numpy.typing.NDArray

topact.spatial.extract_classifications(confidence_matrix, threshold)

Extracts a dictionary of all spot classifications given the threshold.

Parameters

  • confidence_matrix (numpy.typing.NDArray) – A matrix X such that X[i, j, s, c] is the confidence that the cell type of spot (i, j) is c at scale s.

  • threshold (float) – The confidence threshold.

Returns

A dictionary d such that (i, j) is in d if and only if there is some scale s and cell type c so that confidence_matrix[i, j, s, c] >= threshold. Moreover, d[x,y] is the value of c corresponding to the lowest such value of s.

Return type

dict[tuple[int, int], int]

topact.spatial.extract_image(confidence_matrix, threshold)
Parameters

  • confidence_matrix (numpy.typing.NDArray) –

  • threshold (float) –

Return type

numpy.typing.NDArray

class topact.spatial.ExpressionGrid(table, genes, gene_col='gene', count_col='count')

A spatial grid equipped with gene expressions.

An ExpressionGrid encapsulates a 2D grid. For each coordinate (x,y) in the grid, we have a corresponding gene expression vector where each entry counts the number of reads of its corresponding gene.

Parameters

  • genes (Sequence[str]) –

  • gene_col (str) –

  • count_col (str) –

x_min

The smallest x coordinate in the grid.

y_min

The smallest y coordinate in the grid.

x_max

The largest x coordinate in the grid.

y_max

The largest y coordinate in the grid.

height

The height of the grid.

width

The width of the grid.

rows()

Returns a range of all row indices in the grid.

Return type

range

cols()

Returns a range of all column indices in the grid.

Return type

range

_flatten_coords(i, j)
Parameters

  • i (int) –

  • j (int) –

Return type

int

_flatten_coords_vec(coords)
Return type

numpy.typing.ArrayLike

expression(*coords)

The total expression at these coordinates in the grid

Parameters

coords (tuple[int, int]) –

Return type

scipy.sparse.spmatrix

expression_vec(coords)
Parameters

coords (numpy.typing.NDArray) –

Return type

scipy.sparse.spmatrix

square_nbhd(i, j, scale)

All coordinates (x,y) in the grid such that d(x,i), d(y-j) <= scale

Parameters

  • i (int) –

  • j (int) –

  • scale (int) –

Return type

Iterator[tuple[int, int]]

square_nbhd_vec(i, j, scale)
Parameters

  • i (int) –

  • j (int) –

  • scale (int) –

Return type

numpy.typing.NDArray

class topact.spatial.Worker(grid, min_scale, max_scale, classifier, job_queue, res_queue, procid, verbose)

Bases: multiprocessing.Process

Process objects represent activity that is run in a separate process

The class is analogous to threading.Thread

Parameters

  • grid (ExpressionGrid) –

  • min_scale (int) –

  • max_scale (int) –

  • classifier (topact.classifier.Classifier) –

  • job_queue (multiprocessing.Queue) –

  • res_queue (multiprocessing.Queue) –

  • procid (int) –

  • verbose (bool) –

run()

Method to be run in sub-process; can be overridden in sub-class

class topact.spatial.CountGrid(*args, **kwargs)

Bases: topact.countdata.CountTable

A spatial transcriptomics object with associated methods.

grid

An expression grid.

classmethod from_coord_table(table, **kwargs)
pseudobulk()
Return type

numpy.typing.NDArray

count_matrix()
Return type

numpy.typing.NDArray

density_mask(radius, threshold)
Parameters

  • radius (int) –

  • threshold (int) –

Return type

numpy.typing.NDArray

generate_expression_grid()
classify_parallel(classifier, min_scale, max_scale, outfile, mask=None, num_proc=1, verbose=False)
Parameters

  • classifier (topact.classifier.Classifier) –

  • min_scale (int) –

  • max_scale (int) –

  • outfile (str) –

  • mask (npt.NDArray | None) –

  • num_proc (int) –

  • verbose (bool) –

annotate(confidence_matrix, threshold, labels, column_label='cell type')
Parameters

  • confidence_matrix (numpy.typing.NDArray) –

  • threshold (float) –

  • labels (tuple[str, Ellipsis]) –

  • column_label (str) –