API reference

This page documents the public objects exported by easydecon.__all__. Private helpers and implementation modules are intentionally omitted.

Version

easydecon.__version__ = '0.1.6a0'

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

Core workflow

easydecon.run_easydecon(sdata, markers_df=None, prepared_markers=None, marker_genes=None, filename=None, adata=None, mask_col='easydecon_mask', celltype='group', gene_id_column='names', exclude_group_names=None, bin_size=8, marker_method='auto', groupby=None, sample_col=None, marker_key='rank_genes_groups', top_n_genes=60, sort_by_column='scores', ascending=False, log2fc_min=0.25, pval_cutoff=0.05, drop_ribosomal=True, drop_mitochondrial=True, table_key=None, preferred_table_keys=None, marker_source=None, scanpy_method='wilcoxon', layer=None, use_raw=None, reference='rest', copy_adata=True, rank_genes_groups_kwargs=None, min_cells_per_group=20, min_replicates_per_condition=2, deseq_alpha=0.05, deseq_n_cpus=None, deseq_quiet=True, deseq_kwargs=None, deseq_stats_kwargs=None, reference_min_cells=25, reference_min_mean=0.0002, reference_min_log2fc=1.0, reference_min_detection=0.1, reference_min_detection_delta=0.05, reference_pseudocount=1e-09, reference_contrast='max_other', marker_roles='shared', reference_presence_min_log2fc=0.5, reference_presence_min_detection_delta=0.0, reference_negative_min_log2fc=1.0, reference_negative_min_detection=0.1, reference_negative_min_detection_delta=0.05, marker_role_inference='none', verbose=True, return_result_object=False, return_diagnostics=False, aggregation_method='sum', filtering_algorithm='permutation', num_permutations=5000, parametric=True, alpha=0.01, subsample_size=25000, subsample_signal_quantile=0, permutation_gene_pool_fraction=0.3, n_subs=5, quantile=0.7, phase1_output_stat='expression', method='wjaccard', similarity_by_column='logfoldchanges', lambda_param=0.25, weight_column='logfoldchanges', min_markers=3, fallback_auc=0.0, expression_threshold=0.1, top_n_markers=None, recovery_power=1.0, drop_shared_markers=False, center_auc=True, ucell_max_rank=None, ucell_negative_weight=1.0, ucell_marker_role_column='marker_role', evidence_to_likelihood='softmax', softmax_tau=1.0, epsilon=1e-12, prior_weight=1.0, likelihood_weight=1.0, apply_prior_presence_mask=False, prior_presence_threshold=0.0, phase2_candidate_pruning=False, phase2_candidate_threshold=0.0, results_column='easydecon', assign_method='max', allow_multiple=False, diagnostic=None, fold_change_threshold=2.0, minimum_evidence=0.0, tie_tolerance=1e-12)

Parameters:

• celltype (str)

• gene_id_column (str)

• exclude_group_names (list[str] | None)

• bin_size (int)

• marker_method (str)

• groupby (str | None)

• sample_col (str | None)

• marker_key (str)

• top_n_genes (int)

• sort_by_column (str)

• ascending (bool)

• log2fc_min (float)

• pval_cutoff (float)

• drop_ribosomal (bool)

• drop_mitochondrial (bool)

• scanpy_method (str)

• reference (str)

• copy_adata (bool)

• min_cells_per_group (int)

• min_replicates_per_condition (int)

• deseq_alpha (float)

• deseq_quiet (bool)

• reference_min_cells (int)

• reference_min_mean (float)

• reference_min_log2fc (float)

• reference_min_detection (float)

• reference_min_detection_delta (float)

• reference_pseudocount (float)

• reference_contrast (str)

• marker_roles (str)

• reference_presence_min_log2fc (float)

• reference_presence_min_detection_delta (float)

• reference_negative_min_log2fc (float)

• reference_negative_min_detection (float)

• reference_negative_min_detection_delta (float)

• marker_role_inference (str)

• verbose (bool)

• return_result_object (bool)

