@datagrok/proteomics 1.0.1 → 1.2.0

package/src/analysis/log2-scale.ts

@@ -0,0 +1,139 @@
+import * as grok from 'datagrok-api/grok';
+import * as ui from 'datagrok-api/ui';
+import * as DG from 'datagrok-api/dg';
+
+import {SEMTYPE} from '../utils/proteomics-types';
+import {log2TransformColumns, copyAsLog2Columns, detectLog2Status} from '../parsers/shared-utils';
+
+/**
+ * Post-import correction for the log2 scale of intensity data.
+ *
+ * At import each parser decides whether the intensities are raw (needs a log2
+ * transform) or already log2-transformed (copy as-is). That decision is a
+ * magnitude heuristic (`detectLog2Status`) and has misfired on small-magnitude
+ * linear intensities — values that happen to sit in the [0, 30] "looks like
+ * log2" band get copied instead of transformed, producing nonsense ±thousands
+ * fold changes downstream. This module lets the analyst override that call
+ * without re-importing.
+ *
+ * The rebuild works off the ORIGINAL (non-`log2(...)`) intensity columns, which
+ * every parser keeps pristine — normalization/imputation only ever mutate the
+ * `log2(...)` copies in place. So re-deriving the `log2(...)` columns is always
+ * valid and, by design, discards any normalization/imputation/DE that ran on the
+ * old values; those steps must be re-run, which the dialog warns about.
+ */
+
+/** Original (pre-`log2(...)`) intensity column names — the pristine source the
+ * rebuild derives from. Excludes the `log2(...)` copies themselves. */
+export function getIntensityOriginals(df: DG.DataFrame): string[] {
+  return df.columns.toList()
+    .filter((c) => c.semType === SEMTYPE.INTENSITY && !c.name.startsWith('log2('))
+    .map((c) => c.name);
+}
+
+/** Infers whether the current `log2(...)` columns were produced by a transform
+ * (`Math.log2(orig)`) or a straight copy (`orig`, i.e. treated as already log2).
+ * Scans until the first decisive non-null positive row — the two branches never
+ * coincide for a positive value (`log2(x) ≠ x` for all x > 0). Returns 'unknown'
+ * when no `log2(...)` column or no decisive row exists. */
+export function detectCurrentLog2Applied(
+  df: DG.DataFrame, originalNames: string[],
+): 'transform' | 'copy' | 'unknown' {
+  for (const name of originalNames) {
+    const orig = df.col(name);
+    const l2 = df.col(`log2(${name})`);
+    if (!orig || !l2) continue;
+    for (let i = 0; i < df.rowCount; i++) {
+      if (orig.isNone(i) || l2.isNone(i)) continue;
+      const o = Number(orig.get(i));
+      const v = Number(l2.get(i));
+      if (!(o > 0) || !Number.isFinite(v)) continue;
+      if (Math.abs(v - Math.log2(o)) < 1e-4) return 'transform';
+      if (Math.abs(v - o) < 1e-4) return 'copy';
+    }
+  }
+  return 'unknown';
+}
+
+/** Rebuilds the `log2(...)` columns from the originals under the chosen scale:
+ * `alreadyLog2` copies as-is, otherwise applies the log2 transform. Removes the
+ * existing `log2(...)` columns first (so a re-run doesn't duplicate) and clears
+ * stale downstream pipeline tags — the base data changed, so any prior
+ * normalize/impute/DE is invalid and must be re-run. No-op (returns false) when
+ * the requested scale already matches what's applied. */
+export function applyLog2Scale(df: DG.DataFrame, alreadyLog2: boolean): boolean {
+  const originals = getIntensityOriginals(df);
+  if (originals.length === 0) return false;
+
+  const current = detectCurrentLog2Applied(df, originals);
+  const target = alreadyLog2 ? 'copy' : 'transform';
+  if (current === target) return false;
+
+  for (const name of originals) {
+    const l2 = `log2(${name})`;
+    if (df.col(l2)) df.columns.remove(l2);
+  }
+  if (alreadyLog2)
+    copyAsLog2Columns(df, originals);
+  else
+    log2TransformColumns(df, originals);
+
+  // Base intensities were re-derived — anything computed from the old log2
+  // columns is stale. Drop the completion tags so viewers gate correctly and
+  // the analyst re-runs from Normalize.
+  for (const tag of ['proteomics.normalized', 'proteomics.imputed',
+    'proteomics.de_complete', 'proteomics.de_method'])
+    df.setTag(tag, '');
+  return true;
+}
+
+/** Dialog to review and override the log2 scale of the imported intensities.
+ * Seeds the checkbox from the scale actually applied at import (inferred), not a
+ * re-detection, so it reflects reality; shows the magnitude heuristic's read as
+ * an advisory hint. */
+export function showLog2ScaleDialog(df: DG.DataFrame): void {
+  const originals = getIntensityOriginals(df);
+  if (originals.length === 0) {
+    grok.shell.warning('No intensity columns found — nothing to rescale.');
+    return;
+  }
+
+  const current = detectCurrentLog2Applied(df, originals);
+  const detection = detectLog2Status(df, originals);
+
+  const alreadyLog2 = ui.input.bool('Data is already log2-transformed', {
+    value: current === 'copy',
+    tooltipText: 'On: intensities are used as-is. Off: a log2 transform is applied. ' +
+      'Flip this if fold changes look wildly off — the import heuristic can misread ' +
+      'small-magnitude raw intensities as already-log2.',
+  });
+
+  const hint = ui.divText(`Auto-detection: ${detection.message}.` +
+    (current !== 'unknown' ? ` Currently applied: ${current === 'copy' ?
+      'used as-is (no transform)' : 'log2-transformed'}.` : ''));
+  hint.style.cssText = 'font-style:italic;color:#888;margin:4px 0;font-size:12px;max-width:420px;';
+
+  const pipelineRan = ['proteomics.normalized', 'proteomics.imputed', 'proteomics.de_complete']
+    .some((t) => df.getTag(t) === 'true');
+  const warn = ui.divText(
+    'Normalize / Impute / Differential Expression have already run. Changing the ' +
+    'scale resets those steps — re-run them from Analyze.');
+  warn.style.cssText = 'color:#b26a00;margin:4px 0;font-size:12px;max-width:420px;';
+  warn.style.display = pipelineRan ? '' : 'none';
+
+  ui.dialog('Set Log2 Scale')
+    .add(alreadyLog2)
+    .add(hint)
+    .add(warn)
+    .onOK(() => {
+      const changed = applyLog2Scale(df, alreadyLog2.value);
+      if (!changed) {
+        grok.shell.info('Scale unchanged.');
+        return;
+      }
+      grok.shell.info(alreadyLog2.value ?
+        'Intensities are now used as-is (no log2 transform). Re-run analysis steps.' :
+        'Intensities are now log2-transformed. Re-run analysis steps.');
+    })
+    .show();
+}

