multineuronchat 2026.8.18.dev0__tar.gz → 2026.9.1.dev0__tar.gz

{multineuronchat-2026.8.18.dev0/src/multineuronchat.egg-info → multineuronchat-2026.9.1.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multineuronchat
-Version: 2026.8.18.dev0
+Version: 2026.9.1.dev0
 Summary: MultiNeuronChat is a Python library for inferring condition‑related changes in synaptic cell‑cell communication from scRNA-/snRNA-Seq datasets in case vs control study designs.
 Author-email: Gianluca Volkmer <gianluca.volkmer@ki.se>
 License-Expression: GPL-3.0

{multineuronchat-2026.8.18.dev0 → multineuronchat-2026.9.1.dev0}/pyproject.toml

@@ -11,7 +11,7 @@ description = "MultiNeuronChat is a Python library for inferring condition‑rel
 readme = "README.md"
 license = "GPL-3.0"
 license-files = ["LICENSE"]
-version = "2026.8.18.dev0"
+version = "2026.9.1.dev0"
 requires-python = '>=3.10'
 dependencies = [
     "numpy==1.26.4",

{multineuronchat-2026.8.18.dev0 → multineuronchat-2026.9.1.dev0}/src/multineuronchat/MultiNeuronChatObject.py

@@ -4,6 +4,8 @@ import pickle
 
 import warnings
 
+from multiprocessing import Pool
+
 import numpy as np
 import xarray as xr
 
@@ -19,6 +21,112 @@ from .MultiNeuronChat import compute_avg_expression, compute_communication_score
 from typing import Tuple, Optional, List, Dict, Set, Any, Union
 
 
+def _compute_anderson_pvalue_for_triple(
+        task: Tuple[Any, Any, Any, np.ndarray, np.ndarray, bool, int, int, bool, Optional[int]]
+) -> Optional[Tuple[Any, Any, Any, float, float, bool]]:
+    """
+    Compute the Anderson-Darling p-value and test statistic for a single triple.
+
+    This is the body of the per-triple loop in ``MultiNeuronChatObject.__compute_p_values_Anderson``, lifted out to a
+    module-level function so it can be dispatched to a ``multiprocessing.Pool``. It is kept at module scope (rather than a
+    closure or a bound method) so it stays picklable under the 'spawn' start method used on macOS, and it receives the two
+    pre-extracted score arrays instead of the whole object so the parent does not have to pickle its state per task.
+
+    The computation is identical to the serial path, including which triples are skipped and how randomness is seeded:
+    the first stage uses the shared run-level ``random_state`` and the escalation stage uses ``_derive_seed`` keyed on the
+    triple's position. Both are independent of the order in which triples are processed, so the parallel result is
+    bit-identical to the serial one regardless of scheduling.
+
+    :param task: a tuple ``(source, receiver, interaction, scores_a, scores_b, permutation_method, n_resamples_stage_one,
+                 n_resamples_stage_two, escalate, random_state)``
+    :return: ``(source, receiver, interaction, p_value, test_statistic, escalated)``, or None if the triple is degenerate
+             (all scores identical, or fewer than two scores in either condition) and must be left as NaN
+    """
+    (source, receiver, interaction,
+     condition_a_communication_scores, condition_b_communication_scores,
+     permutation_method,
+     n_resamples_stage_one, n_resamples_stage_two,
+     escalate, random_state) = task
+
+    # The Anderson Darling Test does work if all values of the data are the same
+    # Therefore we have to check if the data is the same and if so we have to skip the test
+    # IMPORTANT: this includes the case when both distributions are the same, e.g., both are completely zero
+    if np.unique(np.hstack([condition_a_communication_scores, condition_b_communication_scores])).shape[0] == 1:
+        return None
+
+    # Restrict to the case where both samples have at least 2 samples (SciPy's anderson_ksamp arranges N-1 samples, so a
+    # single-value sample yields 0 and errors). Mirrors the serial guard.
+    if len(condition_a_communication_scores) < 2 or len(condition_b_communication_scores) < 2:
+        return None
+
+    # Track whether the reported p-value came from a permutation run, and at what depth, so the escalation trigger and the
+    # zero-guard below both refer to the resolution that actually produced it.
+    n_resamples_used: Optional[int] = None
+
+    # First try the default (analytical/approximate) unless permutation was explicitly requested
+    if not permutation_method:
+        anderson_statistic = stats.anderson_ksamp(
+            samples=[
+                condition_a_communication_scores,
+                condition_b_communication_scores,
+            ]
+        )
+        p = float(anderson_statistic.pvalue)
+        # SciPy's approximate p can be clipped (~<=0.001). If clipped or non-finite, redo via permutation.
+        if MultiNeuronChatObject._needs_permutation(p, coarse_levels={0.001}):
+            anderson_statistic = stats.anderson_ksamp(
+                samples=[
+                    condition_a_communication_scores,
+                    condition_b_communication_scores,
+                ],
+                method=PermutationMethod(
+                    n_resamples=n_resamples_stage_one,
+                    random_state=random_state
+                )
+            )
+            n_resamples_used = n_resamples_stage_one
+    else:
+        anderson_statistic = stats.anderson_ksamp(
+            samples=[
+                condition_a_communication_scores,
+                condition_b_communication_scores
+            ],
+            method=PermutationMethod(
+                n_resamples=n_resamples_stage_one,
+                random_state=random_state
+            )
+        )
+        n_resamples_used = n_resamples_stage_one
+
+    # Second stage: this triple's p-value is pinned at the resolution of the first stage and carries no information beyond
+    # "smaller than 1 / (R + 1)". Re-run it deeply enough to survive the correction, with fresh draws from a derived seed,
+    # and replace the first-stage value outright.
+    escalated: bool = False
+    if escalate and MultiNeuronChatObject._is_at_monte_carlo_floor(float(anderson_statistic.pvalue), n_resamples_used):
+        anderson_statistic = stats.anderson_ksamp(
+            samples=[
+                condition_a_communication_scores,
+                condition_b_communication_scores,
+            ],
+            method=PermutationMethod(
+                n_resamples=n_resamples_stage_two,
+                random_state=MultiNeuronChatObject._derive_seed(
+                    random_state=random_state,
+                    source=source,
+                    receiver=receiver,
+                    interaction=interaction
+                )
+            )
+        )
+        n_resamples_used = n_resamples_stage_two
+        escalated = True
+
+    p_value: float = MultiNeuronChatObject._ensure_nonzero_p(float(anderson_statistic.pvalue), n_resamples_used)
+    test_statistic: float = float(anderson_statistic.statistic)
+
+    return source, receiver, interaction, p_value, test_statistic, escalated
+
+
 class MultiNeuronChatObject:
     def __init__(self,
                  condition_label_column: str,
@@ -602,7 +710,8 @@ class MultiNeuronChatObject:
             warn_if_underpowered: Optional[bool] = True,
             correction_method: Optional[str] = 'by',
             alpha: Optional[float] = 0.05,
-            escalate_permutation: Optional[bool] = True
+            escalate_permutation: Optional[bool] = True,
+            n_processes: Optional[int] = 1
     ) -> xr.DataArray:
         """
         Compute the p-values for the specified statistical test. The p-values are stored in the MultiNeuronChatObject.
@@ -630,6 +739,11 @@ class MultiNeuronChatObject:
                                      floor with the deeper resample budget the correction requires (default: True).
                                      Only affects the 'Anderson' test, the only one whose analytical p-value is clamped
                                      and therefore always routed through the permutation fallback.
+        :param n_processes: number of processes to parallelise the per-triple loop across (default: 1, i.e. serial).
+                            Only the 'Anderson' test is parallelised, since it is the only one that always runs the
+                            (expensive) permutation fallback; the per-triple work is embarrassingly parallel and the
+                            result is identical to the serial run because every triple's randomness is seeded
+                            independently of the scheduling order.
         :return: the p-values as a DataArray.
         """
         mask = self._validate_or_make_mask(mask)
@@ -683,7 +797,8 @@ class MultiNeuronChatObject:
                 random_state=random_state,
                 escalate_permutation=escalate_permutation,
                 correction_method=correction_method,
-                alpha=alpha
+                alpha=alpha,
+                n_processes=n_processes
             )
         elif statistical_test == 'CVM':
             return self.__compute_p_values_CVM(
@@ -813,7 +928,8 @@ class MultiNeuronChatObject:
             random_state: Optional[int] = None,
             escalate_permutation: Optional[bool] = True,
             correction_method: Optional[str] = 'by',
-            alpha: Optional[float] = 0.05
+            alpha: Optional[float] = 0.05,
+            n_processes: Optional[int] = 1
     ) -> xr.DataArray:
         """
         Compute Anderson-Darling p-values, resampling deeply enough that they can survive multiple-testing correction.
@@ -847,6 +963,9 @@ class MultiNeuronChatObject:
         :param escalate_permutation: whether to run the second stage for floor-pinned triples (default: True)
         :param correction_method: the correction the p-values are intended for, used to size the second stage
         :param alpha: the significance level the p-values are intended to be judged at
+        :param n_processes: number of processes to distribute the per-triple loop across (default: 1, i.e. serial). Each
+                            triple is independent and its randomness is seeded independently of the scheduling order, so
+                            the result is identical to the serial run for any number of processes.
         :return: the p-values as a DataArray
         """
         mask = self._validate_or_make_mask(mask)
@@ -886,91 +1005,43 @@ class MultiNeuronChatObject:
 
         n_escalated: int = 0
 
+        # Build one independent task per tested triple. The scores are extracted here (cheap xarray slicing) rather than
+        # inside the workers so the workers never need the object itself. See the TODO preserved in the worker: both
+        # samples must have at least 2 values, which the worker checks and skips otherwise.
+        tasks: List[Tuple[Any, Any, Any, np.ndarray, np.ndarray, bool, int, int, bool, Optional[int]]] = []
         for source, receiver, interaction in zip(*idx):
             condition_a_communication_scores, condition_b_communication_scores = self.__get_communication_scores_for_p_value_test(
                 source=source,
                 receiver=receiver,
                 interaction=interaction
             )
+            tasks.append((
+                source, receiver, interaction,
+                condition_a_communication_scores, condition_b_communication_scores,
+                bool(permutation_method),
+                n_resamples_stage_one, n_resamples_stage_two,
+                escalate, random_state
+            ))
+
+        # The per-triple work is embarrassingly parallel and dominated by the permutation resampling of the few escalated
+        # triples, so a process pool with dynamic scheduling (chunksize=1) keeps every worker busy on the heavy triples
+        # rather than letting one straggler chunk serialise the run. Results are written by (source, receiver,
+        # interaction) index, so completion order is irrelevant and the output is identical for any n_processes.
+        if n_processes is None or n_processes <= 1:
+            results = [_compute_anderson_pvalue_for_triple(task) for task in tasks]
+        else:
+            with Pool(processes=n_processes) as pool:
+                results = list(pool.imap_unordered(_compute_anderson_pvalue_for_triple, tasks, chunksize=1))
 
-            # The Anderson Darling Test does work if all values of the data are the same
-            # Therefore we have to check if the data is the same and if so we have to skip the test
-            # IMPORTANT: this includes the case when both distributions are the same, e.g., both are completely zero
-            if np.unique(np.hstack([condition_a_communication_scores, condition_b_communication_scores])).shape[0] == 1:
-                continue
-
-            # TODO Check this; I had a bug, where when both samples are only one sample long, the Anderson test does not work.
-            # This seems to be the case because of an scipy implementation detail where they arrange N-1 sampes, i.e.,
-            # if N=1, then they have 0 samples. This then lead to an error for the Anderson test.
-            # Therefore, I have decided to restrict the test to the case where both samples have at least 2 samples.
-            # This is not ideal, but I think it is the best solution for now.
-            if len(condition_a_communication_scores) < 2 or len(condition_b_communication_scores) < 2:
+        for result in results:
+            if result is None:
                 continue
-
-            # Track whether the reported p-value came from a permutation run, and at what depth, so the escalation
-            # trigger and the zero-guard below both refer to the resolution that actually produced it.
-            n_resamples_used: Optional[int] = None
-
-            # First try the default (analytical/approximate) unless permutation was explicitly requested
-            if not permutation_method:
-                anderson_statistic = stats.anderson_ksamp(
-                    samples=[
-                        condition_a_communication_scores,
-                        condition_b_communication_scores,
-                    ]
-                )
-                p = float(anderson_statistic.pvalue)
-                # SciPy's approximate p can be clipped (~<=0.001). If clipped or non-finite, redo via permutation.
-                if self._needs_permutation(p, coarse_levels={0.001}):
-                    anderson_statistic = stats.anderson_ksamp(
-                        samples=[
-                            condition_a_communication_scores,
-                            condition_b_communication_scores,
-                        ],
-                        method=PermutationMethod(
-                            n_resamples=n_resamples_stage_one,
-                            random_state=random_state
-                        )
-                    )
-                    n_resamples_used = n_resamples_stage_one
-            else:
-                anderson_statistic = stats.anderson_ksamp(
-                    samples=[
-                        condition_a_communication_scores,
-                        condition_b_communication_scores
-                    ],
-                    method=PermutationMethod(
-                        n_resamples=n_resamples_stage_one,
-                        random_state=random_state
-                    )
-                )
-                n_resamples_used = n_resamples_stage_one
-
-            # Second stage: this triple's p-value is pinned at the resolution of the first stage and carries no
-            # information beyond "smaller than 1 / (R + 1)". Re-run it deeply enough to survive the correction, with
-            # fresh draws from a derived seed, and replace the first-stage value outright.
-            if escalate and self._is_at_monte_carlo_floor(float(anderson_statistic.pvalue), n_resamples_used):
-                anderson_statistic = stats.anderson_ksamp(
-                    samples=[
-                        condition_a_communication_scores,
-                        condition_b_communication_scores,
-                    ],
-                    method=PermutationMethod(
-                        n_resamples=n_resamples_stage_two,
-                        random_state=self._derive_seed(
-                            random_state=random_state,
-                            source=source,
-                            receiver=receiver,
-                            interaction=interaction
-                        )
-                    )
-                )
-                n_resamples_used = n_resamples_stage_two
+            source, receiver, interaction, p_value, test_statistic_value, escalated = result
+            p_values[source, receiver, interaction] = p_value
+            test_statistic[source, receiver, interaction] = test_statistic_value
+            if escalated:
                 n_escalated += 1
 
-            p_values[source, receiver, interaction] = self._ensure_nonzero_p(float(anderson_statistic.pvalue), n_resamples_used)
-            test_statistic[source, receiver, interaction] = float(anderson_statistic.statistic)
-
         # If escalation was disabled or capped below what the correction needs, p-values can still be pinned at the
         # Monte-Carlo floor. Those triples are unreportable no matter how large their effect, so say so explicitly
         # rather than letting them silently fail the correction.

{multineuronchat-2026.8.18.dev0 → multineuronchat-2026.9.1.dev0/src/multineuronchat.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multineuronchat
-Version: 2026.8.18.dev0
+Version: 2026.9.1.dev0
 Summary: MultiNeuronChat is a Python library for inferring condition‑related changes in synaptic cell‑cell communication from scRNA-/snRNA-Seq datasets in case vs control study designs.
 Author-email: Gianluca Volkmer <gianluca.volkmer@ki.se>
 License-Expression: GPL-3.0

{multineuronchat-2026.8.18.dev0 → multineuronchat-2026.9.1.dev0}/src/multineuronchat.egg-info/SOURCES.txt

@@ -21,4 +21,15 @@ src/multineuronchat/InteractionDB/__init__.py
 src/multineuronchat/db/__init__.py
 src/multineuronchat/db/interactionDB_human.pkl
 src/multineuronchat/db/interactionDB_human_extended.pkl
-src/multineuronchat/db/interactionDB_mouse.pkl
+src/multineuronchat/db/interactionDB_mouse.pkl
+tests/test_avg_expression.py
+tests/test_communication_score.py
+tests/test_correction.py
+tests/test_golden_master.py
+tests/test_interaction_db.py
+tests/test_masks.py
+tests/test_normalize.py
+tests/test_object_save_load.py
+tests/test_power.py
+tests/test_significance.py
+tests/test_utils_filter.py

multineuronchat-2026.9.1.dev0/tests/test_avg_expression.py

@@ -0,0 +1,272 @@
+"""Locks for the average-expression stage (``MultiNeuronChat.py``).
+
+``compute_subject_specific_avg_expression`` summarizes each gene across one
+subject's cells of a given type, with three mean flavors:
+
+* ``'mean'``      — plain arithmetic mean;
+* ``'tri_mean'``  — Tukey's trimean ``(q1 + 2*q2 + q3) / 4`` using
+  ``np.percentile`` (linear interpolation) — the default;
+* ``'trim_mean'`` — ``scipy.stats.trim_mean`` (needs ``trim_mean_fraction``).
+
+Each is pinned against a direct oracle on hand-known count columns. Also locked:
+the NaN-on-too-few-cells behavior (with its ``UserWarning``), the empty
+cell-type/subject combination (NaN + ``UserWarning``), and that cell types come
+out **sorted**.
+
+``compute_avg_expression`` fans the per-subject function over subjects and groups
+the results by condition, dropping subjects in neither condition. Its default
+``mean_type='trimean'`` is a *bug* (the accepted values are ``'tri_mean'`` /
+``'mean'`` / ``'trim_mean'``), so calling it with defaults raises ``ValueError``;
+that broken default is deliberately locked in here, not fixed.
+"""
+
+import numpy as np
+import pytest
+from scipy import stats
+
+import helpers
+from multineuronchat.MultiNeuronChat import (
+    compute_avg_expression,
+    compute_subject_specific_avg_expression,
+)
+
+
+# One subject (s1/ctrl), one cell type (A), four cells. Two genes with values
+# chosen so mean != trimean != trim_mean.
+_ARITH_GENES = ["G1", "G2"]
+_ARITH_COUNTS = np.array(
+    [
+        [1.0, 2.0, 3.0, 10.0],  # G1
+        [0.0, 1.0, 1.0, 2.0],   # G2
+    ]
+)
+
+
+def _arith_loom(tmp_path):
+    return helpers.make_loom(
+        tmp_path / "arith.loom",
+        counts=_ARITH_COUNTS,
+        gene_names=_ARITH_GENES,
+        subjects=["s1", "s1", "s1", "s1"],
+        conditions=["ctrl", "ctrl", "ctrl", "ctrl"],
+        cell_types=["A", "A", "A", "A"],
+    )
+
+
+def test_mean_matches_numpy_mean(tmp_path):
+    loom = _arith_loom(tmp_path)
+    avg = compute_subject_specific_avg_expression(
+        loom, subject_id="s1", subject_label_column="subject",
+        cell_type_label_column="cell_type", mean_type="mean",
+    )
+    expected = _ARITH_COUNTS.mean(axis=1)
+    np.testing.assert_allclose(avg.sel(cell_types="A").values, expected, rtol=1e-12)
+
+
+def test_tri_mean_matches_percentile_oracle(tmp_path):
+    loom = _arith_loom(tmp_path)
+    avg = compute_subject_specific_avg_expression(
+        loom, subject_id="s1", subject_label_column="subject",
+        cell_type_label_column="cell_type", mean_type="tri_mean",
+    )
+    q1 = np.percentile(_ARITH_COUNTS, 25, axis=1)
+    q2 = np.percentile(_ARITH_COUNTS, 50, axis=1)
+    q3 = np.percentile(_ARITH_COUNTS, 75, axis=1)
+    expected = (q1 + 2 * q2 + q3) / 4
+    np.testing.assert_allclose(avg.sel(cell_types="A").values, expected, rtol=1e-12)
+
+
+def test_tri_mean_is_the_default(tmp_path):
+    loom = _arith_loom(tmp_path)
+    default = compute_subject_specific_avg_expression(
+        loom, subject_id="s1", subject_label_column="subject",
+        cell_type_label_column="cell_type",
+    )
+    explicit = compute_subject_specific_avg_expression(
+        loom, subject_id="s1", subject_label_column="subject",
+        cell_type_label_column="cell_type", mean_type="tri_mean",
+    )
+    np.testing.assert_allclose(default.values, explicit.values, rtol=1e-12)
+
+
+def test_trim_mean_matches_scipy_oracle(tmp_path):
+    loom = _arith_loom(tmp_path)
+    avg = compute_subject_specific_avg_expression(
+        loom, subject_id="s1", subject_label_column="subject",
+        cell_type_label_column="cell_type", mean_type="trim_mean",
+        trim_mean_fraction=0.25,
+    )
+    expected = stats.trim_mean(_ARITH_COUNTS, 0.25, axis=1)
+    np.testing.assert_allclose(avg.sel(cell_types="A").values, expected, rtol=1e-12)
+
+
+# Richer loom: subject s1 (ctrl) has cell type A x3 and B x1; subject s2 (case)
+# has A x2 and NO B. Used for threshold / empty-combo / sorting locks.
+def _mixed_loom(tmp_path):
+    return helpers.make_loom(
+        tmp_path / "mixed.loom",
+        counts=np.array([[1.0, 2.0, 3.0, 9.0, 4.0, 6.0]]),  # single gene G1
+        gene_names=["G1"],
+        subjects=["s1", "s1", "s1", "s1", "s2", "s2"],
+        conditions=["ctrl", "ctrl", "ctrl", "ctrl", "case", "case"],
+        cell_types=["A", "A", "A", "B", "A", "A"],
+    )
+
+
+def test_min_n_cells_threshold_sets_undersized_celltype_nan(tmp_path):
+    loom = _mixed_loom(tmp_path)
+    with pytest.warns(UserWarning):
+        avg = compute_subject_specific_avg_expression(
+            loom, subject_id="s1", subject_label_column="subject",
+            cell_type_label_column="cell_type", mean_type="mean",
+            min_n_cells_threshold=2,
+        )
+    # A has 3 cells (>=2) -> computed; B has 1 cell (<2) -> NaN.
+    np.testing.assert_allclose(avg.sel(cell_types="A").values, [2.0], rtol=1e-12)
+    assert np.isnan(avg.sel(cell_types="B").values).all()
+
+
+def test_missing_celltype_for_subject_is_nan_and_warns(tmp_path):
+    loom = _mixed_loom(tmp_path)
+    # s2 has cell type A but no B -> B column is NaN and a UserWarning fires.
+    with pytest.warns(UserWarning):
+        avg = compute_subject_specific_avg_expression(
+            loom, subject_id="s2", subject_label_column="subject",
+            cell_type_label_column="cell_type", mean_type="mean",
+        )
+    np.testing.assert_allclose(avg.sel(cell_types="A").values, [5.0], rtol=1e-12)
+    assert np.isnan(avg.sel(cell_types="B").values).all()
+
+
+def test_cell_types_are_sorted(tmp_path):
+    loom = helpers.make_loom(
+        tmp_path / "sorted.loom",
+        counts=np.array([[1.0, 2.0, 3.0]]),
+        gene_names=["G1"],
+        subjects=["s1", "s1", "s1"],
+        conditions=["ctrl", "ctrl", "ctrl"],
+        cell_types=["C", "A", "B"],  # deliberately unsorted
+    )
+    avg = compute_subject_specific_avg_expression(
+        loom, subject_id="s1", subject_label_column="subject",
+        cell_type_label_column="cell_type", mean_type="mean",
+    )
+    assert list(avg.coords["cell_types"].values) == ["A", "B", "C"]
+
+
+# --------------------------------------------------------------------------- #
+# Validation of the per-subject function.
+# --------------------------------------------------------------------------- #
+def test_missing_file_raises(tmp_path):
+    with pytest.raises(FileNotFoundError):
+        compute_subject_specific_avg_expression(
+            str(tmp_path / "nope.loom"), subject_id="s1",
+            subject_label_column="subject", cell_type_label_column="cell_type",
+        )
+
+
+def test_non_loom_extension_raises(tmp_path):
+    bogus = tmp_path / "data.txt"
+    bogus.write_text("not a loom")
+    with pytest.raises(ValueError):
+        compute_subject_specific_avg_expression(
+            str(bogus), subject_id="s1",
+            subject_label_column="subject", cell_type_label_column="cell_type",
+        )
+
+
+def test_bad_mean_type_raises(tmp_path):
+    loom = _arith_loom(tmp_path)
+    with pytest.raises(ValueError):
+        compute_subject_specific_avg_expression(
+            loom, subject_id="s1", subject_label_column="subject",
+            cell_type_label_column="cell_type", mean_type="median",
+        )
+
+
+def test_trim_mean_without_fraction_raises(tmp_path):
+    loom = _arith_loom(tmp_path)
+    with pytest.raises(ValueError):
+        compute_subject_specific_avg_expression(
+            loom, subject_id="s1", subject_label_column="subject",
+            cell_type_label_column="cell_type", mean_type="trim_mean",
+        )
+
+
+def test_empty_subject_id_raises(tmp_path):
+    loom = _arith_loom(tmp_path)
+    with pytest.raises(ValueError):
+        compute_subject_specific_avg_expression(
+            loom, subject_id="", subject_label_column="subject",
+            cell_type_label_column="cell_type",
+        )
+
+
+# --------------------------------------------------------------------------- #
+# compute_avg_expression orchestration.
+# --------------------------------------------------------------------------- #
+def _three_condition_loom(tmp_path):
+    # s1 -> ctrl, s2 -> case, s3 -> other (must be dropped).
+    return helpers.make_loom(
+        tmp_path / "three.loom",
+        counts=np.array([[1.0, 2.0, 3.0, 4.0, 5.0, 6.0]]),
+        gene_names=["G1"],
+        subjects=["s1", "s1", "s2", "s2", "s3", "s3"],
+        conditions=["ctrl", "ctrl", "case", "case", "other", "other"],
+        cell_types=["A", "A", "A", "A", "A", "A"],
+    )
+
+
+def test_avg_expression_groups_by_condition_and_drops_outsiders(tmp_path):
+    loom = _three_condition_loom(tmp_path)
+    result = compute_avg_expression(
+        path_to_loom=loom,
+        condition_label_column="condition",
+        condition_label_a="ctrl", condition_label_b="case",
+        subject_label_column="subject", cell_type_label_column="cell_type",
+        mean_type="mean", n_processes=1,
+    )
+    assert set(result.keys()) == {"ctrl", "case"}
+    assert set(result["ctrl"].keys()) == {"s1"}
+    assert set(result["case"].keys()) == {"s2"}
+    # s3 (condition 'other') appears nowhere.
+    assert "s3" not in result["ctrl"] and "s3" not in result["case"]
+    np.testing.assert_allclose(result["ctrl"]["s1"].sel(cell_types="A").values, [1.5], rtol=1e-12)
+
+
+def test_avg_expression_default_mean_type_is_broken_and_raises(tmp_path):
+    """Locked bug: the default ``mean_type='trimean'`` is not an accepted value
+    (the valid spelling is ``'tri_mean'``), so a defaults call raises ValueError."""
+    loom = _three_condition_loom(tmp_path)
+    with pytest.raises(ValueError):
+        compute_avg_expression(
+            path_to_loom=loom,
+            condition_label_column="condition",
+            condition_label_a="ctrl", condition_label_b="case",
+            subject_label_column="subject", cell_type_label_column="cell_type",
+            n_processes=1,
+        )
+
+
+def test_avg_expression_equal_conditions_raises(tmp_path):
+    loom = _three_condition_loom(tmp_path)
+    with pytest.raises(ValueError):
+        compute_avg_expression(
+            path_to_loom=loom,
+            condition_label_column="condition",
+            condition_label_a="ctrl", condition_label_b="ctrl",
+            subject_label_column="subject", cell_type_label_column="cell_type",
+            mean_type="mean", n_processes=1,
+        )
+
+
+def test_avg_expression_non_positive_n_processes_raises(tmp_path):
+    loom = _three_condition_loom(tmp_path)
+    with pytest.raises(ValueError):
+        compute_avg_expression(
+            path_to_loom=loom,
+            condition_label_column="condition",
+            condition_label_a="ctrl", condition_label_b="case",
+            subject_label_column="subject", cell_type_label_column="cell_type",
+            mean_type="mean", n_processes=0,
+        )