BiFuncLib 1.0.2__tar.gz → 1.0.4__tar.gz

{bifunclib-1.0.2 → bifunclib-1.0.4}/BiFuncLib/bimax_biclus.py

@@ -4,8 +4,10 @@ from BiFuncLib.BiclustResult import BiclustResult
 
 
 def apriori_bimax(matrix, minr=2, minc=2, number=100):
+    # Get matrix dimensions
     rows = len(matrix)
     cols = len(matrix[0]) if rows else 0
+    # Convert each row to a bitmask for efficient column intersection
     row_masks = []
     for row in matrix:
         m = 0
@@ -13,6 +15,7 @@ def apriori_bimax(matrix, minr=2, minc=2, number=100):
             if v:
                 m |= 1 << j
         row_masks.append(m)
+    # Generate frequent 1-itemsets (single columns meeting min row support)
     L1 = []
     for j in range(cols):
         bit = 1 << j
@@ -22,11 +25,13 @@ def apriori_bimax(matrix, minr=2, minc=2, number=100):
     freq_sets = []
     if minc <= 1:
         freq_sets.extend(L1)
+    # Apriori algorithm: iteratively build larger itemsets from smaller ones
     k = 1
     prev_L = L1
     while prev_L and k < cols:
         Ck = {}
         n = len(prev_L)
+        # Join step: combine itemsets that share (k-1) prefix
         for a in range(n):
             items_a, mask_a, _ = prev_L[a]
             for b in range(a + 1, n):
@@ -49,6 +54,7 @@ def apriori_bimax(matrix, minr=2, minc=2, number=100):
         prev_L = list(Ck.values())
         if k >= minc:
             freq_sets.extend(prev_L)
+    # Sort by itemset size (descending) then support (descending)
     freq_sets.sort(key=lambda x: (len(x[0]), x[2]), reverse=True)
     maximal = []
     for items, mask, sup in freq_sets:
@@ -57,6 +63,7 @@ def apriori_bimax(matrix, minr=2, minc=2, number=100):
             maximal.append((items, mask, sup))
         if len(maximal) >= number:
             break
+    # Convert to bicluster format with row and column indices
     biclusters = []
     for items, mask, sup in maximal:
         rows_res = [i for i, rm in enumerate(row_masks) if (rm & mask) == mask]
@@ -66,17 +73,21 @@ def apriori_bimax(matrix, minr=2, minc=2, number=100):
 
 
 def bimax_biclus(matrix, minr=2, minc=2, number=100):
+    # Run Apriori-Bimax to get raw biclusters
     raw = apriori_bimax(matrix, minr, minc, number)
     bic_n = len(raw)
     R = len(matrix)
     C = len(matrix[0]) if R else 0
+    # Build RowxNumber matrix: rows x biclusters membership
     RowxNumber = [[False] * bic_n for _ in range(R)]
+    # Build NumberxCol matrix: biclusters x columns membership
     NumberxCol = [[False] * C for _ in range(bic_n)]
     for idx, bc in enumerate(raw):
         for r in bc["rows"]:
             RowxNumber[r][idx] = True
         for c in bc["cols"]:
             NumberxCol[idx][c] = True
