Configure lisaR in R, YAML or JSON

Compare one complete configuration in three formats

A named R list, YAML and JSON describe the same study. Here is a complete R list with two analyses, one contrast and four collections. Its resource identifiers select the installed sample fixtures.

library(lisaR)

cfg <- list(
  pipeline = list(
    schema_version = "1.0.0",
    profile = "transcriptomic/genomic",
    evidence_mode = "full_de",
    output_dir = "results/minimal-study",
    dry_run = TRUE,
    workers = 4L,
    dictionary_resource = "lisa_dictionary_quickstart@1.1.0",
    term2gene_resource = "lisa_quickstart_term2gene@2.1.0",
    category_map_resource = "lisa_quickstart_category_map@1.1.0",
    run_kegg_maps = FALSE,
    run_hallmarks = FALSE,
    sufficiency_action = "ignore_with_reason",
    sufficiency_ignore_reason = "Bundled synthetic sample dataset; the restricted universe is intentional.",
    duplicate_policies = list(
      de_table_duplicate_policy = "error",
      matrix_duplicate_policy = "error",
      mapped_id_collision_policy = "error"
    )
  ),
  report = list(
    mode = "standard",
    category_evidence = TRUE,
    category_nes_variants = c("clean", "percentages", "direction", "dispersion"),
    legacy_gene_products = FALSE,
    evidence_max_sets = 25L,
    evidence_max_genes = 40L,
    formats = list(png = TRUE, svg = FALSE, pdf = FALSE),
    source_data = TRUE,
    recipes = FALSE
  ),
  collections = c("GOBP-C2", "GOMF", "GOCC", "PATHWAYS"),
  single_de = list(
    list(
    analysis_id = "treatment",
    de_path = system.file("extdata", "minimal", "de_A.tsv", package = "lisaR"),
    species = "Homo sapiens",
    symbol_col = "symbol",
    logfc_col = "log2FC",
    padj_col = "padj"),
    list(
    analysis_id = "control",
    de_path = system.file("extdata", "minimal", "de_B.tsv", package = "lisaR"),
    species = "Homo sapiens",
    symbol_col = "symbol",
    logfc_col = "log2FC",
    padj_col = "padj")
  ),
  contrasts = list(list(
    contrast_id = "treatment_vs_control",
    analysis_a = "treatment",
    analysis_b = "control",
    contrast_label = "Treatment versus control"
  ))
)

validation <- validate_lisa_config(cfg, check_files = FALSE)
stopifnot(validation$structural_valid, !validation$execution_ready)
validation$readiness

##          stage checked ready      status
## 1    structure    TRUE  TRUE       ready
## 2       inputs   FALSE    NA not_checked
## 3 dependencies    TRUE  TRUE       ready
## 4    resources   FALSE    NA not_checked
## 5    execution    TRUE FALSE   not_ready

The structure passes, but inputs and resources remain not_checked, so this check alone does not establish execution readiness. These sample tables use their signed effect as the ranking because they have no separate signed test-statistic column. For real DESeq2 or limma results, declare the appropriate rank_col explicitly.

Before execution, validate with check_files = TRUE and require execution_ready to be TRUE. Obtain and register real resources through the resource workflow; do not substitute sample fixtures into a scientific study.

Inspect what lisaR actually resolved

Validation, planning and configured execution share the same resolution rules. Defaults and supplied values are visible without learning a new configuration format:

validation$config$report

## $category_evidence
## [1] TRUE
##
## $category_nes_variants
## $category_nes_variants[[1]]
## [1] "clean"
##
## $category_nes_variants[[2]]
## [1] "percentages"
##
## $category_nes_variants[[3]]
## [1] "direction"
##
## $category_nes_variants[[4]]
## [1] "dispersion"
##
##
## $evidence_max_genes
## [1] 40
##
## $evidence_max_sets
## [1] 25
##
## $formats
## $formats$pdf
## [1] FALSE
##
## $formats$png
## [1] TRUE
##
## $formats$svg
## [1] FALSE
##
##
## $legacy_gene_products
## [1] FALSE
##
## $mode
## [1] "standard"
##
## $recipes
## [1] FALSE
##
## $source_data
## [1] TRUE

validation$configuration_provenance[
  validation$configuration_provenance$field %in% c(
    "report.category_evidence", "report.category_nes_variants",
    "pipeline.gsea_padj_cutoff", "pipeline.cache_mode"
  ),
]

