Type:	Package
Title:	An R Package for the Mean Measure of Divergence (MMD)
Description:	Offers a graphical user interface for the calculation of the mean measure of divergence, with facilities for trait selection and graphical representations <doi:10.1002/ajpa.23336>.
Version:	4.0.3
Depends:	R (≥ 4.1.0)
Imports:	dplyr, MASS, plotrix, rlang, scatterplot3d, shiny, smacof
Suggests:	cluster, covr, knitr, rmarkdown, testthat (≥ 2.1.0)
License:	CeCILL-2 | file LICENSE
Encoding:	UTF-8
URL:	https://gitlab.com/f-santos/anthropmmd/
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2023-11-29 09:28:21 UTC; fsantos
Author:	Frédéric Santos [aut, cre]
Maintainer:	Frédéric Santos <frederic.santos@u-bordeaux.fr>
Repository:	CRAN
Date/Publication:	2023-11-29 10:40:02 UTC

An R package for the Mean Measure of Divergence (MMD)

Description

Offers a graphical user interface for the calculation of the mean measure of divergence, with facilities for trait selection and graphical representations.

Author(s)

Frédéric Santos, frederic.santos@u-bordeaux.fr

References

Harris, E. F. and Sjøvold, T. (2004) Calculation of Smith's mean measure of divergence for intergroup comparisons using nonmetric data. Dental Anthropology, 17(3), 83–93.

Irish, J. (2010) The mean measure of divergence: Its utility in model-free and model-bound analyses relative to the Mahalanobis D2 distance for nonmetric traits. American Journal of Human Biology, 22, 378–395. doi: 10.1002/ajhb.21010

Nikita, E. (2015) A critical review of the mean measure of divergence and Mahalanobis distances using artificial data and new approaches to the estimation of biodistances employing nonmetric traits. American Journal of Physical Anthropology, 157, 284–294. doi: 10.1002/ajpa.22708

Santos, F. (2018) AnthropMMD: an R package with a graphical user interface for the mean measure of divergence. American Journal of Physical Anthropology, 165(1), 200–205. doi: 10.1002/ajpa.23336

Fidalgo, D., Hubbe, M. and Wesolowski, V. (2021) Population History of Brazilian South and Southeast Shellmound Builders Inferred through Dental Morphology. American Journal of Physical Anthropology, 176(2), 192–207. doi: 10.1002/ajpa.24342

Examples

## Not run:  start_mmd() 

A toy example dataset for mean measures of divergence, in a table format

Description

This artifical dataset includes 200 individuals described by 9 binary traits and splitted into 5 groups. To fit with commonly observed datasets in past sciences, a substantial amount of missing values have been added at random on this dataset.

Usage

data(absolute_freqs)

Format

A matrix with 10 rows and 9 columns:

Trait1

summary statistics for this trait

Trait2

summary statistics for this trait

Trait3

summary statistics for this trait

Trait4

summary statistics for this trait

Trait5

summary statistics for this trait

Trait6

summary statistics for this trait

Trait7

summary statistics for this trait

Trait8

summary statistics for this trait

Trait9

summary statistics for this trait

Converts a data frame of binary (i.e., presence/absence) trait information into a table of sample sizes and frequencies.

Description

This function allows to get a summary of sample sizes and frequencies for each trait in each group. It is also mandatory to apply this function before using the mmd function, since the latter only accepts table of frequencies, and cannot work with raw binary data.

Usage

binary_to_table(data, relative = FALSE)

Arguments

Value

A matrix with 2*K rows (K being the number of groups in the dataset) and p columns (one per trait). The first K rows are the sample sizes, the last K rows are trait frequencies.

Author(s)

Frédéric Santos, frederic.santos@u-bordeaux.fr

References

Santos, F. (2018) AnthropMMD: an R package with a graphical user interface for the mean measure of divergence. American Journal of Physical Anthropology, 165(1), 200–205. doi: 10.1002/ajpa.23336

See Also

start_mmd

Examples

## Load and visualize a binary dataset:
data(toyMMD)
head(toyMMD)

## Convert this dataframe into a table of sample sizes and relative frequencies:
binary_to_table(toyMMD, relative = TRUE)

Compute MMD values from a table of sample sizes and relative frequencies

Description

