---
library_name: pytorch
license: mit
pipeline_tag: unconditional-image-generation
tags:
- hdtree
- pytorch
- mnist
- single-cell
- clustering
---

# HDTree ICML Checkpoints

This repository hosts pretrained checkpoints for the model presented in the paper [HDTree: Generative Modeling of Cellular Hierarchies for Robust Lineage Inference](https://huggingface.co/papers/2506.23287).

HDTree is a generative modeling framework designed for robust lineage inference. It captures tree relationships within a hierarchical latent space using a unified hierarchical codebook and employs a quantized diffusion process to model continuous cell state transitions.

- **Code:** [https://github.com/zangzelin/code_HDTree_icml](https://github.com/zangzelin/code_HDTree_icml)
- **Project Page:** [https://zangzelin.github.io/code_HDTree_icml/](https://zangzelin.github.io/code_HDTree_icml/)

## Files

| File | Dataset | Configuration | Notes |
|---|---|---|---|
| `checkpoints/mnist/hdtree_mnist_best_epoch59_acc0.97570.pth` | MNIST | `configs/mnist.yaml` | Best MNIST checkpoint from the full run by checkpoint validation accuracy. |
| `checkpoints/limb/hdtree_limb_i10_epoch199_acc0.53921.pth` | Limb | `configs/limb.yaml` default | Limb sweep i10/default checkpoint. |

## Sample Usage

To validate a trained checkpoint using the official code, you can use the provided validation script:

```bash
# Example for MNIST
bash scripts/validate_checkpoint.sh mnist checkpoints/mnist/hdtree_mnist_best_epoch59_acc0.97570.pth
```

To compute reconstruction and log-likelihood with diffusion sampling, enable generation using the following command:

```bash
python main.py validate \
  -c configs/mnist.yaml \
  --model.init_args.ckpt_path=checkpoints/mnist/hdtree_mnist_best_epoch59_acc0.97570.pth \
  --model.init_args.training_str=step2_r \
  --model.init_args.gen_data_bool=True
```

## Reported Metrics

MNIST full run summary:

| ACC | DP | LP | NMI |
|---:|---:|---:|---:|
| 0.97310 | 0.93262 | 0.97310 | 0.92999 |

Limb i10 run summary (`batch_size=1000`, `K=10`, `exaggeration_lat=0.5`, `nu_lat=0.3`):

| ACC | DP | LP | NMI |
|---:|---:|---:|---:|
| 0.52860 | 0.41029 | 0.58370 | 0.49042 |

The included `logs/` files contain the original run outputs used to record these metrics.

## Download

```bash
pip install huggingface_hub
huggingface-cli download zelinzang/HDTree-ICML-checkpoints --local-dir .
```

## Checksums

See `SHA256SUMS`.