Xenium Human Renal Cell Carcinoma

Key features:

• Apply Gaussian smoothing to address data noise and sparsity
• Construct a gene co-expression network across samples using smoothed dataset
• Group genes into spatial modules with hard and soft thresholding on the co-expression network

In [1]:

import anndata as ad
import numpy as np
import pandas as pd
import scanpy as sc
import matplotlib.pyplot as plt

import smoothie
smoothie.suppress_warnings() # Suppress a few warnings for cleaner output

import anndata as ad import numpy as np import pandas as pd import scanpy as sc import matplotlib.pyplot as plt import smoothie smoothie.suppress_warnings() # Suppress a few warnings for cleaner output

Load AnnData¶

Smoothie requires data input in the AnnData format. A guide for constructing the AnnData data structure for both imaging-based and sequencing-based spatial transcriptomics outputs can be found in /guides/convert_to_anndata.md

In [ ]:

# Source data (output bundle full .zip): https://www.10xgenomics.com/datasets/xenium-protein-ffpe-human-renal-carcinoma
# Bash code to generate adata.h5ad from transcripts.parquet Xenium output.
# python -m smoothie.imaging_data_converter /path/to/transcripts.parquet \
#         --x-col x_location \
#         --y-col y_location \
#         --gene-col feature_name \
#         --output renal_cell_carcinoma_xenium_dataset.h5ad \
#         --format parquet

# Source data (output bundle full .zip): https://www.10xgenomics.com/datasets/xenium-protein-ffpe-human-renal-carcinoma # Bash code to generate adata.h5ad from transcripts.parquet Xenium output. # python -m smoothie.imaging_data_converter /path/to/transcripts.parquet \ # --x-col x_location \ # --y-col y_location \ # --gene-col feature_name \ # --output renal_cell_carcinoma_xenium_dataset.h5ad \ # --format parquet

In [2]:

# Load your spatial transcriptomics data
adata = ad.read_h5ad("/path/to/renal_cell_carcinoma_xenium_data.h5ad")

# Load your spatial transcriptomics data adata = ad.read_h5ad("/path/to/renal_cell_carcinoma_xenium_data.h5ad")

In [3]:

adata

adata

Out[3]:

AnnData object with n_obs × n_vars = 77033317 × 516
    obsm: 'spatial'

Quality Control¶

The table below shows suggested QC values given the resolution of your AnnData spatial coordinates.

• Note: If you have cell-segmented imaging / fine resolution data, then you should use the "Cell-sized" QC settings. If you have true individual transcripts or fine resolution data, then you should use the Fine / Imaging QC settings.

Resolution	min_counts (filter_cells)	min_counts (filter_genes)	min_cells (filter_genes)
"Cell-sized" (8-10 µm)	10 - 100	100 - 500	10 - 100
Binned (20-50 µm)	50 - 500	100 - 500	10 - 100
Fine / Imaging (< 1-2 µm)	1	100 - 500	10 - 100

In [4]:

# Filter spots with low UMI counts
sc.pp.filter_cells(adata, min_counts=1) # Each spot is a single transcript, min_counts must be 1!

# Filter genes with low counts/unique spots
sc.pp.filter_genes(adata, min_counts=50)

# Filter spots with low UMI counts sc.pp.filter_cells(adata, min_counts=1) # Each spot is a single transcript, min_counts must be 1! # Filter genes with low counts/unique spots sc.pp.filter_genes(adata, min_counts=50)

Normalization¶

Normalization depends on the resolution of your AnnData spatial coordinates.

• Note: If you have cell-segmented imaging / fine resolution data, then you should use the "Cell-sized" normalization method. If you have true individual transcripts or fine resolution data, then you should use the Fine / Imaging normalization method.

Resolution	Normalization Method
"Cell sized" or Binned Data (8-50 micron resolution)	CPT + Log1p normalization
Fine / Imaging (<1-2 micron resolution)	Log1p normalization only

In [5]:

# # CHOOSE: CPT + Log1p normalization (8-50 micron resolution data)
# sc.pp.normalize_total(adata, target_sum=1e3)
# sc.pp.log1p(adata)

# CHOOSE: Log1p normalization only (<1-2 micron resolution data)
sc.pp.log1p(adata)

