Spaces:
Running
Running
| /** PrismAudit analytical core. Pure functions; no network, no dependencies. MIT. */ | |
| export const VERSION = '1.0.0'; | |
| export const MAX_ROWS = 10000; | |
| export const REQUIRED_COLUMNS = ['score', 'label', 'group']; | |
| export const DEFAULT_THRESHOLD = 0.50; | |
| export function parseCSV(csv) { | |
| if (typeof csv !== 'string') throw new Error('Expected a CSV text file.'); | |
| csv = csv.replace(/^\uFEFF/, ''); | |
| const table = []; let row = [], val = '', quoted = false; | |
| for (let i = 0; i < csv.length; i++) { | |
| const c = csv[i]; | |
| if (quoted) { | |
| if (c === '"' && csv[i+1] === '"') { val += '"'; i++; } | |
| else if (c === '"') quoted = false; | |
| else val += c; | |
| } else if (c === '"') { | |
| if (val.trim() !== '') throw new Error('Unexpected quote in CSV field.'); | |
| quoted = true; | |
| } else if (c === ',') { row.push(val); val = ''; } | |
| else if (c === '\n' || c === '\r') { | |
| if (c === '\r' && csv[i+1] === '\n') i++; | |
| row.push(val); val = ''; | |
| if (row.some(v => v.trim().length)) table.push(row); | |
| row = []; | |
| if (table.length > MAX_ROWS + 1) throw new Error(`Maximum ${MAX_ROWS.toLocaleString()} data rows allowed.`); | |
| } else { val += c; } | |
| } | |
| if (quoted) throw new Error('Unclosed quoted field in CSV.'); | |
| row.push(val); if (row.some(v => v.trim().length)) table.push(row); | |
| if (table.length < 2) throw new Error('CSV must contain a header and at least one data row.'); | |
| const headers = table.shift().map(s => s.trim().toLowerCase()); | |
| if (new Set(headers).size !== headers.length) throw new Error('CSV has duplicate column names.'); | |
| for (const h of REQUIRED_COLUMNS) if (!headers.includes(h)) throw new Error(`Missing required column: ${h}.`); | |
| const indices = Object.fromEntries(headers.map((h, i) => [h, i])); | |
| if (table.length > MAX_ROWS) throw new Error(`Maximum ${MAX_ROWS.toLocaleString()} rows allowed.`); | |
| const rows = table.map((fields, i) => { | |
| if (fields.length !== headers.length) throw new Error(`Row ${i + 2}: expected ${headers.length} columns, got ${fields.length}.`); | |
| const rawScore = fields[indices.score].trim(), rawLabel = fields[indices.label].trim(); | |
| if (!/^(?:0(?:\.\d+)?|1(?:\.0+)?)$/.test(rawScore)) throw new Error(`Row ${i + 2}: score must be between 0 and 1.`); | |
| if (!/^[01]$/.test(rawLabel)) throw new Error(`Row ${i + 2}: label must be exactly 0 or 1.`); | |
| const group = fields[indices.group].trim(); | |
| if (!group || group.length > 72) throw new Error(`Row ${i + 2}: group is empty or exceeds 72 characters.`); | |
| const id = indices.id === undefined ? String(i + 1) : fields[indices.id].trim().slice(0,120); | |
| return { id, score: Number(rawScore), label: Number(rawLabel), group }; | |
| }); | |
| return validateRows(rows); | |
| } | |
| export function validateRows(rows) { | |
| if (!Array.isArray(rows) || rows.length < 1 || rows.length > MAX_ROWS) throw new Error(`Use 1 to ${MAX_ROWS.toLocaleString()} rows.`); | |
| const groupCount = new Set(); | |
| for (const [i, r] of rows.entries()) { | |
| if (!Number.isFinite(r.score) || r.score < 0 || r.score > 1) throw new Error(`Row ${i + 1}: invalid score.`); | |
| if (r.label !== 0 && r.label !== 1) throw new Error(`Row ${i + 1}: label must be 0 or 1.`); | |
| if (typeof r.group !== 'string' || !r.group.trim() || r.group.length > 72) throw new Error(`Row ${i + 1}: invalid group.`); | |
| groupCount.add(r.group); | |
| if (groupCount.size > 35) throw new Error('A maximum of 35 unique groups is supported.'); | |
| } | |
| return rows; | |
| } | |
| export const safeDivide = (a, b) => b === 0 ? null : a / b; | |
| export const round = (v, places = 4) => v === null || !Number.isFinite(v) ? null : Number(v.toFixed(places)); | |
| export function confusion(rows, threshold) { | |
| if (!Number.isFinite(threshold) || threshold < 0 || threshold > 1) throw new Error('Threshold must be between 0 and 1.'); | |
| let tp = 0, fp = 0, tn = 0, fn = 0; | |
| for (const r of rows) { | |
| const positive = r.score >= threshold; | |
| if (positive && r.label === 1) tp++; | |
| else if (positive && r.label === 0) fp++; | |
| else if (!positive && r.label === 0) tn++; | |
| else fn++; | |
| } | |
| return { tp, fp, tn, fn }; | |
| } | |
| /** Tie-aware Mann-Whitney (rank statistic) ROC AUC. Undefined if only one observed class. */ | |
| export function auc(rows) { | |
| let positives = 0, negatives = 0; | |
| for (const r of rows) r.label ? positives++ : negatives++; | |
| if (!positives || !negatives) return null; | |
| const sorted = [...rows].sort((a, b) => a.score - b.score); | |
| let rank = 1, sumPositiveRanks = 0; | |
| for (let i = 0; i < sorted.length;) { | |
| let j = i + 1; | |
| while (j < sorted.length && sorted[j].score === sorted[i].score) j++; | |
| const meanRank = (rank + (rank + j - i - 1)) / 2; | |
| for (let k = i; k < j; k++) if (sorted[k].label) sumPositiveRanks += meanRank; | |
| rank += j - i; i = j; | |
| } | |
| return (sumPositiveRanks - positives * (positives + 1) / 2) / (positives * negatives); | |
| } | |
| export function calibration(rows, bins = 10) { | |
| const slots = Array.from({length: bins}, (_, i) => ({index:i, n:0, totalScore:0, totalLabel:0})); | |
| let brierSum = 0; | |
| for (const r of rows) { | |
| const b = Math.min(bins - 1, Math.floor(r.score * bins)); | |
| slots[b].n++; slots[b].totalScore += r.score; slots[b].totalLabel += r.label; | |
| brierSum += (r.score - r.label) ** 2; | |
| } | |
| let ece = 0; | |
| const data = slots.map(({index,n,totalScore,totalLabel}) => { | |
| const confidence = safeDivide(totalScore,n), outcome = safeDivide(totalLabel,n); | |
| if (n) ece += n / rows.length * Math.abs(confidence - outcome); | |
| return {bin:index + 1, n, confidence, outcome}; | |
| }); | |
| return {bins:data, ece, brier:brierSum / rows.length}; | |
| } | |
| export function evaluate(rows, threshold = DEFAULT_THRESHOLD) { | |
| validateRows(rows); | |
| const {tp, fp, tn, fn} = confusion(rows, threshold); | |
| const n = rows.length, p = tp + fn, negative = tn + fp; | |
| const precision = safeDivide(tp, tp + fp); | |
| const recall = safeDivide(tp, p); | |
| const specificity = safeDivide(tn, negative); | |
| const f1 = precision === null || recall === null || precision + recall === 0 ? (precision === 0 || recall === 0 ? 0 : null) : 2 * precision * recall / (precision + recall); | |
| const balancedAccuracy = recall === null || specificity === null ? null : (recall + specificity) / 2; | |
| return { | |
| n, threshold, tp, fp, tn, fn, prevalence:p/n, | |
| accuracy:(tp + tn)/n, precision, recall, specificity, f1, | |
| balancedAccuracy, fpr:safeDivide(fp,negative), fnr:safeDivide(fn,p), | |
| positiveRate:(tp + fp)/n, auc:auc(rows), ...calibration(rows) | |
| }; | |
| } | |
| export function byGroup(rows, threshold) { | |
| const map = new Map(); | |
| for (const r of rows) { if (!map.has(r.group)) map.set(r.group, []); map.get(r.group).push(r); } | |
| return [...map.entries()].sort((a,b)=>a[0].localeCompare(b[0])).map(([group,subset])=>({group, ...evaluate(subset, threshold)})); | |
| } | |
| export function rangeOf(values) { const a=values.filter(x=>x!==null && Number.isFinite(x)); return a.length < 2 ? null : Math.max(...a)-Math.min(...a); } | |
| export function fairness(rows, threshold) { | |
| const groups=byGroup(rows,threshold); | |
| return {groups, demographicParityGap:rangeOf(groups.map(x=>x.positiveRate)), | |
| equalOpportunityGap:rangeOf(groups.map(x=>x.recall)), | |
| falsePositiveRateGap:rangeOf(groups.map(x=>x.fpr)), | |
| minimumGroupN:Math.min(...groups.map(x=>x.n)), | |
| reliable:groups.length >= 2 && groups.every(x=>x.n>=30) && groups.every(x=>x.recall!==null && x.fpr!==null)}; | |
| } | |
| export function rocCurve(rows) { | |
| const p = rows.reduce((s,r)=>s+r.label,0), n=rows.length-p; | |
| if (!p || !n) return []; | |
| const sorted=[...rows].sort((a,b)=>b.score-a.score); | |
| const points=[{fpr:0,tpr:0,threshold:1.000001}]; | |
| let tp=0, fp=0; | |
| for(let i=0;i<sorted.length;) { | |
| const score=sorted[i].score; | |
| while(i<sorted.length && sorted[i].score===score) { if(sorted[i].label)tp++;else fp++;i++; } | |
| points.push({fpr:fp/n,tpr:tp/p,threshold:score}); | |
| } | |
| return points; | |
| } | |
| export function thresholdSweep(rows, step = 0.05) { | |
| const out=[]; | |
| for(let i=0;i<=Math.round(1/step);i++) { | |
| const threshold=Number((i*step).toFixed(4)); | |
| const m=evaluate(rows,threshold), f=fairness(rows,threshold); | |
| out.push({threshold, f1:m.f1, accuracy:m.accuracy, balancedAccuracy:m.balancedAccuracy, precision:m.precision, recall:m.recall, positiveRate:m.positiveRate, parityGap:f.demographicParityGap}); | |
| } | |
| return out; | |
| } | |
| /** Deterministic noncryptographic PRNG, never for security or personal data. */ | |
| export function rng(seed) {let t=seed>>>0;return ()=>{t+=0x6D2B79F5;let x=t; x=Math.imul(x^x>>>15,x|1);x^=x+Math.imul(x^x>>>7,x|61);return ((x^x>>>14)>>>0)/4294967296;};} | |
| export function bootstrapInterval(rows, threshold, metric = 'f1', repeats = 240, seed = 24) { | |
| if(!['f1','accuracy','balancedAccuracy','auc','brier'].includes(metric))throw new Error('Unsupported metric.'); | |
| if (!Number.isInteger(repeats) || repeats < 50 || repeats > 500) throw new Error('Use 50 to 500 bootstrap repeats.'); | |
| validateRows(rows); const random=rng(seed), values=[]; | |
| for (let b=0;b<repeats;b++) { | |
| const sample=Array.from({length:rows.length},()=>rows[Math.floor(random()*rows.length)]); | |
| const metricValue=evaluate(sample,threshold)[metric]; | |
| if(metricValue!==null)values.push(metricValue); | |
| } | |
| if(values.length<Math.ceil(repeats*0.8))return {lower:null,upper:null,repeats,valid:values.length}; | |
| values.sort((a,b)=>a-b); | |
| const quantile=q=>{const at=(values.length-1)*q, lo=Math.floor(at), hi=Math.ceil(at);return values[lo]+(values[hi]-values[lo])*(at-lo);}; | |
| return {lower:quantile(.025),upper:quantile(.975),repeats,valid:values.length}; | |
| } | |
| export function csvEscape(v) {const s=String(v??'');return /[,"\r\n]/.test(s)?`"${s.replace(/"/g,'""')}"`:s;} | |
| export function toCSV(rows, columns) {return [columns.join(','), ...rows.map(r=>columns.map(c=>csvEscape(r[c])).join(','))].join('\r\n')+'\r\n';} | |
| export function syntheticRows(preset='support',count=720,seed=2026) { | |
| if(!['support','quality','education'].includes(preset)) throw new Error('Unknown demo dataset.'); | |
| const random=rng(seed), rows=[], cohorts=['North','Central','South']; | |
| const sigmoid=x=>1/(1+Math.exp(-x)); | |
| for(let i=0;i<count;i++) { | |
| const group=cohorts[i%3]; | |
| const index=i%3; | |
| const latent=random()*2-1; | |
| const groupDelta=preset==='support'?[.22,-.12,-.22][index]:preset==='quality'?[.05,.12,-.1][index]:[-.1,.2,-.16][index]; | |
| const base=preset==='support' ? -.2 : preset==='quality' ? -.48 : .1; | |
| const trueP=sigmoid(base+latent*3+groupDelta); | |
| const label=random()<trueP?1:0; | |
| const noise=(random()-.5)*.35; | |
| const score=Math.max(.005,Math.min(.995,sigmoid(base+latent*3+groupDelta*1.65+noise))); | |
| rows.push({id:`SYN-${String(i+1).padStart(4,'0')}`,score:Number(score.toFixed(4)),label,group}); | |
| } | |
| return rows; | |
| } | |