Package 'craftgrn'

Title: Integrative Chromatin Accessibility and RNA Framework for Gene Regulatory Networks
Description: Provides a reproducible framework for constructing and comparing gene regulatory networks by integrating chromatin accessibility footprint scores with matched RNA expression data. It implements context-specific enhancer-gene linking, transcription factor focused network analysis, differential network analysis, and regulatory topic modeling workflows for systematic exploration of gene regulation across conditions. Methodological background is described in Bentsen and others (2020) <doi:10.1038/s41467-020-18035-1>, Blei, Ng and Jordan (2003) <https://www.jmlr.org/papers/v3/blei03a.html>, and Chen, Li, Zhu and Chen (2015) <doi:10.48550/arXiv.1510.08628>.
Authors: Yaoxiang Li [aut, cre], Chunling Yi [aut]
Maintainer: Yaoxiang Li <[email protected]>
License: GPL (>= 3)
Version: 0.1.7
Built: 2026-10-04 10:15:17 UTC
Source: https://github.com/oncologylab/craftgrn

Help Index

Build a Module 1 QC HTML report

Description

Builds a comprehensive HTML report for Module 1 run parameters, input gates, motif-supported canonical support, prediction output integrity, correlation diagnostics, condition-level CraftGRN multiomic input QC, metadata-aware PCA, footprint alignment summaries, warning checks, and interactive Binding, Co-binding, and Motif review. The report can consume a 'predict_tfbs()' result, a step-by-step Module 1 result list, or a Module 1 output directory.

Usage

build_module1_qc_report(
  module1,
  omics_data = NULL,
  output_dir = NULL,
  report_name = "module1_qc_report.html",
  scan_predicted_tfbs = TRUE,
  top_n = 20L,
  project_config = NULL,
  project_date = NULL,
  build_tfbs_explorer = TRUE,
  default_condition = NULL,
  recompute_correlation_hist = FALSE,
  correlation_hist_cores = NULL,
  verbose = TRUE
)

Arguments

module1

Module 1 result list or Module 1 output directory.
omics_data

Optional CraftGRN multiomic object. Used when 'module1' is an output directory or does not contain 'omics_data'.
output_dir

Directory where the HTML report should be written. If 'NULL', the report is written under 'reports' inside the Module 1 output directory when available.
report_name

HTML report filename.
scan_predicted_tfbs

Logical; if 'TRUE', scan predicted TFBS chunks to summarize top TFs and condition support. This is comprehensive but can take extra time on full projects.
top_n

Number of TFs to show in top-TF summaries.
project_config

Optional YAML path or list used for parameter provenance in the Run Summary.
project_date

Optional project date displayed in the report title.
build_tfbs_explorer

Logical; embed the interactive Binding, Co-binding, and Motif explorer sections in the QC report.
default_condition

Optional initial condition for TFBS report previews and the linked explorer.
recompute_correlation_hist

Logical; recompute the all-evaluated correlation histogram for a legacy run that predates the compact histogram artifact. This requires the matching multiomic object and exact saved canonical-bound footprint set.
correlation_hist_cores

Optional worker count for legacy histogram recomputation.
verbose

Emit concise progress messages.

Value

Normalized path to the HTML report.

Build the interactive Module 1 TFBS Explorer

Description

Builds an explicitly requested standalone HTML explorer. Standard 'predict_tfbs()' runs embed the same controls in the Module 1 QC report. Exact co-binding queries run in a browser worker, and motif rankings show the true top 20 plus canonical TF references at their actual rank.

Usage

build_module1_tfbs_explorer(
  module1,
  multiomic_data = NULL,
  output_file = NULL,
  default_condition = NULL,
  project_config = NULL,
  rebuild_cache = FALSE,
  verbose = TRUE
)

Arguments

module1

A 'predict_tfbs()' result, Module 1 output directory, predicted TFBS table, table path, or manifest path.
multiomic_data

Optional CraftGRN multiomic object.
output_file

HTML output path.
default_condition

Initial condition. If 'NULL', use project configuration, control metadata, then A-Z order.
project_config

Optional YAML path or configuration list.
rebuild_cache

Rebuild the compact analysis cache even when valid.
verbose

Emit concise progress messages.

Value

Normalized path to the HTML report.

Build a Module 2 QC HTML report

Description

Builds a compact, review-oriented HTML report for Module 2 run parameters, CraftGRN multiomic input handoff, TF-target and FP-target correlation filters, candidate source and distance-to-TSS evidence, final TF-FP-target links, condition activity, warning and integrity checks, and related browser reports.

Usage

build_module2_qc_report(
  module2,
  multiomic_data = NULL,
  output_dir = NULL,
  report_name = "module2_qc_report.html",
  scan_large_tables = TRUE,
  validate_integrity = TRUE,
  top_n = 20L,
  verbose = TRUE
)

Arguments

module2

Module 2 result list, loaded Module 2 list, or output directory.
multiomic_data

Optional CraftGRN multiomic object used for context.
output_dir

Directory where the HTML report should be written. If 'NULL', the report is written under 'reports' inside the Module 2 output directory when available.
report_name

HTML report filename.
scan_large_tables

Logical; if 'TRUE', scan candidate and link chunks for top-TF, distance, and integrity summaries.
validate_integrity

Logical; if 'TRUE', verify final links against passing TF-target and FP-target keys while scanning link chunks.
top_n

Number of TFs to show in top-TF summaries.
verbose

Emit concise progress messages.

Value

Normalized path to the HTML report.

Build a Module 3 QC HTML report

Description

Writes a self-contained HTML report for Module 3 topic-model outputs. The report summarizes topic-input caches, model rows, theta separation scores, compact topic-link pass counts, and differential-link summaries when available.

Usage

build_module3_qc_report(
  topic_dir,
  output_dir = file.path(topic_dir, "reports"),
  differential_links_dir = NULL,
  title = "Module 3 QC report",
  top_n = 20L,
  verbose = TRUE
)

