Spatial-LDA is a probabilistic topic model for identifying characteristic cellular microenvironments from in-situ multiplexed imaging data such as MIBI-ToF or CODEX.
This repository contains an implementation of the Spatial-LDA model as described in the paper Modeling Multiplexed Images with Spatial-LDA Reveals Novel Tissue Microenvironments.
Please cite our work if you find this tool useful.
Modeling Multiplexed Images with Spatial-LDA Reveals Novel Tissue Microenvironments
Zhenghao Chen, Ilya Soifer, Hugo Hilton, Leeat Keren, and Vladimir Jojic
Journal of Computational Biology 2020.04.03; doi: http://doi.org/10.1089/cmb.2019.0340
BibTeX
@article{chen2020modeling,
title={Modeling Multiplexed Images with Spatial-LDA Reveals Novel Tissue Microenvironments},
author={Chen, Zhenghao and Soifer, Ilya and Hilton, Hugo and Keren, Leeat and Jojic, Vladimir},
journal={Journal of Computational Biology},
year={2020},
publisher={Mary Ann Liebert, Inc., publishers 140 Huguenot Street, 3rd Floor New~…}
}The repository also contains notebooks that generate the results and figures presented in the paper as examples of how to use Spatial-LDA.
The easiest and preferred way to install the Spatial-LDA package is via pip:
pip install spatial_lda
Alternatively, you can clone this repository and run setup.py directly (assuming you have setuptools installed).
python setup.py install
Please refer to the included notebooks below for examples of how to train a Spatial-LDA model. We include two notebooks:
We apply Spatial-LDA to a dataset of mouse spleens from Deep Profiling of Mouse Splenic Architecture with CODEX Multiplexed Imaging to validate that it recovers known spatial relationships between immune cells in the mouse spleen.
We apply Spatial-LDA to a dataset of TNBC tumors from A Structured Tumor-Immune Microenvironment in Triple Negative Breast Cancer Revealed by Multiplexed Ion Beam Imaging to identify prototypical tumor-immune microenvironments in TNBC.
For convenience, we have included pre-processed versions of the data from the two datasets above under 'data/' and pretrained models (the output of these notebooks) under 'models/'.
Please note that in order to download the data and model files you will need to install and enable Git Large File Storage (LFS) before cloning this repository.
The Spatial-LDA model requires a dataset of index cells and neighborhood features along with an undirected graph where nodes are index cells and edges between nodes encode index cells that should be regularized to have similar topic priors.
We provide utilities in the featurization module to generate required neighborhood features
(featurization.featurize_samples) and adjacency matrices (featurization.make_merged_difference_matrices)
from dataframes containing the location and features of index and background cells.
To fit a Spatial-LDA model, call spatial_lda.model.train on the feature matrix and difference matrix generated in
the featurization step. E.g.,
spatial_lda_model = spatial_lda.model.train(train_tumor_marker_features,
train_difference_matrices,
n_topics=N_TOPICS,
difference_penalty=DIFFERENCE_PENALTY,
verbosity=1,
n_parallel_processes=3,
n_iters=3,
admm_rho=0.1,
primal_dual_mu=2)To run inference - computing regularized topic weights on a pre-trained set of topics:
complete_lda = spatial_lda.model.infer(
spatial_lda_model.components_, tumor_marker_features,
complete_difference_matrices, difference_penalty=DIFFERENCE_PENALTY,
n_parallel_processes=N_PARALLEL_PROCESSES)For reference, we also include an earlier primal-dual based implementation of the model that was described in an earlier version of our paper. However, the ADMM based solution should be preferred as it should be significantly faster.