##                           field                                  value   source
## 5     pipeline.gsea_padj_cutoff                                   0.25  default
## 14          pipeline.cache_mode                                    off  default
## 30     report.category_evidence                                   TRUE explicit
## 34 report.category_nes_variants clean;percentages;direction;dispersion explicit
##                          origin
## 5     pipeline.gsea_padj_cutoff
## 14          pipeline.cache_mode
## 30     report.category_evidence
## 34 report.category_nes_variants

validation$config contains resolved values and paths; configuration_provenance identifies defaults and explicit declarations. A completed run records these as config/pipeline_config.normalized.json and config/configuration_provenance.tsv. Preserve the original study file as well. Resolved absolute paths are useful locally, but are not a portable replacement for the original relative-path configuration.

Use strict validation, the default. Unknown fields raise an error rather than silently changing the run. strict = FALSE is for inspecting older files; it still checks known types and scientific contracts, and run_lisa() always validates strictly.

The following YAML and JSON are complete equivalents of the R list. The R list uses system.file() because it has no containing configuration file; the two file formats use the same sample paths relative to the directory that contains the saved configuration.

pipeline:
  schema_version: "1.0.0"
  profile: "transcriptomic/genomic"
  evidence_mode: "full_de"
  output_dir: "results/minimal-study"
  workers: 4
  dry_run: true
  dictionary_resource: "lisa_dictionary_quickstart@1.1.0"
  term2gene_resource: "lisa_quickstart_term2gene@2.1.0"
  category_map_resource: "lisa_quickstart_category_map@1.1.0"
  run_kegg_maps: false
  run_hallmarks: false
  sufficiency_action: "ignore_with_reason"
  sufficiency_ignore_reason: "Bundled synthetic sample dataset; the restricted universe is intentional."
  duplicate_policies:
    de_table_duplicate_policy: "error"
    matrix_duplicate_policy: "error"
    mapped_id_collision_policy: "error"
report:
  mode: "standard"
  category_evidence: true
  category_nes_variants: [clean, percentages, direction, dispersion]
  legacy_gene_products: false
  evidence_max_sets: 25
  evidence_max_genes: 40
  formats: {png: true, svg: false, pdf: false}
  source_data: true
  recipes: false
collections: ["GOBP-C2", "GOMF", "GOCC", "PATHWAYS"]
single_de:
  - analysis_id: "treatment"
    de_path: "../extdata/minimal/de_A.tsv"
    species: "Homo sapiens"
    symbol_col: "symbol"
    logfc_col: "log2FC"
    padj_col: "padj"
  - analysis_id: "control"
    de_path: "../extdata/minimal/de_B.tsv"
    species: "Homo sapiens"
    symbol_col: "symbol"
    logfc_col: "log2FC"
    padj_col: "padj"
contrasts:
  - contrast_id: "treatment_vs_control"
    analysis_a: "treatment"
    analysis_b: "control"
    contrast_label: "Treatment versus control"

{
  "pipeline": {
    "schema_version": "1.0.0",
    "profile": "transcriptomic/genomic",
    "evidence_mode": "full_de",
    "output_dir": "results/minimal-study",
    "workers": 4,
    "dry_run": true,
    "dictionary_resource": "lisa_dictionary_quickstart@1.1.0",
    "term2gene_resource": "lisa_quickstart_term2gene@2.1.0",
    "category_map_resource": "lisa_quickstart_category_map@1.1.0",
    "run_kegg_maps": false,
    "run_hallmarks": false,
    "sufficiency_action": "ignore_with_reason",
    "sufficiency_ignore_reason": "Bundled synthetic sample dataset; the restricted universe is intentional.",
    "duplicate_policies": {
      "de_table_duplicate_policy": "error",
      "matrix_duplicate_policy": "error",
      "mapped_id_collision_policy": "error"
    }
  },
  "report": {
    "mode": "standard",
    "category_evidence": true,
    "category_nes_variants": ["clean", "percentages", "direction", "dispersion"],
    "legacy_gene_products": false,
    "evidence_max_sets": 25,
    "evidence_max_genes": 40,
    "formats": {"png": true, "svg": false, "pdf": false},
    "source_data": true,
    "recipes": false
  },
  "collections": ["GOBP-C2", "GOMF", "GOCC", "PATHWAYS"],
  "single_de": [
    {"analysis_id": "treatment", "de_path": "../extdata/minimal/de_A.tsv", "species": "Homo sapiens", "symbol_col": "symbol", "logfc_col": "log2FC", "padj_col": "padj"},
    {"analysis_id": "control", "de_path": "../extdata/minimal/de_B.tsv", "species": "Homo sapiens", "symbol_col": "symbol", "logfc_col": "log2FC", "padj_col": "padj"}
  ],
  "contrasts": [
    {"contrast_id": "treatment_vs_control", "analysis_a": "treatment", "analysis_b": "control", "contrast_label": "Treatment versus control"}
  ]
}

