FlowMap ModuleΒΆ

High-level entry point for fitting FlowMap embeddings and splines.

VectorFieldEmbedder(X, V, *, method="umap", spline_type="thin_plate", embedding_dim=2, dof=30, dof_vf=None, dist_method="phase", custom_dist=None, X_emb=None, dist_kwargs=None, embed_kwargs=None, spline_kwargs=None, spline_vf_kwargs=None, knn_k=30, alpha=0.5, use_PCA=True, pca_components=30, n_control_points=4000, n_spline_points=None)

Create a FlowMap embedding object from observations and velocities. Call fit_embedding() to compute the embedding and fit the main splines.

Parameters

  • X: (n_cells, n_features) data matrix.

  • V: (n_cells, n_features) velocity matrix aligned to X.

  • method: embedding backend, one of "umap", "tsne", or "pca".

  • spline_type: spline backend, "thin_plate" or "polyharmonic".

  • embedding_dim: output embedding dimension. Most plotting and geometry helpers expect 2.

  • dof: effective degrees of freedom for the reconstruction spline.

  • dof_vf: effective degrees of freedom for the velocity-field spline. Defaults to dof.

  • dist_method: distance mode, "phase" or "euclidean".

  • custom_dist: precomputed distance graph or matrix used instead of FlowMap distance construction.

  • X_emb: existing embedding coordinates. If provided, FlowMap skips embedding initialization and fits splines on these coordinates.

  • dist_kwargs: keyword arguments passed to the distance solver.

  • embed_kwargs: keyword arguments passed to UMAP or t-SNE.

  • spline_kwargs: keyword arguments passed to the reconstruction spline.

  • spline_vf_kwargs: keyword arguments passed to the velocity spline.

  • knn_k: number of neighbors for phase-distance graph construction.

  • alpha: phase-distance velocity/time weighting parameter.

  • use_PCA: project high-dimensional input before fitting when X has many features.

  • pca_components: number of PCA/SVD components when use_PCA=True.

  • n_control_points: number of spline control points.

  • n_spline_points: optional random subset size for spline fitting.

Output

Returns a VectorFieldEmbedder instance. After fitting, commonly used attributes are X_emb, V_emb, spline, and spline_vf.

Method notes: FlowMap embedding and spline fitting.

VectorFieldEmbedder.fit_embedding(seed=None)

Compute the low-dimensional embedding and fit the reconstruction and velocity-field splines.

Parameters

  • seed: optional random seed for embedding initialization and reproducibility.

Output

Returns None. Updates X_emb, V_emb, spline, and spline_vf on the object.

Method notes: FlowMap embedding.

VectorFieldEmbedder.fit_gene_level_splines(dof_gene=80, dof_vf_gene=80, X=None, V=None)

Fit splines from embedding coordinates to gene expression and gene velocity. Use this before gene-level evaluation or gradient analysis.

Parameters

  • dof_gene: effective degrees of freedom for the gene-expression spline.

  • dof_vf_gene: effective degrees of freedom for the gene-velocity spline.

  • X: optional gene-expression matrix. If omitted, FlowMap uses stored raw input when available.

  • V: optional gene-velocity matrix aligned to X.

Output

Returns None. Adds X_gene, V_gene, spline_gene, and spline_vf_gene to the object.

Method notes: Gene-level reconstruction.

VectorFieldEmbedder.refine_embedding(lam=None, method="batch", batch_size=64, lr=1e-3, epochs=50, tol=1e-2, verbose=False)

Optionally refine embedding coordinates after the initial fit. Most tutorials do not need this step.

Parameters

  • lam: velocity reconstruction weight.

  • method: optimization mode, "batch" or "global".

  • batch_size: mini-batch size for method="batch".

  • lr: learning rate for method="batch".

  • epochs: number of optimization epochs for method="batch".

  • tol: convergence tolerance for method="global".

  • verbose: print optimization progress.

Output

Returns None. Updates X_emb and refits spline and spline_vf.

Method notes: Embedding refinement.