• return_diagnostics (bool)

• aggregation_method (str)

• filtering_algorithm (str)

• num_permutations (int)

• parametric (bool)

• alpha (float)

• subsample_size (int)

• subsample_signal_quantile (float)

• permutation_gene_pool_fraction (float)

• n_subs (int)

• quantile (float)

• phase1_output_stat (str)

• method (str)

• similarity_by_column (str)

• lambda_param (float)

• weight_column (str)

• min_markers (int)

• fallback_auc (float)

• expression_threshold (float)

• top_n_markers (int | None)

• recovery_power (float)

• drop_shared_markers (bool)

• center_auc (bool)

• ucell_max_rank (int | None)

• ucell_negative_weight (float)

• ucell_marker_role_column (str)

• evidence_to_likelihood (str)

• softmax_tau (float)

• epsilon (float)

• prior_weight (float)

• likelihood_weight (float)

• apply_prior_presence_mask (bool)

• prior_presence_threshold (float)

• phase2_candidate_pruning (bool)

• phase2_candidate_threshold (float)

• results_column (str)

• assign_method (str)

• allow_multiple (bool)

• fold_change_threshold (float)

• minimum_evidence (float)

• tie_tolerance (float)

easydecon.easydecon_workflow(sdata, markers_df=None, prepared_markers=None, marker_genes=None, filename=None, adata=None, mask_col='easydecon_mask', celltype='group', gene_id_column='names', exclude_group_names=None, bin_size=8, marker_method='auto', groupby=None, sample_col=None, marker_key='rank_genes_groups', top_n_genes=60, sort_by_column='scores', ascending=False, log2fc_min=0.25, pval_cutoff=0.05, drop_ribosomal=True, drop_mitochondrial=True, table_key=None, preferred_table_keys=None, marker_source=None, scanpy_method='wilcoxon', layer=None, use_raw=None, reference='rest', copy_adata=True, rank_genes_groups_kwargs=None, min_cells_per_group=20, min_replicates_per_condition=2, deseq_alpha=0.05, deseq_n_cpus=None, deseq_quiet=True, deseq_kwargs=None, deseq_stats_kwargs=None, reference_min_cells=25, reference_min_mean=0.0002, reference_min_log2fc=1.0, reference_min_detection=0.1, reference_min_detection_delta=0.05, reference_pseudocount=1e-09, reference_contrast='max_other', marker_roles='shared', reference_presence_min_log2fc=0.5, reference_presence_min_detection_delta=0.0, reference_negative_min_log2fc=1.0, reference_negative_min_detection=0.1, reference_negative_min_detection_delta=0.05, marker_role_inference='none', verbose=True, return_result_object=False, return_diagnostics=False, aggregation_method='sum', filtering_algorithm='permutation', num_permutations=5000, parametric=True, alpha=0.01, subsample_size=25000, subsample_signal_quantile=0, permutation_gene_pool_fraction=0.3, n_subs=5, quantile=0.7, phase1_output_stat='expression', method='wjaccard', similarity_by_column='logfoldchanges', lambda_param=0.25, weight_column='logfoldchanges', min_markers=3, fallback_auc=0.0, expression_threshold=0.1, top_n_markers=None, recovery_power=1.0, drop_shared_markers=False, center_auc=True, ucell_max_rank=None, ucell_negative_weight=1.0, ucell_marker_role_column='marker_role', evidence_to_likelihood='softmax', softmax_tau=1.0, epsilon=1e-12, prior_weight=1.0, likelihood_weight=1.0, apply_prior_presence_mask=False, prior_presence_threshold=0.0, phase2_candidate_pruning=False, phase2_candidate_threshold=0.0, results_column='easydecon', assign_method='max', allow_multiple=False, diagnostic=None, fold_change_threshold=2.0, minimum_evidence=0.0, tie_tolerance=1e-12)

Parameters:

• celltype (str)

• gene_id_column (str)

• exclude_group_names (list[str] | None)

• bin_size (int)

• marker_method (str)

