Skip to content

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.