Running Gromov-Wasserstein
- class cajal.run_gw.Distribution
A
run_gw.Distribution
is a numpy array of shape (n,), with values nonnegative and summing to 1, where n is the number of points in the set.- Value
numpy.typing.NDArray[numpy.float_]
- class cajal.run_gw.DistanceMatrix
A DistanceMatrix is a numpy array of shape (n, n) where n is the number of points in the space; it should be a symmetric nonnegative matrix with zeros along the diagonal.
- Value
numpy.typing.NDArray[numpy.float_]
- icdm_csv_validate(intracell_csv_loc: str) None
Raise an exception if the file in intracell_csv_loc fails to pass formatting tests.
If formatting tests are passed, the function returns none.
- Parameters
intracell_csv_loc (str) – The (full) file path for the CSV file containing the intracell distance matrix.
- Return type
None
The file format for an intracell distance matrix is as follows:
A line whose first character is ‘#’ is discarded as a comment.
- The first line which is not a comment is discarded as a “header” - this line may
contain the column titles for each of the columns.
Values separated by commas. Whitespace is not a separator.
- The first value in the first non-comment line should be the string ‘cell_id’, and
all values in the first column after that should be a unique identifier for that cell.
All values after the first column should be floats.
- Not including the cell id in the first column, each row except the header should contain
the entries of an intracell distance matrix lying strictly above the diagonal, as in the footnotes of https://docs.scipy.org/doc/scipy/reference/ generated/scipy.spatial.distance.squareform.html
- cell_iterator_csv(intracell_csv_loc: str) Iterator[tuple[str, numpy.ndarray[Any, numpy.dtype[numpy.float64]]]]
- Parameters
intracell_csv_loc (str) – A full file path to a csv file.
- Returns
an iterator over cells in the csv file, given as tuples of the form (name, dmat). Intracell distance matrices are in squareform.
- Return type
Iterator[tuple[str, numpy.ndarray[Any, numpy.dtype[numpy.float64]]]]
- cell_pair_iterator_csv(intracell_csv_loc: str, chunk_size: int) Iterator[tuple[tuple[int, str, numpy.ndarray[Any, numpy.dtype[numpy.float64]]], tuple[int, str, numpy.ndarray[Any, numpy.dtype[numpy.float64]]]]]
Iterate over pairs of cells in a CSV in a memory efficient way.
This is almost equivalent to itertools.combinations(cell_iterator_csv(intracell_csv_loc),2) but with more efficient file IO.
- Parameters
- Returns
an iterator over pairs of cells, each entry is of the form ((indexA, nameA, distance_matrixA),(indexB, nameB, distance_matrixB)), where indexA is the line number in the file, and indexA < indexB.
- Return type
Iterator[tuple[tuple[int, str, numpy.ndarray[Any, numpy.dtype[numpy.float64]]], tuple[int, str, numpy.ndarray[Any, numpy.dtype[numpy.float64]]]]]
- gw_pairwise_parallel(cells: list[tuple[numpy.ndarray[Any, numpy.dtype[numpy.float64]], run_gw.Distribution]], num_processes: int, names: Optional[list[str]] = None, gw_dist_csv: Optional[str] = None, gw_coupling_mat_csv: Optional[str] = None, return_coupling_mats: bool = False) tuple[numpy.ndarray[Any, numpy.dtype[numpy.float64]], Optional[list[tuple[int, int, cajal.run_gw.Matrix]]]]
Compute the pairwise Gromov-Wasserstein distances between cells.
Optionally one can also compute their coupling matrices. If appropriate file names are supplied, the output is also written to file. If computing a large number of coupling matrices, for reduced memory consumption it is suggested not to return the coupling matrices, and instead write them to file.
- Parameters
cells (list[tuple[numpy.ndarray[Any, numpy.dtype[numpy.float64]], run_gw.Distribution]]) – A list of pairs (A,a) where A is a squareform intracell distance matrix and a is a probability distribution on the points of A.
num_processes (int) – How many Python processes to run in parallel for the computation.
names (Optional[list[str]]) – A list of unique cell identifiers, where names[i] is the identifier for cell i. This argument is required if gw_dist_csv is not None, or if gw_coupling_mat_csv is not None, and is ignored otherwise.
gw_dist_csv (Optional[str]) – If this field is a string giving a file path, the GW distances will be written to this file. A list of cell names must be supplied.
gw_coupling_mat_csv (Optional[str]) – If this field is a string giving a file path, the GW coupling matrices will be written to this file. A list of cell names must be supplied.
return_coupling_mats (bool) – Whether the function should return the coupling matrices. Please be warned that for a large number of cells, couplings will be large, and memory consumption will be high. If return_coupling_mats is False, returns (gw_dmat, None). This argument is independent of whether the coupling matrices are written to a file; one may return the coupling matrices, write them to file, both, or neither.
- Returns
If return_coupling_mats is True, returns ( gw_dmat, couplings ), where gw_dmat is a square matrix whose (i,j) entry is the GW distance between two cells, and couplings is a list of tuples (i,j, coupling_mat) where i,j are indices corresponding to positions in the list cells and coupling_mat is a coupling matrix between the two cells. If return_coupling_mats is False, returns (gw_dmat, None).
- Return type
tuple[numpy.ndarray[Any, numpy.dtype[numpy.float64]], Optional[list[tuple[int, int, cajal.run_gw.Matrix]]]]
- compute_gw_distance_matrix(intracell_csv_loc: str, gw_dist_csv_loc: str, num_processes: int, gw_coupling_mat_csv_loc: Optional[str] = None, return_coupling_mats: bool = False, verbose: Optional[bool] = False) tuple[numpy.ndarray[Any, numpy.dtype[numpy.float64]], Optional[list[tuple[int, int, cajal.run_gw.Matrix]]]]
Compute the matrix of pairwise Gromov-Wasserstein distances between cells.
This function is a wrapper for
cajal.run_gw.gw_pairwise_parallel()
except that it reads icdm’s from a file rather than from a list. For the file format of icdm’s seecajal.run_gw.icdm_csv_validate()
.- Parameters
- Return type
tuple[numpy.ndarray[Any, numpy.dtype[numpy.float64]], Optional[list[tuple[int, int, cajal.run_gw.Matrix]]]]
For other parameters see
cajal.run_gw.gw_pairwise_parallel()
.