ccc: rename pvalue-related parameters and add pvalue_chunksize

Author: miltondp

libs/ccc/coef/impl.py

@@ -310,10 +310,11 @@ def ccc(
     internal_n_clusters: Union[int, Iterable[int]] = None,
     return_parts: bool = False,
     n_chunks_threads_ratio: int = 1,
-    pvalue_n_permutations: int = None,
+    pvalue_n_perms: int = None,
     random_state: int = None,
     n_jobs: int = 1,
-    n_jobs_permutations: int = 1,
+    pvalue_n_jobs: int = 1,
+    pvalue_chunksize: int = 100,
 ) -> tuple[NDArray[float], NDArray[float], NDArray[np.uint64], NDArray[np.int16]]:
     """
     This is the main function that computes the Clustermatch Correlation
@@ -334,15 +335,18 @@ def ccc(
         n_chunks_threads_ratio: allows to modify how pairwise comparisons are
           split across different threads. It's given as the ratio parameter of
           function get_chunks.
-        pvalue_n_permutations: if given, it computes the p-value of the
+        pvalue_n_perms: if given, it computes the p-value of the
             coefficient using the given number of permutations.
         random_state: seed for the random number generator. This is used to compute
             the p-value of the coefficient using permutations.
         n_jobs: number of CPU cores to use for parallelization. The value
           None will use all available cores (`os.cpu_count()`), and negative
           values will use `os.cpu_count() - n_jobs`. Default is 1.
-        n_jobs_permutations: number of CPU cores to use for parallelization when
+        pvalue_n_jobs: number of CPU cores to use for parallelization when
             computing the p-value of the coefficient using permutations.
+        pvalue_chunksize: number of permutations to compute in each chunk when
+            computing the p-value of the coefficient using permutations. It's the
+            chunksize parameter of the executor.map function.
 
 
     Returns:
@@ -545,9 +549,9 @@ def compute_coef(idx_list):
                 max_ari_list[idx] = np.max((comp_values[max_idx], 0.0))
 
                 # compute p-value if requested
-                if pvalue_n_permutations is not None and pvalue_n_permutations > 0:
+                if pvalue_n_perms is not None and pvalue_n_perms > 0:
                     with ThreadPoolExecutor(
-                        max_workers=n_jobs_permutations
+                        max_workers=pvalue_n_jobs
                     ) as executor_perms:
                         # select the variable that generated more partitions as the one
                         # to permute
@@ -560,7 +564,7 @@ def compute_coef(idx_list):
                             obj_parts_sel_j = obji_parts
 
                         cdist_here = cdist_parts_basic
-                        if n_jobs_permutations == 1:
+                        if pvalue_n_jobs == 1:
                             cdist_here = cdist_func
 
                         def compute_permutations(_):
@@ -586,24 +590,20 @@ def compute_permutations(_):
                             )
                             return np.max((p_comp_values[p_max_idx], 0.0))
 
-                        p_ccc_values = np.full(
-                            pvalue_n_permutations, np.nan, dtype=float
-                        )
+                        p_ccc_values = np.full(pvalue_n_perms, np.nan, dtype=float)
                         for p_idx, p_ccc_val in zip(
-                            np.arange(pvalue_n_permutations),
+                            np.arange(pvalue_n_perms),
                             executor_perms.map(
                                 compute_permutations,
-                                np.arange(pvalue_n_permutations),
-                                chunksize=100,
+                                np.arange(pvalue_n_perms),
+                                chunksize=pvalue_chunksize,
                             ),
                         ):
-                            # for i in range(pvalue_n_permutations):
                             p_ccc_values[p_idx] = p_ccc_val
-                            # p_ccc_values[i] = compute_permutations()
 
                     # compute p-value
                     pvalues[idx] = (np.sum(p_ccc_values >= max_ari_list[idx]) + 1) / (
-                        pvalue_n_permutations + 1
+                        pvalue_n_perms + 1
                     )
 
             return max_ari_list, max_part_idx_list, pvalues
@@ -621,23 +621,23 @@ def compute_permutations(_):
     # return an array of values or a single scalar, depending on the input data
     if cm_values.shape[0] == 1:
         if return_parts:
-            if pvalue_n_permutations is not None and pvalue_n_permutations > 0:
+            if pvalue_n_perms is not None and pvalue_n_perms > 0:
                 return (cm_values[0], cm_pvalues[0]), max_parts[0], parts
             else:
                 return cm_values[0], max_parts[0], parts
         else:
-            if pvalue_n_permutations is not None and pvalue_n_permutations > 0:
+            if pvalue_n_perms is not None and pvalue_n_perms > 0:
                 return cm_values[0], cm_pvalues[0]
             else:
                 return cm_values[0]
 
     if return_parts:
-        if pvalue_n_permutations is not None and pvalue_n_permutations > 0:
+        if pvalue_n_perms is not None and pvalue_n_perms > 0:
             return (cm_values, cm_pvalues), max_parts, parts
         else:
             return cm_values, max_parts, parts
     else:
-        if pvalue_n_permutations is not None and pvalue_n_permutations > 0:
+        if pvalue_n_perms is not None and pvalue_n_perms > 0:
             return cm_values, cm_pvalues
         else:
             return cm_values

tests/test_coef_pval.py

@@ -20,7 +20,7 @@ def test_cm_basic_pvalue_n_permutations_not_given():
     feature1 = rs.rand(100)
 
     # Run
-    cm_value = ccc(feature0, feature1, pvalue_n_permutations=None)
+    cm_value = ccc(feature0, feature1, pvalue_n_perms=None)
 
     # Validate
     assert cm_value is not None
@@ -37,7 +37,7 @@ def test_cm_basic_pvalue_n_permutations_is_zero():
     feature1 = rs.rand(100)
 
     # Run
-    cm_value = ccc(feature0, feature1, pvalue_n_permutations=0)
+    cm_value = ccc(feature0, feature1, pvalue_n_perms=0)
 
     # Validate
     assert cm_value is not None
@@ -54,7 +54,7 @@ def test_cm_basic_pvalue_n_permutations_is_1():
     feature1 = rs.rand(100)
 
     # Run
-    res = ccc(feature0, feature1, pvalue_n_permutations=1)
+    res = ccc(feature0, feature1, pvalue_n_perms=1)
 
     # Validate
     assert len(res) == 2
@@ -78,7 +78,7 @@ def test_cm_basic_pvalue_n_permutations_is_10():
     feature1 = rs.rand(100)
 
     # Run
-    res = ccc(feature0, feature1, pvalue_n_permutations=10)
+    res = ccc(feature0, feature1, pvalue_n_perms=10)
 
     # Validate
     assert len(res) == 2
@@ -101,7 +101,7 @@ def test_cm_linear_pvalue_n_permutations_10():
     feature1 = feature0 * 5.0
 
     # Run
-    res = ccc(feature0, feature1, pvalue_n_permutations=10)
+    res = ccc(feature0, feature1, pvalue_n_perms=10)
 
     # Validate
     assert len(res) == 2
@@ -124,7 +124,7 @@ def test_cm_linear_pvalue_n_permutations_100():
     feature1 = feature0 * 5.0
 
     # Run
-    res = ccc(feature0, feature1, pvalue_n_permutations=100)
+    res = ccc(feature0, feature1, pvalue_n_perms=100)
 
     # Validate
     assert len(res) == 2
@@ -147,7 +147,7 @@ def test_cm_quadratic_pvalue():
     feature1 = np.power(feature0, 2.0)
 
     # Run
-    res = ccc(feature0, feature1, pvalue_n_permutations=100)
+    res = ccc(feature0, feature1, pvalue_n_perms=100)
 
     # Validate
     assert len(res) == 2
@@ -170,7 +170,7 @@ def test_cm_quadratic_noisy_pvalue_with_random_state():
     feature1 = np.power(feature0, 2.0) + (2.0 * rs.rand(feature0.shape[0]))
 
     # Run
-    res = ccc(feature0, feature1, pvalue_n_permutations=100, random_state=2)
+    res = ccc(feature0, feature1, pvalue_n_perms=100, random_state=2)
 
     # Validate
     assert len(res) == 2
@@ -196,7 +196,7 @@ def test_cm_one_feature_with_all_same_values_pvalue():
     feature1 = np.array([5] * feature0.shape[0])
 
     # Run
-    res = ccc(feature0, feature1, pvalue_n_permutations=100)
+    res = ccc(feature0, feature1, pvalue_n_perms=100)
 
     # Validate
     assert len(res) == 2
@@ -222,7 +222,7 @@ def test_cm_single_argument_is_matrix():
     input_data = np.array([feature0, feature1, feature2])
 
     # Run
-    res = ccc(input_data, pvalue_n_permutations=100, random_state=1)
+    res = ccc(input_data, pvalue_n_perms=100, random_state=1)
 
     # Validate
     assert len(res) == 2
@@ -252,11 +252,11 @@ def test_cm_large_n_objects_pvalue_computation_is_parallelized():
 
     # Run
     start_time = time.time()
-    res = ccc(feature0, feature1, pvalue_n_permutations=50, n_jobs=1)
+    res = ccc(feature0, feature1, pvalue_n_perms=50, n_jobs=1)
     elapsed_time_single_thread = time.time() - start_time
 
     start_time = time.time()
-    res = ccc(feature0, feature1, pvalue_n_permutations=50, n_jobs=2)
+    res = ccc(feature0, feature1, pvalue_n_perms=50, n_jobs=2)
     elapsed_time_multi_thread = time.time() - start_time
 
     # Validate
@@ -273,11 +273,11 @@ def test_cm_medium_n_objects_with_many_pvalue_computation_is_parallelized():
 
     # Run
     start_time = time.time()
-    res = ccc(feature0, feature1, pvalue_n_permutations=1000, n_jobs=1)
+    res = ccc(feature0, feature1, pvalue_n_perms=1000, n_jobs=1)
     elapsed_time_single_thread = time.time() - start_time
 
     start_time = time.time()
-    res = ccc(feature0, feature1, pvalue_n_permutations=1000, n_jobs_permutations=2)
+    res = ccc(feature0, feature1, pvalue_n_perms=1000, pvalue_n_jobs=2)
     elapsed_time_multi_thread = time.time() - start_time
 
     # Validate
@@ -298,7 +298,7 @@ def test_cm_return_parts_quadratic_pvalue():
         feature1,
         internal_n_clusters=[2, 3],
         return_parts=True,
-        pvalue_n_permutations=10,
+        pvalue_n_perms=10,
     )
 
     # Validate
@@ -350,7 +350,7 @@ def test_cm_numerical_and_categorical_features_perfect_relationship_pvalue():
     res = ccc(
         numerical_feature0,
         categorical_feature1,
-        pvalue_n_permutations=100,
+        pvalue_n_perms=100,
     )
 
     # Validate
@@ -366,9 +366,7 @@ def test_cm_numerical_and_categorical_features_perfect_relationship_pvalue():
     assert pvalue == (0 + 1) / (100 + 1)
 
     # Run with flipped variables (symmetry)
-    assert (
-        ccc(categorical_feature1, numerical_feature0, pvalue_n_permutations=100) == res
-    )
+    assert ccc(categorical_feature1, numerical_feature0, pvalue_n_perms=100) == res
 
 
 def test_cm_numerical_and_categorical_features_weakly_relationship_pvalue():
@@ -397,7 +395,7 @@ def test_cm_numerical_and_categorical_features_weakly_relationship_pvalue():
     res = ccc(
         categorical_feature1,
         numerical_feature0,
-        pvalue_n_permutations=100,
+        pvalue_n_perms=100,
         random_state=1,
     )
 
@@ -418,7 +416,7 @@ def test_cm_numerical_and_categorical_features_weakly_relationship_pvalue():
         ccc(
             numerical_feature0,
             categorical_feature1,
-            pvalue_n_permutations=100,
+            pvalue_n_perms=100,
             random_state=1,
         )
         == res
@@ -442,7 +440,7 @@ def test_cm_numerical_and_categorical_features_a_single_categorical_value():
     res = ccc(
         numerical_feature0,
         categorical_feature1,
-        pvalue_n_permutations=100,
+        pvalue_n_perms=100,
         random_state=1,
     )
 
@@ -463,7 +461,7 @@ def test_cm_numerical_and_categorical_features_a_single_categorical_value():
         ccc(
             categorical_feature1,
             numerical_feature0,
-            pvalue_n_permutations=100,
+            pvalue_n_perms=100,
             random_state=1,
         )
         == res
@@ -478,7 +476,7 @@ def test_cm_with_pandas_dataframe_several_features():
     data = pd.DataFrame(rs.rand(20, 50))
 
     # Run
-    res = ccc(data, internal_n_clusters=3, pvalue_n_permutations=10, random_state=1)
+    res = ccc(data, internal_n_clusters=3, pvalue_n_perms=10, random_state=1)
 
     # Validate
     assert len(res) == 2