Arguments

topic_dir

Module 3 topic output directory.
output_dir

Directory where the report is written. Defaults to 'topic_dir/reports'.
differential_links_dir

Optional Module 3 differential-link directory. If 'NULL', CraftGRN tries to detect a sibling or nested 'differential_links' directory.
title

Report title.
top_n

Number of top differential TFs retained per comparison in the QC summary CSV.
verbose

Emit concise progress messages.

Value

Path to the HTML report.

Build an interactive TF UMAP report from predicted TFBS

Description

Build an interactive TF UMAP report from predicted TFBS

Usage

build_tfbs_umap_report(
  module1,
  output_file,
  top_variable_tfbs = 2000L,
  cluster_range = 2:12,
  default_clusters = 5L,
  seed = 1L,
  verbose = TRUE
)

Arguments

module1

A Module 1 result, output directory, predicted TFBS table, table path, or manifest path.
output_file

HTML output path.
top_variable_tfbs

Maximum number of variable footprint features.
cluster_range

Integer cluster counts offered in the HTML selector.
default_clusters

Initial cluster count.
seed

Random seed for UMAP and k-means.
verbose

Emit concise progress messages.

Value

Normalized path to the HTML report.

Perform sanity check for predicted links for Module 2 diagnostics

Description

Perform sanity check for predicted links for Module 2 diagnostics

Usage

check_predicted_links(module2)

Arguments

module2

Module 2 result list or loaded output list.

Value

TRUE invisibly when valid.

Return metadata for configured external CraftGRN demo data

Description

Return metadata for configured external CraftGRN demo data

Usage

craftgrn_demo_data_info(demo = NULL)

Arguments

demo

Optional demo bundle name. No external demo bundle is currently configured.

Value

A data frame with the bundle URL, checksum, archive file name, and extracted project directory name. When no demo bundle is configured, the returned data frame has zero rows.

Download and unpack configured external CraftGRN demo data

Description

Downloads a processed demo data archive from a configured external source, verifies its MD5 checksum by default, extracts it, and returns the extracted project directory. Demo bundles are external to the R package so package installation remains small and CRAN-friendly. No external demo bundle is currently configured.

Usage

download_craftgrn_demo_data(
  destdir = ".",
  demo = NULL,
  overwrite = FALSE,
  checksum = TRUE,
  verbose = TRUE
)

Arguments

destdir

Directory where the archive should be downloaded and unpacked.
demo

Optional demo bundle name. No external demo bundle is currently configured.
overwrite

Logical; if 'TRUE', download the archive again and replace an existing extracted project directory.
checksum

Logical; if 'TRUE', verify the downloaded archive MD5.
verbose

Logical; if 'TRUE', emit concise status messages.

Details

If the download fails, inspect 'craftgrn_demo_data_info()' and download the configured asset manually. If checksum verification fails, rerun with 'overwrite = TRUE' to replace a stale or partial archive. The extracted project uses 'base_dir: "."', so pass the returned directory or its project config path directly to package functions after moving the folder.

Value

The normalized path to the extracted demo project directory.

Examples

craftgrn_demo_data_info()

Export predicted TFBS as BED files

Description

Export predicted TFBS as BED files

Usage

export_predicted_tfbs_bed(
  predicted_tfbs,
  out_file = NULL,
  out_dir = NULL,
  tf = NULL,
  split_by = c("none", "tf")
)

Arguments

predicted_tfbs

Compact predicted TFBS table or path.
out_file

BED output path. Required when split_by is none.
out_dir

Directory for split BED outputs.
tf

Optional TF subset.
split_by

One of none or tf.

Value

Output path or manifest tibble, invisibly.

Export predicted TF-target links as BEDPE

Description

Export predicted TF-target links as BEDPE

Usage

export_tf_target_bedpe(module2, output_file, tf = NULL)

Arguments

module2

Module 2 result list or loaded output list.
output_file

BEDPE output file.
tf

Optional TF subset.

Value

Output path invisibly.

Load a CraftGRN YAML config into an environment

Description

Reads a YAML file and assigns each top-level key as a variable in the target environment (e.g., 'db', 'threshold_tf_expr', etc.). Also runs standard config initialization helpers when available.

Usage

load_config(path, env = .craftgrn_state)

Arguments

path

Character path to a YAML file.
env

Environment to populate. Defaults to the internal CraftGRN config state.

Value

(Invisibly) the parsed list.

Examples

config_path <- tempfile(fileext = ".yaml")
writeLines(c(
  "db: JASPAR2024",
  "ref_genome: hg38",
  "threshold_expr: 1",
  "threshold_fp_score: 0",
  "threshold_fp_tf_corr_r: 0.3",
  "threshold_rna_gene_corr_r: 0.3",
  "threshold_fp_gene_corr_r: 0.3"
), config_path)
load_config(config_path)
# Config values are now available to CraftGRN helper functions.

Load a multi-omic data object from disk

Description

Load a multi-omic data object from disk

Usage

load_omics_data(file, verbose = TRUE)

Arguments

file

Path to an RDS file produced by save_omics_data().
verbose

Emit status messages.

Value

The loaded multi-omic data list.

Load predicted links from Module 2

Description

Load predicted links from Module 2

Usage

load_predicted_links(path)

Arguments

path

Module 2 output directory or module2_manifest.csv path.

Value

A named list of Module 2 tables.

Load TFBS predicted from Module 1

Description

Load TFBS predicted from Module 1

Usage

load_predicted_tfbs(path)

Arguments

path

Path to a predicted TFBS manifest, Parquet file, or CSV file.

Value

A tibble.

Load and prepare the Module 1 multi-omic object

Description

Build the rebuilt Module 1 data object from cached aligned footprints or from raw footprint overview files plus RNA and sample metadata inputs. ATAC is optional; when it is absent, footprint-bound calls and footprint scores are used without an accessibility gate. The returned object is the canonical input for downstream Step 1 TFBS correlation.

