Merge pull request #532 from propcgamer20-png/fix/parse-reference-per-column-scale

fix: decide reference percent-vs-fraction scale per column, not table-wide

Author: yakew7

assets/profiler-engine.js

@@ -856,11 +856,21 @@
       if (isNaN(share)) return;
       raw.push([String(row[colC]).trim(), String(row[grpC]).trim(), share]);
     });
-    var scale = raw.some(function (r) { return r[2] > 1.5; }) ? 100 : 1;
-    var reference = {};
+    // Percent-vs-fraction scale is decided per column (grouped by the column
+    // identifier), not once across the whole table: a reference file that
+    // mixes conventions between columns would otherwise get the wrong scale
+    // applied to whichever column didn't trigger the heuristic. Mirrors
+    // faircode.profiler.parse_reference.
+    var byCol = {};
     raw.forEach(function (r) {
-      if (!reference[r[0]]) reference[r[0]] = {};
-      reference[r[0]][r[1]] = r[2] / scale;
+      (byCol[r[0]] = byCol[r[0]] || []).push([r[1], r[2]]);
+    });
+    var reference = {};
+    Object.keys(byCol).forEach(function (col) {
+      var pairs = byCol[col];
+      var scale = pairs.some(function (p) { return p[1] > 1.5; }) ? 100 : 1;
+      reference[col] = {};
+      pairs.forEach(function (p) { reference[col][p[0]] = p[1] / scale; });
     });
     return reference;
   }

faircode/SPEC.md

@@ -323,7 +323,9 @@ under-sampling relative to who a model will actually serve. Supplied via `--refe
 
 **Format** - a long-format table with three columns (headers case-insensitive; `column`/`dimension`,
 `group`/`value`/`label`, `share`/`expected`/`percent`). Shares may be fractions (`0.51`) or
-percentages (`51`) - if any value exceeds `1.5` the whole table is read as percentages. Parsed into
+percentages (`51`) - the scale is decided per column (rows grouped by the `column` identifier): if
+any of a column's values exceeds `1.5` that column is read as percentages, so a reference file that
+mixes conventions between columns still parses each column correctly. Parsed into
 `{column: {group: expected_share}}`.
 
 ```

faircode/profiler.py

@@ -385,8 +385,11 @@ def parse_reference(df: pd.DataFrame) -> dict:
     """Parse a long-format reference baseline into {column: {group: share}}.
 
     Expected headers (case-insensitive): a column identifier, a group/value, and
-    a share. Shares may be fractions (0.51) or percentages (51) - if any value
-    exceeds 1.5 the whole table is read as percentages. See SPEC section 8.
+    a share. Shares may be fractions (0.51) or percentages (51); the choice is
+    made per column (grouped by the column identifier) - if any of a column's
+    values exceeds 1.5 that column is read as percentages. Deciding it once
+    across the whole table corrupted a correctly-scaled column in a reference
+    file that mixes conventions between columns. See SPEC section 8.
     """
     lower = {str(c).strip().lower(): c for c in df.columns}
 
@@ -414,10 +417,15 @@ def pick(aliases):
             continue
         raw.append((str(row[col_c]).strip(), str(row[grp_c]).strip(), share))
 
-    scale = 100.0 if any(s > 1.5 for _, _, s in raw) else 1.0
-    reference: dict = {}
+    by_col: dict = {}
     for col, grp, share in raw:
-        reference.setdefault(col, {})[grp] = share / scale
+        by_col.setdefault(col, []).append((grp, share))
+
+    reference: dict = {}
+    for col, pairs in by_col.items():
+        scale = 100.0 if any(s > 1.5 for _, s in pairs) else 1.0
+        for grp, share in pairs:
+            reference.setdefault(col, {})[grp] = share / scale
     return reference
 
 

tests/test_js_parity.py

@@ -281,6 +281,43 @@ def test_python_js_reference_parity_on_unmatched_column(tmp_path):
     assert "reference file's column(s) don't match any profiled dimension: totally_wrong_col" in completed.stderr
 
 
+def test_python_js_parse_reference_mixed_scale_parity(tmp_path):
+    """parse_reference / parseReference decide percent-vs-fraction per column,
+    not once across the whole table, so a reference file mixing conventions
+    between columns parses identically on both engines (#513)."""
+    from faircode.profiler import parse_reference
+
+    ref_df = pd.DataFrame({
+        "column": ["sex", "sex", "race", "race", "race"],
+        "group": ["Female", "Male", "White", "Black", "Other"],
+        "share": [0.6, 0.4, 70, 20, 10],
+    })
+    py_result = parse_reference(ref_df)
+    assert py_result == {
+        "sex": {"Female": 0.6, "Male": 0.4},
+        "race": {"White": 0.7, "Black": 0.2, "Other": 0.1},
+    }
+
+    table_json = tmp_path / "table.json"
+    table_json.write_text(json.dumps({
+        "columns": list(ref_df.columns),
+        "rows": ref_df.to_dict(orient="records"),
+    }), encoding="utf-8")
+
+    script = (
+        "const fs=require('fs');"
+        "require(process.argv[1]);"
+        "const t=JSON.parse(fs.readFileSync(process.argv[2],'utf-8'));"
+        "process.stdout.write(JSON.stringify(globalThis.FairCodeProfiler.parseReference(t)));"
+    )
+    completed = subprocess.run(
+        ["node", "-e", script,
+         str(REPO_ROOT / "assets" / "profiler-engine.js"), str(table_json)],
+        capture_output=True, text=True, encoding="utf-8", check=True,
+    )
+    assert json.loads(completed.stdout) == py_result
+
+
 def test_python_js_json_parity_inconsistent_keys():
     """Records-orient JSON where later records add columns the first one
     doesn't have (#144). The JS parseJSON() used to derive columns from only

tests/test_profiler.py

@@ -340,6 +340,23 @@ def test_parse_reference_fraction_and_percent():
     assert pct == {"sex": {"m": 0.4, "f": 0.6}}  # percentages normalized to fractions
 
 
+def test_parse_reference_mixed_scale_is_decided_per_column():
+    # A reference file assembled from multiple sources: `sex` given as
+    # fractions, `race` given as percentages, in the same file. The
+    # percent-vs-fraction decision used to be made once across the whole
+    # table, so `race`'s 70 pushed a global scale=100 onto `sex`'s already
+    # correct 0.6/0.4, corrupting them to 0.006/0.004 (#513).
+    ref = parse_reference(pd.DataFrame({
+        "column": ["sex", "sex", "race", "race", "race"],
+        "group": ["Female", "Male", "White", "Black", "Other"],
+        "share": [0.6, 0.4, 70, 20, 10],
+    }))
+    assert ref == {
+        "sex": {"Female": 0.6, "Male": 0.4},
+        "race": {"White": 0.7, "Black": 0.2, "Other": 0.1},
+    }
+
+
 def test_parse_reference_percent_string_values():
     # "49%" used to raise inside float() and get silently dropped by the
     # bare except - the whole --reference file went to {} with no error.