biom.table.Table.collapse — biom-format.org

# biom-format.org

## biom.table.Table.collapse

`Table.` `collapse`(f, collapse_f=None, norm=True, min_group_size=1, include_collapsed_metadata=True, one_to_many=False, one_to_many_mode='add', one_to_many_md_key='Path', strict=False, axis='sample')

  Collapse partitions in a table by metadata or by IDs

  Partition data by metadata or IDs and then collapse each partition into a single vector.

  If include_collapsed_metadata is `True`, the metadata for the collapsed partition will be a category named ‘collapsed_ids’, in which a list of the original ids that made up the partition is retained

  The remainder is only relevant to setting one_to_many to `True`.

  If one_to_many is `True`, allow vectors to collapse into multiple bins if the metadata describe a one-many relationship. Supplied functions must allow for iteration support over the metadata key and must return a tuple of (path, bin) as to describe both the path in the hierarchy represented and the specific bin being collapsed into. The uniqueness of the bin is _not_ based on the path but by the name of the bin.

  The metadata value for the corresponding collapsed column may include more (or less) information about the collapsed data. For example, if collapsing “FOO”, and there are vectors that span three associations A, B, and C, such that vector 1 spans A and B, vector 2 spans B and C and vector 3 spans A and C, the resulting table will contain three collapsed vectors:

  - A, containing original vectors 1 and 3
  - B, containing original vectors 1 and 2
  - C, containing original vectors 2 and 3

  If a vector maps to the same partition multiple times, it will be counted multiple times.

  There are two supported modes for handling one-to-many relationships via one_to_many_mode: `add` and divide. `add` will add the vector counts to each partition that the vector maps to, which may increase the total number of counts in the output table. `divide` will divide a vectors’s counts by the number of metadata that the vector has before adding the counts to each partition. This will not increase the total number of counts in the output table.

  If one_to_many_md_key is specified, that becomes the metadata key that describes the collapsed path. If a value is not specified, then it defaults to ‘Path’.

  If strict is specified, then all metadata pathways operated on must be indexable by metadata_f.

  one_to_many and norm are not supported together.

  one_to_many and collapse_f are not supported together.

  one_to_many and min_group_size are not supported together.

  A final note on space consumption. At present, the one_to_many functionality requires a temporary dense matrix representation.

  Parameters: | f : function Function that is used to determine what partition a vector belongs to collapse_f : function, optional Function that collapses a partition in a one-to-one collapse. The expected function signature is: dense or sparse_vector <- collapse_f(Table, axis) Defaults to a pairwise add. norm : bool, optional Defaults to `True`. If `True`, normalize the resulting table min_group_size : int, optional Defaults to `1`. The minimum size of a partition when performing a one-to-one collapse include_collapsed_metadata : bool, optional Defaults to `True`. If `True`, retain the collapsed metadata keyed by the original IDs of the associated vectors one_to_many : bool, optional Defaults to `False`. Perform a one-to-many collapse one_to_many_mode : {‘add’, ‘divide’}, optional The way to reduce two vectors in a one-to-many collapse one_to_many_md_key : str, optional Defaults to “Path”. If include_collapsed_metadata is `True`, store the original vector metadata under this key strict : bool, optional Defaults to `False`. Requires full pathway data within a one-to-many structure axis : {‘sample’, ‘observation’}, optional The axis to collapse
  Returns: | Table The collapsed table

  Examples

      >>> import numpy as np
      >>> from biom.table import Table

  Create a `Table`

      >>> dt_rich = Table(
      ...    np.array([[5, 6, 7], [8, 9, 10], [11, 12, 13]]),
      ...    ['1', '2', '3'], ['a', 'b', 'c'],
      ...    [{'taxonomy': ['k__a', 'p__b']},
      ...     {'taxonomy': ['k__a', 'p__c']},
      ...     {'taxonomy': ['k__a', 'p__c']}],
      ...    [{'barcode': 'aatt'},
      ...     {'barcode': 'ttgg'},
      ...     {'barcode': 'aatt'}])
      >>> print dt_rich
      # Constructed from biom file
      #OTU ID a   b   c
      1   5.0 6.0 7.0
      2   8.0 9.0 10.0
      3   11.0    12.0    13.0

  Create Function to determine what partition a vector belongs to

      >>> bin_f = lambda id_, x: x['taxonomy'][1]
      >>> obs_phy = dt_rich.collapse(
      ...    bin_f, norm=False, min_group_size=1,
      ...    axis='observation').sort(axis='observation')
      >>> print obs_phy
      # Constructed from biom file
      #OTU ID a   b   c
      p__b    5.0 6.0 7.0
      p__c    19.0    21.0    23.0