• groupby (str | None)

• sample_col (str | None)

• marker_key (str)

• top_n_genes (int)

• sort_by_column (str)

• ascending (bool)

• log2fc_min (float)

• pval_cutoff (float)

• drop_ribosomal (bool)

• drop_mitochondrial (bool)

• scanpy_method (str)

• reference (str)

• copy_adata (bool)

• min_cells_per_group (int)

• min_replicates_per_condition (int)

• deseq_alpha (float)

• deseq_quiet (bool)

• reference_min_cells (int)

• reference_min_mean (float)

• reference_min_log2fc (float)

• reference_min_detection (float)

• reference_min_detection_delta (float)

• reference_pseudocount (float)

• reference_contrast (str)

• marker_roles (str)

• reference_presence_min_log2fc (float)

• reference_presence_min_detection_delta (float)

• reference_negative_min_log2fc (float)

• reference_negative_min_detection (float)

• reference_negative_min_detection_delta (float)

• marker_role_inference (str)

• verbose (bool)

• return_result_object (bool)

• return_diagnostics (bool)

• aggregation_method (str)

• filtering_algorithm (str)

• num_permutations (int)

• parametric (bool)

• alpha (float)

• subsample_size (int)

• subsample_signal_quantile (float)

• permutation_gene_pool_fraction (float)

• n_subs (int)

• quantile (float)

• phase1_output_stat (str)

• method (str)

• similarity_by_column (str)

• lambda_param (float)

• weight_column (str)

• min_markers (int)

• fallback_auc (float)

• expression_threshold (float)

• top_n_markers (int | None)

• recovery_power (float)

• drop_shared_markers (bool)

• center_auc (bool)

• ucell_max_rank (int | None)

• ucell_negative_weight (float)

• ucell_marker_role_column (str)

• evidence_to_likelihood (str)

• softmax_tau (float)

• epsilon (float)

• prior_weight (float)

• likelihood_weight (float)

• apply_prior_presence_mask (bool)

• prior_presence_threshold (float)

• phase2_candidate_pruning (bool)

• phase2_candidate_threshold (float)

• results_column (str)

• assign_method (str)

• allow_multiple (bool)

• fold_change_threshold (float)

• minimum_evidence (float)

• tie_tolerance (float)

class easydecon.EasyDeconResult(markers_df: pandas.core.frame.DataFrame, phase1_result: pandas.core.frame.DataFrame, phase2_result: pandas.core.frame.DataFrame, assigned_labels: pandas.core.frame.DataFrame, priors_df: pandas.core.frame.DataFrame, likelihoods_df: pandas.core.frame.DataFrame, posterior_df: pandas.core.frame.DataFrame | None, assignment_df: pandas.core.frame.DataFrame, diagnostics: dict, prepared_markers: easydecon.markers.PreparedMarkers | None = None)

Parameters:

• markers_df (DataFrame)

• phase1_result (DataFrame)

• phase2_result (DataFrame)

• assigned_labels (DataFrame)

• priors_df (DataFrame)

• likelihoods_df (DataFrame)

• posterior_df (DataFrame | None)

• assignment_df (DataFrame)

• diagnostics (dict)

• prepared_markers (PreparedMarkers | None)

Marker loading and preparation

prepare_markers owns source loading, marker generation, alias resolution, canonical preparation, and optional source-level role inference. It returns a spatial-unfiltered PreparedMarkers object. select_prepared_markers owns spatial-specific marker selection. resolve_phase_marker_tables is an internal workflow helper for Phase 1/Phase 2 routing and workflow top-N selection. read_markers_dataframe remains a supported backward-compatible convenience wrapper that returns a selected DataFrame.

