{"id":7420,"library":"mmtf-python","title":"MMTF-Python","description":"MMTF-Python is a Python library for decoding, encoding, and working with the Macromolecular Transmission Format (MMTF), a binary encoding designed for efficient storage and transmission of biological structures. The current version is 1.1.3, released in July 2022. While the library is stable, the RCSB PDB no longer serves MMTF data by default, encouraging a switch to BinaryCIF (BCIF). Therefore, the project is considered to be in maintenance mode.","status":"maintenance","version":"1.1.3","language":"en","source_language":"en","source_url":"https://github.com/rcsb/mmtf-python.git","tags":["bioinformatics","PDB","MMTF","chemistry","structural biology","protein structure"],"install":[{"cmd":"pip install mmtf-python","lang":"bash","label":"PyPI"},{"cmd":"conda install -c conda-forge mmtf-python","lang":"bash","label":"Conda"}],"dependencies":[{"reason":"Required for efficient binary serialization and deserialization of MMTF data.","package":"msgpack","optional":false},{"reason":"Often used internally for handling numerical data arrays within decoded structures.","package":"numpy","optional":true}],"imports":[{"symbol":"fetch","correct":"from mmtf import fetch"},{"note":"MMTFDecoder is typically accessed via the mmtf.decoder submodule, though 'fetch' is the recommended entry point for common use cases.","wrong":"from mmtf import MMTFDecoder","symbol":"MMTFDecoder","correct":"from mmtf.decoder import MMTFDecoder"}],"quickstart":{"code":"from mmtf import fetch\n\n# Get the data for a PDB structure (e.g., 4CUP)\ndecoded_data = fetch(\"4CUP\")\n\nprint(f\"PDB Code: {decoded_data.structure_id} has {decoded_data.num_chains} chains\")\n\n# Show the charge information for the first group\nif decoded_data.group_list and decoded_data.group_list[0]:\n    group_name = decoded_data.group_list[0].get(\"groupName\", \"N/A\")\n    charges = decoded_data.group_list[0].get(\"formalChargeList\", [])\n    print(f\"Group name: {group_name} has the following atomic charges: {','.join(map(str, charges))}\")\n\n# Show how many bioassemblies it has\nprint(f\"PDB Code: {decoded_data.structure_id} has {len(decoded_data.bio_assembly)} bioassemblies\")","lang":"python","description":"This quickstart demonstrates how to fetch and access basic structural information from a PDB entry using the MMTF format. It retrieves the structure for PDB ID 4CUP and prints its code, number of chains, formal charges for the first group, and the count of bioassemblies."},"warnings":[{"fix":"Migrate data fetching mechanisms to use BinaryCIF (BCIF) format or obtain MMTF files from other archives. Consider libraries supporting BCIF for new data.","message":"RCSB PDB ceased serving MMTF data by default as of July 2, 2024. Users relying on direct downloads from RCSB PDB in MMTF format will need to switch to BinaryCIF (BCIF) or find alternative MMTF data sources.","severity":"breaking","affected_versions":"All versions, for data fetching directly from RCSB PDB"},{"fix":"Test thoroughly with your specific Python environment and dependency versions. Consider pinning dependency versions if issues arise.","message":"The `mmtf-python` library has not had major feature updates since its 1.1.3 release in July 2022. While functional, it may encounter compatibility issues with very recent Python versions (e.g., Python 3.10+) or newer versions of its dependencies.","severity":"gotcha","affected_versions":"1.1.3 and older"},{"fix":"Ensure all `print` statements are converted to `print()` functions and other Python 2 specific syntax is updated.","message":"When migrating code from Python 2 to Python 3, be aware of syntax changes, particularly `print` becoming a function (`print()`). Incorrect usage may lead to `SyntaxError` or `TypeError`.","severity":"gotcha","affected_versions":"Code originally written for Python 2"},{"fix":"Upgrade to version 1.0.10 or newer to benefit from the fix for file handle leaks.","message":"Older versions (prior to v1.0.10) had issues with leaking open file handles, which could lead to resource exhaustion in long-running applications or when processing many files.","severity":"gotcha","affected_versions":"< 1.0.10"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the library using `pip install mmtf-python` or `conda install -c conda-forge mmtf-python`.","cause":"The 'mmtf-python' library has not been installed or the Python environment where it's installed is not active.","error":"ModuleNotFoundError: No module named 'mmtf'"},{"fix":"Use the high-level `mmtf.fetch()` function for direct PDB ID retrieval, or correctly import and instantiate `MMTFDecoder` from `mmtf.decoder` if manual decoding is needed. Example: `from mmtf import fetch; data = fetch('1ABC')`.","cause":"Attempting to call `MMTFDecoder` directly as a function instead of importing and instantiating it, or more commonly, trying to call the `mmtf` module itself when meaning to use a function like `fetch`.","error":"TypeError: 'MMTFDecoder' object is not callable"},{"fix":"Consult the `mmtf-python` documentation or the MMTF specification for the correct attribute names available in the decoded structure. Common attributes include `structure_id`, `num_chains`, `bio_assembly`, `group_list`.","cause":"Attempting to access an attribute (e.g., `structure_id`, `num_chains`) that either doesn't exist or is misspelled on the `DecodedData` object returned by `fetch`.","error":"AttributeError: 'DecodedData' object has no attribute 'some_invalid_attribute'"},{"fix":"Use `.get(key, default_value)` when accessing dictionary keys to prevent `KeyError` if a key might be absent. Example: `group_name = decoded_data.group_list[0].get('groupName', 'Unknown')`.","cause":"Attempting to access a key within a dictionary-like structure (e.g., `group_list` elements) that is not present in the specific MMTF file's data.","error":"KeyError: 'some_missing_key'"},{"fix":"Ensure you are using `from mmtf import fetch`. If the error persists, check for any local files named 'mmtf.py' that might be shadowing the installed library. Verify the installed version against documentation.","cause":"This usually indicates that the 'fetch' function is not directly exposed at the top level of the 'mmtf' package, or there is a naming conflict/issue with the local environment.","error":"ImportError: cannot import name 'fetch' from 'mmtf'"}]}