Which hg38 should I use?
The public server at https://api.refgenie.org holds about three dozen genomes related to hg38 (GRCh38). They share the same main chromosomes, but they differ in the extra pieces they carry, in how chromosomes are named, and in which pre-built assets they have. If you have no special need, pull hg38.
hg38 is NCBI's "no-alt analysis set" (GCA_000001405.15). It has no ALT contigs, it has the most pre-built assets, and it is the version most short-read pipelines use.
If "hg38" means the hg38.fa file you download from UCSC, that file is hg38_initial in refgenie, not hg38.
Two facts make the choice easier:
- The main chromosomes match everywhere. The GRCh38 genomes in the catalog all share the same lengths for chr1-22, X, Y and M. Only the names change (
chr1,1,NC_000001.11). - The differences that matter are small. Genomes differ in which extra pieces they include (ALT contigs, decoys, HLA, EBV, unplaced pieces), whether a few regions are masked with N, and whether rare ambiguous bases (IUPAC codes such as R or M) are kept or turned into N. These change where reads land, so pick one genome and use it for every step.
What to pull
Section titled “What to pull”| If you want to... | Pull | Why |
|---|---|---|
| Align short DNA reads and call variants (bwa, bowtie2) | hg38 | No ALT contigs, so aligners that are not ALT-aware keep their mapping quality in duplicated regions. It includes chrEBV and the unplaced pieces. Has FASTA and bwa, bowtie2, hisat2 and suffixerator indexes. |
| The same, with decoys | hg38_noalt_decoy | hg38 plus the hs38d1 decoy contigs, which absorb reads from DNA missing in the reference. Same coordinates as hg38, and the same indexes. |
| ALT-aware alignment (bwa-kit, GATK bundle) | hs38DH | hg38 plus ALT contigs, decoys and HLA alleles. No pre-built assets yet. |
| RNA-seq with GENCODE annotation | hg38 | GENCODE uses the same chr1 ... chrM names and lengths, so its GTF lines up on the main chromosomes. Has a hisat2 index. GENCODE's own FASTA is hg38_primary_gencode, which has no assets yet. |
RNA-seq with Ensembl annotation (names 1, MT) | hg38_primary_ensembl | Names match Ensembl GTFs. Same sequences as hg38_primary_gencode. No pre-built assets yet. |
| UCSC Genome Browser tracks | hg38 | Every hg38 name and length is also in UCSC's hg38, except chrEBV. UCSC's own hg38.fa, with ALT contigs, is hg38_initial, which has FASTA and the same indexes as hg38. |
| Only chromosome sizes, or one region | hg38 | No need to download the genome: pull fasta_index (about 12 KB), or use refgenie getseq. |
| Only the 25 main chromosomes | hg38_primary | chr1-22, X, Y and M, and nothing else. Has FASTA and bwa and bowtie2 indexes. |
For example, to get the FASTA and a bwa index, or only the chromosome sizes, or one region:
refgenie pull hg38/fasta hg38/bwa_indexrefgenie pull hg38/fasta_indexrefgenie seek hg38/fasta_index.chrom_sizesrefgenie getseq -g hg38 -l chr1:10,001-10,100A region is 1-based and inclusive, like in a genome browser. See Coordinates.
Avoid for plain alignment any genome with ALT contigs or patches (hg38_initial, hg38_p14, hg38_full_analysis, hg38_p14_genomic, hg38_p14_gencode), unless your aligner is ALT-aware.
How the hg38 genomes differ
Section titled “How the hg38 genomes differ”Asset availability changes as builds finish, so check with refgenie listr -g <alias>.
| Alias | What it is | Sequences |
|---|---|---|
hg38 | NCBI no-alt analysis set; same as GRCh38-igenomes-ncbi | 195, with EBV |
hg38_analysis_set | UCSC's copy of the same set; same as hg38-igenomes-ucsc | 195, with EBV |
hg38_noalt_decoy | no-alt set plus hs38d1 decoys; same as hg38_decoy_igenomes | 2,580, with 2,385 decoys and EBV |
hg38_full_analysis | NCBI full analysis set | 456, with 261 ALT and EBV |
hg38_full_analysis_plus_decoy | full analysis set plus decoys | 2,841, with 261 ALT, 2,385 decoys and EBV |
hs38DH | 1000 Genomes / Broad GATK bundle | 3,366, with 261 ALT, 2,385 decoys, 525 HLA and EBV |
hg38_initial | UCSC hg38.fa, 2013 release | 455, with 261 ALT |
hg38_p14 | UCSC hg38.p14.fa | 711, with 261 ALT and 256 patches |
hg38_primary | UCSC main chromosomes only | 25 |
hg38_primary_gencode | GENCODE / Ensembl 113 primary assembly; same as hg38_primary_ensembl | 194 |
hg38_p14_gencode | GENCODE all / Ensembl 113 toplevel; same as hg38_toplevel_ensembl | 706, with 261 ALT and 251 patches |
hg38_p14_genomic | NCBI RefSeq, patch release 14 (hg38_p0_genomic is the first release) | 705, with 260-261 ALT and patches |
hg38_mm10 | hg38_primary plus mm10_primary, names prefixed hg38_ and mm10_ | 47 |
Two more differences change a few bases:
- Masked: chr5, 14, 19, 21, 22 and Y carry N in some regions in
hg38,hg38_analysis_set,hg38_noalt_decoy,hg38_full_analysis,hg38_full_analysis_plus_decoyandhs38DH. The others are not masked. - IUPAC codes kept: rare ambiguity codes (such as R or M) are kept in
hg38,hg38_noalt_decoy,hg38_full_analysis,hg38_full_analysis_plus_decoy,hs38DHandhg38_p14_genomic. The others turn them into N.
Every genome above except hg38_primary and hg38_mm10 also has the 169 small unplaced and unlocalized pieces. Genomes marked "same as" hold the same sequences under different names or order. Soft-masked and unmasked files get the same digest, so they count as the same.
Names differ by source: UCSC and NCBI analysis sets use chr1, chrM, chrUn_KI270302v1; GENCODE uses chr1, chrM, KI270302.1; Ensembl uses 1, MT, KI270302.1; RefSeq uses NC_000001.11. chrM is the same 16,569 bp sequence (rCRS) in every GRCh38 genome.
hg38 vs hg38_primary. Both have the same 25 main chromosomes by name and length, but 18 of them differ in content: 12 because hg38 keeps IUPAC codes, 4 because hg38 is masked, and 2 for both reasons. hg38 also has 170 extra pieces (169 unplaced and chrEBV).
To check how two genomes differ, use refgenie compare:
refgenie compare hg38 hg38_primaryFor mouse and yeast, see Which mm39 should I use? and Which yeast genome should I use?.