easydecon.read_markers_dataframe(sdata, filename=None, adata=None, exclude_celltype=None, bin_size=8, top_n_genes=60, sort_by_column='scores', ascending=False, gene_id_column='names', celltype='group', key='rank_genes_groups', log2fc_min=0.25, pval_cutoff=0.05, drop_ribosomal=False, drop_mitochondrial=False, markers_df=None, prepared_markers=None, table_key=None, preferred_table_keys=None, source=None, return_diagnostics=False, verbose=True, marker_method='auto', groupby=None, scanpy_method='wilcoxon', layer=None, use_raw=None, reference='rest', copy_adata=True, rank_genes_groups_kwargs=None, sample_col=None, min_cells_per_group=20, min_replicates_per_condition=2, deseq_alpha=0.05, deseq_n_cpus=None, deseq_quiet=True, deseq_kwargs=None, deseq_stats_kwargs=None, reference_min_cells=25, reference_min_mean=0.0002, reference_min_log2fc=1.0, reference_min_detection=0.1, reference_min_detection_delta=0.05, reference_pseudocount=1e-09, reference_contrast='max_other', marker_roles='shared', reference_presence_min_log2fc=0.5, reference_presence_min_detection_delta=0.0, reference_negative_min_log2fc=1.0, reference_negative_min_detection=0.1, reference_negative_min_detection_delta=0.05, marker_role_inference='none')

Compatibility wrapper returning a spatial-selected marker DataFrame.

Parameters:

• marker_roles (str)

• reference_presence_min_log2fc (float)

• reference_presence_min_detection_delta (float)

• reference_negative_min_log2fc (float)

• reference_negative_min_detection (float)

• reference_negative_min_detection_delta (float)

• marker_role_inference (str)

easydecon.prepare_markers(adata=None, marker_method='auto', *, prepared_markers=None, markers_df=None, filename=None, source=None, celltype='group', gene_id_column='names', groupby=None, marker_key='rank_genes_groups', scanpy_method='wilcoxon', layer=None, use_raw=None, reference='rest', copy_adata=True, rank_genes_groups_kwargs=None, sample_col=None, min_cells_per_group=20, min_replicates_per_condition=2, deseq_alpha=0.05, deseq_n_cpus=None, deseq_quiet=True, deseq_kwargs=None, deseq_stats_kwargs=None, reference_min_cells=25, reference_min_mean=0.0002, reference_min_log2fc=1.0, reference_min_detection=0.1, reference_min_detection_delta=0.05, reference_pseudocount=1e-09, reference_contrast='max_other', marker_roles='shared', reference_presence_min_log2fc=0.5, reference_presence_min_detection_delta=0.0, reference_negative_min_log2fc=1.0, reference_negative_min_detection=0.1, reference_negative_min_detection_delta=0.05, marker_role_inference='none', marker_role_inference_log2fc_min=0.25, verbose=True)

Load, generate, or reuse a spatial-unfiltered marker preparation.

Parameters:

• celltype (str)

• gene_id_column (str)

• reference_min_cells (int)

• reference_min_mean (float)

• reference_min_log2fc (float)

• reference_min_detection (float)

• reference_min_detection_delta (float)

• reference_pseudocount (float)

• reference_contrast (str)

• marker_roles (str)

• reference_presence_min_log2fc (float)

• reference_presence_min_detection_delta (float)

• reference_negative_min_log2fc (float)

• reference_negative_min_detection (float)

• reference_negative_min_detection_delta (float)

• marker_role_inference (str)

• marker_role_inference_log2fc_min (float)

Return type:

PreparedMarkers

easydecon.select_prepared_markers(prepared, gene_universe, exclude_celltype=None, top_n_genes=60, sort_by_column='scores', ascending=False, log2fc_min=0.25, pval_cutoff=0.05, drop_ribosomal=False, drop_mitochondrial=False, source=None, return_diagnostics=False)

Select spatial-specific markers from a reusable marker preparation.

Return type:

DataFrame

easydecon.compute_reference_profile_markers(adata, groupby, layer=None, min_cells_per_group=25, min_mean_expression=0.0002, min_log2fc=1.0, min_detection=0.1, min_detection_delta=0.05, contrast='max_other', top_n_genes=None, pseudocount=1e-09, drop_ribosomal=False, drop_mitochondrial=False, marker_roles='shared', reference_presence_min_log2fc=0.5, reference_presence_min_detection_delta=0.0, reference_negative_min_log2fc=1.0, reference_negative_min_detection=0.1, reference_negative_min_detection_delta=0.05)

