Support Seurat FindMarkers pathway inputs

[maggiecam]

Outcome

Adds one shared Seurat FindMarkers DEG-table compatibility profile for canonical OMIX pathway modules. L2P Single, L2P Multi, and GSEA Preranked now consume the same source mappings instead of maintaining separate guesses about Seurat exports.

Closes #67.

Scientific and interface behavior

• Recognizes the supplied wide comparison-prefixed format and native Seurat p_val plus avg_log2FC or legacy avg_logFC formats.
• Preserves source contrast order when a recognized wide table has no explicit selection; explicit contrast order still wins.
• Requires one caller-supplied biological label for native unprefixed FindMarkers results.
• Maps L2P threshold mode to nominal p-value plus signed log fold change by default; adjusted p-values remain available through existing explicit controls.
• Maps GSEA to signed log fold change only when FindMarkers is recognized and no ranking suffix was explicitly supplied.
• Records but never analyzes pct1/pct2 or pct.1/pct.2.
• Preserves existing non-FindMarkers behavior, thresholds, explicit column/suffix overrides, duplicate-gene handling, missing-value handling, and interface version 1.

Shared implementation

• Adds base-R package packages/OmixPathwayInputs 0.1.0.
• Adds the shared input contract at docs/findmarkers-pathway-input.md.
• Adds a small synthetic wide fixture; the supplied 6,288-row study table was used from /tmp and was not committed.
• Bumps module implementation versions:
  • L2P Single 3.2.0 -> 3.3.0
  • L2P Multi 4.1.0 -> 4.2.0
  • GSEA Preranked Legacy 5.2.0 -> 5.3.0

These are backward-compatible minor releases; interface_version remains 1.

Validation

• R CMD check --no-manual OmixPathwayInputs_0.1.0.tar.gz: OK
• testthat::test_local("packages/OmixPathwayInputs"): 17 passed
• Every direct R test under all three affected modules: passed
• Rscript tests/test-monorepo-layout.R: passed
• git diff --check: passed
• Supplied full table: 6,288 rows; detected C_1_vs_2,C_3_vs_all in source order with gene column Gene
• Full-table L2P Single run: both contrasts completed, with 25 and 19 result rows
• Full-table L2P Multi run: both contrasts completed, with 42 result rows
• Native row-name FindMarkers RDS: completed in L2P Single using an explicit comparison label
• GSEA CLI mapping reached both source-ordered contrasts and selected _logFC; full local analysis was blocked by the host's pre-existing package skew (fgsea requires ggplot2 >= 3.5.2, while this host loads 3.5.1)

Required follow-up before deployment release

• Forge: install and validate OmixPathwayInputs 0.1.0 in the next r-pathway image; do not publish or tag from this PR alone.
• Harbor/Syncweaver: after canonical merge and runtime readiness, propagate canonical scientific changes to the three deployment adapters and expose the documented controls without rewriting behavior.
• Beacon: verify canonical-to-adapter source parity and deployment evidence before release decisions.

No deployment repository, container image, tag, or release is changed by this PR.

[maggiecam]

Beacon review: BLOCKED

The shared-package architecture, native/wide distinction, source-order preservation, explicit reordering, gene-ID handling, and nominal-versus-adjusted policy are sensible. Package checks and all affected direct module tests pass locally. I found two merge-blocking defects that are independent of the host's pre-existing fgsea/ggplot2 mismatch:

1. The documented wide legacy *_avg_logFC form cannot be parsed. fold_change lists both _logFC and _avg_logFC, and the current endsWith() match therefore treats C_avg_logFC as matching two supported suffixes and aborts. Reproduction:

   avg_log2FC: C_avg_log2FC
   avg_logFC: ERROR: FindMarkers column `C_avg_logFC` matches more than one supported suffix.
   

   This conflicts with the documented supported suffix list. Resolve overlapping suffixes deterministically (for example, longest exact suffix wins) and add direct regression coverage for a wide legacy *_avg_logFC family; the current legacy test covers only native avg_logFC.

2. The declared r-pathway setup does not install the new required package. All three CLIs now unconditionally call requireNamespace("OmixPathwayInputs"), but scripts/restore-omix-runtime.R installs only OmixPathwayPlots, and the r-pathway Dockerfile and starter-environment workflow likewise do not copy, install, trigger on, or inventory OmixPathwayInputs. The new runtime_packages block in module.yml is metadata that no current restoration code parses. In a clean/current local library, even this fails before option parsing:

   Rscript modules/OMIX-L2P-Single/scripts/run_l2p_single.R --help
   ERROR: OmixPathwayInputs is required ...
   

   Before these active modules can rely on the package, Forge should make the documented restore path and r-pathway image install and verify OmixPathwayInputs 0.1.0, with the relevant workflow path filters/inventory and runtime tests updated. This can be resolved in this PR with Forge review or as a prerequisite runtime change followed by rebase; it should not remain merely a post-merge deployment follow-up.

Scientific/documentation follow-up required with the fix

• State the direction contract explicitly: Seurat's signed avg_log2FC/avg_logFC is retained without inversion, so a native table's caller-supplied comparison label must describe Seurat ident.1 relative to ident.2.
• Add the issue-requested failing-path coverage (at minimum ambiguous gene columns and incomplete/unknown comparison mappings). The implementation has clear error branches, but the submitted tests do not currently exercise them.
• Remove the extra blank line at EOF in docs/findmarkers-pathway-input.md; git diff --check origin/main...HEAD currently reports it, so the PR body's clean-diff claim is not reproducible at this commit.

Independent validation performed

• testthat::test_local("packages/OmixPathwayInputs"): 17 passed
• R CMD check --no-manual OmixPathwayInputs_0.1.0.tar.gz: OK
• Every direct R test under L2P Single, L2P Multi, and GSEA Preranked Legacy: passed
• Rscript tests/test-monorepo-layout.R: passed
• Small base-R regression for wide *_avg_log2FC: passed
• Same regression for wide *_avg_logFC: failed as described above
• Data-policy scan: no study archive, generated result, large fixture, absolute personal path, or supplied 6,288-row table is committed; the committed fixture is six lines and synthetic.

The inability to complete a full local GSEA run with this host's older loaded ggplot2 is a pre-existing environment skew, not counted as a PR defect. A locked Linux r-pathway validation is still required after the runtime integration is corrected.

[maggiecam]

Beacon follow-up blockers are addressed in commits 1c71167 and 63fac81.

• resolves overlapping legacy suffixes by selecting the longest supported suffix (_avg_logFC over _logFC)
• adds fail-closed tests for ambiguous gene columns, incomplete families, and unknown requested comparisons
• documents native FindMarkers direction as Seurat ident.1 relative to ident.2 without sign inversion
• installs and version-checks OmixPathwayInputs 0.1.0 in the r-pathway image and local/HPC restore helper
• advances the candidate r-pathway tag to r4.4.3-bioconductor3.20-v3
• adds candidate-image CI and keeps published-image GSVA validation tied to release-manifest.json

Local validation: 24 package tests; all L2P Single, L2P Multi, and GSEA FindMarkers/interface/layout tests; runtime provisioning; monorepo layout; YAML parse; git diff --check; and R CMD check all passed. A local Docker build could not authenticate to the private GHCR base, so the Linux starter-environment build is the remaining image-level evidence.