about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-12 17:15:53 +0000
committerPjotr <wrk@bosa.lan>2026-11-12 17:15:53 +0000
commitd9e1bf7fd9da4e0bae6579b95fd0028296b997ac (patch)
tree450ea1eb5642227f4859e9941edc7d8910f90032 /docs
parent7a78dce4bf6db058f1ac12a4176c2702debff798 (diff)
downloadgenenetwork4-d9e1bf7fd9da4e0bae6579b95fd0028296b997ac.tar.gz
compute/bnw: a Bayesian network over traits, called out to BNW's driver
POST /compute/bnw learns a network over a set of variables and returns one row
per candidate edge: from, to, posterior, in_structure. Inputs are published
traits of a group (group + traits) or an explicit matrix (values: one entry per
variable with per-sample values), which covers the case the database cannot --
a basket's columns, a handful of probe sets.

BNW's knowledge stays in the gn-bnw repository. GN4 writes a variables x
samples matrix, runs `bnw learn` (BNW_CMD, BNW_BIN_DIR, BNW_CACHE_DIR) and
parses the reply: nothing about the three C programs, the private work
directory or the type line in the input file lives here, so BNW's pipeline can
change without a GN4 release. The driver's failures map onto the API's own:
bad input 422, a missing driver 502 bnw_not_installed (its exit 77), a failed
computation 502 bnw_failed in the driver's words.

Decisions worth recording:

  * parameters are BNW's own defaults -- maxparents 4, k 1, tiers 3, threshold
    0.5, read from its create_tiers_gom_part1.php rather than chosen here --
    and the reply names the values used, because a network at 0.5 and one at
    0.9 are different answers to the same question;
  * at most 40 variables and at least 3 samples complete across every variable.
    The first is the structure search's exponential in-degree; the second is
    BNW modelling a complete multivariate normal, so a sample missing any value
    is dropped -- and the note says how many survived rather than silently
    shrinking the panel;
  * its own gate, always claimed (threshold 0): there is no such thing as a
    small BNW run, the cost is the search, not the number of individuals;
  * the notes say plainly that a posterior is not a p-value and that a network
    is not a QTL, because that is the easiest thing to over-read.

tests/bnw.rs compares the endpoint against the answer the BNW *web
application* gives for its own six-trait example (the same fixture as the
driver's parity check, gn-bnw/test/golden/): the five edges must match, and the
notes must name the parameters and carry the caveat. It skips when the driver
or its binaries are absent.

Not deployed to production.
Diffstat (limited to 'docs')
-rw-r--r--docs/www/SKILL.md9
1 files changed, 9 insertions, 0 deletions
diff --git a/docs/www/SKILL.md b/docs/www/SKILL.md
index 4bb81e4..bb8bd3e 100644
--- a/docs/www/SKILL.md
+++ b/docs/www/SKILL.md
@@ -152,6 +152,15 @@ header (peak, and the reference lines drawn when you asked for them).
   scale-free: compare `pve` with `h2`, never `vg` with `σ²_e`. A `pve` of
   exactly 0 or 1 is a boundary (the standard error then reads "not
   available"), a direction rather than a proportion.
+* `/compute/bnw`: a Bayesian network over a set of traits (BNW). Give `group` +
+  `traits`, or `values` (one entry per variable with per-sample values). Columns
+  `from, to, posterior, in_structure`; one row per candidate edge, strongest
+  first. **A posterior is not a p-value** — it is the share of the k-best
+  networks containing the edge, i.e. how often the search drew that arrow in
+  this sample, so quote it as a structural claim and never as a threshold on a
+  QTL. Parameters default to BNW's own (maxparents 4, k 1, tiers 3, threshold
+  0.5) and the reply names the ones used. At most 40 variables, at least 3
+  samples complete across every variable.
 * `/compute/fitqtl`: **how big** an effect is, not just where. Give it the
   marker names a scan found (its peaks) and it fits R/qtl's `fitqtl` at
   each: columns `marker, chr, pos, lod, pct_var, additive, se, t, p`. Use it