Compute various MMD results, typically using a table returned by the function binary_to_table with the argument relative = TRUE.

Usage

mmd(data, angular = c("Anscombe", "Freeman"), correct = TRUE,
    all.results = TRUE)

Arguments

Value

A list with four components:

Author(s)

Frédéric Santos, frederic.santos@u-bordeaux.fr

References

de Souza, P. and Houghton, P. (1977). The mean measure of divergence and the use of non-metric data in the estimation of biological distances. Journal of Archaeological Science, 4(2), 163–169. doi: 10.1016/0305-4403(77)90063-2

Harris, E. F. and Sjøvold, T. (2004) Calculation of Smith's mean measure of divergence for intergroup comparisons using nonmetric data. Dental Anthropology, 17(3), 83–93.

Nikita, E. (2015) A critical review of the mean measure of divergence and Mahalanobis distances using artificial data and new approaches to the estimation of biodistances employing nonmetric traits. American Journal of Physical Anthropology, 157, 284–294. doi: 10.1002/ajpa.22708

See Also

start_mmd

Examples

## Load and visualize a binary dataset:
data(toyMMD)
head(toyMMD)

## Convert this dataframe into a table of sample sizes and relative
## frequencies:
tab <- binary_to_table(toyMMD, relative = TRUE)
tab

## Compute and display a symmetrical matrix of MMD values:
mmd_out <- mmd(tab, angular = "Anscombe")
mmd_out$MMDSym

## Significant MMD values are indicated by a star:
mmd_out$MMDSignif

Implementation of Fidalgo et al.'s (2022) method of bootstrap for the Mean Measure of Divergence

Description

Compute a matrix of MMD dissimilarities among bootstrapped samples of the original groups. The input data must be a “raw binary dataset”.

Usage

mmd_boot(data, angular = c("Anscombe", "Freeman"), B = 100, ...)

Arguments

Details

This function sticks very close to Fidalgo et al's (2022) implementation. In particular, no correction for small sample sizes is applied in the MMD formula; see Fidalgo et al's (2021) for the rationale.

Note that only a “raw binary dataset” is allowed as input, since the resampling cannot be performed properly from a table of counts and frequencies.

To get a MDS plot of the dissimilarity matrix obtained with this function, see plot.anthropmmd_boot.

Value

A symmetrical dissimilarity matrix of MMD values among original groups and bootstrapped samples. This matrix is an R object of class anthropmmd_boot.

Author(s)

Frédéric Santos, frederic.santos@u-bordeaux.fr

References

D. Fidalgo, M. Hubbe and V. Vesolowski (2021). Population history of Brazilian south and southeast shellmound builders inferred through dental morphology. American Journal of Physical Anthropology 176(2), 192-207.

D. Fidalgo, V. Vesolowski and M. Hubbe (2022). Biological affinities of Brazilian pre-colonial coastal communities explored through boostrapped biodistances of dental non-metric traits. Journal of Archaeological Science 138, 105545.

See Also

plot.anthropmmd_boot

Examples

## Not run: 
## Load and visualize a raw binary dataset:
data(toyMMD)
head(toyMMD)
## Compute MMD among bootstrapped samples:
resboot <- mmd_boot(
    data = toyMMD,
    B = 50, # number of bootstrap samples
    angular = "Anscombe",
    strategy = "excludeQNPT", # strategy for trait selection
    k = 10 # minimal number of observations required per trait
)
## View part of MMD matrix among bootstrapped samples:
dim(resboot)
print(resboot[1:15, 1:15])

## End(Not run)

Display a multidimensional scaling (MDS) plot using Fidalgo et al's (2022) bootstrap method for MMD

Description

This function plots a 2D MDS to represent the MMD dissimilarities among the groups compared, after a bootstrap resampling performed with mmd_boot.

Usage

## S3 method for class 'anthropmmd_boot'
plot(x, method = c("classical", "interval", "ratio", "ordinal"),
    level = 0.95, pch = 16, gof = FALSE, xlab = NA, ylab = NA,
    main = "MDS plot of original and bootstrapped samples", ...)

Arguments

.

Details

In the current implementation, to stick to Fidalgo et al.'s (2022) protocol, this function does not provide as much freedom as plot.anthropmmd_result as concenrs MDS parameters and other analysis options.

Value

