pertpy.tools.Dialogue#
- class Dialogue(*, celltype_key, sample_key, cell_quality_key='cellQ', n_programs=3, feature_space_key='X_pca', n_components=30, n_genes_per_signature=100, anova_alpha=0.05, winsorize_quantile=0.01, n_permutations=100, empirical_alpha=0.1, use_tme_qc=True, additional_covariates=(), min_cells_per_sample=15, random_state=1234)[source]#
Multicellular program discovery (DIALOGUE).
- Parameters:
- celltype_key
str Column of
adata.obswith the cell-type assignment.- sample_key
str Column of
adata.obswith the sample / niche identifier.- cell_quality_key
str, default:'cellQ' Column of
adata.obswith the per-cell QC value (typically log-counts) used as a confounder in residualization and in the per-pair HLM (R’scellQ).- n_programs
int, default:3 Number of multicellular programs to fit (
kin the paper).- feature_space_key
str, default:'X_pca' adata.obsmkey for the pre-computed feature space (typically PCA).- n_components
int, default:30 Number of components of the feature space to use.
- n_genes_per_signature
int, default:100 Number of top-correlated genes kept per program signature and direction (R’s
n.genes, 100 as in the DIALOGUE tutorial).- anova_alpha
float, default:0.05 Per-feature ANOVA significance threshold for filtering uninformative components (R’s
p.anova).- winsorize_quantile
float, default:0.01 Tail clipping fraction applied to pseudobulk components (R’s
cap.matparameter).- n_permutations
int, default:100 Number of PMD fits in the empirical test, the observed one plus
n_permutations - 1on sample-permuted matrices (R’sn1inDIALOGUE1.PMD.empirical). At least 11 are needed for any pair to pass the defaultempirical_alpha.- empirical_alpha
float, default:0.1 P-value threshold below which a program is considered shared between a pair of cell types (R’s implicit
< 0.1).- use_tme_qc
bool, default:True If True, add
tme_qc(partner-celltype per-sample average ofcell_quality_key) as an additional HLM covariate (R default).- additional_covariates
Sequence[str], default:() Extra
adata.obscolumns to include as HLM covariates.- min_cells_per_sample
int, default:15 Minimum cells a sample needs for its cells to enter the ANOVA feature filter (R’s
abn.c).- random_state
int, default:1234 Reproducibility seed for the permutation tests.
- celltype_key
Methods table#
find_extreme_score_genes(adata, *[, ...])Differential-expression scan between the highest- and lowest-scoring cells per cell type for one program.
fit_programs(adata)Identify multicellular programs across cell types via penalized multiple-CCA.
get_program_genes(adata, *, program[, ...])Return the refined gene signature
{"up": [...], "down": [...]}for a program.plot_pairplot(adata, *, color[, program, ...])Cross-celltype pairplot of sample-level program scores, colored by a phenotype.
plot_split_violins(adata, *, condition_key)Per-celltype split violin of program scores stratified by a binary phenotype.
refine_scores(adata)Aggregate per-pair HLM evidence and fit final per-cell program scores via iterative non-negative least squares.
test_celltype_pairs(adata, *[, show_progress])For every ordered pair of cell types, fit a hierarchical linear model of one cell type's program score against the partner cell type's pseudobulk expression of candidate genes.
test_phenotype_association(adata, ...[, ...])Test each program's association with a phenotype by hierarchical linear models, R's
DIALOGUE.pheno.Methods#
- find_extreme_score_genes(adata, *, program='MCP1', fraction=0.1)[source]#
Differential-expression scan between the highest- and lowest-scoring cells per cell type for one program.
- Parameters:
- adata
AnnData AnnData after
refine_scores().- program
str, default:'MCP1' Program to use (
"MCP1"by default).- fraction
float, default:0.1 Fraction of cells at each tail to compare. Must lie in
(0, 0.5).
- adata
- Return type:
Examples
>>> import pertpy as pt >>> import scanpy as sc >>> adata = pt.ds.dialogue_example() >>> sc.pp.pca(adata) >>> dl = pt.tl.Dialogue(celltype_key="cell.subtypes", sample_key="sample", n_programs=3) >>> dl.fit_programs(adata) >>> dl.test_celltype_pairs(adata) >>> dl.refine_scores(adata) >>> dl.find_extreme_score_genes(adata, program="MCP1", fraction=0.1)
- fit_programs(adata)[source]#
Identify multicellular programs across cell types via penalized multiple-CCA.
Phase 1 of DIALOGUE. Pseudobulks each cell type per sample, filters uninformative components by ANOVA, centers and winsorizes them, then runs penalized multiple-CCA on the cell types’ pseudobulk feature spaces to obtain weights and per-cell program scores. Empirical p-values for each program-by-pair are computed by repeating the PMD on permuted matrices.
Stores the following on
adata:adata.obsm["X_dialogue_cca"]— per-cell CCA scores (n_obs × n_programs), residualized on the cell-quality confounder, NaN-padded for cells of cell types skipped during fitting.adata.uns["dialogue"]["weights"][celltype]— PMD weights (n_components × n_programs).adata.uns["dialogue"]["pseudobulk_features"][celltype]— the post-filter, post-center pseudobulk matrices (samples × retained components).adata.uns["dialogue"]["empirical_pvalues"]— programs × cell-type pairs.adata.uns["dialogue"]["cca_correlations_R"]/"_P"— per-pair pairwise correlation and p-value of the cell types’ CCA scores.adata.uns["dialogue"]["program_celltypes"]— mapping of each program to the cell types retained by R’sDIALOGUE.identify.cell.typespruning of the pairs passingempirical_alpha.adata.uns["dialogue"]["program_signatures"][program][celltype]— initial signature genes, the top Pearson-correlated genes re-ranked by partial Spearman correlation of the CCA scores with expression, controlling for cell quality.adata.uns["dialogue"]["params"]— recorded hyperparameters.adata.uns["dialogue"]["shared_samples"]— samples present in all cell types.adata.uns["dialogue"]["cell_type_order"]— cell types fit (in stable order).
Examples
>>> import pertpy as pt >>> import scanpy as sc >>> adata = pt.ds.dialogue_example() >>> sc.pp.pca(adata) >>> dl = pt.tl.Dialogue(celltype_key="cell.subtypes", sample_key="sample", n_programs=3) >>> dl.fit_programs(adata)
- Return type:
- get_program_genes(adata, *, program, celltype=None, strict=False)[source]#
Return the refined gene signature
{"up": [...], "down": [...]}for a program.- Parameters:
- adata
AnnData AnnData after
refine_scores().- program
str Program label (e.g.
"MCP1").- celltype
str|None, default:None If given, return only that cell type’s signature. Otherwise return the cross-celltype intersection of consistently up/down genes.
- strict
bool, default:False Use the strict variant from
program_gene_signatures_strict(genes flagged in every pair).
- adata
- Return type:
Examples
>>> import pertpy as pt >>> import scanpy as sc >>> adata = pt.ds.dialogue_example() >>> sc.pp.pca(adata) >>> dl = pt.tl.Dialogue(celltype_key="cell.subtypes", sample_key="sample", n_programs=3) >>> dl.fit_programs(adata) >>> dl.test_celltype_pairs(adata) >>> dl.refine_scores(adata) >>> dl.get_program_genes(adata, program="MCP1", celltype="CD8+ IELs")
- plot_pairplot(adata, *, color, program='MCP1', return_fig=False)[source]#
Cross-celltype pairplot of sample-level program scores, colored by a phenotype.
Aggregates each (sample, cell type) to the mean program score, pivots into a sample-by-celltype matrix, and runs
seaborn.pairplotwith the sample-levelcolorannotation as the hue.- Parameters:
- adata
AnnData AnnData processed by
refine_scores().- color
str Column of
adata.obswith the per-sample annotation used as the pairplot hue.- program
str, default:'MCP1' Program label.
- return_fig
bool, default:False if
True, returns figure of the plot, that can be used for saving.
- adata
- Return type:
- Returns:
If
return_figisTrue, returns the figure, otherwiseNone.
Examples
>>> import pertpy as pt >>> adata = pt.ds.dialogue_example() >>> dl = pt.tl.Dialogue(celltype_key="cell.subtypes", sample_key="sample", n_programs=3) >>> dl.fit_programs(adata) >>> dl.test_celltype_pairs(adata) >>> dl.refine_scores(adata) >>> dl.plot_pairplot(adata, color="clinical.status", program="MCP1")
- Preview:
- plot_split_violins(adata, *, condition_key, program='MCP1', conditions=None, return_fig=False)[source]#
Per-celltype split violin of program scores stratified by a binary phenotype.
- Parameters:
- adata
AnnData AnnData processed by
refine_scores().- condition_key
str Column of
adata.obswith the binary phenotype to split on.- program
str, default:'MCP1' Program label (
"MCP1","MCP2", …).- conditions
tuple[str,str] |None, default:None Pick which two values of
adata.obs[condition_key]to plot. Required when the column has more than two levels.- return_fig
bool, default:False if
True, returns figure of the plot, that can be used for saving.
- adata
- Return type:
- Returns:
If
return_figisTrue, returns the figure, otherwiseNone.
Examples
>>> import pertpy as pt >>> adata = pt.ds.dialogue_example() >>> dl = pt.tl.Dialogue(celltype_key="cell.subtypes", sample_key="sample", n_programs=3) >>> dl.fit_programs(adata) >>> dl.test_celltype_pairs(adata) >>> dl.refine_scores(adata) >>> dl.plot_split_violins(adata, condition_key="path_str", program="MCP1")
- Preview:
- refine_scores(adata)[source]#
Aggregate per-pair HLM evidence and fit final per-cell program scores via iterative non-negative least squares.
Phase 3 of DIALOGUE. For every cell type, gather the per-gene z-scores produced by
test_celltype_pairs()across every pair the cell type appears in, BH-adjust within each program-by-direction, Fisher-combine across pairs, then run iterative NNLS to fit per-cell program scores against the resulting candidate gene set (sign-flipping down-regulated columns). The fitted scores are residualized on the cell-quality confounder and written back toadata.obsm["X_dialogue"].Stores on
adata.uns["dialogue"]:gene_pvalues[celltype]— R’sgene.pvaltable with per-partner z-scores, Fisher-combined one-sidedp_up/p_down, support countsn_up/n_downand fractionsnf_up/nf_downat R’s fixed 0.1 threshold, program label,updirection, and the fittedcoeffrom NNLS.program_gene_signatures[program][celltype] = {"up": [...], "down": [...]}— refined gene signatures (R’ssig1fromDLG.find.scoring).program_gene_signatures_strict[program][celltype] = {"up": [...], "down": [...]}— stricter set (R’ssig2).pair_refined_correlations[pair][program]— R’spref: the correlationRof the per-sample median refined scores of the two cell types, and the p-valueshlm_p1/hlm_p2of each cell type’s scores against the partner’s per-sample median score in the pair HLM.
Updates
adata.obsm["X_dialogue"]with the refined per-cell program scores.Examples
>>> import pertpy as pt >>> import scanpy as sc >>> adata = pt.ds.dialogue_example() >>> sc.pp.pca(adata) >>> dl = pt.tl.Dialogue(celltype_key="cell.subtypes", sample_key="sample", n_programs=3) >>> dl.fit_programs(adata) >>> dl.test_celltype_pairs(adata) >>> dl.refine_scores(adata)
- Return type:
- test_celltype_pairs(adata, *, show_progress=False)[source]#
For every ordered pair of cell types, fit a hierarchical linear model of one cell type’s program score against the partner cell type’s pseudobulk expression of candidate genes.
Phase 2 of DIALOGUE. Builds per-pair, per-program tables of (estimate, standard error, degrees of freedom, p-value, z-score) for each candidate gene from
fit_programs’ signatures and keeps the top 100 genes per direction with|z| >= 1as refined signatures, like R. Only samples with at least two cells in both cell types of the pair enter a pair’s models, as in R.Stores on
adata.uns["dialogue"]["pair_results"]a nested dict.pair_results[pair_name][program][celltype]is a DataFrame with one row per gene tested (in that cell type’s signature) and columnsestimate, std_error, df, pvalue, zscore, pvalue_adj, up. Refined per-pair signatures live atpair_results[pair_name][program]["refined_signatures"][celltype] = {"up": [...], "down": [...]}.- Parameters:
- adata
AnnData AnnData previously processed by
fit_programs().- show_progress
bool, default:False If True, print one line per pair while running.
- adata
- Return type:
Examples
>>> import pertpy as pt >>> import scanpy as sc >>> adata = pt.ds.dialogue_example() >>> sc.pp.pca(adata) >>> dl = pt.tl.Dialogue(celltype_key="cell.subtypes", sample_key="sample", n_programs=3) >>> dl.fit_programs(adata) >>> dl.test_celltype_pairs(adata)
- test_phenotype_association(adata, condition_key, *, conditions=None)[source]#
Test each program’s association with a phenotype by hierarchical linear models, R’s
DIALOGUE.pheno.For every cell type, and once more for all cells pooled (row
"All"), fitsscore ~ (1 | sample) + phenotype + cell_qualityon the refined scores.phenotypeindicates the first level ofadata.obs[condition_key]in sorted order, or is the column itself when it is boolean, as in R. Returns signed log10 p-value z-scores (rows: cell types and"All", columns: programs), positive when that level has higher scores.- Parameters:
- Returns:
cell types and
"All", columns: programs), also stored onadata.uns["dialogue"]["phenotype_zscores"].- Return type:
Examples
>>> import pertpy as pt >>> import scanpy as sc >>> adata = pt.ds.dialogue_example() >>> sc.pp.pca(adata) >>> dl = pt.tl.Dialogue(celltype_key="cell.subtypes", sample_key="sample", n_programs=3) >>> dl.fit_programs(adata) >>> dl.test_celltype_pairs(adata) >>> dl.refine_scores(adata) >>> dl.test_phenotype_association(adata, condition_key="pathology")