Usage

load_prep_multiomic_data(
  config = NULL,
  project_date = NULL,
  genome = NULL,
  gene_symbol_col = "HGNC",
  fp_aligned = NULL,
  do_preprocess = FALSE,
  do_motif_clustering = FALSE,
  trim_hocomoco = FALSE,
  fp_root_dir = NULL,
  fp_input_format = NULL,
  fp_cache_dir = NULL,
  fp_cache_tag = NULL,
  footprint_sample_scope = "metadata",
  mid_slop = 10L,
  round_digits = 1L,
  score_match_pct = 0.8,
  output_mode = c("full", "distinct"),
  write_outputs = FALSE,
  write_fp_score_qn_csv = TRUE,
  atac_data = NULL,
  rna_tbl = NULL,
  metadata = NULL,
  atac_data_path = NULL,
  rna_path = NULL,
  metadata_path = NULL,
  step1_out_dir_name = "predict_tf_binding_sites",
  label_col,
  expected_n = NULL,
  tf_list = NULL,
  motif_db = NULL,
  threshold_gene_expr = NULL,
  threshold_fp_score = NULL,
  use_parallel = TRUE,
  verbose = TRUE,
  time_log = verbose
)

Arguments

config

Optional YAML config path.
project_date

Optional project date stored for reproducible reports.
genome

Optional genome string used to override the config value.
gene_symbol_col

Gene-symbol column in the RNA table.
fp_aligned

Optional pre-aligned footprint object.
do_preprocess

Logical; if 'TRUE', load and align raw footprints before building the object. If 'FALSE', use cached aligned footprints.
do_motif_clustering

Logical; if 'TRUE', run motif clustering during preprocessing when available.
trim_hocomoco

Logical; trim HOCOMOCO manifests when the trimming helper is available.
fp_root_dir

Optional root directory for raw footprint overview files.
fp_input_format

Footprint input layout. '"overview"' uses native per-motif overview files. '"fp_tools_compact"' imports fp-tools compact motif-site caches directly.
fp_cache_dir

Cache directory for aligned footprint files.
fp_cache_tag

Cache tag, typically the motif database name.
footprint_sample_scope

Footprint sample selection rule.
mid_slop, round_digits, score_match_pct

Alignment parameters passed to 'align_footprints()'.
output_mode

Output mode for aligned footprints. One of '"full"' or '"distinct"'.
write_outputs

Logical; if 'TRUE', save the prepared object as an RDS cache under 'predict_tf_binding_sites/'.
write_fp_score_qn_csv

Logical; if 'TRUE' and 'write_outputs = TRUE', also save quantile-normalized footprint scores as '01_fp_scores_qn_<db>.csv' under the Module 1 output directory.
atac_data, rna_tbl, metadata

Optional in-memory input tables. ATAC may be omitted; RNA and metadata remain required.
atac_data_path, rna_path, metadata_path

Optional explicit file paths for the input tables.
step1_out_dir_name

Output folder name under 'base_dir'.
label_col

Metadata column used to aggregate matched conditions.
expected_n

Optional expected matched sample count.
tf_list

Optional TF allowlist for downstream correlation.
motif_db

Optional motif metadata table.
threshold_gene_expr

Expression threshold for Step 1 expression flags.
threshold_fp_score

Footprint-score threshold for Step 1 bound flags. Supply one value for every sample or a named numeric vector with one value per sample id.
use_parallel

Logical; if 'TRUE', allow parallel work in supported helpers.
verbose

Logical; if 'TRUE', emit concise progress messages.
time_log

Logical; if TRUE, emit elapsed-time messages.

Value

A rebuilt Module 1 multi-omic object.

Examples

config_path <- "dev/config/pdac_nutrient_stress_strict_jaspar2024_demo.yaml"
if (file.exists(config_path)) {
  omics_data <- load_prep_multiomic_data(
    config = config_path,
    genome = "hg38",
    label_col = "strict_match_rna",
    do_preprocess = FALSE,
    verbose = TRUE
  )
}

Correlate TFs to their canonical TFBS

Description

Correlate TFs to their canonical TFBS

Usage

module1_correlate_TF_to_canonical_tfbs(
  module1_inputs,
  r_cutoff = 0.3,
  p_cutoff = NULL,
  fdr_cutoff = NULL,
  min_non_na = 3L,
  cores = NULL,
  verbose = TRUE
)

Arguments

module1_inputs

Output from module1_prepare_tfbs_inputs.
r_cutoff

Minimum positive best correlation.
p_cutoff

Optional best-method p-value cutoff.
fdr_cutoff

Optional best-method FDR cutoff.
min_non_na

Minimum finite condition pairs required.
cores

Number of worker cores; NULL uses all available cores.
verbose

Emit concise progress messages.

Value

A tibble with Pearson, Spearman, best-method statistics, and pass flags.

Filter footprints with canonical binding for full TFBS prediction

Description

Filter footprints with canonical binding for full TFBS prediction

Usage

module1_filter_canonical_bound_tfbs(
  module1_inputs,
  motif_supported_correlations,
  r_cutoff = 0.3,
  p_cutoff = NULL,
  fdr_cutoff = NULL,
  filter_to_canonical_bound = TRUE,
  verbose = TRUE
)

Arguments

module1_inputs

Output from module1_prepare_tfbs_inputs.
motif_supported_correlations

Output from module1_correlate_TF_to_canonical_tfbs.
r_cutoff

Minimum positive best correlation.
p_cutoff

Optional p-value cutoff.
fdr_cutoff

Optional FDR cutoff.
filter_to_canonical_bound

Keep only footprints with a passing motif-supported TF.
verbose

Emit concise progress messages.

Value

A list with canonical-bound and prediction footprint tables.

Predict full TFBS for all expressed TFs

