Sovereign 8s.is mirror of standardgalactic/ddHodge.jl
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Kazumitsu Maehara 2808d29d92
Some checks failed
CI / Julia pre - ubuntu-latest - x64 - push (push) Has been cancelled
CI / Julia 1.11 - ubuntu-latest - x64 - push (push) Has been cancelled
CI / Julia 1.9 - ubuntu-latest - x64 - push (push) Has been cancelled
CI / Documentation (push) Has been cancelled
Merge pull request #13 from kazumits/dependabot/github_actions/julia-actions/setup-julia-3
Bump julia-actions/setup-julia from 2 to 3
2026-04-27 16:17:54 +09:00
.github Bump julia-actions/setup-julia from 2 to 3 2026-04-20 12:38:08 +00:00
docs merged original files 2024-11-12 01:01:20 +09:00
ext * refined some abstract type definitions 2025-02-09 11:37:58 +09:00
src * Added an example of POI selection in README 2025-09-24 10:17:12 +09:00
test Files generated by PkgTemplates 2024-11-12 00:35:55 +09:00
.gitignore add an image to README 2025-03-05 20:34:04 +09:00
LICENSE Files generated by PkgTemplates 2024-11-12 00:35:55 +09:00
Project.toml CompatHelper: bump compat for CUDA in [weakdeps] to 6, (keep existing compat) 2026-04-11 02:43:31 +00:00
README.md PythonCall.jl is now recommended to use with anndata 2026-03-05 15:36:58 +09:00

ddHodge

Dev Build Status

ddHodge workflow

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.

  1. Graph construction (undirected SimpleGraph type of Graphs.jl)
  2. 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: potential
  • ddh.div: divergence
  • ddh.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).

POISelection

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