diff --git a/stlearn/tl/cci/analysis.py b/stlearn/tl/cci/analysis.py index 3a619915..e463d8d6 100644 --- a/stlearn/tl/cci/analysis.py +++ b/stlearn/tl/cci/analysis.py @@ -31,7 +31,7 @@ ) from .ligand_receptors import LRPairs, genes_of, lr_pairs, split_name from .neighbours import calc_distance, calc_neighbours, stored_neighbours -from .permutation import perform_spot_testing +from .permutation import Null, perform_spot_testing from .scoring import get_lrs_scores @@ -91,6 +91,7 @@ def run( random_state: int = 0, verbose: bool = True, cell_prop_cutoff: float = 0.2, + null: Null = "codetected", ) -> anndata.AnnData: """Performs stLearn LR analysis. @@ -140,6 +141,14 @@ def run( cell_prop_cutoff: float With use_label, a cell type is in a spot when its proportion is above this, as in run_cci. + null: str + Which of an LR's random gene pairs a spot's score is tested against. + "codetected" (default): those that score above 0 at the spot, detected + there as the LR is, so p = (n_greater + 1) / (n_codetected + 1); for + sparse data (single cells, Visium HD bins) without gridding. "random": + all n_pairs of them, the original test, p = max(n_greater, 1) / n_pairs, + where the pairs not detected at a spot score 0 and make any score there + significant. Not used with neg_binom. Returns ------- AnnData @@ -280,6 +289,7 @@ def run( save_bg=save_bg, neg_binom=neg_binom, random_state=random_state, + null=null, ) features = tests.lr_features.loc[tested.names()] var = pandas.DataFrame( diff --git a/stlearn/tl/cci/permutation.py b/stlearn/tl/cci/permutation.py index 56a8789d..d81c2d06 100644 --- a/stlearn/tl/cci/permutation.py +++ b/stlearn/tl/cci/permutation.py @@ -3,6 +3,7 @@ from dataclasses import dataclass from functools import partial +from typing import Literal, get_args import numpy as np import numpy.typing as npt @@ -19,6 +20,10 @@ from .perm_utils import _column_quantiles, background_pairs, get_lr_features from .scoring import LRScorer, spots_per_chunk +Null = Literal["codetected", "random"] +"""What a spot's score is compared with: its random pairs that scored there too +("codetected"), or all of them, the zeros included ("random").""" + @dataclass class SpotTests: @@ -59,6 +64,7 @@ def perform_spot_testing( 1, ), random_state: int = 0, + null: Null = "codetected", ) -> SpotTests: """Tests each spot's LR scores against random gene pairs with similar expression to the LR pair; backgrounds are only generated for spots @@ -67,8 +73,16 @@ def perform_spot_testing( for each of `lrs`, in the order of lrs.names(), as get_lrs_scores gives them. The p-values come back sparse, an entry for each. + `null` is which of a spot's n_pairs random pairs its score is compared with + (see empirical_pvals): + + The backgrounds saved with save_bg, and the negative binomial fitted with + neg_binom, are of every random pair under either. + Returns lr_features in expression-rank order. """ + if null not in get_args(Null): + raise ValueError(f"null must be one of {get_args(Null)}; got {null!r}.") quantiles = np.array(quantiles) scores = scored_entries(lr_scores) names, ligands, receptors = lrs.names(), lrs.ligands(), lrs.receptors() @@ -153,10 +167,8 @@ def perform_spot_testing( chunk = spots_per_chunk(2 * n_genes, n_pairs) for a in range(0, len(spot_indices), chunk): background = score(spot_indices[a : a + chunk]) - n_greater = (background >= lr_j_scores[a : a + chunk, None]).sum(1) - n_greater = np.maximum(n_greater, 1) # pseudocount pvals.data[start + a : start + a + len(background)] = ( - n_greater / n_pairs + empirical_pvals(lr_j_scores[a : a + chunk], background, null) ) # Collect memory before the next chunk is made del background @@ -186,6 +198,29 @@ def perform_spot_testing( return SpotTests(pvals, lr_feats, backgrounds, bg_spot_indices) +def empirical_pvals( + scores: npt.NDArray[np.float64], + background: npt.NDArray[np.float64], + null: Null = "codetected", +) -> npt.NDArray[np.float64]: + """A p-value for each spot's score (all above 0) from its row of background: + the scores of the LR's random pairs at the spot. + + "random" is a null using any random pairs, where there must be at least one and + they must be scored to be at least the spot's own score. + + "codetected" is a null using pairs that score above 0 and where one gene is + expressed at the spot and the other in its neighbours. Formulae is: + (n_greater + 1) / (n_codetected + 1) + """ + n_greater = (background >= scores[:, None]).sum(1) + if null == "random": + return np.maximum(n_greater, 1) / background.shape[1] + else: + n_codetected = (background > 0).sum(1) + return (n_greater + 1) / (n_codetected + 1) + + def score_background( scorer: LRScorer, pairs: npt.NDArray[np.int64], diff --git a/tests/tl/test_analysis.py b/tests/tl/test_analysis.py index cccef74b..a5c4d614 100644 --- a/tests/tl/test_analysis.py +++ b/tests/tl/test_analysis.py @@ -5,11 +5,10 @@ import anndata import numpy as np -import pandas as pd -from anndata import AnnData import stlearn as st from stlearn.tl.cci import LRPairs +from tests.utils import spot_table def _make_cci_adata(dtype=np.float64, n_side=8, n_extra_genes=40, seed=0): @@ -17,18 +16,9 @@ def _make_cci_adata(dtype=np.float64, n_side=8, n_extra_genes=40, seed=0): n_spots = n_side * n_side lr_genes = ["Lig0", "Rec0", "Lig1", "Rec1"] # two L-R pairs - extra_genes = [f"gene{i}" for i in range(n_extra_genes)] - var_names = lr_genes + extra_genes - - X = rng.poisson(3.0, size=(n_spots, len(var_names))).astype(dtype) - + X = rng.poisson(3.0, size=(n_spots, len(lr_genes) + n_extra_genes)) rows, cols = np.divmod(np.arange(n_spots), n_side) - obs = pd.DataFrame( - {"imagerow": rows.astype(float), "imagecol": cols.astype(float)}, - index=[f"spot{i}" for i in range(n_spots)], - ) - var = pd.DataFrame(index=var_names) - return AnnData(X=X, obs=obs, var=var) + return spot_table(X, rows, cols, lr_genes, sparse=False, dtype=dtype) LRS = LRPairs.from_names(["Lig0_Rec0", "Lig1_Rec1"], species="human") diff --git a/tests/tl/test_cci_labels.py b/tests/tl/test_cci_labels.py index f646cfc8..b88880ef 100644 --- a/tests/tl/test_cci_labels.py +++ b/tests/tl/test_cci_labels.py @@ -58,7 +58,14 @@ class TestCCILabels(unittest.TestCase): def setUpClass(cls): adata, lrs = read_test_data_with_lr_pairs() cls.lr_results = st.tl.cci.run( - adata, lrs, min_spots=5, distance=None, n_pairs=200, n_cpus=1, verbose=False + adata, + lrs, + min_spots=5, + distance=None, + n_pairs=200, + n_cpus=1, + verbose=False, + null="random", ) # Three bands of cell types across the tissue. bands = pd.qcut(adata.obs["imagecol"], 3, labels=CELL_TYPE_LABELS) diff --git a/tests/tl/test_het.py b/tests/tl/test_het.py index feaf8558..37c0a8e3 100644 --- a/tests/tl/test_het.py +++ b/tests/tl/test_het.py @@ -13,7 +13,7 @@ from stlearn.tl.cci import lr_result from stlearn.tl.cci.het import count, get_data_for_counting from stlearn.tl.cci.neighbours import calc_neighbours -from tests.utils import CCI_LRS, cci_table +from tests.utils import CCI_LRS, cci_table, spot_table LRS = st.tl.cci.LRPairs.from_names( ["Lig0_Rec0", "Lig1_Rec1"], species="human", source="test" @@ -25,15 +25,10 @@ def _make_adata(n_side=6, n_extra_genes=40, seed=0): """Spots on a unit grid, with cell type proportions in uns["cell_type"].""" rng = np.random.default_rng(seed) n_spots = n_side * n_side - var_names = list(LRS.genes()) + [f"gene{i}" for i in range(n_extra_genes)] - X = rng.poisson(3.0, size=(n_spots, len(var_names))).astype(np.float64) - + lr_genes = list(LRS.genes()) + X = rng.poisson(3.0, size=(n_spots, len(lr_genes) + n_extra_genes)) rows, cols = np.divmod(np.arange(n_spots), n_side) - obs = pd.DataFrame( - {"imagerow": rows.astype(float), "imagecol": cols.astype(float)}, - index=[f"spot{i}" for i in range(n_spots)], - ) - adata = AnnData(X=X, obs=obs, var=pd.DataFrame(index=var_names)) + adata = spot_table(X, rows, cols, lr_genes, sparse=False, dtype=np.float64) adata.uns["spatial"] = { "lib": { "scalefactors": {"spot_diameter_fullres": 5.0, "tissue_hires_scalef": 0.1}, diff --git a/tests/tl/test_permutation.py b/tests/tl/test_permutation.py index 33762023..fa4eb96b 100644 --- a/tests/tl/test_permutation.py +++ b/tests/tl/test_permutation.py @@ -1,239 +1,71 @@ #!/usr/bin/env python -"""Tests for perform_spot_testing: per-spot p-values against each LR's background.""" +"""Tests for empirical_pvals: the p-value of a spot's score from its row of +background scores, under each null. perform_spot_testing is tested in +test_permutation_gridded_sparse.py, st.tl.cci.run's null in +test_permutation_run_null.py.""" import unittest import numpy as np -import pandas as pd -import scipy.sparse -from anndata import AnnData -from stlearn.tl.cci._results import to_dense -from stlearn.tl.cci.ligand_receptors import LRPairs -from stlearn.tl.cci.neighbours import calc_neighbours -from stlearn.tl.cci.permutation import gene_quantiles, perform_spot_testing -from stlearn.tl.cci.scoring import get_lrs_scores - -LRS = LRPairs.from_names(["Lig0_Rec0", "Lig1_Rec1", "Lig2_Rec2"], species="human") -N_PAIRS = 100 - - -def _make_adata(n_side=10, n_extra_genes=60, seed=0): - """Sparse counts on a grid. Lig0 and Rec0 are high together in one corner, so - some spots are significant; zeros elsewhere leave some spots unscored.""" - rng = np.random.default_rng(seed) - n_spots = n_side * n_side - lr_genes = ["Lig0", "Rec0", "Lig1", "Rec1", "Lig2", "Rec2"] - var_names = lr_genes + [f"gene{i}" for i in range(n_extra_genes)] - - X = rng.poisson(0.3, size=(n_spots, len(var_names))).astype(np.float32) - rows, cols = np.divmod(np.arange(n_spots), n_side) - corner = (rows < 4) & (cols < 4) - X[corner, :2] = 6 - - obs = pd.DataFrame( - {"imagerow": rows.astype(float), "imagecol": cols.astype(float)}, - index=[f"spot{i}" for i in range(n_spots)], - ) - var = pd.DataFrame(index=var_names) - return AnnData(X=scipy.sparse.csr_matrix(X), obs=obs, var=var) +from stlearn.tl.cci.permutation import empirical_pvals class TestPermutation(unittest.TestCase): - @classmethod - def setUpClass(cls): - cls.adata = _make_adata() - neighbours = calc_neighbours(cls.adata, distance=1.5, verbose=False) - het_vals = np.ones(len(cls.adata)) - # Columns of scores, and of everything perform_spot_testing returns, - # follow the scored pairs get_lrs_scores gives: their names() order. - cls.scores, cls.lrs = get_lrs_scores(cls.adata, LRS, neighbours, het_vals, 0) - cls.results = perform_spot_testing( - cls.adata, - cls.scores, - cls.lrs, - N_PAIRS, - neighbours, - het_vals, - 0, - verbose=False, - save_bg=True, + """The p-value of a spot's score from its row of background scores.""" + + def setUp(self): + self.scores = np.array([3.0, 3.0, 3.0, 3.0]) + self.background = np.array( + [ + [0, 0, 0, 0, 0, 0, 0, 0, 0, 0], # no random pair detected + [0, 0, 0, 0, 0, 0, 0, 0, 1, 2], # two detected, both below + [0, 0, 0, 0, 0, 0, 1, 2, 3, 4], # four detected, two at or above + [1, 1, 2, 2, 2, 2, 2, 3, 8, 9], # all detected, three above + ], + dtype=float, ) - def test_pvals_from_background(self): - """A scored spot's p-value is the share of its background scores at or - above its own score, at least 1 / n_pairs. Unscored spots keep 1: they - are not in the sparse p-values, whose entries are the scored spots.""" - sparse_pvals = self.results.pvals - self.assertTrue(scipy.sparse.issparse(sparse_pvals)) - self.assertEqual(sparse_pvals.shape, self.scores.shape) - np.testing.assert_array_equal(sparse_pvals.toarray() != 0, self.scores > 0) - pvals = to_dense(sparse_pvals, 1.0) - for j, lr in enumerate(self.lrs.names()): - background = self.results.backgrounds[lr] - spots = self.results.bg_spot_indices[lr] - np.testing.assert_array_equal(spots, np.flatnonzero(self.scores[:, j] > 0)) - self.assertTrue(0 < len(spots) < len(self.adata), msg=lr) - self.assertEqual(background.shape, (len(spots), N_PAIRS), msg=lr) - - for spot_i, spot in enumerate(spots): - n_greater = np.count_nonzero(background[spot_i] >= self.scores[spot, j]) - expected = max(n_greater, 1) / N_PAIRS - self.assertEqual(pvals[spot, j], expected, msg=f"{lr} {spot}") - - unscored = np.setdiff1d(np.arange(len(self.adata)), spots) - np.testing.assert_array_equal(pvals[unscored, j], 1) - - def test_some_spots_significant(self): - """The co-expressed corner gives Lig0_Rec0 p-values at the floor.""" - j = list(self.lrs.names()).index("Lig0_Rec0") - self.assertEqual(to_dense(self.results.pvals, 1.0)[:, j].min(), 1 / N_PAIRS) - - def test_lr_features_cover_every_lr(self): - self.assertCountEqual(self.results.lr_features.index, self.lrs.names()) - - def test_leaves_adata_alone(self): - """Results are returned; st.tl.cci.run is what stores them.""" - for key in ("lr_summary", "lrfeatures", "lrs_to_bg", "lr_spot_indices"): - self.assertNotIn(key, self.adata.uns) - self.assertNotIn("p_vals", self.adata.obsm) - - def test_no_backgrounds_unless_asked(self): - adata = _make_adata() - neighbours = calc_neighbours(adata, distance=1.5, verbose=False) - het_vals = np.ones(len(adata)) - scores, lrs = get_lrs_scores(adata, LRS, neighbours, het_vals, 0) - results = perform_spot_testing( - adata, - scores, - lrs, - N_PAIRS, - neighbours, - het_vals, - 0, - verbose=False, - ) - self.assertIsNone(results.backgrounds) - self.assertIsNone(results.bg_spot_indices) + def test_random_counts_every_pair(self): + """The share of all the random pairs at or above the score, or at least + one of them divided by the number of pairs.""" np.testing.assert_array_equal( - results.pvals.toarray(), - self.results.pvals.toarray(), + empirical_pvals(self.scores, self.background, "random"), + [ + # None detected or 1, 1 / 10 (shape of background column) + 0.1, + # None detected or 1, 1 / 10 (shape of background column) + 0.1, + # n > 3 = 2, 2 / 10 (shape of background column) + 0.2, + # n > 3 = 3, 3 / 10 (shape of background column) + 0.3, + ], ) - def test_sparse_scores_test_the_same(self): - """The sparse scores run passes in (the scores above 0) give the same - p-values as the dense scores, entry for entry.""" - adata = _make_adata() - neighbours = calc_neighbours(adata, distance=1.5, verbose=False) - het_vals = np.ones(len(adata)) - scores, lrs = get_lrs_scores( - adata, - LRS, - neighbours, - het_vals, - 0, - sparse_result=True, - ) - self.assertTrue(scipy.sparse.issparse(scores)) - results = perform_spot_testing( - adata, - scores, - lrs, - N_PAIRS, - neighbours, - het_vals, - 0, - verbose=False, - ) - np.testing.assert_array_equal(results.pvals.indptr, scores.indptr) - np.testing.assert_array_equal(results.pvals.indices, scores.indices) + def test_codetected_counts_detected_pairs(self): + """The share of all the codetected pairs at or above the score.""" np.testing.assert_array_equal( - results.pvals.toarray(), - self.results.pvals.toarray(), + empirical_pvals(self.scores, self.background, "codetected"), + [ + # None detected so 1/1 + 1, + # n > 3 = 0 + 1, 1 / 3 (non-zero = 2 + 1) + 1 / 3, + # n > 3 = 2 + 1, 3 / 5 (non-zero = 4 + 1) + 0.6, + # n > 3 = 3 + 1, 4 / 11 (non-zero = 10 + 1) + 4 / 11, + ], ) - def test_homophilic_lr_is_tested(self): - """A gene paired with itself gets a background like any LR: random pairs - of two different genes similar to it, so the random pairs never pair a - gene with itself (as before), but the LR itself is tested.""" - adata = _make_adata() - neighbours = calc_neighbours(adata, distance=1.5, verbose=False) - het_vals = np.ones(len(adata)) - lrs = LRPairs.from_names(["Lig0_Lig0"], species="human") - scores, lrs = get_lrs_scores( - adata, - lrs, - neighbours, - het_vals, - 0, - ) - self.assertEqual(list(lrs.names()), ["Lig0_Lig0"]) - - results = perform_spot_testing( - adata, - scores, - lrs, - N_PAIRS, - neighbours, - het_vals, - 0, - verbose=False, - save_bg=True, - ) - - spots = np.flatnonzero(scores[:, 0] > 0) - pvals = to_dense(results.pvals, 1.0) - self.assertEqual(results.backgrounds["Lig0_Lig0"].shape, (len(spots), N_PAIRS)) - self.assertTrue((pvals[spots, 0] < 1).any()) - self.assertEqual(pvals[:, 0].min(), 1 / N_PAIRS) # the corner - - def test_unscored_lr_is_left_untested(self): - """An LR with no scored spot has nothing to test: its p-values stay 1, - its background is empty, and the other LRs are tested as before.""" - adata = _make_adata() - neighbours = calc_neighbours(adata, distance=1.5, verbose=False) - het_vals = np.ones(len(adata)) - scores, lrs = get_lrs_scores(adata, LRS, neighbours, het_vals, 0) - scores[:, 1] = 0 # as if Lig1_Rec1 never scored - results = perform_spot_testing( - adata, - scores, - lrs, - N_PAIRS, - neighbours, - het_vals, - 0, - verbose=False, - save_bg=True, - ) - pvals = to_dense(results.pvals, 1.0) - np.testing.assert_array_equal(pvals[:, 1], 1) - self.assertEqual(results.pvals[:, 1].nnz, 0) # no entries: nothing tested - unscored = lrs.names()[1] - self.assertEqual(results.backgrounds[unscored].shape, (0, N_PAIRS)) - self.assertEqual(results.bg_spot_indices[unscored].size, 0) + def test_codetected_is_the_default(self): np.testing.assert_array_equal( - pvals[:, [0, 2]], - to_dense(self.results.pvals, 1.0)[:, [0, 2]], + empirical_pvals(self.scores, self.background), + empirical_pvals(self.scores, self.background, "codetected"), ) - def test_matches_quantiles_per_gene(self): - """Quantiles computed in chunks equal np.quantile gene by gene, for chunk - sizes that split the genes unevenly, one at a time, or all at once.""" - adata = _make_adata() - genes = adata.var_names.to_numpy() - quantiles = np.array([0.5, 0.75, 0.9, 0.99, 1]) - expected = np.apply_along_axis( - np.quantile, - 0, - adata.X.toarray(), - q=quantiles, - method="nearest", - ) - for chunk_size in (1, 7, len(genes), 1000): - np.testing.assert_array_equal( - gene_quantiles(adata, genes, quantiles, chunk_size), - expected, - err_msg=f"{chunk_size=}", - ) + +if __name__ == "__main__": + unittest.main() diff --git a/tests/tl/test_permutation_gridded_sparse.py b/tests/tl/test_permutation_gridded_sparse.py new file mode 100644 index 00000000..2b70b851 --- /dev/null +++ b/tests/tl/test_permutation_gridded_sparse.py @@ -0,0 +1,228 @@ +#!/usr/bin/env python + +"""Tests for perform_spot_testing: per-spot p-values against each LR's background, +under both nulls ("codetected", the default, and "random", the original), on a +gridded sample of well-covered spots and on sparse single cells without a grid.""" + +import itertools +import unittest + +import numpy as np +import scipy.sparse +from anndata import AnnData + +from stlearn.tl.cci._results import to_dense +from stlearn.tl.cci.ligand_receptors import LRPairs +from stlearn.tl.cci.neighbours import calc_neighbours +from stlearn.tl.cci.permutation import ( + empirical_pvals, + gene_quantiles, + perform_spot_testing, +) +from stlearn.tl.cci.scoring import get_lrs_scores +from tests.utils import spot_table + +# Lig0 and Rec0 are high together in a patch; the other two pairs are noise. +LRS = LRPairs.from_names(["Lig0_Rec0", "Lig1_Rec1", "Lig2_Rec2"], species="human") +LR_GENES = ["Lig0", "Rec0", "Lig1", "Rec1", "Lig2", "Rec2"] +NULLS = ("codetected", "random") + + +def _test(adata, distance, n_pairs, lrs=LRS, sparse_result=False, **kwargs): + """Scores `lrs` and tests them; kwargs go to perform_spot_testing.""" + neighbours = calc_neighbours(adata, distance=distance, verbose=False) + het_vals = np.ones(len(adata)) + scores, lrs = get_lrs_scores( + adata, lrs, neighbours, het_vals, 0, sparse_result=sparse_result + ) + if "zero_lr" in kwargs: # as if this LR never scored + scores[:, kwargs.pop("zero_lr")] = 0 + results = perform_spot_testing( + adata, scores, lrs, n_pairs, neighbours, het_vals, 0, verbose=False, **kwargs + ) + return scores, lrs, results + + +def _gridded_adata(n_side=10, n_extra_genes=60, seed=0): + """Spots on a grid, each covering many cells, as Visium or gridded data: most + genes are detected at most spots, so most random pairs score at a spot. Lig0 + and Rec0 are high together in one corner, so some spots are significant; the + opposite corner has no LR gene, which leaves its spots unscored.""" + rng = np.random.default_rng(seed) + n_spots = n_side * n_side + X = rng.poisson(2.0, size=(n_spots, len(LR_GENES) + n_extra_genes)) + rows, cols = np.divmod(np.arange(n_spots), n_side) + X[(rows < 4) & (cols < 4), :2] = 12 + X[(rows >= 8) & (cols >= 8), : len(LR_GENES)] = 0 + return spot_table(X, rows, cols, LR_GENES) + + +def _sparse_cells_adata(n_cells=900, n_extra_genes=150, seed=0): + """Single cells scattered at one per unit area, as Xenium or Visium HD bins + without gridding: a gene is detected in about a cell in ten, so few random + pairs score at a cell. Lig0 and Rec0 are high together in the cells of one + corner; the other LR genes are as sparse as the rest.""" + rng = np.random.default_rng(seed) + side = np.sqrt(n_cells) + rows, cols = rng.uniform(0, side, size=(2, n_cells)) + X = rng.poisson(0.1, size=(n_cells, len(LR_GENES) + n_extra_genes)) + patch = (rows < side * 0.3) & (cols < side * 0.3) + X[patch, :2] = rng.poisson(4.0, size=(patch.sum(), 2)) + return spot_table(X, rows, cols, LR_GENES) + + +class Sample: + """A sample tested under each null, with its backgrounds saved.""" + + def __init__(self, adata: AnnData, distance: float, n_pairs: int): + self.adata = adata + self.n_pairs = n_pairs + # Columns of scores, and of everything perform_spot_testing returns, + # follow the scored pairs get_lrs_scores gives: their names() order. + self.results = {} + for null in NULLS: + self.scores, self.lrs, self.results[null] = _test( + adata, distance, n_pairs, save_bg=True, null=null + ) + self.pvals = {null: to_dense(r.pvals, 1.0) for null, r in self.results.items()} + self.tested = self.scores > 0 + + def column(self, lr: str) -> int: + return list(self.lrs.names()).index(lr) + + def codetected_share(self) -> np.ndarray: + """Per tested spot and LR, the share of its random pairs scoring above 0.""" + backgrounds = self.results["random"].backgrounds + return np.concatenate([(bg > 0).mean(1) for bg in backgrounds.values()]) + + def called(self, null: str, lr: str) -> float: + """The share of an LR's tested spots with p < 0.05.""" + j = self.column(lr) + return (self.pvals[null][self.tested[:, j], j] < 0.05).mean() + + +class TestGriddedAndSparse(unittest.TestCase): + """Both nulls on two samples. Gridded: well-covered spots, where nearly every + random pair is detected at a spot, so the nulls are nearly the same test. + Sparse: single cells without a grid, where few are, so the nulls part.""" + + @classmethod + def setUpClass(cls): + # distance: the 8 surrounding spots; about 6 neighbouring cells. + cls.gridded = Sample(_gridded_adata(), distance=1.5, n_pairs=100) + cls.sparse = Sample(_sparse_cells_adata(), distance=1.4, n_pairs=1000) + cls.samples = {"gridded": cls.gridded, "sparse": cls.sparse} + + # On both samples + + def test_pvals_from_background(self): + """Each scored spot gets a p-value from its own background, as + empirical_pvals counts it for the null. Unscored spots are left out of + the sparse p-values, so read as 1.""" + for (name, sample), null in itertools.product(self.samples.items(), NULLS): + results = sample.results[null] + with self.subTest(sample=name, null=null): + self.assertTrue(scipy.sparse.issparse(results.pvals)) + np.testing.assert_array_equal( + results.pvals.toarray() != 0, sample.tested + ) + for j, lr in enumerate(sample.lrs.names()): + with self.subTest(sample=name, null=null, lr=lr): + spots = results.bg_spot_indices[lr] + background = results.backgrounds[lr] + np.testing.assert_array_equal( + spots, np.flatnonzero(sample.tested[:, j]) + ) + self.assertTrue(0 < len(spots) < len(sample.adata)) # some unscored + self.assertEqual(background.shape, (len(spots), sample.n_pairs)) + np.testing.assert_array_equal( + sample.pvals[null][spots, j], + empirical_pvals(sample.scores[spots, j], background, null), + ) + + def test_nulls_share_the_background(self): + """The null chooses which background scores count, not the random pairs + or their scores.""" + for name, sample in self.samples.items(): + codetected, random = sample.results["codetected"], sample.results["random"] + for lr in sample.lrs.names(): + with self.subTest(sample=name, lr=lr): + np.testing.assert_array_equal( + codetected.backgrounds[lr], random.backgrounds[lr] + ) + np.testing.assert_array_equal( + codetected.bg_spot_indices[lr], random.bg_spot_indices[lr] + ) + + def test_co_expressed_patch_is_significant(self): + """Lig0 and Rec0, high together in a patch, are called under either + null; under "random" at its floor.""" + for name, sample in self.samples.items(): + with self.subTest(sample=name): + j = sample.column("Lig0_Rec0") + self.assertEqual(sample.pvals["random"][:, j].min(), 1 / sample.n_pairs) + self.assertLess(sample.pvals["codetected"][:, j].min(), 0.05) + + # Where the samples differ + + def test_share_of_random_pairs_codetected(self): + """Nearly every random pair is detected at a gridded spot; few are at a + sparse cell.""" + self.assertGreater(np.median(self.gridded.codetected_share()), 0.9) + self.assertLess(np.median(self.sparse.codetected_share()), 0.25) + + def test_nulls_agree_on_gridded_spots(self): + """With few zeros in the background the two nulls' p-values are close.""" + pvals = self.gridded.pvals + self.assertLess(np.abs(pvals["codetected"] - pvals["random"]).max(), 0.1) + + def test_unrelated_genes_are_called_at_chance(self): + """Lig1_Rec1 and Lig2_Rec2 are pairs of unrelated genes, so should be + called at about the 5% chance gives. "codetected" is, on either sample; + "random" only on gridded spots. At a sparse cell most random pairs score + 0, so against all of them any score above 0 is significant.""" + for lr in ("Lig1_Rec1", "Lig2_Rec2"): + with self.subTest(lr=lr): + self.assertLess(self.gridded.called("codetected", lr), 0.15) + self.assertLess(self.sparse.called("codetected", lr), 0.15) + self.assertLess(self.gridded.called("random", lr), 0.15) + self.assertGreater(self.sparse.called("random", lr), 0.3) + + def test_patch_is_called_more_than_the_rest(self): + """On sparse cells, under "codetected", the co-expressed patch is still + what Lig0_Rec0 is called in.""" + sample = self.sparse + j = sample.column("Lig0_Rec0") + obs = sample.adata.obs + side = np.sqrt(len(obs)) + patch = ((obs["imagerow"] < side * 0.3) & (obs["imagecol"] < side * 0.3)).values + tested = sample.tested[:, j] + significant = sample.pvals["codetected"][:, j] < 0.05 + self.assertGreater(significant[patch & tested].mean(), 0.5) + self.assertLess(significant[~patch & tested].mean(), 0.15) + + +class TestGeneQuantiles(unittest.TestCase): + def test_matches_quantiles_per_gene(self): + """Quantiles computed in chunks equal np.quantile gene by gene, for chunk + sizes that split the genes unevenly, one at a time, or all at once.""" + adata = _sparse_cells_adata(n_cells=100, n_extra_genes=60) + genes = adata.var_names.to_numpy() + quantiles = np.array([0.5, 0.75, 0.9, 0.99, 1]) + expected = np.apply_along_axis( + np.quantile, + 0, + adata.X.toarray(), + q=quantiles, + method="nearest", + ) + for chunk_size in (1, 7, len(genes), 1000): + np.testing.assert_array_equal( + gene_quantiles(adata, genes, quantiles, chunk_size), + expected, + err_msg=f"{chunk_size=}", + ) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/tl/test_permutation_run_null.py b/tests/tl/test_permutation_run_null.py new file mode 100644 index 00000000..107c0a64 --- /dev/null +++ b/tests/tl/test_permutation_run_null.py @@ -0,0 +1,31 @@ +import unittest + +import numpy as np + +import stlearn as st +from stlearn.tl.cci.permutation import empirical_pvals +from tests.utils import CCI_LRS, cci_table + + +class TestRunNull(unittest.TestCase): + """st.tl.cci.run passes its `null` on, "codetected" by default.""" + + @staticmethod + def pvals(**kwargs): + settings = {"min_spots": 2, "distance": 1.5, "n_pairs": 100, "verbose": False} + lr = st.tl.cci.run(cci_table(), CCI_LRS, **settings, **kwargs) + lr = lr[:, CCI_LRS.names()] + return st.tl.cci.lr_result(lr, "p_vals"), lr + + def test_null_reaches_the_test(self): + default, _ = self.pvals() + codetected, _ = self.pvals(null="codetected") + random, lr = self.pvals(null="random", save_bg=True) + np.testing.assert_array_equal(default, codetected) + for null, pvals in (("random", random), ("codetected", codetected)): + for j, name in enumerate(CCI_LRS.names()): + spots = lr.uns["lr_spot_indices"][name] + scores = st.tl.cci.lr_result(lr, "lr_scores", name)[spots] + expected = empirical_pvals(scores, lr.uns["lrs_to_bg"][name], null) + np.testing.assert_array_equal(pvals[spots, j], expected, err_msg=null) + self.assertFalse(np.array_equal(random, codetected)) diff --git a/tests/tl/test_report_dropped_lrs.py b/tests/tl/test_report_dropped_lrs.py index fee5fbdc..db365b89 100644 --- a/tests/tl/test_report_dropped_lrs.py +++ b/tests/tl/test_report_dropped_lrs.py @@ -5,20 +5,21 @@ import unittest import numpy as np -import pandas as pd -import scipy.sparse -from anndata import AnnData from stlearn.tl.cci import LRPairs from stlearn.tl.cci.analysis import _report_dropped_lrs +from tests.utils import spot_table def _adata(sparse=False): - """Four spots: A is 0.3 everywhere, E is never expressed, the rest are 1.""" - X = np.array([[0.3, 1.0, 1.0, 1.0, 0.0]] * 4, dtype=np.float32) - return AnnData( - scipy.sparse.csr_matrix(X) if sparse else X, - var=pd.DataFrame(index=list("ABCDE")), + """Four spots in a row: A is 0.3 everywhere, E is never expressed, the rest + are 1.""" + return spot_table( + np.array([[0.3, 1.0, 1.0, 1.0, 0.0]] * 4), + np.zeros(4), + np.arange(4), + list("ABCDE"), + sparse=sparse, ) @@ -65,7 +66,9 @@ def test_nothing_dropped(self): def test_names_at_most_max_named_genes(self): genes = [f"G{i}" for i in range(12)] - adata = AnnData(np.zeros((2, 12)), var=pd.DataFrame(index=genes)) + adata = spot_table( + np.zeros((2, 12)), np.zeros(2), np.arange(2), genes, sparse=False + ) lrs = [f"G{i}_G{i + 1}" for i in range(11)] report = _report(adata, lrs, [0] * 11) self.assertIn("G0, G1, G10, G11, G2, G3, G4, G5, G6, G7 and 2 more.", report) diff --git a/tests/tl/test_scoring.py b/tests/tl/test_scoring.py index 1639d102..d3c81fe2 100644 --- a/tests/tl/test_scoring.py +++ b/tests/tl/test_scoring.py @@ -6,9 +6,7 @@ from unittest import mock import numpy as np -import pandas as pd import scipy.sparse -from anndata import AnnData from stlearn.tl.cci import scoring from stlearn.tl.cci.neighbours import calc_neighbours @@ -19,6 +17,7 @@ neighbourhood_means, score_spots, ) +from tests.utils import spot_table def _reference_scores(expr, pairs, neighbour_lists, het_vals, min_expr, spot_indices): @@ -185,18 +184,10 @@ def test_spots_scored_in_chunks(self): def _make_adata(n_side=6, seed=0, sparse=True): rng = np.random.default_rng(seed) n_spots = n_side * n_side - var_names = ["Lig0", "Rec0", "Lig1", "Rec1", "Rec2", "gene0"] - X = rng.poisson(1.0, size=(n_spots, len(var_names))).astype(np.float32) + lr_genes = ["Lig0", "Rec0", "Lig1", "Rec1", "Rec2"] # and gene0 + X = rng.poisson(1.0, size=(n_spots, len(lr_genes) + 1)) rows, cols = np.divmod(np.arange(n_spots), n_side) - obs = pd.DataFrame( - {"imagerow": rows.astype(float), "imagecol": cols.astype(float)}, - index=[f"spot{i}" for i in range(n_spots)], - ) - return AnnData( - X=scipy.sparse.csr_matrix(X) if sparse else X, - obs=obs, - var=pd.DataFrame(index=var_names), - ) + return spot_table(X, rows, cols, lr_genes, sparse=sparse) class TestGetLrsScores(unittest.TestCase): diff --git a/tests/utils.py b/tests/utils.py index f334b254..b99c6890 100644 --- a/tests/utils.py +++ b/tests/utils.py @@ -44,6 +44,22 @@ def scores_and_pvals(n_spots=30, seed=0): return scores, pvals +def spot_table( + X, rows, cols, lr_genes, sparse=True, dtype=np.float32 +) -> anndata.AnnData: + n_other_genes = X.shape[1] - len(lr_genes) + var_names = list(lr_genes) + [f"gene{i}" for i in range(n_other_genes)] + obs = pd.DataFrame( + {"imagerow": np.asarray(rows, float), "imagecol": np.asarray(cols, float)}, + index=[f"spot{i}" for i in range(len(X))], + ) + X = np.asarray(X, dtype=np.float32) + X = np.asarray(X, dtype=dtype) + if sparse: + X = scipy.sparse.csr_matrix(X) + return anndata.AnnData(X=X, obs=obs, var=pd.DataFrame(index=var_names)) + + CCI_LRS = LRPairs.from_names(["LigA_RecA", "LigB_RecB", "LigC_RecC"], species="human") CELL_TYPES = np.array(["CT1", "CT2", "CT3"]) @@ -63,29 +79,17 @@ def cci_table( n_spots = n_side * n_side lr_genes = np.column_stack((CCI_LRS.ligands(), CCI_LRS.receptors())).ravel() lr_genes = lr_genes.tolist() # each pair's ligand then receptor - var_names = lr_genes + [f"gene{i}" for i in range(n_other_genes)] - X = rng.poisson(0.3, size=(n_spots, len(var_names))).astype(np.float32) + X = rng.poisson(0.3, size=(n_spots, len(lr_genes) + n_other_genes)) rows, cols = np.divmod(np.arange(n_spots), n_side) X[(rows < 4) & (cols < 4), :2] = 6 - obs_names = [f"spot{i}" for i in range(n_spots)] band = np.minimum(rows * len(CELL_TYPES) // n_side, len(CELL_TYPES) - 1) - adata = anndata.AnnData( - X=scipy.sparse.csr_matrix(X), - obs=pd.DataFrame( - { - "imagerow": rows.astype(float), - "imagecol": cols.astype(float), - "cell_type": pd.Categorical(CELL_TYPES[band], categories=CELL_TYPES), - }, - index=obs_names, - ), - var=pd.DataFrame(index=var_names), - ) + adata = spot_table(X, rows, cols, lr_genes) + adata.obs["cell_type"] = pd.Categorical(CELL_TYPES[band], categories=CELL_TYPES) adata.obsm["spatial"] = np.column_stack([cols, rows]).astype(float) adata.uns["cell_type"] = pd.DataFrame( - np.eye(len(CELL_TYPES))[band], index=obs_names, columns=CELL_TYPES + np.eye(len(CELL_TYPES))[band], index=adata.obs_names, columns=CELL_TYPES ) adata.uns["spatial"] = { "synthetic": {