equity-scorer_skill

Overview

This skill computes HEIM diversity and equity metrics from VCF or ancestry CSV inputs and produces a reproducible markdown report with figures and tables. It calculates heterozygosity, pairwise FST, PCA visualisations, ancestry summaries, and a composite HEIM Equity Score (0–100) to quantify representation across populations. Outputs include plots, CSV tables, a JSON score, and rerunnable commands for reproducibility.

How this skill works

The tool detects whether the input is a VCF or an ancestry CSV, extracts sample and population labels, then runs appropriate analyses. For VCFs it parses genotypes to compute per-site and per-population heterozygosity, pairwise FST, and PCA. For CSVs it computes representation statistics, ancestry distributions, and geographic spread. Finally it combines Representation Index, Heterozygosity Balance, FST Coverage, and Geographic Spread with configurable weights into the HEIM Equity Score and writes a markdown report with embedded figures and a reproducibility block.

When to use it

• Assess population representation and equity in a biobank, cohort, or study
• Compare diversity between two or more cohorts
• Generate PCA plots colored by ancestry for population structure checks
• Produce a reproducible analysis package (report, figures, tables) for publication
• Screen VCF inputs for underrepresented populations before association analyses

Best practices

• Provide clear population or ancestry labels in sample metadata to improve accuracy
• Use cyvcf2 for large VCFs (>1 GB) or subset variants before full analyses
• Run ancestry-aware association methods if HEIM score indicates imbalance
• Include the reproducibility folder (commands, environment, checksums) with reports
• Report HEIM score alongside study demographics and recruitment strategies

Example use cases

• Score diversity of a research cohort VCF and identify underrepresented continental groups
• Compare HEIM scores for two cohorts to guide targeted recruitment efforts
• Produce PCA and heterozygosity plots for a manuscript methods section
• Summarise ancestry composition from a clinical sequencing rollout before downstream analyses
• Generate a reproducible archive (report + commands) to accompany data release