about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/www/ai-instruction.md48
1 files changed, 41 insertions, 7 deletions
diff --git a/docs/www/ai-instruction.md b/docs/www/ai-instruction.md
index fcc5c4c..fe033d4 100644
--- a/docs/www/ai-instruction.md
+++ b/docs/www/ai-instruction.md
@@ -55,6 +55,25 @@ built from a working tree with uncommitted changes: compare the part
 before `-dirty`, and quote `source_digest` if you need to identify the
 exact build.
 
+**A version change means refetch this document.** `/version` reports the
+build the *server* is running, and this deployment is updated in place —
+so a `git` value you have not seen before (or one that moved during your
+session) is the signal that the page you are reading may be out of date.
+When that happens, do not keep working from your copy: refresh it and
+re-read it before the next call.
+
+```sh
+git -C genenetwork4 pull --depth 1          # or re-run the clone above
+less genenetwork4/docs/www/ai-instruction.md
+```
+
+Endpoints, parameters and defaults get added between revisions (covariate
+support in `/compute/rqtl` and `/compute/gemma` arrived that way), and a
+stale copy does not announce itself: the API simply accepts a request
+without the new option, or answers with fields the old text does not
+mention. Re-reading a file is cheap; a wrong conclusion from a stale
+description is not.
+
 ```
 1. You are given a token     → by the GeneNetwork team, out of band
 2. Send it on every request  → Authorization: Bearer <token>
@@ -131,7 +150,10 @@ returns `git` (the commit the running binary was built from; a `-dirty`
 suffix means that build had uncommitted changes), `dirty`,
 `source_digest` (which identifies the build when a commit hash cannot),
 `database` (`reachable` or `unreachable`) and `date` (the *commit's* date,
-not the build time). If `database` is `unreachable`, every data endpoint
+not the build time). If `git` is not the revision you started your session
+with, the server has been updated under you: refetch this document (see
+"Get this document" above) and re-read it before going on. If `database`
+is `unreachable`, every data endpoint
 will fail with `503 db_unavailable` or `500 database_error` and there is
 nothing you can do but report it — do not retry in a loop and do not
 conclude the resource does not exist.
@@ -418,12 +440,14 @@ A mapping's response ends with what to do next:
   naming them, so a Manhattan plot needs no reshaping.
 
 **Covariates.** Add `covariates` to fit the study's own metadata — sex,
-diet, batch — alongside the trait. The easiest form names a case
-attribute (§3), and the server codes it. It is also the smallest: nothing
-is posted, where an inline covariate sends a value per individual — for a
-panel of thousands that is the difference between a few hundred bytes and
-a multi-megabyte body, and bodies are capped at 64 MiB (`413`, in plain
-text, if you pass it):
+diet, batch — alongside the trait, in **both** `/compute/rqtl` and
+`/compute/gemma`. The easiest form names a case attribute (§3), and the
+server codes it. It is also the smallest: nothing is posted, where an
+inline covariate sends a value per individual — for a panel of thousands
+that is the difference between a few hundred bytes and a multi-megabyte
+body, and bodies are capped at 64 MiB (`413`, in plain text, if you pass
+it). Covariates need a `group` on the request: individuals are aligned by
+name, which an explicit `genotype_file` does not carry (`422`):
 
 ```json
 "covariates": [{"case_attribute": "Sex"}]
@@ -440,6 +464,16 @@ matters, or `{"name": …, "kind": "numerical", "values": […]}` when you
 already have numbers. An attribute the group does not define is a `422`
 listing the ones it has.
 
+The two engines fit the same covariates differently, which changes what
+you should expect in `notes`: R/qtl takes each categorical covariate as
+one column and dummy-expands it itself, while GEMMA gets a covariate file
+of its own with k‑1 dummy columns named after their levels
+(`Status.Live`) — GEMMA has no factors — and a column that does not vary
+among the individuals fitted is left out, with a note saying so (an
+all-zero column is singular, and GEMMA stops rather than dropping the
+term). Either way, covariates reach only the association step and not the
+kinship, so adding one does not recompute the relatedness matrix.
+
 **GEMMA has no permutation test.** Its `actions` therefore suggests the
 *R/qtl* permutation run on the same group and the same values, and says
 so; judge a GEMMA peak against the smallest `p_lrt` it reached, not