Description

Predict full TFBS for all expressed TFs

Usage

module1_predict_full_tfbs(
  module1_inputs,
  prediction_footprints,
  out_dir = NULL,
  r_cutoff = 0.3,
  p_cutoff = NULL,
  fdr_cutoff = NULL,
  min_non_na = 3L,
  cores = NULL,
  write_outputs = FALSE,
  output_format = c("csv", "parquet", "auto"),
  return_prediction_stats = NULL,
  verbose = TRUE
)

Arguments

module1_inputs

Output from module1_prepare_tfbs_inputs.
prediction_footprints

Footprint table from module1_filter_canonical_bound_tfbs.
out_dir

Optional output directory. Required when 'write_outputs = TRUE'.
r_cutoff

Minimum positive best correlation.
p_cutoff

Optional best-method p-value cutoff.
fdr_cutoff

Optional best-method FDR cutoff.
min_non_na

Minimum finite condition pairs required.
cores

Number of worker cores; NULL uses all available cores.
write_outputs

Write predicted TFBS outputs. Defaults to 'FALSE' so calls do not write into the working directory unless an output directory is explicitly supplied.
output_format

One of csv, parquet, or auto.
return_prediction_stats

Return full prediction statistics in memory.
verbose

Emit concise progress messages.

Value

A list with prediction statistics or manifests and predicted TFBS outputs.

Prepare Module 1 TFBS prediction inputs

Description

Prepare Module 1 TFBS prediction inputs

Usage

module1_prepare_tfbs_inputs(
  omics_data,
  label_col = NULL,
  tf_subset = NULL,
  verbose = TRUE
)

Arguments

omics_data

CraftGRN multiomic object returned by 'load_prep_multiomic_data()'.
label_col

Optional metadata column used to rebuild condition matrices.
tf_subset

Optional TF symbols to keep.
verbose

Emit concise progress messages.

Value

A list containing prepared data, condition columns, TFs, and footprint universe.

Correlate FP score with target gene expression

Description

Correlate FP score with target gene expression

Usage

module2_correlate_fp_targets(
  module2_inputs,
  candidates,
  n_cores = NULL,
  verbose = TRUE
)

Arguments

module2_inputs

Output from module2_identify_candidate_links.
candidates

Output from module2_link_fp_targets.
n_cores

Number of worker cores; NULL uses all available cores.
verbose

Emit concise progress messages.

Value

An FP-target correlation table with pass flags.

Correlate TF expression with target gene expression

Description

Correlate TF expression with target gene expression

Usage

module2_correlate_tf_targets(module2_inputs, n_cores = NULL, verbose = TRUE)

Arguments

module2_inputs

Output from module2_identify_candidate_links.
n_cores

Number of worker cores; NULL uses all available cores.
verbose

Emit concise progress messages.

Value

A TF-target correlation table with pass flags.

Link TFs to potential target genes based on TFBS-TSS proximity or 3D interaction data

Description

Link TFs to potential target genes based on TFBS-TSS proximity or 3D interaction data

Usage

module2_identify_candidate_links(
  multiomic_data,
  predicted_tfbs,
  gene_tss = NULL,
  regulatory_prior = NULL,
  project_config = NULL,
  max_distance_bp = NULL,
  verbose = TRUE
)

Arguments

multiomic_data

CraftGRN multiomic object.
predicted_tfbs

Predicted TFBS table or path from Module 1.
gene_tss

Optional gene TSS table or path.
regulatory_prior

Optional generic FP-target prior.
project_config

Optional project config path or list.
max_distance_bp

Maximum signed distance to TSS.
verbose

Emit concise progress messages.

Value

A list of normalized Module 2 inputs used by downstream step functions.

Build restricted candidate FP-target links

Description

Build restricted candidate FP-target links

Usage

module2_link_fp_targets(module2_inputs, tf_target_corr, verbose = TRUE)

Arguments

module2_inputs

Output from internal Module 2 input preparation.
tf_target_corr

Output from module2_correlate_tf_targets.
verbose

Emit concise progress messages.

Value

A candidate table restricted by TF-target pass calls and genomic priors.

Assemble, filter, and output final predicted TF-FP-target links

Description

Assemble, filter, and output final predicted TF-FP-target links

Usage

module2_output_predicted_links(
  module2_inputs,
  candidates,
  tf_target_corr,
  fp_target_corr,
  output_dir = NULL,
  output_format = c("auto", "parquet", "csv"),
  verbose = TRUE
)

Arguments

module2_inputs

Output from [module2_identify_candidate_links()].
candidates

Candidate table from [module2_link_fp_targets()].
tf_target_corr

TF-target correlation table from [module2_correlate_tf_targets()].
fp_target_corr

FP-target correlation table from [module2_correlate_fp_targets()].
output_dir

Optional output directory.
output_format

One of auto, parquet, or csv.
verbose

Emit concise progress messages.

Value

A Module 2 result list.

Construct input documents for topic modeling

Description

Builds and caches the document-level link table, document-term table, sparse document-term matrix, and summary metadata used by Module 3 topic modeling.

Usage

module3_construct_docs(
  filtered_dir,
  output_dir,
  tf_cluster_map = NULL,
  check_repeated_values = FALSE,
  condition_document_unit = c("condition_tf", "condition"),
  condition_gene_token_fraction = 0.6,
  condition_document_token_budget = 1000000L,
  condition_specificity_temperature = 0.5,
  condition_specificity_floor = 0.1,
  ...
)

Arguments

filtered_dir

Directory containing Module 3 filtered differential-link CSV files.
output_dir

Directory where topic input caches are written.
tf_cluster_map

Named vector mapping TF names to motif clusters.
check_repeated_values

Warn about repeated inconsistent term values. The high-throughput default is 'FALSE'; set to 'TRUE' for diagnostic audits.
condition_document_unit

