Wrapper function to conduct the full regulatory topic-modeling workflow for one or more topic-document construction methods.
Usage
run_topic_modeling(
filtered_dir,
multiomic_data = NULL,
comparisons,
output_dir,
project_config = NULL,
method = NULL,
k_grid = NULL,
output_layout = c("auto", "standard", "benchmark", "legacy"),
warplda_iterations = NULL,
warplda_sampler = NULL,
warplda_beta = NULL,
warplda_seed = NULL,
topic_link_output = NULL,
count_method = NULL,
count_scale = NULL,
count_input = NULL,
fp_term_mode = NULL,
de_gene_union_scope = NULL,
condition_gene_weighting = NULL,
condition_peak_weighting = NULL,
condition_gene_expression_file = NULL,
condition_specificity_temperature = NULL,
condition_specificity_floor = NULL,
condition_specificity_expression_min = NULL,
topic_score_method = NULL,
topic_term_assignment_method = NULL,
optimize_topics = NULL,
run_topic_assignment_qc = NULL,
topic_merge_min_genes = NULL,
topic_merge_min_links = NULL,
topic_merge_similarity_threshold = NULL,
topic_merge_tf_theta_preference = NULL,
topic_qc_umap_links_per_condition = NULL,
topic_qc_top_tfs = NULL,
topic_qc_reference_condition = NULL,
topic_qc_upregulated_log2fc_min = NULL,
topic_qc_upregulated_pseudocount = NULL,
vae_device = NULL,
vae_batch_size = NULL,
vae_paired_term_regularization = NULL,
pathway_backend = NULL,
pathway_species = NULL,
pathway_databases = NULL,
sample_subset = NULL,
analysis_label = NULL,
extraction_topic_report_args = list(),
extraction_k_workers = NULL,
extraction_k_max_workers = 4L,
memory_safety = c("strict", "adaptive", "off"),
memory_max_fraction = 0.8,
input_source = c("differential_links", "condition_links"),
...
)Arguments
- filtered_dir
Directory containing Module 3 filtered differential-link files.
- multiomic_data
Optional CraftGRN multiomic object. Required when `replicate_documents = TRUE`. In condition mode, supply the complete object so HTML RNA values and pathway-expression scores use the full normalized `matrices$gene_expr` matrix rather than filtered link rows.
- comparisons
Comparison or condition grouping table, or a CSV path.
- output_dir
Topic output directory.
- project_config
Optional project YAML path or config list. When supplied, `topic_method`, `topic_k` or `topic_k_grid`, `warplda_iterations`, `topic_link_output`, `topic_score_method`, `topic_term_assignment_method`, `topic_gammafit_thrP` (a scalar or an `lda`/`multivi`/`vae_mlp` mapping), `topic_tf_membership_cutoff`, `topic_tf_primary_margin_cutoff`, and `topic_raw_theta_document_heatmap` are used for arguments that are left as `NULL` or as default extraction settings. A nested `report` mapping can define `condition_colors`, `condition_order`, `condition_short_labels`, and initial `defaults` for generated reports without creating package or browser-persistent state. Defaults may use exact `condition_1` and `condition_2` IDs or reusable `condition_1_suffix` and `condition_2_suffix` selectors. Set `report.defaults.topic: top` to start at the highest mean-theta topic for the initial Condition 1.
- method
One or more Module 3 method IDs. If `NULL`, read from `project_config` or use the package default.
- k_grid
Integer topic numbers. If `NULL`, read from `project_config` or use `10`.
- output_layout
Output folder layout. `"auto"` uses the standard flat layout for one method and the shallow benchmark layout for multiple methods.
- warplda_iterations
Number of native WarpLDA iterations. If `NULL`, read from `project_config` or use `2000`.
- warplda_sampler
Native WarpLDA sampler. If `NULL`, read from project config or use `"warp_omp"`.
- warplda_beta
Topic-word prior. `NULL` uses `1/K`.
- warplda_seed
Integer random seed for native WarpLDA.
- topic_link_output
Topic-link output mode. If `NULL`, read from `project_config` or use `"pass"`.
- count_method
Topic count conversion method. If `NULL`, read from `project_config` or use `"log"`.
- count_scale
Positive pseudo-count scaling factor. If `NULL`, read from project config or use `50`.
- count_input
Topic count column for model fitting. If `NULL`, inferred from `count_method`.
- fp_term_mode
Optional term-mode override. This is intended for isolated experiments such as `"tf_target"`; `NULL` preserves the mode encoded by each selected method.
- de_gene_union_scope
Differential-gene union used by filtered condition links. `"condition"` uses genes passing a configured comparison involving each condition; `"global"` applies the union from every configured comparison to every condition before the expression filter. If `NULL`, read `topic_de_gene_union_scope` from project config or use `"condition"`.
- condition_gene_weighting
Condition-mode target-gene weighting. Use `"specificity"` to emphasize relative expression across conditions while retaining every document term and conserving document token totals.
- condition_peak_weighting
Condition-mode aggregated-Peak weighting. Use `"tf_expression"` to multiply balanced Peak weights by the selected TF condition-specific log expression relative to its median across included conditions before pseudo-count conversion.
- condition_gene_expression_file
Long condition-gene expression CSV. If `NULL`, specificity weighting reads `condition_gene_expression.csv` under `filtered_dir`.
- condition_specificity_temperature
Positive temperature for expression-specific weighting. If `NULL`, read from project config or use `0.5`.
- condition_specificity_floor
Uniform expressed-condition share retained during specificity weighting. If `NULL`, read from project config or use `0.1`.
- condition_specificity_expression_min
Minimum expression used to define expressed condition-gene pairs. If `NULL`, training reuses `threshold_gene_expr`.
- topic_score_method
Topic-term score method for extraction. If `NULL`, read from `project_config` or use `"normtop_specificity"`.
- topic_term_assignment_method
Term-to-topic assignment method. If `NULL`, read from `project_config`. Aggregate Gene/Peak methods default to `"gammafit_maxprob"`, which applies GammaFit first and retains a Gene/Peak pair only when the independently selected maximum-phi passing topics agree. In experimental `"tf_target"` mode, Gene and TF-target terms are fit independently and a TF-target assignment is retained only when its maximum-phi passing topic agrees with the target Gene term. Unique or aggregate-weight methods retain the independent `"max_phi"` default.
- optimize_topics
Whether eligible condition-topic extractions merge undersized or highly similar topics before downstream reports. If `NULL`, use project config or the standard condition-mode default.
- run_topic_assignment_qc
Whether to write the standard per-K topic assignment QC PDF. If `NULL`, use project config.
- topic_merge_min_genes
Minimum assigned genes required to retain a topic without a size-based merge. If `NULL`, use project config.
- topic_merge_min_links
Minimum aligned TF-target links required to retain a topic without a size-based merge. If `NULL`, use project config.
- topic_merge_similarity_threshold
Mean Gene/Peak Hellinger similarity at or above which topics are merged. If `NULL`, use project config.
- topic_merge_tf_theta_preference
Whether merge selection should retain target assignments and prefer mappings that reduce TF terms lacking a matching condition::TF theta membership. If `NULL`, use project config.
- topic_qc_umap_links_per_condition
Maximum deterministic UMAP sample size per condition. Full-universe counts are not sampled.
- topic_qc_top_tfs
Number of globally ranked TFs shown in the pooled TF-by-topic QC heatmap.
- topic_qc_reference_condition
Optional reference condition for the upregulated assigned-target QC panel.
- topic_qc_upregulated_log2fc_min
Minimum log2 fold change above the reference condition in that panel.
- topic_qc_upregulated_pseudocount
Positive expression pseudocount for that log2 fold change.
- vae_device
VAE device, for example `"auto"`, `"cpu"`, or `"cuda"`. If `NULL`, read from `project_config` or use `"auto"`.
- vae_batch_size
VAE mini-batch size. If `NULL`, read from `project_config` or use `64`.
- vae_paired_term_regularization
Non-negative strength for matching the topic distributions of paired Gene and Peak terms. If `NULL`, read from project config and otherwise use `5` for MultiVI and `0` for other VAE variants.
- pathway_backend
Pathway enrichment backend. Use `"enrichly"` for local cached enrichment or `"enrichr"` for the Enrichr web API. If `NULL`, read from `project_config` or use `"enrichly"`.
- pathway_species
Species used to choose default pathway databases. Supported values include `"human"`, `"mouse"`, and `"human_mouse_best"`. The best-of mode runs human and mouse pathway databases separately and reports the better row per topic and normalized pathway name, ranked by adjusted p-value, logp, combined score, and overlap size. If `NULL`, read from `project_config` or infer from `ref_genome`.
- pathway_databases
Optional Enrichr database names. If `NULL`, read from `project_config` or use the species-specific package defaults.
- sample_subset
Optional condition/sample IDs to retain when building topic documents. Condition-link runs read only matching manifest rows.
- analysis_label
Stable label written to topic input metadata.
- extraction_topic_report_args
Optional named list of topic-extraction report argument overrides. Values here override project config values, including TF-to-topic assignment cutoffs.
- extraction_k_workers
Number of K values to extract concurrently. Use `1` to request sequential extraction.
- extraction_k_max_workers
Maximum concurrent K extraction workers.
- memory_safety
Module 3 memory policy. `"strict"` fails before an unsafe allocation, `"adaptive"` reduces concurrency where possible, and `"off"` disables memory preflight checks.
- memory_max_fraction
Maximum fraction of currently available memory that a Module 3 stage may use. Defaults to `0.8`.
- input_source
Input source type. Use `"differential_links"` for comparison links and `"condition_links"` for condition-native links.
- ...
Additional arguments passed to the internal topic-modeling wrapper.