scPLAD manuscript checkpoints and model assets

This repository contains the representative scPLAD checkpoints and the compact assets needed to load them for the two experiments reported in the manuscript:

1. held-out perturbation generation within K562 (k562_only); and
2. transfer to a held-out K562 cell-line background (cross_cell_line).

The complete training, evaluation, and figure-reproduction code is maintained at https://github.com/zzgzanyr/scPLAD. This model repository complements the code repository with weights, model inputs, and the processed AnnData splits used by the two principal experiments.

Released checkpoints

Experiment	Released run	Checkpoint	Selection note
K562-only	seed 20260613	k562_only/model/model_ema_step_100000.pt	Best representative full-prior pathway-order seed across the principal reported K562 metrics
Cross-cell-line	seed 20260601	cross_cell_line/model/model_step_300000.pt	Validation-selected representative run used for the manuscript case analyses

The manuscript reports three-seed aggregate results. These two files are representative checkpoints for inference and reproduction; they are not a replacement for the three-seed statistical summaries.

Repository contents

Each experiment directory contains:

• the released diffusion-model checkpoint;
• the paired PatchAE checkpoint and configuration;
• the exact gene order used by the encoder;
• the multi-source biological-prior table;
• serialized condition features, context features, and control-anchor latents;
• displacement scaling metadata and the original run configuration.

The representative cross-cell-line checkpoint's per-condition result tables are under results/cross_cell_line/main/seed20260601/. They provide all 1,086 conditions without requiring the large generated-cell matrices.

Shared model definitions are under src/scplad_transport/, and task-specific inference entry points are under scripts/inference/.

Important input conventions

• K562-only uses a pathway-aware order of 5,000 genes.
• Cross-cell-line transfer uses a pathway-aware order of 3,352 genes.
• The prior CSV files contain 2,342 numeric prior columns plus identifier columns. The released main models exclude columns beginning with depmap_, yielding the 2,336-dimensional condition vector recorded in each model configuration.
• Published configurations and checkpoint metadata use repository-relative paths. They do not require the authors' compute environment.

Quick-start inference

Download the release and expose the bundled Python package:

hf download zhangzhigang/scPLAD --local-dir scPLAD-release
export PYTHONPATH="$PWD/scPLAD-release/src:$PYTHONPATH"

Run a one-condition K562-only smoke test. The training split is accepted as the control source; the inference script uses only rows whose condition is an explicit control label.

python scPLAD-release/scripts/inference/k562_only/generate_and_evaluate.py \
  --checkpoint scPLAD-release/k562_only/model/model_ema_step_100000.pt \
  --eval_h5ad scPLAD-release/datasets/k562_only/test.h5ad \
  --control_context_h5ad scPLAD-release/datasets/k562_only/train.h5ad \
  --output_dir outputs/k562_only_smoke \
  --max_groups 1

Cross-cell-line matrices are distributed as gzip files. Decompress them while keeping the downloaded archives, then run:

gunzip -k scPLAD-release/datasets/cross_cell_line/*.h5ad.gz
python scPLAD-release/scripts/inference/cross_cell_line/generate_and_evaluate.py \
  --checkpoint scPLAD-release/cross_cell_line/model/model_step_300000.pt \
  --eval_h5ad scPLAD-release/datasets/cross_cell_line/test.h5ad \
  --control_context_h5ad scPLAD-release/datasets/cross_cell_line/control_context.h5ad \
  --output_dir outputs/cross_cell_line_smoke \
  --context_filter K562 \
  --max_groups 1

The scripts automatically resolve the matching config/, priors/, and patchae/ directories from the checkpoint's experiment directory. Explicit --config, --gene_feature_csv, --control_anchor_latents, and --displacement_scaler overrides are also available.

Recommended verification

After downloading the repository, verify the files with:

sha256sum -c SHA256SUMS

On macOS, use shasum -a 256 -c SHA256SUMS.

Data and scope

The processed K562-only train, validation, and test AnnData matrices are available under datasets/k562_only/. The cross-cell-line data are available under datasets/cross_cell_line/: perturbation responses from RPE1, HepG2, and Jurkat form the training and validation splits, while the held-out test split contains only K562 perturbation responses. K562 non-targeting controls are provided separately for target-context construction and evaluation. Each data directory includes split documentation and SHA-256 checksums. Generated-cell matrices are not included. Lightweight per-condition metrics and their summary metadata are included under results/.

Citation and license

Citation information will be updated when the manuscript record is public.

The scPLAD-authored model weights, source code, configurations, and documentation are released under the Apache License 2.0. Processed datasets, biological-prior resources, pretrained components, and other third-party or derived assets retain their original providers' terms. See LICENSE_SCOPE.md for the exact scope before reuse or redistribution.