Select marker genes from library-size-normalized reference profiles.

Parameters:

• marker_roles (str)

• reference_presence_min_log2fc (float)

• reference_presence_min_detection_delta (float)

• reference_negative_min_log2fc (float)

• reference_negative_min_detection (float)

• reference_negative_min_detection_delta (float)

Return type:

tuple[DataFrame, dict]

easydecon.compute_pseudobulk_deseq_markers(adata, groupby, sample_col, layer='counts', min_cells_per_group=20, min_replicates_per_condition=2, alpha=0.05, n_cpus=None, quiet=True, deseq_kwargs=None, deseq_stats_kwargs=None)

Generate one-vs-rest pseudobulk marker tables with PyDESeq2.

class easydecon.PreparedMarkers(raw_markers_df: 'pd.DataFrame', marker_method: 'str', source: 'str', parameters: 'dict' = <factory>, diagnostics: 'dict' = <factory>, signature: 'str' = '')

Parameters:

• raw_markers_df (DataFrame)

• marker_method (str)

• source (str)

• parameters (dict)

• diagnostics (dict)

• signature (str)

Phase functions and assignment

easydecon.common_markers_gene_expression_and_filter(sdata, marker_genes, common_group_name='MarkerGroup', celltype='group', gene_id_column='names', exclude_group_names=None, bin_size=8, aggregation_method='sum', add_to_obs=True, filtering_algorithm='permutation', num_permutations=5000, alpha=0.01, subsample_size=25000, subsample_signal_quantile=0.1, permutation_gene_pool_fraction=0.3, parametric=True, n_subs=5, quantile=0.7, output_stat='expression', verbose=True, **kwargs)

Compute Phase 1 marker-expression evidence.

marker_genes may be a list, a mapping from group to genes, or a marker DataFrame. Expression is aggregated for each marker group and filtered with the selected algorithm.

Parameters:

• sdata (object) – SpatialData-like container or AnnData-like table.

• marker_genes – List of genes, mapping from group to genes, or marker DataFrame.

• common_group_name (str) – Group name used when marker_genes is a list.

• celltype (str) – Marker DataFrame columns for group and gene names.

• gene_id_column (str) – Marker DataFrame columns for group and gene names.

• exclude_group_names (list[str] | None) – Groups whose nonzero rows should be excluded from Phase 1 evidence.

• bin_size (int) – Bin size used when resolving a SpatialData table.

• aggregation_method (str) – One of "sum", "mean", "median", or "cs".

• add_to_obs (bool) – Whether to merge Phase 1 columns into table.obs.

• filtering_algorithm (str) – One of "permutation", "quantile", or "nb".

• output_stat (str) – "expression" or "minus_log10_p". The latter is invalid with quantile filtering.

• **kwargs – Additional method-specific options, including nb_global_theta for NB filtering.

• num_permutations (int)

• alpha (float)

• subsample_size (int)

• subsample_signal_quantile (float)

• permutation_gene_pool_fraction (float)

• parametric (bool)

• n_subs (int)

• quantile (float)

• verbose (bool)

Returns:

Thresholded Phase 1 evidence with spatial locations as rows and marker groups as columns.

Return type:

pd.DataFrame

easydecon.get_clusters_by_similarity_on_tissue(sdata, markers_df, common_group_name=None, bin_size=8, gene_id_column='names', celltype='group', method='wjaccard', add_to_obs=False, verbose=True, _diagnostics_out=None, _candidate_mask=None, **kwargs)

Compute Phase 2 marker-profile evidence with a chosen method.

Parameters:

• sdata (AnnData-like object) – Spatial (or single-cell) data containing expression matrices. It is expected to have ‘tables’ attribute with keys like “square_00Xum”, or simply be treated as a table if the key doesn’t exist.

