{"id":2999,"library":"mmcif","title":"mmCIF Core Access Library","description":"The `mmcif` Python library, current version 1.1.0, provides a comprehensive API for interacting with macromolecular Crystallographic Information File (mmCIF) and BinaryCIF data. Developed by the RCSB PDB, it includes native Python functionality and leverages pybind11 wrappers for accelerated I/O operations from a C++ core library. It is designed for reading, manipulating, and exporting structural biology data in mmCIF format and is actively maintained with updates.","status":"active","version":"1.1.0","language":"en","source_language":"en","source_url":"https://github.com/rcsb/py-mmcif","tags":["structural biology","mmCIF","PDB","crystallography","bioinformatics","chemistry"],"install":[{"cmd":"pip install mmcif","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"Primary class for reading and writing mmCIF/BinaryCIF data.","symbol":"MarshalUtil","correct":"from rcsb.utils.io.MarshalUtil import MarshalUtil"}],"quickstart":{"code":"import os\nfrom rcsb.utils.io.MarshalUtil import MarshalUtil\n\n# Create a MarshalUtil instance for I/O operations\nmU = MarshalUtil()\n\n# Define a public mmCIF file URL (e.g., from RCSB PDB)\nmmcif_url = \"https://files.rcsb.org/download/1ema.cif\"\n\n# Load data from the URL. The library can handle both local paths and URLs.\ndataContainerList = mU.load(mmcif_url, contentType=\"mmcif\")\n\nif dataContainerList:\n    # An mmCIF file can contain multiple data blocks; typically, we access the first one\n    dataContainer = dataContainerList[0]\n\n    print(f\"Data block ID: {dataContainer.getName()}\")\n\n    # Access a specific data category, e.g., '_entity'\n    entity_category = dataContainer.getObj(\"entity\")\n\n    if entity_category:\n        print(f\"\\nFound {entity_category.getRowCount()} entities:\")\n        for i in range(entity_category.getRowCount()):\n            pdbx_description = entity_category.getValue(\"pdbx_description\", i)\n            type_val = entity_category.getValue(\"type\", i)\n            print(f\"  - Entity {i+1}: Type='{type_val}', Description='{pdbx_description}'\")\n    else:\n        print(\"'_entity' category not found in the mmCIF file.\")\nelse:\n    print(f\"Failed to load data from {mmcif_url}. Please check the URL and network connection.\")","lang":"python","description":"This quickstart demonstrates how to read an mmCIF file from a URL, access its data blocks, and extract information from a specific category using the `MarshalUtil` class."},"warnings":[{"fix":"Always import from `rcsb.utils.io` and related submodules for `mmcif` (PyPI package) to ensure you are using the correct library's API.","message":"Multiple Python libraries exist for mmCIF parsing (e.g., `PDBeCIF`, `BioPython.PDB.MMCIFParser`, `mmcif-pdbx`, `python-modelcif`). Ensure you are explicitly using the `rcsb/py-mmcif` library (installed as `mmcif` via pip) as its API may differ from others.","severity":"gotcha","affected_versions":"All"},{"fix":"Pin your `mmcif` package version (`pip install mmcif==X.Y.Z`) and review the GitHub `HISTORY.txt` for `rcsb/py-mmcif` if encountering unexpected behavior, especially when working with BinaryCIF or migrating between older versions.","message":"The `rcsb/py-mmcif` project's internal versioning (e.g., `0.x.y` for GitHub commits) may not directly correspond to the PyPI `mmcif` package version. Historically, there have been updates to BinaryCIF handling (e.g., changing data item storage from tuples to lists) for compatibility, which could affect code relying on specific data types.","severity":"breaking","affected_versions":"<=0.84.0 (internal git versions before PyPI 1.1.0 equivalent)"},{"fix":"If migrating from `mmcif-pdbx`, consult the `rcsb/py-mmcif` documentation for equivalent API calls, as direct method name translations may not be possible.","message":"The `mmcif-pdbx` library, while related, notes that versions after `0.*` break API compatibility by renaming methods to conform to PEP8. While `rcsb/py-mmcif` is the canonical library, users migrating from `mmcif-pdbx` may encounter API differences.","severity":"deprecated","affected_versions":"All versions of `mmcif-pdbx` > 0.* (if migrating to `mmcif`)"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}