spacec.plotting package

Module contents

spacec.plotting.BC_projection(adata, cnmap_dict, cn_col, plot_list, cn_col_annt=None, palette=None, figsize=(7, 7), rand_seed=1, SMALL_SIZE=14, MEDIUM_SIZE=16, BIGGER_SIZE=18, n_num=None, threshold=None, savefig=False, output_fname='', output_dir='', dpi=300)[source]

Plot barycentric projection.

Parameters:

adata (AnnData) – Annotated data object.
cnmap_dict (dict) – Dictionary containing keys ‘w’, ‘l’, ‘k’, and ‘threshold’.
cn_col (str) – Column name in adata.obs containing copy number information.
plot_list (list) – List of 3 elements from cn_col.
cn_col_annt (str, optional) – Annotated column name, by default None.
palette (dict, optional) – Color palette, by default None.
figsize (tuple, optional) – Figure size, by default (7, 7).
rand_seed (int, optional) – Random seed, by default 1.
SMALL_SIZE (int, optional) – Font size for small text, by default 14.
MEDIUM_SIZE (int, optional) – Font size for medium text, by default 16.
BIGGER_SIZE (int, optional) – Font size for large text, by default 18.
n_num (int, optional) – Number, by default None.
threshold (float, optional) – Threshold, by default None.
savefig (bool, optional) – Whether to save the figure, by default False.
output_fname (str, optional) – Output file name, by default “”.
output_dir (str, optional) – Output directory, by default “”.
dpi (int, optional) – Dots per inch, by default 300.

spacec.plotting.catplot(adata, color, unique_region, subset=None, X='x', Y='y', invert_y=False, size=6, alpha=1, palette=None, savefig=False, output_dir='./', output_fname='', figsize=5, style='white', axis='on', scatter_kws={}, n_columns=4, legend_padding=0.2, rand_seed=1)[source]

Plots cells in tissue section color coded by either cell type or node allocation.

Parameters:

adata (AnnData) – Annotated data matrix.
color (str) – Color by “Clusterid” or “Node” respectively.
unique_region (str) – Each region is one independent CODEX image.
subset (str, optional) – Subset of data to plot. If None, all data is plotted.
X (str, optional) – Column name for x-axis in the DataFrame.
Y (str, optional) – Column name for y-axis in the DataFrame.
invert_y (bool, optional) – If True, invert y-axis.
size (int, optional) – Size of point to plot for each cell.
alpha (float, optional) – Transparency of points.
palette (dict, optional) – Colors to use for different levels of the hue variable. Should be something that can be interpreted by color_palette(), or a dictionary mapping hue levels to matplotlib colors.
savefig (bool, optional) – If True, save figure.
output_dir (str, optional) – Directory to save figure.
output_fname (str, optional) – Filename to save figure.
figsize (int, optional) – Size of the figure.
style (str, optional) – Style of the plot.
axis (str, optional) – If “off”, axis is not displayed.
scatter_kws (dict, optional) – Additional keyword arguments to pass to scatterplot().
n_columns (int, optional) – Number of columns in the figure.
legend_padding (float, optional) – Padding around the legend.
rand_seed (int, optional) – Seed for random number generator.

Returns:

This function doesn’t return anything. It plots a scatterplot with the specified parameters.

Return type:

None

spacec.plotting.cn_exp_heatmap(adata, cluster_col, cn_col, palette=None, savefig=False, output_fname='', output_dir='./', row_clus=True, col_clus=True, rand_seed=1, figsize=(10, 5))[source]

Create a heatmap of expression data, clustered by rows and columns.

Parameters:

adata (AnnData) – Annotated data matrix.
cluster_col (str) – The column name for clustering the data.
cn_col (str) – The column name for the color selection.
palette (dict, optional) – A dictionary to manually set colors for neighborhoods. Defaults to None.
figsize (tuple, optional) – The size of the figure. Defaults to (18, 12).
savefig (bool, optional) – Whether to save the figure or not. Defaults to False.
output_fname (str, optional) – The output file name. Defaults to “”.
output_dir (str, optional) – The output directory. Defaults to “./”.
row_clus (bool, optional) – Whether to cluster the rows or not. Defaults to True.
col_clus (bool, optional) – Whether to cluster the columns or not. Defaults to True.
rand_seed (int, optional) – The random seed for color generation. Defaults to 1.

