Renoir API

This page documents every public function in Renoir. Internal helper functions (entropy, ISM, PEM, min_max, etc.) are intentionally omitted — they are implementation details not intended for direct use.

Core functions (Renoir.renoir)

These functions cover the full pre-processing and score-computation pipeline, from building the neighborhood graph through to producing the final AnnData of neighborhood scores.

Renoir.renoir.compute_neighborhood_scores(SC_path, ST_path, pairs_path, ligand_receptor_path, celltype_proportions_path, expins_path=None, single_cell=False, use_radius=False, radius=0, return_adata=True)

Computes neighborhood score for each ligand-target pair across each spot.

Parameters:

  • SC_path – path to single cell RNA-seq data as an anndata object

  • ST (str) – path to spatial transcriptomics data as an anndata object

  • pairs_path (str) – path to a .csv file with ligand target pairs. The ligand and target are two columns in the dataframe with column labels ‘ligand’ and ‘target’

  • ligand_receptor_path (str) – path to a .csv file with ligand receptor pairs. The ligand and receptors are two columns in the dataframe with column labels ‘ligand’ and ‘receptor’

  • celltype_proportions_path (str) – path to a .csv file with celltype proportions. Rows are spots and columns are celltypes.

  • expins_path – path to celltype specific mRNA abundance values for each gene. These values can be estimated using cell2location.

  • single_cell (bool, optional) – Default False. Whether the spatial transcriptomic data is of single cell resolution. Set to true if you want to use radius

  • use_radius (bool, optional) – Needed when single cell set to True.

  • radius (float, optional) – Needed when single cell set to True.

  • return_adata (bool, optional) – Return neighborhood scores as an anndata object with ST spatial information, defaults to True

Returns:

neighborhood scores

Return type:

ndarray

Renoir.renoir.neighborhood(X_coord, Y_coord, technology, radius)

Generate neighborhood graph provided X and Y coordinates of each spot.

Parameters:

  • X_coord (list) – List of X coordinates of spatial transcriptomics data

  • Y_coord (list) – List of Y coordinates of spatial transcriptomics data

  • technology (str) – spatial technology used to generate spatial data. Currently supports argument “visium”.

  • radius (float) – (Optional) Every spot within radius distance from a spot is considered as the spots neighbor.

Raises:

Exception – Raises exception if appropriate tehcnology is not selected.

Returns:

2D array of graph with corresponding neighbor indices

Return type:

ndarray

Renoir.renoir.get_ligand_target(ligands, targets, ST, SC, expins_genes, lr_database, celltypes)

Get unique set of ligands and targets and indexed ligand target pairs.

Parameters:

  • ligands (list) – List of ligands as they occur with every corresponding target

  • targets (list) – _List of targets as they occur with every corresponding ligand

  • ST (AnnData) – spatial transcriptomics data as an anndata object

  • SC (AnnData) – single cell RNA-seq data as an anndata object

  • expins_genes (list) – List of uniques genes for which celltype specific mRNA abundance have been calculated

  • lr_database (str) – Path to a csv with ligand-receptor pairs

  • celltypes (list) – List of celltypes involved

Raises:

Exception – Raises exception if each ligand provided does not correspond to each target provided

Returns:

  • unique ligands and targets (dict) - dictionary with indexed, unique, ligands and targets

  • ligand target pairs (ndarray) - 2D array of ligands and their corresponding targets

  • ST non zero matrix (ndarray) - Boolean matrix denoting non zero values in ST

  • ligand receptor celltype matrix - A boolean matrix denoting the presence of any receptor corresponding to a ligand in a cell type

Renoir.renoir.compute_celltype_expression(expr, ct, genes, celltypes, spot_indices)

Compute celltype-specific gene expression as sparse matrices.

For each gene, the celltype-specific expression at a spot is defined as the product of the gene’s expression at that spot and the celltype proportion at that spot, yielding a spot × celltype matrix. All matrices are returned as Compressed Sparse Row (CSR) sparse matrices of dtype float64.

Parameters:

  • expr (numpy.ndarray) – Expression matrix of shape (n_spots, n_genes).

  • ct (numpy.ndarray) – Celltype proportion matrix of shape (n_spots, n_celltypes).

  • genes (list) – List of gene names in the same column order as expr.

  • celltypes (list) – List of celltype names in the same column order as ct.

  • spot_indices (list) – List of spot identifiers in the same row order as expr and ct.