This function returns no value by itself, and only plots a MDS in a new device.

Author(s)

Frédéric Santos, frederic.santos@u-bordeaux.fr

References

D. Fidalgo, V. Vesolowski and M. Hubbe (2022). Biological affinities of Brazilian pre-colonial coastal communities explored through boostrapped biodistances of dental non-metric traits. Journal of Archaeological Science 138, 105545.

See Also

start_mmd, stats::cmdscale

Examples

## Not run: 
## Load and visualize a raw binary dataset:
data(toyMMD)
head(toyMMD)
## Compute MMD among bootstrapped samples:
resboot <- mmd_boot(
    data = toyMMD,
    B = 50, # number of bootstrap samples
    angular = "Anscombe",
    strategy = "excludeQNPT", # strategy for trait selection
    k = 10 # minimal number of observations required per trait
)
## MDS plot for bootstrapped samples:
plot(
    x = resboot,
    method = "interval", # algorithm used for MDS computation
    level = 0.95 # confidence level for the contour lines
)

## End(Not run)

Display a multidimensional scaling (MDS) plot with the MMD dissimilarities as input

Description

This function plots a 2D or 3D MDS to represent the MMD dissimilarities among the groups compared. Various MDS methods are proposed, and most of them are based on the R package smacof.

Usage

## S3 method for class 'anthropmmd_result'
plot(x, method = c("classical", "interval", "ratio", "ordinal"),
axes = FALSE, gof = FALSE, dim = 2, asp = TRUE, xlim = NULL, ...)

Arguments

.

Details

• Axes and scale. Making all axes use the same scale is strongly recommended in all cases (Borg et al., 2013). For a 3D-plot, since the third axis carries generally only a very small percentage of the total variability, you might want to uncheck this option to better visualize the distances along the third axis. In this case, the axes scales must be displayed on the plot, otherwise the plot would be misleading.

• Goodness of fit values. (i) For classical metric MDS, a common statistic is given: the sum of the eigenvalues of the first two axes, divided by the sum of all eigenvalues. It indicates the fraction of the total variance of the data represented in the MDS plot. This statistic comes from the $GOF value returned by the function stats::cmdscale. (ii) For SMACOF methods, the statistic given is the $stress value returned by the function smacof::smacofSym It indicates the final stress-1 value. A value very close to 0 corresponds to a perfect fit. (iii) For both approaches, a 'rho' value is also given, which is the Spearman's correlation coefficient between real dissimilarities (i.e., MMD values) and distances observed on the MDS plot (Dzemyda et al.,2013). A value very close to 1 indicates a perfect fit.

Value

This function returns no value by itself, and only plots a MDS in a new device.

Author(s)

Frédéric Santos, frederic.santos@u-bordeaux.fr

References

G. Dzemyda, O. Kurasova and J. Zilinskas (2013) Multidimensional Data Visualization, Springer, chap. 2, p. 39–40.

I. Borg, P. Groenen and P. Mair (2013) Applied Multidimensional Scaling, Springer, chap. 7, p. 79.

See Also

start_mmd, stats::cmdscale, smacof::smacofSym

Examples

## Load and visualize a binary dataset:
data(toyMMD)
head(toyMMD)

## Convert this dataframe into a table of sample sizes and relative
## frequencies:
tab <- binary_to_table(toyMMD, relative = TRUE)
tab

## Compute and display a symmetrical matrix of MMD values:
mmd_out <- mmd(tab, angular = "Freeman")

## Plot a classical metric MDS in two dimensions:
plot(x = mmd_out, method = "classical",
     axes = TRUE, gof = TRUE, dim = 2)

Select a subset of traits meeting certain criteria

Description

This function provides several strategies to discard some useless traits (non-polymorphic, non-discriminatory, etc.) upstream the MMD analysis.

Usage

select_traits(tab, k = 10, strategy = c("none", "excludeNPT",
"excludeQNPT", "excludeNOMD", "keepFisher"), OMDvalue = NULL, groups,
angular = c("Anscombe", "Freeman"))

Arguments

Value

A list with two components:

Author(s)

Frédéric Santos, frederic.santos@u-bordeaux.fr

References

Harris, E. F. and Sjøvold, T. (2004) Calculation of Smith's mean measure of divergence for intergroup comparisons using nonmetric data. Dental Anthropology, 17(3), 83–93.

