Skip to content

Getting Started

First, follow Installation Guide to install WaveFactor.

Example Code Snippet

This example shows how WaveFactor can be applied on data and how posterior estimates can be extracted.

import numpy as np
import wavefactor as wf

# 1. Simulating input data
# Input requirements:
#   X: continuous expression matrix (N_spots x N_genes)
#   coords: (N_spots x 2) integer grid coordinates covering [0, L-1] x [0, L-1]
#   N_spots = L * L must be an exact power of 4 (e.g. 64, 256, 1024, 4096)
np.random.seed(42)
gx, gy = np.meshgrid(np.arange(32), np.arange(32))
coords = np.column_stack([gx.ravel(), gy.ravel()])
X = np.random.randn(1024, 200)

# 2. Instantiate WaveFactor estimator
model = wf.WaveFactor(
    n_factors=10,               # Number of latent factors (K)
    n_length_scales=4,          # Wavelet detail levels (R = 5 total resolutions)
    n_init=5,                   # Multi-start initializations (selects best ELBO)
    n_jobs=1,                   # Parallel workers across initializations
    random_state=42,
)

# 3. Apply WaveFactor to the data
model.fit(X, coords)

# 4. Access posterior estimates
result = model.get_result()
print(f"Final ELBO: {result.elbo:.2f} across {result.n_iter} iterations")

spot_factors = result.factors        # Latent spatial factors (N_spots x K)
gene_loadings = result.loadings      # Factor loadings matrix (K x N_genes)
gene_pips = result.gene_pip          # Gene Posterior Inclusion Probabilities
spatial_pips = result.spatial_pip    # Multiresolution spatial wavelet PIPs

Another Example With Simulated Data Based On Gene Program Ground Truths

Additionally, WaveFactor includes a ready-to-run simulation example that simulates data with ground-truth gene programs, fits the model, and verifies the estimated factors and loadings against the ground truth.

This example can be run with the following command:

python examples/getting_started/run_analysis.py