Choose safe paths and identifiers

Paths in YAML or JSON start from the folder that contains the configuration file. Paths in an R list start from the current working directory. pipeline.output_dir tells lisaR where to save the finished analysis. Work in progress stays separate and is promoted to the new final destination only after all checks pass. It does not replace an existing completed run.

Technical identifiers that become directory or file-name components use one portable ASCII grammar. These include run_id, analysis_id, contrast_id, output_id, file_label_prefix and source_data.target_subdir.

lisaR rejects invalid identifiers instead of silently rewriting them. Keep readable Unicode in the separate label, contrast_label, report_title, comparison and other display-text fields. External scientific keys are not relabelled: for example, a KEGG key such as hsa:1 remains hsa:1 in the API and provenance, while lisaR derives a deterministic ASCII-only component for its private cache path.

On Unix-like systems, lisaR keeps both areas private: staging and final result directories are 0700, and their files are 0600. Existing ancestor permissions are not changed. For a shared HPC project, require verify_lisa_run(...)$gate to be "PASS" before deliberately granting group access according to the institutional policy.

Use a new local output directory that other processes cannot modify while the analysis is running. lisaR checks managed paths, builds the run in a private staging directory and exposes it only after validation. Network and shared filesystems can have different rename and locking behaviour; use them only when your institution has validated that behaviour for lisaR. See Troubleshooting for recovery and diagnostic guidance.

Set pipeline inputs and resources

Required fields:

• schema_version: the configuration format, currently "1.0.0". This is distinct from the package version and the visible “1.0 beta” label.
• profile: transcriptomic/genomic, global proteomic, targeted or custom.
• evidence_mode: full_de, rank_only, effect_only or custom.
• output_dir: new destination for the run.
• duplicate_policies: explicit policy for DE tables, expression matrices and mapped-identifier collisions.

schema_version is not a request to use the newest package release. It tells lisaR how to interpret the fields in the file. Keep it fixed until you deliberately migrate the configuration to a different schema.

full_de requires an effect and adjusted significance, rank_only requires a ranking value, and effect_only requires an effect. Typical source-column mappings are:

Do not use padj or FDR as a ranking value: it has no direction and often contains ties. For DESeq2, a common full_de entry uses logfc_col: log2FoldChange, padj_col: padj and rank_col: stat.

For the advanced custom mode, declare the evidence explicitly:

pipeline:
  evidence_mode: custom
  evidence:
    required_columns: [effect, significance]
    products: []

The values in required_columns are evidence roles: effect, significance and rank. Map them to real columns with logfc_col, padj_col and rank_col in each single_de entry. products records your declared product compatibility as provenance; it does not enable a product or override its own data requirements.

Resource selection fields:

• dictionary_resource: versioned, registered LISA dictionary.
• term2gene_resource: versioned, registered gene-set memberships used by gene set enrichment analysis (GSEA).
• category_map_resource: registered LISA category-map resource.
• lisa_dictionary: optional core or expanded tier selector. Omit it when selecting a custom dictionary resource.

You may omit all three resource IDs in an ordinary configuration. lisaR then selects lisa_dictionary_core@1.0.0, msigdb_term2gene@2026.1 and lisa_category_map@1.0.0 by default. Leaving those IDs explicit is also valid and can make review easier. The core and expanded dictionary resources are bundled as lisa_dictionary_core@1.0.0 and lisa_dictionary_expanded@1.0.0. Both use the score-free lisa_dictionary@2 file schema. The bundled category map uses the category_map@1 schema. The default MSigDB TERM2GENE memberships are external: obtain them through the authorised resource route, then register the exact versioned file. The synthetic sample resources are also bundled, but are not scientific substitutes for a study.

Use explicit name@version overrides for reviewed alternatives. Custom dictionaries and supercategory maps must be registered and validated together with their TERM2GENE resource; see Custom dictionaries and supercategories.

Look up exact fields and defaults

