code wiki / _hdl_build / nx_analyst_report.nx
`nx_analyst_report.nx` source

↩ module page · 178 lines · 9428 B
1// nx_analyst_report.nx -- LIB: the "ANALYZE THIS DATASET" front door (capstone). Hand it N named i64 columns
2// + a target column; it composes the whole sovereign analytics stack into ONE human-readable report:
3//   - per-column PROFILE + plain-English read (nx_analyst_data)
4//   - each column's CORRELATION to the target + strength class (nx_analyst_multi)
5//   - the strongest ASSOCIATION with the target (F1005: not called a DRIVER -- that is a causal word
6//     and this is a correlation; the report says so in-band and points at nx_analyst_causal)
7//   - a one-line SUMMARY
8// This is what a user actually wants: point at a dataset, get an analysis. license_tier: ORIGINAL
9import "nx_syscalls.nx"
10import "_hdl_build/nx_analyst_data.nx"
11import "_hdl_build/nx_analyst_multi.nx"
12import "nx_analyst_infer.nx"
13
14func arx_cat(d: *u8, o: i64, s: *u8) -> i64 { var i: i64 = 0; while s[i] != (0 as u8) { d[o + i] = s[i]; i = i + 1 } return o + i }
15func arx_catn(d: *u8, o: i64, v: i64) -> i64 {
  var oo: i64 = o
  var m: i64 = v
  if m < 0 { d[oo] = 45 as u8; oo = oo + 1; m = 0 - m }
  let t: *u8 = sys_mmap(24)
  var k: i64 = 0
  if m == 0 { t[0] = 48 as u8; k = 1 }
  while m > 0 { t[k] = (48 + (m % 10)) as u8; m = m / 10; k = k + 1 }
  var i: i64 = k - 1
  while i >= 0 { d[oo] = t[i]; oo = oo + 1; i = i - 1 }
  return oo
26}
27
28// cols = array of column pointers (i64 each); names = array of name pointers (i64 each); target_idx names the
29// target column. Emits the full report into out. Returns bytes written.
30func ar_analyze(cols: *i64, names: *i64, ncol: i64, n: i64, target_idx: i64, out: *u8, cap: i64) -> i64 {
  if cap < 8192 { return 0 }
  if ncol <= 0 { return 0 }
  if target_idx < 0 { return 0 }
  if target_idx >= ncol { return 0 }
  var o: i64 = 0
  o = arx_cat(out, o, "=== DATASET ANALYSIS ===\nrows=" as *u8)
  o = arx_catn(out, o, n)
  o = arx_cat(out, o, " columns=" as *u8)
  o = arx_catn(out, o, ncol)
  o = arx_cat(out, o, " target=" as *u8)
  let tname: *u8 = names[target_idx] as *u8
  o = arx_cat(out, o, tname)
  o = arx_cat(out, o, "\n\n-- PER-COLUMN PROFILES --\n" as *u8)
44
  let prof: *i64 = sys_mmap(16 * 8) as *i64
  let sub: *u8 = sys_mmap(4096)
  var c: i64 = 0
  while c < ncol {
      if o + 4200 >= cap { return o }
      let colc: *i64 = cols[c] as *i64
      let namec: *u8 = names[c] as *u8
      ad_profile(colc, n, 10, prof)
      let sn: i64 = ad_report(namec, prof, sub, 4096)
      var si: i64 = 0
      while si < sn { out[o] = sub[si]; o = o + 1; si = si + 1 }
      c = c + 1
  }
58
  // relationships to the target
  o = arx_cat(out, o, "\n-- RELATIONSHIPS TO " as *u8)
  o = arx_cat(out, o, tname)
  o = arx_cat(out, o, " --\n" as *u8)
  let tcol: *i64 = cols[target_idx] as *i64
  let cls: *u8 = sys_mmap(128)
  let sigb: *u8 = sys_mmap(512)                    // significance verdict text (nx_analyst_infer)
  c = 0
  while c < ncol {
      if c != target_idx {
          if o + 400 >= cap { return o }
          let colc2: *i64 = cols[c] as *i64
          let namec2: *u8 = names[c] as *u8
          let r: i64 = am_pearson_milli(tcol, colc2, n)
          am_class(0 as *u8, r, cls)
          o = arx_cat(out, o, "  " as *u8)
          o = arx_cat(out, o, namec2)
          o = arx_cat(out, o, ": r=" as *u8)
          o = arx_catn(out, o, r)
          o = arx_cat(out, o, "/1000 (" as *u8)
          o = arx_cat(out, o, cls)
          // SIGNIFICANCE (2026-07-23): a strength class on its own says nothing about sample size, so
          // the same "negative weak" sentence is printed for a real effect at n=300 and for pure noise at
          // n=8. Every r now also states whether it is distinguishable from no correlation, and if not,
          // what n it would take to settle it.
          o = arx_cat(out, o, ") " as *u8)
          ai_r_verdict(r, n, sigb)
          o = arx_cat(out, o, sigb)
          o = arx_cat(out, o, "\n" as *u8)
      }
      c = c + 1
  }
91
  // key driver (exclude the target itself by building a candidate list of the OTHER columns)
  let cand: *i64 = sys_mmap(64 * 8) as *i64
  let cand_names: *i64 = sys_mmap(64 * 8) as *i64
  var nc: i64 = 0
  c = 0
  while c < ncol {
      if c != target_idx { if nc < 64 { cand[nc] = cols[c]; cand_names[nc] = names[c]; nc = nc + 1 } }
      c = c + 1
  }
  let oi: *i64 = sys_mmap(8) as *i64
  let orr: *i64 = sys_mmap(8) as *i64
  o = arx_cat(out, o, "\n-- STRONGEST ASSOCIATION with " as *u8)
  o = arx_cat(out, o, tname)
  o = arx_cat(out, o, " --\n  " as *u8)
  if am_key_driver(tcol, cand, nc, n, oi, orr) == 1 {
      let dname: *u8 = cand_names[oi[0]] as *u8
      am_class(0 as *u8, orr[0], cls)
      // GUARD (2026-07-23): the strongest |r| is a FINDING only if it clears significance at this n.
      // am_key_driver is a bare argmax -- it ALWAYS names something, however little data backs it.
      // Below the bar the honest report is that the data cannot support naming a driver at all,
      // plus the n that would settle it.
      // Bonferroni over the nc candidates: naming the LARGEST of nc correlations IS a selection, so the
      // driver must clear the family-wise level, not the per-test one. Uncorrected, ~nc*5% of datasets
      // hand you a "driver" that is luck.
      if ai_r_sig_bonferroni(orr[0], n, nc) == 1 {
          o = arx_cat(out, o, dname)
          o = arx_cat(out, o, " has the strongest association (r=" as *u8)
          o = arx_catn(out, o, orr[0])
          o = arx_cat(out, o, "/1000, " as *u8)
          o = arx_cat(out, o, cls)
          o = arx_cat(out, o, ") " as *u8)
          ai_r_verdict(orr[0], n, sigb)
          o = arx_cat(out, o, sigb)
          o = arx_cat(out, o, "\n" as *u8)
          // F1013: the plausible RANGE, not just the point and a yes/no. At small n this is often
          // embarrassingly wide, which is the point -- a reader deserves to see how little the data pins down.
          let cl: *i64 = sys_mmap(8) as *i64
          let ch: *i64 = sys_mmap(8) as *i64
          if ai_r_ci(orr[0], n, 50, cl, ch) == 1 {
              o = arx_cat(out, o, "     95pct CONFIDENCE INTERVAL for r: " as *u8)
              o = arx_catn(out, o, cl[0])
              o = arx_cat(out, o, " to " as *u8)
              o = arx_catn(out, o, ch[0])
              o = arx_cat(out, o, "/1000 (Fisher z)\n" as *u8)
          }
          // CONFOUND CHECK (F1004): a pairwise correlation cannot tell a cause from a shared cause. If
          // controlling for another candidate collapses the relationship, the "driver" was that other
          // column all along -- so say so instead of leaving a confound with a number attached.
          let zi: *i64 = sys_mmap(8) as *i64
          let pr: *i64 = sys_mmap(8) as *i64
          if ai_confound_scan(tcol, cand, nc, n, oi[0], zi, pr) == 1 {
              // one control consumes one dof, so the partial is tested at n-1 (df = n-3)
              let still: i64 = ai_r_significant(pr[0], n - 1)
              o = arx_cat(out, o, "     CONTROLLING FOR " as *u8)
              o = arx_cat(out, o, cand_names[zi[0]] as *u8)
              o = arx_cat(out, o, " (the control that weakens it most): partial r=" as *u8)
              o = arx_catn(out, o, pr[0])
              if still == 1 {
                  o = arx_cat(out, o, "/1000 -- SURVIVES, the relationship is not explained away by it\n" as *u8)
              } else {
                  o = arx_cat(out, o, "/1000 -- CONFOUNDED: it does NOT survive that control, so this is a shared cause, not an effect\n" as *u8)
              }
              // HONEST NAMING (F1005): the control here was picked because it moves the number most.
              // That is a heuristic, and the SAME adjustment is required for a confounder, forbidden for
              // a mediator, and actively harmful for a collider -- so say what this is and is not.
              o = arx_cat(out, o, "     NOTE: that control was picked because it weakens the association most -- a HEURISTIC, not a causal identification. Adjusting is REQUIRED for a confounder, FORBIDDEN for a mediator, and actively harmful for a collider (it manufactures associations from independent columns), and correlation cannot tell those apart. Declare roles via nx_analyst_causal to license a causal reading.\n" as *u8)
          }
      } else {
          o = arx_cat(out, o, "NO ASSOCIATION SUPPORTED BY THIS DATA (family-wise .05 over " as *u8)
          o = arx_catn(out, o, nc)
          o = arx_cat(out, o, " candidates) -- the strongest relationship (" as *u8)
          o = arx_cat(out, o, dname)
          o = arx_cat(out, o, " r=" as *u8)
          o = arx_catn(out, o, orr[0])
          o = arx_cat(out, o, "/1000) is not distinguishable from noise at n=" as *u8)
          o = arx_catn(out, o, n)
          let needn: i64 = ai_min_n(orr[0])
          if needn > 0 { o = arx_cat(out, o, "; an r that size needs n>=" as *u8); o = arx_catn(out, o, needn) }
          o = arx_cat(out, o, "\n" as *u8)
      }
  } else {
      o = arx_cat(out, o, "no measurable driver (all candidates constant)\n" as *u8)
  }
  if o + 2 >= cap { return o }
  out[o] = 0 as u8
  return o
178}
nx_analyst_report.nx source

`nx_analyst_report.nx` source
