OSCR

NicheDeSig: niche-aware deconvolution and adaptive signature analysis for spatial transcriptomics.

Code ↔ Paper

1 match between paragraphs of the paper and lines of its authors' code, computed by the harvester (lexical-v1). Click a colored paragraph or line to see its counterpart.

The 1 match
  1. [1] § 2 Materials and methods › 2.4 Model optimization ↔ train.py, lines 98–139 · score 0.55 · AdamW, autoencoder, pretrain, decoder, batch, masked

Paper

Loaded from Europe PMC by your browser, not stored by OSCR: doi.org · Europe PMC

The paper is loaded when this pane is shown.

The authors' code

Python · 494 lines · 18 KB · no license · 1 match

  1. from __future__ import annotations
  3. import argparse
  4. import logging
  5. from pathlib import Path
  7. import anndata as ad
  8. import numpy as np
  9. import pandas as pd
  10. import torch
  11. import torch.nn as nn
  12. from torch.utils.data import DataLoader, TensorDataset
  14. from NicheDeSig.data import build_gene_dict
  15. from NicheDeSig.model import (
  16. NicheDeSigModel,
  17. d_hinge_loss,
  18. g_hinge_loss,
  19. kl_divergence_loss,
  20. r1_penalty,
  21. sparse_constraint,
  22. )
  23. from NicheDeSig.utils import (
  24. adata_to_frame,
  25. ensure_directory,
  26. extract_pseudo_label,
  27. get_device,
  28. one_hot,
  29. safe_write_h5ad,
  30. sanitize_label,
  31. save_json,
  32. set_seed,
  33. )
  36. def parse_args() -> argparse.Namespace:
  37. parser = argparse.ArgumentParser(description="Train NicheDeSig models.")
  38. parser.add_argument("--preproc-dir", type=str, required=True)
  39. parser.add_argument("--outdir", type=str, required=True)
  40. parser.add_argument("--feature-space", type=str, default="gene", choices=["gene", "scvi"])
  42. parser.add_argument("--celltype-key", type=str, default="celltype_final")
  43. parser.add_argument("--niche-key", type=str, default="niche")
  44. parser.add_argument("--slice-key", type=str, default="slice")
  45. parser.add_argument("--train-layer", type=str, default="norm", help="Used only in gene space.")
  47. parser.add_argument("--device", type=str, default="auto")
  48. parser.add_argument("--seed", type=int, default=42)
  49. parser.add_argument("--batch-size", type=int, default=256)
  50. parser.add_argument("--hidden-dim", type=int, default=512)
  51. parser.add_argument("--latent-dim", type=int, default=128)
  52. parser.add_argument("--predictor-hidden", type=int, default=128)
  54. parser.add_argument("--ae-epochs", type=int, default=3)
  55. parser.add_argument("--global-epochs", type=int, default=5)
  56. parser.add_argument("--niche-epochs", type=int, default=3)
  57. parser.add_argument("--ae-lr", type=float, default=1e-4)
  58. parser.add_argument("--lr", type=float, default=1e-4)
  59. parser.add_argument("--d-lr-mult", type=float, default=0.5)
  60. parser.add_argument("--mask-ratio", type=float, default=0.5)
  61. parser.add_argument("--gp-gamma", type=float, default=5.0)
  62. parser.add_argument("--w-con", type=float, default=1.0)
  63. parser.add_argument("--w-scrna", type=float, default=0.8)
  64. parser.add_argument("--w-cell", type=float, default=0.6)
  65. parser.add_argument("--w-adv", type=float, default=0.15)
  66. parser.add_argument("--w-pred", type=float, default=40.0)
  67. parser.add_argument("--w-sparse", type=float, default=0.5)
  68. parser.add_argument("--w-kl", type=float, default=4.0)
  69. parser.add_argument("--w-mask", type=float, default=2.5)
  70. return parser.parse_args()
  73. def resolve_feature_paths(preproc_dir: Path, feature_space: str) -> tuple[Path, Path, Path, str]:
  74. if feature_space == "gene":
  75. return (
  76. preproc_dir / "Real_ST_prepared_with_norm.h5ad",
  77. preproc_dir / "scRNA_prepared_with_norm.h5ad",
  78. preproc_dir / "Sm_STdata_pseudo_by_niche.h5ad",
  79. ".h5ad",
  80. )
  81. return (
  82. preproc_dir / "st_scvi_latent.h5ad",
  83. preproc_dir / "sc_scvi_latent.h5ad",
  84. preproc_dir / "sm_scvi_latent.h5ad",
  85. "_scvi_latent.h5ad",
  86. )
  89. def make_loader(x_frame: pd.DataFrame, y_frame: pd.DataFrame | None, batch_size: int, shuffle: bool) -> DataLoader:
  90. x_tensor = torch.tensor(x_frame.values, dtype=torch.float32)
  91. if y_frame is None:
  92. y_tensor = torch.zeros((x_frame.shape[0], 1), dtype=torch.float32)
  93. else:
  94. y_tensor = torch.tensor(y_frame.values, dtype=torch.float32)
  95. return DataLoader(TensorDataset(x_tensor, y_tensor), batch_size=batch_size, shuffle=shuffle, drop_last=False)
  98. def pretrain_autoencoder(
  99. model: NicheDeSigModel,
  100. feature_frame: pd.DataFrame,
  101. device: torch.device,
  102. epochs: int,
  103. lr: float,
  104. mask_ratio: float,
  105. batch_size: int,
  106. ) -> pd.DataFrame:
  107. if epochs <= 0:
  108. return pd.DataFrame()
  109. optimizer = torch.optim.AdamW(
  110. list(model.encoder.parameters()) + list(model.decoder.parameters()),
  111. lr=float(lr),
  112. weight_decay=1e-5,
  113. )
  114. mse = nn.MSELoss()
  115. loader = DataLoader(
  116. TensorDataset(torch.tensor(feature_frame.values, dtype=torch.float32)),
  117. batch_size=batch_size,
  118. shuffle=True,
  119. drop_last=False,
  120. )
  122. history: list[dict[str, float]] = []
  123. model.train()
  124. for epoch in range(1, epochs + 1):
  125. epoch_loss = 0.0
  126. n_batches = 0
  127. for (batch_x,) in loader:
  128. batch_x = batch_x.to(device)
  129. optimizer.zero_grad(set_to_none=True)
  130. masked_x, _ = model.mask_input(batch_x, mask_ratio=mask_ratio)
  131. recon_x = model.decoder(model.encoder(masked_x))
  132. loss = mse(recon_x, batch_x)
  133. loss.backward()
  134. torch.nn.utils.clip_grad_norm_(list(model.encoder.parameters()) + list(model.decoder.parameters()), max_norm=5.0)
  135. optimizer.step()
  136. epoch_loss += float(loss.item())
  137. n_batches += 1
  138. history.append({"epoch": epoch, "ae_loss": epoch_loss / max(1, n_batches)})
  139. return pd.DataFrame(history)
  142. def train_stage(
  143. model: NicheDeSigModel,
  144. sc_frame: pd.DataFrame,
  145. sc_label: pd.DataFrame,
  146. sm_frame: pd.DataFrame,
  147. sm_label: pd.DataFrame,
  148. st_frame: pd.DataFrame,
  149. gene_dict: dict[str, np.ndarray],
  150. device: torch.device,
  151. epochs: int,
  152. lr: float,
  153. d_lr_mult: float,
  154. mask_ratio: float,
  155. gp_gamma: float,
  156. batch_size: int,
  157. w_con: float,
  158. w_scrna: float,
  159. w_cell: float,
  160. w_adv: float,
  161. w_pred: float,
  162. w_sparse: float,
  163. w_kl: float,
  164. w_mask: float,
  165. ) -> pd.DataFrame:
  166. if epochs <= 0:
  167. return pd.DataFrame()
  169. optimizer_g = torch.optim.AdamW(
  170. [
  171. {"params": model.encoder.parameters()},
  172. {"params": model.predictor.parameters()},
  173. {"params": model.decoder.parameters()},
  174. {"params": model.predictor_sc.parameters()},
  175. {"params": [model.signature], "lr": float(lr) * 0.5},
  176. ],
  177. lr=float(lr),
  178. weight_decay=1e-5,
  179. )
  180. optimizer_d = torch.optim.AdamW(model.discriminator.parameters(), lr=float(lr) * float(d_lr_mult), weight_decay=1e-5)
  181. scheduler_g = torch.optim.lr_scheduler.CosineAnnealingLR(optimizer_g, T_max=max(1, epochs), eta_min=1e-5)
  182. scheduler_d = torch.optim.lr_scheduler.CosineAnnealingLR(optimizer_d, T_max=max(1, epochs), eta_min=1e-5)
  184. mse = nn.MSELoss()
  185. l1_loss = nn.L1Loss()
  186. cross_entropy = nn.CrossEntropyLoss()
  188. sc_loader = make_loader(sc_frame, sc_label, batch_size=batch_size, shuffle=True)
  189. sm_loader = make_loader(sm_frame, sm_label, batch_size=batch_size, shuffle=True)
  190. st_loader = make_loader(st_frame, None, batch_size=batch_size, shuffle=True)
  192. history: list[dict[str, float]] = []
  193. for epoch in range(1, epochs + 1):
  194. model.train()
  195. model.update_signature_from_reference(gene_dict=gene_dict, device=device)
  196. running = {
  197. "total_g": 0.0,
  198. "d_loss": 0.0,
  199. "gp": 0.0,
  200. "scrna_rec": 0.0,
  201. "cell_cls": 0.0,
  202. "pred_l1": 0.0,
  203. "adv": 0.0,
  204. "con_src": 0.0,
  205. "con_tgt": 0.0,
  206. }
  207. steps = max(len(sc_loader), len(sm_loader), len(st_loader))
  208. sc_iter = iter(sc_loader)
  209. sm_iter = iter(sm_loader)
  210. st_iter = iter(st_loader)
  212. for _ in range(steps):
  213. try:
  214. sc_x, sc_y = next(sc_iter)
  215. except StopIteration:
  216. sc_iter = iter(sc_loader)
  217. sc_x, sc_y = next(sc_iter)
  218. try:
  219. sm_x, sm_y = next(sm_iter)
  220. except StopIteration:
  221. sm_iter = iter(sm_loader)
  222. sm_x, sm_y = next(sm_iter)
  223. try:
  224. st_x, _ = next(st_iter)
  225. except StopIteration:
  226. st_iter = iter(st_loader)
  227. st_x, _ = next(st_iter)
  229. sc_x = sc_x.to(device)
  230. sc_y = sc_y.to(device)
  231. sm_x = sm_x.to(device)
  232. sm_y = sm_y.to(device)
  233. st_x = st_x.to(device)
  235. optimizer_g.zero_grad(set_to_none=True)
  237. masked_sc, _ = model.mask_input(sc_x, mask_ratio=mask_ratio)
  238. sc_latent = model.encoder(masked_sc)
  239. sc_recon = model.decoder(sc_latent)
  240. sc_logits = model.predictor_sc(model.encoder(sc_x))
  241. scrna_rec = mse(sc_recon, sc_x)
  242. sc_target = torch.argmax(sc_y, dim=1)
  243. cell_cls = cross_entropy(sc_logits, sc_target)
  245. masked_sm, _ = model.mask_input(sm_x, mask_ratio=mask_ratio)
  246. masked_st, _ = model.mask_input(st_x, mask_ratio=mask_ratio)
  247. _, rec_sm, _, _ = model(masked_sm, signature=model.signature, use_ema=False)
  248. _, rec_st, _, _ = model(masked_st, signature=model.signature, use_ema=False)
  249. con_src = mse(rec_sm, sm_x)
  250. con_tgt = mse(rec_st, st_x)
  252. optimizer_d.zero_grad(set_to_none=True)
  253. real_input = st_x.detach().requires_grad_(True)
  254. d_real = model.discriminator(real_input)
  255. d_fake = model.discriminator(rec_st.detach())
  256. d_loss = d_hinge_loss(d_real, d_fake)
  257. gp = r1_penalty(d_real, real_input, gamma=float(gp_gamma))
  258. (d_loss + gp).backward()
  259. optimizer_d.step()
  261. d_fake_for_g = model.discriminator(rec_st)
  262. adv = g_hinge_loss(d_fake_for_g)
  263. _, _, pred_sm, mask_sm = model(sm_x, signature=model.signature.detach(), use_ema=False)
  264. mask_label = (sm_y > 0.01).float()
  265. mask_l1 = l1_loss(mask_sm, mask_label)
  266. pred_l1 = l1_loss(pred_sm, sm_y)
  267. sparse_l = sparse_constraint(pred_sm, sm_y)
  268. kl_l = kl_divergence_loss(pred_sm, sm_y)
  270. total_g = (
  271. float(w_con) * (con_src + con_tgt)
  272. + float(w_scrna) * scrna_rec
  273. + float(w_cell) * cell_cls
  274. + float(w_adv) * adv
  275. + float(w_pred) * pred_l1
  276. + float(w_sparse) * sparse_l
  277. + float(w_kl) * kl_l
  278. + float(w_mask) * mask_l1
  279. )
  280. total_g.backward()
  281. torch.nn.utils.clip_grad_norm_(
  282. list(model.encoder.parameters()) + list(model.decoder.parameters()),
  283. max_norm=5.0,
  284. )
  285. optimizer_g.step()
  286. model.predictor.update_ema()
  288. running["total_g"] += float(total_g.item())
  289. running["d_loss"] += float(d_loss.item())
  290. running["gp"] += float(gp.item())
  291. running["scrna_rec"] += float(scrna_rec.item())
  292. running["cell_cls"] += float(cell_cls.item())
  293. running["pred_l1"] += float(pred_l1.item())
  294. running["adv"] += float(adv.item())
  295. running["con_src"] += float(con_src.item())
  296. running["con_tgt"] += float(con_tgt.item())
  298. scheduler_g.step()
  299. scheduler_d.step()
  300. history.append({key: value / max(1, steps) for key, value in running.items()} | {"epoch": epoch})
  301. return pd.DataFrame(history)
  304. def load_training_bundle(
  305. preproc_dir: Path,
  306. feature_space: str,
  307. celltype_key: str,
  308. niche_key: str,
  309. train_layer: str,
  310. ) -> tuple[ad.AnnData, ad.AnnData, ad.AnnData, list[str], list[str], str]:
  311. st_path, sc_path, sm_all_path, niche_suffix = resolve_feature_paths(preproc_dir, feature_space)
  312. st_adata = ad.read_h5ad(st_path)
  313. sc_adata = ad.read_h5ad(sc_path)
  314. sm_all = ad.read_h5ad(sm_all_path)
  316. if feature_space == "gene":
  317. st_adata.X = st_adata.layers[train_layer].copy()
  318. sc_adata.X = sc_adata.layers[train_layer].copy()
  319. sm_all.X = sm_all.layers[train_layer].copy()
  321. celltypes = sorted(sc_adata.obs[celltype_key].astype(str).unique().tolist())
  322. niche_ids = sorted(st_adata.obs[niche_key].astype(str).unique().tolist())
  323. return st_adata, sc_adata, sm_all, celltypes, niche_ids, niche_suffix
  326. def main() -> None:
  327. args = parse_args()
  328. logging.basicConfig(level=logging.INFO, format="%(asctime)s | %(levelname)s | %(message)s")
  329. set_seed(args.seed)
  331. device = get_device(args.device)
  332. preproc_dir = Path(args.preproc_dir)
  333. outdir = ensure_directory(args.outdir)
  335. st_adata, sc_adata, sm_all, celltypes, niche_ids, niche_suffix = load_training_bundle(
  336. preproc_dir=preproc_dir,
  337. feature_space=args.feature_space,
  338. celltype_key=args.celltype_key,
  339. niche_key=args.niche_key,
  340. train_layer=args.train_layer,
  341. )
  342. features = st_adata.var_names.astype(str).tolist()
  344. sc_frame = adata_to_frame(sc_adata)
  345. sc_label = one_hot(sc_adata.obs[args.celltype_key].astype(str), categories=celltypes, index=sc_frame.index)
  346. st_frame = adata_to_frame(st_adata)
  347. sm_all_frame = adata_to_frame(sm_all)
  348. sm_all_label = extract_pseudo_label(sm_all, celltypes=celltypes)
  349. gene_dict = build_gene_dict(
  350. sc_adata=sc_adata,
  351. celltype_key=args.celltype_key,
  352. celltypes=celltypes,
  353. layer=args.train_layer if args.feature_space == "gene" else None,
  354. )
  356. def init_model() -> NicheDeSigModel:
  357. return NicheDeSigModel(
  358. celltypes=celltypes,
  359. features=features,
  360. hidden_dim=int(args.hidden_dim),
  361. latent_dim=int(args.latent_dim),
  362. predictor_hidden=int(args.predictor_hidden),
  363. batch_size=int(args.batch_size),
  364. learning_rate=float(args.lr),
  365. ).to(device)
  367. model = init_model()
  369. logging.info("Stage 1/3: autoencoder pretraining")
  370. ae_dir = ensure_directory(outdir / "stage1_ae_pretrain")
  371. ae_history = pretrain_autoencoder(
  372. model=model,
  373. feature_frame=pd.concat([sc_frame, st_frame], axis=0),
  374. device=device,
  375. epochs=int(args.ae_epochs),
  376. lr=float(args.ae_lr),
  377. mask_ratio=float(args.mask_ratio),
  378. batch_size=int(args.batch_size),
  379. )
  380. if not ae_history.empty:
  381. ae_history.to_csv(ae_dir / "training_history.csv", index=False)
  382. model.save_checkpoint(ae_dir / "model_last.pt", extra={"stage": "autoencoder_pretrain"})
  384. logging.info("Stage 2/3: global warmup")
  385. global_dir = ensure_directory(outdir / "global")
  386. global_history = train_stage(
  387. model=model,
  388. sc_frame=sc_frame,
  389. sc_label=sc_label,
  390. sm_frame=sm_all_frame,
  391. sm_label=sm_all_label,
  392. st_frame=st_frame,
  393. gene_dict=gene_dict,
  394. device=device,
  395. epochs=int(args.global_epochs),
  396. lr=float(args.lr),
  397. d_lr_mult=float(args.d_lr_mult),
  398. mask_ratio=float(args.mask_ratio),
  399. gp_gamma=float(args.gp_gamma),
  400. batch_size=int(args.batch_size),
  401. w_con=float(args.w_con),
  402. w_scrna=float(args.w_scrna),
  403. w_cell=float(args.w_cell),
  404. w_adv=float(args.w_adv),
  405. w_pred=float(args.w_pred),
  406. w_sparse=float(args.w_sparse),
  407. w_kl=float(args.w_kl),
  408. w_mask=float(args.w_mask),
  409. )
  410. if not global_history.empty:
  411. global_history.to_csv(global_dir / "training_history.csv", index=False)
  412. model.save_checkpoint(global_dir / "model_last.pt", extra={"stage": "global"})
  413. model.signature_dataframe().to_csv(global_dir / "signature_embeddings.csv")
  415. pred_all = pd.DataFrame(index=st_frame.index, columns=celltypes, dtype=np.float32)
  417. logging.info("Stage 3/3: niche fine-tuning")
  418. for niche_id in niche_ids:
  419. niche_name = sanitize_label(niche_id)
  420. niche_dir = ensure_directory(outdir / f"niche_{niche_name}")
  421. niche_st_mask = st_adata.obs[args.niche_key].astype(str).values == str(niche_id)
  422. st_niche = st_adata[niche_st_mask].copy()
  423. if st_niche.n_obs == 0:
  424. continue
  426. if args.feature_space == "gene":
  427. pseudo_path = preproc_dir / f"Sm_pseudo_niche_{niche_name}{niche_suffix}"
  428. else:
  429. pseudo_path = preproc_dir / f"Sm_pseudo_niche_{niche_name}{niche_suffix}"
  430. if not pseudo_path.exists():
  431. logging.warning("Pseudo input missing for niche %s: %s", niche_id, pseudo_path)
  432. continue
  434. sm_niche = ad.read_h5ad(pseudo_path)
  435. if args.feature_space == "gene" and args.train_layer in sm_niche.layers:
  436. sm_niche.X = sm_niche.layers[args.train_layer].copy()
  438. niche_model = init_model()
  439. niche_model.load_state_dict(model.state_dict(), strict=True)
  440. niche_history = train_stage(
  441. model=niche_model,
  442. sc_frame=sc_frame,
  443. sc_label=sc_label,
  444. sm_frame=adata_to_frame(sm_niche),
  445. sm_label=extract_pseudo_label(sm_niche, celltypes=celltypes),
  446. st_frame=adata_to_frame(st_niche),
  447. gene_dict=gene_dict,
  448. device=device,
  449. epochs=int(args.niche_epochs),
  450. lr=float(args.lr),
  451. d_lr_mult=float(args.d_lr_mult),
  452. mask_ratio=float(args.mask_ratio),
  453. gp_gamma=float(args.gp_gamma),
  454. batch_size=int(args.batch_size),
  455. w_con=float(args.w_con),
  456. w_scrna=float(args.w_scrna),
  457. w_cell=float(args.w_cell),
  458. w_adv=float(args.w_adv),
  459. w_pred=float(args.w_pred),
  460. w_sparse=float(args.w_sparse),
  461. w_kl=float(args.w_kl),
  462. w_mask=float(args.w_mask),
  463. )
  464. if not niche_history.empty:
  465. niche_history.to_csv(niche_dir / "training_history.csv", index=False)
  466. niche_model.save_checkpoint(niche_dir / "model_last.pt", extra={"stage": "niche", "niche": str(niche_id)})
  467. niche_model.signature_dataframe().to_csv(niche_dir / "signature_embeddings.csv")
  469. niche_pred = niche_model.predict_dataframe(adata_to_frame(st_niche), device=device, batch_size=int(args.batch_size))
  470. niche_pred.to_csv(niche_dir / "pred_spots.csv")
  471. pred_all.loc[niche_pred.index, :] = niche_pred.values
  473. pred_all = pred_all.fillna(0.0).astype(np.float32)
  474. pred_all.to_csv(outdir / "pred_all_spots.csv")
  476. st_export = st_adata.copy()
  477. st_export.obsm["deconv"] = pred_all.loc[st_export.obs_names.astype(str)].to_numpy(dtype=np.float32)
  478. st_export.uns["deconv_celltypes"] = celltypes
  479. safe_write_h5ad(st_export, outdir / "st_with_deconv.h5ad")
  481. save_json(
  482. {
  483. "feature_space": args.feature_space,
  484. "n_celltypes": len(celltypes),
  485. "n_niches": len(niche_ids),
  486. "device": str(device),
  487. },
  488. outdir / "training_summary.json",
  489. )
  490. logging.info("Training outputs written to %s", outdir)
  493. if __name__ == "__main__":
  494. main()

