- Julia 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .github | ||
| docs | ||
| ext | ||
| src | ||
| test | ||
| .gitignore | ||
| LICENSE | ||
| Project.toml | ||
| README.md | ||
ddHodge
A Julia package for reconstructing potential, divergence and curl from sampled velocities.
Install
The development version of ddHodge can be installed via:
using Pkg
Pkg.add(url="https://github.com/kazumits/ddHodge.jl")
Basic usage
Required inputs are the matrices of sampled data points X and the corresponding velocity V.
These matrices should be in the same size of M variables (rows) x N samples (columns).
The basic usage of ddHodge consists of the following two steps.
- Graph construction (undirected
SimpleGraphtype of Graphs.jl) - Run ddHodge standard workflow with the options.
using ddHodge
g, kdtree, = kNNGraph(X,6) # k = 6
ddh = ddHodgeWorkflow(g,X,V,rdim=2) # rdim <= k
You can skip specifying rdim if no dimension reduction is required.
The ddh object contains the several vertex- and edge-level indicators of dynamics such as:
ddh.u: potentialddh.div: divergenceddh.rot: rotation (curl)ddh.vgrass: Grassmann distance (averaged at vertices)
These values are stored in the order of vertices in g.
See the help page ddHodgeWorkflow for more details and other returned values.
Advanced usage
Please refer to the repository to reproduce the figures in ddHodge paper.
GPU acceleration
After installing CUDA.jl, you can try the GPU acceleration.
import CUDA
CUDA.@time ddh = ddHodgeWorkflow(g, X, V, rdim=4, useCUDA=true)
RNA velocity data analysis
Before you start, please:
- Run scvelo to embed the estimated velocity into the PCA space, e.g., with
scvelo.tl.velocity_embedding(data, basis='pca'). - Install PythonCall.jl Julia package and anndata python package (e.g,
pip install anndata) to load scvelo analysis results.
Below is a minimal example of RNA velocity data analysis.
ENV["JULIA_PYTHONCALL_EXE"] = "/path/to/your/python"
# load scvelo output in anndata format
using PythonCall
h5file = "scvelo_out.h5ad"
anndata = pyimport("anndata")
adata = anndata.read_h5ad(h5file)
X = pyconvert(Matrix,adata.obsm["X_pca"])' # should be transposed
V = pyconvert(Matrix,adata.obsm["velocity_pca"])' # should be transposed
# ddHodge part
using ddHodge
g, kdtree, = kNNGraph(X,12) # k = 12
ddh = ddHodgeWorkflow(g,X,V,rdim=4) # rdim <= k
# save ddHodge results to the loaded anndata
for ft in [:u, :div, :rot, :vgrass]
adata.obs["ddh_$(ft)"] = pylist(getfield(ddh, ft))
end
anndata.settings.allow_write_nullable_strings = true
adata.write_h5ad(h5file)
adata.obs
Now, the cell-centered ddHodge results of potential: ddh_u, divergence: ddh_div, curl: ddh_rot and Grassmann distances (averaged at vertex-level): ddh_vgrass are accessible via adata.obs.ddh_*.
The saved results in scvelo_out.h5ad will be freely incorporated to your favorite platform: Python, R (via anndata package), and interactive single-cell data viewers (e.g., UCSC Cell Browser, CELLxGENE).
This image shows an example of the interactive POI (point-of-interest) selection. Users can visually identify cells with a high divergence value (1) by color and click to select them as a POI (2). The copied cell IDs (3) can be used for further detailed analysis.
Citing ddHodge
Please cite our paper (published in late 2025): Geometry-preserving vector field reconstruction of high-dimensional cell-state dynamics using ddHodge.
@article{maehara2025,
title = {Geometry-preserving vector field reconstruction of high-dimensional cell-state dynamics using {ddHodge}},
volume = {16},
issn = {2041-1723},
url = {https://www.nature.com/articles/s41467-025-67782-6},
doi = {10.1038/s41467-025-67782-6},
number = {1},
journal = {Nature Communications},
author = {Maehara, Kazumitsu and Ohkawa, Yasuyuki},
month = dec,
year = {2025},
pages = {11342},
}
TODO
- Add tests and documents
- Add harmonic component analyzer