Santos, F. (2018) AnthropMMD: an R package with a graphical user interface for the mean measure of divergence. American Journal of Physical Anthropology, 165(1), 200–205. doi: 10.1002/ajpa.23336

See Also

start_mmd

Examples

## Load and visualize a binary dataset:
data(toyMMD)
head(toyMMD)

## Convert this dataframe into a table of sample sizes and
## relative frequencies:
tab <- binary_to_table(toyMMD, relative = TRUE)
tab

## Filter this dataset to keep only those traits that have at
## least k=10 individuals in each group:
select_traits(tab, k = 10)
## Only Trait1 is excluded.

## Filter this dataset to keep only those traits that have at
## least k=11 individuals in each group, and show significant
## differences at Fisher's exact test:
select_traits(tab, k = 11, strategy = "keepFisher")
## Traits 1, 5 and 8 are excluded.

An R-Shiny application for the mean measure of divergence

Description

Launches a graphical user interface (GUI) for the calculation of the mean measure of divergence.

Usage

start_mmd()
StartMMD()

Details

The GUI of AnthropMMD is completely autonomous: reading the data file and specifying the parameters of the analysis are done through the interface. Once the dataset is loaded, the output reacts dynamically to any change in the analysis settings.

• AnthropMMD accepts .CSV or .TXT data files, but does not support .ODS or .XLS(X) files. Two types of data input formats can be used:

  • A ‘Raw binary dataset’ (one row for each individual, one column for each variable). The first column must be the group indicator, and the other columns are binary data for the traits studied, where 1 indicates the presence of a trait, and 0 its absence. Row names are optional for this type of file. An example of valid data file can be found as Supporting Information online in Santos (2018).

  • A ‘Table of n's and absolute frequencies for each group’, i.e. a dataset of sample sizes and absolute frequencies. This type of dataset has 2 \times K rows (K being the number of groups compared) and p columns (p being the number of traits studied). The first K lines must be the group n's for each trait, and the last K lines are absolute frequencies for each trait (i.e. the number of times the trait is present). Row names are mandatory for this type of file. The first K rows must be labelled with names beginning with ‘N_’, such as: N_GroupA, N_GroupB, ..., N_GroupK. The last K rows should be labelled with names beginning with ‘Freq_’, such as: Freq_GroupA, ..., Freq_GroupK. An example of valid data file can be found as Supporting Information online in Santos (2018).

  For both data types, column names are strongly recommended for better interpretability of the results.

• One can choose between Anscombe or Freeman-Tukey formula for angular transformation (cf. Harris and Sjøvold 2004; Irish 2010).

• ‘Only retain the traits with this minimal number of individuals per group’: the traits with fewer individuals in at least one active group will not be considered in the analysis.