train.py at commit a975d78, no license · at the source

Overview

Authors: Wen Xue1, Juncheng Zhang2, Tianyi Chen3, Wenjun Shen4, Jinjin Ma5, Yong Xu1, Hau-San Wong3, Si Wu1
ORCID iDs: Tianyi Chen, Jinjin Ma, Si Wu
  1. School of Computer Science and Engineering, South China University of Technology, Guangzhou, Guangdong 510006, P.R. China
  2. School of Future Technology, South China University of Technology, Guangzhou, Guangdong 510006, P.R. China
  3. Department of Computer Science, City University of Hong Kong, Kowloon 999077, Hong Kong
  4. Department of Bioinformatics, Shantou University Medical College, Shantou, Guangdong 515063, P.R. China
  5. The Institute of Future Health, South China University of Technology, Guangzhou 511442, P.R. China
Institutions: South China University of Technology (China); City University of Hong Kong (Hong Kong SAR China); Shantou University Medical College (China)
Journal: Bioinformatics (Oxford, England), volume 42, issue 8, article btag578
Dates: received 20 April 2026; accepted 20 July 2026; published online 30 July 2026; in print August 2026
Type: Research article · Language: English
License: CC BY
Identifiers: DOI 10.1093/bioinformatics/btag578 · PMID 42530368 · PMCID PMC13481669 · OpenAlex W7171800970
Open access: gold, a free copy (OpenAlex)
Status: code verified
Categories: genetics / omics (modality), human (organism), other condition (population), methods / tools (subfield)
Methods: Machine learning
MeSH: Computational Biology*, Gene Expression Profiling*, Software*, Spatial Transcriptomics*, Algorithms, Breast Neoplasms, Dorsolateral Prefrontal Cortex, Humans, Tumor Microenvironment (* major topic)
Journal subjects: Gene Expression
Topic: Single-cell and spatial transcriptomics (Molecular Biology, Biochemistry, Genetics and Molecular Biology), according to OpenAlex
Funding: Scientific Research Innovation Capability Support Project for Young Faculty (ZYGXQNJSKYCXNLZCXM-H8); National Key Research and Development Program of China (2025YFC3610300, 2025YFC3610301); Basic and Applied Basic Research Foundation of Guangdong Province (2024A1515011437, 2023A1515030154)
Citations: not cited yet (Europe PMC); 35 references in the paper