+    # Return structured bicluster result object
     return BiclustResult(
         {
             "Algorithm": "Apriori-Bimax",

{bifunclib-1.0.2 → bifunclib-1.0.4}/BiFuncLib/cc_bifunc.py

@@ -22,7 +22,7 @@ def cc_bifunc(
     max_iter_align=100,
 ):
 
-    # Check inputs
+    # Validate input parameters
     if len(data.shape) != 3:
         raise ValueError("Error: data should be an array of three dimensions")
     if template_type == "medoid" and (alpha != 0 or beta != 0):
@@ -50,7 +50,7 @@ def cc_bifunc(
     if delta < 0:
         raise ValueError("Error: delta must be a number greater than 0")
 
-    # Initialize parameters
+    # Initialize algorithm parameters and matrices
     n, m, p = data.shape
     parameter_input = {
         "delta": [delta],
@@ -64,6 +64,7 @@ def cc_bifunc(
         "shift_max": [shift_max],
         "max_iter_align": [max_iter_align],
     }
+    # Determine constraint mode based on alpha/beta settings
     if alpha == 0 and beta == 0:
         only_one = "True"
     elif alpha == 0 and beta != 0:
@@ -72,6 +73,7 @@ def cc_bifunc(
         only_one = "True_alpha"
     elif alpha != 0 and beta != 0:
         only_one = "False"
+    # Initialize membership matrices
     x = np.full((n, number), False, dtype=bool)
     y = np.full((number, m), False, dtype=bool)
     xy = np.zeros((n, m), dtype=int)
@@ -89,6 +91,7 @@ def cc_bifunc(
             submat = data[logr, :, 0][:, logc]
             rows_with_all_nan = np.all(np.isnan(submat), axis=1)
             logr[logr] = ~rows_with_all_nan
+        # Check stopping conditions based on constraint mode
         if (
             (
                 only_one == "False"
@@ -128,6 +131,7 @@ def cc_bifunc(
             submat = data[logr, :, 0][:, logc]
             cols_with_all_nan = np.all(np.isnan(submat), axis=0)
             logc[logc] = ~cols_with_all_nan
+        # Check stopping conditions
         if (
             (
                 only_one == "False"
@@ -163,6 +167,7 @@ def cc_bifunc(
             )
         ):
             break
+        # Apply Cheng-Church algorithm to current submatrix
         fun_mat_temp = data[logr][:, logc, :]
         erg = bigcc_fun(
             fun_mat_temp,
@@ -190,12 +195,14 @@ def cc_bifunc(
             logc = np.full(xy.shape[1], False, dtype=bool)
             logc[np.array(clus_col)[cl - 1, :]] = True
         else:
+            # Store found bicluster
             k += 1
             true_rows = np.where(logr)[0]
             x[true_rows, k - 1] = erg[0]
             true_cols = np.where(logc)[0]
             y[k - 1, true_cols] = erg[1]
             xy = xy + np.outer(x[:, k - 1].astype(int), y[k - 1, :].astype(int))
+            # Find overlapping biclusters using Bimax
             if only_one == "False":
                 res = bimax_biclus(1 - xy, minr=2, minc=2, number=100)
             elif only_one == "True":
@@ -210,6 +217,7 @@ def cc_bifunc(
                 break
             clus_row = res.RowxNumber
             clus_col = res.NumberxCol
+            # Filter out single-element biclusters
             d_rows = np.sum(clus_row, axis=0)
             d_cols = np.sum(clus_col, axis=1)
             dimensioni = d_rows * d_cols
@@ -222,6 +230,7 @@ def cc_bifunc(
                 clus_col = np.array(clus_col)[if_oneone, :]
             if n_clust == 0:
                 break
+            # Sort biclusters by size (descending)
             if n_clust > 1:
                 d = np.sum(clus_row, axis=0) * np.sum(clus_col, axis=1)
                 sorted_idx = np.argsort(-d)
@@ -232,7 +241,7 @@ def cc_bifunc(
             logc = np.full(xy.shape[1], False, dtype=bool)
             logc[np.array(clus_col)[0, :]] = True
 
-    # Return results
+    # Sort final biclusters by size
     clus_row_final = x[:, :k]
     clus_col_final = y[:k, :]
     if k > 1:
@@ -248,7 +257,7 @@ def cc_bifunc(
     }
     return result
 
-
+# Cross-validation for delta parameter selection
 def cc_bifunc_cv(
     data,
     delta_list,
@@ -288,11 +297,13 @@ def cc_bifunc_cv(
             shift_max=shift_max,
             max_iter_align=max_iter_align,
         )
+        # Handle no clusters found
         if res_fun["Number"] == 0:
             Htot_all_mean_list.append(np.nan)
             Htot_sum_list.append(np.nan)
             num_clust_list.append(0)
             not_assigned_list.append(data.shape[0] * data.shape[1])
+        # Evaluate single bicluster
         elif res_fun["Number"] == 1:
             row_mask = res_fun["RowxNumber"]
             col_mask = res_fun["NumberxCol"]
@@ -316,6 +327,7 @@ def cc_bifunc_cv(
             Htot_all_mean_list.append(Htot_d)
             Htot_sum_list.append(np.sum(H_cl))
             num_clust_list.append(1)
+        # Evaluate multiple biclusters
         elif res_fun["Number"] > 1:
             num_clust_list.append(res_fun["Number"])
             H_cl = []

{bifunclib-1.0.2 → bifunclib-1.0.4}/BiFuncLib/cc_main_func.py

@@ -3,7 +3,7 @@ from scipy.optimize import minimize_scalar
 from scipy.interpolate import interp1d
 from scipy.spatial.distance import pdist, squareform
 
-
+# Compute medoid-based template using pairwise distances
 def medoid_evaluation(fun_mat, a, b, const_a, const_b):
     n, m, p = fun_mat.shape
     fun_per_medoid = fun_mat.reshape(n * m, p)
@@ -16,7 +16,7 @@ def medoid_evaluation(fun_mat, a, b, const_a, const_b):
     new_fun = np.tile(medoid_fun, (n, m, 1))
     return new_fun
 
-
+# Compute medoid template for selected rows/columns only
 def medoid_evaluation_add(fun_mat, logr, logc, a, b, const_a, const_b):
     n, m, p = fun_mat.shape
     filtered_fun_mat = fun_mat[logr, :, :][:, logc, :]
@@ -31,7 +31,7 @@ def medoid_evaluation_add(fun_mat, logr, logc, a, b, const_a, const_b):
     new_fun = np.tile(medoid_fun, (n, m, 1))
     return new_fun
 
-
+# Compute mean-based template with row and column effects
 def template_evaluation(fun_mat, a, b, const_a, const_b):
     n, m, p = fun_mat.shape
     count_null = np.sum(np.isnan(fun_mat), axis=2)
@@ -65,7 +65,7 @@ def template_evaluation(fun_mat, a, b, const_a, const_b):
     new_fun = fun_mean_mat + b * beta_fun_mat + a * alpha_fun_mat
     return new_fun
 
-
+# Compute mean template for selected rows/columns with additive effects
 def template_evaluation_add(fun_mat, logr, logc, a, b, const_a, const_b):
     n, m, p = fun_mat.shape
     count_null = np.sum(np.isnan(fun_mat), axis=2)
@@ -112,6 +112,7 @@ def warping_function(
     shift_max,
     max_iter,
 ):
+    # Compute distance between warped data and template
     def warping_shift(coeff):
         st = x_reg + coeff
         template_t = new_fun[i, j, :]
@@ -183,6 +184,7 @@ def warping_function_add(
     shift_max,
     max_iter,
 ):
+    # Compute distance for warped data against template
     def warping_shift(coeff):
         st = x_reg + coeff
         template_t = new_fun[i, j, :]
@@ -322,28 +324,28 @@ def evaluate_mat_dist_add(
         mat_dist = np.sum((fun_mat - new_fun) ** 2, axis=2) / p
     return mat_dist
 
-
+# Compute overall Cheng-Church score as mean distance
 def ccscore_fun(mat_dist):
     score_fun = np.nanmean(mat_dist)
     return score_fun
 
-
+# Compute row-wise mean distances
 def rowscore_fun(mat_dist):
     score_fun = np.nanmean(mat_dist, axis=1)
     return score_fun
 
-
+# Compute column-wise mean distances
 def colscore_fun(mat_dist):
     score_fun = np.nanmean(mat_dist, axis=0)
     return score_fun
 
-
+# Compute row scores for selected columns
 def addrowscore_fun(mat_dist, logc):
     selected_cols = mat_dist[:, logc]
     score_fun = np.nanmean(selected_cols, axis=1)
     return score_fun
 
-
+# Compute column scores for selected rows
 def addcolscore_fun(mat_dist, logr):
     selected_rows = mat_dist[logr, :]
     score_fun = np.nanmean(selected_rows, axis=0)
@@ -365,6 +367,7 @@ def cc1_fun(
     max_iter,
     only_one,
 ):
+    # Phase 1: Remove worst rows/columns until score <= delta
     logr = logr.copy()
     logc = logc.copy()
     sub_mat = fun_mat[np.ix_(logr, logc, [True] * fun_mat.shape[2])]
@@ -478,6 +481,7 @@ def cc2_fun(
     shift_max,
     max_iter,
 ):
+    # Phase 2: Multiple row/column removal using theta threshold
     logr = logr.copy()
     logc = logc.copy()
     mdi = 1
@@ -565,6 +569,7 @@ def cc3_fun(
     shift_max,
     max_iter,
 ):
+    # Phase 3: Add rows/columns back to expand bicluster
     logr = logr.copy()
     logc = logc.copy()
     br = 1
@@ -647,6 +652,7 @@ def bigcc_fun(
     max_iter,
     only_one,
 ):
+    # Main Cheng-Church algorithm: 3-phase iterative refinement
     n, m, p = fun_mat.shape
     logr = np.ones(n, dtype=bool)
     logc = np.ones(m, dtype=bool)

{bifunclib-1.0.2 → bifunclib-1.0.4}/BiFuncLib/cvx_main_func.py

@@ -5,7 +5,7 @@ import networkx as nx
 import random
 import math
 
-
+# Compute Gaussian kernel weights for all pairs of columns
 def kernel_weights(X, phi):
     p, n = X.shape
     num_weights = n * (n - 1) // 2
@@ -19,7 +19,7 @@ def kernel_weights(X, phi):
             k += 1
     return w
 
-
+# Sparse matrix-matrix multiplication: M * X
 def spmm(M, X):
     m = M["Nrow"]
     n = M["Ncol"]
@@ -32,7 +32,7 @@ def spmm(M, X):
                 Y[row_ind, i] += M["values"][k] * X[j, i]
     return Y
 
-
+# Sparse matrix transpose multiplication: M^T * X
 def spmtm(M, X):
     n = M["Ncol"]
     p = X.shape[1]
@@ -44,7 +44,7 @@ def spmtm(M, X):
                 Y[j, i] += M["values"][k] * X[row_ind, i]
     return Y
 
-
+# Sparse matrix multiply with transpose: M * X^T
 def spmmt(M, X):
     m = M["Nrow"]
     n = M["Ncol"]
@@ -57,19 +57,19 @@ def spmmt(M, X):
                 Y[row_ind, i] += M["values"][k] * X[i, j]
     return Y
 
-
+# Compute dual objective for convex clustering
 def convex_cluster_dual(XT, UT):
     dual = 0.5 * (np.sum(XT**2) - np.sum(UT**2))
     return dual
 
-
+# Compute primal objective with fusion penalty
 def convex_cluster_primal(XT, UT, VT, Phi, w):
     primal = 0.5 * np.sum((XT - UT) ** 2)
     VT[:] = spmm(Phi, UT)
     penalty = np.sum(w * np.sqrt(np.sum(VT**2, axis=1)))
     return primal + penalty
 
-
+# Compute biclustering primal with row and column fusion penalties
 def convex_bicluster_primal(
     XT, UT, VT_row, VT_col, Phi_row, Phi_col, w_row, w_col
 ):
@@ -80,7 +80,7 @@ def convex_bicluster_primal(
     penalty_col = np.sum(w_col * np.sqrt(np.sum(VT_col**2, axis=1)))
     return primal + penalty_row + penalty_col
 
-
+# Proximal operator for L2 norm (group lasso)
 def prox_L2(X, tau):
     m, n = X.shape
     Y = np.empty_like(X)
@@ -93,7 +93,7 @@ def prox_L2(X, tau):
             Y[i, :] = factor * X[i, :]
     return Y
 
-
+# Projection onto L2 ball
 def proj_L2(X, tau):
     m, n = X.shape
     Y = np.empty_like(X)
@@ -106,49 +106,49 @@ def proj_L2(X, tau):
         Y[i, :] = factor * X[i, :]
     return Y
 
-
+# Update U from dual variables
 def update_UT(XT, LambdaT, Phi):
     UT = spmtm(Phi, LambdaT)
     UT = XT - UT
     return UT
 
-
+# Compute gradient of dual variables
 def grad_LambdaT(UT, Phi):
     gLambdaT = spmm(Phi, UT)
     return -gLambdaT
 
-
+# Update dual variables with gradient step
 def update_LambdaT2(LambdaT, gLambdaT, nu, w):
     LambdaT_temp = LambdaT - nu * gLambdaT
     new_LambdaT = proj_L2(LambdaT_temp, w)
     return new_LambdaT
 
-
+# Alternative update for dual variables
 def update_LambdaT(LambdaT, UT, Phi, nu, w):
     LambdaT_temp = spmm(Phi, UT)
     LambdaT_temp = LambdaT + nu * LambdaT_temp
     new_LambdaT = proj_L2(LambdaT_temp, w)
     return new_LambdaT
 
-
+# Update row fusion variables
 def update_VT_row(U, LambdaT, Phi, w, nu):
     tau = w / nu
     VT_temp = spmm(Phi, U) - (1 / nu) * LambdaT
     VT_row = prox_L2(VT_temp, tau)
     return VT_row
 
-
+# Update column fusion variables
 def update_VT_col(UT, LambdaT, Phi, w, nu):
     tau = w / nu
     VT_temp = spmm(Phi, UT) - (1 / nu) * LambdaT
     VT_col = prox_L2(VT_temp, tau)
     return VT_col
 
-
+# Convert triangular indices to linear index
 def tri2vec(i, j, n):
     return n * (i - 1) - (i * (i - 1)) // 2 + j - i
 
-
+# Convert linear index to triangular indices
 def vec2tri(k, n):
     k = np.asarray(k)
     i = np.ceil(0.5 * (2 * n - 1 - np.sqrt((2 * n - 1) ** 2 - 8 * k))).astype(
@@ -157,7 +157,7 @@ def vec2tri(k, n):
     j = k - n * (i - 1) + (i * (i - 1)) // 2 + i
     return np.column_stack((i, j))
 
-
+# Compute graph weights using k-nearest neighbors
 def gkn_weights(X, phi=0.5, k_row=5, k_col=5):
     p, n = X.shape
     w_row = kernel_weights(X.T, phi / n)
@@ -183,7 +183,7 @@ def gkn_weights(X, phi=0.5, k_row=5, k_col=5):
         "nColComp": nColComp,
     }
 
-
+# Keep only k-nearest neighbor weights
 def knn_weights(w, k, n):
     keep = set()
     i = 1
@@ -210,7 +210,7 @@ def knn_weights(w, k, n):
     new_w[mask] = 0
     return csc_matrix(new_w.reshape(-1, 1))
 
-
+# Create edge incidence matrix from weights
 def create_edge_incidence(w, n):
     P = vec2tri(w.indices + 1, n)
     nEdges = P.shape[0]
@@ -220,7 +220,7 @@ def create_edge_incidence(w, n):
     E = coo_matrix((data, (row, col)), shape=(nEdges, n)).tocsc()
     return E
 
-
+# Create adjacency matrix from fusion variables
 def create_adjacency(V, Phi):
     differences = np.linalg.norm(V, axis=0)
     connected_ix = np.where(differences == 0)[0]
@@ -244,7 +244,7 @@ def create_adjacency(V, Phi):
         A = csc_matrix((n, n))
     return A
 
-
+# Find connected components in graph
 def find_clusters(A):
     G = nx.from_scipy_sparse_array(A, create_using=nx.Graph)
     clusters = list(nx.connected_components(G))
@@ -256,7 +256,7 @@ def find_clusters(A):
     sizes = np.array([len(comp) for comp in clusters], dtype=int)
     return {"cluster": cluster, "size": sizes}
 
-
+# Create adjacency matrix from weight indices
 def weights_graph(w, n):
     P = vec2tri(w.indices + 1, n)
     nEdges = P.shape[0]
@@ -266,7 +266,7 @@ def weights_graph(w, n):
     A = coo_matrix((data, (row, col)), shape=(n, n)).tocsc()
     return A
 
-
+# Update missing values via majorization
 def update_majorization(MT, UT, Theta, nMissing):
     MT = np.asfortranarray(MT)
     UT = np.asfortranarray(UT)
@@ -274,7 +274,7 @@ def update_majorization(MT, UT, Theta, nMissing):
         MT.ravel(order="F")[idx] = UT.ravel(order="F")[idx]
     return MT
 
-
+# Compute mean values for each bicluster block
 def get_subgroup_means_full(X, clusters_row, clusters_col):
     if not isinstance(X, np.ndarray):
         X = np.array(X)
@@ -295,13 +295,13 @@ def get_subgroup_means_full(X, clusters_row, clusters_col):
                     M[i, j] = np.nanmean(submat)
     return M
 
-
+# Get subgroup means with missing values excluded
 def get_subgroup_means(X, Theta, clusters_row, clusters_col):
     Y = X.copy()
     Y.to_numpy().ravel(order="F")[Theta] = np.nan
     return get_subgroup_means_full(Y, clusters_row, clusters_col)
 
-
+# Generate random validation set indices
 def get_validation(p, n, fraction=0.1, seed=123):
     random.seed(seed)
     total = n * p
@@ -314,7 +314,7 @@ def get_validation(p, n, fraction=0.1, seed=123):
     ThetaV = ix1
     return {"ThetaM": ThetaM, "ThetaV": ThetaV}
 
-
+# FASTA solver for convex clustering with Nesterov acceleration
 def convex_cluster_fasta(
     XT,
     UT,
@@ -389,7 +389,7 @@ def convex_cluster_fasta(
             break
     return nu, its, primal_hist, dual_hist
 
-
+# ADMM-style solver for convex biclustering
 def convex_bicluster_dlpa(
     XT,
     LambdaT_row,
@@ -505,7 +505,7 @@ def convex_bicluster_dlpa(
         "iter": its,
     }
 
-
+# Majorization-minimization for biclustering with missing values
 def convex_bicluster_impute(
     MT,
     UT,
@@ -603,7 +603,7 @@ def convex_bicluster_impute(
         res["nu_col"],
     )
 
-
+# Wrapper for convex biclustering with imputation
 def test_convex_bicluster_impute(
     mt,
     ut,
@@ -681,7 +681,7 @@ def test_convex_bicluster_impute(
         tol_inner,
     )
 
-
+# Main COBRA solver (Convex Biclustering)
 def cobra_pod(
     X,
     Lambda_row,
@@ -773,7 +773,7 @@ def cobra_pod(
         "iter": iter_count,
     }
 
-
+# Cross-validation for gamma parameter selection
 def cobra_validate(
     X,
     E_row,
@@ -852,7 +852,7 @@ def cobra_validate(
         "validation_error": validation_error,
     }
 
-
+# Smooth data matrix using bicluster means
 def biclust_smooth(X, clusters_row, clusters_col):
     p, n = X.shape
     Y = np.full((p, n), np.nan)

{bifunclib-1.0.2 → bifunclib-1.0.4}/BiFuncLib/fem_bifunc.py

@@ -20,6 +20,7 @@ def fem_bifunc(
     lambda_=0,
     graph=False,
 ):
+    # Initialize storage for all model-K combinations
     resultat = [None] * (len(K) * len(model))
     bic = [None] * (len(K) * len(model))
     aic = [None] * (len(K) * len(model))
@@ -27,6 +28,7 @@ def fem_bifunc(
     nbprm = [None] * (len(K) * len(model))
     ll = [None] * (len(K) * len(model))
     it = 0
+    # Grid search over K values and model types
     for k_idx in range(len(K)):
         current_K = K[k_idx]
         if disp:
@@ -44,6 +46,7 @@ def fem_bifunc(
                 lambda_=lambda_,
                 graph=graph,
             )
+            # Store information criteria if optimization succeeded
             if resultat[it] is not None:
                 bic[it] = resultat[it]["bic"]
                 aic[it] = resultat[it]["aic"]
@@ -64,10 +67,12 @@ def fem_bifunc(
                             f"{current_model}\t:\t icl = {resultat[it]['icl']}"
                         )
             it += 1
+    # Validate that at least one model succeeded
     if all(v is None for v in bic):
         raise ValueError(
             "No reliable results to return (empty clusters in all partitions)!"
         )
+    # Select best model based on chosen criterion
     if crit == "bic":
         id_max = bic.index(max([v for v in bic if v is not None]))
         crit_max = resultat[id_max]["bic"]
@@ -82,6 +87,7 @@ def fem_bifunc(
         print(
             f"The best model is {res['model']} with K = {res['K']} ({crit} = {crit_max})"
         )
+    # Add metadata and all criterion values to result
     res["crit"] = crit
     nm = len(model)
     res["allCriterions"] = {