bioneuralnet.network.generate

Functions

correlation_network(X[, k, method, signed, ...])

Build a correlation-based graph from feature vectors with optional kNN sparsification.

gaussian_knn_network(X[, k, sigma, mutual, ...])

Build a Gaussian (RBF) kNN similarity graph from feature vectors.

get_logger(name)

Retrieves a global logger configured to write to 'bioneuralnet.log'.

similarity_network(X[, k, metric, mutual, ...])

Build a k-nearest neighbors similarity graph from feature vectors.

threshold_network(X[, b, k, mutual, ...])

Build a soft-thresholded kNN co-expression graph, similar to WGCNA-style networks.
bioneuralnet.network.generate.correlation_network(X: DataFrame, k: int | None = 15, method: str = 'pearson', signed: bool = True, normalize: bool = True, mutual: bool = False, per_node: bool = True, threshold: float | None = None, self_loops: bool = False) → DataFrame[source]

Build a correlation-based graph from feature vectors with optional kNN sparsification.

Pairwise correlations (Pearson or Spearman) are computed between features, mapped to similarity scores in [0, 1], and then optionally sparsified using per-node kNN or a global cutoff. Mutual pruning, self-loops, and row-normalization can be applied to obtain a final adjacency matrix.

Parameters:

  • X (pd.DataFrame) – Input data of shape (N, D) where N is the number of samples and D is the number of features.

  • k (int | None) – Number of neighbors for sparsification; when per_node is True this is per node, otherwise used to approximate k*N edges globally, and if None with threshold=None a fully connected graph is returned subject to self_loops.

  • method (str) – Correlation method; “pearson” for standard correlation or “spearman” for rank-based correlation.

  • signed (bool) – If True, use signed correlations mapped to [0, 1] via (C + 1)/2; if False, use absolute correlations in [0, 1].

  • normalize (bool) – If True, row-normalize the adjacency; if False, keep raw similarity weights.

  • mutual (bool) – If True, retain only edges that are present in both directions (i->j and j->i).

  • per_node (bool) – If True, apply kNN per node; if False, use a global cutoff determined by k or threshold.

  • threshold (float | None) – Similarity cutoff; when provided and per_node is False, overrides the k-based global cutoff.

  • self_loops (bool) – If True, add self-loop weights of 1 on the diagonal of the adjacency matrix.

Returns:

Adjacency matrix of shape (D, D) representing the feature-feature correlation graph.

Return type:

pd.DataFrame

bioneuralnet.network.generate.gaussian_knn_network(X: DataFrame, k: int = 15, sigma: float | None = None, mutual: bool = False, self_loops: bool = True, normalize: bool = True) → DataFrame[source]

Build a Gaussian (RBF) kNN similarity graph from feature vectors.

Pairwise Euclidean distances between features are converted to similarities using a Gaussian kernel with bandwidth sigma (or a median-distance heuristic). The graph is sparsified by keeping top-k neighbors per node, optionally restricted to mutual neighbors, with optional self-loops and row-normalization.

Parameters:

  • X (pd.DataFrame) – Input data of shape (N, D) where N is the number of samples and D is the number of features.

  • k (int) – Number of neighbors to keep per node in the kNN graph.

  • sigma (float | None) – Bandwidth parameter for the Gaussian kernel; if None, a median squared distance heuristic is used.

  • mutual (bool) – If True, retain only edges where i and j are mutual kNN neighbors.

  • self_loops (bool) – If True, add self-loop weights of 1 on the diagonal of the adjacency matrix.

  • normalize (bool) – If True, row-normalize the adjacency so each row sums to 1.

Returns:

Adjacency matrix of shape (D, D) representing the Gaussian-kernel feature similarity graph.

Return type:

pd.DataFrame

bioneuralnet.network.generate.similarity_network(X: DataFrame, k: int = 15, metric: str = 'cosine', mutual: bool = False, per_node: bool = True, self_loops: bool = False, normalize: bool = True) → DataFrame[source]

Build a k-nearest neighbors similarity graph from feature vectors.

Pairwise similarities are computed using either cosine similarity or a Gaussian kernel on Euclidean distances. The similarity matrix is sparsified by keeping top-k neighbors per node (or via a global cutoff), optionally restricted to mutual neighbors, with optional self-loops and row-normalization.

Parameters:

  • X (pd.DataFrame) – Input data of shape (N, D) where N is the number of samples and D is the number of features.

  • k (int) – Number of neighbors to keep per node, or approximate neighbors per node when using a global cutoff.

  • metric (str) – Similarity metric; either “cosine” or “euclidean” (case-insensitive) where the latter uses a Gaussian kernel on squared distances.

  • mutual (bool) – If True, retain only edges where i is in the kNN of j and j is in the kNN of i.

  • per_node (bool) – If True, apply kNN per node; if False, apply a global threshold to keep approximately k edges per node.

  • self_loops (bool) – If True, add self-loop weights of 1 on the diagonal of the adjacency matrix.

  • normalize (bool) – If True, row-normalize the adjacency so each row sums to 1.

Returns:

Adjacency matrix of shape (D, D) representing the feature-feature similarity graph.

Return type:

pd.DataFrame

bioneuralnet.network.generate.threshold_network(X: DataFrame, b: float = 6.0, k: int = 15, mutual: bool = False, self_loops: bool = False, normalize: bool = True) → DataFrame[source]

Build a soft-thresholded kNN co-expression graph, similar to WGCNA-style networks.

Absolute Pearson correlations between features are raised to a power b to obtain soft-thresholded similarities. A kNN mask keeps the top-k neighbors per node, optionally restricted to mutual neighbors, with optional self-loops and row-normalization.

Parameters:

  • X (pd.DataFrame) – Input data of shape (N, D) where N is the number of samples and D is the number of features.

  • b (float) – Soft-threshold exponent applied to absolute correlations to control network sparsity and hub emphasis.

  • k (int) – Number of neighbors to keep per node in the kNN graph.

  • mutual (bool) – If True, retain only edges where i and j are mutual kNN neighbors.

  • self_loops (bool) – If True, add self-loop weights of 1 on the diagonal of the adjacency matrix.

  • normalize (bool) – If True, row-normalize the adjacency so each row sums to 1.

Returns:

Adjacency matrix of shape (D, D) representing the soft-thresholded co-expression graph.

Return type:

pd.DataFrame