Abstract

Motivation: For spot-based spatial transcriptomics (ST), accurate cell-type deconvolution is essential for downstream analysis since each spot captures mixtures of multiple cell types. Meanwhile, spatial niches define distinct micro-environmental contexts, also salient for biological interpretation. However, existing deconvolution methods usually rely on fixed reference signatures or mapping single cells onto ST spots, without incorporating niche priors or modeling niche-dependent shifts. Consequently, existing methods remain focused on spot-level proportion estimation, with limited ability to support functional analysis of niche-associated molecular programs.

Results: We present NicheDeSig for niche-aware deconvolution. NicheDeSig models each cell type through adaptive signatures, enabling spot deconvolution under context-dependent signatures and supporting niche-aware analysis of cell-state variation across spatial micro-environments. Our method achieves strong deconvolution performance across the simulated benchmark datasets and improves spatial fidelity in the simulated colon dataset. The learned signatures recover laminar and white-matter-associated programs in the human dorsolateral prefrontal cortex (DLPFC), domain-stratified tumor microenvironment patterns in breast cancer (BRCA), and region-associated signatures in pancreatic ductal adenocarcinoma sample A (PDAC-A) and colorectal liver metastasis analyses.

Availability and implementation: Source code and the archived code snapshot are available at https://github.com/Davidcoach/NicheDeSig and https://doi.org/10.5281/zenodo.20685597.

