crested.tl.modisco.create_tf_ct_matrix#
- crested.tl.modisco.create_tf_ct_matrix(pattern_tf_dict, all_patterns, df, classes, log_transform=True, normalize_pattern_importances=False, normalize_gex=False, min_tf_gex=0, min_total_seqlets=0, importance_threshold=0, pattern_parameter='seqlet_count', filter_correlation=False, zscore_threshold=2, correlation_threshold=0.2, similarity_metric='pearson', selection='nnls', nnls_alpha=1.0, nnls_keep_frac=0.2, rel_keep_frac=0.1, verbose=False)#
Create a tensor (matrix) of transcription factor (TF) expression and cell type contributions.
- Parameters:
pattern_tf_dict (
dict) – A dictionary with pattern indices and their TFs. Seecrested.tl.modisco.create_pattern_tf_dict.all_patterns (
dict) – A list of patterns with metadata. Seecrested.tl.modisco.process_patterns.df (
DataFrame) – A DataFrame containing gene expression data. Seecrested.tl.modisco.calculate_mean_expression_per_cell_typelog_transform (
bool(default:True)) – Whether to apply log transformation to the gene expression values. Default is True.normalize_pattern_importances (
bool(default:False)) – Whether to normalize the contribution scores across the cell types. Default is False.normalize_gex (
bool(default:False)) – Whether to normalize gene expression across the cell types. Default is False.min_tf_gex (
float(default:0)) – Minimum expression a TF must reach in at least one cell type where the pattern fires (contribution >importance_threshold) to be kept. Applied to the expression values used by this function (i.e., after optionallog_transform, if enabled), before this function’snormalize_gexpeak-scaling (which scales each TF to max 1 and would make a level floor meaningless). Default 0 (no floor). Note that some genuine TFs are lowly expressed, so raising this can drop real candidates; withverbose=Truethe per-candidate expression percentiles on the firing cell types are printed to help calibrate.min_total_seqlets (
int(default:0)) – Minimum number of seqlets a pattern must have, summed across all the cell types it fires in, to be kept. Unlikeimportance_threshold(a per-cell-type peak gate: keep the pattern if any single cell type clears the floor), this ranks patterns by their total seqlet count and trims the weakest – raising it drops patterns in ascending total-seqlet order. Applied as a whole-pattern gate (all of a pattern’s TF columns drop together). Default 0 (no floor).importance_threshold (
float(default:0)) – The minimum pattern importance value. Default is 0.pattern_parameter (
str(default:'seqlet_count')) – Parameter which is used to indicate the pattern’s importance. Either average contribution score (‘contrib’), or number of pattern instances (‘seqlet_count’, default) and its log (‘seqlet_count_log’).filter_correlation (
bool(default:False)) – Whether to filter based on Pearson correlation betweentf_gexandct_contribs. Default is False.zscore_threshold (
float(default:2)) – Zscore used for filtering TF candidates. If the max zscore over the cell types is belofw this threshold, the TF gets discarded. Default is 2.correlation_threshold (
float(default:0.2)) – Minimum agreement (seesimilarity_metric) between expression and contribution profile required to keep a column if filtering is enabled. Default is 0.2.similarity_metric (
str(default:'pearson')) – Metric for the expression/contribution agreement, used by the"threshold"selection’s correlation filter."pearson"(default) keeps the original mean-centered Pearson correlation."cosine"uses an uncentered cosine between the absolute contribution and the (non-negative) expression profile. Because it is not mean-centered, cosine matches the shape of the two profiles: a broadly-expressed TF on a broad contribution still scores high, but a broadly-expressed TF on a cell-type-specific contribution scores low and is dropped. Recommended (with a slightly highercorrelation_threshold, ~0.55, since cosine has a positive floor) when broadly-expressed TFs are being selected for specific patterns. (The"nnls"selection’s pattern gate always uses Pearson regardless of this value.)selection (
str(default:'nnls')) – How candidate TF-pattern columns are selected."nnls"(default) = deconvolution: a Pearson pattern gate decides which patterns are annotated, then a non-negative ridge regression models each pattern’s contribution as a combination of its full candidate pool (down-weighting broadly-expressed binders that merely correlate), and finally an expression-relevance gate (rel_keep_frac) keeps the candidates actually expressed where the pattern fires. Seecrested.tl.modisco._tfmodisco._nnls_paralog_select. With"nnls"thefilter_correlationflag is ignored (the pattern gate useszscore_threshold+correlation_threshold)."threshold"= the original per-column gates (gex/importance, then thefilter_correlationcorrelation/zscore gate); use it to reproduce pre-change analyses.nnls_alpha (
float(default:1.0)) –selection="nnls"only. Non-negative ridge (Tikhonov) strength for the per-pattern regression. >0 spreads weight across collinear candidate columns so a single paralog does not arbitrarily absorb it; ~1.0 is a good default. Default 1.0.nnls_keep_frac (
float(default:0.2)) –selection="nnls"only. Within a pattern, keep a TF if its regression weight is > 0 and >=nnls_keep_fracx the pattern’s maximum weight. Default 0.2.rel_keep_frac (
float(default:0.1)) –selection="nnls"only. Expression-relevance gate applied to the regression survivors: for each survivor compute a contribution-weighted mean RAW expressionrel_t = (|contrib| . gex_t) / sum(|contrib|)(cell types where the pattern fires strongly dominate), and keep it only ifrel_t >= rel_keep_fracx the pattern’s best survivor. This drops candidates barely expressed where the pattern fires while keeping every genuinely co-expressed paralog (no family grouping or name heuristic — 1 or more paralogs survive on their own merit). Higher = stricter (fewer paralogs). Default 0.1.verbose (
bool(default:False)) – Whether to print intermediate debugging steps.