This is the shared field reference for named R lists, YAML and JSON. Required means required by schema 1.0.0, not merely recommended. A blank default means the field is optional and has no parser-supplied value. A file path is resolved from the YAML/JSON file’s directory, or from the current working directory for an R list.

The schema rejects unknown fields. The parser recognises the older output keys only to issue a migration error; do not use plot_formats, export_formats, run_reports or run_gene_level in a 1.0.0 study.

Choose report products

report is a top-level section, alongside pipeline; do not nest it under pipeline.

The matrix limits restrict the displayed view, not the complete evidence tables or the recurrence counts. The report provides a shared navigation header, a category navigator after the LISA overview graphics and a member-gene-set chart at the end of the corresponding category sheet. There is no duplicate visible category table or separate gallery of those member charts.

The Hommel category-significance view is a separate automatic product of a completed run_lisa() analysis when applicable. Its four adjusted-P star thresholds are presentation conventions, not an additional value of report.category_nes_variants or a configurable inferential cutoff. The four NES variants remain descriptive; HALLMARKS and A/B profile contrasts do not gain category inference.

category_nes_variants: [clean, percentages, direction, dispersion]  # default: all four

category_nes_variants: [clean]  # one clean overview

category_nes_variants: [dispersion]  # one overview with all annotations

clean_only <- cfg
clean_only$report$category_nes_variants <- "clean"
clean_check <- validate_lisa_config(clean_only, check_files = FALSE)
stopifnot(identical(
  unlist(clean_check$config$report$category_nes_variants, use.names = FALSE),
  "clean"
))

dispersion_only <- cfg
dispersion_only$report$category_nes_variants <- "dispersion"
dispersion_check <- validate_lisa_config(dispersion_only, check_files = FALSE)
stopifnot(identical(
  unlist(dispersion_check$config$report$category_nes_variants, use.names = FALSE),
  "dispersion"
))

all_plan <- plan_lisa_outputs(cfg, category_counts = c(`GOBP-C2` = 2L))
clean_plan <- plan_lisa_outputs(clean_only, category_counts = c(`GOBP-C2` = 2L))
all_plan$summary

##       mode analyses contrasts collections selected_categories
## 1 standard        2         1           4                   0
##   member_gene_set_categories category_evidence_categories
## 1                          0                          604
##   category_member_evidence_categories contrast_evidence_categories
## 1                                 604                          302
##   category_nes_variant_figures standard_contrast_profile_figures
## 1                           80                                24
##   figure_families format_multiplier expected_figure_files
## 1              17                 1                  1650
##   interactive_category_overviews shared_gene_explorer_pages conservative_bytes
## 1                             12                          1         2159542272
##   conservative_gib
## 1            2.011
##                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     warning
## 1 Standard preserves category overview families and includes one evidence matrix per applicable LISA category and one downloadable member-set chart within each individual evidence sheet, plus linked SVG navigation and aligned contrast evidence. The unified category viewer offers selected NES variants; contrasts include all, same-direction and opposite-direction subsets. The shared gene explorer size depends on full membership and DE cardinality, not this figure estimate.

clean_plan$summary

##       mode analyses contrasts collections selected_categories
## 1 standard        2         1           4                   0
##   member_gene_set_categories category_evidence_categories
## 1                          0                          604
##   category_member_evidence_categories contrast_evidence_categories
## 1                                 604                          302
##   category_nes_variant_figures standard_contrast_profile_figures
## 1                           20                                24
##   figure_families format_multiplier expected_figure_files
## 1              11                 1                  1590
##   interactive_category_overviews shared_gene_explorer_pages conservative_bytes
## 1                             12                          1         2080899072
##   conservative_gib
## 1            1.938
##                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     warning
## 1 Standard preserves category overview families and includes one evidence matrix per applicable LISA category and one downloadable member-set chart within each individual evidence sheet, plus linked SVG navigation and aligned contrast evidence. The unified category viewer offers selected NES variants; contrasts include all, same-direction and opposite-direction subsets. The shared gene explorer size depends on full membership and DE cardinality, not this figure estimate.

no_static <- cfg
no_static$report$formats <- list(png = FALSE, svg = FALSE, pdf = FALSE)
no_static_check <- validate_lisa_config(no_static, check_files = FALSE)
stopifnot(!any(unlist(no_static_check$config$report$formats)))

Choose execution and output controls