Condition-mode document unit. The standard '"condition_tf"' value builds one document per condition and TF. Experimental '"condition"' builds one document per condition from unique Gene and coordinate Peak terms.
condition_gene_token_fraction

Exact fraction of model tokens allocated to Gene terms in each condition document.
condition_document_token_budget

Exact total model tokens allocated to each condition document.
condition_specificity_temperature

Positive temperature controlling condition-specific feature weighting for condition documents.
condition_specificity_floor

Uniform baseline retained during condition-specific feature weighting.
...

Additional topic-document construction arguments passed to the internal Module 3 document builder.

Value

A list with cache paths and input summary counts.

Extract Module 3 regulatory topics

Description

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 standardized compact per-K input-design QC PDF and optimization audit tables. The PDF ends with the full-universe topic-assignment retention funnels.
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.

Value

Invisibly returns TRUE when extraction completes.

Prepare condition-native Module 3 links

Description

Builds per-condition TF-peak-gene links from Module 2 final links and the CraftGRN multiomic condition matrices. This path is used for condition topic models that should not depend on differential-link comparisons.

Usage

module3_prepare_condition_links(
  module2,
  multiomic_data,
  conditions = NULL,
  output_dir,
  threshold_fp_score = 0,
  threshold_gene_expr = 0,
  threshold_tf_expr = -Inf,
  output_format = c("auto", "parquet", "csv"),
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

module2

Module 2 output object or output directory.
multiomic_data

CraftGRN multiomic object.
conditions

Optional condition IDs to keep.
output_dir

Directory for per-condition link files and manifest.
threshold_fp_score

Minimum condition footprint score.
threshold_gene_expr

Minimum target-gene expression.
threshold_tf_expr

Minimum TF expression.
output_format

Output format: auto, parquet, or csv.
overwrite

Overwrite existing condition-link files.
verbose

Emit concise progress messages.

Value

A list containing the manifest and summary tables.

Prepare differential links for Module 3

Description

Converts Module 2 link manifests into the filtered differential-link files consumed by CraftGRN topic-modeling utilities. This avoids writing full per-condition GRN matrices and keeps Module 3 compatible with the existing '*_filtered_links_up.csv' and '*_filtered_links_down.csv' contract.

Usage

module3_prepare_differential_links(
  module2,
  multiomic_data,
  compar = NULL,
  project_config = NULL,
  output_dir = NULL,
  n_cores = NULL,
  pseudocount = 1,
  rna_de_results = NULL,
  fp_signal_mode = NULL,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

module2

Module 2 object returned by [predict_tf_targets()] or a path to a Module 2 output directory containing 'module2_manifest.csv'.
multiomic_data

CraftGRN multiomic object returned by [load_prep_multiomic_data()].
compar

Comparison table or CSV path with 'cond1_label' and 'cond2_label'. If 'NULL', 'data/episcope_comparisons.csv' under 'base_dir' is used.
project_config

Project config list or YAML path.
output_dir

Directory for filtered differential links. If 'NULL', 'regulatory_topics/differential_links' under 'base_dir' is used.
n_cores

Number of data.table threads to use while reading and joining chunks. Defaults to all available cores. Comparison-level parallelism is controlled by 'module3_comparison_workers' in the project config and defaults to 1 for RAM safety.
pseudocount

Pseudocount for log2 fold-change calculations.
rna_de_results

Optional standardized RNA differential expression table or CSV. When provided, target-gene and TF log2 fold changes are read from this table and direct condition fold changes are used only for missing genes.
fp_signal_mode

FP signal used for differential FP fold changes. actual uses the measured FP score in both conditions. link_padded sets the FP score to zero in conditions where the TF-FP-gene link is not active before calculating delta_fp_score and log2FC_fp_score.
overwrite

Overwrite existing filtered link files.
verbose

Emit concise progress messages.

Value

A tibble manifest with one row per comparison.

Train Module 3 topic models

Description

Public step function for training one Module 3 topic-model setup after [module3_prepare_differential_links()] has produced filtered differential links. This is a thin Module 3-named wrapper around the internal training engine.

Usage

module3_train_topic_models(
  k_grid,
  filtered_dir,
  output_dir,
  flat_output = TRUE,
  ...
)

Arguments

k_grid

Integer vector of K values for training.
filtered_dir

Directory containing Module 3 filtered differential-link files.
output_dir

Directory to write topic model outputs.
flat_output

Whether to write this selected setup directly under 'output_dir'. Defaults to 'TRUE' for the public step API.
...

Additional arguments passed to the internal training engine, such as 'doc_design', 'fp_term_mode', 'backend', and 'local_threads'.

Value

Invisibly returns TRUE when training completes.

Output predicted TFBS

Description

Output predicted TFBS

Usage

output_predicted_tfbs(
  prediction_stats,
  out_dir = NULL,
  output_format = c("auto", "parquet", "csv"),
  include_support = TRUE
)

Arguments

prediction_stats

Module 1 TFBS prediction statistic table.
out_dir

Optional output directory. If supplied, a predicted TFBS table and manifest are written for Module 2.
output_format

Output format: auto, parquet, or csv.
include_support

Include compact condition support when available.

Value

A predicted TFBS tibble when 'out_dir' is NULL; otherwise a list with output paths and row counts.

Plot a TF-TF co-binding heatmap

Description

Plot a TF-TF co-binding heatmap

Usage

plot_tf_tf_cobinding_heatmap(
  module1,
  metric = c("absolute", "jsd"),
  max_tfs = 100L,
  verbose = TRUE
)

Arguments

module1

A Module 1 result, output directory, predicted TFBS table, table path, or manifest path.
metric

Heatmap metric: absolute shared-site counts or Jensen-Shannon distance ('jsd').
max_tfs

Maximum number of TFs, ranked by predicted TFBS count.
verbose

Emit concise progress messages.

Value

A ggplot heatmap with 'cobinding_matrix' and 'tf_order' attributes.

Plot TFBS changes between two conditions

Description

Summarizes active predicted TFBS and footprint signal for each TF. A TFBS is active when its footprint is bound and its TF is expressed in the condition.

Usage

plot_tfbs_condition_comparison(
  module1,
  multiomic_data = NULL,
  cond1,
  cond2,
  pseudocount = 1,
  label_top_n = 15L,
  verbose = TRUE
)

Arguments

module1

A 'predict_tfbs()' result, Module 1 output directory, predicted TFBS table, table path, or manifest path.
multiomic_data

Optional CraftGRN multiomic object. It may be omitted when it is present in 'module1'.
cond1, cond2

Condition names. Changes are computed as cond1 relative to cond2.
pseudocount

Positive pseudocount for log2 fold changes.
label_top_n

Number of the most divergent TFs to label.
verbose

Emit concise progress messages.

Value

A ggplot object with the TF summary attached as 'tfbs_summary'.

Predict TF targets through TFBS-target and TF-target correlations

Description

Predict TF targets through TFBS-target and TF-target correlations

Usage

predict_tf_targets(
  multiomic_data,
  predicted_tfbs,
  gene_tss = NULL,
  regulatory_prior = NULL,
  project_config = NULL,
  output_dir = NULL,
  max_distance_bp = NULL,
  n_cores = NULL,
  output_format = c("auto", "parquet", "csv"),
  verbose = TRUE,
  write_qc_report = TRUE,
  qc_report_validate = FALSE
)

Arguments

multiomic_data

CraftGRN multiomic object returned by 'load_prep_multiomic_data()'.
predicted_tfbs

Compact Module 1 predicted TFBS table or manifest path.
gene_tss

Optional gene TSS annotation table or path. If 'NULL', the table is resolved from 'project_config$gene_tss' or generated from the configured 'ref_genome'.
regulatory_prior

Optional generic FP-target regulatory prior.
project_config

Optional project YAML path or list.
output_dir

Optional output directory.
max_distance_bp

Maximum signed distance to TSS for window candidates.
n_cores

Number of CPU cores.
output_format

Output format: auto, parquet, or csv.
verbose

Emit concise progress messages.
write_qc_report

Write a Module 2 HTML QC report when 'output_dir' is supplied.
qc_report_validate

Run relational integrity checks in the automatic QC report.

Value

Compact Module 2 relational result list.

Predict transcription factor binding sites from matched footprint and RNA data

Description

Run the Module 1 TFBS workflow as one user-facing operation. The function first uses motif-supported FP-TF correlations to define high-confidence footprints, then predicts sparse FP-TF binding events for expressed TFs.

Usage

predict_tfbs(
  omics_data,
  out_dir = NULL,
  db = "JASPAR2024",
  label_col = NULL,
  project_config = NULL,
  project_date = NULL,
  r_cutoff = 0.3,
  p_cutoff = NULL,
  fdr_cutoff = NULL,
  filter_to_canonical_bound = TRUE,
  tf_subset = NULL,
  write_outputs = FALSE,
  write_stats = FALSE,
  write_bed = FALSE,
  write_qc_report = TRUE,
  write_tfbs_explorer = TRUE,
  qc_report_scan = FALSE,
  output_format = c("csv", "parquet", "auto"),
  return_prediction_stats = NULL,
  prediction_return_limit = getOption("craftgrn.module1_prediction_return_limit", 5e+06),
  min_non_na = 3L,
  cores = NULL,
  verbose = TRUE,
  time_log = verbose
)

Arguments

omics_data

CraftGRN multiomic object returned by 'load_prep_multiomic_data()'.
out_dir

Optional output directory. Required when 'write_outputs = TRUE'.
db

Motif database label used in output metadata.
label_col

Metadata column used to build condition-level matrices when missing from 'omics_data'.
project_config

Optional YAML path or list recorded in the QC report. It does not change analysis parameters.
project_date

Optional date displayed in the QC report.
r_cutoff

Minimum positive correlation used for motif-supported and prediction calls.
p_cutoff

Optional best-method p-value cutoff. If 'NULL', p-value filtering is disabled.
fdr_cutoff

Optional best-method adjusted p-value cutoff. If 'NULL', FDR filtering is disabled.
filter_to_canonical_bound

Logical; if 'TRUE', only footprints with at least one motif-supported TF passing the cutoffs are used for the all-expressed-TF prediction stage.
tf_subset

Optional TF subset.
write_outputs

Write Module 1 output files. Defaults to 'FALSE' so calls do not write into the working directory unless an output directory is explicitly supplied.
write_stats

Retain and write full FP-TF correlation statistics.
write_bed

Write optional BED-like browser files for high-confidence footprints and in-memory TFBS prediction statistics.
write_qc_report

Write a Module 1 HTML QC report when outputs are written.
write_tfbs_explorer

Embed the interactive Binding, Co-binding, and Motif explorer sections in the Module 1 QC HTML report.
qc_report_scan

Scan predicted TFBS chunks for top-TF summaries in the QC report.
output_format

Output format for large streamed TFBS prediction statistic chunks.
return_prediction_stats

Return the TFBS prediction statistic table in memory. If 'NULL', large output-writing runs are streamed to disk and return a manifest.
prediction_return_limit

Maximum number of predicted events to keep in memory when 'return_prediction_stats = NULL' and 'write_outputs = TRUE'.
min_non_na

Minimum finite condition pairs required for correlation.
cores

Number of worker cores for the dense prediction correlation step. If 'NULL', use available cores.
verbose

Emit concise progress messages.
time_log

Logical; if TRUE, emit elapsed-time messages.

Value

A list containing 'omics_data', 'high_confidence_footprints', 'motif_supported_correlations', 'prediction_stats', 'predicted_tfbs', 'prediction_stats_manifest', 'reports', and 'parameters'.

Query specific links by TF(s) and/or distance to TSS

Description

Query specific links by TF(s) and/or distance to TSS

Usage

query_predicted_links(
  module2,
  tf = NULL,
  fp_id = NULL,
  target_gene = NULL,
  max_distance_to_tss = NULL,
  pass_only = TRUE
)

Arguments

module2

Module 2 result list or loaded output list.
tf

Optional TF filter.
fp_id

Optional FP filter.
target_gene

Optional target-gene filter.
max_distance_to_tss

Optional maximum absolute distance to TSS.
pass_only

Keep only passing links.

Value

A tibble of matching final links.

Export an interactive HTML browser of direct TF-TF regulations

Description

Export an interactive HTML browser of direct TF-TF regulations

Usage

report_direct_tf_tf_regulations(
  module2,
  output_dir,
  multiomic_data = NULL,
  k_values = c(5L, 7L, 10L),
  verbose = TRUE
)

Arguments

module2

Module 2 result list, loaded output list, or output directory.
output_dir

Output directory.
multiomic_data

Optional CraftGRN multiomic object for condition-filtered reports.
k_values

Cluster counts.
verbose

Emit concise progress messages.

Value

A tibble report manifest.

Export an interactive HTML browser of TF-TF co-regulatory activities

Description

Export an interactive HTML browser of TF-TF co-regulatory activities

Usage

report_tf_tf_coregulations(
  module2,
  output_dir,
  multiomic_data = NULL,
  k_values = c(5L, 7L, 10L),
  verbose = TRUE
)

Arguments

module2

Module 2 result list, loaded output list, or output directory.
output_dir

Output directory.
multiomic_data

Optional CraftGRN multiomic object for condition-filtered reports.
k_values

Cluster counts.
verbose

Emit concise progress messages.

Value

A tibble report manifest.

Export an interactive HTML browser of individual TF regulons

Description

Export an interactive HTML browser of individual TF regulons

Usage

report_top_tf_targets(
  module2,
  output_dir,
  tfs,
  top_n = 100L,
  default_top_n = NULL,
  verbose = TRUE,
  multiomic_data = NULL,
  conditions = NULL,
  combine_tfs = FALSE,
  default_condition = NULL,
  max_linked_tfs = 50L,
  max_linked_tfs_per_target = 2L,
  supporting_module2 = NULL,
  default_fp_r_cutoff = 0.5,
  expression_pseudocount = 1,
  target_genes = NULL
)

Arguments

module2

Module 2 result list, loaded output list, or output directory.
output_dir

Output directory.
tfs

TFs to report.
top_n

Number of top targets per TF.
default_top_n

Initial number of targets displayed in the browser. The default displays the complete embedded target set.
verbose

Emit concise progress messages.
multiomic_data

Optional CraftGRN multiomic object used to precompute condition activity and expression for the browser.
conditions

Optional conditions to include. The default includes all conditions available in 'multiomic_data'.
combine_tfs

Combine all requested TFs into one global target-union browser. The default writes one browser per TF.
default_condition

Initial condition shown by the browser.
max_linked_tfs

Maximum number of non-seed supporting TFs.
max_linked_tfs_per_target

Maximum supporting TFs retained per target.
supporting_module2

Optional full Module 2 result or output directory used only to add non-seed TFs regulating the selected seed-TF targets.
default_fp_r_cutoff

Initial strict FP R cutoff shown by the browser.
expression_pseudocount

Pseudocount for differential node log2 fold changes.
target_genes

Optional target-gene subset embedded in each TF browser. The default ranks all predicted targets before applying 'top_n'. Use 'top_n = Inf' to retain the complete predicted or supplied target set.

Value

A tibble report manifest.

Resolve gene symbols to formal species-specific symbols

Description

Resolves human or mouse gene names using Bioconductor organism annotation packages when available, with a deterministic case-normalized fallback when formal annotation is unavailable or a symbol has no database match.

Usage

resolve_gene_symbols(
  genes,
  species = NULL,
  ref_genome = NULL,
  use_annotation = TRUE,
  allow_heuristic = TRUE
)

Arguments

genes

Character vector of gene names or identifiers.
species

Species name, either '"human"' or '"mouse"'.
ref_genome

Optional reference genome such as '"hg38"' or '"mm10"'. Used to infer 'species' when 'species' is 'NULL'.
use_annotation

Logical; use AnnotationDbi and organism annotation packages when available.
allow_heuristic

Logical; use case-normalized fallback for unmatched symbols or when annotation packages are unavailable.

Value

A data frame with one row per input gene and columns describing the canonical symbol, matching key, match source, and ambiguity status.

Run the Shiny Application

Description

Run the Shiny Application

Usage

run_app(
  onStart = NULL,
  options = list(),
  enableBookmarking = NULL,
  uiPattern = "/",
  ...
)

Arguments

onStart

A function that will be called before the app is actually run. This is only needed for shinyAppObj, since in the shinyAppDir case, a global.R file can be used for this purpose.
options

Named options that should be passed to the runApp call (these can be any of the following: "port", "launch.browser", "host", "quiet", "display.mode" and "test.mode"). You can also specify width and height parameters which provide a hint to the embedding environment about the ideal height/width for the app.
enableBookmarking

Can be one of "url", "server", or "disable". The default value, NULL, will respect the setting from any previous calls to enableBookmarking(). See enableBookmarking() for more information on bookmarking your app.
uiPattern

A regular expression that will be applied to each GET request to determine whether the ui should be used to handle the request. Note that the entire request path must match the regular expression in order for the match to be considered successful.
...

arguments to pass to golem_opts. See '?golem::get_golem_options' for more details.

Value

A Shiny application object returned by 'shiny::shinyApp()'. Calling this function is primarily useful for its side effect of launching the app in interactive use.

Run topic modeling

Description

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_alpha_sum = 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,
  final_peak_gene_token_ratio = NULL,
  condition_term_idf = NULL,
  condition_term_idf_floor = 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,
  vae_topic_diversity_regularization = NULL,
  vae_document_topic_separation_regularization = NULL,
  vae_topic_initialization = NULL,
  vae_topic_word_temperature = NULL,
  vae_peak_gene_map = NULL,
  vae_validation_fraction = 0,
  vae_early_stopping_patience = 0L,
  vae_weight_decay = 0,
  vae_kl_warmup_epochs = 0L,
  vae_dropout = 0,
  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_alpha_sum

Total document-topic prior mass. The per-topic alpha is this value divided by K. If 'NULL', use project config or '50'.
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 Peak weighting. Use '"tf_expression"' to multiply balanced aggregate or coordinate 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'.
final_peak_gene_token_ratio

Optional final Peak/Gene model-token ratio for condition::TF documents after pseudo-count conversion. 'NULL' preserves legacy counts.
condition_term_idf

Whether to downweight terms present across many conditions while preserving each document's total model tokens.
condition_term_idf_floor

Minimum multiplier for a term found in every condition. Must be between zero and one.
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 standardized compact per-K input-design 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 '1' for MultiVI and '0' for other VAE variants.
vae_topic_diversity_regularization

Non-negative penalty for similar Gene and Peak topic distributions. If 'NULL', read from project config or use the model-specific default.
vae_document_topic_separation_regularization

Non-negative penalty that encourages distinct document-topic mixtures and broad topic use.
vae_topic_initialization

Topic initialization. Use '"random"' or '"document_anchor"'; 'NULL' reads project config or uses the model default.
vae_topic_word_temperature

Positive topic-word softmax temperature.
vae_peak_gene_map

Optional CSV with 'peak_id' and 'gene_key' columns used to regularize coordinate Peak and Gene topic distributions.
vae_validation_fraction

Fraction of each document's integer tokens held out for validation. Zero preserves legacy full-data training.
vae_early_stopping_patience

Validation epochs without improvement before stopping. Zero disables early stopping.
vae_weight_decay

Non-negative Adam weight decay.
vae_kl_warmup_epochs

Number of epochs used to increase the KL weight from zero to one. Zero disables warmup.
vae_dropout

Encoder dropout in '[0, 1)'.
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.

Value

An invisible list with topic input/model/extraction paths, review outputs, and 'qc_report' when requested.

Save a multi-omic data object to disk

Description

Save a multi-omic data object to disk

Usage

save_omics_data(
  omics_data,
  file = NULL,
  out_dir = NULL,
  db = NULL,
  prefix = "omics_data",
  compress = "xz",
  verbose = TRUE
)

Arguments

omics_data

A multi-omic data list (e.g., output of load_prep_multiomic_data()).
file

Optional full path to an RDS file. If NULL, uses out_dir/db/prefix.
out_dir

Output directory used when file is NULL.
db

Optional database tag appended to the filename when file is NULL.
prefix

Filename prefix used when file is NULL.
compress

Compression passed to saveRDS().
verbose

Emit status messages.

Value

Path to the written file (invisible).

Validate config values

Description

Ensures required config keys (e.g. thresholds and db) exist in the chosen environment before running pipelines.

Usage

validate_config(
  required = c("db", "ref_genome", "threshold_expr", "threshold_fp_score",
    "threshold_fp_tf_corr_r", "link_window_bp", "threshold_rna_gene_corr_r",
    "threshold_fp_gene_corr_r"),
  numeric_required = c("threshold_expr", "threshold_fp_score", "threshold_fp_tf_corr_r",
    "link_window_bp", "threshold_rna_gene_corr_r", "threshold_fp_gene_corr_r"),
  env = .craftgrn_state,
  project_config = NULL
)

Arguments

required

Character vector of required variable names.
numeric_required

Character vector of required numeric variable names.
env

Environment to check. Defaults to the internal CraftGRN config state.
project_config

Optional parsed project config or YAML path to validate against the package project schema. Unknown or malformed entries fail.

Value

TRUE invisibly when validation passes.

Export an interactive HTML browser of differential GRNs

Description

Builds an interactive TF-to-gene network browser from Module 3 filtered differential links. Users can select a comparison, choose up or down differential links, adjust the number of top TFs and links to display, and inspect footprint-supported edge evidence in tooltips.

Usage

visualize_differential_grns(
  differential_links_dir,
  output_dir = file.path(differential_links_dir, "reports"),
  top_tf_n = 10L,
  top_link_n = 300L,
  default_direction = "up",
  browser_max_rows_per_file = 50000L,
  top_n = NULL,
  verbose = TRUE
)

Arguments

differential_links_dir

Module 3 differential-link directory.
output_dir

Directory where the browser HTML and CSV summaries are written.
top_tf_n

Default number of top TFs shown in the browser.
top_link_n

Default number of top TF-to-gene links shown in the browser.
default_direction

Initial direction selected in the browser.
browser_max_rows_per_file

Maximum filtered-link rows read from each comparison/direction file when building the browser payload. The full filtered-link CSVs remain the authoritative data source; this cap keeps the self-contained HTML browser responsive for large projects.
top_n

Deprecated compatibility alias for top_tf_n.
verbose

Emit concise progress messages.

Value

Path to the HTML browser.

Export interactive HTML browsers of topic modeling results

Description

Builds a self-contained index browser for existing Module 3 topic-modeling review outputs at the topic, condition, comparison, and pathway levels. This function organizes existing outputs and does not train or extract models.

Usage

visualize_topic_modeling_results(
  topic_dir,
  output_dir = file.path(topic_dir, "reports"),
  include = c("topic", "condition", "comparison", "pathway"),
  verbose = TRUE
)

Arguments

topic_dir

Module 3 topic output directory.
output_dir

Directory where the browser HTML and manifest are written.
include

Existing output families to include.
verbose

Emit concise progress messages.

Value

Path to the HTML browser.