---
title: "SpaTopic Basics"
author: "Xiyu Peng"
date: 2024-04-20

output: 
  rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{SpaTopic Basics}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
  % \VignettePackage{SpaTopic}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

**More detailed documentation is available at the [SpaTopic Home Page](https://xiyupeng.github.io/SpaTopic/). 
Please check the [github page](https://github.com/xiyupeng/SpaTopic) for more detailed information for the package.

## Introduction

Recent advancements in multiplexed tissue imaging allow for examination of tissue microenvironments in great detail. 
These cutting-edge technologies offer invaluable insights into cellular heterogeneity and spatial architectures, 
playing a crucial role in decoding mechanisms of treatment response and disease progression.

However, gaining a deep understanding of complex spatial patterns remains challenging. 
`SpaTopic` implements a novel spatial topic model to integrate both cell type and spatial information to identify the complex spatial tissue structures without human intervention.
The Collapsed Gibbs sampling algorithm is used for model inference.
Contrasting to computationally intensive K-nearest-neighbor-based cell neighborhood analysis approaches, 
`SpaTopic` is more scalable to large-scale image datasets without extracting neighborhood information for every single cell.

`SpaTopic` can be applied either on a single image or across multiple images.

## Simple Usage

The required input of SpaTopic is a data frame containing cells within on a single image or a list of data frames for multiple images. Each data frame consists of four columns: 

- image: Image ID
- X, Y: X, Y cell coordinate
- type: cell type information

```{r,warning=FALSE,message=FALSE}
library(SpaTopic)
library(sf)
## The input can be a data frame or a list of data frames
data("lung5")
head(lung5)
```

Run Gibbs Sampling
```{r,warning=FALSE,message=FALSE}
## Gibbs sampling
gibbs.res<-SpaTopic_inference(lung5, ntopics = 7, sigma = 50, region_radius = 400)
```

Check the output of SpaTopic

```{r}
str(gibbs.res)
```

For more detailed usage of SpaTopic and how to interprete output from SpaTopic,
please check the complete tutorial in [SpaTopic Home Page](https://xiyupeng.github.io/SpaTopic/).
We also provide a function to prepare input from Seurat v5 object.