Tutorial

Getting started

After installation of scSELpy, lets load scSELpy as scS. scSELpy does not use dependencies that scanpy does not use, if scanpy runs fine on your system, scSELpy should also work.

 
#If plots are not being shown on Jupyter Notebook, try using:
#%matplotlib inline
#Do not use it on ipython.

import scanpy as sc 
import scselpy as scS 
adata = scS.generate.adata()

sc.pl.umap(adata,color='CellType1')
sc.pl.scatter(adata,"x_scat","y_scat",color='CellType2') #in scatter plot, x_scat and y_scat could be e.g. n_genes and n_counts in a real anndata object.

png

Selecting cells on UMAP

We will now select our cells using scSELpy.

Some tips before:

Left click to select.
Middle button to erase last selected point.
Right click once when you are done selecting.
Right click twice when you want to exit. Do not use the X(cross) in the top right corner to exit.

Running scSELpy

Lets run scSELpy. Since we imported scSELpy as scS, we can basically copy paste the code of scanpy imported as sc, and change sc to scS.

A window should popup, in which you can select your cells. Left click a few times on the plot, afterwards right click two times to exit.

scS.pl.umap(adata,color="CellType1")#,helpbox=True 

png

Ploting selected cells

The selected cells are annotated and stored as Anndata observations. By default, it is stored as REMAP_1. The second time your run scSELpy, it will be stored as REMAP_2 and so on. If scselpy.settings.verbosity is atleast 2 (2 by default), the stored observation name will be output after it is added by scSELpy.

sc.pl.umap(adata,color="REMAP_1")

png

Lets say we are only interested in our select cells, we can remove the other cells.

adata_selected = adata[adata.obs["REMAP_1"] != "Other"]
sc.pl.umap(adata_selected,color="REMAP_1")

png

Or the inverse, only keep other.

adata_unselected = adata[adata.obs["REMAP_1"] == "Other"]#Lets say we are only interested in our select cells, we can remove the other cells.
sc.pl.umap(adata_unselected,color="REMAP_1")

png

Replot the selection with the CellTypes as background.

scS.pl.umap(adata_unselected,color="CellType1",replot_lines="REMAP_1")

png

The coordinates of the polygons are stored in Anndata Unstructured annotation. By running adata.uns, we can see the coordinates of the polygon. Alternatively, we can run scselpy.pl.umap(adata,printcords=True), to print the coordinates of the polygon. These coordinates can be added to the mock parameter, to automatically redraw the polygons. More on the mock parameter in the Mock toturial.

Selecting cells on Scatter plots.

Besides UMAP, we can also select on PCA, TSNE and Scatter plots. It is basically all the same. Here we demonstrate the cell selection on Scatter plots.

This time, lets make multiple overlapping selections. After you made your selection with left click, right click once and make a new selection with left click. After you are done, right click twice

scS.pl.scatter(adata,"x_scat","y_scat",color='CellType2') 

png

For the consequetive scatter plot, the selected cells were stored as REMAP_2

sc.pl.scatter(adata,"x_scat","y_scat",color='REMAP_2')

png

Lets use the selection from above and add an extra selection to it, using the load parameter.

scS.pl.scatter(adata,"x_scat","y_scat",color='REMAP_2',load="REMAP_2",replot_lines="REMAP_2")

png

Revisualize using scanpy. Now we have an extra selection.

sc.pl.scatter(adata,"x_scat","y_scat",color='REMAP_2')

png

It is also possible to totally overwrite any existing cluster.

scS.pl.scatter(adata,"x_scat","y_scat",color='REMAP_2',load="REMAP_2",overwrite=True)
sc.pl.scatter(adata,"x_scat","y_scat",color='REMAP_2')

png

from scanpy.plotting import palettes
color_pal = palettes.vega_20
#color_pal = palettes.default_102

scSELpy is not made for more than one input for the color parameter. If this is done, the lines will always be shown on the right most plot. Example:

scS.pl.umap(adata,color=["CellType2","CellType1"],replot_lines="REMAP_2",line_palette=palettes.default_102[5:8],line_labels=["A","B","C"])

png

With line_palette, we can specify the colors of the lines

scS.pl.umap(adata,line_palette=palettes.default_102) 

png

We can also add a legend

scS.pl.umap(adata,replot_lines="REMAP_3",line_palette=palettes.default_102[5:8],line_labels=["A","B","C"])

png

Or change the position of the legend

scS.pl.umap(adata,replot_lines="REMAP_3",line_palette=palettes.default_102[12:15],line_labels=["A","B","C"],line_loc='upper right',line_bbox_to_anchor=(-0.05,1))

png

Or not show all labels

scS.pl.umap(adata,replot_lines="REMAP_3",line_palette=palettes.default_102[12:14],line_labels=["A","B","_nolegend_"],line_loc='upper right',line_bbox_to_anchor=(-0.05,1))

png

Changing annotation names

sc.pl.umap(adata,color="REMAP_3")

png

We are going to rename the annotations. Number 1 and 2 will be part of “gene A” and number 3 will be “gene B” Lets generate a dictionary in which we can assign the names we want to replace for REMAP_3.

scS.annotate.gen_dict(adata.obs['REMAP_3'])

{'2': '2', 'Other': 'Other', '3': '3', '1': '1'}

Lets copy the dict above and rename:

input_dict = {'2': 'Gene B',
 '3': 'Gene A',
 'Other': 'Other',
 '1': 'Gene A'}

adata.obs['REMAP_3_renamed'] = scS.annotate.rename(adata.obs['REMAP_3'],input_dict)

sc.pl.umap(adata,color="REMAP_3_renamed")

png

Now the annotations are renamed. If we would load REMAP_3_renamed and plot more lines, the reannotated names would not change. If we however used replot_lines parameter together with the load parameter, the old numeric names would reappear and be added to the new annotations. Please be aware of this.

Selection tools

scSELpy has a function to:

calculate the % of cells in each selection

scS.tl.cells_per_cluster(adata,"REMAP_3_renamed")

{'Other': 57.17, 'Gene A': 25.5, 'Gene B': 11.67, 'Gene A,Gene B': 5.67}

to calculate the % of cells expressing a certain gene in each selection

scS.tl.cells_expressing_gene(adata,"REMAP_3_renamed","ENSG00000075624")

{'Gene A': 49.02, 'Gene A,Gene B': 50.0, 'Gene B': 58.57, 'Other': 46.36}

In the case that the gene name is not stored in anndata.var_names, but e.g. in anndata.var["Genes"], we can run:

scS.tl.cells_expressing_gene(adata,"REMAP_3_renamed","ACTB",which_var="Genes")

{'Gene A': 49.02, 'Gene A,Gene B': 50.0, 'Gene B': 58.57, 'Other': 46.36}

Calculate the Transcripts per Million:

scS.tl.calculate_TPM(adata,"REMAP_3_renamed","ACTB",which_var="Genes",use_raw=False)

{'Gene A': 7.33, 'Gene A,Gene B': 6.2, 'Gene B': 11.82, 'Other': 6.87}

Tips and tricks

If you do not want to store to REMAP_1, you can also create your own name.

adata.obs['Own_name'] = ['Other']*len(adata.obs)
scS.pl.umap(adata,load="Own_name",printcords=True)
sc.pl.umap(adata,color="Own_name")

png

If you want to show a subcluster but not move the entire plot, you can draw a line around it and change the line_palette parameter to a color with a transparancy setting of 0, e.g. (0,0,0,0).

scS.pl.umap(adata,color='CellType1')

png

for ct in sorted(set(adata.obs['CellType1'])):
    print(ct)
    scS.pl.umap(adata[adata.obs['CellType1'] == ct],color="CellType1",replot_lines="REMAP_4",line_palette=[(0,0,0,0)],size=200)

png