• markers_df (pd.DataFrame) – DataFrame containing marker genes for each cluster. Rows typically represent clusters, columns represent information about each gene (e.g., logfoldchanges, names, etc.).

• common_group_name (str, optional) – Name of a column in table.obs specifying spots to process. If found, only spots where common_group_name != 0 are processed. Otherwise, all spots are processed. Default is None.

• bin_size (int, optional) – Determines the bin size (like “square_008um”) for looking up the table in sdata.tables. Default is 8.

• gene_id_column (str, optional) – Name of the column in markers_df that contains gene IDs. Default is “names”.

• celltype (str, optional) – Column in markers_df containing cluster/cell type labels when the DataFrame index is not already grouped by cell type.

• similarity_by_column (str, optional) – Column in markers_df used to measure similarity or weight. Default is “logfoldchanges”.

• method (str, optional) – One of "correlation", "cosine", "jaccard", "overlap", "wjaccard", "diagnostic", "sum", "mean", "median", "euclidean", "auc", or "ucell". Default is "wjaccard".

• add_to_obs (bool, optional) – If True, adds the resulting assignment columns to table.obs. Default is False.

• **method_kwargs – Additional, method-specific parameters. For example: - For method=”wjaccard”: supply lambda_param, etc.

Returns:

A DataFrame whose index matches table.obs.index with cluster assignment columns (or other metrics) computed by the specified method.

Return type:

pd.DataFrame

easydecon.assign_clusters_from_df(sdata, df, bin_size=8, results_column='easydecon', method='max', allow_multiple=False, diagnostic=None, fold_change_threshold=2.0, minimum_evidence=0.0, tie_tolerance=1e-12, add_to_obs=True, verbose=True)

Convert a score matrix into hard assignments.

Parameters:

• sdata – SpatialData-like container or AnnData-like table.

• df – Score matrix with spatial locations as rows and marker groups as columns.

• bin_size – Bin size used when resolving a SpatialData table.

• results_column – Column name for the primary assignment.

• method – One of "max", "zmax", or "hybrid".

• allow_multiple – Multiple assignments are supported only with method="hybrid".

• fold_change_threshold – Hybrid assignment threshold comparing top and second adaptive probabilities.

• minimum_evidence – Minimum score required before a row can receive a hard assignment.

• tie_tolerance – Tolerance used to leave near-tied winners unassigned.

• add_to_obs – If True, merge assignment columns into table.obs.

Returns:

Assignment labels aligned to table.obs.index.

Return type:

pandas.DataFrame

Refinement

easydecon.refine_group(sdata, parent_result, parent_group, markers_df=None, prepared_markers=None, filename=None, adata=None, mode='phase2', parent_source='priors', parent_threshold=0.0, results_column=None, bin_size=8, table_key=None, preferred_table_keys=None, marker_roles='shared', reference_presence_min_log2fc=0.5, reference_presence_min_detection_delta=0.0, reference_negative_min_log2fc=1.0, reference_negative_min_detection=0.1, reference_negative_min_detection_delta=0.05, evidence_to_likelihood='softmax', softmax_tau=1.0, assign_method='max', allow_multiple=False, fold_change_threshold=2.0, minimum_evidence=0.0, tie_tolerance=1e-12, phase2_candidate_pruning=False, phase2_candidate_threshold=0.0, marker_role_inference='none', verbose=True, **workflow_kwargs)

Refine one broad parent group into marker-defined subclusters.

Parameters:

• reference_presence_min_log2fc (float)

• reference_presence_min_detection_delta (float)

• reference_negative_min_log2fc (float)

• reference_negative_min_detection (float)

• reference_negative_min_detection_delta (float)

• phase2_candidate_pruning (bool)

• phase2_candidate_threshold (float)

• marker_role_inference (str)

Return type:

RefinedGroupResult

class easydecon.RefinedGroupResult(parent_group: 'str', mode: 'str', parent_scores: 'pd.Series', eligible_mask: 'pd.Series', conditional_df: 'pd.DataFrame', absolute_df: 'pd.DataFrame', assigned_labels: 'pd.DataFrame', phase2_result: 'pd.DataFrame', child_result: 'EasyDeconResult | None', diagnostics: 'dict')