Raises:

ValueError – If the number of rows in expr and ct do not match, or if the lengths of genes, celltypes, or spot_indices are inconsistent with the shapes of expr and ct.

Returns:

Dictionary mapping each gene name to a CSR sparse matrix of shape (n_spots, n_celltypes) and dtype float64, where entry [i, j] is the expression of the gene at spot spot_indices[i] weighted by the proportion of celltype celltypes[j] at that spot.

Return type:

dict[str, scipy.sparse.csr_matrix]

Renoir.renoir.register_table(sdata, adata, table_name, region, reference_table_key, instance_key='instance_id', region_key='region')

Add a copy of an AnnData object into a SpatialData object as a named table.

SpatialData requires every table to declare which spatial element it annotates via three metadata fields set in .uns['spatialdata_attrs']: region, region_key, and instance_key. This function sets all three up automatically by aligning the AnnData obs_names against a reference table already present in sdata. Observations present in the reference table but absent in adata are filled with zeros, so the registered table is always index-complete with respect to the reference.

Parameters:

  • sdata (spatialdata.SpatialData) – The SpatialData object to add the table to. Modified in-place.

  • adata (anndata.AnnData) – The AnnData to register. Its obs_names must be a subset of the obs_names of the reference table in sdata. Observations not present in adata are padded with zeros in the registered table.

  • table_name (str) – Key under which the new table will be stored in sdata.tables.

  • region (str) – Name of the shape element in sdata that this table annotates, e.g. 'A1_square_016um' or 'cell_boundaries'.

  • reference_table_key (str) – Key of an existing table in sdata.tables whose obs_names and instance_key column are used as the alignment reference, e.g. 'square_016um'.

  • instance_key (str) – Name of the obs column that holds integer instance IDs matching the row index of the shape element. Taken from the reference table and propagated to the registered table.

  • region_key (str) – Name of the obs column that holds the region name for each row. Created automatically.

Raises:

  • KeyError – If reference_table_key is not found in sdata.tables, or if region is not found in sdata.shapes.

  • ValueError – If instance_key is not present in the reference table’s obs, or if none of the adata obs_names are found in the reference table.

Returns:

The same SpatialData object passed in, modified in-place with the new table accessible at sdata.tables[table_name].

Return type:

spatialdata.SpatialData

Downstream analysis (Renoir.downstream)

These functions operate on the neighborhood-score AnnData produced by Renoir.renoir.compute_neighborhood_scores() and cover the full downstream workflow: clustering, domain identification, pathway activity, ligand ranking, and visualization.

Renoir.downstream.get_msig(species, path=None)
Renoir.downstream.create_cluster(neighbscore, msig, pathway_path=None, method='dhc', minpts=3, use_pathway=False, pathway_thresh=4, ltclust_thresh=6, restrict_to_KHW=False)

Creation of ligand-target pair sets using provided pathways; or by De novo clustering of ligand-target pairs.

Parameters:

  • neighbscore (AnnData) – Neighborhood scores generated

  • msig (DataFrame) – Dataframe with columns ‘gs_name’ and ‘gs_symbol’

  • pathway_path (str, optional) – Subset of pathways to use within msig, defaults to None

  • method (str, optional) – Clustering method for De novo clusters (available: [‘hdbscan’,’dhc’]), defaults to ‘dhc’

  • minpts (int, optional) – Minimum cluster size for hdbscan option, defaults to 3

  • use_pathway (bool, optional) – Use pathway_path to subset msig, defaults to False

  • pathway_thresh (int, optional) – Minimum number of ligand-target pairs in pathway ligand-target pair set, defaults to 4

  • ltclust_thresh (int, optional) – Minimum number of ligand-target pairs in De novo ligand-target pair set, defaults to 6

  • restrict_to_KHW (bool, optional) – Restrict pathways to KEGG, HALLMARK and WIKIPATHWAYS (Note: gs_name should have prefixes ‘KEGG_’, ‘HALLMARK_’, ‘WP_’ in order to be considered), defaults to False

Returns:

Dictionary of pathways/De novo clusters and their corresponding ligand-target pair sets

Return type:

dict

Renoir.downstream.downstream_analysis(neighbscore, ltpair_clusters=None, resolution=0.8, n_markers=20, n_top=20, pdf_path=None, return_cluster=False, return_pcs=False)