Reproduced under the paper's license (CC BY), from the paper cited above.

Repositories

Its files are read in the Code ↔ Paper reader above, with 1 match between paragraphs and lines of code.

Zenodo 20604815

License: Apache-2.0
State: the link answers, verified on 26 September 2026
Evidence: files inventoried
Size: 1 file
Software Heritage: not checked
Found in: “Data availability”
Not found: README, license file, CITATION.cff, environment file, tests, continuous integration, documentation
Availability: 1 check, the latest on 26 September 2026: the link answers (HTTP 200)
  • 26 September 2026: the link answers (HTTP 200)
At the source: doi.org/10.5281/zenodo.20604815

Davidcoach/NicheDeSig

License: none: the authors keep all their rights
State: the link answers, verified on 26 September 2026
Evidence: files inventoried
Commit: a975d788d91455f6cf72917c9f560e1acfdc77c5, 13 June 2026
Languages: Python (8), Shell (1)
Size: 17 files, 9 scripts
Software Heritage: not archived
Found in: “Code availability”
Holds: README, environment (requirements.txt)
Not found: license file, CITATION.cff, tests, continuous integration, documentation
Tools: anndata (6 files), NumPy (6 files), pandas (6 files), PyTorch (3 files), Matplotlib (1 file), Scanpy (1 file), SciPy (1 file)
Availability: 1 check, the latest on 26 September 2026: the link answers
  • 26 September 2026: the link answers
