Skip to content

densityPlot2D

Short Description

The sm.pl.densityPlot2D function crafts 2D density plots to visualize expression levels of one or two specified markers. When a single marker is provided, it depicts its expression distribution across the dataset. With two markers, it contrasts the expression of the first against the second, offering insights into their co-expression or distribution patterns.

Function

densityPlot2D(adata, markerA, markerB=None, layer=None, subset=None, imageid='imageid', ncols=None, cmap='jet', figsize=(3, 3), hline='auto', vline='auto', fontsize=None, dpi=100, xticks=None, yticks=None, outputDir=None, outputFileName='densityPlot2D.pdf')

Parameters:

Name Type Description Default
adata AnnData

Annotated data matrix containing single-cell gene expression data.

 required
markerA str

The name of the first marker whose expression will be plotted.

 required
markerB list

The name of the second marker or a list of second markers whose expression will be plotted. If not provided, a 2D density plot of markerA against all markers in the dataset will be plotted.

 None
layer str or list of str

The layer in adata.layers that contains the expression data to use. If None, adata.X is used. use raw to use the data stored in adata.raw.X

 None
subset list

imageid of a single or multiple images to be subsetted for plotting purposes.

 None
imageid str

Column name of the column containing the image id. Use in conjunction with subset.

 'imageid'
ncols int

The number of columns in the grid of density plots.

 None
cmap str

The name of the colormap to use. Defaults to 'jet'.

 'jet'
figsize tuple

The size of the figure in inches.

 (3, 3)
hline float or auto

The y-coordinate of the horizontal line to plot. If set to None, a horizontal line is not plotted. Use 'auto' to draw a vline at the center point.

'auto'
vline float or auto

The x-coordinate of the vertical line to plot. If set to None, a vertical line is not plotted. Use 'auto' to draw a vline at the center point.

'auto'
fontsize int

The size of the font of the axis labels.

 None
dpi int

The DPI of the figure. Use this to control the point size. Lower the dpi, larger the point size.

 100
xticks list of float

Custom x-axis tick values.

 None
yticks list of float

Custom y-axis tick values.

 None
outputDir str

The directory to save the output plot.

 None
outputFileName str

The name of the output file. Use desired file format as suffix (e.g. .png or .pdf).

 'densityPlot2D.pdf'

Returns:

Name Type Description
Plot image

If outputDir is not provided, the plot is displayed on the screen. Otherwise, the plot is saved in the provided outputDir directory.
Example 
1
2
3
4
5
# create a 2D density plot of the expression of 'CD3D' against 'CD8A' in the dataset 'adata'
sm.pl.densityPlot2D(adata, markerA='CD3D', markerB='CD8A')

