biom-format

library2.1.17pypypi✓ verified 85d ago

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.

data serialization

pip install biom-format

package ↗homepage ↗

INSTALL

IMPORT

SIG · BIOM-FORMAT

biom-format

datapythonv2.1.17

Install

12.3s avg

Import

971ms

Disk

369MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.17 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

build_error

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 12.3s · import 0.971s · 363MB

369MB installed

● package 369MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Table

✓ from biom import Table

✗ from biom.table import Table

Table is a top-level export; direct submodule import may break in future versions.

load_table

✓ from biom import load_table

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)

Debug

Known issues

gotchaHDF5 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]'

affects: >=2.1.0

breakingThe `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')`.

affects: <2.0 vs >=2.0

gotchaWhen 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)`

affects: all

deprecatedUsing 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.

affects: >=2.1.15

Errors

Common errors & fixes

'h5py' is required to read HDF5 BIOM files

biom-format installed without h5py dependency.

fix

pip install 'biom-format[hdf5]'

ModuleNotFoundError: No module named 'biom'

Package not installed or installed in wrong environment.

fix

pip install biom-format

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

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'.

ValueError: cannot reshape array of size ...

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.

Upgrade

Version history

2.1.17latest on PyPI · released Aug 26, 2025

Audit

Dependencies

h5pyoptionalHDF5 backend for BIOM files

numpyrequiredArray operations on observation/sample data

pandasrequiredDataFrame conversions and table operations

scipyoptionalSparse matrix support

Agent activity

20 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/biom-format/ ↗

homepagehttp://www.biom-format.org ↗