Parameters:

• parent_group (str)

• mode (str)

• parent_scores (Series)

• eligible_mask (Series)

• conditional_df (DataFrame)

• absolute_df (DataFrame)

• assigned_labels (DataFrame)

• phase2_result (DataFrame)

• child_result (EasyDeconResult | None)

• diagnostics (dict)

Diagnostics

easydecon.summarize_easydecon_result(result, sdata=None, bin_size=8, table_key=None, preferred_table_keys=None, assignment_column=None, as_dataframe=True)

Summarize marker, matrix, posterior, assignment, and alignment QC.

Parameters:

• bin_size (int)

• as_dataframe (bool)

easydecon.summarize_marker_table(markers_df, group_col='group', gene_col='names', source_col='marker_source', top_genes=5)

Return one compact marker-count row per cell type or marker group.

Parameters:

• group_col (str)

• gene_col (str)

• source_col (str)

• top_genes (int)

Return type:

DataFrame

Niches

easydecon.detect_spatial_niches_from_posteriors(sdata, posterior_df, bin_size=8, table_key=None, preferred_table_keys=None, use_assignment_if_no_posterior=False, n_neighbors=6, n_niches=5, auto_n_niches=False, n_niches_min=2, n_niches_max=10, selection_metric='silhouette', smooth=True, niches_column='niche', add_to_obs=True, random_state=0, return_diagnostics=False)

Detect spatial niches from an easydecon posterior dataframe.

This function takes per-spot posterior cell-type probabilities (or proportions) and identifies recurrent spatial niches as clusters of local compositions.

Workflow:

1. Align posterior_df rows to the spatial table.

2. Extract spatial coordinates for each spot.

3. Optionally smooth posteriors by averaging over spatial k-nearest neighbors.

4. Select n_niches (optionally automatically via silhouette/inertia).

5. Cluster the (smoothed) compositions into n_niches groups (niches).

6. Optionally write niche labels into table.obs[niches_column].

Parameters:

• sdata (SpatialData or AnnData-like) – Object containing the spatial transcriptomics data and tables. A table named f”square_{bin_size:03}um” is used if present; otherwise “table” or sdata itself is used.

• posterior_df (pandas.DataFrame) – DataFrame of posteriors / proportions. Rows = spots, columns = cell types. Row index must match the spot IDs in table.obs.index (at least partially).

• bin_size (int, optional (default: 8)) – Bin size used in the spatial table name, f”square_{bin_size:03}um”.

• n_neighbors (int, optional (default: 6)) – Number of spatial nearest neighbors used for smoothing. If smooth=False, this is ignored.

• n_niches (int, optional (default: 5)) – Number of spatial niche clusters to detect, if auto_n_niches=False.

• auto_n_niches (bool, optional (default: False)) – If True, ignore n_niches and select the optimal number automatically between [n_niches_min, n_niches_max] using selection_metric.

• n_niches_min (int, optional (default: 2)) – Minimum number of niches to consider in automatic selection.

• n_niches_max (int, optional (default: 10)) – Maximum number of niches to consider in automatic selection.

• selection_metric ({"silhouette", "inertia"}, optional (default: "silhouette")) –

  Metric for automatic selection:

  • ”silhouette”: choose k with highest silhouette score.

  • ”inertia”: choose k with strongest elbow-like drop in inertia (here simply the largest relative decrease).

• smooth (bool, optional (default: True)) – If True, compute neighborhood-averaged compositions before clustering.

• niches_column (str, optional (default: "niche")) – Name of the column to store niche labels in table.obs when add_to_obs=True.

• add_to_obs (bool, optional (default: True)) – If True, writes niche labels into table.obs[niches_column].

• random_state (int, optional (default: 0)) – Random seed for clustering.

