Implement `tissue_correlation` function

Issue:
https://github.com/genenetwork/gn-gemtext-threads/blob/main/topics/gn1-migration-to-gn2/partial-correlations.gmi

* gn3/computations/partial_correlations.py: New function (tissue_correlation)
* tests/unit/test_partial_correlations.py ->
  tests/unit/computations/test_partial_correlations.py: Move module. Implement
  tests for new function

  Migrate the `cal_tissue_corr` function embedded in the
  `web.webqtl.correlation.correlationFunction.batchCalTissueCorr` function in
  GN1 and implement tests to ensure it works correctly.

2 files changed, 79 insertions, 5 deletions

diff --git a/gn3/computations/partial_correlations.py b/gn3/computations/partial_correlations.py
index b3de31c..e73edfd 100644
--- a/gn3/computations/partial_correlations.py
+++ b/gn3/computations/partial_correlations.py
@@ -7,6 +7,7 @@ GeneNetwork1.
 
 from functools import reduce
 from typing import Any, Tuple, Sequence
+from scipy.stats import pearsonr, spearmanr
 
 def control_samples(controls: Sequence[dict], sampleslist: Sequence[str]):
     """
@@ -123,6 +124,32 @@ def find_identical_traits(
                  if len(item[1]) > 1),
                 tuple()))
 
+def tissue_correlation(
+        primary_trait_values: Tuple[float, ...],
+        target_trait_values: Tuple[float, ...],
+        method: str) -> Tuple[float, float]:
+    """
+    Compute the correlation between the primary trait values, and the values of
+    a single target value.
+
+    This migrates the `cal_tissue_corr` function embedded in the larger
+    `web.webqtl.correlation.correlationFunction.batchCalTissueCorr` function in
+    GeneNetwork1.
+    """
+    def spearman_corr(*args):
+        result = spearmanr(*args)
+        return (result.correlation, result.pvalue)
+
+    method_fns = {"pearson": pearsonr, "spearman": spearman_corr}
+
+    assert len(primary_trait_values) == len(target_trait_values), (
+        "The lengths of the `primary_trait_values` and `target_trait_values` "
+        "must be equal")
+    assert method in method_fns.keys(), (
+        "Method must be one of: {}".format(",".join(method_fns.keys())))
+
+    return method_fns[method](primary_trait_values, target_trait_values)
+
 def batch_computed_tissue_correlation(
         trait_value: str, symbol_value_dict: dict,
         method: str = "pearson") -> Tuple[dict, dict]:
diff --git a/tests/unit/test_partial_correlations.py b/tests/unit/computations/test_partial_correlations.py
index 60e54c1..7ff8b80 100644
--- a/tests/unit/test_partial_correlations.py
+++ b/tests/unit/computations/test_partial_correlations.py
@@ -1,11 +1,7 @@
 """Module contains tests for gn3.partial_correlations"""
 
 from unittest import TestCase
-from gn3.partial_correlations import (
-    fix_samples,
-    control_samples,
-    dictify_by_samples,
-    find_identical_traits)
+from gn3.computations.partial_correlations import *
 
 sampleslist = ["B6cC3-1", "BXD1", "BXD12", "BXD16", "BXD19", "BXD2"]
 control_traits = (
@@ -209,3 +205,54 @@ class TestPartialCorrelations(TestCase):
                     control_names=contn, control_values=contv):
                 self.assertEqual(
                     find_identical_traits(primn, primv, contn, contv), expected)
+
+    def test_tissue_correlation_error(self):
+        """
+        Test that `tissue_correlation` raises specific exceptions for particular
+        error conditions.
+        """
+        for primary, target, method, error, error_msg in (
+                ((1,2,3), (4,5,6,7), "pearson",
+                 AssertionError,
+                 (
+                     "The lengths of the `primary_trait_values` and "
+                     "`target_trait_values` must be equal")),
+                ((1,2,3), (4,5,6,7), "spearman",
+                 AssertionError,
+                 (
+                     "The lengths of the `primary_trait_values` and "
+                     "`target_trait_values` must be equal")),
+                ((1,2,3,4), (5,6,7), "pearson",
+                 AssertionError,
+                 (
+                     "The lengths of the `primary_trait_values` and "
+                     "`target_trait_values` must be equal")),
+                ((1,2,3,4), (5,6,7), "spearman",
+                 AssertionError,
+                 (
+                     "The lengths of the `primary_trait_values` and "
+                     "`target_trait_values` must be equal")),
+                ((1,2,3), (4,5,6), "nonexistentmethod",
+                 AssertionError,
+                 (
+                     "Method must be one of: pearson, spearman"))):
+            with self.subTest(primary=primary, target=target, method=method):
+                with self.assertRaises(error, msg=error_msg):
+                    tissue_correlation(primary, target, method)
+
+    def test_tissue_correlation(self):
+        """
+        Test that the correct correlation values are computed for the given:
+        - primary trait
+        - target trait
+        - method
+        """
+        for primary, target, method, expected in (
+                ((12.34, 18.36, 42.51), (37.25, 46.25, 46.56), "pearson",
+                 (0.6761779252651052, 0.5272701133657985)),
+                ((1, 2, 3, 4, 5), (5, 6, 7, 8, 7), "spearman",
+                 (0.8207826816681233, 0.08858700531354381))
+        ):
+            with self.subTest(primary=primary, target=target, method=method):
+                self.assertEqual(
+                    tissue_correlation(primary, target, method), expected)