flowmap.geometry ModuleΒΆ

Geometry analysis tools for fitted FlowMap embeddings.

FixedPointAnalyzer(embedding)

Create an analyzer for fixed points of a fitted FlowMap velocity field.

Parameters

  • embedding: fitted VectorFieldEmbedder with X_emb, V_emb, spline, and spline_vf.

Output

Returns a FixedPointAnalyzer instance.

Method notes: Fixed points and local linearization.

FixedPointAnalyzer.identify_fixed_points(*, mode="euclidean", grid_resolution=60, speed_smoothing=1.0, speed_quantile_threshold=0.1, max_candidates=20, min_separation=None, refine=True, metric_regularization=1e-8, jacobian_radius=0.15, weighted_jacobian=True, **grid_kwargs)

Find low-speed candidate locations and classify local dynamics near each candidate.

Parameters

  • mode: "euclidean" for embedding-space classification or "riemannian" for local metric flattening.

  • grid_resolution: number of grid points per axis.

  • speed_smoothing: Gaussian smoothing strength applied to the grid-speed field.

  • speed_quantile_threshold: low-speed quantile used to keep candidate regions.

  • max_candidates: maximum number of candidates to refine and classify.

  • min_separation: minimum returned fixed-point separation in embedding units.

  • refine: locally minimize velocity magnitude from grid candidates.

  • metric_regularization: diagonal regularization for Riemannian metric factorization.

  • jacobian_radius: compatibility argument for older notebooks.

  • weighted_jacobian: compatibility argument for older notebooks.

  • grid_kwargs: passed to compute_velocity_on_grid.

Output

Returns a list of dictionaries with position, jacobian, linearization, eigenvalues, type, speed, and mode.

Method notes: Fixed points and local linearization.

LagrangianPathOptimizer(emb, D=1.0, lam=0.0)

Create an optimizer for least-action transition paths on a fitted FlowMap embedding.

Parameters

  • emb: fitted VectorFieldEmbedder with X_emb, V_emb, and spline_vf.

  • D: diffusion scale in the action.

  • lam: path-length regularization weight.

Output

Returns a LagrangianPathOptimizer instance.

Method notes: Least-action paths.

LagrangianPathOptimizer.fit_path(start=None, end=None, *, path_init=None, distance_mode="embed", subsample_n=4000, k=20, alpha=0.0, n_segments=100, lr=5e-3, iters=300)

Compute a transition path between two embedding-space points.

Parameters

  • start: start coordinate in embedding space.

  • end: end coordinate in embedding space.

  • path_init: optional initial path; if provided, start and end are inferred from it.

  • distance_mode: graph initialization space, "embed" or "orig".

  • subsample_n: number of cells used for graph initialization.

  • k: number of nearest neighbors in the graph.

  • alpha: velocity-alignment penalty during graph initialization.

  • n_segments: number of segments in the resampled path.

  • lr: gradient-descent learning rate.

  • iters: number of path optimization iterations.

Output

Returns a dictionary with path_init, path_refined, and dt.

Method notes: Least-action paths.

GeneGradientAnalyzer(emb, *, cell_indices=None, max_cells=None, random_state=0, verbose=True)

Precompute gene-expression Jacobians for path-local or region-local gene-gradient analysis.

Parameters

  • emb: fitted VectorFieldEmbedder with gene-level splines.

  • cell_indices: optional cells on which to compute Jacobians.

  • max_cells: optional random cap when cell_indices is large.

  • random_state: seed for max_cells subsampling.

  • verbose: print progress and tensor shapes.

Output

Returns a GeneGradientAnalyzer instance with jacobians, metric, and cell_indices.

Method notes: Gene gradients.

GeneGradientAnalyzer.find_neighbors(trajectory, epsilon=0.05)

Find cells close to a path or trajectory in embedding space.

Parameters

  • trajectory: (n_points, embedding_dim) path coordinates.

  • epsilon: radius as a fraction of embedding scale.

Output

Returns integer cell indices.

Method notes: Gene gradients.

GeneGradientAnalyzer.compute_relative_gradients(neighbor_indices, gene_indices, weight="magnitude")

Compute gene-gradient direction and magnitude relative to local velocity.

Parameters

  • neighbor_indices: cells used for local averaging.

  • gene_indices: genes to evaluate.

  • weight: averaging mode, "magnitude" or "uniform".

Output

Returns a dictionary with angles, magnitudes, and gene_indices.

Method notes: Gene gradients.

compute_flow_curvature(emb, X_emb=None, eps=1e-12)

Compute velocity, acceleration components, and curvature from fitted FlowMap splines.

Parameters

  • emb: fitted VectorFieldEmbedder.

  • X_emb: optional embedding coordinates at which to evaluate curvature. Defaults to emb.X_emb.

  • eps: numerical stabilizer.

Output

Returns nested dictionaries for velocity, acceleration, and curvature arrays.

Method notes: Curvature and acceleration decomposition.