biomedical_data_generator.features.correlated

Generation of correlated feature clusters simulating pathway-like modules.

Overview

This module generates correlated Gaussian feature clusters that can be interpreted as simplified “pathway-like” modules (e.g., sets of co-expressed genes or co-regulated proteins).

Each cluster is defined by:

A correlation structure (equicorrelated or Toeplitz/AR(1)).
A correlation strength parameter correlation.
Optionally class-specific correlation strengths to mimic activation in specific biological conditions (e.g., tumors vs controls).
An anchor feature with class-specific mean shifts representing diagnostic strength (e.g., biomarker concentration changes).

The resulting clusters are concatenated horizontally.

Statistical model

At the core, each cluster implements a multivariate Gaussian model:

For a given cluster with n_features (p) and a correlation matrix \(\Sigma\), we generate samples according to

\[x \sim \mathcal{N}_p(\mu_c, \Sigma_c),\]

where \(\mu_c\) and \(\Sigma_c\) depend on class \(c\).
Two correlation structures are supported:
- Equicorrelated: All off-diagonal entries are equal to the correlation parameter:
  
  \[\begin{split}\Sigma_{ij} = \begin{cases} 1 & i = j, \\ \rho & i \neq j. \end{cases}\end{split}\]
  
  where \(\rho\) is the correlation parameter.
- Toeplitz / AR(1): Correlation decays with distance:
  
  \[\Sigma_{ij} = \rho^{\lvert i - j \rvert}.\]
  
  where \(\rho\) is the correlation parameter.

Anchor effects (mean channel)

First-moment signal is carried by the optional mean_channel. When present, the anchor feature receives the channel’s per-class mean shift:

\[\mu_{anchor, c} = \text{mean\_channel.per\_class\_effect}[c],\]

with absent classes receiving 0.0 (baseline). A proxy at block column j inherits this shift structurally: the anchor’s per-class effect is propagated as effect * proxy_attenuation * sigma[anchor_index, j], where sigma is the structural correlation matrix built from correlation_structure and that class’s effective correlation (the same correlation that samples the block). The proxy shift is therefore deterministic and decays with structural distance from the anchor under a Toeplitz structure.

Configuration semantics (channel model):

Relevance is derived, never declared – there is no declared anchor role. A cluster is informative iff its mean channel varies across classes (first moment) or its effective per-class correlation varies across classes (second moment, via the covariance_channel).
No mean_channel → no class-dependent mean shift on the anchor or its proxies.
A mean_channel whose effects are equal across classes contributes no first-moment signal (the cluster is informative only if some channel varies).

Limitations and biological realism

See module docstring for detailed discussion of simplifications. Key points:

Gaussian marginals (real data is often skewed, zero-inflated)
Linear dependence only (no thresholds, saturation)
Independent clusters (no pathway crosstalk)
Blockwise effects (partial activation not modeled)
No sample-level heterogeneity (no subtypes)

Intended use

Realistic enough for teaching and benchmarking, but not a fully realistic generative model for complex omics data.

Functions

`build_correlation_matrix`(n_features, correlation)	Build a correlation matrix with specified structure.
`sample_all_correlated_clusters`(cfg, y[, rng])	Generate and assemble all correlated feature clusters for a dataset.
`sample_correlated_data`(n_samples, ...[, ...])	Sample correlated Gaussian data with zero mean and unit variance.

biomedical_data_generator.features.correlated.build_correlation_matrix(n_features, correlation, structure='equicorrelated')[source]

Build a correlation matrix with specified structure.

Parameters:

n_features (int) – Number of features (matrix dimension).
correlation (float) – Correlation parameter.
structure (str) – Either ‘equicorrelated’ or ‘toeplitz’.

Returns:

Correlation matrix of shape (n_features, n_features).

Raises:

ValueError – If structure is unknown or correlation is out of bounds.

Return type:

ndarray

biomedical_data_generator.features.correlated.sample_all_correlated_clusters(cfg, y, rng=None)[source]

Generate and assemble all correlated feature clusters for a dataset.

For each cluster, a Gaussian block is sampled per class from that class’s effective within-block correlation (the covariance channel value for the class, or the cluster’s baseline_correlation when absent), then the mean channel adds the per-class anchor shift with its structurally derived proxy propagation. Relevance is never declared; it is derived from these channels.

Parameters:

cfg (DatasetConfig) – Dataset configuration with the corr_clusters field.
y (ndarray) – Class labels as a 1D NumPy array of length n_samples.
rng (Generator | None) – Optional random number generator. If None, creates a new one.

Returns:

x_clusters: Array of shape (n_samples, n_corr_features) with the assembled correlated blocks including channel effects.
cluster_meta: Dictionary with cluster-level metadata, keyed by field name then cluster id:
- ”mean_per_class_effect”: cluster_id -> mean channel mapping or None
- ”covariance_per_class_correlation”: cluster_id -> covariance mapping or None
- ”baseline_correlation”: cluster_id -> structural baseline correlation
- ”label”: cluster_id -> human-readable label
- ”structure”: cluster_id -> correlation structure (“equicorrelated” or “toeplitz”)
- ”proxy_attenuation”: cluster_id -> anchor-to-proxy mean-propagation multiplier
- ”anchor_index”: cluster_id -> structural anchor column within the block

Return type:

A tuple (x_clusters, cluster_meta) where

biomedical_data_generator.features.correlated.sample_correlated_data(n_samples, n_features, correlation, *, structure='equicorrelated', rng=None)[source]

Sample correlated Gaussian data with zero mean and unit variance.

This function generates the Gaussian core for correlated feature clusters.

Parameters:

n_samples (int) – Number of samples to generate.
n_features (int) – Number of features.
correlation (float) – Correlation parameter.
structure (str) – Correlation structure (‘equicorrelated’ or ‘toeplitz’).
rng (Generator | None) – Random number generator. If None, creates a new one.

Returns:

Array of shape (n_samples, n_features) with standard normal marginals and specified correlation structure.

Raises:

ValueError – If structure is invalid or correlation out of bounds.

Return type:

ndarray