# # CHOOSE: CPT + Log1p normalization (8-50 micron resolution data) # sc.pp.normalize_total(adata, target_sum=1e3) # sc.pp.log1p(adata) # CHOOSE: Log1p normalization only (<1-2 micron resolution data) sc.pp.log1p(adata)

Step 1: Run Gaussian Smoothing¶

Here, we run Gaussian smoothing on the spatial dataset address data sparsity and noise. Key parameters for function smoothie.run_parallelized_smoothing:

gaussian_sd: float

• The standard deviation for the Gaussian distribution, which determines smoothing degree. Generally across high-resolution S.T. platforms, a gaussian_sd corresponding to 20-30 microns is ideal.
• gaussian_sd is calculated as target_microns * micron_to_unit_conversion
  • For Slide-seq, micron_to_unit_conversion = 1.5456 (1 micron equals 1.5456 Slide-seq spatial units)
  • For Stereo-seq, micron_to_unit_conversion = 2 (1 micron equals 2 Stereo-seq spatial units)
  • A table of micron_to_unit_conversion values for spatial transcriptomics platforms is included in /guides/micron_to_unit_conversion_table.md

grid_based_or_not: boolean

• True = grid-based smoothing: smooth only at imposed hexagonal grid points. Good for subcellular to "cell-sized" resolution data (<1-10 micron).
• False = in-place smoothing: smooth at every spatial location in the dataset. Good for "cell-sized" to binned resolution data (10-50 micron).

min_spots_under_gaussian

• Minimum required number of data points within radius (3 * gaussian_sd) for smoothing to occur at a given location.
• Default is 10-100. Raise value if low density regions around the perimeter of tissue appear noisy in modules. Lower value if you have large spot size (e.g. original Visium 100 micron resolution data or binned 20-50 micron resolution).

In [6]:

# Determine gaussian_sd ---------------------------------------------------
target_microns = 20.0 # 20-30 microns is ideal for smoothing
micron_to_unit_conversion = 1  # IMPORTANT! For Xenium this value is 1.
# ------------------------------------------------------------------------

sm_adata = smoothie.run_parallelized_smoothing(
    adata,
    grid_based_or_not=True,  # Select True or False,
    gaussian_sd=target_microns * micron_to_unit_conversion,
    min_spots_under_gaussian=100 # Adjust as needed
)

# Determine gaussian_sd --------------------------------------------------- target_microns = 20.0 # 20-30 microns is ideal for smoothing micron_to_unit_conversion = 1 # IMPORTANT! For Xenium this value is 1. # ------------------------------------------------------------------------ sm_adata = smoothie.run_parallelized_smoothing( adata, grid_based_or_not=True, # Select True or False, gaussian_sd=target_microns * micron_to_unit_conversion, min_spots_under_gaussian=100 # Adjust as needed )

Checking dataset point density...
Fitting grid to tissue coordinates...
Variation in X-direction: 11472.671875
Variation in Y-direction: 5804.484375
Number of points in fitted grid: 187611
Gaussian smoothing will run in 36 chunks.
Smoothing chunk: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 
Total runtime for grid-based Gaussian smoothing: 196.08 seconds.

In [7]:

sm_adata

sm_adata

Out[7]:

AnnData object with n_obs × n_vars = 187611 × 516
    var: 'n_counts'
    uns: 'log1p'
    obsm: 'spatial'

Step 2: Measure and Cluster Gene Co-expression Network¶

First, we compute the pairwise Pearson correlation coefficient between all smoothed gene surface pairs.

Next, we evaluate optimal hyperparameter choices for network construction and clustering. The function smoothie.select_clustering_params calculates network clustering statistics across different choices for pcc_cutoff and clustering_power.

Choose values for pcc_cutoff and clustering_power that balance the following goals:

1. High gene margin scores for high gene module confidence
2. Stable number of modules (n_clusters) compared to other pcc_cutoff values
3. High gene recall for more gene-rich analyses

Refer to /docs/tutorials for examples on selecting these parameters.

In [8]:

# Compute pairwise gene correlations
pearsonR_mat, _ = smoothie.compute_correlation_matrix(sm_adata.X)

# Compute pairwise gene correlations pearsonR_mat, _ = smoothie.compute_correlation_matrix(sm_adata.X)

compute_correlation_matrix running...
Total runtime for compute_correlation_matrix: 1.08 seconds.

In [9]:

# Clustering hyperparameter selection
smoothie.select_clustering_params(
    gene_names=sm_adata.var_names, # don't change
    pearsonR_mat=pearsonR_mat, # don't change
    output_folder=None,
    pcc_cutoffs=[0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8], # lower pcc_cutoffs require more runtime
    clustering_powers=[1, 3, 5, 7, 9],
    min_genes_for_module=2
)

# Clustering hyperparameter selection smoothie.select_clustering_params( gene_names=sm_adata.var_names, # don't change pearsonR_mat=pearsonR_mat, # don't change output_folder=None, pcc_cutoffs=[0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8], # lower pcc_cutoffs require more runtime clustering_powers=[1, 3, 5, 7, 9], min_genes_for_module=2 )

Running network clustering with parameters:
PCC hard cutoff: 0.2, clustering soft power: 1, 3, 5, 7, 9, 
PCC hard cutoff: 0.3, clustering soft power: 1, 3, 5, 7, 9, 
PCC hard cutoff: 0.4, clustering soft power: 1, 3, 5, 7, 9, 
PCC hard cutoff: 0.5, clustering soft power: 1, 3, 5, 7, 9, 
PCC hard cutoff: 0.6, clustering soft power: 1, 3, 5, 7, 9, 
PCC hard cutoff: 0.7, clustering soft power: 1, 3, 5, 7, 9, 
PCC hard cutoff: 0.8, clustering soft power: 1, 3, 5, 7, 9, 

Optionally, data shuffling and smoothing can be done to help determine the lower bound for pcc_cutoff selection. Here, use the same parameters as before in smoothie.run_parallelized_smoothing.

In [ ]:

# p95, p99, p999 = smoothie.compute_shuffled_correlation_percentiles(
#     adata,
#     grid_based_or_not=True, # Choose same value as in smoothie.run_parallelized_smoothing
#     gaussian_sd=target_microns * micron_to_unit_conversion, # Choose same value as in smoothie.run_parallelized_smoothing
#     min_spots_under_gaussian=100, # Choose same value as in smoothie.run_parallelized_smoothing
#     seed=0
# )

# p95, p99, p999 = smoothie.compute_shuffled_correlation_percentiles( # adata, # grid_based_or_not=True, # Choose same value as in smoothie.run_parallelized_smoothing # gaussian_sd=target_microns * micron_to_unit_conversion, # Choose same value as in smoothie.run_parallelized_smoothing # min_spots_under_gaussian=100, # Choose same value as in smoothie.run_parallelized_smoothing # seed=0 # )

Based on the outputs above, we can select pcc_cutoff and clustering_power hyperparameters for smoothie.make_spatial_network.

pcc_cutoff: The Pearson correlation coefficient (PCC) hard threshold for network construction. Only correlations above this value are retained in the gene network. Higher cutoff values result in smaller, stronger average correlation networks.

clustering_power: A soft thresholding parameter that controls how much weaker PCC values are suppressed. Higher values favor more modules.

In [10]:

edge_list, node_label_df = smoothie.make_spatial_network(
    pearsonR_mat=pearsonR_mat, # don't change
    gene_names=sm_adata.var_names, # don't change
    pcc_cutoff=0.3,
    clustering_power=5,
    output_folder='./out'
)

# Filter node_label_df for only genes within modules of size 2 or more.
modules_df = node_label_df.groupby('module_label').filter(lambda x: len(x) >= 2)

# Examine modules
modules_df

