Module ImportFrom alias Import alias identifier Import alias identifier ImportFrom alias ImportFrom alias ImportFrom alias ImportFrom alias FunctionDef arguments args NameParam NameParam NameParam defaults NameLoad body Expr Str If UnaryOpNot Call NameLoad NameLoad NameLoad body Raise Call NameLoad Str If UnaryOpNot Call NameLoad NameLoad AttributeLoad NameLoad attr body Raise Call NameLoad Str If CompareIs NameLoad NameLoad body Assign NameStore Call AttributeLoad AttributeLoad AttributeLoad NameLoad attr attr attr If CompareNotEq Call NameLoad Call NameLoad NameLoad Call NameLoad NameLoad body Raise Call NameLoad Str If CompareLt Call NameLoad NameLoad Num body Raise Call NameLoad Str For NameStore NameLoad body If CompareNotIn NameLoad NameLoad body Raise Call NameLoad BinOpMod Str NameLoad Assign NameStore SubscriptLoad AttributeLoad NameLoad attr Index TupleLoad AttributeLoad NameLoad attr NameLoad If Call AttributeLoad Call AttributeLoad Call AttributeLoad NameLoad attr attr attr body Raise Call NameLoad Str TryExcept body Assign NameStore Call AttributeLoad NameLoad attr NameLoad handlers ExceptHandler type NameLoad body Raise Call NameLoad Str Assign NameStore AttributeLoad Call NameLoad NameLoad attr Assign NameStore Call AttributeLoad NameLoad attr Assign NameStore Call NameLoad NameLoad Assign NameStore Call AttributeLoad NameLoad attr NameLoad Assign NameStore Call AttributeLoad NameLoad attr NameLoad keyword ListLoad TupleLoad Str NameLoad TupleLoad Str NameLoad TupleLoad Str NameLoad For NameStore Call NameLoad Num BinOpAdd NameLoad Num body Assign NameStore NameLoad For NameStore Call NameLoad NameLoad NameLoad body Assign NameStore Call NameLoad SubscriptLoad NameLoad ExtSlice Slice Index NameLoad keyword Str Assign NameStore SubscriptLoad Call NameLoad NameLoad NameLoad Index Num If BoolOpOr CompareIs NameLoad NameLoad CompareGt NameLoad SubscriptLoad NameLoad Index Num body Assign NameStore TupleLoad NameLoad NameLoad Assign NameStore Call AttributeLoad Str attr ListComp SubscriptLoad NameLoad Index NameLoad comprehension NameStore SubscriptLoad NameLoad Index Num Assign SubscriptStore NameLoad Index BinOpSub NameLoad Num TupleLoad NameLoad NameLoad SubscriptLoad NameLoad Index Num Return Call AttributeLoad AttributeLoad NameLoad attr attr NameLoad keyword Str decorator_list Call NameLoad keyword Str FunctionDef arguments args NameParam defaults body Expr Str Assign NameStore Call AttributeLoad NameLoad attr AugAssignSub NameStore Call AttributeLoad NameLoad attr AugAssignDiv NameStore Call AttributeLoad NameLoad attr If Call AttributeLoad Call AttributeLoad Call AttributeLoad NameLoad attr attr attr body Raise Call NameLoad Str Return NameLoad decorator_list
N/A itertools combinations N/A numpy np N/A pandas pd scipy.spatial.distance pdist scipy.stats spearmanr skbio.stats.distance DistanceMatrix skbio.util._decorator experimental bioenv N/A N/A distance_matrix data_frame columns N/A None N/A N/A Find subset of variables maximally correlated with distances.

    Finds subsets of variables whose Euclidean distances (after scaling the
    variables; see Notes section below for details) are maximally
    rank-correlated with the distance matrix. For example, the distance matrix
    might contain distances between communities, and the variables might be
    numeric environmental variables (e.g., pH). Correlation between the
    community distance matrix and Euclidean environmental distance matrix is
    computed using Spearman's rank correlation coefficient (:math:`\rho`).

    Subsets of environmental variables range in size from 1 to the total number
    of variables (inclusive). For example, if there are 3 variables, the "best"
    variable subsets will be computed for subset sizes 1, 2, and 3.

    The "best" subset is chosen by computing the correlation between the
    community distance matrix and all possible Euclidean environmental distance
    matrices at the given subset size. The combination of environmental
    variables with maximum correlation is chosen as the "best" subset.

    Parameters
    ----------
    distance_matrix : DistanceMatrix
        Distance matrix containing distances between objects (e.g., distances
        between samples of microbial communities).
    data_frame : pandas.DataFrame
        Contains columns of variables (e.g., numeric environmental variables
        such as pH) associated with the objects in `distance_matrix`. Must be
        indexed by the IDs in `distance_matrix` (i.e., the row labels must be
        distance matrix IDs), but the order of IDs between `distance_matrix`
        and `data_frame` need not be the same. All IDs in the distance matrix
        must be present in `data_frame`. Extra IDs in `data_frame` are allowed
        (they are ignored in the calculations).
    columns : iterable of strs, optional
        Column names in `data_frame` to include as variables in the
        calculations. If not provided, defaults to all columns in `data_frame`.
        The values in each column must be numeric or convertible to a numeric
        type.

    Returns
    -------
    pandas.DataFrame
        Data frame containing the "best" subset of variables at each subset
        size, as well as the correlation coefficient of each.

    Raises
    ------
    TypeError
        If invalid input types are provided, or if one or more specified
        columns in `data_frame` are not numeric.
    ValueError
        If column name(s) or `distance_matrix` IDs cannot be found in
        `data_frame`, if there is missing data (``NaN``) in the environmental
        variables, or if the environmental variables cannot be scaled (e.g.,
        due to zero variance).

    See Also
    --------
    scipy.stats.spearmanr

    Notes
    -----
    See [1]_ for the original method reference (originally called BIO-ENV).
    The general algorithm and interface are similar to ``vegan::bioenv``,
    available in R's vegan package [2]_. This method can also be found in
    PRIMER-E [3]_ (originally called BIO-ENV, but is now called BEST).

    .. warning:: This method can take a *long* time to run if a large number of
       variables are specified, as all possible subsets are evaluated at each
       subset size.

    The variables are scaled before computing the Euclidean distance: each
    column is centered and then scaled by its standard deviation.

    References
    ----------
    .. [1] Clarke, K. R & Ainsworth, M. 1993. "A method of linking multivariate
       community structure to environmental variables". Marine Ecology Progress
       Series, 92, 205-219.

    .. [2] http://cran.r-project.org/web/packages/vegan/index.html

    .. [3] http://www.primer-e.com/primer.htm

    Examples
    --------
    Import the functionality we'll use in the following examples:

    >>> import pandas as pd
    >>> from skbio import DistanceMatrix
    >>> from skbio.stats.distance import bioenv

    Load a 4x4 community distance matrix:

    >>> dm = DistanceMatrix([[0.0, 0.5, 0.25, 0.75],
    ...                      [0.5, 0.0, 0.1, 0.42],
    ...                      [0.25, 0.1, 0.0, 0.33],
    ...                      [0.75, 0.42, 0.33, 0.0]],
    ...                     ['A', 'B', 'C', 'D'])

    Load a ``pandas.DataFrame`` with two environmental variables, pH and
    elevation:

    >>> df = pd.DataFrame([[7.0, 400],
    ...                    [8.0, 530],
    ...                    [7.5, 450],
    ...                    [8.5, 810]],
    ...                   index=['A','B','C','D'],
    ...                   columns=['pH', 'Elevation'])

    Note that the data frame is indexed with the same IDs (``'A'``, ``'B'``,
    ``'C'``, and ``'D'``) that are in the distance matrix. This is necessary in
    order to link the environmental variables (metadata) to each of the objects
    in the distance matrix. In this example, the IDs appear in the same order
    in both the distance matrix and data frame, but this is not necessary.

    Find the best subsets of environmental variables that are correlated with
    community distances:

    >>> bioenv(dm, df) # doctest: +NORMALIZE_WHITESPACE
                   size  correlation
    vars
    pH                1     0.771517
    pH, Elevation     2     0.714286

    We see that in this simple example, pH alone is maximally rank-correlated
    with the community distances (:math:`\rho=0.771517`).

     N/A N/A N/A isinstance distance_matrix DistanceMatrix N/A N/A N/A TypeError Must provide a DistanceMatrix as input. N/A N/A N/A isinstance data_frame N/A pd DataFrame N/A N/A N/A TypeError Must provide a pandas.DataFrame as input. N/A N/A columns None N/A N/A columns N/A N/A N/A N/A data_frame columns values tolist N/A N/A N/A len N/A set columns N/A len columns N/A N/A N/A ValueError Duplicate column names are not supported. N/A N/A N/A len columns 1 N/A N/A N/A ValueError Must provide at least one column. N/A column columns N/A N/A N/A column data_frame N/A N/A N/A ValueError N/A Column '%s' not in data frame. column N/A vars_df N/A N/A data_frame loc N/A N/A N/A distance_matrix ids columns N/A N/A N/A N/A N/A N/A N/A vars_df isnull any any N/A N/A N/A ValueError One or more IDs in the distance matrix are not in the data frame, or there is missing data in the data frame. N/A N/A N/A vars_df N/A N/A vars_df astype float N/A N/A N/A ValueError N/A N/A N/A TypeError All specified columns in the data frame must be numeric. N/A vars_array N/A N/A _scale vars_df values N/A dm_flat N/A N/A distance_matrix condensed_form N/A num_vars N/A len columns N/A var_idxs N/A N/A np arange num_vars N/A max_rhos N/A N/A np empty num_vars dtype N/A N/A vars object N/A size int N/A correlation float N/A subset_size N/A range 1 N/A num_vars 1 N/A N/A max_rho None N/A subset_idxs N/A combinations var_idxs subset_size N/A N/A vars_dm_flat N/A pdist N/A vars_array N/A N/A N/A subset_idxs metric euclidean N/A rho N/A N/A spearmanr dm_flat vars_dm_flat N/A 0 N/A N/A N/A max_rho None N/A rho N/A max_rho N/A 0 N/A N/A max_rho N/A rho subset_idxs N/A vars_label N/A N/A ,  join N/A N/A columns N/A i N/A i N/A max_rho N/A 1 N/A N/A max_rhos N/A N/A subset_size 1 N/A vars_label subset_size N/A max_rho N/A 0 N/A N/A N/A N/A pd DataFrame from_records max_rhos index vars N/A N/A experimental as_of 0.4.0 _scale N/A N/A df N/A N/A N/A Center and scale each column in a data frame.

    Each column is centered (by subtracting the mean) and then scaled by its
    standard deviation.

     N/A df N/A N/A df copy N/A df N/A N/A df mean N/A df N/A N/A df std N/A N/A N/A N/A N/A N/A N/A df isnull any any N/A N/A N/A ValueError Column(s) in the data frame could not be scaled, likely because the column(s) had no variance. N/A df N/A