Return type:

None

spacec.plotting.cn_map(adata, cnmap_dict, cn_col, palette=None, figsize=(40, 20), savefig=False, output_fname='', output_dir='./', rand_seed=1)[source]

Generates a CNMap plot using the provided data and parameters.

Parameters:

adata (anndata.AnnData) – Annotated data matrix.
cnmap_dict (dict) – Dictionary containing graph, tops, e0, e1, and simp_freqs.
cn_col (str) – Column name in adata to be used for color coding.
palette (dict, optional) – Color palette to use for the plot. If None, a random color palette is generated.
figsize (tuple, optional) – Size of the figure. Defaults to (40, 20).
savefig (bool, optional) – Whether to save the figure or not. Defaults to False.
output_fname (str, optional) – The filename for the saved figure. Required if savefig is True. Defaults to “”.
output_dir (str, optional) – The directory where the figure will be saved. Defaults to “./”.
rand_seed (int, optional) – Seed for random number generator. Defaults to 1.

Return type:

None

spacec.plotting.coordinates_on_image(df, overlay_data, color=None, x='x', y='y', fig_width=20, fig_height=20, dot_size=10, convert_to_grey=True, scale=False, cmap='inferno', savefig=False, output_dir='./', output_fname='')[source]

Plot coordinates on an image.

Parameters:

df (pd.DataFrame) – The input DataFrame. The DataFrame should have columns ‘x’ and ‘y’ representing the coordinates.
overlay_data (ndarray) – The image data to overlay the coordinates on.
color (str, optional) – The column name in df for the color variable. Defaults to None.
x (str, optional) – The column name in df for the x-coordinate. Defaults to “x”.
y (str, optional) – The column name in df for the y-coordinate. Defaults to “y”.
fig_width (int, optional) – The width of the figure. Defaults to 20.
fig_height (int, optional) – The height of the figure. Defaults to 20.
dot_size (int, optional) – The size of the dots representing the coordinates. Defaults to 10.
convert_to_grey (bool, optional) – Whether to convert the image to grayscale. Defaults to True.
scale (bool, optional) – Whether to scale the color variable. Defaults to False.
cmap (str, optional) – The colormap to use. Defaults to “inferno”.
savefig (bool, optional) – Whether to save the figure or not. Defaults to False.
output_dir (str, optional) – The output directory. Defaults to “./”.
output_fname (str, optional) – The output file name. Defaults to “”.

Return type:

None

spacec.plotting.count_patch_proximity_res(adata, x, hue, palette='Set3', order=True, key_name='ppa_result', savefig=False, output_dir='./', output_fname='')[source]

Create a count plot for patch proximity results.

Parameters:

adata (AnnData) – Annotated data matrix.
x (str) – The column name in the DataFrame for the x-axis variable.
hue (str) – The column name in the DataFrame for the hue variable.
palette (str, optional) – The palette to use for the plot. Defaults to “Set3”.
order (bool, optional) – Whether to order the count plot. Defaults to True.
key_name (str, optional) – The key name for the patch proximity results in adata.uns. Defaults to “ppa_result”.
savefig (bool, optional) – Whether to save the figure or not. Defaults to False.
output_dir (str, optional) – The output directory. Defaults to “./”.
output_fname (str, optional) – The output file name. Defaults to “”.

Return type:

None

spacec.plotting.create_pie_charts(adata, color, grouping, plot_order=None, show_percentages=True, palette=None, savefig=False, output_fname='', output_dir='./', rand_seed=1)[source]

Create pie charts for each group based on a grouping column, showing the percentage of total rows based on a count column.

Parameters:

adata (pd.DataFrame) – The input DataFrame.
color (str) – The column name used for counting occurrences.
grouping (str) – The column name for grouping the data.
plot_order (list, optional) – The order of groups for plotting. Defaults to None.
show_percentages (bool, optional) – Whether to show the percentage numbers on the pie charts. Defaults to True.
palette (dict, optional) – A dictionary to manually set colors for neighborhoods. Defaults to None.
savefig (bool, optional) – Whether to save the figure or not. Defaults to False.
output_fname (str, optional) – The output file name. Defaults to “”.
output_dir (str, optional) – The output directory. Defaults to “./”.
rand_seed (int, optional) – The random seed for color generation. Defaults to 1.

Return type:

None

spacec.plotting.distance_graph(dist_table, distance_pvals, palette=None, condition_pair=None, interaction_col='interaction', condition_col='condition', logfold_group_col='logfold_group', celltype1_col='celltype1', celltype2_col='celltype2', pair_col='pairs', with_labels=True, node_size=910, font_size=7, multiplication_factor=10, savefig=False, output_fname='', output_dir='', dpi=300, color_seed=0)[source]

Generates a distance graph from a dataframe.

Parameters: df (DataFrame): The input dataframe. palette (dict, optional): A dictionary mapping nodes to colors. If None, nodes are colored ‘lightgrey’. condition_pair (list, optional): A list of two conditions to compare. If None, uses unique conditions from the dataframe. interaction_col (str, optional): The name of the interaction column in the dataframe. Defaults to ‘interaction’. condition_col (str, optional): The name of the condition column in the dataframe. Defaults to ‘condition’. logfold_group_col (str, optional): The name of the logfold group column in the dataframe. Defaults to ‘logfold_group’. celltype1_col (str, optional): The name of the first cell type column in the dataframe. Defaults to ‘celltype1’. celltype2_col (str, optional): The name of the second cell type column in the dataframe. Defaults to ‘celltype2’. with_labels (bool, optional): Whether to draw labels on the nodes. Defaults to True. node_size (int, optional): The size of the nodes. Defaults to 910. font_size (int, optional): The font size for the labels. Defaults to 7.

Returns: None: The function generates a plot and does not return anything.

spacec.plotting.dumbbell(data, figsize=(10, 10), colors=['#DB444B', '#006BA2'], savefig=False, output_fname='', output_dir='./')[source]

Create a dumbbell plot.

Parameters:

data (pd.DataFrame) – The input DataFrame. The DataFrame should have two columns representing two different conditions.
figsize (tuple, optional) – The size of the figure. Defaults to (10, 10).
colors (list, optional) – The colors to use for the two conditions. Defaults to [“#DB444B”, “#006BA2”].

Return type:

None

spacec.plotting.plot_top_n_distances(dist_table_filt, dist_data_filt, n=5, colors=None, dodge=False, savefig=False, output_fname='', output_dir='./', figsize=(5, 5), unit='px', errorbars=True)[source]

spacec.plotting.ppa_res_donut(adata, cat_col, key_name='ppa_result', palette=None, distance_mode='within', unit='µm', figsize=(10, 10), add_guides=True, text='example CN', label_color='black', rand_seed=1, subset_column=None, subset_condition=None, group_by=None, title='Title', savefig=False, output_fname='', output_dir='./')[source]

Plot donut chart of cell type proportions at different distances. Generates a multi-ring donut chart where each ring represents a specific distance range from the patches. The segments within each ring show the proportion of different categories (e.g., cell types) found within that distance range. The function can operate in two modes: ‘within’ (cumulative proportions up to a distance) or ‘between’ (proportions within discrete distance intervals). It also supports subsetting the data and generating separate plots for different groups. :param adata: Annotated data object containing the results in adata.uns.

Column name in the results DataFrame (accessed via key_name) that contains the categorical data to plot (e.g., ‘cell_type’).

Parameters:

key_name (str, optional) – Key in adata.uns where the DataFrame containing distance information (specifically ‘distance_from_patch’ column) is stored. Defaults to “ppa_result”.
palette (dict or None, optional) – A dictionary mapping category names (from cat_col) to colors. If None, colors are automatically generated using tab20 colormap and stored in adata.uns[cat_col + ‘_colors’]. Defaults to None.
distance_mode ({'within', 'between'}, optional) –
Determines how proportions are calculated for each distance ring: - “within”: Includes all cells up to the specified distance. Rings

represent cumulative proportions.
- ”between”: Includes only cells between the current distance ring’s outer radius and the previous ring’s outer radius. Rings represent proportions in discrete intervals.
Defaults to “within”.
unit (str, optional) – Unit for distance labels displayed on the plot (e.g., ‘µm’, ‘px’). Defaults to “µm”.
figsize (tuple, optional) – Size of the figure (width, height) in inches. Defaults to (10, 10).
add_guides (bool, optional) – Whether to add radial and circular guide lines to the plot background. Defaults to True.
text (str, optional) – Text to display in the center of the donut chart. Defaults to “example CN”.
label_color (str, optional) – Color of the distance labels placed on the rings. Defaults to “black”.
rand_seed (int, optional) – Random seed used for reproducible color generation if palette is None. Defaults to 1.
subset_column (str or None, optional) – Column name in the results DataFrame to use for subsetting the data before plotting. If None, no subsetting is performed based on this. Defaults to None.
subset_condition (str or None, optional) – Value within subset_column to filter the data by. Only data points where subset_column equals subset_condition will be used. Requires subset_column to be set. Defaults to None.
group_by (str or None, optional) – Column name in the results DataFrame to group the data by. If provided, a separate donut chart will be generated for each unique value in this column. The function calls itself recursively for each group. Defaults to None.
title (str, optional) – Main title for the plot. If group_by is used, the group identifier will be appended to this title for each subplot. Defaults to “Title”.
savefig (bool, optional) – Whether to save the generated figure(s) to disk. If False, displays the plot instead. Defaults to False.
output_fname (str, optional) – Base filename for the saved plot (without extension). If group_by is used, the group identifier will be appended. Defaults to “”.
output_dir (str, optional) – Directory where the plot(s) will be saved if savefig is True. Defaults to “./”.

Returns:

If group_by is None, returns the single matplotlib Figure object for the plot. If group_by is provided, returns a dictionary where keys are the unique values from the group_by column and values are the corresponding matplotlib Figure objects.

Return type:

matplotlib.figure.Figure or dict

Raises:

ValueError – If key_name is not found in adata.uns. If the DataFrame accessed by key_name is empty. If the ‘distance_from_patch’ column is missing in the DataFrame. If cat_col is missing in the DataFrame. If subset_column is provided but missing in the DataFrame. If subset_condition is provided but not found within subset_column. If group_by column is missing in the DataFrame. If no distance values are found in the ‘distance_from_patch’ column. If distance_mode is not ‘within’ or ‘between’. If a category found in the data is missing from the provided palette.

Notes

The function assumes the results DataFrame stored in adata.uns[key_name] contains at least the columns specified by cat_col and ‘distance_from_patch’.
When group_by is used, the function makes recursive calls to itself, passing the subsetted data for each group. The subset_column and subset_condition parameters within the recursive call are used to filter for the specific group, and group_by is set to None to prevent infinite recursion.
The radii of the donut rings increase linearly with the sorted unique distance values. The innermost ring corresponds to the smallest distance, and the outermost ring corresponds to the largest distance.

spacec.plotting.segmentation_ch(file_name, channel_file, output_dir, savefig=False, output_fname='', extra_seg_ch_list=None, nuclei_channel='DAPI', input_format='Multichannel')[source]

Plot the channel selected for segmentation.

Parameters:

file_name (str) – The path to the image file for segmentation.
channel_file (str) – The path to the file containing all channels used for staining.
output_dir (str) – The directory to save the output in.
savefig (bool, optional) – Whether to save the figure, by default False.
output_fname (str, optional) – The filename for the saved figure, by default “”.
extra_seg_ch_list (list, optional) – The channels used for membrane segmentation, by default None.
nuclei_channel (str, optional) – The channel used for nuclei, by default “DAPI”.
input_format (str, optional) – The input_format used (either “CODEX”, “Multichannel” or “Channels”), by default “Multichannel”.

Return type:

None

spacec.plotting.show_masks(seg_output, nucleus_channel, additional_channels=None, show_subsample=True, n=2, tilesize=100, idx=0, rand_seed=1)[source]

Visualize the segmentation results of an image.

Parameters:

seg_output (dict) – The output from the segmentation process. It should contain ‘image_dict’ and ‘masks’.
nucleus_channel (str) – The name of the nucleus channel in the image_dict.
additional_channels (list of str, optional) – The names of additional channels to be combined with the nucleus channel for visualization.
show_subsample (bool, optional) – Whether to show a subsample of the image. Default is True.
n (int, optional) – The number of subsamples to show. Default is 2.
tilesize (int, optional) – The size of the tiles for subsampling. Default is 100.
idx (int, optional) – The index for displaying. Default is 0.
rand_seed (int, optional) – The seed for the random number generator. Default is 1.

Returns:

overlay_data (ndarray) – The overlay of the segmentation results on the RGB images.
rgb_images (ndarray) – The RGB images.

Raises:

ValueError – If the image size is smaller than the tile size or if there are not enough tiles to display.

spacec.plotting.stacked_bar_plot(adata, color, grouping, cell_list, output_dir, norm=True, savefig=False, output_fname='', col_order=None, sub_col=None, name_cat='celltype', fig_sizing=(8, 4), plot_order=None, palette=None, remove_leg=False, rand_seed=1)[source]

Plot a stacked bar plot based on the given data.

Parameters:

data (pandas.DataFrame) – The input data containing the necessary information for plotting.
color (str) – The column name representing the categories.
grouping (str) – The column name representing the grouping.
cell_list (list) – The list of cell types to include in the plot.
output_dir (str) – The output directory for saving the plot.
norm (bool, optional) – Flag indicating whether to normalize the values. Defaults to True.
save_name (str, optional) – The name to use when saving the plot. Defaults to None.
col_order (list, optional) – The order of columns/categories for plotting. Defaults to None.
sub_col (str, optional) – The column name representing sub-categories. Defaults to None.
name_cat (str, optional) – The name for the category column in the plot. Defaults to ‘celltype’.
fig_sizing (tuple, optional) – The size of the figure (width, height) in inches. Defaults to (8, 4).
plot_order (list, optional) – The order of categories for plotting. Defaults to None.
palette (dict, optional) – A dictionary mapping categories to colors for custom colorization. Defaults to None.
remove_leg (bool, optional) – Flag indicating whether to remove the legend. Defaults to False.

Returns:

pandas.DataFrame – The pivoted data used for plotting.
list – The order of categories used for plotting.

spacec.plotting.tissue_lables(tissueframe, region='region1')[source]

Plot the tissue and region labels of the given DataFrame.

Parameters:

tissueframe (DataFrame) – The DataFrame containing the labels from the segmentation.
region (str, optional) – The region to group by, by default “region1”.

Return type:

None

spacec.plotting.zcount_thres(dfz, col_num, cut_off=0.01, count_bin=50, zsum_bin=50, figsize=(10, 5))[source]

Determines the threshold to use for removing noises. The default cut off is the top 1%.

Parameters:

dfz (DataFrame) – The input data from which the threshold is to be determined.
col_num (int) – The column number up to which the operation is performed.
cut_off (float, optional) – The cut off percentage for the threshold. By default, it is 0.01 (1%).
count_bin (int, optional) – The number of bins for the count histogram. By default, it is 50.
zsum_bin (int, optional) – The number of bins for the z-score sum histogram. By default, it is 50.
figsize (tuple, optional) – The size of the figure to be plotted. By default, it is (10, 5).

Returns:

This function doesn’t return anything. It plots two histograms for ‘Count’ and ‘Zscore sum’ with the cut off line.

Return type:

None