icat

Identifying Cell-states Across Treatments

ICAT is a tool developed to better identify cell states in scRNAseq experiments where perturbations or some other biologic heterogeneity is present, such as gene knock-outs.

The method works by first identifying a set of conrol-defined cell states by performing unsupervised clustering. These identified cell states are then fed into a sparse gene weighting algorithm, Neighborhood Component Feature Selection (NCFS), to highly weight the most predictive genes, while also removing variance from non-explanatory genes. We then transform the data matrix using this weight vector, and perform semi-supervised clustering such that the originally identified control labels remain constant, but cells from experimental conditions are free to cluster with any other cells regardless of treatment status.

Installation

ICAT can be installed on linux machines using pip with the following command:

pip install icat-sc

Paper

To learn more about the algorithm, and how it compares to other methods, see the original paper at Bioinformatics

How to use

ICAT makes heavy use of the excellent scanpy library along with the associated AnnData data structure.

An example code block walks through running icat on a simulated dataset. The final clustering is stored in the sslouvain column of the returned AnnData object.

fromicatimportsimulatefromicatimportmodelsimportscanpyasscimportnumpyasnpdata_model=simulate.SingleCellDataset(
populations=2,
genes=1000,
dispersion=np.random.choice([1, 2, 3], 1000)
)
controls=data_model.simulate()
controls.obs['treatment'] ='control'perturbed=simulate.perturb(controls)
perturbed.obs['treatment'] ='perturbed'adata=controls.concatenate([perturbed])
sc.pp.log1p(adata)

visualizing dataset

# specify model parameters -- see documentation for more informationmodel=models.icat(
ctrl_value="control",
ncfs_kws={'reg': 1, 'sigma': 3},
neighbor_kws={'n_neighbors': 15}, cluster_kws={'resolution': 0.75},
)
# cluster cells by providing treatment informationout=model.cluster(adata, adata.obs['treatment'])
print(out.obs['sslouvain'].unique())

visualizing results

While ICAT does not automatically compute UMAP, tsne, or other reduced dimension visualizations during clustering, it is possible to pass the upweighted count matrix (found in adata.obsm["X_icat"]) to these algorithms. In the case of UMAP, the returned adata object already has neighbors defined in this upweighted space, so calculating a new UMAP is simple:

sc.tl.umap(out)
sc.pl.umap(out, color=['sslouvain', 'Population'])

Hyper Parameter Optimization

For working with your own data, we recommend finding appropriate Louvain and NCFS hyper parameters prior to running the complete ICAT workflow. All hyper parameters used in the original pre-print can be found as supplemental tables.

We have also provided grid search functions to find the "best" n_neighbor and resolution parameters for Louvain and Semi-supervised Louvain clustering steps, as well as a function to find the "best" kernel width (sigma) and regularization parameters (reg).

fromicatimportoptimizesc.pp.pca(controls)
# Find the "best" `n_neighbor` and `resolution` parameter for clustering control cells by# optimizing the Calinski-Harabasz Index over a grid of `n` and `r` valueslouvain_n, louvain_r=optimize.optimize_louvain(
controls,
min_neighbors=3,
max_neighbors=50,
neighbor_step=2,
min_res=0.3,
max_res=1.2,
res_step=0.02,
)
# cluster control cells with "best" valuessc.pp.neighbors(controls, n_neighbors=louvain_n)
sc.tl.louvain(controls, resolution=louvain_r)
# find "best" `sigma` and `reg` NCFS values by measuring the MCC in a# weighted KNN over k-fold cross validationsigma, reg=optimize.optimize_ncfs(
controls,
controls.obs.louvain,
n_neighbors=5,
n_splits=3,
sigma_vals=[0.5, 1, 1.5, 2, 2.5, 3],
reg_vals=[0.25, 0.5, 1, 1.5, 2, 2.5, 3],
)

By default, ICAT uses the same n_neighbors and resolution parameters during semi-supervised clustering as it does during control clustering. In practice, this leads to good results (see paper). However, if users would like to optimize these parameters separately, we've include the below function:

# optimize louvain parameters for semi-supervised clustering in NCFS# space -- include complete dataset now adata.obs.loc[controls.obs.index, "control_clusters"] =controls.obs.louvainsslouvain_n, sslouvain_r=optimize_sslouvain(
adata,
adata.obs.control_clusters,
reg,
sigma,
max_cells=750,
min_neighbors=3,
max_neighbors=50,
neighbor_step=2,
min_res=0.3,
max_res=1.2,
res_step=0.02,
)