package/src/analysis/normalization.ts

@@ -0,0 +1,255 @@
+import * as grok from 'datagrok-api/grok';
+import * as ui from 'datagrok-api/ui';
+import * as DG from 'datagrok-api/dg';
+
+import {SEMTYPE} from '../utils/proteomics-types';
+import {unpivotIntensities} from '../viewers/qc-computations';
+
+/** Median-centers each specified column in-place.
+ * Subtracts the column median from every non-null value.
+ * Uses getRawData() for bulk array access instead of per-element get/set. */
+export function medianNormalize(df: DG.DataFrame, colNames: string[]): void {
+  for (const name of colNames) {
+    const col = df.col(name);
+    if (!col) continue;
+    if (col.type !== DG.COLUMN_TYPE.FLOAT) {
+      console.warn(`medianNormalize: skipping non-float column "${name}" (type=${col.type})`);
+      continue;
+    }
+
+    const median = col.stats.med;
+    if (isNaN(median)) continue;
+
+    const raw = col.getRawData() as Float32Array | Float64Array;
+    for (let i = 0; i < raw.length; i++) {
+      if (!col.isNone(i))
+        raw[i] -= median;
+    }
+  }
+  df.fireValuesChanged();
+  df.setTag('proteomics.normalized', 'true');
+}
+
+/** Quantile-normalizes the specified columns in-place.
+ * Aligns all column distributions to the same shape by replacing values
+ * with rank-based averages. Missing values are preserved.
+ * Uses getRawData() for bulk array access in tight loops. */
+export function quantileNormalize(df: DG.DataFrame, colNames: string[]): void {
+  if (colNames.length < 2) return;
+
+  const cols = colNames.map((n) => df.col(n))
+    .filter((c) => c != null && c.type === DG.COLUMN_TYPE.FLOAT) as DG.Column[];
+  if (cols.length < 2) return;
+
+  const nRows = df.rowCount;
+
+  // For each column, collect indices of non-missing values and sort by value
+  const colData: {indices: number[]; raw: Float32Array | Float64Array}[] = [];
+  for (const col of cols) {
+    const raw = col.getRawData() as Float32Array | Float64Array;
+    const indices: number[] = [];
+    for (let i = 0; i < nRows; i++) {
+      if (!col.isNone(i))
+        indices.push(i);
+    }
+    // Sort indices by value (ascending)
+    indices.sort((a, b) => raw[a] - raw[b]);
+    colData.push({indices, raw});
+  }
+
+  // Find the maximum number of non-null values across columns
+  const maxValid = Math.max(...colData.map((d) => d.indices.length));
+  if (maxValid === 0) return;
+
+  // Compute rank means using scaled rank alignment
+  // For each rank position r (0..maxValid-1), compute the mean of values
+  // at the corresponding fractional position in each column
+  const rankMeans = new Float64Array(maxValid);
+  for (let r = 0; r < maxValid; r++) {
+    let sum = 0;
+    let count = 0;
+    for (const d of colData) {
+      if (d.indices.length === 0) continue;
+      // Map rank r in [0..maxValid-1] to position in this column's sorted values
+      const pos = (r / (maxValid - 1)) * (d.indices.length - 1);
+      // Interpolate between floor and ceil positions
+      const lo = Math.floor(pos);
+      const hi = Math.min(Math.ceil(pos), d.indices.length - 1);
+      const frac = pos - lo;
+      const val = (1 - frac) * d.raw[d.indices[lo]] + frac * d.raw[d.indices[hi]];
+      sum += val;
+      count++;
+    }
+    rankMeans[r] = sum / count;
+  }
+
+  // Replace each column's sorted values with the corresponding rank mean
+  for (const d of colData) {
+    const n = d.indices.length;
+    if (n === 0) continue;
+    for (let r = 0; r < n; r++) {
+      // Map this column's rank to the global rank mean position
+      const globalPos = maxValid === 1 ? 0 : (r / (n - 1)) * (maxValid - 1);
+      const lo = Math.floor(globalPos);
+      const hi = Math.min(Math.ceil(globalPos), maxValid - 1);
+      const frac = globalPos - lo;
+      const val = (1 - frac) * rankMeans[lo] + frac * rankMeans[hi];
+      d.raw[d.indices[r]] = val;
+    }
+  }
+
+  df.fireValuesChanged();
+  df.setTag('proteomics.normalized', 'true');
+}
+
+/** Performs Variance-Stabilizing Normalization via server-side R script.
+ * Operates on raw (non-log2) intensity columns and writes results to log2 columns.
+ * Falls back to quantile normalization if R environment is unavailable. */
+export async function vsnNormalize(df: DG.DataFrame, colNames: string[]): Promise<void> {
+  try {
+    // Find raw intensity column names by stripping log2() prefix
+    const rawColNames: string[] = [];
+    const log2ColNames: string[] = [];
+    for (const name of colNames) {
+      if (name.startsWith('log2(') && name.endsWith(')')) {
+        const rawName = name.slice(5, -1);
+        if (df.col(rawName)) {
+          rawColNames.push(rawName);
+          log2ColNames.push(name);
+        }
+      }
+    }
+
+    if (rawColNames.length === 0) {
+      // No raw columns found, fall back to quantile
+      if (colNames.length < 2) {
+        grok.shell.warning('Cannot normalize — VSN needs raw intensity columns and quantile fallback needs at least 2 columns');
+        return;
+      }
+      grok.shell.warning('No raw intensity columns found for VSN — using quantile normalization');
+      quantileNormalize(df, colNames);
+      return;
+    }
+
+    // Build clean DataFrame with simple column names (s1, s2, ...)
+    const exprDf = DG.DataFrame.create(df.rowCount);
+    for (let i = 0; i < rawColNames.length; i++) {
+      const src = df.col(rawColNames[i])!;
+      const srcRaw = src.getRawData() as Float32Array | Float64Array;
+      const dst = exprDf.columns.addNewFloat(`s${i + 1}`);
+      dst.init((r) => srcRaw[r]);
+    }
+
+    const result: DG.DataFrame = await grok.functions.call('Proteomics:VsnNormalize', {exprDf});
+
+    // Copy VSN output (glog2 scale) into log2 intensity columns
+    for (let i = 0; i < log2ColNames.length; i++) {
+      const dst = df.col(log2ColNames[i])!;
+      const src = result.col(`s${i + 1}`)!;
+      const dstRaw = dst.getRawData() as Float32Array | Float64Array;
+      const srcRaw = src.getRawData() as Float32Array | Float64Array;
+      for (let r = 0; r < df.rowCount; r++) {
+        if (srcRaw[r] !== DG.FLOAT_NULL)
+          dstRaw[r] = srcRaw[r];
+      }
+    }
+
+    df.fireValuesChanged();
+    df.setTag('proteomics.normalized', 'true');
+  } catch (e: any) {
+    console.warn('VSN normalization failed, using quantile fallback:', e);
+    if (colNames.length < 2) {
+      grok.shell.warning('VSN failed and quantile fallback needs at least 2 columns — data left unnormalized');
+      return;
+    }
+    grok.shell.warning('R environment unavailable — using quantile normalization');
+    quantileNormalize(df, colNames);
+  }
+}
+
+/** Shows a dialog for normalizing intensity columns.
+ * Supports Median Centering, Quantile, and VSN methods with reactive box plot preview.
+ * Displays an inline warning when Spectronaut pre-normalized data is detected. */
+export function showNormalizationDialog(df: DG.DataFrame): void {
+  if (df.getTag('proteomics.normalized') === 'true') {
+    grok.shell.warning('Data already normalized');
+    return;
+  }
+
+  const log2ColNames = df.columns.toList()
+    .filter((c) => c.semType === SEMTYPE.INTENSITY && c.name.startsWith('log2('))
+    .map((c) => c.name);
+
+  const log2Cols = log2ColNames.map((n) => df.col(n)!);
+
+  // Pre-normalized warning banner (NORM-04)
+  const warningDiv = ui.div([], {style: {
+    background: '#FFF3CD', border: '1px solid #FFEEBA', color: '#856404',
+    padding: '8px', margin: '4px 0', borderRadius: '4px',
+    display: df.getTag('proteomics.preNormalized') === 'true' ? '' : 'none',
+  }});
+  warningDiv.textContent =
+    'This data may be pre-normalized (Spectronaut). Additional normalization may distort results.';
+
+  // Method selector (NORM-03)
+  const methodInput = ui.input.choice('Method', {
+    value: 'Median Centering',
+    items: ['Median Centering', 'Quantile', 'VSN'],
+    nullable: false,
+  });
+
+  // Column picker
+  const colsInput = ui.input.columns('Intensity columns', {
+    table: df, available: log2ColNames, value: log2Cols,
+  });
+
+  // Box plot preview container
+  const plotContainer = ui.div([], {style: {
+    width: '100%', height: '250px', border: '1px solid #ddd', marginTop: '8px',
+  }});
+
+  function updatePreview(): void {
+    plotContainer.innerHTML = '';
+    const selected = colsInput.value.map((c: DG.Column) => c.name);
+    if (selected.length === 0) return;
+
+    // Clone DataFrame and apply selected normalization for preview
+    const clone = df.clone(null, selected);
+    const method = methodInput.value;
+    if (method === 'Median Centering')
+      medianNormalize(clone, selected);
+    else if (method === 'Quantile')
+      quantileNormalize(clone, selected);
+    // VSN requires async R call -- show un-normalized distributions as preview
+
+    const longDf = unpivotIntensities(clone, selected);
+    const boxPlot = DG.Viewer.boxPlot(longDf, {
+      valueColumnName: 'Intensity', categoryColumnName: 'Sample',
+    } as any);
+    boxPlot.root.style.width = '100%';
+    boxPlot.root.style.height = '220px';
+    plotContainer.appendChild(boxPlot.root);
+  }
+
+  methodInput.onChanged.subscribe(() => updatePreview());
+  colsInput.onChanged.subscribe(() => updatePreview());
+  updatePreview();
+
+  ui.dialog('Normalize')
+    .add(warningDiv)
+    .add(methodInput)
+    .add(colsInput)
+    .add(plotContainer)
+    .onOK(async () => {
+      const selected = colsInput.value.map((c: DG.Column) => c.name);
+      const method = methodInput.value as string;
+      if (method === 'Median Centering')
+        medianNormalize(df, selected);
+      else if (method === 'Quantile')
+        quantileNormalize(df, selected);
+      else if (method === 'VSN')
+        await vsnNormalize(df, selected);
+      grok.shell.info(`Normalized ${selected.length} columns (${method})`);
+    })
+    .show();
+}

