
---
title: "Interface with other single-cell analysis toolkits"
author: "Suoqin Jin"
date: "`r format(Sys.time(), '%d %B, %Y')`"
output:
  html_document:
    toc: true
    theme: united
mainfont: Arial
vignette: >
  %\VignetteIndexEntry{Interface with other single-cell analysis toolkits}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r setup, include = FALSE}
knitr::opts_chunk$set(eval = FALSE)
```

# Create a CellChat object from Seurat or SingleCellExperiment object
From CellChat version 0.5.0, **USERS can create a new CellChat object from Seurat or SingleCellExperiment object.** .  If input is a Seurat or SingleCellExperiment object, the meta data in the object will be used by default and USER must provide `group.by` to define the cell groups. e.g, group.by = "ident" for the default cell identities in Seurat object. 

Please check the examples in the documentation of `createCellChat` for details via `help(createCellChat)`. 

**NB: If USERS load previously calculated CellChat object (version < 0.5.0),  please update the object via `updateCellChat`** 


## Converting between single-cell objects (Seurat, SingleCellExperiment and anndata objects)
There are several excellent tools to convert between Seurat objects, SingleCellExperiment objects, and anndata objects. Here are two examples: one is [Seurat R package](https://satijalab.org/seurat/v3.1/conversion_vignette.html) from Satija Lab, and another is [zellkonverter R package](https://github.com/theislab/zellkonverter) from Theis Lab. 


# Create a CellChat object from a data matrix extracting from Seurat and Scanpy tools

Below we shows how to extract the CellChat input files as data matrix from other existing single-cell analysis toolkits, including [Seurat](https://satijalab.org/seurat/) and [Scanpy](https://icb-scanpy.readthedocs-hosted.com/en/stable/tutorials.html). 


## Data input required in CellChat
CellChat requires two user inputs: one is the gene expression data of cells, and the other is either user assigned cell labels (i.e., label-based mode) or a low-dimensional representation of the single-cell data (i.e., label-free mode). For the latter, CellChat automatically groups cells by building a shared neighbor graph based on the cell-cell distance in the low-dimensional space or the pseudotemporal trajectory space. 

### Data format
*For the gene expression data matrix*, genes should be in rows with rownames and cells in columns with colnames. Normalized data is required as input for CellChat analysis, e.g., library-size normalization and then log-transformed with a pseudocount of 1. If user provides count data, we provide a `normalizeData` function to account for library size. 

*For the cell group information*, a dataframe with rownames is required as input for CellChat. 

## Extract the CellChat input files from a Seurat V3 object
The normalized count data and cell group information can be obtained from the Seurat object by
```{r}
data.input <- GetAssayData(seurat_object, assay = "RNA", slot = "data") # normalized data matrix
labels <- Idents(seurat_object)
meta <- data.frame(group = labels, row.names = names(labels)) # create a dataframe of the cell labels
```

## Extract the CellChat input files from a Seurat V2 object
The normalized count data and cell group information can be obtained from the Seurat object by
```{r}
data.input <- seurat_object@data # normalized data matrix
labels <- seurat_object@idents
meta <- data.frame(group = labels, row.names = names(labels)) # create a dataframe of the cell labels
```

## Extract the CellChat input files from a Scanpy object
anndata provides a python class that can be used to store single-cell data. This data format is also use for storage in the scanpy package. We first read the data into R using the reticulate package to import the anndata module.

Please also check the suggestions by other USERS (https://github.com/sqjin/CellChat/issues/300#issuecomment-1116343516)
```{r}
library(reticulate)
ad <- import("anndata", convert = FALSE)
ad_object <- ad$read_h5ad("scanpy_object.h5ad")
# access normalized data matrix
data.input <- t(py_to_r(ad_object$X))
rownames(data.input) <- rownames(py_to_r(ad_object$var))
colnames(data.input) <- rownames(py_to_r(ad_object$obs))
# access meta data
meta.data <- py_to_r(ad_object$obs)
meta <- meta.data
```


Upon extracting the required CellChat input files, then create a CellChat object and start the analysis.

## Create a CellChat object using data matrix as input
```{r}
cellchat <- createCellChat(object = data.input, meta = meta, group.by = "labels")
```

## Add cell information into *meta* slot of the object
If cell mata information is not added when creating CellChat object, USERS can also add it later using `addMeta`, and set the default cell identities using `setIdent`.
```{r eval = FALSE}
cellchat <- addMeta(cellchat, meta = meta, meta.name = "labels")
cellchat <- setIdent(cellchat, ident.use = "labels") # set "labels" as default cell identity
levels(cellchat@idents) # show factor levels of the cell labels
```

