ModelCIF

1.7 verified Fri May 01 auth: no python

A Python package for handling ModelCIF mmCIF and BinaryCIF files, used for representing comparative protein structure models and their metadata. It builds on the ihm library and supports reading/writing ModelCIF dictionaries, including references, alignments, quality metrics, and protocol steps. Current version is 1.7, with a release cadence of approximately every 6 months. Requires Python >=3.6.

pip install modelcif

Common errors

error ImportError: cannot import name 'System' from 'modelcif' ↓

cause Attempting to import from a submodule that does not exist or wrong casing.

fix

Use 'from modelcif import System'.

error AttributeError: 'System' object has no attribute 'write' ↓

cause Using an older version of modelcif where write is not a method of System; it may be accessed via a different API.

fix

Ensure you have modelcif >=0.7 and use sys.write(filename).

error TypeError: __init__() got an unexpected keyword argument 'align_begin' ↓

cause Deprecated argument used with TargetReference in modelcif >=1.0.

fix

Remove align_begin and align_end; use the new reference sequence API.

Warnings

deprecated The 'align_begin' and 'align_end' arguments to TargetReference are deprecated since version 1.0. ↓

fix Use the new Sequence-based API; provide full database sequence and differences via insertion/deletion classes.

gotcha Writing files with waters requires the pdbx_poly_seq_scheme and pdbx_nonpoly_scheme tables; these are handled automatically since version 1.5, but older versions may lose water info. ↓

fix Upgrade to modelcif >=1.5 or manually populate the scheme tables.

gotcha The 'is_primary' attribute of TargetReference may not be correctly set when reading files that contain '_struct_ref' but no '_ma_target_ref_db_details' table prior to version 1.5. ↓

fix Upgrade to modelcif >=1.5 or ensure '_ma_target_ref_db_details' is present in input files.

Imports

System
wrong
```
from modelcif.system import System
```
correct
```
from modelcif import System
```
System is in top-level __init__.py, not a separate module.

Model

wrong

from modelcif import Model

correct

from modelcif.model import Model

Model class is in modelcif.model module.

TargetReference

wrong

from modelcif import TargetReference

correct

from modelcif.reference import TargetReference

TargetReference is in the reference submodule.

Quickstart

Create a minimal ModelCIF system with one model, write it to a mmCIF file, and read it back.

import modelcif
import modelcif.reader
import modelcif.model
import tempfile, os

# create a simple system
sys = modelcif.System("Example model")
# add a model
model = modelcif.model.Model(sys, "model_1")
# write to a temporary file
with tempfile.NamedTemporaryFile(suffix='.cif', delete=False) as f:
    fname = f.name
    sys.write(fname)
# read back
sys2 = modelcif.reader.read(fname)
print(len(sys2.models))
os.unlink(fname)