package/src/analysis/pca.ts

@@ -0,0 +1,254 @@
+import * as DG from 'datagrok-api/dg';
+import {GroupAssignment} from './experiment-setup';
+
+/** Transpose a matrix (rows x cols) -> (cols x rows). */
+function transpose(matrix: number[][], rows: number, cols: number): number[][] {
+  const result: number[][] = [];
+  for (let j = 0; j < cols; j++) {
+    const row: number[] = new Array(rows);
+    for (let i = 0; i < rows; i++)
+      row[i] = matrix[i][j];
+    result.push(row);
+  }
+  return result;
+}
+
+/** Multiply matrices A (m x n) and B (n x p) -> C (m x p). */
+function matmul(A: number[][], B: number[][], m: number, n: number, p: number): number[][] {
+  const C: number[][] = [];
+  for (let i = 0; i < m; i++) {
+    const row = new Array(p).fill(0);
+    for (let k = 0; k < n; k++) {
+      const aik = A[i][k];
+      for (let j = 0; j < p; j++)
+        row[j] += aik * B[k][j];
+    }
+    C.push(row);
+  }
+  return C;
+}
+
+/** Jacobi eigendecomposition for a symmetric matrix.
+ *  Returns eigenvalues and eigenvectors sorted descending by eigenvalue. */
+function jacobi(matrix: number[][], n: number): {eigenvalues: number[]; eigenvectors: number[][]} {
+  // Deep copy the matrix
+  const A: number[][] = matrix.map((row) => [...row]);
+
+  // Initialize eigenvectors as identity matrix
+  const V: number[][] = [];
+  for (let i = 0; i < n; i++) {
+    const row = new Array(n).fill(0);
+    row[i] = 1;
+    V.push(row);
+  }
+
+  const maxIter = 100;
+  const tolerance = 1e-10;
+  let converged = false;
+
+  for (let iter = 0; iter < maxIter; iter++) {
+    // Find largest off-diagonal element
+    let maxVal = 0;
+    let p = 0;
+    let q = 1;
+    for (let i = 0; i < n; i++) {
+      for (let j = i + 1; j < n; j++) {
+        if (Math.abs(A[i][j]) > maxVal) {
+          maxVal = Math.abs(A[i][j]);
+          p = i;
+          q = j;
+        }
+      }
+    }
+
+    if (maxVal < tolerance) {
+      converged = true;
+      break;
+    }
+
+    // Compute rotation angle
+    const theta = (A[q][q] - A[p][p]) / (2 * A[p][q]);
+    const t = Math.sign(theta) / (Math.abs(theta) + Math.sqrt(theta * theta + 1));
+    const c = 1 / Math.sqrt(t * t + 1);
+    const s = t * c;
+
+    // Apply rotation to A
+    const app = A[p][p];
+    const aqq = A[q][q];
+    const apq = A[p][q];
+
+    A[p][p] = c * c * app - 2 * s * c * apq + s * s * aqq;
+    A[q][q] = s * s * app + 2 * s * c * apq + c * c * aqq;
+    A[p][q] = 0;
+    A[q][p] = 0;
+
+    for (let i = 0; i < n; i++) {
+      if (i !== p && i !== q) {
+        const aip = A[i][p];
+        const aiq = A[i][q];
+        A[i][p] = c * aip - s * aiq;
+        A[p][i] = A[i][p];
+        A[i][q] = s * aip + c * aiq;
+        A[q][i] = A[i][q];
+      }
+    }
+
+    // Update eigenvectors
+    for (let i = 0; i < n; i++) {
+      const vip = V[i][p];
+      const viq = V[i][q];
+      V[i][p] = c * vip - s * viq;
+      V[i][q] = s * vip + c * viq;
+    }
+  }
+
+  if (!converged)
+    console.warn(`PCA Jacobi did not converge in ${maxIter} iterations (n=${n}); results may be approximate`);
+
+  // Extract eigenvalues and sort descending
+  const eigenvalues = new Array(n);
+  for (let i = 0; i < n; i++)
+    eigenvalues[i] = A[i][i];
+
+  const indices = Array.from({length: n}, (_, i) => i);
+  indices.sort((a, b) => eigenvalues[b] - eigenvalues[a]);
+
+  const sortedEigenvalues = indices.map((i) => eigenvalues[i]);
+  const sortedEigenvectors: number[][] = [];
+  for (let i = 0; i < n; i++) {
+    const row = new Array(n);
+    for (let j = 0; j < n; j++)
+      row[j] = V[i][indices[j]];
+    sortedEigenvectors.push(row);
+  }
+
+  return {eigenvalues: sortedEigenvalues, eigenvectors: sortedEigenvectors};
+}
+
+/** Compute sample-level PCA on intensity columns.
+ *  Returns a NEW sample-level DataFrame (rows = samples, not proteins)
+ *  and the variance explained percentages. */
+export function computePCA(
+  df: DG.DataFrame,
+  intensityCols: string[],
+  groupAssignment: GroupAssignment,
+  nComponents: number = 2,
+): {pcaDf: DG.DataFrame; varianceExplained: number[]} {
+  const nSamples = intensityCols.length;
+  const nProteins = df.rowCount;
+
+  // Step 1: Build transposed matrix (nSamples x nProteins)
+  // Each row = one sample, each column = one protein's intensity across that sample
+  const matrix: number[][] = [];
+
+  // Compute protein means for imputation (mean across samples for each protein)
+  const proteinMeans: number[] = new Array(nProteins).fill(0);
+  const proteinCounts: number[] = new Array(nProteins).fill(0);
+
+  for (const colName of intensityCols) {
+    const col = df.col(colName);
+    if (!col) continue;
+    for (let i = 0; i < nProteins; i++) {
+      if (!col.isNone(i)) {
+        proteinMeans[i] += col.get(i) as number;
+        proteinCounts[i]++;
+      }
+    }
+  }
+  for (let i = 0; i < nProteins; i++)
+    proteinMeans[i] = proteinCounts[i] > 0 ? proteinMeans[i] / proteinCounts[i] : 0;
+
+  // Build sample rows with imputation
+  for (const colName of intensityCols) {
+    const col = df.col(colName);
+    const row: number[] = new Array(nProteins);
+    for (let i = 0; i < nProteins; i++) {
+      if (!col || col.isNone(i))
+        row[i] = proteinMeans[i];
+      else
+        row[i] = col.get(i) as number;
+    }
+    matrix.push(row);
+  }
+
+  // Step 2: Center each column (protein) by subtracting its mean across samples
+  const colMeans: number[] = new Array(nProteins).fill(0);
+  for (let j = 0; j < nProteins; j++) {
+    for (let i = 0; i < nSamples; i++)
+      colMeans[j] += matrix[i][j];
+    colMeans[j] /= nSamples;
+  }
+  for (let i = 0; i < nSamples; i++) {
+    for (let j = 0; j < nProteins; j++)
+      matrix[i][j] -= colMeans[j];
+  }
+
+  // Step 3: Compute covariance matrix S (nSamples x nSamples)
+  // S = X * X^T / (nProteins - 1) -- small matrix since nSamples << nProteins
+  const Xt = transpose(matrix, nSamples, nProteins);
+  const S = matmul(matrix, Xt, nSamples, nProteins, nSamples);
+  const divisor = nProteins > 1 ? nProteins - 1 : 1;
+  for (let i = 0; i < nSamples; i++) {
+    for (let j = 0; j < nSamples; j++)
+      S[i][j] /= divisor;
+  }
+
+  // Step 4: Eigendecompose S
+  const {eigenvalues, eigenvectors} = jacobi(S, nSamples);
+
+  // Step 5: PC scores are the eigenvectors scaled by sqrt(eigenvalue)
+  const scores: number[][] = [];
+  for (let i = 0; i < nSamples; i++) {
+    const row: number[] = [];
+    for (let k = 0; k < Math.min(nComponents, nSamples); k++) {
+      const scale = eigenvalues[k] > 0 ? Math.sqrt(eigenvalues[k]) : 0;
+      row.push(eigenvectors[i][k] * scale);
+    }
+    scores.push(row);
+  }
+
+  // Step 6: Compute variance explained. Clamp eigenvalues to >= 0 for both
+  // totalVariance and per-PC pct so numerical noise can't produce negative percentages.
+  const totalVariance = eigenvalues.reduce((sum, v) => sum + Math.max(v, 0), 0);
+  const varianceExplained: number[] = [];
+  for (let k = 0; k < Math.min(nComponents, nSamples); k++) {
+    const pct = totalVariance > 0 ? (Math.max(eigenvalues[k], 0) / totalVariance) * 100 : 0;
+    varianceExplained.push(Math.round(pct * 10) / 10);
+  }
+
+  // Step 7: Create sample-level DataFrame. PCA on <2 samples is meaningless;
+  // produce stable column labels rather than "PC1 (NaN%)".
+  const pc1Pct = varianceExplained.length > 0 && isFinite(varianceExplained[0]) ? varianceExplained[0] : 0;
+  const pc1Name = nSamples >= 2 ? `PC1 (${pc1Pct}%)` : 'PC1';
+  const pc2Pct = varianceExplained.length >= 2 && isFinite(varianceExplained[1]) ? varianceExplained[1] : 0;
+  const pc2Name = nComponents >= 2 && varianceExplained.length >= 2 && nSamples >= 2
+    ? `PC2 (${pc2Pct}%)`
+    : 'PC2';
+
+  const sampleNames = DG.Column.fromStrings('SampleName', intensityCols);
+  const pc1Col = DG.Column.fromFloat32Array(pc1Name,
+    new Float32Array(scores.map((s) => s[0])));
+  const columns: DG.Column[] = [sampleNames, pc1Col];
+
+  if (nComponents >= 2) {
+    const pc2Col = DG.Column.fromFloat32Array(pc2Name,
+      new Float32Array(scores.map((s) => s.length > 1 ? s[1] : 0)));
+    columns.push(pc2Col);
+  }
+
+  // Map each sample to its group
+  const groupNames: string[] = intensityCols.map((colName) => {
+    if (groupAssignment.group1.columns.includes(colName))
+      return groupAssignment.group1.name;
+    if (groupAssignment.group2.columns.includes(colName))
+      return groupAssignment.group2.name;
+    return 'Unknown';
+  });
+  const groupCol = DG.Column.fromStrings('Group', groupNames);
+  columns.push(groupCol);
+
+  const pcaDf = DG.DataFrame.fromColumns(columns);
+  pcaDf.name = 'PCA';
+
+  return {pcaDf, varianceExplained};
+}