# create a 2D density plot of the expression of 'CD3D' against all markers in the dataset 'adata'
sm.pl.densityPlot2D(adata, markerA='CD3D')
Source code in scimap/plotting/densityPlot2D.py 
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
def densityPlot2D (adata, 
                   markerA,  markerB=None, 
                   layer=None, 
                   subset=None, 
                   imageid='imageid', 
                   ncols=None, 
                   cmap='jet', 
                   figsize=(3, 3), 
                   hline = 'auto', vline = 'auto',
                   fontsize=None, 
                   dpi=100, 
                   xticks=None,
                   yticks=None,
                   outputDir=None, 
                   outputFileName='densityPlot2D.pdf'):

    """
Parameters:
    adata (anndata.AnnData): 
        Annotated data matrix containing single-cell gene expression data.

    markerA (str):  
        The name of the first marker whose expression will be plotted.

    markerB (list, optional):  
        The name of the second marker or a list of second markers whose expression will be plotted. 
        If not provided, a 2D density plot of `markerA` against all markers in the dataset will be plotted.

    layer (str or list of str, optional):  
        The layer in adata.layers that contains the expression data to use. 
        If None, adata.X is used. use `raw` to use the data stored in `adata.raw.X`

    subset (list, optional):  
        `imageid` of a single or multiple images to be subsetted for plotting purposes.

    imageid (str, optional):  
        Column name of the column containing the image id. Use in conjunction with `subset`.

    ncols (int, optional):  
        The number of columns in the grid of density plots.

    cmap (str, optional):  
        The name of the colormap to use. Defaults to 'jet'.

    figsize (tuple, optional):  
        The size of the figure in inches.

    hline (float or 'auto', optional):  
        The y-coordinate of the horizontal line to plot. If set to `None`, a horizontal line is not plotted. 
        Use 'auto' to draw a vline at the center point. 

    vline (float or 'auto', optional):  
        The x-coordinate of the vertical line to plot. If set to `None`, a vertical line is not plotted. 
        Use 'auto' to draw a vline at the center point. 

    fontsize (int, optional):  
        The size of the font of the axis labels.

    dpi (int, optional):  
        The DPI of the figure. Use this to control the point size. Lower the dpi, larger the point size.

    xticks (list of float, optional):  
        Custom x-axis tick values.

    yticks (list of float, optional):  
        Custom y-axis tick values.

    outputDir (str, optional):  
        The directory to save the output plot.

    outputFileName (str, optional):  
        The name of the output file. Use desired file format as suffix (e.g. `.png` or `.pdf`).

Returns:
    Plot (image):  
        If `outputDir` is not provided, the plot is displayed on the screen. 
        Otherwise, the plot is saved in the provided `outputDir` directory.

Example:
    ```python

    # create a 2D density plot of the expression of 'CD3D' against 'CD8A' in the dataset 'adata'
    sm.pl.densityPlot2D(adata, markerA='CD3D', markerB='CD8A')

    # create a 2D density plot of the expression of 'CD3D' against all markers in the dataset 'adata'
    sm.pl.densityPlot2D(adata, markerA='CD3D')
    ```

    """
    # testing
    # import anndata as ad
    # adata = ad.read(r"C:\Users\aj\Dropbox (Partners HealthCare)\nirmal lab\softwares\scimap\scimap\tests\_data\example_data.h5ad")
    # adata = ad.read('/Users/aj/Dropbox (Partners HealthCare)/nirmal lab/softwares/scimap/scimap/tests/_data/example_data.h5ad')
    # markerA ='CD3E'; layers=None; markerB='CD163'; plotGrid=True; ncols=None; color=None; figsize=(10, 10); fontsize=None; subset=None; imageid='imageid'; xticks=None; dpi=200; outputDir=None; 
    # hline = 'auto'; vline = 'auto'
    # outputFileName='densityPlot2D.png'
    # color = {'markerA': '#000000', 'markerB': '#FF0000'}
    # outputDir = r"C:\Users\aj\Downloads"

    #densityPlot2D (adata, markerA='CD3D', markerB=['CD2', 'CD10', 'CD163'], dpi=50, outputDir=r"C:\Users\aj\Downloads")


    # set color
    cp = copy.copy(cm.get_cmap(cmap))
    cp.set_under(alpha=0)

    # subset data if neede
    if subset is not None:
        if isinstance (subset, str):
            subset = [subset]
        if layer == 'raw':
            bdata=adata.copy()
            bdata.X = adata.raw.X
            bdata = bdata[bdata.obs[imageid].isin(subset)]
        else:
            bdata=adata.copy()
            bdata = bdata[bdata.obs[imageid].isin(subset)]
    else:
        bdata=adata.copy()

    # isolate the data
    if layer is None:
        data = pd.DataFrame(bdata.X, index=bdata.obs.index, columns=bdata.var.index)
    elif layer == 'raw':
        data = pd.DataFrame(bdata.raw.X, index=bdata.obs.index, columns=bdata.var.index)
    else:
        data = pd.DataFrame(bdata.layers[layer], index=bdata.obs.index, columns=bdata.var.index)

    # keep only columns that are required
    x = data[markerA]

    if markerB is None:
        y = data.drop(markerA, axis=1)
    else:
        if isinstance(markerB, str):
            markerB = [markerB]
        y = data[markerB]

    # auto identify rows and columns in the grid plot
    def calculate_grid_dimensions(num_items, num_columns=None):
        """
        Calculates the number of rows and columns for a square grid
        based on the number of items.
        """
        if num_columns is None:
            num_rows_columns = int(math.ceil(math.sqrt(num_items)))
            return num_rows_columns, num_rows_columns
        else:
            num_rows = int(math.ceil(num_items / num_columns))
            return num_rows, num_columns

    # calculate the number of rows and columns
    num_rows, num_cols = calculate_grid_dimensions(len(y.columns), num_columns = ncols)



    fig, axs = plt.subplots(nrows=num_rows, ncols=num_cols, figsize=(num_cols*figsize[0],num_rows*figsize[0]), subplot_kw={'projection': 'scatter_density'})
    if num_rows == 1 and num_cols == 1:
        axs = [axs]  # wrap single subplot in a list
    else:
        axs = axs.flatten()
    for i, col in enumerate(y.columns):
        ax = axs[i]
        ax.scatter_density(x, y[col], dpi=dpi, cmap=cp, norm=LogNorm(vmin=0.5, vmax=x.size))
        ax.set_xlabel(markerA, size = fontsize)
        ax.set_ylabel(col, size = fontsize)

        if hline == 'auto':
            ax.axhline((y[col].max() + y[col].min()) / 2, color='grey')
        elif hline is None:
            pass
        else:
            ax.axhline(hline, color='grey')

        if vline == 'auto':
            ax.axvline((x.max() + x.min()) / 2, color='grey')
        elif vline is None:
            pass
        else:
            ax.axvline(vline, color='grey')

        # control and x and y ticks
        if xticks is not None:
            ax.set_xticks(xticks)
            ax.set_xticklabels([str(x) for x in xticks])

        if yticks is not None:
            ax.set_yticks(yticks)
            ax.set_yticklabels([str(x) for x in yticks])


    # Remove any empty subplots
    num_plots = len(y.columns)
    for i in range(num_plots, num_rows * num_cols):
        ax = axs[i]
        fig.delaxes(ax)

    plt.tick_params(axis='both', labelsize=fontsize)
    plt.tight_layout()

    # Save the figure to a file
    # save figure
    if outputDir is not None:
        plt.savefig(pathlib.Path(outputDir) / outputFileName)