10 files
At the source: github.com/Davidcoach/NicheDeSig

Zenodo 20685597

License: Apache-2.0
State: the link answers, verified on 26 September 2026
Evidence: files inventoried
Size: 1 file
Software Heritage: not checked
Found in: “Code availability”
Not found: README, license file, CITATION.cff, environment file, tests, continuous integration, documentation
Availability: 1 check, the latest on 26 September 2026: the link answers (HTTP 200)
  • 26 September 2026: the link answers (HTTP 200)
At the source: doi.org/10.5281/zenodo.20685597

Availability and implementation

Source code and the archived code snapshot are available at https://github.com/Davidcoach/NicheDeSig and https://doi.org/10.5281/zenodo.20685597.

Reproduced under the paper's license (CC BY), from the paper cited above.

Code availability

Source code, manuscript-specific analysis scripts, and processed outputs are available at https://github.com/Davidcoach/NicheDeSig. The archived code snapshot for this revision is available at https://doi.org/10.5281/zenodo.20685597.

Reproduced under the paper's license (CC BY), from the paper cited above.

Tracing map

Proposed by the machine: these links were found in the paper and verified at the source, without human review. The map will receive a Zenodo DOI once one of the paper's authors has validated it with their ORCID.

What the map holds:

  • 3 repositories of the authors' code, each at its verified commit, with its license and how the link was found in the paper;
  • 9 scripts, each with its path and the digest of its content;
  • 1 match between paragraphs of the paper and lines of the code (method lexical-v1);
  • neither the text of the paper nor the code itself.