• ‘Exclusion strategy’: a careful selection of traits is crucial when using MMD (cf. Harris and Sjøvold 2004 for a complete explanation), and the user should probably “exclude the traits that are nondiscriminatory across groups” (Irish 2010).

  • ‘Exclude nonpolymorphic traits’ removes all the traits showing no variability at all, i.e. with the same value (‘0’ or ‘1’) for all individuals.

  • ‘Exclude quasi-nonpolymorphic traits’ also removes the traits whose variability is only due to a single individual: for example, a trait with only one positive observation in the whole dataset.

  • ‘Use Fisher's exact test’ implements the advice given by Harris and Sjøvold (2004) to select contributory traits, defined as those “showing a statistically significant difference between at least one pair of the groups being evaluated”. Fisher's exact tests are performed for each pair of groups, and the traits showing no intergroup difference at all are excluded. Note that if you have a large number of groups (say, 10 groups), a trait with strictly equal frequencies for the last 8 groups may be considered as useful according to this criterion if there is a significant difference for the first two groups. This criterion will select all traits that can be useful for a given pair of groups, even if they are nondiscriminatory for all the other ones.

  • ‘Exclude traits with overall MD’ lower than a given threshold: it is a simple way of removing the traits with quite similar frequencies across groups (the ‘overall MD’ is defined as the sum of the variable's measures of divergence over all pairs of groups). This criterion aims to select the traits whose frequency differs substantially across most or all groups.

  These four options are designed to avoid negative MMD values.

• Some groups/populations can be manually excluded from the analysis. This may be useful if very few individuals belonging to a given population could be recorded for the variables retained by the criteria described above.

• A MDS plot and a hierarchical clustering, done using MMD dissimilarities as inputs, are displayed in the last two tabs. As MMD can sometimes be negative, those negatives values are replaced by zeros, so that the MMD matrix can be seen as a symmetrical distance matrix. Please note that the classical two-dimensional metric MDS plot cannot be displayed if there is only one positive eigenvalue. Several MDS options are proposed, cf. the help page of the smacofSym function from the R package smacof for detailed technical information.

Value

The function returns no value by itself, but all results can be individually downloaded through the graphical interface.

• The ‘true’ MMD values (i.e., which can be negative in the case of small samples with similar traits frequencies, cf. Irish 2010) and their standard deviations are presented in the matrix labelled ‘MMD values (upper triangular part) and associated SD values (lower triangular part)’.

• A MMD value can be considered as significant if it is greater than twice its standard deviation. Significance is assessed in another ad-hoc table of results.

• The negative MMD values, if any, are replaced by zeros in the ‘Symmetrical matrix of MMD values’.

Note

The R console is not available when the GUI is active. To exit the GUI, type Echap (on MS Windows systems) or Ctrl+C (on Linux systems) in the R console.

On 14-inch (or smaller) screens, for convenience, it may be necessary to decrease the zoom level of your web browser and/or to turn on fullscreen mode.

Author(s)

Frédéric Santos, frederic.santos@u-bordeaux.fr

References

Harris, E. F. and Sjøvold, T. (2004) Calculation of Smith's mean measure of divergence for intergroup comparisons using nonmetric data. Dental Anthropology, 17(3), 83–93.

Irish, J. (2010) The mean measure of divergence: Its utility in model-free and model-bound analyses relative to the Mahalanobis D2 distance for nonmetric traits. American Journal of Human Biology, 22, 378–395. doi: 10.1002/ajhb.21010

Nikita, E. (2015) A critical review of the mean measure of divergence and Mahalanobis distances using artificial data and new approaches to the estimation of biodistances employing nonmetric traits. American Journal of Physical Anthropology, 157, 284–294. doi: 10.1002/ajpa.22708

Santos, F. (2018) AnthropMMD: an R package with a graphical user interface for the mean measure of divergence. American Journal of Physical Anthropology, 165(1), 200–205. doi: 10.1002/ajpa.23336

Examples

## An example of valid binary dataset:
data(toyMMD)
head(toyMMD)

## An example of valid table:
data(absolute_freqs)
absolute_freqs

## Launch the GUI:
## Not run:  start_mmd()

Converts a table of sample sizes and frequencies into a table of sample sizes and relative frequencies.

Description

Mostly used as an internal function, but could also be convenient to transform frequencies (i.e., number of individuals having a given trait) into relative frequencies (i.e., proportions).

Usage

table_relfreq(tab)

Arguments

Value

The last K rows (K being the number of groups) of tab are simply transformed to relative frequencies.

Author(s)

Frédéric Santos, frederic.santos@u-bordeaux.fr

See Also

binary_to_table, start_mmd

Examples

## Load and visualize a binary dataset:
data(toyMMD)
head(toyMMD)

## Convert this dataframe into a table of sample sizes and frequencies:
tab <- binary_to_table(toyMMD, relative = FALSE)
tab

## Convert this table into relative frequencies:
table_relfreq(tab)

A toy example dataset for mean measures of divergence, in a binary format

Description

This artifical dataset includes 200 individuals described by 9 binary traits and splitted into 5 groups. To fit with commonly observed datasets in past sciences, a substantial amount of missing values have been added at random on this dataset.

Usage

data(toyMMD)

Format

A data frame with 200 observations on the following 10 variables:

Group

a factor with 5 levels (group indicator)

Trait1

a numeric vector of zeroes and ones

Trait2

a numeric vector of zeroes and ones

Trait3

a numeric vector of zeroes and ones

Trait4

a numeric vector of zeroes and ones

Trait5

a numeric vector of zeroes and ones

Trait6

a numeric vector of zeroes and ones

Trait7

a numeric vector of zeroes and ones

Trait8

a numeric vector of zeroes and ones

Trait9

a numeric vector of zeroes and ones