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:

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);

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 };

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 }

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

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.

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

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:

How well it aligns:

What kind of structure it is:

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.

Returns a hash ref keyed by sample, a hash of hashes that write_table can write, with these fields for each sample:

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:

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.

What is counted, and where sex_check differs from peddy:

Returns a hash ref keyed by sample, a hash of hashes that write_table can write, with these fields for each sample:

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.

What is counted:

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

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:

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.

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:

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:

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.

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:

concordance returns a hash keyed by the test's name for each sample compared. Each sample's hash has these fields on every return:

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 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

What it returns

A hash ref keyed by sample name, each holding:

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

What it returns

A hash ref keyed by sample name, each holding:

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

What it returns

A hash ref keyed by sample and then by trait, each holding:

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',
);

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',
);

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',
);

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.

Thanks

A lot of this work (not all!) used Claude AI, which was paid for by the University of Idaho's IMCI