bioc - Processing BioC, Brat, and PubTator with Python

2.1 · active · verified Thu Apr 16

bioc is a Python library designed for processing and manipulating data in BioC XML/JSON, Brat standoff, and PubTator formats. It provides an API that facilitates reading, writing, and working with these common bioinformatics text mining annotation formats. Currently at version 2.1, the library undergoes releases with a focus on supporting the latest Python versions and format specifications.

Common errors

```
AttributeError: module 'bioc' has no attribute 'dump'
```
cause Attempting to use `bioc.dump` or `bioc.load` directly in `bioc` versions 2.x or later.

fix For XML operations, use `from bioc import biocxml` and then call `biocxml.dump()` or `biocxml.load()`.
```
ModuleNotFoundError: No module named 'biocxml'
```
cause Trying to import `biocxml` directly as a top-level package or without `from bioc`.

fix The `biocxml` module is part of the `bioc` package. Use `from bioc import biocxml`.
```
SyntaxError: invalid syntax (when running on Python 2.x)
```
cause Running `bioc` code (especially versions 1.2.1+) with a Python 2 interpreter.

fix Upgrade your Python environment to Python 3.6 or higher. `bioc` no longer supports Python 2.

Warnings

breaking Direct top-level import of BioC XML functions (e.g., `bioc.dump`, `bioc.load`, `bioc.dumps`, `bioc.loads`) was removed in version 2.0. These functions are now part of the `biocxml` submodule.
Fix: Update imports from `import bioc` to `from bioc import biocxml` for XML operations, and then use `biocxml.dump()` or `biocxml.load()`.
breaking Python 2.x is no longer supported. Version 1.2.1 removed support for Python 2, and subsequent versions are Python 3.6+ only.
Fix: Ensure your project runs on Python 3.6 or newer. Upgrade your Python environment if necessary.
gotcha The PyPI project metadata still lists the 'Development Status' as '1 - Planning' (as of v2.1). This is misleading as the library has undergone multiple releases and is actively maintained for production use.
Fix: Disregard the 'Development Status' classifier on PyPI; the library is stable and actively developed.

Install

pip install bioc Install latest stable version

Imports

biocxml
wrong:
```
import bioc
```
correct:
```
from bioc import biocxml
```
In versions 2.x and later, BioC XML functionalities are moved under the `biocxml` submodule. Direct `import bioc` no longer exposes XML dump/load functions.
brat
```
from bioc import brat
```
pubtator
```
from bioc import pubtator
```
BioCCollection
wrong:
```
from bioc import BioCCollection
```
correct:
```
from bioc.bioc import BioCCollection
```
Core BioC data structures like `BioCCollection`, `BioCDocument`, etc., are typically accessed via `bioc.bioc` submodule.

Quickstart

This quickstart demonstrates how to create a basic BioC collection programmatically, add a document with a passage and an annotation, and then serialize it to a BioC XML string using `biocxml.dumps`. It also shows how to deserialize an XML string back into a BioC collection using `biocxml.loads`.

from bioc import biocxml, bioc

# Create a simple BioC Collection
collection = bioc.BioCCollection()
collection.date = '2023-01-01'
collection.source = 'Example'

document = bioc.BioCDocument()
document.id = '123'

passage = bioc.BioCPassage()
passage.offset = 0
passage.text = 'This is a test sentence.'

annotation = bioc.BioCAnnotation()
annotation.id = 'T1'
annotation.text = 'test sentence'
annotation.add_location(bioc.BioCLocation(offset=10, length=13))
passage.add_annotation(annotation)

document.add_passage(passage)
collection.add_document(document)

# Serialize to a BioC XML string
xml_string = biocxml.dumps(collection, pretty_print=True)
print('--- BioC XML ---')
print(xml_string)

# Deserialize from a BioC XML string
loaded_collection = biocxml.loads(xml_string)
print('\n--- Loaded Collection ID ---')
for doc in loaded_collection.documents:
    print(doc.id)

view raw JSON →