Performs leiden clustering over neighborhood scores, generates DE ligand-target pairs for each domain, finds top n highly expressed pairs across each domain and converts pathway/De novo cluster scores into AnnData objects. (Note: This function executes default DE analysis as is mentioned in scanpy docs. For more flexibility, it is recommended for users to perform analysis over generated neighborhood scores manually with the help of scanpy)

Parameters:

  • neighbscore (AnnData) – adata object with pre computed neighborhood scores

  • ltpair_clusters (dict, optional) – Dictionary of pathway/gene set vs ligand-target pairs. Can be generated using create_cluster, defaults to None

  • resolution (float, optional) – resoluton parameter for leiden clustering, defaults to 0.8

  • n_markers (int, optional) – number of markers to display for each cluster, defaults to 20

  • n_top (int, optional) – number of highly expressed ligand-target pairs to display, defaults to 20

  • pdf_path (str, optional) – path where the results are to be stored as a pdf, defaults to None

  • return_cluster (bool, optional) – return adata object with computed leiden clusters, defaults to False

  • return_pcs (bool, optional) – return adata object with pathway/geneset and their corresponding scores, defaults to False

Returns:

return adata neighborhood score adata object with leiden clusters and/or adata object with pathway/geneset and their corresponding scores

Return type:

AnnData

Renoir.downstream.spot_v_spot(neighbscore, celltype, resolution=0.8, ltpair_clusters=None, n_markers=20, n_top=20, pdf_path=None)
Renoir.downstream.pcs_v_neighbscore(neighbscore, ltpair_clusters=None, pdf_path=None, spatialfeatureplot=True, clustermap=True, size=1.4, colormap=seaborn.color_palette)

Generate heatmaps of pathway/geneset scores vs individual liagnd-target contribution

Parameters:

  • neighbscore (AnnData) – adata object of neighborhood scores

  • ltpair_clusters (dict, optional) – dictionary of genesets/pathways with corresponding ligand-target pairs (can be generated using create_cluster), defaults to None

  • pdf_path (str, optional) – path to save plots as a pdf file, defaults to None

  • spatialfeatureplot (bool, optional) – Include spatial feature plots of geneset/pathway activity, defaults to True

  • clustermap (bool, optional) – Generate clustermap of each pathway/geneset, defaults to True

  • size (float, optional) – spot size (required if spatialfeatureplot is set to True), defaults to 1.4

  • colormap (_type_, optional) – colormap for the heatmap and spatial fetaure plots, defaults to sns.color_palette(“Spectral”,as_cmap=True)

Renoir.downstream.ligand_ranking(neighbscore, celltype, scrna, ligand_receptor_pairs, ligand_target_regulatory_potential, domain, receptor_exp=0.1, markers={'top': 100}, domain_celltypes=['top', 5], celltype_colors={'auto': True})

_summary_

Parameters:

  • neighbscore (_type_) – _description_

  • celltype (_type_) – _description_

  • scrna (_type_) – _description_

  • ligand_receptor_pairs (_type_) – _description_

  • ligand_target_regulatory_potential (_type_) – _description_

  • domain (_type_) – _description_

  • receptor_exp (float, optional) – _description_, defaults to 0.1

  • markers (dict, optional) – _description_, defaults to {‘top’:100}

  • domain_celltypes (list, optional) – _description_, defaults to [‘top’,5]

  • celltype_colors (dict, optional) – _description_, defaults to {‘auto’:True}

Returns:

_description_

Return type:

_type_

Renoir.downstream.sankeyPlot(neighbscore, celltype, ltpairs, n_celltype=5, clusters='All', title=None, labelsize=2, labelcolor='#000000')

Summarizes ligand-target activity across celltypes and domains using a Sankey plot for a given set of ligand-target pairs.

Parameters:

  • neighbscore (AnnData) – adata object of neighborhood scores with leiden clusters (obs column ‘leiden’ of type categorical)

  • celltype (AnnData) – adata object with celltype distributions (proportiond or abundance) across spots

  • ltpairs (list) – set of ligand-target pairs to display

  • n_celltype (int, optional) – top n highly expressed celltypes to be considered per domain, defaults to 5

  • clusters (list, optional) – list of domains to consider, defaults to ‘All’

  • title (str, optional) – Title of the sankey plot, defaults to None

  • labelsize (int, optional) – size of labels in the plot, defaults to 2

  • labelcolor (str, optional) – color of labels in the plot, defaults to ‘#000000’