Fork me on GitHub

Warning

This site has been replaced by the new QIIME 2 “amplicon distribution” documentation, as of the 2025.4 release of QIIME 2. You can still access the content from the “old docs” here for the QIIME 2 2024.10 and earlier releases, but we recommend that you transition to the new documentation at https://amplicon-docs.qiime2.org. Content on this site is no longer updated and may be out of date.

Are you looking for:

Old content beyond this point… 👴👵

mantel: Apply the Mantel test to two distance matrices

Citations

  • Nathan Mantel. The detection of disease clustering and a generalized regression approach. Cancer research, 27(2 Part 1):209–220, 1967.

  • Karl Pearson. Note on regression and inheritance in the case of two parents. Proceedings of the Royal Society of London, 58:240–242, 1895. doi:https://doi.org/10.1098/rspl.1895.0041.

  • Charles Spearman. The proof and measurement of association between two things. The American journal of psychology, 15(1):72–101, 1904. doi:https://doi.org/10.2307/1422689.

Docstring:

Usage: qiime diversity mantel [OPTIONS]

  Apply a two-sided Mantel test to identify correlation between two distance
  matrices.

  Note: the directionality of the comparison has no bearing on the results.
  Thus, comparing distance matrix X to distance matrix Y is equivalent to
  comparing Y to X.

  Note: the order of samples within the two distance matrices does not need to
  be the same; the distance matrices will be reordered before applying the
  Mantel test.

  See the scikit-bio docs for more details about the Mantel test:

  http://scikit-bio.org/docs/latest/generated/skbio.stats.distance.mantel

Inputs:
  --i-dm1 ARTIFACT       Matrix of distances between pairs of samples.
    DistanceMatrix                                                  [required]
  --i-dm2 ARTIFACT       Matrix of distances between pairs of samples.
    DistanceMatrix                                                  [required]
Parameters:
  --p-method TEXT Choices('spearman', 'pearson')
                         The correlation test to be applied in the Mantel
                         test.                           [default: 'spearman']
  --p-permutations INTEGER
    Range(0, None)       The number of permutations to be run when computing
                         p-values. Supplying a value of zero will disable
                         permutation testing and p-values will not be
                         calculated (this results in *much* quicker execution
                         time if p-values are not desired).     [default: 999]
  --p-intersect-ids / --p-no-intersect-ids
                         If supplied, IDs that are not found in both distance
                         matrices will be discarded before applying the Mantel
                         test. Default behavior is to error on any mismatched
                         IDs.                                 [default: False]
  --p-label1 TEXT        Label for `dm1` in the output visualization.
                                                [default: 'Distance Matrix 1']
  --p-label2 TEXT        Label for `dm2` in the output visualization.
                                                [default: 'Distance Matrix 2']
Outputs:
  --o-visualization VISUALIZATION
                                                                    [required]
Miscellaneous:
  --output-dir PATH      Output unspecified results to a directory
  --verbose / --quiet    Display verbose output to stdout and/or stderr
                         during execution of this action. Or silence output if
                         execution is successful (silence is golden).
  --example-data PATH    Write example data and exit.
  --citations            Show citations and exit.
  --use-cache DIRECTORY  Specify the cache to be used for the intermediate
                         work of this action. If not provided, the default
                         cache under $TMP/qiime2/ will be used.
                         IMPORTANT FOR HPC USERS: If you are on an HPC system
                         and are using parallel execution it is important to
                         set this to a location that is globally accessible to
                         all nodes in the cluster.
  --help                 Show this message and exit.

Import:

from qiime2.plugins.diversity.visualizers import mantel

Docstring:

Apply the Mantel test to two distance matrices

Apply a two-sided Mantel test to identify correlation between two distance
matrices.  Note: the directionality of the comparison has no bearing on the
results. Thus, comparing distance matrix X to distance matrix Y is
equivalent to comparing Y to X.  Note: the order of samples within the two
distance matrices does not need to be the same; the distance matrices will
be reordered before applying the Mantel test.  See the scikit-bio docs for
more details about the Mantel test:  http://scikit-
bio.org/docs/latest/generated/skbio.stats.distance.mantel

Parameters
----------
dm1 : DistanceMatrix
    Matrix of distances between pairs of samples.
dm2 : DistanceMatrix
    Matrix of distances between pairs of samples.
method : Str % Choices('spearman', 'pearson'), optional
    The correlation test to be applied in the Mantel test.
permutations : Int % Range(0, None), optional
    The number of permutations to be run when computing p-values. Supplying
    a value of zero will disable permutation testing and p-values will not
    be calculated (this results in *much* quicker execution time if
    p-values are not desired).
intersect_ids : Bool, optional
    If supplied, IDs that are not found in both distance matrices will be
    discarded before applying the Mantel test. Default behavior is to error
    on any mismatched IDs.
label1 : Str, optional
    Label for `dm1` in the output visualization.
label2 : Str, optional
    Label for `dm2` in the output visualization.

Returns
-------
visualization : Visualization