edge_list, node_label_df = smoothie.make_spatial_network( pearsonR_mat=pearsonR_mat, # don't change gene_names=sm_adata.var_names, # don't change pcc_cutoff=0.3, clustering_power=5, output_folder='./out' ) # Filter node_label_df for only genes within modules of size 2 or more. modules_df = node_label_df.groupby('module_label').filter(lambda x: len(x) >= 2) # Examine modules modules_df

Out[10]:

	name	module_label	degree	weighted_degree	rescaled_weighted_degree	clustering_coeff	margin_score
0	MET	1	34	16.463557	5.947648e-01	0.370766	0.985185
1	KRT8	1	25	11.597137	2.965807e-01	0.543333	0.997236
2	SEMA3C	1	22	10.215806	2.881728e-01	0.510823	0.999998
3	KRT18	1	29	12.971457	2.861013e-01	0.453202	0.981296
4	CDH2	1	28	12.577449	2.779173e-01	0.502646	0.995451
...	...	...	...	...	...	...	...
252	KRT5	23	1	0.363811	6.295017e-06	0.000000	1.000000
253	CRHBP	24	1	0.384462	2.557468e-05	0.000000	1.000000
254	OPRPN	24	1	0.384462	2.557468e-05	0.000000	1.000000
255	CPA3	25	1	0.316276	6.795240e-09	0.000000	1.000000
256	KIT	25	1	0.316276	6.795240e-09	0.000000	1.000000

257 rows × 7 columns

Finally, we can import the saved edge_list.csv and node_labels.csv files into Cytoscape for interactive network visualization! More info in /guides/cytoscape_instructions.md

Visualize Smoothed Gene Expression and Modules¶

In [11]:

# Plot individual gene
smoothie.plot_gene(
    sm_adata=sm_adata,
    gene_name="MET",  # Replace with your gene
    output_folder="./gene_plots",
    spot_size=25, # Adjust for optimal visualization
)

# Plot individual gene smoothie.plot_gene( sm_adata=sm_adata, gene_name="MET", # Replace with your gene output_folder="./gene_plots", spot_size=25, # Adjust for optimal visualization )

In [12]:

# Plot all gene modules
smoothie.plot_modules(
    sm_adata,
    node_label_df,
    output_folder='./module_plots', 
    min_genes=2, # Minimum number of genes in a module to plot the module
    spot_size=25 # Adjust for optimal visualization
)

# Plot all gene modules smoothie.plot_modules( sm_adata, node_label_df, output_folder='./module_plots', min_genes=2, # Minimum number of genes in a module to plot the module spot_size=25 # Adjust for optimal visualization )

Analyze Specific Gene or Gene Set Correlations¶

1. Find top correlated genes to a gene of interest.
2. Build a network focused on a specific set of genes with a more permissive PCC cutoff.

In [ ]:

# Find top correlated genes for a gene of interest (GOI)
GOI_correlations = smoothie.get_correlations_to_GOI(
    pearsonR_mat=pearsonR_mat, # don't change
    gene_names=sm_adata.var_names, # don't change
    GOI="Gene1",
    reverse_order=False,  # False for top correlations, True for anti-correlations
    plot_histogram=True
)
    
print(f"\nTop 10 gene correlations with GOI:")
print(GOI_correlations[:10])

# Find top correlated genes for a gene of interest (GOI) GOI_correlations = smoothie.get_correlations_to_GOI( pearsonR_mat=pearsonR_mat, # don't change gene_names=sm_adata.var_names, # don't change GOI="Gene1", reverse_order=False, # False for top correlations, True for anti-correlations plot_histogram=True ) print(f"\nTop 10 gene correlations with GOI:") print(GOI_correlations[:10])

In [ ]:

# Build targeted network for your gene set of interest
my_gene_list = ['Gene1', 'Gene2', 'Gene3']  # Replace with your genes

# Build targeted network
geneset_edge_list, geneset_node_label_df = smoothie.make_geneset_spatial_network(
    pearsonR_mat=pearsonR_mat, # don't change
    gene_names=sm_adata.var_names, # don't change
    node_label_df=node_label_df, # don't change
    gene_list=my_gene_list,
    low_pcc_cutoff=0.3,  # More permissive pcc_cutoff than main network
    output_folder=None,
    intra_geneset_edges_only=True  # Only edges within gene set
)

print(f"Gene set network: {len(geneset_edge_list)} edges")
print(f"Genes included: {geneset_node_label_df['geneset_member'].sum()}")

# Build targeted network for your gene set of interest my_gene_list = ['Gene1', 'Gene2', 'Gene3'] # Replace with your genes # Build targeted network geneset_edge_list, geneset_node_label_df = smoothie.make_geneset_spatial_network( pearsonR_mat=pearsonR_mat, # don't change gene_names=sm_adata.var_names, # don't change node_label_df=node_label_df, # don't change gene_list=my_gene_list, low_pcc_cutoff=0.3, # More permissive pcc_cutoff than main network output_folder=None, intra_geneset_edges_only=True # Only edges within gene set ) print(f"Gene set network: {len(geneset_edge_list)} edges") print(f"Genes included: {geneset_node_label_df['geneset_member'].sum()}")