Public step function for extracting regulatory topics, pathway summaries, topic-link tables, direction-specific TF-to-topic assignment tables, and review outputs from trained Module 3 topic models.
Usage
module3_extract_topics(
k,
model_dir,
output_dir,
flatten_single_output = TRUE,
topic_score_method = c("normtop_specificity", "rowmax_phi"),
topic_term_assignment_method = c("gammafit_maxprob", "max_phi", "gammafit"),
optimize_topics = NULL,
topic_merge_min_genes = 150L,
topic_merge_min_links = 200L,
topic_merge_similarity_threshold = 0.65,
topic_merge_tf_theta_preference = TRUE,
run_topic_assignment_qc = NULL,
topic_qc_umap_links_per_condition = 3000L,
topic_qc_top_tfs = 150L,
topic_qc_condition_expression_file = NULL,
topic_qc_reference_condition = NULL,
topic_qc_upregulated_log2fc_min = 1,
topic_qc_upregulated_pseudocount = 1,
k_workers = NULL,
k_max_workers = 4L,
k_memory_gb = NULL,
k_memory_reserve_gb = 32,
cores = NULL,
verbose = TRUE,
...
)Arguments
- k
Integer K value or vector of K values selected for extraction.
- model_dir
Directory containing trained topic model outputs.
- output_dir
Directory to write extracted topic outputs.
- flatten_single_output
Whether to write a single selected model directly under `output_dir`. Defaults to `TRUE` for the public step API.
- topic_score_method
Topic-term score method. `"normtop_specificity"` is the default for new extractions; `"rowmax_phi"` preserves the legacy row-maximum-scaled phi score.
- topic_term_assignment_method
Term-to-topic assignment. `"gammafit_maxprob"` applies GammaFit first, independently selects the maximum-phi passing topic for each paired term, and keeps a Gene/Peak pair or TF-target/Gene pair only when those topics agree. `"max_phi"` assigns terms independently from raw `phi`; `"gammafit"` retains multi-topic cutoff membership.
- optimize_topics
Whether eligible condition-topic extractions merge undersized or highly similar topics before downstream reports.
- topic_merge_min_genes
Minimum assigned genes required to retain a topic without a size-based merge.
- topic_merge_min_links
Minimum aligned TF-target links required to retain a topic without a size-based merge.
- topic_merge_similarity_threshold
Mean Gene/Peak Hellinger similarity at or above which two topics are merged.
- topic_merge_tf_theta_preference
Whether eligible topic merges must preserve target assignments and prefer mappings that reduce TF terms without a matching condition::TF theta membership.
- run_topic_assignment_qc
Whether to write the standard per-K topic assignment QC PDF and optimization audit tables.
- topic_qc_umap_links_per_condition
Maximum deterministic UMAP sample size per condition. Full-universe counts are never sampled.
- topic_qc_top_tfs
Number of globally ranked TFs shown in the pooled TF-by-topic QC heatmap.
- topic_qc_condition_expression_file
Optional complete condition-pair gene-expression audit CSV. When supplied, QC expression summaries use this complete matrix instead of the condition-filtered link rows.
- topic_qc_reference_condition
Optional reference condition used to count assigned target genes with increased expression in the QC report.
- topic_qc_upregulated_log2fc_min
Minimum log2 fold change above the reference condition for the upregulated-target QC panel.
- topic_qc_upregulated_pseudocount
Positive expression pseudocount used for the reference-condition log2 fold change.
- k_workers
Number of K values to extract concurrently. `NULL` selects workers adaptively from current memory and CPU headroom.
- k_max_workers
Maximum concurrent K workers in adaptive mode.
- k_memory_gb
Optional conservative memory estimate per K worker in GiB. When `NULL`, estimate from `edges_docs.rds` with a 16 GiB minimum.
- k_memory_reserve_gb
Minimum RAM in GiB to leave unused. Adaptive scheduling also reserves at least 25 percent of currently available RAM.
- cores
CPU cores available to the extraction scheduler.
- verbose
Emit concise extraction scheduler messages.
- ...
Additional arguments passed to the internal extraction engine, such as `backend`, `doc_mode`, `weight_label`, and `topic_report_args`.
Details
Topic assignment uses unit-specific evidence. By default, GammaFit first identifies candidate topics for each aggregate `GENE:<gene>` and `PEAK:<gene>` pair. Each term independently selects its maximum-phi passing topic, and the pair is retained only when those topics agree. Experimental `"tf_target"` inputs instead compare each `<TF>::<target>` winner with the corresponding `GENE:<target>` winner and retain the TF-target term only when they agree. This TF-target agreement does not add a theta gate. Overall pathway enrichment in this mode uses every assigned `GENE:<target>` term; retained TF-target terms define link topology and report subnetworks. The explicit `"max_phi"` and legacy `"gammafit"` methods remain available for comparison.
TFs are assigned from raw document-topic `theta` with the TF membership and primary margin cutoffs. Per-comparison pathway gene sets are built from model outputs only: documents with theta above the TF membership cutoff intersect genes represented by topic-assigned terms. Physical TF-peak-gene links are not used to define pathway topic membership at extraction time; they can be projected later onto selected comparison/topic/pathway genes for subnetworks.