Factor-score visualizations (plotFactorScores) + project-summary generator

- matlab/plotFactorScores.m: loads the saved per-model factors and visualizes
  them 6 ways with CANlab core tools — time series (plot_matrix_cols), mango
  heatmap, force-directed graph (canlab_force_directed_graph), correlation
  matrix (plot_correlation_matrix), t-SNE, and UMAP (run_umap) — all colored by
  feature category (domain hues matching the feature summary table). Returns the
  factor struct; saves svg+png to matlab/figures/. Verified end-to-end.
- tools/build_project_summary.py + docs/summarize_project.md: reusable
  "summarize the project now" recipe. Writes a <=1/2 page narrative review + the
  feature table + 3 figures with captions into docs/feature_summary_table.docx,
  pulling live numbers from the template, corpus_stats, and factor_reducibility.
- analysis/factor_reducibility.json: per-category first-PC % (from the MATLAB EFA).
- CONTENTS.md/walkthrough.m: document the new functions. .gitignore: keep figure
  PNGs, exclude the large regenerable SVGs; ignore Office ~$ temp files.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: torwager

.gitignore

@@ -6,6 +6,9 @@ __pycache__/
 # macOS
 .DS_Store
 
+# Office temp/lock files (created while a .docx/.xlsx is open)
+~$*
+
 # mdBook documentation site — both are generated:
 #   book/src   by tools/build_book.py (mirror of docs/)
 #   book/book  by `mdbook build`
@@ -19,6 +22,10 @@ __pycache__/
 # ~36 MB). Regenerate in MATLAB with extractCategoryFactors; kept Dropbox-only.
 /analysis/extracted_factors.mat
 