• workers: distribute independent analysis, contrast and post-processing tasks while keeping their order and random seeds fixed; default 4. Choose a positive integer no larger than the CPU cores allocated to the R process. Linux uses a bounded multicore backend. Windows and macOS run serially even when a larger value is requested. Each DE task uses one thread; shared-cache, report and final-verification steps remain serial.
• gsea_padj_cutoff: the single inclusive adjusted-P threshold used for member-set summaries, A/B support flags and figure endpoints; default 0.25. Use a number from 0 to 1. Changing it changes the descriptive category summaries and must therefore be recorded with the run.
• dry_run: validate and plan without enrichment; start with true. A successful plan returns PLAN_PASS and is stored in the separate directory reported as result$plan_dir. It does not create or reserve pipeline.output_dir. verify_lisa_run(result$plan_dir) returns FAIL because planning evidence is not a completed scientific run. Set dry_run: false to use the still-free scientific destination.
• resume: the default is false, and it must remain false in this beta. lisaR cannot yet prove that a partial run was created with the same configuration, code and resources. If a run is interrupted, keep its staging tree for inspection and start a clean run with a new run_id. Setting true stops with LISA-RESUME-001.
• run_id: optional explicit portable ASCII technical identifier.
• report_title: title displayed in the report.
• file_label_prefix: portable ASCII filename prefix; display text belongs in report_title or analysis labels.
• sufficiency_action: what to do when the usable feature count is below the profile threshold. The default is warn; use error to stop, or ignore_with_reason for an intentionally restricted assay.
• sufficiency_ignore_reason: non-empty justification required with ignore_with_reason; it becomes part of the reproducible configuration.

For transcriptomic/genomic, lisaR warns below 5,000 usable unique features and gives a strong warning below 2,000. For global proteomic, the corresponding thresholds are 1,500 and 500. A targeted profile has no universal minimum and records that limitation instead. These checks flag whether the input may be too narrow for a useful enrichment analysis; they do not measure data quality or statistical power.

For example, an intentionally restricted panel can record:

pipeline:
  sufficiency_action: ignore_with_reason
  sufficiency_ignore_reason: "Targeted 84-gene immune panel; the restricted feature universe is intentional."

Choose collections

A list of registered gene-set collections:

The first four are the semantic LISA universes. HALLMARKS is the fifth analysis option, but it is a direct collection rather than another semantic universe. The examples use the four semantic collections and exclude Hallmarks deliberately:

pipeline:
  run_hallmarks: false

collections:
  - GOBP-C2
  - GOMF
  - GOCC
  - PATHWAYS

You may select a different supported subset for your study. Remember that run_hallmarks: true keeps Hallmarks only when HALLMARKS is selected; it does not add it to the list above. See How lisar works for the relationship between the universes, dictionaries and biological hierarchy. Availability depends on the installed species-matched gene-set membership table.

Describe each analysis

One entry per differential-expression analysis:

• analysis_id: stable portable ASCII technical identifier.
• de_path: differential-expression table.
• species: Homo sapiens or Mus musculus.
• symbol_col: gene-symbol column.
• logfc_col: signed effect-size column.
• pvalue_col: optional raw p-value column.
• padj_col: adjusted p-value/FDR column.
• rank_col: optional precomputed ranking column.

The ranking column must retain direction. Use a signed statistic such as a DESeq2 Wald stat, a limma t or another signed z-score; never use padj or FDR as rank_col.

Presentation metadata is optional but strongly recommended:

• label: concise human-readable analysis title.
• comparison: the exact oriented comparison shown in plot subtitles.
• positive_direction: a plain-language definition of positive log2FC/NES.
• model_note: the fitted model, coefficient or contrast, and any pairing, blocking or adjustment variables.

These fields do not alter statistics. They prevent internal IDs from becoming the only explanation of a figure.

Optional matrix paths and their identifier columns support heatmaps. Match the field to the stored scale: vst_matrix/vst_matrix_path declare transformed values (no further log transform); counts_matrix, tpm_matrix and their *_path forms declare count-like values, which the heatmap displays as log2(x + 1). That display transform is not a substitute for DE normalisation. Generic matrix fields retain a legacy filename-based scale inference, so prefer an explicit typed field. Never declare one file under conflicting scales. matrix_id_col identifies the gene column and sample columns retain their input order. The input adapter’s matrix_scale receipt alone does not configure or transform this matrix.

Use completed DESeq2, edgeR and trusted RDS inputs

YAML and JSON studies accept text DE tables. For a completed data frame, prepare_lisa_de_input() provides an auditable route into the configured workflow; see Preparing DE inputs. For a supported result object retained in memory, the lower-level run_lisa_de() is another route:

