API Reference
This page contains the automated API reference for WaveFactor. Signatures, type annotations, parameters, and return types are parsed directly from the package docstrings.
Estimator
wavefactor.WaveFactor
Bases: BaseEstimator
WaveFactor: Bayesian Multiresolution Wavelet Spatial Factor Model.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_factors
|
int
|
Number of latent spatial factors (K). |
10
|
n_length_scales
|
int
|
Number of wavelet detail length scales / decomposition levels (D). Total resolutions R = D + 1. |
4
|
spatial_prior
|
Optional[ndarray]
|
Prior inclusion probabilities for spatial wavelet coefficients (pi_L). Must be a 1D array of shape (n_resolutions,) with values in (0, 1). |
None
|
gene_prior
|
Optional[ndarray]
|
Prior inclusion probabilities for gene loadings (pi_F). Must be a 2D array of shape (n_factors, n_features) with values in (0, 1). |
None
|
alpha_t
|
Optional[ndarray]
|
Shape hyperparameter matrix for factor precision Gamma prior, shape (R, K). |
None
|
beta_t
|
Optional[ndarray]
|
Rate hyperparameter matrix for factor precision Gamma prior, shape (R, K). |
None
|
alpha_tau
|
Optional[ndarray]
|
Shape hyperparameter matrix for noise precision Gamma prior, shape (R, G) where G = n_features. |
None
|
beta_tau
|
Optional[ndarray]
|
Rate hyperparameter matrix for noise precision Gamma prior, shape (R, G) where G = n_features. |
None
|
max_iter
|
int
|
Maximum CAVI optimization iterations per start. |
1000
|
tol
|
float
|
Relative ELBO change convergence threshold (|Delta ELBO / ELBO| < tol). |
1e-5
|
n_init
|
int
|
Number of randomized initial parameter starts. |
5
|
n_jobs
|
int
|
Number of parallel worker processes (-1 uses all available CPU cores). |
-1
|
random_state
|
int
|
Random seed for deterministic initialization and reproducibility. |
None
|
verbose
|
bool
|
Whether to log progress during CAVI optimization. |
True
|
init
|
str
|
Variational parameter initialisation strategy. Options: - "random": Uniform pseudo-random initialization on [-10, 10] (default). Provides broad exploration across the non-convex ELBO landscape, promotes factor diversity, and prevents factor redundancy / cloning. - "prior": Sample variational states from generative prior expectations with mild jitter. Useful when strong directional priors are specified. |
"random"
|
factors_
property
Spot-space spatial factor activities S in R^(N_spots x K).
loadings_
property
Factor-to-gene loadings matrix F in R^(K x G).
elbo_
property
Final converged Evidence Lower Bound (ELBO).
elbo_history_
property
ELBO convergence trace across iterations.
spatial_pip_
property
Posterior inclusion probabilities for spatial wavelet coefficients (r_L).
gene_pip_
property
Posterior inclusion probabilities for gene loadings (r_F).
precision_t_
property
Posterior factor precision expectation E[t].
precision_tau_
property
Posterior noise precision expectation E[tau].
fit(X, coords)
Fits the WaveFactor model on spatial transcriptomics expression data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
ndarray
|
Gene expression data matrix of shape (N_spots, N_features). N_spots must be an exact power of 4 (e.g. 64, 256, 1024, 4096). |
required |
coords
|
ndarray
|
Spatial (x, y) integer grid coordinates for each spot, shape (N_spots, 2). Must form a unique 1-to-1 mapping onto the [0, L-1] x [0, L-1] lattice. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
self |
WaveFactor
|
Fitted estimator. |
transform(X=None)
Returns the inferred spot-space spatial factor activities.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
Optional[ndarray]
|
Ignored. Present for scikit-learn TransformerMixin API compatibility. |
None
|
Returns:
| Type | Description |
|---|---|
ndarray
|
Spatial factors matrix of shape (N_spots, K). |
fit_transform(X, coords, **fit_params)
Fits the model and returns the inferred spot-space spatial factors.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
ndarray
|
Gene expression data matrix of shape (N_spots, N_features). |
required |
coords
|
ndarray
|
Spatial (x, y) integer grid coordinates, shape (N_spots, 2). |
required |
Returns:
| Type | Description |
|---|---|
ndarray
|
Spatial factors matrix S of shape (N_spots, K). |
get_result()
Returns the rich WaveFactorResult object.
Results Container
wavefactor.results.WaveFactorResult
Container holding WaveFactor posterior parameter estimates, convergence history, and automated 2D Inverse Discrete Wavelet Transform (IDWT) reconstructions.
Attributes:
| Name | Type | Description |
|---|---|---|
parameters |
Dict[str, Any]
|
Raw CAVI parameter dictionary returned by the C++ engine. |
elbo_record |
ndarray
|
ELBO trajectory values across CAVI iterations. |
elbo |
float
|
Final converged Evidence Lower Bound. |
dimensions |
Dict[str, Any]
|
Dictionary with keys 'n_spots', 'n_resolutions', 'n_factors', 'n_features'. |
grid_side_length |
int
|
Side length L of the square L x L spatial grid. |
grid_shape |
Tuple[int, int]
|
2D grid dimensions (grid_side_length, grid_side_length). |
spot_grid_coords |
ndarray
|
Array of shape (N_spots, 2) holding Cartesian [grid_x, grid_y] coordinates. |
grid_x |
ndarray
|
1D integer grid x-coordinates (columns in 0..L-1). |
grid_y |
ndarray
|
1D integer grid y-coordinates (rows in 0..L-1). |
coords |
(ndarray, optional)
|
Original spot spatial coordinates (N_spots, 2). |
cpp_time |
float
|
Elapsed C++ CAVI runtime in seconds. |
version |
str
|
WaveFactor software package version used to generate the result. |
fit_info |
Dict[str, Any]
|
Structured runtime execution and model fitting provenance metadata. |
factors
property
Spot-space latent factor activities S in R^(N_spots x K). If continuous coordinates were provided, factors are evaluated at original spot locations.
spatial_factor_maps
property
2D Continuous Spatial Factor Activity Maps S in R^(L x L x K), reconstructed via automated 2D Inverse Wavelet Transform (IDWT).
loadings
property
Factor-to-gene loadings matrix F in R^(K x G). Computed as the expected gene loading E[F] = mu_F * r_F.
loadings_variance
property
Analytical posterior variance of gene loadings Var_q(F) in R^(K x G). Var_q(F) = r_F * sigma_F^2 + r_F * (1 - r_F) * mu_F^2.
gene_pip
property
Gene posterior inclusion probabilities r_F in R^(K x G).
spatial_pip
property
Spatial wavelet posterior inclusion probabilities r_L (nested resolution lists).
precision_t
property
Posterior expected factor precision E[t] = alpha_hat_t / beta_hat_t in R^(R x K).
precision_tau
property
Posterior expected noise precision E[tau] = alpha_hat_tau / beta_hat_tau in R^(R x G).
elbo = float(elbo)
instance-attribute
elbo_history
property
Trace of Evidence Lower Bound values across iterations.
n_iter
property
Number of completed CAVI iterations.
n_init
property
Number of randomized initial parameter starts evaluated.
grid_x
property
1D integer grid x-coordinates (columns in 0..L-1).
grid_y
property
1D integer grid y-coordinates (rows in 0..L-1).
grid_side_length = int(grid_side_length)
instance-attribute
grid_shape
property
2D spatial grid shape (grid_side_length, grid_side_length).
cpp_time = cpp_time
instance-attribute
dimensions = dimensions
instance-attribute
summary()
Returns a formatted multi-line summary of model fit, dimensions, and provenance.
Spatial Preprocessing
wavefactor.data.prepare_spatial_data(X, coords, n_factors=10, n_length_scales=4)
Preprocesses spatial transcriptomics input data, validates 2D spatial grid mappings, and executes 2D DWT wavelet decomposition.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
X
|
ndarray
|
Gene expression matrix of shape (N_spots, N_features). |
required |
coords
|
ndarray
|
Spatial (x, y) integer grid coordinates for each spot, shape (N_spots, 2). Must be a unique 1-to-1 mapping onto the [0, L-1] x [0, L-1] lattice, where N_spots = L * L is an exact power of 4. |
required |
n_factors
|
int
|
Number of latent factors (K). |
10
|
n_length_scales
|
int
|
Number of wavelet detail levels (D). Total resolutions R = D + 1. Must satisfy 2^D <= L (i.e. D <= log2(L)). |
4
|
Returns:
| Type | Description |
|---|---|
WaveFactorData
|
Structured data container with wavelet decomposition and dimension constants. |