NAME
Cn::Bioinf - FASTA I/O in XS, BLAST hit ranking, and alignment plots and tables
VERSION
version 0.01
SYNOPSIS
use Cn::Bioinf ':all';
my $seqs = fasta2hash('proteome.fa.gz'); # { defline => sequence }
my $one = fasta2hash('proteome.fa', 'P12345'); # just that sequence
hash2fasta_file($seqs, 'copy.fa');
my $part = fasta_region('genome.fa', 'chr1:1000-2000'); # as samtools faidx
# sequences as strings
my $rc = reverse_complement('ATGAAACTG'); # CAGTTTCAT
my $protein = translate('ATGAAACTGTAA', to_stop => 1); # MKL
my $orfs = find_orfs($one, table => 11, min_length => 100);
my $hits = motif_search($one, 'GRATYC', strand => 'both');
my $gc = gc_content($one);
my $kmers = kmer_count($one, 4);
my $stats = assembly_stats($seqs); # N50 and the rest
my $pi = isoelectric_point($protein);
my $hits = get_best_alignment_hit('blast.json', 'bit_score');
# the PDB structures that match a sequence, how well, and what kind they are
my $pdb = pdb_search(seq => $one);
print "$pdb->[0]{id} $pdb->[0]{pident}% $pdb->[0]{method} $pdb->[0]{resolution}\n";
# one clustalo run: plot_msa keeps the guide tree, and plot_phylo draws it
plot_msa(
fasta => 'orthologs.fa', # or { name => sequence }
filename => 'msa.svg', # .png, .pdf, ... too
'tree_file' => 'orthologs.newick',
title => 'EF-3',
);
plot_phylo('tree_file' => 'orthologs.newick', 'output_file' => 'tree.svg', title => 'EF-3');
# a polygenic score for each sample of a VCF, from a PGS Catalog scoring file
my $scores = pgs_score(vcf => 'genome.vcf.gz', weights => 'PGS000138.txt.gz');
# each sample's sex, from its heterozygosity on X
my $sex = sex_check(vcf => 'cohort.vcf.bz2'); # { sample => { sex => 'female', ... } }
# whether two people are parent and child: 1 or 0
my $is = parent(child => 'child.vcf.gz', parent => 'father.vcf.gz');
# how every two people are related: father-son, brother-sister, ...
my $kin = relatedness('mom.vcf.gz', 'dad.vcf.gz', 'kid.vcf.gz');
print $kin->{'kid'}{'dad'}{category}; # by the sample names in the VCFs
# how well a test VCF's calls agree with a truth VCF's, sample by sample
my $conc = concordance(truth => 'NA12878.truth.vcf.gz', test => 'NA12878.run42.vcf.gz');
print $conc->{'NA12878'}{metrics}{genotype_concordance};
# each sample's ABO and RhD blood type, and the genotype behind each
my $blood = blood_type(vcf => 'exome.vcf.gz');
print "$blood->{'NA12878'}{type} ($blood->{'NA12878'}{abo}{genotype})\n"; # A+ (AO)
# the 41 HIrisPlex-S markers, as the webtool's CSV wants them
my $g = hirisplex_genotypes(vcf => 'genome.vcf.gz', file => 'hirisplexs.csv');
# ... and a prediction from a multinomial logistic model you supply
my $p = trait_predict(genotypes => $g, model => 'my_model.tsv');
print $p->{'NA12878'}{eye}{call};
DESCRIPTION
FASTA I/O in XS, with samtools's index for fetching a part of a file; the everyday operations on a sequence (its reverse complement, its translation under any of NCBI's genetic codes, its open reading frames, GC content, k-mers, motifs, molecular weight and isoelectric point, and an assembly's N50); BLAST hit ranking, a search of the PDB's structures for a sequence, and multiple-sequence-alignment plots and LaTeX tables; polygenic scores from a VCF and a PGS Catalog scoring file; and, from VCFs, each sample's sex, whether two people are parent and child, how every two people are related, how well one VCF's calls agree with another's, each sample's ABO and RhD blood type, and the genotypes of the HIrisPlex-S eye, hair and skin colour panel, with a trait predictor for any multinomial logistic model you supply.
Nothing is exported by default; ask for functions by name or with :all. Every function dies (via Carp::croak) on bad arguments, with a message that starts with the name of the function that raised it, as in fasta2hash: couldn't find "four" in x.fa. pdb_search, pgs_score, sex_check, parent, relatedness, concordance, blood_type, hirisplex_genotypes, trait_predict, plot_msa, plot_phylo, msa_quality_table and clustal_view_residues take name => value pairs, not a hash ref.
Alien::Bioinf
Clustal Omega, BLAST+, PLINK 2 and the Python that draws the plots come from Alien::Bioinf, which installs them module-locally and never uses PATH. It is recommended rather than required, because it can only be installed where NCBI builds BLAST+ (Linux and macOS on x86_64 and aarch64, and Windows on x86_64) and it needs the network; PLINK 2 has no build for Linux on aarch64, so there it installs the rest. fasta2hash, hash2fasta_file, get_best_alignment_hit, sex_check, parent, relatedness, concordance, hirisplex_genotypes and trait_predict work without it; pgs_score, plot_msa, plot_phylo, msa_quality_table, and clustal_view_residues given an unaligned file, die saying that they need it. A CPAN client does not install a recommended module unless asked, so install it first:
cpanm Alien::Bioinf
cpanm Cn::Bioinf
or, from a clone of the repository, where it is alien/Alien-Bioinf:
cpanm ./alien/Alien-Bioinf
cpanm .
That downloads nothing it can reuse: archives are cached (ALIEN_BIOINF_CACHE, default ~/.cache/alien-bioinf), a clustalo or BLAST+ already on the machine at the newest version is copied instead (ALIEN_BIOINF_CLUSTALO, ALIEN_BIOINF_BLAST, or PATH), and pip reuses the wheels in its own cache. The Python packages go into a venv of their own, which nothing installed into the base Python can break. To check for and apply updates:
perl -MAlien::Bioinf -MData::Dumper -e 'print Dumper(Alien::Bioinf->check_updates)'
perl -MAlien::Bioinf -e 'print "$_\n" for Alien::Bioinf->update'
Provenance in the images
Every PNG, SVG, PDF, PS or EPS image these functions draw carries its whole provenance on one line, as its Creator metadata and nothing else, just as Matplotlib::Simple writes it. The line names the calling script (its full path), the function, this file and its version, the Alien::Bioinf version, the user who ran it, the computer it ran on (hostname and operating system), the perl version and path, and what drew it: msa_plot.py, the Python version and path, the matplotlib version, and for a tree the Biopython and NumPy versions too. The line has no date; an SVG has the <dc:date> matplotlib writes beside it, taken from SOURCE_DATE_EPOCH where that is set. After a ; come the image's title (or "untitled") and what it was made from and how, with the full path and SHA-256 of each file:
plot_msa: the FASTA file and how many sequences it holds (or the number of sequences in a hash ref), the ungapped copy of it that Clustal Omega read, with the sequences nameds1,s2and so on, the alignment Clustal Omega wrote, with the names put back, the Clustal Omega version, the exact command, and themsa_fileandtree_filekept, if any.plot_phylo: the same when it aligns, with the guide tree it drew; otherwise the newick file it drew. Then how many negative branch lengths were drawn as 0, if any; the tips, with the label each was shown as; and the whole newick tree that was drawn.msa_quality_table: the metric shown, and either the BLAST report it read or the FASTA file, its ungapped copy, the report blastp wrote, the blastp version, the exact command, and thealignment_jsonkept, if any.
For example:
/home/me/work/run.pl called using "plot_phylo" in /.../Cn/Bioinf.pm
version 0.01 with Alien::Bioinf 0.01 by user me on host myhost (linux)
with Perl 5.44.0 (/usr/bin/perl), drawn by /.../msa_plot.py with
Python 3.14.2 (/.../venv/bin/python),
matplotlib 3.11.2, Biopython 1.87, NumPy 2.4.6; titled "DEG20010421";
from the newick file /home/me/work/t.newick (SHA-256 f0e8...); 4 tips:
S.cerevisiae, ...; the tree as drawn, in newick: (S.cerevisiae:0.389085,...);
An SVG holds it in <dc:creator>; exiftool or identify -verbose shows it in a PNG or PDF.
FUNCTIONS
fasta2hash($file, $key)
Reads a FASTA file (gzip-compressed if its name ends in .gz, in any case, which needs a gzip program on PATH). Returns a hash ref of defline (without the >) => sequence, or, with $key, just the sequence of that defline, reading no further than the record after it. A defline that appears twice is warned about and its sequences concatenated. With $key, reading stops at the defline after that record, so only a repeat that follows it directly is seen; a second record of that name further on is not read, and the first's sequence comes back alone, with no warning. Read the whole file where that matters. Line endings may be \n or \r\n; a file whose lines end in \r alone (classic Mac OS) dies, since without a \n it is all one line. Whitespace (space, tab, \r, \f and \x0b) is dropped from sequences and from the end of deflines, as Biopython drops it, so a defline of x and a space is found as x. Deflines and sequences are bytes, just as they are in the file. A .gz that gzip cannot read to its end, such as a truncated one, dies rather than returning the part that was read.
my $h = fasta2hash('DEG20010421.fa');
hash2fasta_file($hash, $filename, $order, $width)
Writes $hash as FASTA: the keys in @$order (default: sorted), sequences wrapped at $width columns (default 80; 0 for one line each). Returns $filename, and prints wrote $filename to STDOUT, with the name in black on cyan when STDOUT is a terminal. Keys and sequences are written as bytes, as print to a :raw handle writes them, so a string that perl holds as UTF-8 is written as the characters in it. A character above 255 has no single byte and dies; encode such a string first, as with Encode::encode('UTF-8', $name). A key that is empty or holds a line feed dies, as does a sequence that is a reference (unless it is an object that overloads its own text), since fasta2hash could not read any of them back as what was given.
fasta_index($file)
Writes the index of a FASTA file that samtools faidx writes, $file.fai, and returns its name; it prints wrote and that name to STDOUT, as hash2fasta_file does. The index has a line for each sequence: its name (the first word of its defline), its length, the byte where it starts, and how many bases and how many bytes each of its lines holds. Other programs that read a .fai can use it, and fasta_region does.
my $fai = fasta_index('genome.fa'); # genome.fa.fai
A file can be indexed when, within each sequence, every line but the last is the same length, which is samtools's rule; a file that breaks it dies, naming the line. Of two sequences with one name, the first is indexed, with a warning. A compressed file dies, since a place in it cannot be sought.
fasta_region($file, @regions)
The parts of a FASTA file that @regions name, as a hash ref of region => sequence, without reading the rest of the file: the job of samtools faidx.
my $part = fasta_region('genome.fa', 'chr1:1,000-2,000', 'chrM');
print $part->{'chr1:1,000-2,000'};
A region is a sequence's name, for all of it, or name:start-end, name:start (to the end) or name:-end (from the start), counting from 1 with both ends included; commas in the numbers are ignored. A name that has a colon in it, such as HLA-A*01:01:01:01, is taken whole when a sequence has that name. A region that runs past the end of its sequence is cut short there, and one that starts past it is empty, as samtools faidx gives them; a name that is not in the file, a start of 0 and an end before the start die.
It uses $file.fai when that is there, whether fasta_index or samtools wrote it, and warns when the index is older than the FASTA. Without one it reads through the file to make the index, which it does not write: for a large file that will be asked more than once, call fasta_index first. The file must not be compressed.
complement($seq, type => 'DNA')
$seq with each nucleotide replaced by the one it pairs with: A and T, C and G, and each IUPAC ambiguity letter with the letter for the bases its own pair with (R and Y, K and M, B and V, D and H; S, W and N are their own). Case is kept, and anything that is not a nucleotide letter, a gap included, is left as it is.
complement('ATGAAACTG'); # TACTTTGAC
complement('AUGAAACUG', type => 'RNA'); # UACUUUGAC
type is DNA (the default) or RNA, in any case, and says what is written, T or U; either is read in both. These are Biopython's complement and complement_rna.
reverse_complement($seq, type => 'DNA')
complement of $seq, reversed: the other strand, read from its own 5' end.
reverse_complement('ATGAAACTG'); # CAGTTTCAT
transcribe($seq), back_transcribe($seq)
transcribe writes U for every T of $seq, and back_transcribe T for every U, in either case; nothing else changes.
transcribe('ATGAAACTG'); # AUGAAACUG
back_transcribe('AUGAAACUG'); # ATGAAACTG
translate($seq, %args)
The protein that the DNA or RNA $seq codes for, one letter for each three of its own, from its first letter.
translate('GTGGCCATTGTAATGGGCCGCTGAAAGGGTGCCCGATAG'); # VAIVMGR*KGAR*
translate('GTGGCCATTGTAATGGGCCGCTGAAAGGGTGCCCGATAG', to_stop => 1); # VAIVMGR
translate($cds, table => 'Vertebrate Mitochondrial', cds => 1);
table: the genetic code, as NCBI's number for it (1, the standard code, by default) or one of its names in any case, such asStandard,SGC0,BacterialorVertebrate Mitochondrial. The codes are those of NCBI's table, version 4.6: 1 to 6, 9 to 16 and 21 to 33.to_stop: 1 ends the protein before the first stop codon; 0 (the default) writes each stop and carries on.stop_symbol: the character written for a stop,*by default.cds: 1 says$seqis a whole coding sequence, and checks it: it must start with one of the code's start codons, be a multiple of three long, end with a stop codon and have no other. The start codon is then written asM, whatever it codes for inside a protein, and the stop is left out.gap: a character, such as-, three of which make a codon that is written as that character. Without it a gap dies, as any other letter that is not a nucleotide's does, naming the codon.
A codon with an ambiguous letter is given what the codons it stands for agree on: their amino acid when they share one (ATGAARCTG is MKL), * when all are stops, B for aspartate or asparagine, Z for glutamate or glutamine, J for leucine or isoleucine, and X otherwise, a codon that may or may not be a stop included. Case is ignored, and T and U may be mixed.
One or two letters left after the last whole codon are not translated, with a warning; cut the sequence to a multiple of three to avoid it. Codes 27, 28 and 31 read some codons as an amino acid or as a stop, by context: those are translated as the amino acid, with a warning, and to_stop dies with them.
These rules are Biopython's, whose Seq.translate this gives the same answers as, with one exception: an X in a codon dies here, since it is not an IUPAC nucleotide letter, where Biopython reads it as N in some codons.
translate_six_frames($seq, %args)
$seq translated in all six reading frames, as a hash ref: 1, 2 and 3 are the frames that start at its first, second and third letter, and -1, -2 and -3 those that start at the first, second and third letter of its reverse complement. Each protein is written from its own N-terminus.
my $f = translate_six_frames('AUGCUAACAUAAA');
# { 1 => 'MLT*', 2 => 'C*HK', 3 => 'ANI', -1 => 'FMLA', -2 => 'LC*H', -3 => 'YVS' }
table and stop_symbol are as for translate. Letters left after a frame's last whole codon are dropped without a warning, since five of the six frames always have some. The minus frames are numbered as scikit-bio and BLAST number them, which is EMBOSS transeq's -alternative.
find_orfs($seq, %args)
The open reading frames of $seq on both strands, as an array ref of hash refs in order of where they start:
my $orfs = find_orfs($plasmid, table => 11, min_length => 100, start => 'code');
printf "%d-%d %s %s...\n", @{ $_ }{qw(start end strand)}, substr $_->{protein}, 0, 10 for @{ $orfs };
table: the genetic code, as fortranslate.start: where a frame opens.any(the default) is at the codon after a stop, or at the sequence's first, so that every stretch between stops is a frame.ATGis at the firstATGafter that, andcodeat the first of the genetic code's own start codons, which for code 11 includeGTGandTTG; with either, the protein starts withM, whatever the codon codes for elsewhere, and a stretch with no start codon is no frame.min_length: the fewest amino acids a frame may have, 10 by default.strand:both(the default),+or-.
Each frame has start and end, its first and last base in $seq, counted from 1, with start the smaller on either strand and the stop codon left out; strand, 1 or -1; frame, as translate_six_frames numbers them; length, in amino acids; and protein. A frame that reaches the end of the sequence without a stop is returned as far as it goes.
This is what EMBOSS's getorf finds: start => 'any' is its -find 0, start => 'ATG' its -find 1 with its default table, and start => 'code' its -find 1 with -table; its -minsize is in nucleotides, three times min_length.
gc_content($seq, ambiguous => 'remove')
The share of $seq that is G or C, from 0 to 1, in either case; 0 for an empty sequence. S, which is G or C, counts as one.
gc_content('ACTGN'); # 0.5
gc_content('ACTGN', ambiguous => 'ignore'); # 0.4
ambiguous says what the other ambiguity letters count for: remove (the default) leaves them out, so that the share is of the letters A, C, G, T, U, S and W; ignore counts them in the length but not as G or C; and weighted counts each as the share of its bases that are G or C, half for N and two-thirds for B. This is Biopython's gc_fraction.
kmer_count($seq, $k, %args)
How many times each run of $k letters occurs in $seq, as a hash ref of k-mer => count. The letters are taken as they are: fold the case first if a and A should count together.
kmer_count('GATTACA', 3); # { GAT => 1, ATT => 1, TTA => 1, TAC => 1, ACA => 1 }
kmer_count('GATTACA', 3, overlap => 0); # { GAT => 1, TAC => 1 }
overlap: 1 (the default) counts the k-mer at every letter; 0 counts one every$kletters, from the first, so that none overlaps another.relative: 1 gives each k-mer's share of all that were counted, which sum to 1, in place of its count.
A $k longer than the sequence gives an empty hash. This is scikit-bio's kmer_frequencies.
assembly_stats($seqs)
The statistics of a set of sequences, such as the contigs of an assembly, that assembly-stats prints. $seqs is a hash ref of name => sequence, as fasta2hash returns, or an array ref of sequences.
my $s = assembly_stats(fasta2hash('contigs.fa'));
print "N50 $s->{n50} in $s->{l50} of $s->{number} contigs\n";
It returns a hash ref of number, how many sequences there are; total_length, mean_length, longest and shortest; n_count, how many letters are N or n, and gaps, how many runs of them there are; n50 and l50; and nx and lx, hash refs of those two for every tenth from 10 to 100. N50 is the length of the sequence at which the lengths, added from the longest down, first reach half of their total, and L50 is how many sequences that took; $s->{nx}{90} and $s->{lx}{90} are the same for 90%. With no sequences every number is 0.
molecular_weight($seq, %args)
The weight of a molecule of DNA, RNA or protein, in daltons.
molecular_weight('AGC'); # 949.6095
molecular_weight('AGC', type => 'RNA'); # 997.6077
molecular_weight('AGC', type => 'protein'); # 249.2874
type:DNA(the default),RNAorprotein, in any case.double_stranded: 1 adds the weight of the strand that pairs with$seq.circular: 1 for a molecule with no ends, which has one more bond.monoisotopic: 1 uses the weight of each element's commonest isotope, which is what a mass spectrometer resolves, rather than its average weight.
A nucleic acid is weighed with a 5' phosphate. Only the plain letters have a weight -- ACGT, ACGU, or the 20 amino acids with O (pyrrolysine) and U (selenocysteine) -- so any other letter dies, as does an empty sequence; whitespace is dropped and case ignored. The weights are Biopython's, and this is its molecular_weight.
isoelectric_point($protein), protein_charge($protein, $pH)
isoelectric_point is the pH at which a protein has no net charge, and protein_charge its charge at a pH you give.
isoelectric_point('INGAR'); # 9.75
protein_charge('INGAR', 7); # 0.76
The charge is that of the two ends of the chain and of every K, R, H, D, E, C and Y, each by the Henderson-Hasselbalch equation, with the pK values of Bjellqvist et al. (Electrophoresis 14:1023, 1993, and 15:529, 1994), which depend on the residue at each end; these are the values ExPASy's Compute pI/Mw uses, and the method is that of Biopython's IsoelectricPoint. The isoelectric point is found by bisection and is good to four decimal places. Other letters carry no charge, case is ignored, and an empty sequence dies.
subseq($seq, $start, $end)
The part of $seq from $start to $end, counting from 1 with both included; $end is the sequence's end when it is not given.
subseq('TTGGTGGCGTCAACT', 2, 5); # TGGT
A start of 0, a start after the end and an end past the sequence die, as they do in BioPerl's subseq. For a part of a sequence in a file, see fasta_region.
motif_search($seq, $motif, %args)
Where $motif occurs in $seq, as an array ref of hits in order of where they start, each a hash ref of start and end (counted from 1, both included), strand (1 or -1) and match, the letters that matched. Hits that overlap are all found.
my $hits = motif_search($seq, 'GRATYC', strand => 'both'); # EcoRI and BamHI sites
my $glyc = motif_search($protein, qr/N[^P][ST][^P]/, type => 'protein');
$motif is a string of IUPAC letters or a qr// pattern. In a string of nucleotide letters, each ambiguity letter matches any of its bases (R is A or G, N any of the four), T and U match each other, and case is ignored; in a protein's, B is D or N, Z is E or Q, J is I or L, and X is anything. A pattern is used as it is written.
type:DNA(the default),RNAorprotein.strand:+(the default),-orboth. The minus strand is searched as its own sequence, the reverse complement of$seq, so a hit there has the motif as itsmatch, while itsstartandendare still positions in$seq. A motif that is its own reverse complement is found on both strands at each site.
get_best_alignment_hit($json_file, $sort_criterion)
For a BLAST -outfmt 15 JSON report, a hash ref of query title => array ref of that query's hits, best first. Each hit is its best hsp plus accession, hit_len, id and title, and descriptions, an array ref of every description BLAST gave the hit. A hit against a non-redundant database such as nr has one for each accession of the same sequence; accession, id and title are those of the first, which is the one BLAST lists first. $sort_criterion is an hsp field (default evalue): align_len, bit_score, evalue, gaps, identity, positive or score. Ties are broken on the bit score, then on BLAST's order. A report with two queries of one title dies, since only one of them could be returned.
pdb_search(%args)
Searches the structures of the RCSB PDB for a sequence, and returns the matching ones, best first, each with how well it aligns and what kind of structure it is:
use Cn::Bioinf qw(pdb_search);
my $hits = pdb_search(seq => 'MVLSPADKTNVKAAWGKVGAHAGEYGAEALERMF...');
my $best = $hits->[0];
print "$best->{id}: $best->{pident}% identical over $best->{query_cover}% of the query, ",
"$best->{method} at $best->{resolution} A, $best->{oligomeric_state}\n";
# 1BZ1_1: 100% identical over 100% of the query, X-ray at 1.59 A, Hetero 4-mer
my ($hits, $total) = pdb_search(seq => $seq, max_hits => 10); # and how many RCSB found
It needs the network, and HTTPS, which HTTP::Tiny gets from IO::Socket::SSL and Net::SSLeay; without them it dies saying which is missing. It asks two of RCSB's APIs: the search API finds the polymer entities (one distinct chain of a structure) whose sequence matches, and the data API says what each one's structure is.
RCSB aligns with MMseqs2, not BLAST, so the numbers are MMseqs2's: its E-value and bit score are on BLAST's scale but are not what blastp would give for the same pair. They are returned under the names get_best_alignment_hit gives a BLAST hsp.
Arguments
seq(required): the sequence, as a string. Whitespace is removed, lower case is made upper case, and a final*(a stop) is dropped, so a sequence pasted from a FASTA file can be given as it is; any other character that is not a letter dies. RCSB itself refuses a sequence shorter than 10 residues.type:protein(the default),dnaorrna.evalue: hits with this E-value or above are left out. The default is 0.1, not BLAST's 10, which in a search of the whole PDB lets in hits expected 10 times over by chance.identity: hits with less identity than this percentage are left out (default 0).max_hits: the most hits returned (default 100). RCSB allows up to 10000.computed: 0 (the default) searches experimental structures only; 1 also searches the computed structure models RCSB holds, from AlphaFold DB and ModelArchive.report: 1 (the default) prints a table of the hits to STDOUT; 0 returns them only.timeout: seconds to wait for each request to RCSB (default 60).
What it returns
An array ref of hits, best first: by E-value, then bit score, then RCSB's own order, as get_best_alignment_hit sorts by evalue. Many hits tie: every structure of the query's own protein aligns the same way. In list context, the number of hits RCSB found is returned as well, which can be more than max_hits. Nothing matching is an empty array ref, not an error.
Each hit is a hash ref with every one of these keys, undef or an empty array ref where RCSB has no value:
What it is:
id: the polymer entity, as1BZ1_1: entry1BZ1, entity1.entry,entity: the two halves ofid. A computed model's entry is likeAF_AFP69905F1.url: the entry's page at RCSB.
How well it aligns:
evalue,bit_score: MMseqs2's.align_len: the length of the alignment, gaps included.identity: the number of aligned columns where the two agree, andpident, that as a percentage ofalign_len. These are counted from the aligned sequences, since RCSB gives the identity only truncated to 3 places.pidentisundefif RCSB gives analign_lenof 0 or none.mismatches,gaps(gap columns),gap_opens.query_from,query_to,query_lenandquery_cover, the percentage of the query in the alignment, which isundefif RCSB gives noquery_lenor one of 0.hit_from,hit_to,hit_len: the same for the hit's sequence.qseq,hseq: the aligned query and hit, with-for gaps.
What kind of structure it is:
title: the entry's title, anddescription, the entity's name.method: how the structure was determined:X-ray,EM,NMR,Neutron,Integrative,Multiple methodsorOther;undeffor a computed model.methodology:experimental,computationalorintegrative.resolution: in Å, for X-ray and EM structures.plddt: a computed model's mean pLDDT, 0 to 100.polymer_type:Protein,DNA,RNA,NA-hybridorOther.polymer_composition: the entry as a whole, such ashomomeric protein,heteromeric proteinorprotein/NA.oligomeric_state,stoichiometryandsymmetry: the global symmetry of the first biological assembly, such asHetero 4-mer,A2B2andC2.chains: an array ref of the chains that are this entity.organisms: an array ref of{ name, taxonomy_id }.uniprot: an array ref of UniProt accessions.pfam,interpro: array refs of{ id, name }.ligands: an array ref of{ id, name }, one for each kind of small molecule in the entry, such asHEM.deposited,released: dates, asYYYY-MM-DD.
A hit that the data API has no record of (one so new that RCSB's search index has it first) is warned of, and is returned with its alignment and no structure.
pgs_score(%args)
Computes a polygenic score for every sample of a VCF from a scoring file of the PGS Catalog: for each variant, the number of copies of the effect allele in the sample's genotype times effect_weight, summed over the variants. PLINK 2, which Alien::Bioinf installs, reads the genotypes and does the arithmetic (--score with no-mean-imputation), so the genotypes are never held in perl:
use Cn::Bioinf 'pgs_score';
my $scores = pgs_score(vcf => 'genome.vcf.gz', weights => 'PGS000138.txt.gz');
# { sample => { score => 1.6742, average => 6.97e-05, variants => 12015,
# alleles => 24030, missing => 10259, mismatched => 0 } }
Both arguments may also be data frames, as Stats::LikeR's read_table returns them, which this module takes without loading Stats::LikeR; a VCF given as a frame is written to a temporary VCF for PLINK 2. Files cost less memory, since a frame is all in perl: on 2026-10-17, PGS000907's 1,773,528 variants were scored from files against a 3.5-million-record genome in 25 s, with perl peaking at 0.8 GB.
vcf(required): a.vcf,.vcf.gz,.vcf.bgzor.bcffile, a PLINK 2 fileset given by its.pgen(with its.pvarand.psambeside it), or a data frame in any ofread_table's four shapes whose genotypes are columns named<sample>.GT, asread_tablegives a VCF by default; one read withexplode => 0has none, and dies. A frame needsCHROM,POS,REFandALT, andIDtoo withmatch => 'id'.weights(required): a scoring file (.txtor.txt.gz), read a line at a time, or a data frame of one. It needseffect_alleleandeffect_weight, and eitherchr_nameandchr_positionor, withmatch => 'id',rsID.other_alleleis used when present. A harmonized file of the PGS Catalog (..._hmPOS_GRCh38.txt.gz) is read byhm_chrandhm_pos(orhm_rsID) instead, which are on the build its name gives. A variant marked TRUE inis_haplotype,is_diplotype,is_interaction,is_dominantoris_recessive, or given adosage_0_weight,dosage_1_weightordosage_2_weight, dies, since only additive weights are scored.match:position(the default) finds each variant by chromosome and position;idfinds it by rsID, in a VCF whoseIDcolumn holds them. AnIDofrs1;rs2is found by either.build:hg19(orb37) orhg38(orb38). PLINK 2 reads X only once told where its pseudo-autosomal regions are, so a score with variants on X or Y dies without it. Every sample is taken to be of unknown sex, which PLINK 2 counts a haploid call on X of as homozygous: 2 copies, 2 alleles.memory,threads: the MiB of memory (640 or more) and the CPUs PLINK 2 may use. By default it reserves half the machine's memory and uses every CPU.
Returns a hash ref keyed by sample, a hash of hashes that write_table can write, with these fields for each sample:
score: the sum of the weights times the dosages, PLINK 2'sSCORE1_SUM. PLINK 2 writes it to six significant figures, so it is good to about one part in a million.average:scoredivided byalleles, PLINK 2'sSCORE1_AVG, or undef whenallelesis 0.variants: the variants ofweightsthat were scored for this sample.alleles: the alleles counted in their genotypes, PLINK 2'sALLELE_CT: 2 for each diploid call.missing: the variants that were not scored, because the VCF has no record of them whose alleles agree, or because the sample's genotype is missing (./., or partly missing, such as./1).variantsandmissingadd up to the number of rows ofweights.mismatched: ofmissing, those at a position (or ID) the VCF has, whose alleles disagree with the record's there.
PLINK 2 by default fills a missing genotype in with the effect allele's frequency in the samples; pgs_score leaves it out.
How a variant is matched, which perl decides, a .pvar line at a time, before PLINK 2 scores:
Chromosomes are compared without UCSC's
chrprefix and in any case, and PLINK's23,24and26and UCSC'sMare taken asX,YandMT, sochr1in a VCF finds1in a scoring file.A variant agrees with a record when its effect allele and its other allele (if it has one) are both among the record's
REFandALTalleles, in any case. A multi-allelic record counts the copies of whicheverALTis the effect allele, so a1/2genotype ofGtoA,Tholds oneT. Where two records agree, as a multi-allelic site split in two can, the first inCHROM:POS:REF:ALTorder is used.A record whose
ALTis., which a VCF of every site writes where the sample matches the reference, agrees with a variant either of whose alleles is itsREF; a0/0there is two copies of the effect allele if it is theREF, and none otherwise.Alleles are not complemented, since a VCF and the PGS Catalog's files are both on the forward strand. A variant written on the other strand disagrees, and A/T and C/G variants, which read the same on either strand, are matched as they are written.
Only
GTis read: a dosage (DS) or a genotype likelihood is not used.
The positions in the scoring file have to be on the same genome build as the VCF's, since a variant's position in GRCh37 (hg19) and in GRCh38 (hg38) differ; rsIDs do not, so match => 'id' needs no build. Many scoring files say genome_build=NR (not reported), so pgs_score cannot compare the builds. The alleles say what it cannot: it warns when none of the variants was found with alleles that agree, and when the alleles disagree at more than half of the variants found. On 2026-10-17, PGS000138, whose header says genome_build=NR, was scored against a GRCh37 genome: 12,015 of its 22,274 variants were found, and the alleles agreed at every one, so its positions are on GRCh37. With every position moved on one base, the alleles agreed at 9 of the 58 found.
A VCF that lists only the variants a sample carries (as most single-sample VCFs from a sequencing service do: every genotype holds an ALT) has no record where the sample matches the reference, so those variants are missing, not scored as zero copies. PLINK 2 refuses such a file; pgs_score warns that its score is not comparable and scores it anyway. That genome above was scored at 12,015 of PGS000138's 22,274 variants, and an exome at 701. A score is comparable only with another scored on the same variants, so check variants before comparing samples; a VCF called jointly over many samples, or one of every site, has far fewer missing. The reference blocks of a gVCF, which cover a range of positions with one record, are not expanded.
PLINK 2 converts the whole of a VCF or BCF before it keeps the score's positions, which for the 12 GB, 81-million-record BCF of 1000 Genomes took 294 s and 6.2 GB on 2026-10-17. Cut the positions out first with bcftools view -R (16 s), or convert such a reference once with plink2 --make-pgen and give pgs_score the .pgen: from a .pgen of those positions, all 2,504 people were scored in under a second.
The PGS Catalog's search pages export a table of scores with a link to each one's scoring file (depression.pgs_scores_data.csv, for one). That table has no weights, so pgs_score cannot use it, but it can say which files to download and score:
use Stats::LikeR 'read_table';
my $catalog = read_table('depression.pgs_scores_data.csv');
foreach my $pgs (@{ $catalog }) {
my ($file) = $pgs->{'Scoring File (FTP Link)'} =~ m{([^/]+)\z};
next unless -f $file;
my $s = pgs_score(vcf => 'genome.vcf.gz', weights => $file);
printf "%s\t%s\t%g\t%d variants\n", $pgs->{'Polygenic Score ID & Name'}, $_, @{ $s->{$_} }{qw(score variants)}
foreach sort keys %{ $s };
}
sex_check(%args)
Tells each sample of a VCF as male or female from its genotypes on X, by the method of peddy's sex_check (0.4.3): of the SNVs on X outside its pseudo-autosomal regions, the ratio of heterozygous calls to homozygous-ALT ones, which is near 0 for a male, whose one X can be heterozygous only by error, and above 1 for a female. The file is decompressed by perl and its lines counted in XS, which holds nothing but seven counters for each sample, so that a whole genome costs about what decompressing it does. It prints a report to STDOUT and returns the same results as a hash:
use Cn::Bioinf 'sex_check';
my $sex = sex_check(vcf => 'genome.vcf.gz');
my $same = sex_check('genome.vcf.gz'); # the file may come first, unnamed
prints
sex_check: genome.vcf.gz
male when het/hom-ALT, over SNVs on X outside its pseudo-autosomal regions, is below 0.6; genotypes of DP below 7 not counted
sample sex het/hom-ALT X het X hom-ALT X haploid X missing Y called
genome male 0.029 1990 68035 0 0 2746
with one row for each sample, in the VCF's order, and a last line counting the samples whose sex is unknown, if any. It returns
# { sample => { sex => 'male', het_ratio => 0.0292, x_het => 1990,
# x_hom_alt => 68035, x_hom_ref => 0, x_haploid => 0,
# x_missing => 0, y_called => 2746, y_alt => 2746 } }
On 2026-10-18 a 155 MB .vcf.gz of a whole genome (3.5 million records) took 4.8 s and 47 MB, where zcat alone takes 3.7 s; the same file as a .vcf.bz2 took 19.4 s, nearly all of it bzip2's.
vcf(required): a.vcf,.vcf.gz,.vcf.bgzor.vcf.bz2file, the suffix in any case. It may also be given first, without its name, assex_check($file)orsex_check($file, report => 0). A VCF may name its chromosomeschrX,Xor23(andchrY,Yor24); records on any other are skipped unread.cutoff: a sample whosehet_ratiois below this is male, and otherwise female. The default, 0.6, is peddy's. On five genomes the three males' ratios were 0.029 (a whole genome), 0.103 and 0.201 (exomes), and the two females' 1.660 and 1.712 (exomes); an exome's off-target calls make more false heterozygotes than a genome's.min_depth: a genotype whoseDPis below this is not counted. The default, 7, is peddy's; 0 counts every genotype. A genotype with noDP, or aDPof., is counted.report: 1 (the default) prints the report; 0 prints nothing, and only returns the results.
What is counted, and where sex_check differs from peddy:
X's pseudo-autosomal regions are taken as X:10000-2781479 and X:154931044-156030895, peddy's bounds, which cover GRCh37's and GRCh38's, so no build need be given. Y's are both builds' too.
Only biallelic SNVs are counted: a record whose
REForALTis not a single base (an indel, a multi-allelic site, or anALTof.,*or<NON_REF>) is skipped, where peddy keeps an insertion. A record with noGTin itsFORMATis skipped too.Every site is counted, where peddy stops at 10,000, and peddy's filters on a site's call rate and ALT frequency across the cohort, which mean nothing for one genome, are left out.
A haploid call, as a caller that knows a sample is male writes it on X, counts as homozygous:
1as hom-ALT,0as hom-REF.A sample with no het or hom-ALT call on X has
sexandhet_ratioundef. peddy divides by a hom-ALT count of 0 as if it were 1, and so would call such a sample male. When the whole VCF has no SNV on X outside the pseudo-autosomal regions,sex_checkalso warns.
Returns a hash ref keyed by sample, a hash of hashes that write_table can write, with these fields for each sample:
sex:male,female, or undef.het_ratio:x_hetdivided byx_hom_alt(by 1 whenx_hom_altis 0), or undef when both are 0.x_het,x_hom_alt,x_hom_ref: the sample's heterozygous, homozygous-ALT and homozygous-REF calls at the SNVs counted on X. A VCF that lists only the sites where its sample carries an ALT allele has no hom-REF calls.x_haploid: of those, the haploid calls.x_missing: the sample's calls there that were missing (./.,., partly missing, such as./1, or cut short, such as1/), or not a call of one or two alleles of the record's two. A genotype left out bymin_depthis in no count.y_called,y_alt: the sample's calls at SNVs on Y outside its pseudo-autosomal regions, and those of them that carry theALT. They decide nothing: an exome of a woman had 530 called SNVs on Y, and one of a man 659, since a short read from X often maps to Y. They show at most whether Y was called at all.
A BCF or a .pgen is not read; convert it with bcftools view -Oz.
parent(%args)
Tells whether two people are parent and child from their genotypes, and returns 1 if they are and 0 if not. A child has one allele from each parent at every site, so wherever a parent is homozygous the child carries that allele, and the two are never opposite homozygotes (one hom-REF and the other hom-ALT, which is called IBS0) except by a genotyping error. Genotypes cannot tell which of the two is the parent, so child and parent may be given either way round, with the same result. Paternity and maternity are this together with the parent's sex, which sex_check tells.
Over the autosomal biallelic SNVs where either of the two carries the ALT, a pair is parent and child when the IBS0 rate (the share of those sites that are IBS0) is below max_ibs0, and the KING-robust kinship coefficient is from 0.177 to 0.354, KING's range for first-degree relatives. Full siblings have that kinship too, but they share no allele by descent at a quarter of sites, so they have opposite homozygotes there, and the IBS0 rate tells them apart. One person sequenced twice, or identical twins, have a kinship above 0.354, and are not parent and child.
The file is decompressed by perl and counted in XS, as for sex_check. The two people are either two samples of one VCF, or each the one sample of a VCF of their own, as a sequencing company delivers it:
use Cn::Bioinf 'parent';
my $is = parent(child => 'child.vcf.gz', parent => 'father.vcf.gz');
my ($same, $stats) = parent(vcf => 'family.vcf.gz', child => 'C', parent => 'F');
The first prints
parent: child child.vcf.gz, parent father.vcf.gz
parent and child (1): the IBS0 rate, 0.0030, is below 0.012, and kinship 0.2587 is from 0.177 to 0.354, as for first-degree relatives
sites compared 150970 autosomal biallelic SNVs where either carries the ALT, DP 10 or more
in both VCFs 98828
in the child's alone 27645 the parent taken as hom-REF
in the parent's alone 24497 the child taken as hom-REF
IBS0 458 opposite homozygotes
child hom-ALT 305 and the parent hom-REF
child hom-REF 153 and the parent hom-ALT
IBS1 76262 one allele shared
IBS2 74250 both alleles shared
het in both 43727
het 82821 the child's, and 80895 the parent's
hom-ALT 43652 the child's, and 42430 the parent's
kinship 0.2587 KING-robust, between-family
and returns 1. On 2026-10-18 the exomes of one family, all three sequenced and called together, gave:
child, parent sites compared IBS0 rate kinship returned
child, father 150,970 0.0030 0.2587 1
child, mother 158,616 0.0020 0.2604 1
father, mother 171,033 0.0810 0.0174 0
Each pair took 1.6 s. A genome against an exome took 7.3 s and 89 MB, and is not to be trusted, for the reason under "Each sample's own VCF" below.
child,parent(required): withoutvcf, the two VCF files, each of one sample (.vcf,.vcf.gz,.vcf.bgzor.vcf.bz2, as forsex_check); withvcf, the names of two of its samples.vcf: a VCF that holds both samples.min_depth: a genotype whoseDPis below this is not counted. The default is 10; 0 counts every genotype. A genotype with noDP, or aDPof., is counted. On the family above, counting every genotype gave the parent and child pairs IBS0 rates of 0.254 and 0.215, as high as an unrelated pair's, from calls ofDP1 to 3 made off the exome's targets. Amin_depthof 7 gave 0.0053 and 0.0037, and 10 gave 0.0030 and 0.0020, keeping 92% of the sites of 7.max_ibs0: the IBS0 rate a parent and child must be below. The default, 0.012, is peddy 0.4.3's (ped_check). It lies between the parent and child rates above (0.002 to 0.005) and the 0.02 or so expected of full siblings, a quarter of the unrelated pair's 0.081.report: 1 (the default) prints the report to STDOUT; 0 prints nothing.
What is counted:
Only the autosomes, named
1to22orchr1tochr22; X is left out, since a father gives his X to a daughter and not to a son.Only biallelic SNVs: a record whose
REForALTis not a single base, or that has noGT, is skipped.A call counts when it is diploid and of the record's
REFandALT, and is not belowmin_depth. A missing or partly missing call (./.,./1), a haploid one, or one with an allele the site lacks leaves that site out. So do sites where both are hom-REF, which say nothing about relatedness; a cohort's VCF has a great many of them.
Each sample's own VCF lists only the sites where its sample carries an ALT allele, so a site that one file lacks is taken as hom-REF in that person, and the two files are compared site by site, holding both in memory (8 bytes a site, so about 30 MB for a genome). A position is left out when either file has more than one SNV there (as after bcftools norm -m-), a call that does not count, or a record of more than one ALT, or when the two files give it different REF or ALT alleles. The files may name and order their chromosomes differently.
Taking a missing site as hom-REF is right only when the other file was sequenced and called there too, so two VCFs from one pipeline are what this compares well. A genome's VCF has millions of sites that an exome's lacks, and two exome capture kits target different regions; either makes IBS0 out of sites that one of the two never had sequenced. The report gives the sites in each file alone for that reason, and parent warns when one file has more than twice as many as the other: the three pairs of the family above had ratios of 1.13 at most, an exome of another kit had 3.0 to 13 against them, and a genome against an exome 58 (with a kinship of -19.8). The difference must also be 50 sites or more, which chance does not give (a ratio over 2 with a difference of 50 has a chance of 4.8e-5 at most, were a site as likely to be in either file alone), and 0.9% or more of the sites compared, since fewer could not carry the parent and child above over max_ibs0 even if every one were an opposite homozygote; so two VCFs that list every site and differ by 3 sites against 1 are not warned of. A VCF that leaves out filtered calls has holes that look hom-REF too.
parent dies, rather than return a 0 or 1 that it has no grounds for, when
fewer than 1,000 sites are compared, which at the unrelated pair's IBS0 rate would hold 81 opposite homozygotes on average, 8 standard deviations above the 12 that
max_ibs0allows (an exome gives about 150,000 and a genome 3 million);neither has a hom-REF call where the other carries the ALT, so that IBS0 cannot be seen. A VCF merged from VCFs that list only their own sample's variants, as
bcftools mergewrites it without-0, is like that, with./.wherever a sample had no variant; give each sample's own VCF instead;either has no het call at the sites compared, so that no kinship can be taken.
In scalar context parent returns 1 or 0. In list context it returns that and a hash ref of what it was decided from, with the same fields on every return:
parent: 1 or 0, as returned.relationship:parent-child,full siblings,duplicate(one person or identical twins),second-degree,third-degreeorunrelated, by KING's kinship ranges, with the IBS0 rate telling parent and child from full siblings.kinship: the KING-robust between-family estimate (Manichaikul et al. 2010, Bioinformatics 26:2867), which is what PLINK 2's--make-king-tablegives, and which agreed with it exactly on the VCF of two of the exomes above merged bybcftools merge -0.ibs0_rate:ibs0divided bysites.sites: the sites compared, and of themin_both,child_onlyandparent_only: those in both own VCFs, in the child's alone and in the parent's alone. Withvcf, every site isin_both.ibs0,ibs1,ibs2: the sites where the two share no allele, one, or both; andibs0split intochild_alt_parent_refandchild_ref_parent_alt.het_het: the sites where both are het;child_het,parent_het,child_hom_altandparent_hom_alt: each one's het and hom-ALT calls at the sites compared.
A BCF is not read; convert it with bcftools view -Oz.
relatedness(@vcf, %args)
Tells how every two people are related, from their genotypes: each pair's KING-robust kinship and its IBS0, IBS1 and IBS2 counts, as parent takes them for one pair, and from those a relationship (parent and child, full siblings, one person twice, second- or third-degree relatives, or unrelated). Each person's sex is told from X in the same reading, as sex_check tells it, so that the relationship can be named: father-son, mother-daughter, brother-sister, brothers, sisters, and so on. Genotypes alone cannot tell which of a parent and child is the parent, but a third person often can, and relatedness says which when one does.
The people are either every sample of one VCF, or the one sample of each of several VCFs, as a sequencing company delivers them:
use Cn::Bioinf 'relatedness';
my $family = relatedness('family.vcf.gz'); # every pair of its samples
my $same = relatedness('mom.vcf.gz', 'dad.vcf.gz', 'kid.vcf.gz', report => 0);
my ($pairs, $samples) = relatedness(vcf => ['mom.vcf.gz', 'dad.vcf.gz']);
print $family->{js}{dc}{category}; # father-son
print $family->{dc}{js}{category}; # the same hash, so the same
The second prints
relatedness: mom.vcf.gz, dad.vcf.gz, kid.vcf.gz
KING-robust kinship over autosomal biallelic SNVs where either carries the ALT, genotypes of DP below 10 not counted; first-degree from 0.177 to 0.354, and of those, parent and child when the IBS0 rate is below 0.012; male when het/hom-ALT on X outside its pseudo-autosomal regions is below 0.6
sample sex X het/hom-ALT VCF
mom female 1.690 mom.vcf.gz
dad male 0.206 dad.vcf.gz
kid female 1.698 kid.vcf.gz
sample sample sites IBS0 rate kinship relationship
mom dad 171033 0.0810 0.0174 unrelated
mom kid 158616 0.0020 0.2604 mother-daughter (mom the parent)
dad kid 150970 0.0030 0.2587 father-daughter (dad the parent)
for the exomes of the family under parent, and returns the same. Every pair's counts are those parent gives for it.
The VCFs are decompressed by perl and counted in XS. One VCF of several samples is read a record at a time, keeping nothing but each pair's counters, and each pair's counts are taken 64 sites at a time from bit masks of the samples' genotypes; several VCFs of one sample each are held in memory, 8 bytes a site, as parent holds two, and opened one at a time. On 2026-10-19 the three exomes above took 2.5 s and 30 MB, where parent takes 1.6 s for one pair of them. The 17 samples of the CEPH 1463 pedigree (peddy's ceph1463.peddy.vcf.gz, 20,000 sites) took 0.27 s. A made-up VCF of 1,000 samples and 20,000 sites took 5.3 s and 890 MB: the counting took 1.7 s and 96 MB, and nearly all the rest is the 499,500 hashes returned.
The VCFs are given first, as
relatedness($file)orrelatedness($file, $file2, ...), before any option, or asvcf. Each is a.vcf,.vcf.gz,.vcf.bgzor.vcf.bz2file, as forsex_check. One VCF must have two samples or more; each of several must have one, and no two the same sample name, which is what each sample is known by.vcf: a VCF, or an array ref of them, in place of giving them first.min_depth: a genotype whoseDPis below this is not counted, on X as on the autosomes. The default, 10, isparent's, forparent's reasons; 0 counts every genotype.max_ibs0: the IBS0 rate that a parent and child must be below, which tells them from full siblings. The default, 0.012, isparent's.report: 1 (the default) prints the report to STDOUT; 0 prints nothing.
What is counted is what parent counts, for every pair: the autosomal biallelic SNVs where either of the two carries the ALT, a site that one own VCF lacks taken as hom-REF in that person, and a site left out of a pair for the reasons given under parent. Each person's sex is from SNVs on X outside its pseudo-autosomal regions, as sex_check tells it with its default cutoff (0.6), but with min_depth as given here.
A pair's relationship is decided as parent decides it: by KING's kinship ranges, with the IBS0 rate telling parent and child from full siblings. Its category names it from the two sexes:
A parent and child is
father-son,father-daughter,mother-sonormother-daughterwhen it is known which is the parent and both sexes are known, withparentorchildin place of a word whose sex is unknown (parent-son). When it is not known which is the parent, two men arefather-sonand two womenmother-daughterall the same, and a man and a woman areparent-child.Full siblings are
brothers,sistersorbrother-sister, orfull siblingswhen either's sex is unknown.Any other relationship is its own category:
duplicate,second-degree,third-degreeorunrelated.
Which of a parent and child is the parent is told by a third person: x is y's parent when x has another child who is y's full sibling, or when y has another parent who is unrelated to x (the two being y's parents). When neither is said, or both, as in a pedigree that this reading cannot untangle, parent is undef. On CEPH 1463, three generations of 17 people, relatedness agreed with the pedigree on all 17 sexes and on 134 of the 136 pairs, including every father, mother, son, daughter, brother and sister, and which of each parent and child was the parent. The other two pairs were the grandson NA12893 with his grandfather and with his grandmother, whose kinships of 0.0839 and 0.0799 are just under KING's 0.0884 for second-degree relatives, and so are third-degree.
Where parent would die, relatedness decides nothing about that pair and goes on to the next: its relationship and category are undef and undecided says why, and relatedness warns once, counting such pairs. That is when fewer than 1,000 sites are compared, when neither has a hom-REF call where the other carries the ALT (as in a VCF merged without -0), or when one has no het call, which leaves kinship undef too. When several VCFs are given, relatedness also warns once about the pairs whose VCFs look sequenced over different regions, as parent warns about one.
In scalar context relatedness returns a hash of hashes keyed by each sample and then by each other sample, so that $r->{js}{dc} and $r->{dc}{js} are the same pair, and the same hash: changing one changes the other. In list context it returns that and a hash ref of the samples. A pair's hash has these fields on every return:
relationship: asparentgives it (parent-child,full siblings,duplicate,second-degree,third-degreeorunrelated), or undef when the pair is undecided.category: the relationship named by sex, as above, or undef.parent: the name of the one that is the parent, for a parent and child where a third person says which; otherwise undef.undecided: why the pair is undecided, or undef.kinship: the KING-robust between-family estimate, or undef when either has no het call. Ont/data/parent.vcfit agreed with PLINK 2's--make-king-tablefor all 21 pairs.ibs0_rate:ibs0divided bysites, or undef when there are no sites.sites: the sites compared, of whichin_bothwere in both VCFs, andonly, a hash of each of the two samples, those in that sample's VCF alone. With one VCF, every site isin_both.ibs0,ibs1,ibs2: the sites where the two share no allele, one, or both;het_het: those where both are het;het, a hash of each of the two samples: its het calls at the sites compared.
parent's split of ibs0, and each one's hom-ALT count, are left out, since each hash of two numbers adds a third to a pair's memory; parent gives them for any one pair.
The samples' hash has, for each sample, what sex_check returns for it (sex, het_ratio, x_het, x_hom_alt and the rest), and file, its VCF.
A BCF is not read; convert it with bcftools view -Oz.
concordance(%args)
Compares the genotype calls of a VCF under test with those of a truth VCF, sample by sample, and counts each kind of agreement and disagreement, as x.low_ram_local_concordance.pl did:
use Cn::Bioinf 'concordance';
my $r = concordance(truth => 'truth.vcf.gz', test => 'test.vcf.gz');
print $r->{NA12878}{metrics}{genotype_concordance};
foreach my $site (@{ $r->{NA12878}{discordances} }) {
print "$site->{chrom}:$site->{pos} $site->{type}: test $site->{test}, truth $site->{truth}\n";
}
This is based off of https://link.springer.com/article/10.1186/s12920-022-01199-8
Each of the test's samples is compared with the truth's sample of the same name, and a sample in only one of the files is left out. When each file has exactly one sample, the two are compared whatever they are called, so a run named run42 can be compared with its truth NA12878. When no sample can be paired, concordance dies and names some of each file's samples.
Every record of the test is compared with the truth's record of the same CHROM, POS, REF and ALT. A chr prefix on CHROM, in any case, is ignored, and so is ID. When the truth has no such record, its call there is a no-call. A site that the truth has and the test lacks is not compared at all, so the test's sites are the ones measured, as for a genotyping panel against a genome. A site whose ALTs are listed in another order, or split over two records, is a different site.
The two files have to be on the same genome build, since a site's POS in GRCh37 (hg19) is not the same place in GRCh38 (hg38). Before either file is read, concordance compares the lengths that their headers' ##contig lines give, matching contigs by name without chr, as sites are matched. It dies if any contig that both give a length for has different lengths, and names the contigs and the build each header gives (its assembly, or else its ##reference). hg19 and b37, whose chromosomes are the same lengths, pass. A header with no ##contig lengths cannot be checked this way. When none of the test's sites is in the truth, concordance warns that the builds may differ.
On t/data/concordance.test.vcf against t/data/concordance.truth.vcf it prints
concordance: test concordance.test.vcf against truth concordance.truth.vcf
each test site compared with the truth's of the same CHROM, POS, REF and ALT, a site the truth lacks being a no-call there; precision, recall and specificity are of genotypes
sample sites in truth concordant discordant gained lost concordance precision recall specificity
B 46 45 34 10 2 0 0.7674 0.9412 0.8889 0.9375
A 46 45 11 32 2 1 0.2381 0.4286 0.4286 0.1111
1 of the test's 3 samples are not in the truth: D
When the paired samples' names differ, a truth sample column follows sample.
The VCFs are decompressed by perl and compared in XS. The test is read first, and its sites are kept with their calls for the samples compared, about 100 bytes a site for one sample. Then the truth is read a record at a time and looked up among them, so memory grows with the test, which is usually the smaller file. On 2026-10-19, one exome compared against another (274,879 test sites) took 1.9 s and 211 MB, or 1.7 s and 47 MB with discordances => 0, because most of that memory is the 163,376 discordant and gained sites returned. A genome compared with itself (3.5 million sites) took 14 s and 362 MB, most of the time being gzip.
truth,test: the two VCFs, each a.vcf,.vcf.gz,.vcf.bgzor.vcf.bz2file, as forsex_check.min_depth: a genotype whoseDPis below this is a no-call, in either file. The default, 0, compares every genotype, as the script did. ADPthat is absent or.leaves the genotype compared.discordances: 1 (the default) lists each discordant, gained and lost site indiscordances; 0 only counts them, and leavesdiscordancesundef.report: 1 (the default) prints the report to STDOUT; 0 prints nothing.
A call is compared by its alleles, in either order and phased or not, so 1/0, 0|1 and 0/1 are the same call. Each call is one of hom-REF (0/0), het-REF (0/1), hom-ALT (1/1, 2/2), het-ALT (1/2), haploid-REF (0), haploid-ALT (1), or a no-call. A missing call (. or ./.), a partly missing one (./1), one of more than two alleles, and one where FORMAT has no GT are all no-calls. Each comparison, truth first, is one of 45 kinds, the script's:
concordant_and the class, when the two calls are the same:concordant_hom_ref,concordant_het_ref,concordant_hom_alt,concordant_het_alt,concordant_haploid_ref,concordant_haploid_altandconcordant_no_call.concordant_diploid_ref_to_haploid_refandconcordant_haploid_ref_to_diploid_ref, for0/0against0and0against0/0;concordant_hom_alt_to_diploid_altandconcordant_haploid_alt_to_hom_alt, for1/1against1and1against1/1.lost_site, when the truth has a call and the test a no-call, andgained_site, when the test has a call and the truth a no-call.discordant_and the two classes otherwise, as indiscordant_het_ref_to_hom_alt(0/1in the truth,1/1in the test). Two different calls of the same class are discordant too, as indiscordant_het_ref_to_het_ref(0/1against0/2).
concordance returns a hash keyed by the test's name for each sample compared. Each sample's hash has these fields on every return:
test_sample,truth_sample: the sample's name in each file.sites: the test's records, every one compared;in_truth: how many of them the truth has.counts: a hash of the 45 kinds, each with its count, 0 included.metrics: a hash of the script's metrics, taken fromcounts:tp_site: the matched calls that carry an ALT:concordant_het_ref,concordant_het_alt,concordant_hom_alt,concordant_haploid_alt,concordant_hom_alt_to_diploid_altandconcordant_haploid_alt_to_hom_alt.tp_genotypeis the same number.fp_site:gained_site;fn_site:lost_site.tn_site: the matched reference calls:concordant_hom_ref,concordant_haploid_ref,concordant_diploid_ref_to_haploid_refandconcordant_haploid_ref_to_diploid_ref.tn_genotypeis the same number.fp_genotype: the discordances where the test's call carries an ALT, whether the truth's is a reference call or another ALT-carrying call;fn_genotype: those where the truth's call carries an ALT, whether the test's is a reference call or another ALT-carrying call. A discordance of two ALT-carrying calls, such as0/1against1/1, is thus counted in both, since the test's call is wrong and the truth's is missed.genotype_concordance: the concordant comparisons, lessconcordant_no_call, over every comparison butconcordant_no_call,gained_siteandlost_site.precision_site:tp_site / (tp_site + fp_site);recall_site:tp_site / (tp_site + fn_site);precision_genotype:tp_genotype / (tp_genotype + fp_genotype);recall_genotype:tp_genotype / (tp_genotype + fn_genotype);specificity_genotype:tn_genotypeovertn_genotypeand those offp_genotypewhere the truth is a reference call, since only those truths are negatives. Each ratio is undef when its denominator is 0, where the script gave the stringundefined.
discordances: an array ref of the discordant, gained and lost sites, in the test's order, each a hash ofchrom,pos,id,refandaltas the test has them,type(the kind), andtestandtruth, the two calls as GT writes them, or.for a no-call; or undef withdiscordances => 0.
Four of the metrics are corrected from the script's. Its tp_site pattern, /^conc\w+(?:alt|hom)/, matched the hom in concordant_hom_ref, so a hom-REF site was a true positive as well as a true negative, and it missed concordant_het_ref, the commonest true positive. Its tn_site missed concordant_diploid_ref_to_haploid_ref, though it took the reverse. And its tn_genotype was concordant_hom_ref alone, though its false positives counted a haploid-REF truth called wrong, so specificity_genotype gave no credit for one called right, as on a male's X. And it counted a discordance of two ALT-carrying calls in neither fp_genotype nor fn_genotype, so that a wrong genotype at a variant site changed neither precision_genotype nor recall_genotype.
concordance departs from the script where the script failed. The script took ID as part of a site, and dropped chr from the truth's CHROM alone, so two files that both had it shared no site. It compared GT strings, and so died on 1/0, 0|1, ./1 and calls of three alleles. And it made a no-call against . discordant_no_call_to_no_call, outside its own 45 kinds. Its XLSX workbook, JSON files and ACMG59 column are left to the caller, who has everything they were made from.
concordance warns when the test has no records, and when none of the test's sites is in the truth, which usually means two genome builds, or two naming schemes for the chromosomes other than chr.
A BCF is not read; convert it with bcftools view -Oz.
blood_type(%args)
Tells each sample's ABO blood group and whether it is RhD positive or negative from a VCF, with the genotype behind each:
use Cn::Bioinf 'blood_type';
my $b = blood_type(vcf => 'exome.vcf.gz');
print $b->{NA12878}{type}; # A+
print $b->{NA12878}{abo}{genotype}; # AO
print $b->{NA12878}{rhesus}{phenotype}; # positive
and prints
blood_type: exome.vcf.gz
ABO from rs8176719 (O's deletion), rs8176746 (B) and rs41302905 (O2); RhD from 15 sites of RHD, or a record of the gene's deletion; matched by position on b37; genotypes of DP below 7 not counted
sample type ABO ABO genotype RhD RhD genotype RHD sites
NA12878 A+ A AO positive D. 2/15
"RHD sites" is how many of the sites the sample has an ALT allele at; one is enough for RhD positive
not in the file, and taken as homozygous for the reference allele: rs8176746, rs41302905, 13 of the 15 RHD sites
with one row for each sample, in the VCF's order.
This is not a blood test, and must not be used to choose blood for a transfusion or for any other clinical purpose. It reads the common alleles and nothing else: a weak or partial D, an RHD gene that is present but does not work (the RHD pseudogene, common in people of African ancestry, makes somebody RhD negative whom this calls positive), a hybrid of RHD and RHCE, the A2 and other subgroups, cis-AB and the rare O alleles are all outside it.
An exome's 22 MB .vcf.gz took 0.8 s and 20 MB, and a whole genome's 155 MB 6.1 s and 47 MB (perl 5.44.0, 2026-11-10). The markers are in share/blood_type_panel.tsv, which share/make_blood_type_panel.pl writes; its header comment says where each comes from, and the module never runs it.
ABO
Three markers are read. rs8176719 is the single-base deletion that makes the common O alleles; the reference genome carries the deletion, on GRCh37 and on GRCh38, so a VCF writes a working gene there as an insertion, and a chromosome with that insertion is A or B. rs8176746 is one of the changes that make the B enzyme, and rs41302905 is the O2 allele, an O with no deletion, which would otherwise be read as A. So a chromosome without the insertion is O, whatever else it carries; one with it is B with rs8176746's T, O with rs41302905's T, and otherwise A. The genotype is the two letters, A before B before O (AO, BO, AB, OO), and the phenotype is what they make: A, B, AB or O.
The genotypes are not phased, so somebody heterozygous at both rs8176719 and rs8176746 is read as BO, the B allele being taken to be on the chromosome with the working gene. Of the 5,008 haplotypes of 1000 Genomes' phase 3, 721 carried both and 44 the B allele without the insertion, which makes that reading right 98.1% of the time.
Checked against 1000 Genomes on 2026-11-10: the ABO genotype read from phase 3's calls on GRCh37 and the one read from the New York Genome Center's 30x resequencing of the same people, called afresh on GRCh38, were the same for all 2,504 of them.
RhD
Most people who are RhD negative have no RHD gene on either chromosome, and a VCF of SNVs has no record for a gene that is not there. blood_type reads it in one of two ways.
Where the file has a record of a deletion that covers the whole gene, as 1000 Genomes' phase 3 does (1:25592642 <CN0>, END=25661222), the sample's genotype there is the answer: DD, Dd or dd. A deletion is an ALT of <CN0>, <DEL> or <DEL:...>, and has to start at or before the gene and end, by END or SVLEN, at or after it.
Otherwise it reads 15 sites inside the gene at which the reference genome carries a rare allele, so that almost everybody who has the gene has an ALT call there, and nobody without it has. One such call makes a sample RhD positive, written D., since SNVs cannot say whether the second chromosome has the gene too: the ratio of heterozygous to homozygous-ALT calls inside the gene, which tells sex on X, got a tenth to a quarter of 2,343 people wrong at any cutoff. No such call makes a sample dd, RhD negative.
The sites were chosen, and counted, in 1000 Genomes: the 30x calls of the 2,493 people whose deletion genotype phase 3 gives. Of the 150 with no gene, none had a call at any of the 15; of the 2,343 with one or two, 5 had a call at none, and so are called negative, and 2 at only one. Choosing the sites on a random half of the people and counting on the other half chose the same 15 and gave the same counts.
An exome sees little of this: the capture kit of the three exomes tried reached 2 of the 15 sites, at a depth of 13. The types of those three are known from the depth of their reads: two cover RHD's exons at a mean depth of 3 and 2 against 90 and 97 over RHCE's, and the third at 30 against 84; blood_type called them negative, negative and positive. A kit that reaches none of the 15 sites would call everybody negative, and carried and listed, below, are returned so that an answer from few sites can be seen for what it is.
A marker the file has no record of
A VCF of one person usually lists only the sites where that person carries an ALT allele, so that somebody who is OO, or has no B allele, or has no RHD gene, simply has no record at those markers. By default a marker with no record is therefore read as homozygous for the reference allele, and each answer says which markers that was done for. Two things are not read that way, because the file could not have held the record:
a marker on a chromosome the file has no record on at all;
rs8176719, an insertion, in a file with no allele longer than one base on chromosome 9. Such a file holds SNVs only, and reading the insertion's absence as REF would call everybody O; no ABO type is given, andwhysays so.
A file of every site, a cohort's, or a genotyping array's does have a record where a sample is homozygous REF, and assume_ref => 0 makes a marker with no record a marker with no genotype.
Arguments
vcf(required): a.vcf,.vcf.gz,.vcf.bgzor.vcf.bz2file. Assex_checkdoes, it may be given first and on its own:blood_type('genome.vcf.gz').assume_ref: 1 (the default) reads a marker the file has no record of as homozygous for the reference allele, as above; 0 leaves it without a genotype.build:hg19,b37,hg38orb38, saying which of the panel's two sets of coordinates to match on. By default it is read from the VCF's##contiglengths, ashirisplex_genotypesreads it, andblood_typedies asking for it when the header gives no length it knows.min_depth: a genotype whose FORMATDPis below this is not counted. Defaults to 7, which issex_check's and the depth the RhD sites were chosen at; 0 counts every call whatever its depth. A genotype with noDPis always counted.report: 1 (the default) prints the table to STDOUT; 0 returns the answers only.
What it returns
A hash ref keyed by sample name, each holding:
type: the two together, asA+orO-, orundefwhen either is not known.abo: a hash ref ofgenotypeandphenotype: as above, orundef;markers: a hash ref of rs number => 0, 1 or 2 copies of the allele counted, orundefwhere the sample has no genotype;assumed_ref: an array ref of the markers the file has no record of that were read as homozygous REF;why:undef, or why no type could be given.
rhesus: a hash ref ofgenotype:DD,Ddorddfrom a record of the deletion;D.orddfrom the sites; orundef;phenotype:positive,negativeorundef;basis:deletionorsites, saying which of the two it was read from, orundef;sites,listedandcarried: how many RhD sites the panel has, how many of them the file has a record of, and at how many this sample has an ALT allele;deleted: the copies of the deletion the sample has, 0 to 2, orundefwhen the file has no record of it that calls the sample;why:undef, or why no type could be given.
A genotype is counted only when the call is diploid and complete, as hirisplex_genotypes counts one. blood_type warns when the file has no record on chromosome 1 or on chromosome 9, which usually means the wrong build.
hirisplex_genotypes(%args)
Reads the 41 markers of the HIrisPlex-S eye, hair and skin colour panel out of a VCF, counting for each sample how many copies of each marker's model allele it carries, and can write them as the CSV the HIrisPlex-S webtool uploads:
use Cn::Bioinf 'hirisplex_genotypes';
my $g = hirisplex_genotypes(vcf => 'genome.vcf.gz', file => 'hirisplexs.csv');
print $g->{NA12878}{genotype}{'rs12913832_T'}; # 0, 1, 2, or undef
print scalar @{ $g->{NA12878}{missing} }, " markers missing\n";
This distribution ships no prediction model, and hirisplex_genotypes makes no prediction. The HIrisPlex-S regression coefficients are not published: Chaitanya et al. (2018) cite them by reference rather than tabulating them, the webtool offers no download and says that no part of it may be reproduced without consent, and part of the knowledge behind it is covered by European patent EP2195448. What is public, and what this function uses, is the panel itself -- which markers, in which order, and which allele each model counts -- taken from the webtool's own input form. So hirisplex_genotypes prepares the input, and the prediction is made either at the webtool or by trait_predict from a model table you hold yourself.
The panel
share/hirisplex_s_panel.tsv holds the panel: each marker's rs number, gene, the allele the model counts, its positions on GRCh37 and GRCh38, and whether it belongs to the 6-marker IrisPlex and 24-marker HIrisPlex subsets. share/make_hirisplex_panel.pl writes that file from the webtool's form and Ensembl, and its header comment says how to re-run it; the committed file is what is used, and the generator is never run by the module.
The webtool asks for a count of the allele on the assay's strand, which is not always the strand a VCF is written on, and the panel records the forward-strand allele to count for each marker so that nothing has to be guessed at run time. Fourteen of the 41 are counted as the complement of the allele the webtool names. One, ASIP rs6119471, carries the named allele on the forward strand and still has to be flipped -- the HIrisPlex-S manual singles it out as "the only SNP that may cause confusion and therefore must be converted (from NCBI's forward orientation)" -- so a tool that simply matched the named allele would silently count the wrong one. MC1R rs312262906 is not a SNP but the 86insA frameshift, merged in dbSNP into rs796296176; it is counted as the ALT that is REF with one A put in (A to AA, or AA to AAA as GRCh38 writes it), so that an MNV or a symbolic <INS> at that position is not taken for it, and matching by rs number looks for both numbers. Bases are compared regardless of case.
Arguments
vcf(required): a.vcf,.vcf.gz,.vcf.bgzor.vcf.bz2file. Assex_checkdoes, it may be given first and on its own:hirisplex_genotypes('genome.vcf.gz').match:position(the default) matches CHROM and POS against the panel's coordinates;idmatches the ID column against the markers' rs numbers, which finds nothing in a VCF whose ID column is.. An ID of several names, separated by semicolons as the VCF specification has them, matches when any of them is a marker's.build:hg19,b37,hg38orb38, saying which of the panel's two sets of coordinates to match on. By default it is read from the VCF's##contiglengths, andhirisplex_genotypesdies asking for it when the header gives no length it knows, or lengths that are neither build's.min_depth: a genotype whose FORMATDPis below this is not counted. Defaults to 7,sex_check's default; 0 counts every call whatever its depth. A genotype with noDPis always counted.file: write the webtool's CSV here. Its header is that of the webtool's own template, column for column, and a marker with no genotype is writtenNA.report: 1 (the default) prints a table of the samples to STDOUT; 0 returns them only.
What it returns
A hash ref keyed by sample name, each holding:
genotype: a hash ref keyed as the webtool's CSV heads its columns,<rs number>_<input allele>, holding 0, 1 or 2 copies of that allele, orundefwhere the sample has no usable call.missing: an array ref of the rs numbers with no genotype, in the panel's order.markersandcalled: how many markers the panel holds, and how many this sample has a genotype for.eye,hair,skin: 1 or 0, whether the HIrisPlex-S rules allow that prediction from these markers at all. The manual refuses an eye prediction without HERC2rs12913832, a hair prediction when all 11 MC1R markers are missing, and both when HERC2, SLC45A2 and IRF4 are all missing, because the loss in AUC is too great. It sets no such rule for skin, soskinis 0 only when nothing at all was called.trait_predicthonours these.
A genotype is counted only when the call is diploid and complete: a ./., a ./1, a haploid call (the panel is autosomal) or one below min_depth leaves the marker without a genotype. A site split into one record per ALT is counted from whichever record carries the counted allele, in either order, and a record at a marker's position whose REF is longer than one base is some other variant and is passed over.
hirisplex_genotypes warns when the file holds none of the 41 markers, which usually means the wrong build or an ID column of ..
Reading the markers is done in XS, in one pass, keeping one byte per sample per marker, so a whole-genome VCF costs no more memory than a small one. A 275,879-record exome of 22 MB gzipped took 0.86 s (perl 5.44.0, 2026-10-20).
Most of the panel is intronic or intergenic, so an exome carries little of it: that same exome held 9 of the 41 markers. A whole-genome VCF, a genotyping array that covers the panel, or the SNaPshot assay the panel was designed for is what the prediction expects, and missing and called are returned so that a prediction made from a handful of markers can be seen for what it is.
trait_predict(%args)
Applies a multinomial logistic regression -- which is what the HIrisPlex-S, HIrisPlex and IrisPlex models are -- to genotypes, and returns a probability for each category of each trait:
use Cn::Bioinf qw(hirisplex_genotypes trait_predict);
my $g = hirisplex_genotypes(vcf => 'genome.vcf.gz', report => 0);
my $p = trait_predict(genotypes => $g, model => 'my_model.tsv');
print $p->{NA12878}{eye}{call}; # the most probable category
print $p->{NA12878}{eye}{p}{blue}; # its probability
The model is yours to supply: see hirisplex_genotypes above for why this distribution ships none. Any model written in the form below works, so this is not limited to pigmentation.
The model table
A tab-separated file (optionally gzipped), or a data frame as Stats::LikeR's read_table returns, with four columns:
trait category marker beta
eye blue (intercept) 3.94
eye blue rs12913832_T -4.81
eye brown (intercept) 0
marker is a key of the genotype hash hirisplex_genotypes returns, which is <rs number>_<input allele>, or the literal (intercept) for the category's intercept. A category whose only row is an intercept of 0 is the reference category, which is how a model of k categories is written with k - 1 sets of betas; every category that should appear in the result needs at least one row. Traits and their categories come out in the order the table first names them.
For each category the linear predictor is its intercept plus the sum of its betas times the genotypes, and the probabilities are exp of those over their sum. The largest is taken out before exp, so a linear predictor large enough to overflow gives 1 rather than a NaN.
Arguments
genotypes(required): whathirisplex_genotypesreturned, or a plain hash ref of sample => { marker => 0, 1 or 2 }. A dosage may be any number from 0 to 2, as imputation gives, andundefis no genotype; anything else,NAincluded, dies naming the sample and the marker. Only the markers the model uses are looked at.model(required): the table above, as a file name or a data frame.force: 0 (the default) makes no prediction for a trait that the genotypes say cannot be predicted -- that is, wherehirisplex_genotypesseteye,hairorskinto 0; 1 predicts it anyway. A trait the genotypes say nothing about is always predicted.report: 1 (the default) prints a table of the samples to STDOUT; 0 returns them only.
What it returns
A hash ref keyed by sample and then by trait, each holding:
p: a hash ref of category => probability, which sum to 1; empty when the prediction was refused.call: the most probable category, orundefwhen it was refused. A tie is broken by the category's name, so the answer does not depend on hash order.markersandcalled: how many markers the trait's categories use between them, and how many this sample has a genotype for.missing: an array ref of the markers the model names and the sample has no genotype for.refused:undef, or why no prediction was made.
A marker the sample has no genotype for drops out of the sum, which is the same as counting it 0 copies of the counted allele. That is a choice, not something the HIrisPlex-S authors specify, and it biases the result towards whatever 0 copies means for that marker; missing and called are returned so that a prediction made from few markers can be reported as such. The webtool reports a loss in AUC for exactly this reason.
plot_msa(%args)
Aligns sequences with Clustal Omega and draws the alignment. Returns a hash ref of the files made: filename, msa_file, python_file (see fh and execute below), and tree_file if it was given. Once the image is written it prints wrote and its file name to STDOUT, the name in black on yellow when STDOUT is a terminal; with execute => 0 it prints will write instead.
plot_msa(
fasta => 't/data/DEG20010421.fa',
filename => 'DEG20010421.msa.svg',
);
fasta,filename(required): the sequences, as a FASTA file name or a hash ref of name => sequence (the function tells the two apart by whether it is a reference); and the image to draw, whose extension picks the format. A name may hold spaces and punctuation: Clustal Omega is given the sequences ass1,s2and so on, and the alignment and tree it writes get their names back, in UTF-8. In the tree, a name with whitespace or any of()[]':;,in it is quoted as newick quotes one, as'it''s (x:1)'.msa_file,tree_file: where to keep clustalo's alignment (FASTA; a temporary file otherwise) and its guide tree (newick; not made otherwise). Keep the tree to draw it withplot_phylowithout aligning a second time.order: names, first to last (default: the input order; for a hash, sorted). Only these are drawn, and the first is drawn at the bottom.labels: a hash ref of name => label to show instead. matplotlib mathtext works:'C.albicans' => '$\it{C. albicans}$'. Two sequences drawn under one label die, since they would be one row of the image.active_site_aa,query:{ His395 => 395, ... }, a dashed vertical line at each of these 1-based residue numbers of the sequence named byquery. A number below 1 dies.tooltips: 1 to give each residue a tooltip, which a browser shows when the pointer rests on it, naming the sequence, the residue and its number in that sequence, and the alignment column, asS.cerevisiae: Lys100, alignment column 105(default 0). The sequence is named as it was given, not by its label. Only SVG carries tooltips, sofilenamemust end in.svg. Each residue is an element of the SVG, so a large alignment makes a large file.title,xlabel,ylabel,threads,clustal_args: the plot title; the axis labels (default "Amino Acid Residue" and "Protein & Species"); clustalo threads (default 1); and an array ref of extra clustalo arguments.fh,execute: as for Matplotlib::Simple'splt. The image is drawn by a Python script, andfhis aFile::Tempobject to append that script to; without it, the script goes in a new temporary file.executeis 1 (the default) to run the script now, under Alien::Bioinf's Python, or 0 only to write it. So several calls with onefhandexecute => 0, then a last one withexecute => 1, draw every image in one run of Python. Thefhmay be one that Matplotlib::Simple'spltalso writes to, since the Python each function appends stands alone. Clustal Omega runs either way; only the drawing waits.python_fileis the script's file name:fh's, or the temporary file's, which is kept after perl exits only whenexecuteis 0. The script carries the alignment and everything else it reads, so it can be run later, withperl -MAlien::Bioinf -e 'print Alien::Bioinf->python'giving the Python to run it with, after perl's own temporary files have gone.
With fewer than two sequences it warns and returns an empty hash ref.
plot_phylo(%args)
Draws a guide tree, with Biopython's Bio.Phylo, from a FASTA (aligned with Clustal Omega first) or from a newick file that plot_msa kept. Returns a hash ref of the files made or used: output_file, python_file, and tree_file and msa_file as below.
plot_phylo(fasta => 't/data/DEG20010421.fa'); # writes phylo.svg
plot_phylo(
tree_file => 'DEG20010421.newick',
output_file => 'DEG20010421.tree.png',
);
output_file: the image to draw (defaultphylo.svg, in the working directory); the extension picks the format.fasta,tree_file: withfasta(as forplot_msa), the sequences are aligned with Clustal Omega and the guide tree drawn;tree_fileandmsa_filethen say where to keep the tree and alignment, andthreadsandclustal_argsare as forplot_msa. Withoutfasta,tree_fileis an existing newick file to draw, such as oneplot_msakept, and no alignment is made.labels,title: a hash ref of name => label for the tips, as forplot_msa; and the plot title.fh,execute: as forplot_msa, which can share anfhwith this; the script carries the newick tree it draws.python_fileis the script's file name.
With fasta of fewer than two sequences it warns and returns an empty hash ref.
msa_quality_table(%args)
Draws an all-against-all BLAST score table with matplotlib, and returns filename. The simplest call is
msa_quality_table(
fasta => 't/data/DEG20010421.fa', # or { name => sequence }, aligned or not
filename => 'DEG20010421.scores.png',
);
fasta,filename(required): the sequences, as a FASTA file name or a hash ref of name => sequence, as forplot_msa; they are aligned all against all withblastp. Gaps are stripped first, so an aligned FASTA, such as the oneplot_msakeeps, will do. Names must look likeGenus.species[.strain].fastais not needed when an existingalignment_jsonis given.unaligned_fais its old name.alignment_json: theblastp -outfmt 15report, as a parsed hash ref or a file name. An existing file is read, and nothing is aligned; otherwiseblastpis run onfastaand its report kept there for next time. Without it, the report is a temporary file.metric: the hsp field to show (defaultscore).normalize: divide every value by the largest, after addinglogscale_addto both, so the scale runs to 1. A largest value of 0 or less, asevaluehas when BLAST has rounded every e-value to 0, dies.order,logscale_add,default_undefined,title,cb_label,cb_min,cb_max,cblogscale,show_numbers: the sequences to show, in order; a number added to every value; the value of a pair with no hit (otherwise drawn grey); the title; the colour bar's label, lower and upper ends, and whether it is logarithmic; and whether each cell shows its number. A name inorderthat the report does not hold dies, and so does alogscale_add,default_undefined,cb_min,cb_maxornormalizethat is not a number.
msa_file is accepted and ignored, for old callers.
clustal_view_residues(%args)
Writes an alignment as LaTeX tables with chosen residues coloured, and returns output_tex_file, printing wrote and that file name to STDOUT, the name in black on cyan when STDOUT is a terminal. Protein names and residues are written so that LaTeX prints them as they are, _, ^, {, |, < and the like included.
msa_file(required): a FASTA file. If its sequences are all one length (such as the alignmentplot_msakeeps) it is shown as it is; if not, it is first aligned with Clustal Omega into a temporary file, andmsa_fileitself is never written.output_tex_file(required): the LaTeX file to write, meant to be\inputinto a document whose preamble loadsxcolor(for the colours) andplaceins(for the\FloatBarrierafter each table).color_residues:{ protein => { residue number => colour } }, where residue numbers are 1-based and a colour is an xcolor name or[r, g, b]; a coloured column is coloured in every protein.track: a protein that gets a row under it showing its coloured residue numbers, each starting at its residue's column, or just after the number before it. A number that would run past the end of its block ends at the block's last column instead, and is left out only when it would then overwrite the number before it.order: an array ref of the proteins to show, top to bottom (default: sorted, ignoring case).row_width: alignment columns per block (default 100).split: blocks per LaTeX table (default 4); further tables are captioned "(continued)".caption: the table caption (default empty).label: written as\label{tab:label}, or astab:label0,tab:label1, ... when there is more than one table.table_text_size: the LaTeX size command put at the start of each table (default\footnotesize).threads,clustal_args: clustalo threads (default 1) and an array ref of further clustalo arguments, whenmsa_filehas to be aligned.
Thanks
A lot of this work (not all!) used Claude AI, which was paid for by the University of Idaho's IMCI
AUTHOR
David E. Condon <dcondon@uidaho.edu>
COPYRIGHT AND LICENSE
This software is copyright (c) 2026-present by David E. Condon.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.