Repository navigation
Add PR 70 rebuild draft notes as evidence #351
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| unposted draft | ||
| SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk> | ||
| SPDX-License-Identifier: AGPL-3.0-or-later | ||
|
|
||
| Add native ALDEx2 and ANCOM-BC differential abundance | ||
|
|
||
| Two new values of analysis.differential.method, fitted in Julia by | ||
| CompositionalDA on the raw count matrix, alongside the existing R-backed | ||
| methods: | ||
|
|
||
| - aldex2: Dirichlet posterior Monte Carlo instances with CLR differences and | ||
| Welch tests, keeping the package's expected within-instance BH values. The | ||
| effect is a log2 CLR difference, not a fold change. | ||
| - ancombc: the two-group sampling-bias model with a bias-corrected log2 fold | ||
| change and conservative Wald standard errors. Structural zeros are reported | ||
| as such, with a note saying whether the absence is in one group or both, and | ||
| never receive a p-value. | ||
|
|
||
| DifferentialConfig gains mc_samples (2 to 4096, default 128) and seed (0 to | ||
| typemax(Int32), default 1), validated in the constructor and at the config | ||
| route. Counts that do not fit Int are refused, a sample with no reads is left | ||
| out and named, and fewer than two retained taxa are refused. A refusal by the | ||
| package is returned as an answer about the data and reported as 422; any other | ||
| error from it propagates. The route accepts a per-request method override, | ||
| spelled and case-folded like the config key. The panel, the CSV settings line, | ||
| the config editor and the guide describe both methods. | ||
|
|
||
| CompositionalDA is a declared dependency with a compat bound and a Manifest | ||
| entry from the General registry. There is no optional loading and no stand-in. | ||
|
|
||
| The tests compare both methods with the output of the R packages ALDEx2 1.42.0 | ||
| and ANCOMBC 2.12.0 on a fixed count table. The reference values are CSV files | ||
| in test/fixtures/native_da, with the R script that made them and the reason for | ||
| each tolerance in the test file. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,29 @@ | ||
| unposted draft | ||
| SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk> | ||
| SPDX-License-Identifier: AGPL-3.0-or-later | ||
|
|
||
| # Final step: after CompositionalDA is registered in General (General#175952) | ||
|
|
||
| Do not run this before the registry shows CompositionalDA 0.1.0. Target: v0.1.0 at bb3cf54 | ||
| (Release 0.1.0 for registration in General). Note for the owner: the existing git tag v0.1.0 | ||
| in hyperpolymath/CompositionalDA.jl points at 320513d, not bb3cf54. See the hub card. | ||
|
|
||
| Owner confirmation for signing (SR-011) is needed again for this amend. | ||
|
|
||
| ``` | ||
| cd /home/user/MetaManifold-WebUI | ||
| git switch rebuild/pr70-native-da | ||
| git fetch upstream main # if main moved: git rebase upstream/main (no merge commits) | ||
| export R_HOME=/opt/R/4.5.0/lib/R LD_LIBRARY_PATH=$R_HOME/lib # a Julia 1.12.5 on PATH | ||
| julia --project=. -e 'using Pkg; Pkg.Registry.update(); Pkg.resolve(); Pkg.instantiate()' | ||
| # Project.toml already declares CompositionalDA = "0.1". resolve adds the Manifest entry. | ||
| # Checks, all must hold: | ||
| grep -n -A6 '^\[\[deps.CompositionalDA\]\]' Manifest.toml # version = "0.1.0", a git-tree-sha1, NO repo-url, NO path | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Compare the Manifest tree hash with the tree of The check at line 21 confirms the version string and that a Add a check that compares the
|
||
| git diff --stat -- Manifest.toml # only CompositionalDA and its new dependencies | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Inspect the manifest entries, not only the diff statistics.
|
||
| julia --project=. -t 2 test/runtests.jl differential_native differential | ||
| git add Project.toml Manifest.toml | ||
| git commit --amend --no-edit -S # with the SR-011 per-commit identity and signing options | ||
| git log -1 --format='%G? %ce' # G and the signing email | ||
| bash scripts/maintenance/check-pr-freshness.sh --base upstream/main --head HEAD # if the script exists on main | ||
| ``` | ||
| No `Pkg.develop`, no `Pkg.add(url=...)`, no `[sources]` entry anywhere. | ||
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,64 @@ | ||||||
| unposted draft | ||||||
| SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk> | ||||||
| SPDX-License-Identifier: AGPL-3.0-or-later | ||||||
|
|
||||||
| <!-- DRAFT. Not posted anywhere. Notes for the owner are in HTML comments and must be removed before use. --> | ||||||
| <!-- Owner note 1: no issue reference is written below on purpose. Any "closes/refs #23" text makes GitHub write a timeline event on that issue. Add one only if the owner decides to. --> | ||||||
| <!-- Owner note 2: do not cite the maintainer's in-person agreement here. --> | ||||||
|
|
||||||
| ## Native ALDEx2 and ANCOM-BC differential abundance | ||||||
|
|
||||||
| ### What this does | ||||||
|
|
||||||
| Adds two values of `analysis.differential.method`, `aldex2` and `ancombc`, fitted in Julia by the registered package `CompositionalDA` (v0.1.0) on the raw count matrix, with no R session involved. | ||||||
|
|
||||||
| - `aldex2`: Dirichlet posterior Monte Carlo instances (prior 0.5), CLR differences, Welch and Wilcoxon tests, with the package's expected within-instance BH values kept as they are. The effect is a log2 CLR difference, not a fold change. | ||||||
| - `ancombc`: the original two-group sampling-bias model. The effect is a bias-corrected log2 fold change. Structural zeros are reported as a decision with a note saying whether the absence is in one group or both, and never receive a p-value. | ||||||
| - `DifferentialConfig` gains `mc_samples` (2 to 4096, default 128) and `seed` (0 to `typemax(Int32)`, default 1), checked in the constructor and at the config route. | ||||||
| - The route accepts a per-request `method` override, spelled and case-folded like the config key. | ||||||
| - Counts that do not fit `Int` are refused, a sample with no reads is left out and named, and fewer than two retained taxa are refused. | ||||||
| - A refusal by the package (`CompositionError`) is returned as `NoTaxonFitted` and reported as 422. Any other error from the package is not turned into a refusal. | ||||||
| - The panel, the CSV settings line, the config editor and the guide describe both methods. | ||||||
|
|
||||||
| `CompositionalDA` is declared in `[deps]` and `[compat]` (`"0.1"`) and resolved in `Manifest.toml` from the General registry. There is no optional loading and no stand-in backend: `differential.jl` imports the package. | ||||||
|
|
||||||
| ### Where this departs from CONTRIBUTING | ||||||
|
|
||||||
| CONTRIBUTING says statistics run in R through RCall. These two methods run in native Julia instead, so this change conflicts with that line. The R packages ALDEx2 and ANCOMBC are used only to produce reference values for the tests (below), and they are not added to `renv.lock`. | ||||||
|
|
||||||
| ### Reference values | ||||||
|
|
||||||
| `test/fixtures/native_da/` holds a 16-sample, 12-taxon count table and the output of the R packages on it, generated by `generate_reference.R` in the same folder (R 4.5.0, Bioconductor 3.22, ALDEx2 1.42.0, ANCOMBC 2.12.0). `test/unit/test_differential_native.jl` compares the package's rows, as produced through `differential_abundance`, with these values. R is not needed to run the tests. | ||||||
|
|
||||||
| Tolerances and their reasons: | ||||||
|
|
||||||
| - **ALDEx2.** The method is Monte Carlo, so two correct runs differ even with a fixed seed. The fixture has the mean of 25 R runs (128 instances, seeds 1001 to 1025) and the range of those runs for each value. A native value must lie within one range of the R mean. The range of 25 draws is about four standard deviations. The largest deviation seen is 0.59 of a range. P-values are compared as log10, floored at 1e-10. | ||||||
| - **ALDEx2 Wilcoxon, one taxon.** `taxon11` is absent from every sample of one group. ALDEx2 reports an expected Wilcoxon p below 1e-10 for it. The package reports 1.55e-4, the smallest p that ranks of 8 against 8 can give. This taxon's Wilcoxon values are not compared, and the Welch values are. This is a real difference between the two implementations and is left visible here. | ||||||
| - **ANCOM-BC.** The package and the R function do not share code or a stopping rule (tolerance 1e-7 and 1e-5), and the standard errors add the bias variance slightly differently. Largest observed differences: effect 0.011, standard error 0.0096. Tolerance is 0.02 on both. The Wald statistic must be within 10 percent of the R value plus 0.15 (largest observed: 7 percent of a large value, 0.12 of a small one). The decision at BH 0.05 must be the same. P-values are not compared directly, because the normal tail turns a small statistic difference into up to two orders of magnitude where p is below 1e-15. | ||||||
| - **ANCOM-BC structural zero.** Both implementations find `taxon11` structurally absent from group A. R prints an effect of 3.94 and a p of exactly 0 for it. The native method reports the decision and no number. | ||||||
|
|
||||||
| ### How to run | ||||||
|
|
||||||
| ``` | ||||||
| julia --project=. -t 2 test/runtests.jl differential_native differential | ||||||
| bun test src/components/differentialTable.test.ts src/components/differentialCsv.fuzz.test.ts | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Run the frontend tests from the The test paths in the command are relative to Suggested fix
Committable suggestion
|
||||||
| ``` | ||||||
|
|
||||||
| To regenerate the fixtures (needs R with ALDEx2, ANCOMBC and their dependencies): `Rscript test/fixtures/native_da/generate_reference.R`. | ||||||
|
|
||||||
| ### What this leaves out | ||||||
|
|
||||||
| - ALDEx2's other tests (`kw`, `glm`) and more than two groups. Both methods are two-group. | ||||||
| - ANCOM-BC2 and the multi-group ANCOM-BC options. | ||||||
| - The calibration of either method beyond agreement with R on this table. | ||||||
| - R packages in `renv.lock`: none added. | ||||||
|
|
||||||
| ### Lockfile | ||||||
|
|
||||||
| `Manifest.toml` changes only to add `CompositionalDA` and the packages it needs. It is needed because the package is a new dependency. | ||||||
|
|
||||||
| ### Tested with | ||||||
|
|
||||||
| Julia 1.12.5, R 4.5.0, bun 1.4.4. | ||||||
|
|
||||||
| <!-- Fill in before use: the exact versions and results of the CI run, once the branch is pushed and CI has run. --> | ||||||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| unposted draft | ||
| SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk> | ||
| SPDX-License-Identifier: AGPL-3.0-or-later | ||
|
|
||
| # PR #70 rebuild thread: summary (21 Nov 2026) | ||
|
|
||
| Hub: session_0136P7Zp4PiAy2XSYEb699Kv (reach only via send_message with that session_id). | ||
|
|
||
| ## Task | ||
| Rebuild upstream PR JoshuaJewell/MetaManifold-WebUI#70: native ALDEx2 and ANCOM-BC via CompositionalDA.jl. Ready to push once CompositionalDA is in Julia General (General#175952, blocked by reviewer goerz). Joshua's conditions (12 Nov): declared dep and compat with regenerated Manifest, no optional loading, no URL pin; R-reference fixtures with justified tolerances, no Python; no merge commits; every commit signed; commit message describes the change, no fork PR numbers; full PR description. | ||
|
|
||
| ## Done | ||
| - Branch rebuild/pr70-native-da from upstream main 89be534. One signed commit 7bd131b3921e5e8368e8b78edab773d77a299456, 21 files. %G? = G, committer email = CLAUDE_SIGNING_EMAIL. No Claude trailers. | ||
| - Project.toml: CompositionalDA = "0.1" in [deps] and [compat]. Optional-loading seam and stub removed. Package refusal -> NoTaxonFitted (422). | ||
| - Fixtures: R 4.5.0, ALDEx2 1.42.0, ANCOMBC 2.12.0. ALDEx2 tolerance: one range of 25 R seeds. ANCOM-BC: 0.02 effect and se, statistic 0.10*|w|+0.15, same BH 0.05 decision. taxon11 ALDEx2 Wilcoxon excluded (implementations disagree), stated in the description. | ||
| - Owner confirmed signing and push by selector in my session. Pushed to fork as new branch rebuild/pr70-native-da (remote 7bd131b). No PR, no tags, validation/issue-23-native-da and main untouched. | ||
|
|
||
| ## Tests (Julia 1.12.5, R 4.5.0, bun 1.4.4) | ||
| Native tests pass (790 fuzz, 9 input, 167 ALDEx2, 77 ANCOM-BC, 6 refusal, 5 structural-zero). Frontend differential tests pass, tsc clean. | ||
| Not run: full suite, integration, CI, SonarCloud, reuse lint, renv-pinned R libs. Pre-existing failure "Route: two runs through the in-process router" also fails on untouched upstream main (believed environmental, not confirmed). | ||
|
|
||
| ## Flags | ||
| - CONTRIBUTING says R through RCall; native Julia conflicts (stated in description). It also says open an issue first; none written, per owner. | ||
| - CompositionalDA tag v0.1.0 is at 320513d, not bb3cf54. Owner plans to re-make it. | ||
|
|
||
| ## Status and gap | ||
| Manifest.toml NOT regenerated. Upstream PR #70 itself is untouched and still points at the old branch (647f8ba). The audit says that branch still has optional loading and was marked ready. My "done" meant the rebuild branch, not the live PR. Nobody re-read Joshua's latest comments against the live branch before saying done. | ||
|
|
||
| ## Next | ||
| 1. Wait for CompositionalDA 0.1.0 in General; make sure the registered release is bb3cf54. | ||
| 2. Run FINAL-STEP.md (Pkg.Registry.update, resolve, instantiate; check Manifest entry; rerun tests; amend signed). | ||
| 3. Owner asks: fresh SR-011 selector for the amend; push selector (force-with-lease); decision on getting the rebuild into live PR #70; strip HTML owner notes and fill CI results in the description. | ||
| 4. Before saying done: check each of Joshua's six conditions against the live PR branch, CI against the commit in the branch, and every commit's committer identity. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Set
R_HOMEbefore expanding it.If
R_HOMEis unset, the shell expandsLD_LIBRARY_PATH=$R_HOME/libbeforeexportassignsR_HOME. The resulting path is/lib, not/opt/R/4.5.0/lib/R/lib. This can make the Julia tests fail when they need that R library path. Use two separate export commands.