[TejusK123]

C4: SHAP values, the default output of AutoDeep visualize

These replace the single decision trees of Figs 2-4. A single tree is one of the model's 2,949, so it says little about how the model as a whole uses a feature.

AutoDeep visualize (new explain.py, using XGBoost's exact TreeSHAP via pred_contribs; no new dependency)

• Writes to plots<timestamp>/ (previously tree_plots<timestamp>/):
  • shap_summary_<class>.pdf, one per class (the new Figs 2-4)
  • shap_importance.pdf (mean absolute SHAP value per feature and class)
  • shap_dependence_<feature>.pdf for 5' homogeneity, both overhangs and folding energy
  • shap_values.csv and shap_importance.csv, the numbers behind the plots
• Options: --data CSV... explains a run, e.g. AutoDeepRun/fully_formatted_data.csv (the default is the bundled training data). --format pdf|svg. --legacy_importance gives the old gain, weight and cover plots unchanged (Tejus's request). --trees is unchanged.
• Figures: vector PDF or SVG, 8 pt Helvetica (Arial or DejaVu Sans where Helvetica is missing), text kept as text (TrueType embedded in PDF, <text> in SVG). Features carry their Table 1 names. All plots share one feature order.
• Colours follow the dataviz skill's reference palette: classes in its first three categorical slots, in fixed order; a feature's value as one blue ramp; blanks in grey; ink-coloured text. The palette validator couldn't run (no Node.js on this Mac); these slots are the ones the palette documents as passing all pairs in light mode. Aqua is below 3:1 contrast, so the bar chart has a legend and a CSV.
• The wrapper no longer requires an AutoDeepRun/ folder in the current directory; nothing in visualize used it.

AutoDeep infer: xgboost_judgement.csv gains shap_top1_feature, shap_top1_value, ... up to shap_top3: each locus's three largest SHAP contributions to its predicted label, signed. Tejus asked whether one header would do, so I checked first. On the training data, the 2,907 loci have 458 different ordered top-three lists, and the most common covers 8%; on Pomonella, 65 lists across 212 loci. So the columns are per locus. The infer help now names the output file correctly (xgboost_judgement.csv, not AutoDeep_results.csv).

Tests (written first; all 13 failed before the code)

• tests/test_explain.py: SHAP values add up to the raw scores; blanks get values; the top three are the largest by size for the predicted class; every feature has a Table 1 name.
• tests/test_visualize.py: the default files and tables; --legacy_importance; PDF text as embedded TrueType; SVG text as text; --data with blank overhangs.
• tests/test_inference_columns.py: the top-three columns match the SHAP values.
• tests/test_example.py: the tutorial's expected output, regenerated, has the new columns; their values are compared with a 1e-5 tolerance because XGBoost's arithmetic differs slightly between Linux and Mac. The old columns are unchanged.

I rendered every figure for the shipped model on the training data and checked each one by eye. That led to two fixes: "|SHAP|" read as "lSHAPl" in Helvetica, and the colour bar was too heavy.

Paper: METHODS_CHANGES.md (C4) has the old text, the new Methods text and a note on the Results paragraph that reads the trees. Make the paper's figures after D1 retrains the model.

Results. Locally, with the testing folder: 150 passed. CI: see the checks below.

🤖 Generated with Claude Code