• return_diagnostics (bool, optional (default: False)) – If True, also return a diagnostics dict with candidate k, inertia, silhouette (if available), and chosen_k.

• use_assignment_if_no_posterior (bool)

Returns:

• niches (pandas.DataFrame) – DataFrame with a single categorical column niches_column (index = spot IDs).

• smoothed_posteriors (pandas.DataFrame) – The (optionally) neighborhood-smoothed posterior matrix used for clustering.

• diagnostics (dict, optional) –

  Only returned when return_diagnostics=True. Contains keys:

  • ”candidate_k”

  • ”inertia”

  • ”silhouette”

  • ”chosen_k”

  • ”selection_metric”

easydecon.detect_niches_from_easydecon_result(sdata, result, bin_size=8, use_assignment_if_no_posterior=False, **kwargs)

Detect niches from an EasyDeconResult-like object.

Parameters:

• bin_size (int)

• use_assignment_if_no_posterior (bool)

easydecon.summarize_niche_compositions(smoothed_posteriors, niches_df, niches_column='niche', normalize_rows=True)

Compute mean cell-type composition per niche.

Parameters:

• smoothed_posteriors (pandas.DataFrame) – (spots x cell types) matrix returned by detect_spatial_niches_from_posteriors.

• niches_df (pandas.DataFrame) – DataFrame with a categorical column niches_column indexed by spots.

• niches_column (str, optional) – Name of the niche column in niches_df.

• normalize_rows (bool, optional) – If True, renormalize each niche’s mean vector to sum to 1.

Returns:

(n_niches x cell types) mean compositions per niche.

Return type:

pandas.DataFrame

easydecon.plot_niche_compositions(smoothed_posteriors, niches_df, niches_column='niche', normalize_rows=True, figsize=(6, 4), legend_fontsize=8, rotation=0)

Plot niche-wise mean cell-type compositions as stacked bars.

Parameters:

• smoothed_posteriors (pandas.DataFrame) – (spots x cell types) matrix.

• niches_df (pandas.DataFrame) – DataFrame with a categorical column niches_column indexed by spots.

• niches_column (str, optional) – Name of the niche column in niches_df.

• normalize_rows (bool, optional) – If True, each bar sums to 1.

• figsize (tuple, optional) – Matplotlib figure size.

• legend_fontsize (int, optional) – Font size for legend.

• rotation (int, optional) – Rotation angle for x-tick labels.

Schema helpers

class easydecon.MarkerSchema(group_col='group', gene_col='names', lfc_col='logfoldchanges', padj_col='pvals_adj', score_col='scores')

Column names used by an easydecon marker DataFrame.

Parameters:

• group_col (str)

• gene_col (str)

• lfc_col (str)

• padj_col (str)

• score_col (str)

easydecon.get_table(sdata, bin_size=8, table_key=None, preferred_table_keys=None)

Resolve and validate an AnnData-like table from a container or table.

easydecon.resolve_marker_columns(df, schema=None)

Map easydecon’s canonical marker columns to columns present in df.

Matching is case-insensitive, while the returned values retain the exact column labels from the input DataFrame.

easydecon.standardize_marker_dataframe(df, schema=None, gene_universe=None, exclude_celltype=None, top_n_genes=60, sort_by_column=None, ascending=False, log2fc_min=0.25, pval_cutoff=0.05, drop_ribosomal=False, drop_mitochondrial=False, source=None, require_group=True, require_gene=True, copy=True)

Return a consistently named and filtered marker DataFrame.

Runtime configuration

easydecon.set_n_jobs(n)

easydecon.set_batch_size(n)

Public constants

easydecon.UCELL_MARKER_ROLES = frozenset({'identity', 'negative', 'positive', 'presence'})

frozenset() -> empty frozenset object frozenset(iterable) -> frozenset object

Build an immutable unordered collection of unique elements.

easydecon.MARKER_ROLE_MODES = frozenset({'phase_specific', 'shared'})

frozenset() -> empty frozenset object frozenset(iterable) -> frozenset object

Build an immutable unordered collection of unique elements.