BIOM Format

2.1.17 verified Mon Apr 27 auth: no python

The BIOM (Biological Observation Matrix) format is a standardized format for representing counts of observations (e.g., OTUs, genes) across samples. This Python library provides read/write support for BIOM files, including HDF5 and JSON backends. Current version: 2.1.17. Released as needed; maintained by the QIIME 2 and scikit-bio ecosystems.

pip install biom-format

Common errors

error 'h5py' is required to read HDF5 BIOM files ↓

cause biom-format installed without h5py dependency.

fix

pip install 'biom-format[hdf5]'

error ModuleNotFoundError: No module named 'biom' ↓

cause Package not installed or installed in wrong environment.

fix

pip install biom-format

error TypeError: __new__() got an unexpected keyword argument 'observation_metadata' ↓

cause Mixing old and new API; Table constructor signature changed in 2.0.

fix

Use positional args: Table(data, obs_ids, sample_ids) or keyword argument 'observation_ids' and 'sample_ids'.

error ValueError: cannot reshape array of size ... ↓

cause Data array does not match dimensions implied by sample IDs and observation IDs.

fix

Ensure len(obs_ids) * len(sample_ids) equals total number of elements in data array.

Warnings

gotcha HDF5 support requires `pip install 'biom-format[hdf5]'` or `conda install -c conda-forge biom-format h5py`. Without h5py, the library falls back to JSON format only, which is slower and may not support large files. ↓

fix Install the extra: pip install 'biom-format[hdf5]'

breaking The `from biom import load_table` function deprecated old function `biom.parse.parse_biom_table` and `biom.parse.parse_biom_table(open('file.biom'))` patterns. Using the old API may raise deprecation warnings or break. ↓

fix Use `from biom import load_table` and call `load_table('file.biom')`.

gotcha When filtering tables using `filter_observations` or `filter_samples`, in-place modification occurs by default. To avoid mutating the original table, pass `inplace=False`. ↓

fix Example: `filtered = table.filter_observations(lambda v, i, m: v.sum() > 10, inplace=False)`

deprecated Using the `biom` command-line interface outside of the package (i.e., calling `biom summarize-table`) is being phased out. Prefer Python API or use `qiime2` tools. ↓

fix Use `import biom` and methods on Table objects.

Install

pip install 'biom-format[hdf5]'

Imports

Table
wrong
```
from biom.table import Table
```
correct
```
from biom import Table
```
Table is a top-level export; direct submodule import may break in future versions.
load_table
```
from biom import load_table
```

Quickstart

Create, save, and load a BIOM table with minimal dependencies.

import numpy as np
from biom import Table, load_table

# Create a simple BIOM table
data = np.array([[1, 2], [3, 4]])
sample_ids = ['S1', 'S2']
obs_ids = ['O1', 'O2']
table = Table(data, obs_ids, sample_ids)
print(table.summary())

# Save to file
table.save('example.biom')

# Load back
loaded = load_table('example.biom')
print(loaded.shape)