Fork me on GitHub"

# skbio.stats.power.paired_subsamples

`skbio.stats.power.``paired_subsamples`(meta, cat, control_cats, order=None, strict_match=True)

  Draws a list of samples varied by cat and matched for control_cats

  State: Experimental as of 0.4.0.

  This function is designed to provide controlled samples, based on a metadata category. For example, one could control for age, sex, education level, and diet type while measuring exercise frequency.

  Parameters:

  meta : pandas.DataFrame

  > The metadata associated with the samples.

  cat : str, list

  > The metadata category (or a list of categories) for comparison.

  control_cats : list

  > The metadata categories to be used as controls. For example, if you wanted to vary age (cat = “AGE”), you might want to control for gender and health status (i.e. control_cats = [“SEX”, “HEALTHY”])

  order : list, optional

  > The order of groups in the category. This can be used to limit the groups selected. For example, if there’s a category with groups ‘A’, ‘B’ and ‘C’, and you only want to look at A vs B, order would be set to [‘A’, ‘B’].

  strict_match: bool, optional

  > This determines how data is grouped using control_cats. If a sample within meta has an undefined value (NaN) for any of the columns in control_cats, the sample will not be considered as having a match and will be ignored when strict_match is True. If strict_match is False, missing values (NaN) in the control_cats can be considered matches.

  Returns:

  ids : array

  > a set of ids which satisfy the criteria. These are not grouped by cat. An empty array indicates there are no sample ids which satisfy the requirements.

  Examples

  If we have a mapping file for a set of random individuals looking at housing, sex, age and antibiotic use.

      >>> import pandas as pd
      >>> import numpy as np
      >>> meta = {'SW': {'HOUSING': '2', 'SEX': 'M', 'AGE': np.nan, 'ABX': 'Y'},
      ...         'TS': {'HOUSING': '2', 'SEX': 'M', 'AGE': '40s', 'ABX': 'Y'},
      ...         'CB': {'HOUSING': '3', 'SEX': 'M', 'AGE': '40s', 'ABX': 'Y'},
      ...         'BB': {'HOUSING': '1', 'SEX': 'M', 'AGE': '40s', 'ABX': 'Y'}}
      >>> meta = pd.DataFrame.from_dict(meta, orient="index")
      >>> meta
         ABX HOUSING  AGE SEX
      BB   Y       1  40s   M
      CB   Y       3  40s   M
      SW   Y       2  NaN   M
      TS   Y       2  40s   M

  We may want to vary an individual’s housing situation, while holding constant their age, sex and antibiotic use so we can estimate the effect size for housing, and later compare it to the effects of other variables.

      >>> from skbio.stats.power import paired_subsamples
      >>> ids = paired_subsamples(meta, 'HOUSING', ['SEX', 'AGE', 'ABX'])
      >>> np.hstack(ids)
      array(['BB', 'TS', 'CB']...)

  So, for this set of data, we can match TS, CB, and BB based on their age, sex, and antibiotic use. SW cannot be matched in either group because strict_match was true, and there is missing AGE data for this sample.