Bruvo's distance missing estimation: use ordered alleles + deprecation

[zkamvar]

Motivation

Problem

Previously brought up in #139, Bruvo's distance from poppr version 1.1 to the current version (06f36f5) has featured the ability to use the methods of estimating distances of polyploids between partial heterozygotes by averaging over all possible combinations of alleles under the genome addition or genome loss models.

The assumption, however was that this was considering all unordered combinations of alleles, which resulted higher weighting of homozygous genotypes in this calculation.

For example, comparing the genotypes 51/52 and 52/52/53/55 results in a distance of 0.34375 under the combined addition/loss model with the ordered combinations of alleles and 0.35495 with unordered combinations.

Who it affects

This affects those with ALL of the following data characteristics:

• Polyploid data with
• more than 2 missing/ambiguous alleles
• using the genome addition or genome loss model

Solution

Since the calculation for Bruvo's distance is calculated in a manner that is agnostic of order, I was able to fix this bug by multiplying the resulting distance and the counter by the number of unique permutations of the alleles used to fill the shorter genotype.

Calculation of multinomial coefficient (no. unique permutations):

https://github.com/zkamvar/poppr/blob/e724d753dec80355bdf3af0ea78e4e4c37682c3d/src/poppr_distance.c#L795-L842

Implementation in genome addition model:

https://github.com/zkamvar/poppr/blob/e724d753dec80355bdf3af0ea78e4e4c37682c3d/src/poppr_distance.c#L941-L944

This addition is:

• Tested
• Documented
• Added to NEWS

User-facing changes

Repeat length warning -> error

Because Bruvo's distance requires knowledge of the repeat lengths, I have soft-deprecated using the default repeat length setting by issuing the following warning to users:

> pcd <- bruvo.dist(partial_clone)
Warning in bruvo.dist(partial_clone) :

	--------------------------------------------------------------
	                       !!! ALERT !!!

	This warning will become an ERROR in future versions of poppr.
	Please define your repeat lengths to avoid this error.
	--------------------------------------------------------------

Repeat length vector for loci is not equal to the number of loci represented.
Estimating repeat lengths from data:
 c(3, 1, 2, 1, 2, 4, 2, 3, 1, 2)

Option to switch between Bruvo model implementation

I have set an option for the user to switch between the unordered and ordered versions of the genome addition and genome loss models. The user can use options(old.bruvo.model = TRUE) to revert to the previous model, but it is set to FALSE by default, using the correct implementation.