MMTF-Python

Common errors

• ModuleNotFoundError: No module named 'mmtf'

  cause The 'mmtf-python' library has not been installed or the Python environment where it's installed is not active.
  fix Install the library using `pip install mmtf-python` or `conda install -c conda-forge mmtf-python`.

• TypeError: 'MMTFDecoder' object is not callable

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

• AttributeError: 'DecodedData' object has no attribute 'some_invalid_attribute'

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

• KeyError: 'some_missing_key'

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

• ImportError: cannot import name 'fetch' from 'mmtf'

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

Warnings

• breaking 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.
  Fix: Migrate data fetching mechanisms to use BinaryCIF (BCIF) format or obtain MMTF files from other archives. Consider libraries supporting BCIF for new data.
• gotcha 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.
  Fix: Test thoroughly with your specific Python environment and dependency versions. Consider pinning dependency versions if issues arise.
• gotcha 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`.
  Fix: Ensure all `print` statements are converted to `print()` functions and other Python 2 specific syntax is updated.
• gotcha 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.
  Fix: Upgrade to version 1.0.10 or newer to benefit from the fix for file handle leaks.

Install

• pip install mmtf-python PyPI
• conda install -c conda-forge mmtf-python Conda

Imports

• fetch

  from mmtf import fetch

• MMTFDecoder
  wrong:

  from mmtf import MMTFDecoder

  correct:

  from mmtf.decoder import MMTFDecoder

  MMTFDecoder is typically accessed via the mmtf.decoder submodule, though 'fetch' is the recommended entry point for common use cases.

Quickstart

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.

from mmtf import fetch

# Get the data for a PDB structure (e.g., 4CUP)
decoded_data = fetch("4CUP")

print(f"PDB Code: {decoded_data.structure_id} has {decoded_data.num_chains} chains")

# Show the charge information for the first group
if decoded_data.group_list and decoded_data.group_list[0]:
    group_name = decoded_data.group_list[0].get("groupName", "N/A")
    charges = decoded_data.group_list[0].get("formalChargeList", [])
    print(f"Group name: {group_name} has the following atomic charges: {','.join(map(str, charges))}")

# Show how many bioassemblies it has
print(f"PDB Code: {decoded_data.structure_id} has {len(decoded_data.bio_assembly)} bioassemblies")