Its JSON (tracing-map.json) is deposited on Zenodo with its DOI once the map is validated.

Data

No dataset and no data link were found in the paper.

Data availability

The data underlying this article are available as follows.

The 32 benchmark datasets used for quantitative evaluation follow the public benchmark collection assembled by Li et al. (2023).

The simulated colon dataset used for qualitative evaluation is a study-specific simulation.

The human DLPFC spatial transcriptomics data are publicly available through https://research.libd.org/spatialLIBD/. The paired single-nucleus RNA-seq reference can be accessed through the same resource.

The 10x Visium breast cancer spatial dataset is publicly available from the 10x Genomics Human Breast Cancer Whole Transcriptome Analysis dataset.

The PDAC-A data are publicly available from GEO under accession GSE111672.

The colorectal liver-metastasis Visium and scRNA-seq inputs are publicly available from GEO under accession GSE225857.

Processed datasets have been deposited in Zenodo. The data-package DOI is https://doi.org/10.5281/zenodo.20604815.

Reproduced under the paper's license (CC BY), from the paper cited above.

Versions

The history of this record: each version stored by the harvester or made by a correction of its authors or of the maintainers of its code, and what changed in its facts. The texts of the paper (its abstract, its availability statements) are not part of it; versions that changed only those are not listed.

