Reproduce KaryoScope v2.1 karyotyping of the T2T-HG002 v1.1 diploid assembly end to end (macOS / Apple Silicon, ~20 min at 8-10 threads, 16 GB+ RAM)

reproduce_karyoscope_hg002.sh

#!/usr/bin/env bash
# =============================================================================
# Reproduce KaryoScope annotation + karyotype plots on HG002 (T2T-HG002 v1.1)
# -----------------------------------------------------------------------------
# Tested on:  MacBook Pro (Apple M1 Max) - 10 cores (8P + 2E), 32 GB RAM
#             macOS 26.5.1  |  KaryoScope v2.1
#
# Requirements
#   - Homebrew            https://brew.sh
#   - Conda (miniforge)   https://docs.conda.io
#   - >= 16 GB RAM        (v2.1 HKS backend peaks at ~10 GB resident memory)
#   - ~50 GB free disk    (HKS CHM13 database ~36 GB extracted; the download
#                          archive is kept until extraction succeeds, plus the
#                          ~1 GB genome and the results/ output)
#   - Runtime: ~20 min for `annotate` at --threads 10 on the machine above;
#              scales with core count. Set --threads to your CPU core count.
# =============================================================================

set -euo pipefail

# --- Install Rust (needed to build HKS) --------------------------------------
brew install rust

# --- Install KaryoScope ------------------------------------------------------
git clone https://github.com/barthel-lab/KaryoScope.git
cd KaryoScope

# Create a dedicated Conda environment and install KaryoScope into it
conda env create -f environment.yml
conda activate karyoscope
pip install -e .

# --- Install HKS -------------------------------------------------------------
# HKS = Hierarchical K-mer Sets (https://github.com/jnalanko/HKS)
# A variable-length k-mer index with hierarchical labels; KaryoScope v2.1's
# indexing backend (~2.5-3x faster, ~1/3 the peak RAM vs the old KMC backend).
git clone --recurse-submodules https://github.com/jnalanko/HKS.git
cargo install --path HKS --root "$CONDA_PREFIX"

# --- Download the HKS k-mer database for the CHM13 reference -----------------
# ~36 GB extracted. Ensure enough free disk for the archive + extracted copy.
karyoscope download HKS_human_CHM13_v2

# --- Download the HG002 diploid assembly (~1 GB compressed) ------------------
curl -O https://s3-us-west-2.amazonaws.com/human-pangenomics/T2T/HG002/assemblies/hg002v1.1.fasta.gz

# --- Annotate ----------------------------------------------------------------
# Emits per-featureset annotations (chromosome, region, repeat,
# subtelomere, gene, acrocentric). --no-bgzip keeps outputs uncompressed.
karyoscope annotate --input hg002v1.1.fasta.gz --outdir results/ --threads 10 --no-bgzip

# --- (Optional) profile CPU/RAM during the run -------------------------------
# This is how the resource-usage figure was produced (pip install psrecord).
# Wrap the command in quotes; --include-children captures the worker threads.
#   psrecord "karyoscope annotate --input hg002v1.1.fasta.gz --outdir results/ --threads 10 --no-bgzip" \
#     --interval 1 --include-children --log stats.txt --plot usage.png

# --- Generate karyotype plots ------------------------------------------------
# HG002 is male, so pass --sex male. --no-scaffolding treats the assembly as-is.
COMMON="--input hg002v1.1.fasta.gz --outdir results/ --threads 10 --sex male --no-scaffolding --no-bgzip"
karyoscope karyotype $COMMON --mode genome      --feature-set chromosome
karyoscope karyotype $COMMON --mode centromere  --feature-set region
karyoscope karyotype $COMMON --mode subtelomere --feature-set subtelomeric