+# plotFactorScores exports: keep the lightweight PNGs in git; the vector SVGs are large
+# (~6 MB, the force-directed one alone is ~2.6 MB) and regenerable, so keep them Dropbox-only.
+/matlab/figures/*.svg
+
 # Reference PDFs — copyrighted publisher/preprint PDFs of the papers behind each
 # model. Kept in Dropbox only, excluded from git (the docs link to public arXiv/DOI
 # URLs instead, which resolve on the web book). See PDFs/README.md.

analysis/factor_reducibility.json

@@ -0,0 +1 @@
+{"generated":"from extractCategoryFactors corpus","n_timepoints":28237,"categories":[{"category":"emonet","class":"affect","model":"Kragel2019-EmoNet(emonet-pytorch)","nVars":20,"pc1_pct":6.8},{"category":"face_emotion","class":"affect","model":"HSEmotion-enet_b0_8_va_mtl","nVars":8,"pc1_pct":20.7},{"category":"text_emotion","class":"affect","model":"SamLowe/roberta-base-go_emotions","nVars":28,"pc1_pct":9.2},{"category":"text_sentiment","class":"affect","model":"cardiffnlp/twitter-roberta-base-sentiment-latest","nVars":3,"pc1_pct":53.2},{"category":"audioset_tags","class":"audio","model":"AST(BEATs-substitute):MIT/ast-finetuned-audioset-10-10-0.4593","nVars":527,"pc1_pct":4.5},{"category":"clap_embedding","class":"audio","model":"laion/clap-htsat-unfused","nVars":512,"pc1_pct":17.6},{"category":"clap_probe","class":"audio","model":"laion/clap-htsat-unfused","nVars":12,"pc1_pct":20.9},{"category":"chroma","class":"audio","model":"librosa","nVars":12,"pc1_pct":56.3},{"category":"mfcc","class":"audio","model":"librosa","nVars":13,"pc1_pct":31.5},{"category":"action_posteriors","class":"visual","model":"MCG-NJU/videomae-base-finetuned-kinetics","nVars":400,"pc1_pct":4.5},{"category":"dino_embedding","class":"visual","model":"facebook/dinov2-small","nVars":384,"pc1_pct":4.9},{"category":"siglip_embedding","class":"visual","model":"google/siglip2-base-patch16-224","nVars":768,"pc1_pct":5.4},{"category":"siglip_probe","class":"visual","model":"google/siglip2-base-patch16-224","nVars":16,"pc1_pct":9.6},{"category":"interpretable_scalars","class":"mixed","model":"(mixed)","nVars":65,"pc1_pct":9.7}]}

docs/CONTENTS.md

@@ -155,6 +155,7 @@ Details: [`../analysis/web/README.md`](../analysis/web/README.md).
 | `plotFeatureMatrix(C)` | heatmap of the full feature time series, color-coded by category |
 | `factorAnalysisCorpus(C)` | exploratory factor analysis (EFA / `factoran`) across all features + color-coded loadings plot |
 | `extractCategoryFactors(C)` | factor analysis **within each model/category** → `C.extracted_factors` (per-model factor time series), saveable to `.mat` |
+| `plotFactorScores()` | load the saved factors and visualize 6 ways (time series, mango heatmap, force-directed graph, correlation matrix, t-SNE, UMAP) with CANlab tools; saves svg+png to `matlab/figures/` |
 
 ---
 

docs/feature_summary_table.docx

@@ -0,0 +1,52 @@
+# Reusable prompt — "summarize the project now"
+
+When the user says **"summarize the project now"** (or asks for a project summary), produce a
+short narrative review of the whole project and its current annotation state, and write it —
+together with the feature table and 1–3 figures — into **`docs/feature_summary_table.docx`**
+(Word format, for import into Google Docs).
+
+## Audience & tone
+Expert scientists who are **not** necessarily AI/ML experts. Convey **what** was done, the
+**current state** of the annotations, and — importantly — **why** it matters (the scientific
+motivation), clearly and fairly. Be accurate; do not overstate. Narrative ≤ **half a page**.
+
+## What the summary must contain (in this order, in the .docx)
+1. **Narrative review** (two short paragraphs, ≤ ½ page):
+   - *What & why:* naturalistic neuroimaging needs quantitative, second-by-second descriptions
+     of dynamic movie/story stimuli; the scoping review of best-in-class visual/auditory/language
+     models; the selection criteria (large training data, **open weights** for reproducibility,
+     best-in-class validated performance); the selected extractors (interpretable classical-ML /
+     signal-processing features **and** large foundation/transformer models, with concrete
+     examples such as DINOv2, SigLIP2, CLAP, VideoMAE, EmoNet); the six broad domains (visual,
+     auditory, language, social, emotional, situational) organized low-/mid-/high-level (Table 1).
+   - *Application & structure:* how many feature-variable time series were extracted from how many
+     clips/stories and how many seconds (1 Hz); the interactive viewer for QC; the within-domain
+     exploratory factor analysis and what it showed — some model outputs are **irreducible**
+     (first principal factor explains only a few %; e.g., action posteriors, DINOv2, SigLIP2,
+     AudioSet, EmoNet), others **highly reducible** (first component > 50%; e.g., chroma, sentiment).
+2. **Table 1** — the class × level feature-summary table.
+3. **1–3 figures** from `plotFactorScores` (`matlab/figures/`), placed **after the table**, each
+   with a brief caption. Pick the ones that show the annotations most clearly and beautifully
+   (defaults: `01_factor_timeseries`, `04_correlation_matrix`, `05_tsne`).
+
+## How to generate it (mechanics)
+All headline numbers are pulled live so the prose stays correct as the corpus grows:
+- `schema/channel_template.json` → channel and variable counts.
+- `analysis/corpus_stats.json` → stimulus counts, modality split, total minutes.
+- `analysis/factor_reducibility.json` → per-category first-PC % (written by the MATLAB factor
+  analysis; regenerate if the corpus changed — see below).
+
+Steps:
+1. If the corpus or factors changed, refresh inputs first:
+   - In MATLAB: `F = readAnnotationCorpusFull("annotations/corpus"); F = extractCategoryFactors(F, "Save","analysis/extracted_factors.mat");`
+     then `plotFactorScores();` (writes the figures and, via the helper, the reducibility numbers).
+     If `analysis/factor_reducibility.json` is stale, recompute the per-category first-PC % and
+     rewrite it.
+2. **Review and, if needed, rewrite the narrative** in `tools/build_project_summary.py` so it is
+   accurate and fair for the current state (this is the judgment step — do not just run the script
+   blindly; update the prose, examples, and figure choices as the project evolves).
+3. Run: `python3 tools/build_project_summary.py` → writes `docs/feature_summary_table.docx`.
+4. Verify (optional): convert to PDF and eyeball that the narrative is ≤ ½ page, the table fits
+   one page, and the figures + captions render.
+
+The table itself is built by `tools/build_feature_summary.py` (reused by the summary builder).

docs/summarize_project.md

@@ -80,6 +80,12 @@
 % Rows for one clip: pick them with the stimulus id, e.g.
 %   r = C.stim == "BigBuckBunny";  plot(C.time_sec(r), C.X(r, 1));
 
+%% 5.2 Read the FULL corpus
+
+C = readAnnotationCorpusFull("annotations/corpus");
+fprintf("corpus: %d clips, %d scalar channels, %d timepoints\n", ...
+    numel(C.ids), size(C.X, 2), size(C.X, 1));
+
 %% 6. Cross-feature STRUCTURE: correlation, PCA, network graphs
 % Saves figures to analysis/figures/ and returns a results struct.
 res = analyzeCorpus(C);

docs/walkthrough.m

@@ -58,21 +58,27 @@
 vecLeaves = unique(info.Leaf(info.Dtype == "vector"), "stable");
 cats = struct("name",{}, "model",{}, "class",{}, "kind",{}, "cols",{});
 for i = 1:numel(vecLeaves)
+    
     idx = find(info.Leaf == vecLeaves(i));
     kind = "interpretable-vector";
     if info.IsEmbedding(idx(1)), kind = "embedding";
     elseif ismember(vecLeaves(i), ["audioset_tags","action_posteriors"]), kind = "taxonomy"; end
+    
     cats(end+1) = struct("name", vecLeaves(i), "model", info.Model(idx(1)), ...
         "class", info.Class(idx(1)), "kind", kind, "cols", idx(:)'); %#ok<AGROW>
 end
+
 sIdx = find(info.Dtype ~= "vector" & info.Numeric);
+
 cats(end+1) = struct("name","interpretable_scalars", "model","(mixed)", ...
     "class","(mixed)", "kind","interpretable-scalar", "cols", sIdx(:)');
 
 % ---- run FA/PCA per category
 byCat = struct([]); allScores = []; FN=strings(0,1); Cat=strings(0,1);
 Mdl=strings(0,1); Cls=strings(0,1); Meth=strings(0,1); VE=zeros(0,1);
+
 for i = 1:numel(cats)
+
     ca = cats(i);
     cols = ca.cols;
     sub = X(:, cols);
@@ -83,6 +89,7 @@
     keep = sd > 0 & isfinite(sd);
     sub = sub(:, keep); vinfo = vinfo(keep,:); mu = mu(keep); sd = sd(keep);
     Z = (sub - mu) ./ sd;
+    
     d = size(Z,2);
     if d == 0, continue; end