Version 1, 27 September 2026: the first record

Recorded: type, language, journal, volume, issue, pages, dates, 8 authors, 9 MeSH terms, 3 funders, 35 references.

Cite

This paper

Xue, W., Zhang, J., Chen, T., Shen, W., Ma, J., Xu, Y., Wong, H.-S., & Wu, S. (2026). NicheDeSig: niche-aware deconvolution and adaptive signature analysis for spatial transcriptomics. Bioinformatics (Oxford, England), 42(8), btag578. https://doi.org/10.1093/bioinformatics/btag578

BibTeX

@article{xue2026nichedesig,
author = {Xue, Wen and Zhang, Juncheng and Chen, Tianyi and Shen, Wenjun and Ma, Jinjin and Xu, Yong and Wong, Hau-San and Wu, Si},
title = {{NicheDeSig: niche-aware deconvolution and adaptive signature analysis for spatial transcriptomics}},
journal = {Bioinformatics (Oxford, England)},
year = {2026},
month = aug,
volume = {42},
number = {8},
pages = {btag578},
publisher = {Oxford University Press},
issn = {1367-4803},
doi = {10.1093/bioinformatics/btag578},
url = {https://doi.org/10.1093/bioinformatics/btag578},
pmid = {42530368},
pmcid = {PMC13481669}
}

RIS

TY - JOUR
AU - Xue, Wen
AU - Zhang, Juncheng
AU - Chen, Tianyi
AU - Shen, Wenjun
AU - Ma, Jinjin
AU - Xu, Yong
AU - Wong, Hau-San
AU - Wu, Si
TI - NicheDeSig: niche-aware deconvolution and adaptive signature analysis for spatial transcriptomics
T2 - Bioinformatics (Oxford, England)
J2 - Bioinformatics
PY - 2026
DA - 2026/08/01
VL - 42
IS - 8
SP - btag578
SN - 1367-4803
PB - Oxford University Press
DO - 10.1093/bioinformatics/btag578
UR - https://doi.org/10.1093/bioinformatics/btag578
LA - en
ER -

CSL-JSON

{
"id": "10.1093/bioinformatics/btag578",
"type": "article-journal",
"title": "NicheDeSig: niche-aware deconvolution and adaptive signature analysis for spatial transcriptomics",
"container-title": "Bioinformatics (Oxford, England)",
"author": [
{
"family": "Xue",
"given": "Wen"
},
{
"family": "Zhang",
"given": "Juncheng"
},
{
"family": "Chen",
"given": "Tianyi"
},
{
"family": "Shen",
"given": "Wenjun"
},
{
"family": "Ma",
"given": "Jinjin"
},
{
"family": "Xu",
"given": "Yong"
},
{
"family": "Wong",
"given": "Hau-San"
},
{
"family": "Wu",
"given": "Si"
}
],
"container-title-short": "Bioinformatics",
"volume": "42",
"issue": "8",
"page": "btag578",
"DOI": "10.1093/bioinformatics/btag578",
"PMID": "42530368",
"PMCID": "PMC13481669",
"ISSN": "1367-4803",
"publisher": "Oxford University Press",
"URL": "https://doi.org/10.1093/bioinformatics/btag578",
"language": "en",
"issued": {
"date-parts": [
[
2026,
8,
1
]
]
}
}

The tracing map gets a citation of its own once an author has validated it and it has a DOI.

Similar papers

The papers with a page that share the most with this one: the tools found in their code, their categories, datasets, cited references and authors, the rarest counting most.

[1] doi:10.21203/rs.3.rs-9676637/v1 [code]
A Comprehensive Benchmarking of Spatial Deconvolution and Domain Detection Methods across Diverse Tissues and Spatial Transcriptomic Technologies
Journal: Research Square (preprint)
In common: anndata, Scanpy, PyTorch, 4 other tools, methods / tools, genetics / omics, 12 references
[2] doi:10.1016/j.isci.2026.117206 [code]
ReliST: A model-agnostic risk layer for spatial transcriptomics deconvolution.
Journal: iScience
In common: anndata, Scanpy, PyTorch, 4 other tools, genetics / omics, 12 references
[3] doi:10.1093/bioinformatics/btag515 [code]
PRISM: Prior-enhanced Inference for Spatial Transcriptomic Cell Type Mapping.
Journal: Bioinformatics (Oxford, England)
In common: anndata, Scanpy, PyTorch, 4 other tools, genetics / omics, 10 references
[4] doi:10.1093/bioinformatics/btag424 [code]
SlotDeconv: spatial transcriptomics deconvolution via diversity-constrained prototype learning and spatial refinement.
Journal: Bioinformatics (Oxford, England)
In common: anndata, Scanpy, PyTorch, 4 other tools, methods / tools, genetics / omics, 6 references
[5] doi:10.1038/s41592-026-03194-8 [code]
Beyond benchmarking: an expert-guided consensus approach to spatially aware clustering.
Journal: Nature methods
In common: anndata, Scanpy, PyTorch, 4 other tools, methods / tools, genetics / omics, 6 references
[6] doi:10.1002/advs.77003 [code]
SemanticST: A Scalable Multi-Contextual Graph Learning Framework for Uncovering Spatial Niches and Robust Multi-Sample Integration in Spatial Transcriptomics.
Journal: Advanced science (Weinheim, Baden-Wurttemberg, Germany)
In common: anndata, Scanpy, PyTorch, 4 other tools, methods / tools, genetics / omics, 6 references
[7] doi:10.1093/bib/bbag404 [code]
Navigating cell maps by deep learning integration of single-cell and spatially resolved transcriptomics.
Journal: Briefings in bioinformatics
In common: anndata, Scanpy, PyTorch, 4 other tools, genetics / omics, other condition, 5 references
[8] doi:10.1093/bib/bbag298 [code]
Empowering multifaceted analysis of spatial transcriptomics data with RGAST.
Journal: Briefings in bioinformatics
In common: anndata, Scanpy, PyTorch, 4 other tools, methods / tools, genetics / omics, 5 references
[9] doi:10.1093/bioinformatics/btag430 [code]
SPIDER: spatially integrated denoising via embedding regularization with single cell supervision.
Journal: Bioinformatics (Oxford, England)
In common: anndata, Scanpy, PyTorch, 4 other tools, genetics / omics, 5 references
[10] doi:10.1186/s13059-026-04069-z [code]
SpaNiche: spatial niche analysis to explore colocalization patterns and cellular interactions in spatial transcriptomics data.
Journal: Genome biology
In common: genetics / omics, 10 references

Contribute

The authors of this paper can claim it, correct its record and validate its tracing map, and the maintainers of its code (its owner, or a public member of its organization) correct what it says of their repository; anyone signed in can ask for its removal. Every request goes to OSCR's own machine, which answers it; your account page follows them.

Sign in with ORCID to claim this paper as one of its authors, correct its record or validate its tracing map: when the paper's metadata lists your ORCID iD, you are recognized at once. Maintainers of its code: sign in with GitHub, then claim the repository on your account page.

Request its removal

To ask OSCR to remove this record, the copies of its authors' scripts or its tracing map, use the removal request page: signed in, you say who you are, what to remove and why, then review and confirm the request. Published rules decide every request (how).

Discussion, reproductions, activity

Discussion: questions and error reports about this paper and its code, from signed-in readers and its authors. It opens with sign-in.

Reproductions: reports from readers who ran the authors' code: what they reproduced, with which environment, commit and data. It opens with sign-in.

Activity: what happens around this paper: new versions of its record, its map's validation, discussions and reproductions. It opens with sign-in.