• DESeqResults can be passed directly.
• DESeqDataSet requires exactly one result selector: deseq2_name for a named coefficient or deseq2_contrast for a contrast. Supplying neither or both is an error.
• edgeR results DGELRT, DGEExact and TopTags are supported.
• DGEList is rejected because it contains counts and design information, not a completed differential-expression result.

For example, choose one DESeq2 coefficient from an object already in memory:

result <- run_lisa_de(
  dds,
  output_dir = "results/treated-vs-control",
  comparison_name = "treated_vs_control",
  species = "Homo sapiens",
  symbol_col = "rowname",
  deseq2_name = "condition_treated_vs_control",
  universes = c("GOBP-C2", "GOMF", "GOCC", "PATHWAYS")
)

The contrast form uses deseq2_contrast instead of deseq2_name, for example c("condition", "treated", "control").

An .rds file is not a plain data table. Read it only when it is local, stable and fully trusted, and make that decision explicit in the R call:

result <- run_lisa_de(
  "dds.rds",
  output_dir = "results/treated-vs-control-rds",
  comparison_name = "treated_vs_control",
  species = "Homo sapiens",
  symbol_col = "rowname",
  trusted_rds = TRUE,
  deseq2_name = "condition_treated_vs_control",
  universes = c("GOBP-C2", "GOMF", "GOCC", "PATHWAYS")
)

The size limit is diagnostic, not a sandbox. YAML and JSON cannot set trusted_rds or point a configured de_path at an RDS file. Export a TSV or CSV first if you need the configuration-defined workflow. See Function reference for the remaining arguments and the trust receipt written for an accepted RDS input.

Describe profile contrasts

Each contrast contains:

• contrast_id: stable portable ASCII technical identifier.
• analysis_a, analysis_b: IDs declared in single_de.
• contrast_label: human-readable label.
• comparison: exact profile-level comparison for report text.
• positive_direction: interpretation of a positive category-profile delta.

Contrast direction follows analysis_a minus analysis_b. Both analyses must be scientifically and technically compatible. A profile difference is descriptive, not a new statistical test of category change. The paired evidence view retains significance and leading edges separately for A and B; missing evidence is not replaced by zero.

Include auditable source files

Optional source files can enter a run only through an explicit, non-empty allowlist:

• every resolved source file must exactly match one listed file;
• allowing a directory does not allow its children;
• allowlisted_source_paths applies to the study, while allowlisted_paths applies to one entry and takes precedence;
• each entry declares its role and destination subdirectory; and
• lisaR checks every entry before copying any of them.

A missing, empty or mismatched allowlist therefore fails without leaving a partial source import. Use this mechanism for auditable source material, not for copying arbitrary directories.

Reuse exact GSEA work in an optional cache

This is a computation cache, not the registry of scientific resources. It is off by default. This partial YAML block enables it in a local directory relative to the study file:

pipeline:
  cache_mode: readwrite
  cache_dir: cache/gsea
  cache_max_bytes: 536870912

An active mode requires an explicit local cache_dir. The default budget is 512 MiB (536870912 bytes), supplied as a positive whole number no larger than 9007199254740991 (the exact-integer limit of the configuration’s numeric representation). This bounds the cache implementation, not R’s total memory. If a changed budget conflicts with existing slots, use a new directory or the original budget; a cached result is disposable, but never delete resources or completed run artefacts as though they were cache entries.

A hit requires the same ordered named ranking, complete selected memberships, universe, gene-set-size limits, algorithm/parameters, seed and task identity, and relevant software/runtime context. A renamed analysis can therefore miss because its task identity changes. Corrupt or incompatible entries cannot be accepted as equivalent results. The cache stores raw GSEA results, not category annotations, report pages or figure files. Those are derived again for the current run. No change in dictionary label or output option alone is proof that reuse is possible.

Inspect qc/<comparison>_content_cache.tsv in each analysis/collection for hit/miss status, reason and component hashes. The report also reuses prepared downloads with identical content internally; that optimisation is separate from this optional GSEA cache and requires no configuration.

The configuration and provenance records use the technical name TERM2GENE for the membership table. Its schema has five columns: gs_collection, gs_subcollection, gs_name, gs_exact_source and gene_symbol. Together they record the source collection, subcollection, gene-set identifier, exact source and one member gene per row.

See Parallel execution to choose a worker count, understand what happens when a task fails and compare serial with parallel results.