def alpha_diversity(metric, counts, ids=None, validate=True, **kwargs):
""" Compute alpha diversity for one or more samples
Parameters
----------
metric : str, callable
The alpha diversity metric to apply to the sample(s). Passing metric as
a string is preferable as this often results in an optimized version of
the metric being used.
counts : 1D or 2D array_like of ints or floats
Vector or matrix containing count/abundance data. If a matrix, each row
should contain counts of OTUs in a given sample.
ids : iterable of strs, optional
Identifiers for each sample in ``counts``. By default, samples will be
assigned integer identifiers in the order that they were provided.
validate: bool, optional
If `False`, validation of the input won't be performed. This step can
be slow, so if validation is run elsewhere it can be disabled here.
However, invalid input data can lead to invalid results or error
messages that are hard to interpret, so this step should not be
bypassed if you're not certain that your input data are valid. See
Notes for the description of what validation entails so you can
determine if you can safely disable validation.
kwargs : kwargs, optional
Metric-specific parameters.
Returns
-------
pd.Series
Values of ``metric`` for all vectors provided in ``counts``. The index
will be ``ids``, if provided.
Raises
------
ValueError, MissingNodeError, DuplicateNodeError
If validation fails (see description of validation in Notes). Exact
error will depend on what was invalid.
TypeError
If invalid method-specific parameters are provided.
See Also
--------
skbio.diversity.alpha
skbio.diversity.beta_diversity
Notes
-----
The value that you provide for ``metric`` can be either a string (e.g.,
``"faith_pd"``) or a function (e.g., ``skbio.diversity.alpha.faith_pd``).
The metric should generally be passed as a string, as this often uses an
optimized version of the metric. For example, passing ``"faith_pd"`` (a
string) will be tens of times faster than passing the function
``skbio.diversity.alpha.faith_pd``. The latter may be faster if computing
alpha diversity for only one or a few samples, but in these cases the
difference in runtime is negligible, so it's safer to just err on the side
of passing ``metric`` as a string.
Validation of input data confirms the following:
* ``counts`` data can be safely cast to integers
* there are no negative values in ``counts``
* ``counts`` has the correct number of dimensions
* if ``counts`` is 2-D, all vectors are of equal length
* the correct number of ``ids`` is provided (if any are provided)
For phylogenetic diversity metrics, validation additional confirms that:
* ``otu_ids`` does not contain duplicate values
* the length of each ``counts`` vector is equal to ``len(otu_ids)``
* ``tree`` is rooted
* ``tree`` has more than one node
* all nodes in ``tree`` except for the root node have branch lengths
* all tip names in ``tree`` are unique
* all ``otu_ids`` correspond to tip names in ``tree``
"""
metric_map = _get_alpha_diversity_metric_map()
if validate:
counts = _validate_counts_matrix(counts, ids=ids)
if metric == 'faith_pd':
otu_ids, tree, kwargs = _get_phylogenetic_kwargs(counts, **kwargs)
counts_by_node, branch_lengths = _setup_faith_pd(counts,
otu_ids,
tree,
validate,
single_sample=False)
counts = counts_by_node
metric = functools.partial(_faith_pd, branch_lengths=branch_lengths)
elif callable(metric):
metric = functools.partial(metric, **kwargs)
elif metric in metric_map:
metric = functools.partial(metric_map[metric], **kwargs)
else:
raise ValueError('Unknown metric provided: %r.' % metric)
results = [metric(c) for c in counts]
return pd.Series(results, index=ids)
def alpha_diversity(metric, counts, ids=None, validate=True, **kwargs):
""" Compute alpha diversity for one or more samples
Parameters
----------
metric : str, callable
The alpha diversity metric to apply to the sample(s). Passing metric as
a string is preferable as this often results in an optimized version of
the metric being used.
counts : 1D or 2D array_like of ints or floats
Vector or matrix containing count/abundance data. If a matrix, each row
should contain counts of OTUs in a given sample.
ids : iterable of strs, optional
Identifiers for each sample in ``counts``. By default, samples will be
assigned integer identifiers in the order that they were provided.
validate: bool, optional
If `False`, validation of the input won't be performed. This step can
be slow, so if validation is run elsewhere it can be disabled here.
However, invalid input data can lead to invalid results or error
messages that are hard to interpret, so this step should not be
bypassed if you're not certain that your input data are valid. See
:mod:`skbio.diversity` for the description of what validation entails
so you can determine if you can safely disable validation.
kwargs : kwargs, optional
Metric-specific parameters.
Returns
-------
pd.Series
Values of ``metric`` for all vectors provided in ``counts``. The index
will be ``ids``, if provided.
Raises
------
ValueError, MissingNodeError, DuplicateNodeError
If validation fails. Exact error will depend on what was invalid.
TypeError
If invalid method-specific parameters are provided.
See Also
--------
skbio.diversity
skbio.diversity.alpha
skbio.diversity.get_alpha_diversity_metrics
skbio.diversity.beta_diversity
"""
metric_map = _get_alpha_diversity_metric_map()
if validate:
counts = _validate_counts_matrix(counts, ids=ids)
if metric == 'faith_pd':
otu_ids, tree, kwargs = _get_phylogenetic_kwargs(counts, **kwargs)
counts_by_node, branch_lengths = _setup_faith_pd(counts,
otu_ids,
tree,
validate,
single_sample=False)
counts = counts_by_node
metric = functools.partial(_faith_pd, branch_lengths=branch_lengths)
elif callable(metric):
metric = functools.partial(metric, **kwargs)
elif metric in metric_map:
metric = functools.partial(metric_map[metric], **kwargs)
else:
raise ValueError('Unknown metric provided: %r.' % metric)
# kwargs is provided here so an error is raised on extra kwargs
results = [metric(c, **kwargs) for c in counts]
return pd.Series(results, index=ids)
def alpha_diversity(metric, counts, ids=None, validate=True, **kwargs):
""" Compute alpha diversity for one or more samples
Parameters
----------
metric : str, callable
The alpha diversity metric to apply to the sample(s). Passing metric as
a string is preferable as this often results in an optimized version of
the metric being used.
counts : 1D or 2D array_like of ints or floats
Vector or matrix containing count/abundance data. If a matrix, each row
should contain counts of OTUs in a given sample.
ids : iterable of strs, optional
Identifiers for each sample in ``counts``. By default, samples will be
assigned integer identifiers in the order that they were provided.
validate: bool, optional
If `False`, validation of the input won't be performed. This step can
be slow, so if validation is run elsewhere it can be disabled here.
However, invalid input data can lead to invalid results or error
messages that are hard to interpret, so this step should not be
bypassed if you're not certain that your input data are valid. See
:mod:`skbio.diversity` for the description of what validation entails
so you can determine if you can safely disable validation.
kwargs : kwargs, optional
Metric-specific parameters.
Returns
-------
pd.Series
Values of ``metric`` for all vectors provided in ``counts``. The index
will be ``ids``, if provided.
Raises
------
ValueError, MissingNodeError, DuplicateNodeError
If validation fails. Exact error will depend on what was invalid.
TypeError
If invalid method-specific parameters are provided.
See Also
--------
skbio.diversity
skbio.diversity.alpha
skbio.diversity.get_alpha_diversity_metrics
skbio.diversity.beta_diversity
"""
metric_map = _get_alpha_diversity_metric_map()
if validate:
counts = _validate_counts_matrix(counts, ids=ids)
if metric == 'faith_pd':
otu_ids, tree, kwargs = _get_phylogenetic_kwargs(counts, **kwargs)
counts_by_node, branch_lengths = _setup_faith_pd(
counts, otu_ids, tree, validate, single_sample=False)
counts = counts_by_node
metric = functools.partial(_faith_pd, branch_lengths=branch_lengths)
elif callable(metric):
metric = functools.partial(metric, **kwargs)
elif metric in metric_map:
metric = functools.partial(metric_map[metric], **kwargs)
else:
raise ValueError('Unknown metric provided: %r.' % metric)
# kwargs is provided here so an error is raised on extra kwargs
results = [metric(c, **kwargs) for c in counts]
return pd.Series(results, index=ids)
def alpha_diversity(metric, counts, ids=None, validate=True, **kwargs):
""" Compute alpha diversity for one or more samples
Parameters
----------
metric : str, callable
The alpha diversity metric to apply to the sample(s). Passing metric as
a string is preferable as this often results in an optimized version of
the metric being used.
counts : 1D or 2D array_like of ints or floats
Vector or matrix containing count/abundance data. If a matrix, each row
should contain counts of OTUs in a given sample.
ids : iterable of strs, optional
Identifiers for each sample in ``counts``. By default, samples will be
assigned integer identifiers in the order that they were provided.
validate: bool, optional
If `False`, validation of the input won't be performed. This step can
be slow, so if validation is run elsewhere it can be disabled here.
However, invalid input data can lead to invalid results or error
messages that are hard to interpret, so this step should not be
bypassed if you're not certain that your input data are valid. See
Notes for the description of what validation entails so you can
determine if you can safely disable validation.
kwargs : kwargs, optional
Metric-specific parameters.
Returns
-------
pd.Series
Values of ``metric`` for all vectors provided in ``counts``. The index
will be ``ids``, if provided.
Raises
------
ValueError, MissingNodeError, DuplicateNodeError
If validation fails (see description of validation in Notes). Exact
error will depend on what was invalid.
TypeError
If invalid method-specific parameters are provided.
See Also
--------
skbio.diversity.alpha
skbio.diversity.beta_diversity
Notes
-----
The value that you provide for ``metric`` can be either a string (e.g.,
``"faith_pd"``) or a function (e.g., ``skbio.diversity.alpha.faith_pd``).
The metric should generally be passed as a string, as this often uses an
optimized version of the metric. For example, passing ``"faith_pd"`` (a
string) will be tens of times faster than passing the function
``skbio.diversity.alpha.faith_pd``. The latter may be faster if computing
alpha diversity for only one or a few samples, but in these cases the
difference in runtime is negligible, so it's safer to just err on the side
of passing ``metric`` as a string.
Validation of input data confirms the following:
* ``counts`` data can be safely cast to integers
* there are no negative values in ``counts``
* ``counts`` has the correct number of dimensions
* if ``counts`` is 2-D, all vectors are of equal length
* the correct number of ``ids`` is provided (if any are provided)
For phylogenetic diversity metrics, validation additional confirms that:
* ``otu_ids`` does not contain duplicate values
* the length of each ``counts`` vector is equal to ``len(otu_ids)``
* ``tree`` is rooted
* ``tree`` has more than one node
* all nodes in ``tree`` except for the root node have branch lengths
* all tip names in ``tree`` are unique
* all ``otu_ids`` correspond to tip names in ``tree``
"""
metric_map = _get_alpha_diversity_metric_map()
if validate:
counts = _validate_counts_matrix(counts, ids=ids)
if metric == 'faith_pd':
otu_ids, tree, kwargs = _get_phylogenetic_kwargs(counts, **kwargs)
counts_by_node, branch_lengths = _setup_faith_pd(
counts, otu_ids, tree, validate, single_sample=False)
counts = counts_by_node
metric = functools.partial(_faith_pd, branch_lengths=branch_lengths)
elif callable(metric):
metric = functools.partial(metric, **kwargs)
elif metric in metric_map:
metric = functools.partial(metric_map[metric], **kwargs)
else:
raise ValueError('Unknown metric provided: %r.' % metric)
results = [metric(c) for c in counts]
return pd.Series(results, index=ids)