+environment:

+ # For Python versions available on Appveyor, see

+ # https://www.appveyor.com/docs/windows-images-software/#python

+ matrix:

+ - {APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2017, PYTHON: "C:\\Python36-x64"}

+ - {APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2019, PYTHON: "C:\\Python38"}

+ - {APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2019, PYTHON: "C:\\Python38-x64"}

+ - {APPVEYOR_BUILD_WORKER_IMAGE: Visual Studio 2019, PYTHON: "C:\\Python39-x64"}

+

+install:

+ - "SET PATH=%PYTHON%;%PYTHON%\\Scripts;%PATH%"

+ - "python.exe -m pip install codecov coverage nose"

+ - "python.exe -m pip install -r requirements.txt"

+

+build: off

+

+test_script:

+ - "nosetests --with-coverage --cover-branches"

+

+on_success:

+ - "codecov"

+ignore:

+ - test

+# For most projects, this workflow file will not need changing; you simply need

+# to commit it to your repository.

+#

+# You may wish to alter this file to override the set of languages analyzed,

+# or to provide custom queries or build logic.

+#

+# ******** NOTE ********

+# We have attempted to detect the languages in your repository. Please check

+# the `language` matrix defined below to confirm you have the correct set of

+# supported CodeQL languages.

+#

+name: "CodeQL"

+

+on:

+ push:

+ branches: [ main ]

+ pull_request:

+ # The branches below must be a subset of the branches above

+ branches: [ main ]

+ schedule:

+ - cron: '27 17 * * 5'

+

+jobs:

+ analyze:

+ name: Analyze

+ runs-on: ubuntu-latest

+ permissions:

+ actions: read

+ contents: read

+ security-events: write

+

+ strategy:

+ fail-fast: false

+ matrix:

+ language: [ 'python' ]

+ # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python' ]

+ # Learn more:

+ # https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#changing-the-languages-that-are-analyzed

+

+ steps:

+ - name: Checkout repository

+ uses: actions/checkout@v4

+

+ # Initializes the CodeQL tools for scanning.

+ - name: Initialize CodeQL

+ uses: github/codeql-action/init@v2

+ with:

+ languages: ${{ matrix.language }}

+ # If you wish to specify custom queries, you can do so here or in a config file.

+ # By default, queries listed here will override any specified in a config file.

+ # Prefix the list here with "+" to use these queries and those in the config file.

+ # queries: ./path/to/local/query, your-org/your-repo/queries@main

+

+ - name: Perform CodeQL Analysis

+ uses: github/codeql-action/analyze@v2

+name: Lint Code Base

+

+#

+# Documentation:

+# https://help.github.com/en/articles/workflow-syntax-for-github-actions

+#

+

+on: [push]

+

+jobs:

+ build:

+ name: Lint Code Base

+ runs-on: ubuntu-latest

+ steps:

+ - name: Checkout Code

+ uses: actions/checkout@v4

+ - name: Lint Code Base

+ uses: docker://github/super-linter:v2.1.0

+ env:

+ VALIDATE_ALL_CODEBASE: false

+ DEFAULT_BRANCH: main

+ VALIDATE_PYTHON: false

+ VALIDATE_BASH: true

+name: build

+

+on: [push, pull_request]

+

+jobs:

+ build:

+

+ strategy:

+ fail-fast: false

+ matrix:

+ os: [ubuntu-latest]

+ python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13']

+ include:

+ - os: macos-latest

+ python-version: '3.10'

+ runs-on: ${{ matrix.os }}

+

+ steps:

+ - uses: actions/checkout@v4

+ - name: Set up Python ${{ matrix.python-version }}

+ uses: actions/setup-python@v5

+ with:

+ python-version: ${{ matrix.python-version }}

+ - name: Install dependencies

+ run: |

+ python -m pip install --upgrade pip

+ pip install coverage pytest-cov flake8

+ pip install -r requirements.txt

+ - name: Test

+ run: |

+ pytest --cov=modelcif --cov-branch --cov-report=xml --cov-append -v .

+ flake8 --ignore E402,W503,W504

+ - uses: codecov/codecov-action@v4

+ env:

+ CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

+.DS_Store

+# vim swapfiles

+.*.swp

+

+# Byte-compiled / optimized / DLL files

+__pycache__/

+*.py[cod]

+*$py.class

+

+# C extensions

+*.so

+

+# Distribution / packaging

+.Python

+env/

+build/

+develop-eggs/

+dist/

+downloads/

+eggs/

+.eggs/

+lib/

+lib64/

+parts/

+sdist/

+var/

+wheels/

+*.egg-info/

+.installed.cfg

+*.egg

+

+# PyInstaller

+# Usually these files are written by a python script from a template

+# before PyInstaller builds the exe, so as to inject date/other infos into it.

+*.manifest

+

+# Installer logs

+pip-log.txt

+pip-delete-this-directory.txt

+

+# Unit test / coverage reports

+htmlcov/

+.tox/

+.coverage

+.coverage.*

+.cache

+nosetests.xml

+coverage.xml

+*.cover

+.hypothesis/

+

+# Translations

+*.mo

+*.pot

+

+# Django stuff:

+*.log

+local_settings.py

+

+# Flask stuff:

+instance/

+.webassets-cache

+

+# Scrapy stuff:

+.scrapy

+

+# Sphinx documentation

+docs/_build/

+

+# PyBuilder

+target/

+

+# Jupyter Notebook

+.ipynb_checkpoints

+

+# pyenv

+.python-version

+

+# celery beat schedule file

+celerybeat-schedule

+

+# SageMath parsed files

+*.sage.py

+

+# dotenv

+.env

+

+# virtualenv

+.venv

+venv/

+ENV/

+

+# Spyder project settings

+.spyderproject

+.spyproject

+

+# Rope project settings

+.ropeproject

+

+# mkdocs documentation

+/site

+

+# mypy

+.mypy_cache/

+.pytest_cache

+[MASTER]

+init-hook="from pylint.config import find_pylintrc; import os, sys; sys.path.append(os.path.dirname(find_pylintrc()))"

+# Read the Docs configuration file for Sphinx projects

+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

+

+# Required

+version: 2

+

+# Set the OS, Python version and other tools you might need

+build:

+ os: ubuntu-22.04

+ tools:

+ python: "3.11"

+ # You can also specify other tool versions:

+ # nodejs: "20"

+ # rust: "1.70"

+ # golang: "1.20"

+

+# Build documentation in the "docs/" directory with Sphinx

+sphinx:

+ configuration: docs/conf.py

+ # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs

+ # builder: "dirhtml"

+ # Fail on all warnings to avoid broken references

+ # fail_on_warning: true

+

+# Optionally build your docs in additional formats such as PDF and ePub

+# formats:

+# - pdf

+# - epub

+

+# Optional but recommended, declare the Python requirements required

+# to build your documentation

+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html

+python:

+ install:

+ - requirements: docs/requirements.txt

+cff-version: 1.2.0

+message: "If you use this software, please cite it as below."

+authors:

+- family-names: "Webb"

+ given-names: "Benjamin"

+title: "python-modelcif"

+url: "https://github.com/ihmwg/python-modelcif"

+preferred-citation:

+ type: article

+ authors:

+ - family-names: "Vallat"

+ given-names: "Brinda"

+ - family-names: "Tauriello"

+ given-names: "Gerardo"

+ - family-names: "Bienert"

+ given-names: "Stefan"

+ - family-names: "Haas"

+ given-names: "Juergen"

+ - family-names: "Webb"

+ given-names: "Benjamin M."

+ - family-names: "Žídek"

+ given-names: "Augustin"

+ - family-names: "Zheng"

+ given-names: "Wei"

+ - family-names: "Peisach"

+ given-names: "Ezra"

+ - family-names: "Piehl"

+ given-names: "Dennis W."

+ - family-names: "Anischanka"

+ given-names: "Ivan"

+ - family-names: "Sillitoe"

+ given-names: "Ian"

+ - family-names: "Tolchard"

+ given-names: "James"

+ - family-names: "Varadi"

+ given-names: "Mihaly"

+ - family-names: "Baker"

+ given-names: "David"

+ - family-names: "Orengo"

+ given-names: "Christine"

+ - family-names: "Zhang"

+ given-names: "Yang"

+ - family-names: "Hoch"

+ given-names: "Jeffrey C."

+ - family-names: "Kurisu"

+ given-names: "Genji"

+ - family-names: "Patwardhan"

+ given-names: "Ardan"

+ - family-names: "Velankar"

+ given-names: "Sameer"

+ - family-names: "Burley"

+ given-names: "Stephen K."

+ - family-names: "Sali"

+ given-names: "Andrej"

+ - family-names: "Schwede"

+ given-names: "Torsten"

+ - family-names: "Berman"

+ given-names: "Helen M."

+ - family-names: "Westbrook"

+ given-names: "John D."

+ doi: "10.1016/j.jmb.2023.168021"

+ journal: "J Mol Biol"

+ month: 7

+ start: 168021

+ title: "ModelCIF: An Extension of PDBx/mmCIF Data Representation for Computed Structure Models"

+ volume: 435

+ issue: 14

+ year: 2023

+1.5 - 2025-09-17

+================

+ - The ``pdbx_nonpoly_scheme`` and ``pdbx_poly_seq_scheme``

+ tables are now read from and written to mmCIF or BinaryCIF

+ files. This allows for files containing waters to be

+ correctly processed (#52).

+ - A ``pyproject.toml`` file is now provided for compatibility

+ with modern versions of pip (#50).

+ - Bugfix: the ``is_primary`` attribute of

+ :class:`modelcif.reference.TargetReference` is now correctly

+ set when reading files containing a ``_struct_ref`` table

+ but no ``_ma_target_ref_db_details`` table (#51).

+

+1.4 - 2025-06-11

+================

+ - Revision information and information on how the data in the file can

+ be used are now read from or written to mmCIF or BinaryCIF files.

+ See :attr:`System.revisions` and :attr:`System.data_usage` respectively.

+ - New classes have been added to :mod:`modelcif.alignment`,

+ :mod:`modelcif.qa_metric`, and :mod:`modelcif.protocol` to support

+ all sequence identity denominators (#47), QA metric types (#45),

+ and protocol step types (#44) respectively, as defined in the ModelCIF

+ dictionary.

+ - The new :class:`modelcif.alignment.Local` and

+ :class:`modelcif.alignment.Multiple` classes allow for both local

+ alignments and multiple sequence alignments to be described (#43).

+ - Bugfix: sequence identity and alignment score (``identity`` and ``score``

+ arguments to :class:`modelcif.alignment.Pair`) are now optional, to

+ match the mmCIF dictionary (#49).

+ - Bugfix: information in ``_ma_template_non_poly.details`` is now read

+ from mmCIF or BinaryCIF files (#48).

+ - Bugfix: files containing empty or missing ``_ma_qa_metric.description``

+ can now be read (#46).

+

+1.3 - 2025-01-14

+================

+ - The new :class:`modelcif.CustomTemplate` class allows for custom templates

+ (that have not been deposited in a database such as PDB) to be referenced,

+ together with their atomic coordinates (#1).

+ - Model quality scores can now be defined that act on single features or

+ pairs of features using the :class:`modelcif.qa_metric.Feature` and

+ :class:`modelcif.qa_metric.FeaturePairwise` classes, respectively.

+ Features can be defined as groups of atoms, residues, or asyms (#38).

+ - The :class:`modelcif.associated.QAMetricsFile` class should now be used

+ to reference files that contain model quality scores. The old name

+ (LocalPairwiseQAScoresFile) is deprecated. This allows for all types of

+ QA scores, not just local pairwise scores, to be stored in a separate file.

+ - Sanity checks when writing out a file can now be disabled if desired,

+ using the new ``check`` argument to :func:`modelcif.dumper.write`.

+ - :class:`modelcif.reference.TargetReference` now takes an ``is_primary``

+ argument which can be used to denote the most pertinent sequence

+ database reference.

+ - Information on model groups (:class:`modelcif.model.ModelGroup`) is now

+ written to the new ``ma_model_group`` and ``ma_model_group_link`` mmCIF

+ tables, instead of ``ma_model_list``, to match the latest ModelCIF

+ dictionary. Old-style information in ``ma_model_list`` will still be

+ used when reading a file if these new tables are missing.

+

+1.2 - 2024-10-23

+================

+ - Data that have been split over multiple mmCIF or BinaryCIF files can now

+ be combined into a single :class:`modelcif.System` object using the new

+ ``add_to_system`` argument to :func:`modelcif.reader.read` (#10).

+ - A new example, ``associated.py``, has been added to demonstrate reading

+ in data that has been split into multiple "associated" mmCIF files using

+ :class:`modelcif.associated.CIFFile`.

+

+1.1 - 2024-09-27

+================

+ - The new class :class:`modelcif.model.NotModeledResidueRange` allows for

+ the annotation of residue ranges that were explicitly not modeled.

+ Any residue marked as not-modeled in all models will be excluded from

+ the ``pdbx_poly_seq_scheme`` table.

+ - The ``util/make-mmcif.py`` script is now included in the installed package,

+ so can be run if desired with ``python3 -m modelcif.util.make_mmcif``.

+ - The ``make_mmcif`` utility script will now automatically add any

+ missing :class:`modelcif.model.NotModeledResidueRange` objects for

+ not-modeled residue ranges.

+

+1.0 - 2024-06-20

+================

+ - Reference information in the ``struct_ref`` mmCIF table is now supported

+ in addition to the ModelCIF-specific tables such as

+ ``ma_target_ref_db_details``. :class:`modelcif.reference.TargetReference`

+ now inherits from ``ihm.reference.Sequence`` and allows for the full

+ database sequence, plus any differences between it and the modeled sequence,

+ to be recorded. The ``align_begin`` and ``align_end`` arguments are now

+ deprecated (#34).

+

+0.9 - 2023-10-02

+================

+ - Bugfix: :class:`modelcif.SoftwareGroup` now allows for parameters to

+ be associated with each piece of software in the group, rather than

+ with the group as a whole (#33).

+

+0.8 - 2023-08-04

+================

+ - :class:`modelcif.associated.File` now takes an optional ``data``

+ argument to allow describing any modeling input/output that is stored

+ in that file.

+ - RPM packages are now provided for Fedora and RedHat Enterprise Linux.

+

+0.7 - 2023-01-25

+================

+ - More examples have been added to demonstrate interconversion between

+ mmCIF and BinaryCIF, and to validate mmCIF files.

+ - A utility script ``util/make-mmcif.py`` has been added which can add

+ minimal ModelCIF-related tables to an mmCIF file, to add in deposition.

+ - The reader is now more robust when handling files that are not ModelCIF

+ compliant (#31).

+ - The ``exptl`` table is no longer written to output mmCIF files, to conform

+ with wwPDB's recommendation. Instead, the

+ ``struct.pdbx_structure_determination_methodology`` data item denotes

+ that the model is computational (#29).

+

+0.6 - 2022-08-03

+================

+ - :class:`ihm.ChemComp` now allows for custom chemical components to be

+ defined in a chemical component dictionary (CCD) outside of the wwPDB CCD,

+ such as the ModelArchive CCD, or in the file itself using descriptors such

+ as SMILES or InChI in the :mod:`modelcif.descriptor` module.

+ - The ``ma_struct_assembly`` category is no longer written out to mmCIF

+ files, as this is deprecated by ModelCIF (all models are required to

+ have the same composition).

+ - Templates can now be described in AlphaFoldDB or PubChem using new

+ :class:`modelcif.reference.TemplateReference` subclasses.

+ - HHblits e-values can now be used as alignment scores, using

+ :class:`modelcif.alignment.HHblitsEValue`.

+ - Bugfix: :class:`modelcif.associated.CIFFile` now writes local files

+ (if requested via ``categories`` or ``copy_categories``) even if it

+ is placed inside a :class:`modelcif.associated.ZipFile` (#26).

+

+0.5 - 2022-05-10

+================

+ - A new class :class:`modelcif.ReferenceDatabase` allows describing

+ collections of sequences that were used as part of the modeling protocol.

+ - Lists of ints or floats can now be given as software parameters to the

+ :class:`modelcif.SoftwareParameter` class.

+

+0.4 - 2022-04-14

+================

+ - Sequence information for templates is now only written to template-specific

+ categories in the mmCIF/BinaryCIF, not to the entity, entity_poly etc.

+ tables, to properly comply with the ModelCIF dictionary.

+ - :class:`modelcif.Template` now takes a ``entity_id`` argument which can be

+ used to provide the entity ID (if known) of the template in its own mmCIF

+ file.

+ - External files (e.g. alignments, or quality scores) can now be referenced

+ from the main file (using the :mod:`modelcif.associated` module). Selected

+ CIF categories can automatically be written to these external files instead

+ of the main file, in either mmCIF or BinaryCIF format (see

+ :class:`modelcif.associated.CIFFile`).

+ - Non-polymer models can now be linked to their template using the

+ :class:`modelcif.NonPolymerFromTemplate` class.

+ - Add classes for the PLDDT, PTM, and IpTM quality metrics.

+ - :class:`modelcif.reference.TargetReference` now supports the version

+ and CRC64 checksum of the reference sequence.

+

+0.3 - 2022-03-21

+================

+ - Add a package to conda-forge so the library can be installed using

+ ``conda install -c conda-forge modelcif``

+ - :class:`modelcif.Template` now takes a ``strand_id`` argument which can

+ be used to provide the author-provided (e.g. PDB) chain ID.

+ - Non-polymers can now be used as templates.

+

+0.2 - 2022-01-27

+================

+ - Minor packaging and documentation improvements.

+ - Add a basic "theoretical model" exptl category to output files.

+ - Bugfix: fix output of alignments with an empty list of pairs.

+

+0.1 - 2022-01-26

+================

+ - First stable release. This provides support for single-chain single-template

+ models using the ModelCIF extension dictionary, and will read and

+ write mmCIF and BinaryCIF files that are compliant with the PDBx and

+ :class:`modelcif.alignment.HHblitsEValue`.

+MIT License

+

+Copyright (c) 2018-2025 IHM Working Group

+

+Permission is hereby granted, free of charge, to any person obtaining a copy

+of this software and associated documentation files (the "Software"), to deal

+in the Software without restriction, including without limitation the rights

+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

+copies of the Software, and to permit persons to whom the Software is

+furnished to do so, subject to the following conditions:

+

+The above copyright notice and this permission notice shall be included in all

+copies or substantial portions of the Software.

+

+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

+SOFTWARE.

+include ChangeLog.rst

+include LICENSE

+include examples/*.py

+[](https://doi.org/10.5281/zenodo.5908678)

+[](https://python-modelcif.readthedocs.org/)

+[](https://anaconda.org/conda-forge/modelcif)

+[](https://badge.fury.io/py/modelcif)

+[](https://github.com/ihmwg/python-modelcif/actions?query=workflow%3Abuild)

+[](https://ci.appveyor.com/project/benmwebb/python-modelcif)

+[](https://codecov.io/gh/ihmwg/python-modelcif)

+

+This is a Python package to assist in handling [mmCIF](http://mmcif.wwpdb.org/)

+and [BinaryCIF](https://github.com/molstar/BinaryCIF) files compliant with the

+[ModelCIF](https://mmcif.wwpdb.org/dictionaries/mmcif_ma.dic/Index/)

+extension. It works with Python 3.6 or later.

+

+Please [see the documentation](https://python-modelcif.readthedocs.org/) or some

+[worked examples](https://github.com/ihmwg/python-modelcif/tree/main/examples)

+for more details.

+

+# Installation with conda or pip

+

+If you are using [Anaconda Python](https://www.anaconda.com/), install with

+

+```

+conda install -c conda-forge modelcif

+```

+

+On a Fedora or RedHat Enterprise Linux box, install with

+

+```

+dnf copr enable salilab/salilab; dnf install python3-modelcif

+```

+

+Alternatively, install with pip:

+

+```

+pip install modelcif

+```

+

+# Installation from source code

+

+To build and install from a clone of the GitHub repository,

+first build and install version 2.6 or later of the

+[python-ihm](https://github.com/ihmwg/python-ihm) module. Then run:

+

+```

+python setup.py build

+python setup.py install

+```

+

+If you want to read or write [BinaryCIF](https://github.com/molstar/BinaryCIF)

+files, you will also need the

+Python [msgpack](https://github.com/msgpack/msgpack-python) package.

+

+# Testing

+

+There are a number of testcases in the `test` directory. Each one can be run

+like a normal Python script to test the library. They can also be all run at

+once using [nose](https://nose.readthedocs.io/en/latest/)

+or [pytest](https://docs.pytest.org/en/latest/).

+python-modelcif (1.5-1) unstable; urgency=medium

+

+ * Initial release. (Closes: #1109466)

+

+ [ Thorsten Alteholz ]

+ * d/copyright: docs/* directly assigned to Ben

+

+ -- Steffen Moeller <moeller@debian.org> Fri, 03 Oct 2025 16:07:11 +0100

+Source: python-modelcif

+#Testsuite: autopkgtest-pkg-python

+Standards-Version: 4.7.2

+Maintainer: Debian Med Packaging Team <debian-med-packaging@lists.alioth.debian.org>

+Uploaders:

+ Steffen Moeller <moeller@debian.org>,

+ Ben Webb <ben@salilab.org>,

+Section: science

+Priority: optional

+Build-Depends:

+ debhelper-compat (= 13),

+ dh-sequence-python3,

+ python3-setuptools,

+ python3-all,

+ python3-ihm,

+Vcs-Browser: https://salsa.debian.org/med-team/python-modelcif

+Vcs-Git: https://salsa.debian.org/med-team/python-modelcif.git

+Homepage: https://github.com/ihmwg/python-modelcif

+Rules-Requires-Root: no

+

+Package: python3-modelcif

+Section: python

+Architecture: all

+Depends:

+ ${python3:Depends},

+ ${misc:Depends},

+Description: handles mmCIF and BinaryCIF files with ModelCIF extension

+ The macromolecular Crystallographic Information File format is a standard

+ for the representation and description of large molecular structures like

+ proteins and/or nucleic acids.

+ .

+ This package provides a mechanism to describe the generation of a

+ theoretical model (for example, via comparative or homology model)

+ a set of Python objects. This includes, if applicable

+ * the templates(s) used for the modeling;

+ * the alignment between the template(s) and target sequence;

+ * the protocol used to generate models, such as template search,

+ modeling, and model selection;

+ * the actual coordinates of output models;

+ * grouping of multiple models;

+ * quality scores for models and/or alignments.

+ .

+ Once created, this set of Python objects can be written to an

+ mmCIF file that is compliant with the ModelCIF extension to the

+ PDBx/mmCIF dictionary, suitable for deposition in a repository such as

+ ModelArchive. The files can be viewed in any regular PDBx mmCIF viewer,

+ such as UCSF ChimeraX (although most viewers to date will only show

+ the model coordinates, not the ModelCIF-specific metadata).

+ .

+ This package leverages functionality provided by the python-ihm

+ package, which functions similarly, building a Python hierarchy

+ and then reading/writing mmCIF files. (However, python-ihm is used

+ for integrative models, and reads or writes files compliant with the

+ integrative/hybrid modeling extension dictionary.) In particular, many

+ python-ihm classes and modules are used in this library, for example

+ the ihm.Grant and ihm.Citation classes for handling grant or citation

+ information, or the ihm.dictionary module for validating files against

+ the mmCIF dictionary itself.

+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/

+Source: https://github.com/ihmwg/python-modelcif

+Upstream-Name: Python-ModelCIF

+Upstream-Contact: Ben Webb <ben@salilab.org>

+

+Files:

+ *

+Copyright:

+ 2018-2025 IHM Working Group

+License: Expat

+Comment: Ben Webb is listed as main author in setup.py, the license

+ file assigned the copyright to the IHM Working Group.

+

+Files:

+ docs/*

+Copyright:

+ 2021-2025 Ben Webb <ben@salilab.org>

+License: Expat

+Comment: Ben Webb is listed as copyright holder in docs/conf.py.

+

+Files:

+ debian/*

+Copyright:

+ 2025 Steffen Moeller <moeller@debian.org>

+License: Expat

+

+License: Expat

+ Permission is hereby granted, free of charge, to any person obtaining a copy

+ of this software and associated documentation files (the "Software"), to deal

+ in the Software without restriction, including without limitation the rights

+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

+ copies of the Software, and to permit persons to whom the Software is

+ furnished to do so, subject to the following conditions:

+ .

+ The above copyright notice and this permission notice shall be included in all

+ copies or substantial portions of the Software.

+ .

+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

+ SOFTWARE.

+#!/usr/bin/make -f

+

+export DH_VERBOSE = 1

+export PYBUILD_NAME=modelcif

+

+%:

+ dh $@ --buildsystem=pybuild

+# For more information on what jobs are run see:

+# https://salsa.debian.org/salsa-ci-team/pipeline

+#

+# To enable the jobs, go to your repository (at salsa.debian.org)

+# and click over Settings > CI/CD > Expand (in General pipelines).

+# In "CI/CD configuration file" write debian/salsa-ci.yml and click

+# in "Save Changes". The CI tests will run after the next commit.

+---

+include:

+ - https://salsa.debian.org/salsa-ci-team/pipeline/raw/master/recipes/debian.yml

+3.0 (quilt)

+extend-diff-ignore = "^[^/]*[.]egg-info/"

+# See https://wiki.debian.org/UpstreamMetadata for more info/fields.

+Bug-Database: https://github.com/ihwmg/python-modelcif/issues

+Bug-Submit: https://github.com/ihwmg/python-modelcif/issues/new

+Changelog: https://github.com/ihmwg/python-modelcif/blob/main/ChangeLog.rst

+Documentation: https://python-modelcif.readthedocs.io

+Repository-Browse: "https://github.com/ihmwg/python-modelcif"

+Repository: "https://github.com/ihmwg/python-modelcif.git"

+Registry:

+ - Name: bio.tools

+ Entry: modelcif

+ - Name: SciCrunch

+ Entry: SCR_027218

+ - Name: conda:conda-forge

+ Entry: modelcif

+Reference:

+ - Authors: Brinda Vallat and Gerardo Tauriello and Stefan Bienert and Juergen Haas and Benjamin M Webb and Augustin Žídek and Wei Zheng and Ezra Peisach and Dennis W Piehl and Ivan Anischanka and Ian Sillitoe and James Tolchard and Mihaly Varadi and David Baker and Christine Orengo and Yang Zhang and Jeffrey C Hoch and Genji Kurisu and Ardan Patwardhan and Sameer Velankar and Stephen K Burley and Andrej Sali and Torsten Schwede and Helen M Berman and John D Westbrook

+# - family-names: "Vallat"

+# given-names: "Brinda"

+# - family-names: "Tauriello"

+# given-names: "Gerardo"

+# - family-names: "Bienert"

+# given-names: "Stefan"

+# - family-names: "Haas"

+# given-names: "Juergen"

+# - family-names: "Webb"

+# given-names: "Benjamin M."

+# - family-names: "Žídek"

+# given-names: "Augustin"

+# - family-names: "Zheng"

+# given-names: "Wei"

+# - family-names: "Peisach"

+# given-names: "Ezra"

+# - family-names: "Piehl"

+# given-names: "Dennis W."

+# - family-names: "Anischanka"

+# given-names: "Ivan"

+# - family-names: "Sillitoe"

+# given-names: "Ian"

+# - family-names: "Tolchard"

+# given-names: "James"

+# - family-names: "Varadi"

+# given-names: "Mihaly"

+# - family-names: "Baker"

+# given-names: "David"

+# - family-names: "Orengo"

+# given-names: "Christine"

+# - family-names: "Zhang"

+# given-names: "Yang"

+# - family-names: "Hoch"

+# given-names: "Jeffrey C."

+# - family-names: "Kurisu"

+# given-names: "Genji"

+# - family-names: "Patwardhan"

+# given-names: "Ardan"

+# - family-names: "Velankar"

+# given-names: "Sameer"

+# - family-names: "Burley"

+# given-names: "Stephen K."

+# - family-names: "Sali"

+# given-names: "Andrej"

+# - family-names: "Schwede"

+# given-names: "Torsten"

+# - family-names: "Berman"

+# given-names: "Helen M."

+# - family-names: "Westbrook"

+# given-names: "John D."

+ DOI: "10.1016/j.jmb.2023.168021"

+ Journal: "J Mol Biol"

+ Month: 7

+ Start: 168021

+ Title: "ModelCIF: An Extension of PDBx/mmCIF Data Representation for Computed Structure Models"

+ Volume: 435

+ Issue: 14

+ Year: 2023

+ PMID: 36828268

+ URL: https://www.sciencedirect.com/science/article/pii/S0022283623000773?via%3Dihub

+version=4

+opts="filenamemangle=s%(?:.*?)?v?(@ANY_VERSION@@ARCHIVE_EXT@)%@PACKAGE@-$1%" \

+ https://github.com/ihmwg/python-modelcif/tags \

+ (?:.*?/)v?@ANY_VERSION@@ARCHIVE_EXT@

+# Minimal makefile for Sphinx documentation

+#

+

+# You can set these variables from the command line.

+SPHINXOPTS =

+SPHINXBUILD = sphinx-build

+SPHINXPROJ = Python-IHM

+SOURCEDIR = .

+BUILDDIR = _build

+

+# Put it first so that "make" without argument is like "make help".

+help:

+ @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

+

+.PHONY: help Makefile

+

+# Catch-all target: route all unknown targets to Sphinx using the new

+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).

+%: Makefile

+ @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file

+.. highlight:: rest

+

+.. _alignment_module:

+

+The :mod:`modelcif.alignment` Python module

+===========================================

+

+.. automodule:: modelcif.alignment

+

+.. autoclass:: Identity

+ :members:

+

+.. autoclass:: ShorterSequenceIdentity

+

+.. autoclass:: AlignedPositionsIdentity

+

+.. autoclass:: AlignedResiduePairsIdentity

+

+.. autoclass:: MeanSequenceIdentity

+

+.. autoclass:: Pair

+ :members:

+

+.. autoclass:: AlignmentMode

+ :members:

+

+.. autoclass:: Global

+ :members:

+

+.. autoclass:: Local

+ :members:

+

+.. autoclass:: AlignmentType

+ :members:

+

+.. autoclass:: Pairwise

+ :members:

+

+.. autoclass:: Multiple

+ :members:

+

+.. autoclass:: Score

+ :members:

+

+.. autoclass:: BLASTEValue

+ :members:

+

+.. autoclass:: HHblitsEValue

+ :members:

+.. highlight:: rest

+

+.. _associated_module:

+

+The :mod:`modelcif.associated` Python module

+============================================

+

+.. automodule:: modelcif.associated

+

+.. autoclass:: Repository

+ :members:

+

+.. autoclass:: File

+ :members:

+

+.. autoclass:: CIFFile

+ :members:

+

+.. autoclass:: QAMetricsFile

+ :members:

+

+.. autoclass:: ZipFile

+ :members:

+.. _changes:

+

+.. currentmodule:: modelcif

+

+Change history

+**************

+

+.. include:: ../ChangeLog.rst

+# -*- coding: utf-8 -*-

+#

+# Python-ModelCIF documentation build configuration file, created by

+# sphinx-quickstart on Thu Mar 1 14:05:33 2018.

+#

+# This file is execfile()d with the current directory set to its

+# containing dir.

+#

+# Note that not all possible configuration values are present in this

+# autogenerated file.

+#

+# All configuration values have a default; values that are commented out

+# serve to show the default.

+

+# If extensions (or modules to document with autodoc) are in another directory,

+# add these directories to sys.path here. If the directory is relative to the

+# documentation root, use os.path.abspath to make it absolute, like shown here.

+#

+import os

+import sys

+sys.path.insert(0, os.path.abspath('..'))

+

+

+# -- General configuration ------------------------------------------------

+

+# If your documentation needs a minimal Sphinx version, state it here.

+#

+# needs_sphinx = '1.0'

+

+# Add any Sphinx extension module names here, as strings. They can be

+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom

+# ones.

+extensions = ['sphinx.ext.autodoc',

+ 'sphinx.ext.viewcode',

+ 'sphinx.ext.intersphinx']

+

+# Link to IHM docs or Python standard library

+intersphinx_mapping = {'ihm': ('https://python-ihm.readthedocs.io/en/latest/',

+ None),

+ 'python': ('https://docs.python.org/3', None)}

+

+# Add any paths that contain templates here, relative to this directory.

+templates_path = ['_templates']

+

+# The suffix(es) of source filenames.

+# You can specify multiple suffix as a list of string:

+#

+# source_suffix = ['.rst', '.md']

+source_suffix = '.rst'

+

+# The master toctree document.

+master_doc = 'index'

+

+# General information about the project.

+project = u'Python-ModelCIF'

+copyright = u'2021-2025, Benjamin Webb'

+author = u'Benjamin Webb'

+

+# The version info for the project you're documenting, acts as replacement for

+# |version| and |release|, also used in various other places throughout the

+# built documents.

+#

+# The short X.Y version.

+version = u''

+# The full version, including alpha/beta/rc tags.

+release = u''

+

+# The language for content autogenerated by Sphinx. Refer to documentation

+# for a list of supported languages.

+#

+# This is also used if you do content translation via gettext catalogs.

+# Usually you set "language" from the command line for these cases.

+language = None

+

+# List of patterns, relative to source directory, that match files and

+# directories to ignore when looking for source files.

+# This patterns also effect to html_static_path and html_extra_path

+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

+

+# The name of the Pygments (syntax highlighting) style to use.

+pygments_style = 'sphinx'

+

+# If true, `todo` and `todoList` produce output, else they produce nothing.

+todo_include_todos = False

+

+

+# -- Options for HTML output ----------------------------------------------

+

+# The theme to use for HTML and HTML Help pages. See the documentation for

+# a list of builtin themes.

+#

+html_theme = 'default'

+

+# Theme options are theme-specific and customize the look and feel of a theme

+# further. For a list of options available for each theme, see the

+# documentation.

+#

+# html_theme_options = {}

+

+# Add any paths that contain custom static files (such as style sheets) here,

+# relative to this directory. They are copied after the builtin static files,

+# so a file named "default.css" will overwrite the builtin "default.css".

+html_static_path = ['_static']

+

+# Custom sidebar templates, must be a dictionary that maps document names

+# to template names.

+#

+html_sidebars = {}

+

+# -- Options for HTMLHelp output ------------------------------------------

+

+# Output file base name for HTML help builder.

+htmlhelp_basename = 'Python-ModelCIFdoc'

+

+

+# -- Options for LaTeX output ---------------------------------------------

+

+latex_elements = {

+ # The paper size ('letterpaper' or 'a4paper').

+ #

+ # 'papersize': 'letterpaper',

+

+ # The font size ('10pt', '11pt' or '12pt').

+ #

+ # 'pointsize': '10pt',

+

+ # Additional stuff for the LaTeX preamble.

+ #

+ # 'preamble': '',

+

+ # Latex figure (float) alignment

+ #

+ # 'figure_align': 'htbp',

+}

+

+# Grouping the document tree into LaTeX files. List of tuples

+# (source start file, target name, title,

+# author, documentclass [howto, manual, or own class]).

+latex_documents = [

+ (master_doc, 'Python-ModelCIF.tex', u'Python-ModelCIF Documentation',

+ u'Benjamin Webb', 'manual'),

+]

+

+

+# -- Options for manual page output ---------------------------------------

+

+# One entry per manual page. List of tuples

+# (source start file, name, description, authors, manual section).

+man_pages = [

+ (master_doc, 'python-ma', u'Python-ModelCIF Documentation',

+ [author], 1)

+]

+

+

+# -- Options for Texinfo output -------------------------------------------

+

+# Grouping the document tree into Texinfo files. List of tuples

+# (source start file, target name, title, author,

+# dir menu entry, description, category)

+texinfo_documents = [

+ (master_doc, 'Python-ModelCIF', u'Python-ModelCIF Documentation',

+ author, 'Python-ModelCIF', 'One line description of project.',

+ 'Miscellaneous'),

+]

+

+# Warn about broken links to classes, etc.

+nitpicky = True

+.. highlight:: rest

+

+.. _data_module:

+

+The :mod:`modelcif.data` Python module

+======================================

+

+.. automodule:: modelcif.data

+

+.. autoclass:: Data

+ :members:

+

+.. autoclass:: DataGroup

+ :members:

+.. highlight:: rest

+

+.. _descriptor_module:

+

+The :mod:`modelcif.descriptor` Python module

+============================================

+

+.. automodule:: modelcif.descriptor

+

+.. autoclass:: Descriptor

+ :members:

+

+.. autoclass:: CanonicalSMILES

+ :members:

+

+.. autoclass:: IsomericSMILES

+ :members:

+

+.. autoclass:: IUPACName

+ :members:

+

+.. autoclass:: InChI

+ :members:

+

+.. autoclass:: InChIKey

+ :members:

+

+.. autoclass:: PubChemCID

+ :members:

+.. highlight:: rest

+

+.. _dumper_module:

+

+The :mod:`modelcif.dumper` Python module

+========================================

+

+.. automodule:: modelcif.dumper

+

+.. autofunction:: write

+

+.. autoclass:: ModelCIFVariant

+Python-ModelCIF documentation

+=============================

+

+This is a Python package to assist in handling mmCIF files compliant

+with the ModelCIF extension.

+

+The documentation below documents the library API. For complete worked examples,

+see `the examples directory at GitHub <https://github.com/ihmwg/python-modelcif/tree/main/examples>`_.

+

+Contents

+========

+

+.. toctree::

+ :maxdepth: 2

+

+ introduction

+ usage

+ limitations

+ changes

+

+API Reference:

+

+.. toctree::

+ :maxdepth: 1

+

+ main

+ reference

+ alignment

+ data

+ protocol

+ model

+ qa_metric

+ associated

+ descriptor

+ dumper

+ reader

+

+

+Indices and tables

+==================

+

+* :ref:`genindex`

+* :ref:`modindex`

+* :ref:`search`

+Introduction

+************

+

+This package provides a mechanism to describe the generation of a

+theoretical model (for example, via comparative or homology model)

+a set of Python objects. This includes, if applicable

+

+ - the templates(s) used for the modeling;

+ - the alignment between the template(s) and target sequence;

+ - the protocol used to generate models, such as template search, modeling,

+ and model selection;

+ - the actual coordinates of output models;

+ - grouping of multiple models;

+ - quality scores for models and/or alignments.

+

+Once created, this set of Python objects can be written to an mmCIF file

+that is compliant with the

+`ModelCIF extension <https://github.com/ihmwg/ModelCIF>`_

+to the `PDBx/mmCIF dictionary <http://mmcif.wwpdb.org/>`_,

+suitable for deposition in a repository such as

+`ModelArchive <https://modelarchive.org/>`_. The files can be viewed in any

+regular PDBx mmCIF viewer, such as

+`UCSF ChimeraX <https://www.cgl.ucsf.edu/chimerax/>`_ (although most viewers

+to date will only show the model coordinates, not the ModelCIF-specific

+metadata).

+

+This package leverages functionality provided by the

+`python-ihm <https://github.com/ihmwg/python-ihm>`_ package, which functions

+similarly, building a Python hierarchy and then reading/writing mmCIF files.

+(However, python-ihm is used for integrative models, and reads or writes files

+compliant with the `integrative/hybrid modeling <https://mmcif.wwpdb.org/dictionaries/mmcif_ihm.dic/Index/>`_ extension dictionary.)

+In particular, many python-ihm classes and modules are used in this library,

+for example the :class:`ihm.Grant` and :class:`ihm.Citation` classes for

+handling grant or citation information, or the :mod:`ihm.dictionary` module

+for validating files against the mmCIF dictionary itself.

+.. _limitations:

+

+.. currentmodule:: modelcif

+

+Limitations

+***********

+

+By design the library maps the PDBx/ModelCIF data model to its own hierarchy

+of Python objects. This hierarchy does not cover every possible mmCIF

+category; thus, the library is not necessarily preserving of file contents

+(e.g. if a file is read in and then a new file is written out, categories or

+data items from the original file not understood by the library will be

+missing in the new file).

+

+In particular, many PDBx categories pertaining to experimentally-determined

+structures are ignored. Also, the following ModelCIF categories are currently

+not supported:

+

+ - ``ma_template_customized``

+ - ``ma_template_coord``

+ - ``ma_coevolution_seq_db_ref``

+ - ``ma_coevolution_msa``

+ - ``ma_coevolution_msa_details``

+ - ``ma_restraints``

+ - ``ma_distance_restraints``

+ - ``ma_angle_restraints``

+ - ``ma_dihedral_restraints``

+ - ``ma_restraints_group``

+ - ``ma_poly_template_library_details``

+ - ``ma_poly_template_library_list``

+ - ``ma_poly_template_library_components``

+

+Note that currently the library is only well-tested with single-chain

+homology models generated from a single template (such as those in the

+`ModBase database <https://modbase.compbio.ucsf.edu>`_).

+

+Please `open an issue <https://github.com/ihmwg/python-modelcif/issues>`_

+if library support is lacking.

+.. highlight:: rest

+

+.. _main_module:

+

+The :mod:`modelcif` Python module

+=================================

+

+.. automodule:: modelcif

+

+.. autoclass:: System

+ :members:

+

+.. autoclass:: Database

+ :members:

+

+.. autoclass:: Software

+ :members:

+

+.. autoclass:: SoftwareGroup

+ :members:

+

+.. autoclass:: SoftwareWithParameters

+ :members:

+

+.. autoclass:: SoftwareParameter

+ :members:

+

+.. autoclass:: Entity

+ :members:

+

+.. autoclass:: AsymUnit

+ :members:

+

+.. autoclass:: WaterAsymUnit

+ :members:

+

+.. autoclass:: NonPolymerFromTemplate

+ :members:

+

+.. autoclass:: Residue

+ :members:

+

+.. autoclass:: Assembly

+ :members:

+

+.. autoclass:: AsymUnitRange

+ :members:

+

+.. autoclass:: Transformation

+ :members:

+

+.. autoclass:: TemplateSegment

+ :members:

+

+.. autoclass:: Template

+ :members:

+

+.. autoclass:: CustomTemplate

+ :members:

+

+.. autoclass:: TemplateAtom

+ :members:

+

+.. autoclass:: ReferenceDatabase

+ :members:

+

+.. autoclass:: Feature

+ :members:

+

+.. autoclass:: AtomFeature

+ :members:

+

+.. autoclass:: PolyResidueFeature

+ :members:

+

+.. autoclass:: EntityInstanceFeature

+ :members:

+@ECHO OFF

+

+pushd %~dp0

+

+REM Command file for Sphinx documentation

+

+if "%SPHINXBUILD%" == "" (

+ set SPHINXBUILD=sphinx-build

+)

+set SOURCEDIR=.

+set BUILDDIR=_build

+set SPHINXPROJ=Python-IHM

+

+if "%1" == "" goto help

+

+%SPHINXBUILD% >NUL 2>NUL

+if errorlevel 9009 (

+ echo.

+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx

+ echo.installed, then set the SPHINXBUILD environment variable to point

+ echo.to the full path of the 'sphinx-build' executable. Alternatively you

+ echo.may add the Sphinx directory to PATH.

+ echo.

+ echo.If you don't have Sphinx installed, grab it from

+ echo.http://sphinx-doc.org/

+ exit /b 1

+)

+

+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%

+goto end

+

+:help

+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%

+

+:end

+popd

+.. highlight:: rest

+

+.. _model_module:

+

+The :mod:`modelcif.model` Python module

+=======================================

+

+.. automodule:: modelcif.model

+

+.. autoclass:: Atom

+ :members:

+

+.. autoclass:: Model

+ :members:

+

+.. autoclass:: HomologyModel

+

+.. autoclass:: AbInitioModel

+

+.. autoclass:: NotModeledResidueRange

+

+.. autoclass:: ModelGroup

+ :members:

+.. highlight:: rest

+

+.. _protocol_module:

+

+The :mod:`modelcif.protocol` Python module

+==========================================

+

+.. automodule:: modelcif.protocol

+

+.. autoclass:: Step

+ :members:

+

+.. autoclass:: TemplateSearchStep

+ :members:

+

+.. autoclass:: TemplateSelectionStep

+ :members:

+

+.. autoclass:: TargetTemplateAlignmentStep

+ :members:

+

+.. autoclass:: CoevolutionMSAStep

+ :members:

+

+.. autoclass:: ContactPredictionStep

+ :members:

+

+.. autoclass:: ModelingStep

+ :members:

+

+.. autoclass:: ModelSelectionStep

+ :members:

+

+.. autoclass:: ModelRefinementStep

+ :members:

+

+.. autoclass:: Protocol

+ :members:

+.. highlight:: rest

+

+.. _qa_metric_module:

+

+The :mod:`modelcif.qa_metric` Python module

+===========================================

+

+.. automodule:: modelcif.qa_metric

+

+.. autoclass:: MetricMode

+ :members:

+

+.. autoclass:: Global

+ :members:

+

+.. autoclass:: Local

+ :members:

+

+.. autoclass:: LocalPairwise

+ :members:

+

+.. autoclass:: Feature

+ :members:

+

+.. autoclass:: FeaturePairwise

+ :members:

+

+.. autoclass:: MetricType

+ :members:

+

+.. autoclass:: ZScore

+

+.. autoclass:: Energy

+

+.. autoclass:: Distance

+

+.. autoclass:: NormalizedScore

+

+.. autoclass:: PAE

+

+.. autoclass:: ContactProbability

+

+.. autoclass:: PLDDT

+

+.. autoclass:: PLDDT01

+

+.. autoclass:: PLDDTAllAtom

+

+.. autoclass:: PLDDTAllAtom01

+

+.. autoclass:: PLDDTToPolymer

+

+.. autoclass:: PTM

+

+.. autoclass:: IpTM

+

+.. autoclass:: Boolean

+.. highlight:: rest

+

+.. _reader_module:

+

+The :mod:`modelcif.reader` Python module

+========================================

+

+.. automodule:: modelcif.reader

+

+.. autofunction:: read

+

+.. autoclass:: ModelCIFVariant

+.. highlight:: rest

+

+.. _reference_module:

+

+The :mod:`modelcif.reference` Python module

+===========================================

+

+.. automodule:: modelcif.reference

+

+.. autoclass:: TargetReference

+ :members:

+

+.. autoclass:: UniProt

+

+.. autoclass:: Alignment

+ :members:

+

+.. autoclass:: SeqDif

+ :members:

+

+.. autoclass:: TemplateReference

+ :members:

+

+.. autoclass:: PDB

+

+.. autoclass:: AlphaFoldDB

+

+.. autoclass:: PubChem

+ihm >= 0.27

+Usage

+*****

+

+Usage of the library for output consists of first creating a hierarchy of

+Python objects that together describe the system, and then dumping that

+hierarchy to an mmCIF or BinaryCIF file.

+

+For complete worked examples, see the

+`ModBase example <https://github.com/ihmwg/python-ma/blob/main/examples/mkmodbase.py>`_

+or the

+`ligands example <https://github.com/ihmwg/python-modelcif/blob/main/examples/ligands.py>`_.

+

+The top level of the hierarchy is the :class:`modelcif.System`. All other

+objects are referenced from a System object (either directly or via another

+object that is referenced by the System).

+

+System architecture

+===================

+

+The architecture of the system is described with a number of classes:

+

+ - :class:`modelcif.Entity` describes each unique sequence (used in the target

+ model, in one or more templates, or both).

+ - :class:`modelcif.AsymUnit` describes each asymmetric unit (chain) in the

+ target model. For example, a homodimer would consist of two asymmetric

+ units, both pointing to the same entity, while a heterodimer contains

+ two entities.

+ - Similarly, :class:`modelcif.Template` describes a chain used as a template.

+ - :class:`modelcif.Assembly` groups asymmetric units, or parts of

+ them. Assemblies are used to describe which parts of the system were modeled.

+ - A variety of classes in the :mod:`modelcif.alignment` module can be used to

+ describe alignments between the target and one or more templates.

+

+Modeling protocol

+=================

+

+:class:`modelcif.protocol.Protocol` objects describe how models were generated

+from the input data. A protocol can consist of

+:class:`multiple steps <modelcif.protocol.Step>`, such as template search,

+alignment, modeling, and model selection. These objects also describe what

+was used as input and what was generated on output by each step, as one or more

+:class:`modelcif.data.Data` objects.

+

+Model coordinates

+=================

+

+:class:`modelcif.model.Model` objects give the actual coordinates of the final

+generated models. These point to the :class:`~modelcif.Assembly` of what was

+modeled. Quality scores can also be assigned to each model (see the

+:mod:`modelcif.qa_metric` module) or to individual residues or pairs

+of residues.

+

+Models can also be grouped together for any purpose using the

+:class:`modelcif.model.ModelGroup` class.

+

+Metadata

+========

+

+Metadata can also be added to the system, such as

+

+ - :attr:`modelcif.System.citations`: publication(s) that describe this modeling

+ or the methods used in it.

+ - :class:`modelcif.Software`: software packages used at any stage in the

+ modeling.

+ - :attr:`modelcif.System.grants`: funding support for the modeling.

+ - :class:`modelcif.reference.TemplateReference`: or

+ :class:`modelcif.reference.TargetReference`: information on a template

+ structure, or a target sequence.

+

+Residue numbering

+=================

+

+The library keeps track of several numbering schemes to reflect the reality

+of the data used in modeling:

+

+ - *Internal numbering*. Residues are always numbered sequentially starting at

+ 1 in an :class:`~modelcif.Entity`. All references to residues or residue

+ ranges in the library use this numbering.

+ - *Author-provided numbering*. If a different numbering scheme is used by the

+ authors, for example to correspond to the numbering of the original sequence

+ that is modeled, this can be given as an author-provided numbering for

+ one or more asymmetric units. See the ``auth_seq_id_map`` parameter to

+ :class:`~modelcif.AsymUnit`. (The mapping between author-provided and

+ internal numbering is given in the ``pdbx_poly_seq_scheme`` table in

+ the mmCIF file.)

+

+Output

+======

+

+Once the hierarchy of classes is complete, it can be freely inspected or

+modified. All the classes are simple lightweight Python objects, generally

+with the relevant data available as member variables.

+

+The complete hierarchy can be written out to an mmCIF or BinaryCIF file using

+the :func:`modelcif.dumper.write` function.

+

+Input

+=====

+

+Hierarchies of classes can also be read from mmCIF or BinaryCIF files.

+This is done using the :func:`modelcif.reader.read` function, which returns

+a list of :class:`modelcif.System` objects.

+

+Format conversion

+=================

+

+The library can be employed to easily convert a ModelCIF file between mmCIF

+and BinaryCIF format by simply reading in one format and then writing in

+another. See the

+`convert_bcif example <https://github.com/ihmwg/python-modelcif/blob/main/examples/convert_bcif.py>`_.

+

+Conversion from legacy PDB format to mmCIF or BinaryCIF is not generally

+possible because PDB format has no defined standard for including information

+about modeling protocols, alignments, and so on. This extra information must be

+deduced from other sources, for example custom PDB REMARK records or separate

+files, and provided to the library. For reference, a script that uses the

+library to convert `ModBase <https://modbase.compbio.ucsf.edu/>`_ models from

+PDB format to mmCIF can be

+`seen here <https://github.com/salilab/modbase_utils/blob/main/modbase_pdb_to_cif.py>`_.

+

+Validation

+==========

+

+The library is designed to generate files that are consistent with the

+`PDBx <https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v50.dic/Index/>`_

+and `ModelCIF <https://mmcif.wwpdb.org/dictionaries/mmcif_ma.dic/Index/>`_

+dictionaries by construction. However, the library can also be used to validate

+ModelCIF (or other mmCIF/BinaryCIF files) if desired; see the

+`validator example <https://github.com/ihmwg/python-modelcif/blob/main/examples/validate_mmcif.py>`_.

+These examples demonstrate some of the functionality of the python-modelcif

+software. See [the documentation](https://python-modelcif.readthedocs.io/)

+for more information.

+

+ - [convert\_bcif.py](convert_bcif.py) converts an mmCIF file containing

+ ModelCIF data to [BinaryCIF](https://github.com/molstar/BinaryCIF) format.

+ - [ligands.py](ligands.py) demonstrates writing an mmCIF file of a typical

+ single-template homology or comparative model, including a ligand.

+ - [mkmodbase.py](mkmodbase.py) demonstrates using the library to make an mmCIF

+ file of a typical single-template single-chain homology or comparative

+ model, similar to those generated by

+ [MODELLER](https://salilab.org/modeller/) and deposited in the

+ [ModBase database](https://modbase.compbio.ucsf.edu/).

+ - [associated.py](associated.py) demonstrates reading a deposition from

+ [ModelArchive](https://www.modelarchive.org/) that has been split into

+ multiple mmCIF files.

+ - [validate\_mmcif.py](validate_mmcif.py) demonstrates the use of the

+ library's validator to validate a user-provided input mmCIF file against the

+ [ModelCIF dictionary](https://mmcif.wwpdb.org/dictionaries/mmcif_ma.dic/Index/).

+ - [validate\_modbase.py](validate_modbase.py) demonstrates downloading an

+ mmCIF structure from the [ModBase database](https://modbase.compbio.ucsf.edu/)

+ and validating it against the

+ [ModelCIF dictionary](https://mmcif.wwpdb.org/dictionaries/mmcif_ma.dic/Index/)

+ for compliance.

+# This example demonstrates reading ModelCIF "associated" files.

+# Some repositories, such as ModelArchive, split the deposited data into

+# multiple mmCIF files, putting some of the quality score information not

+# into the main mmCIF file but into a separate "associated" file.

+# These associated files are referenced in the main file

+# (see System.repositories) so we can programmatically download and

+# extract them.

+# This example requires Python 3.

+

+import urllib.request

+import zipfile

+import tempfile

+import shutil

+import modelcif.reader

+

+

+# Get any associated files containing pairwise QA scores

+def _get_zip_scores_files(s):

+ for repo in s.repositories:

+ for f in repo.files:

+ if isinstance(f, modelcif.associated.ZipFile):

+ for zf in f.files:

+ if isinstance(

+ zf, modelcif.associated.QAMetricsFile):

+ yield zf, f, repo

+

+

+# Download entry ma-bak-cepc-0944 directly from ModelArchive

+url = "https://www.modelarchive.org/doi/10.5452/ma-bak-cepc-0944.cif"

+with urllib.request.urlopen(url) as fh:

+ s, = modelcif.reader.read(fh)

+

+

+# Get any referenced associated files containing QA scores. For ModelArchive,

+# these are stored in an mmCIF file that is then compressed into a zip file

+for scores, archive, repo in _get_zip_scores_files(s):

+ url = repo.get_url(archive)

+ # Download the referenced zip file directly from ModelArchive

+ with urllib.request.urlopen(repo.get_url(archive)) as f_url:

+ with tempfile.NamedTemporaryFile() as f_zip:

+ shutil.copyfileobj(f_url, f_zip)

+ # Extract the scores file from the zip file

+ with zipfile.ZipFile(f_zip) as zf:

+ with zf.open(scores.path) as f_scores:

+ # Add scores in the file to our existing System

+ modelcif.reader.read(f_scores, add_to_system=s)

+

+for mg in s.model_groups:

+ for m in mg:

+ print("Model %s contains %d QA metrics" % (m, len(m.qa_metrics)))

+# This example demonstrates using the library to convert an mmCIF file

+# containing ModelCIF data to BinaryCIF format.

+

+# Import used classes.

+import modelcif

+import modelcif.dumper

+import modelcif.reader

+

+# Read in an existing mmCIF file:

+with open('input/ligands.cif') as fh:

+ systems = modelcif.reader.read(fh, format='mmCIF')

+

+# Write a new BinaryCIF file containing the same data:

+with open('ligands.bcif', 'wb') as fh:

+ modelcif.dumper.write(fh, systems, format='BCIF')

+data_model

+_entry.id model

+_struct.entry_id model

+_struct.pdbx_model_details .

+_struct.pdbx_structure_determination_methodology computational

+_struct.title 'Ligand example'

+_audit_conform.dict_location https://raw.githubusercontent.com/ihmwg/ModelCIF/557bda7/base/mmcif_ma-core.dic

+_audit_conform.dict_name mmcif_ma.dic

+_audit_conform.dict_version 1.4.1

+#

+loop_

+_chem_comp.id

+_chem_comp.type

+_chem_comp.name

+_chem_comp.formula

+_chem_comp.formula_weight

+_chem_comp.ma_provenance

+ALA 'L-peptide linking' ALANINE 'C3 H7 N O2' 89.094 'CCD Core'

+ASN 'L-peptide linking' ASPARAGINE 'C4 H8 N2 O3' 132.119 'CCD Core'

+ASP 'L-peptide linking' 'ASPARTIC ACID' 'C4 H7 N O4' 133.103 'CCD Core'

+CYS 'L-peptide linking' CYSTEINE 'C3 H7 N O2 S' 121.154 'CCD Core'

+ILE 'L-peptide linking' ISOLEUCINE 'C6 H13 N O2' 131.175 'CCD Core'

+LYS 'L-peptide linking' LYSINE 'C6 H15 N2 O2 1' 147.198 'CCD Core'

+PHE 'L-peptide linking' PHENYLALANINE 'C9 H11 N O2' 165.192 'CCD Core'

+SER 'L-peptide linking' SERINE 'C3 H7 N O3' 105.093 'CCD Core'

+SF4 non-polymer 'IRON/SULFUR CLUSTER' 'Fe4 S4' 351.620 'CCD Core'

+THR 'L-peptide linking' THREONINE 'C4 H9 N O3' 119.120 'CCD Core'

+TYR 'L-peptide linking' TYROSINE 'C9 H11 N O3' 181.191 'CCD Core'

+VAL 'L-peptide linking' VALINE 'C5 H11 N O2' 117.148 'CCD Core'

+#

+#

+loop_

+_entity.id

+_entity.type

+_entity.src_method

+_entity.pdbx_description

+_entity.formula_weight

+_entity.pdbx_number_of_molecules

+_entity.details

+1 polymer man 'Model subunit' 1230.346 1 .

+2 non-polymer man 'IRON/SULFUR CLUSTER' 351.620 1 .

+#

+#

+loop_

+_entity_poly.entity_id

+_entity_poly.type

+_entity_poly.nstd_linkage

+_entity_poly.nstd_monomer

+_entity_poly.pdbx_strand_id

+_entity_poly.pdbx_seq_one_letter_code

+_entity_poly.pdbx_seq_one_letter_code_can

+1 polypeptide(L) no no A AYVINDSCIA AYVINDSCIA

+#

+#

+loop_

+_pdbx_entity_nonpoly.entity_id

+_pdbx_entity_nonpoly.name

+_pdbx_entity_nonpoly.comp_id

+_pdbx_entity_nonpoly.ma_model_mode

+2 'IRON/SULFUR CLUSTER' SF4 implicit

+#

+#

+loop_

+_entity_poly_seq.entity_id

+_entity_poly_seq.num

+_entity_poly_seq.mon_id

+_entity_poly_seq.hetero

+1 1 ALA .

+1 2 TYR .

+1 3 VAL .

+1 4 ILE .

+1 5 ASN .

+1 6 ASP .

+1 7 SER .

+1 8 CYS .

+1 9 ILE .

+1 10 ALA .

+#

+#

+loop_

+_struct_asym.id

+_struct_asym.entity_id

+_struct_asym.details

+A 1 'Model subunit A'

+B 2 'Model subunit B'

+#

+#

+loop_

+_pdbx_poly_seq_scheme.asym_id

+_pdbx_poly_seq_scheme.entity_id

+_pdbx_poly_seq_scheme.seq_id

+_pdbx_poly_seq_scheme.mon_id

+_pdbx_poly_seq_scheme.pdb_seq_num

+_pdbx_poly_seq_scheme.auth_seq_num

+_pdbx_poly_seq_scheme.pdb_mon_id

+_pdbx_poly_seq_scheme.auth_mon_id

+_pdbx_poly_seq_scheme.pdb_strand_id

+_pdbx_poly_seq_scheme.pdb_ins_code

+A 1 1 ALA 1 1 ALA ALA A .

+A 1 2 TYR 2 2 TYR TYR A .

+A 1 3 VAL 3 3 VAL VAL A .

+A 1 4 ILE 4 4 ILE ILE A .

+A 1 5 ASN 5 5 ASN ASN A .

+A 1 6 ASP 6 6 ASP ASP A .

+A 1 7 SER 7 7 SER SER A .

+A 1 8 CYS 8 8 CYS CYS A .

+A 1 9 ILE 9 9 ILE ILE A .

+A 1 10 ALA 10 10 ALA ALA A .

+#

+#

+loop_

+_pdbx_nonpoly_scheme.asym_id

+_pdbx_nonpoly_scheme.entity_id

+_pdbx_nonpoly_scheme.mon_id

+_pdbx_nonpoly_scheme.ndb_seq_num

+_pdbx_nonpoly_scheme.pdb_seq_num

+_pdbx_nonpoly_scheme.auth_seq_num

+_pdbx_nonpoly_scheme.auth_mon_id

+_pdbx_nonpoly_scheme.pdb_strand_id

+_pdbx_nonpoly_scheme.pdb_ins_code

+B 2 SF4 1 1 1 SF4 B .

+#

+#

+loop_

+_ma_data.id

+_ma_data.name

+_ma_data.content_type

+_ma_data.content_type_other_details

+1 'Template polymer' 'template structure' .

+2 'Template ligand' 'template structure' .

+3 'Model subunit' target .

+4 'IRON/SULFUR CLUSTER' target .

+5 'Modeling alignment' 'target-template alignment' .

+6 'Best scoring model' 'model coordinates' .

+#

+#

+loop_

+_ma_data_group.ordinal_id

+_ma_data_group.group_id

+_ma_data_group.data_id

+1 1 5

+2 2 6

+#

+#

+loop_

+_ma_target_entity.entity_id

+_ma_target_entity.data_id

+_ma_target_entity.origin

+1 3 designed

+2 4 designed

+#

+#

+loop_

+_ma_target_entity_instance.asym_id

+_ma_target_entity_instance.entity_id

+_ma_target_entity_instance.details

+A 1 'Model subunit A'

+B 2 'Model subunit B'

+#

+#

+loop_

+_ma_template_trans_matrix.id

+_ma_template_trans_matrix.rot_matrix[1][1]

+_ma_template_trans_matrix.rot_matrix[2][1]

+_ma_template_trans_matrix.rot_matrix[3][1]

+_ma_template_trans_matrix.rot_matrix[1][2]

+_ma_template_trans_matrix.rot_matrix[2][2]

+_ma_template_trans_matrix.rot_matrix[3][2]

+_ma_template_trans_matrix.rot_matrix[1][3]

+_ma_template_trans_matrix.rot_matrix[2][3]

+_ma_template_trans_matrix.rot_matrix[3][3]

+_ma_template_trans_matrix.tr_vector[1]

+_ma_template_trans_matrix.tr_vector[2]

+_ma_template_trans_matrix.tr_vector[3]

+1 1.000000 0.000000 0.000000 0.000000 1.000000 0.000000 0.000000 0.000000

+1.000000 0 0 0

+#

+#

+loop_

+_ma_template_details.ordinal_id

+_ma_template_details.template_id

+_ma_template_details.template_origin

+_ma_template_details.template_entity_type

+_ma_template_details.template_trans_matrix_id

+_ma_template_details.template_data_id

+_ma_template_details.target_asym_id

+_ma_template_details.template_label_asym_id

+_ma_template_details.template_label_entity_id

+_ma_template_details.template_model_num

+_ma_template_details.template_auth_asym_id

+1 1 'reference database' polymer 1 1 A A . 1 A

+2 2 'reference database' non-polymer 1 2 B B . 1 B

+#

+#

+loop_

+_ma_template_poly.template_id

+_ma_template_poly.seq_one_letter_code

+_ma_template_poly.seq_one_letter_code_can

+1 AFVVTDNCIKCK AFVVTDNCIKCK

+#

+#

+loop_

+_ma_template_poly_segment.id

+_ma_template_poly_segment.template_id

+_ma_template_poly_segment.residue_number_begin

+_ma_template_poly_segment.residue_number_end

+1 1 1 12

+#

+#

+loop_

+_ma_template_non_poly.template_id

+_ma_template_non_poly.comp_id

+_ma_template_non_poly.details

+2 SF4 'IRON/SULFUR CLUSTER'

+#

+#

+loop_

+_ma_template_ref_db_details.template_id

+_ma_template_ref_db_details.db_name

+_ma_template_ref_db_details.db_name_other_details

+_ma_template_ref_db_details.db_accession_code

+_ma_template_ref_db_details.db_version_date

+1 PDB . 5fd1 .

+2 PDB . 5fd1 .

+#

+#

+loop_

+_ma_target_template_poly_mapping.id

+_ma_target_template_poly_mapping.template_segment_id

+_ma_target_template_poly_mapping.target_asym_id

+_ma_target_template_poly_mapping.target_seq_id_begin

+_ma_target_template_poly_mapping.target_seq_id_end

+1 1 A 1 10

+#

+#

+loop_

+_ma_alignment_info.alignment_id

+_ma_alignment_info.data_id

+_ma_alignment_info.software_group_id

+_ma_alignment_info.alignment_length

+_ma_alignment_info.alignment_type

+_ma_alignment_info.alignment_mode

+1 5 . 12 'target-template pairwise alignment' global

+#

+#

+loop_

+_ma_alignment_details.ordinal_id

+_ma_alignment_details.alignment_id

+_ma_alignment_details.template_segment_id

+_ma_alignment_details.target_asym_id

+_ma_alignment_details.score_type

+_ma_alignment_details.score_type_other_details

+_ma_alignment_details.score_value

+_ma_alignment_details.percent_sequence_identity

+_ma_alignment_details.sequence_identity_denominator

+_ma_alignment_details.sequence_identity_denominator_other_details

+1 1 1 A 'BLAST e-value' . 1e-15 45.000 'Length of the shorter sequence' .

+#

+#

+loop_

+_ma_alignment.ordinal_id

+_ma_alignment.alignment_id

+_ma_alignment.target_template_flag

+_ma_alignment.sequence

+1 1 1 AYVINDSC--IA

+2 1 2 AFVVTDNCIKCK

+#

+#

+loop_

+_ma_protocol_step.ordinal_id

+_ma_protocol_step.protocol_id

+_ma_protocol_step.step_id

+_ma_protocol_step.method_type

+_ma_protocol_step.step_name

+_ma_protocol_step.details

+_ma_protocol_step.software_group_id

+_ma_protocol_step.input_data_group_id

+_ma_protocol_step.output_data_group_id

+1 1 1 modeling . . . 1 2

+#

+#

+loop_

+_ma_model_list.ordinal_id

+_ma_model_list.model_id

+_ma_model_list.model_group_id

+_ma_model_list.model_name

+_ma_model_list.model_group_name

+_ma_model_list.data_id

+_ma_model_list.model_type

+_ma_model_list.model_type_other_details

+1 1 1 'Best scoring model' 'All models' 6 'Homology model' .

+#

+#

+loop_

+_atom_site.group_PDB

+_atom_site.id

+_atom_site.type_symbol

+_atom_site.label_atom_id

+_atom_site.label_alt_id

+_atom_site.label_comp_id

+_atom_site.label_seq_id

+_atom_site.auth_seq_id

+_atom_site.pdbx_PDB_ins_code

+_atom_site.label_asym_id

+_atom_site.Cartn_x

+_atom_site.Cartn_y

+_atom_site.Cartn_z

+_atom_site.occupancy

+_atom_site.label_entity_id

+_atom_site.auth_asym_id

+_atom_site.B_iso_or_equiv

+_atom_site.pdbx_PDB_model_num

+ATOM 1 C CA . ALA 1 1 ? A 1.000 2.000 3.000 . 1 A . 1

+ATOM 2 C CA . TYR 2 2 ? A 4.000 5.000 6.000 . 1 A . 1

+ATOM 3 C CA . VAL 3 3 ? A 7.000 8.000 9.000 . 1 A . 1

+HETATM 4 FE FE . SF4 . 1 ? B 10.000 10.000 10.000 . 2 B . 1

+#

+#

+loop_

+_atom_type.symbol

+C

+FE

+#

+# This example demonstrates writing an mmCIF file of a typical

+# single-template homology or comparative model, including a ligand.

+#

+# This is very similar to the mkmodbase.py example; see that example for

+# more details.

+

+# Import used classes

+import modelcif

+import modelcif.model

+import modelcif.dumper

+import modelcif.reference

+import modelcif.protocol

+import modelcif.alignment

+from modelcif.alignment import ShorterSequenceIdentity as SequenceIdentity

+import ihm

+

+system = modelcif.System(title='Ligand example')

+

+# Describe the amino acid (polymer) sequences as Entity objects, for both

+# template and model:

+template_e = modelcif.Entity('AFVVTDNCIKCK', description='Template subunit')

+model_e = modelcif.Entity('AYVINDSCIA', description='Model subunit')

+

+# For non-polymers (e.g. ligands) we need to describe the chemistry of the

+# ligand as a chemical component object, then create an Entity using that

+# component. We only need to do this once because the ligand is the same

+# in both template and model:

+sf4 = ihm.NonPolymerChemComp("SF4", name='IRON/SULFUR CLUSTER',

+ formula='Fe4 S4')

+ligand_e = modelcif.Entity([sf4], description='IRON/SULFUR CLUSTER')

+

+# Create a Template for each chain (amino acids in chain A, ligand in chain B)

+# and point to the original PDB, 5fd1:

+s = modelcif.reference.PDB('5fd1')

+templateA = modelcif.Template(

+ entity=template_e, asym_id='A', model_num=1, name="Template polymer",

+ transformation=modelcif.Transformation.identity(), references=[s])

+templateB = modelcif.Template(

+ entity=ligand_e, asym_id='B', model_num=1, name='Template ligand',

+ transformation=modelcif.Transformation.identity(), references=[s])

+

+# Define the model assembly, as two AsymUnits. NonPolymerFromTemplate is a

+# subclass of AsymUnit that additionally notes the Template from which it

+# was derived. In this case we state that the ligand was simply copied from

+# the template into the target (explicit=False):

+asymA = modelcif.AsymUnit(model_e, details='Model subunit A', id='A')

+asymB = modelcif.NonPolymerFromTemplate(template=templateB, explicit=False,

+ details='Model subunit B', id='B')

+modeled_assembly = modelcif.Assembly((asymA, asymB), name='Modeled assembly')

+

+

+# For the amino acid chain, add the modeling alignment, just as in the

+# mkmodbase.py example:

+class Alignment(modelcif.alignment.Global, modelcif.alignment.Pairwise):

+ pass

+

+

+p = modelcif.alignment.Pair(

+ template=templateA.segment("AFVVTDNCIKCK", 1, 12),

+ target=asymA.segment("AYVINDSC--IA", 1, 10),

+ score=modelcif.alignment.BLASTEValue(1e-15),

+ identity=SequenceIdentity(45.0))

+aln = Alignment(name="Modeling alignment",

+ pairs=[p])

+system.alignments.append(aln)

+

+# Add model coordinates, similarly to the mkmodbase.py example.

+# Note that nonpolymers are not "sequences" and so seq_id=None.

+atoms = [('A', 1, 'C', 'CA', 1., 2., 3.),

+ ('A', 2, 'C', 'CA', 4., 5., 6.),

+ ('A', 3, 'C', 'CA', 7., 8., 9.),

+ ('B', None, 'FE', 'FE', 10., 10., 10.)]

+

+

+class MyModel(modelcif.model.HomologyModel):

+ asym_unit_map = {'A': asymA, 'B': asymB}

+

+ def get_atoms(self):

+ for asym, seq_id, type_symbol, atom_id, x, y, z in atoms:

+ yield modelcif.model.Atom(

+ asym_unit=self.asym_unit_map[asym], type_symbol=type_symbol,

+ seq_id=seq_id, atom_id=atom_id, x=x, y=y, z=z,

+ het=seq_id is None)

+

+

+# Add the model and modeling protocol to the file and write them out:

+model = MyModel(assembly=modeled_assembly, name='Best scoring model')

+

+model_group = modelcif.model.ModelGroup([model], name='All models')

+system.model_groups.append(model_group)

+

+protocol = modelcif.protocol.Protocol()

+protocol.steps.append(modelcif.protocol.ModelingStep(

+ input_data=aln, output_data=model))

+system.protocols.append(protocol)

+

+with open('output.cif', 'w') as fh:

+ modelcif.dumper.write(fh, [system])

+# This example demonstrates using the library to make an mmCIF file of a

+# typical single-template single-chain homology or comparative model, similar

+# to those generated by MODELLER (https://salilab.org/modeller/) and deposited

+# in the ModBase database (https://modbase.compbio.ucsf.edu/)

+

+# For a more complete (but less documented) script to convert a complete

+# ModBase PDB file into a corresponding mmCIF or BinaryCIF file, see

+# https://github.com/salilab/modbase_utils/blob/main/modbase_pdb_to_cif.py

+

+# Import used classes.

+import modelcif

+import modelcif.protocol

+import modelcif.model

+import modelcif.dumper

+import modelcif.reference

+import modelcif.qa_metric

+import modelcif.alignment

+# Different methods measure "sequence identity" in different ways, so import

+# the class that matches the way Modeller understands it (number of identical

+# aligned residues, divided by the length of the shorter sequence)

+from modelcif.alignment import ShorterSequenceIdentity as SequenceIdentity

+import ihm.citations

+import modelcif.reader

+

+# First, we create a system, which contains everything we know about the

+# modeling. A single mmCIF file can contain multiple Systems, but in most

+# cases we use just one:

+system = modelcif.System(title='S54091 hypothetical protein YPR070w')

+

+# List the authors of this file (here these are the ModBase authors)

+system.authors.extend(('Pieper U', 'Webb B', 'Narayanan E', 'Sali A'))

+

+# Describe the software that was used in the modeling

+modpipe_software = modelcif.Software(

+ name='ModPipe', classification='comparative modeling',

+ location='https://salilab.org/modpipe/', type='program',

+ version='SVN.r1703', description='Comparative modeling pipeline')

+# Every object we create must ultimately be linked to the System, which

+# maintains simple lists for each type of object. For example, there is a

+# list system.software (like system.authors above) which can be used for

+# any Software object not referenced by any other object. But in this case

+# we're going to use these Software objects further on in the script, so

+# don't need to explicitly add them here.

+

+modeller_software = modelcif.Software(

+ name='MODELLER', classification='comparative modeling',

+ location='https://salilab.org/modeller/', type='program',

+ version='SVN', citation=ihm.citations.modeller,

+ description='Comparative modeling by satisfaction of spatial restraints')

+

+# Next, we define "entities", unique sequences in the system, as Entity

+# objects. First, the template sequence:

+template_e = modelcif.Entity('DMACDTFIKCC', description='Template subunit')

+

+# Next, the target (model) sequence, together with a link to the reference

+# sequence (in UniProt):

+s = modelcif.reference.UniProt(code='MED1_YEAST', accession='Q12321',

+ sequence='DSYVETLDCC')

+model_e = modelcif.Entity('DSYVETLDCC', description='Model subunit',

+ references=[s])

+

+# Next, we define asymmetric units for everything we modeled.

+# These roughly correspond to chains in a traditional PDB file. Multiple

+# asymmetric units may map to the same entity (for example if there are

+# several copies of a given protein).

+asymA = modelcif.AsymUnit(model_e, details='Model subunit A', id='A')

+

+# Next, we group asymmetric units into assemblies.

+modeled_assembly = modelcif.Assembly((asymA,), name='Modeled assembly')

+

+# In a similar fashion, we declare a Template for each chain that we used

+# as a template structure, with a link to the reference structure database

+# (PDB).

+s = modelcif.reference.PDB('3nc1')

+template = modelcif.Template(

+ entity=template_e, asym_id='A', model_num=1, name="Template Structure",

+ transformation=modelcif.Transformation.identity(),

+ references=[s])

+

+

+# Now, we describe the alignment between target and template.

+# python-ma provides various subclasses to use here. All ModBase structures

+# use a simple pairwise global alignment between target and template, so

+# declare a suitable class:

+class Alignment(modelcif.alignment.Global, modelcif.alignment.Pairwise):

+ pass

+

+

+# An alignment consists of a list of aligned target-template segments.

+# Here we provide the residue ranges and the actual alignment, including gaps,

+# between the two, together with the sequence identity and any score available

+# for the alignment (here we have the BLAST e-value):

+p = modelcif.alignment.Pair(

+ template=template.segment("DMACDTFIK", 1, 9),

+ target=asymA.segment("DSYV-ETLD", 1, 8),

+ score=modelcif.alignment.BLASTEValue(1e-15),

+ identity=SequenceIdentity(45.0))

+aln = Alignment(name="Modeling alignment", software=modpipe_software,

+ pairs=[p])

+# Alignments aren't used by any objects; they should be added directly

+# to the System:

+system.alignments.append(aln)

+

+# For the actual model coordinates, we must subclass a suitable class and

+# override the get_atoms() method to return a list of Atom objects. This design

+# avoids having a separate copy of every atom in memory.

+# Modeller models are comparative or homology models, so we subclass

+# HomologyModel. For the purposes of this example, we just return a simple

+# static list of atoms:

+

+atoms = [('A', 1, 'C', 'CA', 1., 2., 3.),

+ ('A', 2, 'C', 'CA', 4., 5., 6.),

+ ('A', 3, 'C', 'CA', 7., 8., 9.),

+ ('A', 4, 'C', 'CA', 10., 11., 12.)]

+

+

+class MyModel(modelcif.model.HomologyModel):

+ # Map our asym unit names to ModelCIF asym_unit objects:

+ asym_unit_map = {'A': asymA}

+

+ def get_atoms(self):

+ for asym, seq_id, type_symbol, atom_id, x, y, z in atoms:

+ yield modelcif.model.Atom(

+ asym_unit=self.asym_unit_map[asym], type_symbol=type_symbol,

+ seq_id=seq_id, atom_id=atom_id, x=x, y=y, z=z)

+

+

+# Link the model to the Assembly that describes all subunits

+model = MyModel(assembly=modeled_assembly, name='Best scoring model')

+

+# Next, we describe the modeling protocol:

+protocol = modelcif.protocol.Protocol()

+protocol.steps.append(modelcif.protocol.TemplateSearchStep(

+ name='ModPipe Seq-Prf (0001)', software=modpipe_software,

+ input_data=model_e, output_data=aln))

+protocol.steps.append(modelcif.protocol.ModelingStep(

+ software=modeller_software, input_data=aln, output_data=model))

+protocol.steps.append(modelcif.protocol.ModelSelectionStep(

+ software=modpipe_software, input_data=model, output_data=model))

+# Protocols aren't used by any other objects; they should be added directly

+# to the System:

+system.protocols.append(protocol)

+

+

+# We can also attach quality scores to our model(s). To do this we must

+# first define the scores by creating subclasses using a MetricMode

+# (e.g. global, per-residue) and a MetricType (e.g. distance, z-score).

+# Here we define the quality scores used by the ModPipe pipeline that is used

+# by ModBase. Note that one score (MPQS) uses a custom metric type, while

+# another (zDOPE) is a simple global z-score:

+class MPQSMetricType(modelcif.qa_metric.MetricType):

+ """composite score, values >1.1 are considered reliable"""

+

+

+class MPQS(modelcif.qa_metric.Global, MPQSMetricType):

+ """ModPipe Quality Score"""

+ software = modpipe_software

+

+

+class zDOPE(modelcif.qa_metric.Global, modelcif.qa_metric.ZScore):

+ """Normalized DOPE"""

+ software = modeller_software

+

+

+class TSVModRMSD(modelcif.qa_metric.Global, modelcif.qa_metric.Distance):

+ """TSVMod predicted RMSD (MSALL)"""

+ software = None

+

+

+class TSVModNO35(modelcif.qa_metric.Global,

+ modelcif.qa_metric.NormalizedScore):

+ """TSVMod predicted native overlap (MSALL)"""

+ software = None

+

+

+# Add qa metrics to the model

+model.qa_metrics.extend((MPQS(0.853452), zDOPE(0.31), TSVModRMSD(12.996),

+ TSVModNO35(0.143)))

+

+# All ModBase QA metrics are global, but the library also supports per-residue

+# or pairwise (between two residues) scores. Here's a fictional example for a

+# z-score on the 4th residue of the first chain in the model, and a distance

+# score between the 1st and 3rd residues:

+

+

+class SomeLocalScore(modelcif.qa_metric.Local, modelcif.qa_metric.ZScore):

+ """A per-residue z-score"""

+ software = None

+

+

+class SomePairScore(modelcif.qa_metric.LocalPairwise,

+ modelcif.qa_metric.Distance):

+ """A distance score between two residues"""

+ software = None

+

+

+model.qa_metrics.append(SomeLocalScore(asymA.residue(4), -0.1))

+model.qa_metrics.append(SomePairScore(asymA.residue(1), asymA.residue(3), 1.0))

+

+# Models should be grouped together using ModelGroup and then added to the

+# top-level System. Here we only have a single model in the group:

+model_group = modelcif.model.ModelGroup([model], name='All models')

+system.model_groups.append(model_group)

+

+# Once the system is complete, we can write it out to an mmCIF file:

+with open('output.cif', 'w') as fh:

+ modelcif.dumper.write(fh, [system])

+

+# We can also *read* an mmCIF file and create a set of Python objects from it.

+# Here we read in the file we just created:

+with open('output.cif') as fh:

+ s, = modelcif.reader.read(fh)

+for t in s.templates:

+ print(t.name, "-".join(c.id for c in t.entity.sequence))

+for e in s.entities:

+ print(e.description, "-".join(c.id for c in e.sequence))

+# This example demonstrates the use of the Python IHM library's validator

+# to validate a user-provided input mmCIF file.

+# See also validate_modbase.py for a more detailed example.

+

+import sys

+import ihm.dictionary

+import urllib.request

+

+

+if len(sys.argv) != 2:

+ print("Usage: %s input.cif" % sys.argv[0], file=sys.stderr)

+ sys.exit(1)

+fname = sys.argv[1]

+

+# Read in the ModelCIF and PDBx dictionary from https://mmcif.wwpdb.org/

+with urllib.request.urlopen(

+ 'https://mmcif.wwpdb.org/dictionaries/ascii/mmcif_ma.dic') as fh:

+ pdbx_mcif = ihm.dictionary.read(fh)

+

+# Validate the mmCIF file assuming it is UTF8 encoded.

+# See validate_modbase.py for code to fallback to ASCII for non-UTF8 files.

+with open(fname, encoding='UTF-8') as fh:

+ pdbx_mcif.validate(fh)

+

+# Similarly, to validate a BinaryCIF file, use:

+# with open(fname, 'rb') as fh:

+# pdbx_mcif.validate(fh, format='BCIF')

+# This example demonstrates the use of the Python IHM library's validator.

+# A structure is downloaded from the ModBase database and checked against

+# the ModelCIF dictionary for compliance. This validator can be used

+# to perform basic integrity checking against any mmCIF dictionary.

+# See also validate_mmcif.py for a simpler script to validate a

+# user-provided mmCIF file.

+

+import io

+import ihm.dictionary

+import urllib.request

+

+# Read in the ModelCIF dictionary from wwPDB as a Dictionary object.

+# Note that the ModelCIF dictionary also includes the PDBx dictionary,

+# so we don't need to read that in separately

+fh = urllib.request.urlopen(

+ 'https://mmcif.wwpdb.org/dictionaries/ascii/mmcif_ma.dic')

+pdbx_mc = ihm.dictionary.read(fh)

+fh.close()

+

+# Validate a structure against PDBx+ModelCIF.

+# A correct structure here should result in no output; an invalid structure

+# will result in a ValidatorError Python exception.

+# Here, a structure from ModBase (which should be valid) is used.

+acc = 'P21812'

+cif = urllib.request.urlopen('https://salilab.org/modbase/retrieve'

+ '?databaseID=%s&format=mmcif' % acc).read()

+

+# The encoding for mmCIF files isn't strictly defined, so first try UTF-8

+# and if that fails, strip out any non-ASCII characters. This ensures that

+# we handle accented characters in string fields correctly.

+try:

+ fh = io.StringIO(cif.decode('utf-8'))

+except UnicodeDecodeError:

+ fh = io.StringIO(cif.decode('ascii', errors='ignore'))

+

+pdbx_mc.validate(fh)

+#!/bin/bash -e

+

+# First, do

+# - Check spelling with

+# codespell . --skip '*.cif' -L assertIn

+# - Update AuditConformDumper to match latest MA dictionary if necessary

+# - Run util/validate-outputs.py to make sure all example outputs validate

+# (cd util; PYTHONPATH=.. python3 ./validate-outputs.py)

+# - Run util/check-db-entries.py to check against some real archive structures

+# (cd util; PYTHONPATH=.. python3 check-db-entries.py)

+# - If we need a newer python-ihm, update the version requirement in

+# requirements.txt, setup.py, pyproject.toml, util/python-modelcif.spec,

+# and README.md.

+# - Update ChangeLog.rst and util/python-modelcif.spec with the release number

+# - Update release number in modelcif/__init__.py, setup.py and pyproject.toml

+# - Commit, tag, and push

+# - Make release on GitHub

+# - Upload the release tarball from

+# https://github.com/ihmwg/python-modelcif/releases to Zenodo as a new release

+# - Make sure there are no extraneous .py files (setup.py will include them

+# in the pypi package)

+

+VERSION=$(python3 setup.py --version)

+python3 setup.py sdist

+echo "Now use 'twine upload dist/modelcif-${VERSION}.tar.gz' to publish the release on PyPi"

+echo "Then, update the conda-forge and COPR packages to match."

+echo "For COPR, use dist/modelcif-${VERSION}.tar.gz together with util/python-modelcif.spec"

+echo "For conda-forge, make sure the correct version of python-ihm is required"

+import itertools

+import warnings

+import ihm

+from ihm import Entity, AsymUnit, Software, Assembly, Residue # noqa: F401

+from ihm import WaterAsymUnit, AsymUnitRange, _remove_identical # noqa: F401

+import modelcif.data

+

+__version__ = '1.5'

+

+

+class System:

+ """Top-level class representing a complete modeled system.

+

+ :param str title: Longer text description of the system.

+ :param str id: Unique identifier for this system in the mmCIF file.

+ :param database: If this system is part of an official database

+ (e.g. SwissModel, ModBase), details of the database identifiers.

+ :type database: :class:`Database`

+ :param str model_details: Detailed description of the system, like an

+ abstract.

+

+ The system contains a number of simple flat lists of various objects,

+ for example :attr:`alignments`. After constructing objects they should

+ usually be added to these lists so that a hierarchy of classes is

+ formed and is ultimately written out to mmCIF/BinaryCIF. After reading

+ a file the resulting ``System`` object will also populate these lists.

+

+ Most objects do not need to be explicitly added to the system since

+ they are referenced by other objects. For example :class:`Template`

+ objects are not usually added to the system because they are added

+ to alignments which in turn are added to the system. If however an

+ "orphan" Template is desired (not part of an alignment) the system does

+ maintain an appropriate list (``System.templates`` in this case) to

+ which it can be added.

+ """

+

+ structure_determination_methodology = "computational"

+

+ def __init__(self, title=None, id='model', database=None,

+ model_details=None):

+ self.id, self.title = id, title

+ self.database = database

+ self.model_details = model_details

+

+ #: List of plain text comments. These will be added to the top of

+ #: the mmCIF file.

+ self.comments = []

+

+ #: List of all authors of this system, as a list of strings (last name

+ #: followed by initials, e.g. "Smith AJ"). When writing out a file,

+ #: if this list is empty, all authors from the first citation

+ #: (see :attr:`citations` and :class:`ihm.Citation`) are used instead.

+ self.authors = []

+

+ #: List of all grants that supported this work. See :class:`ihm.Grant`.

+ self.grants = []

+

+ #: List of all citations. By convention the first citation describes

+ #: the system itself. See :class:`ihm.Citation`.

+ self.citations = []

+

+ #: Revision/update history. See :class:`ihm.Revision`.

+ self.revisions = []

+

+ #: Information on usage of the data. See :class:`ihm.DataUsage`.

+ self.data_usage = []

+

+ #: All groups of models. See :class:`~modelcif.model.ModelGroup`.

+ self.model_groups = []

+

+ #: All modeling protocols.

+ #: See :class:`~modelcif.protocol.Protocol`.

+ self.protocols = []

+

+ #: All modeling alignments.

+ #: See :mod:`modelcif.alignment`.

+ self.alignments = []

+

+ #: Any additional files with extra data about this system.

+ #: See :class:`modelcif.associated.Repository`.

+ self.repositories = []

+

+ self.entities = []

+ self.asym_units = []

+ self.templates = []

+ self.template_segments = []

+ self.template_transformations = []

+ self.data = []

+ self.data_groups = []

+ self.software = []

+ self.software_groups = []

+ self.assemblies = []

+ self._orphan_chem_comps = []

+

+ # Mapping from ID to QA metric classes

+ self._qa_by_id = {}

+

+ def _all_models(self):

+ """Iterate over all Models in the system"""

+ # todo: raise an error if a model is present in multiple groups?

+ seen_models = set()

+ for group in self._all_model_groups():

+ for model in group:

+ if model in seen_models:

+ continue

+ seen_models.add(model)

+ yield group, model

+

+ def _before_write(self):

+ # Populate flat lists to contain all referenced objects only once

+ # We must populate these in the correct order to get all objects

+ self.assemblies = list(_remove_identical(self._all_assemblies()))

+ self.asym_units = list(_remove_identical(self._all_asym_units()))

+ self.alignments = list(_remove_identical(self.alignments))

+ self.template_segments = list(

+ _remove_identical(self._all_template_segments()))

+ self.templates = list(_remove_identical(self._all_templates()))

+ self.entities = list(_remove_identical(self._all_entities()))

+ self.template_transformations = list(_remove_identical(

+ self._all_template_transformations()))

+ self.data_groups = list(_remove_identical(

+ self._all_data_groups()))

+ self.data = list(_remove_identical(

+ self._all_data()))

+ self.model_groups = list(_remove_identical(self.model_groups))

+ self.software_groups = list(_remove_identical(

+ self._all_software_groups()))

+ self.software = list(_remove_identical(

+ self._all_ref_software()))

+ self._add_missing_reference_sequence()

+

+ def _add_missing_reference_sequence(self):

+ """If any TargetReference has no sequence, use that of the Entity"""

+ for e in self.entities:

+ for r in e.references:

+ if r.sequence is None:

+ r.sequence = "".join(comp.code_canonical

+ for comp in e.sequence)

+

+ def _check_after_write(self):

+ pass

+

+ def _all_template_segments(self):

+ return itertools.chain(

+ self.template_segments,

+ (p.template for aln in self.alignments for p in aln.pairs))

+

+ def _all_templates(self):

+ return itertools.chain(

+ self.templates,

+ (x.template for x in self.template_segments),

+ (x.template for x in self.asym_units

+ if isinstance(x, NonPolymerFromTemplate)))

+

+ def _all_template_transformations(self):

+ return itertools.chain(

+ self.template_transformations,

+ (x.transformation for x in self.templates))

+

+ def _all_citations(self):

+ """Iterate over all Citations in the system.

+ This includes all Citations referenced from other objects, plus

+ any referenced from the top-level system.

+ Duplicates are filtered out."""

+ return _remove_identical(itertools.chain(

+ self.citations,

+ (software.citation for software in self._all_software()

+ if software.citation)))

+

+ def _all_software(self):

+ """Utility method used by ihm.dumper to get all Software. To initially

+ populate this list from all Software referenced in the system,

+ use _all_ref_software() instead."""

+ return self.software

+

+ def _all_ref_software(self):

+ """Iterate over all Software in the system.

+ This includes all Software referenced from other objects, plus

+ any referenced from the top-level system.

+ Duplicates may be present."""

+ def _all_software_in_groups():

+ for sg in self.software_groups:

+ if isinstance(sg, Software):

+ yield sg

+ else:

+ for s in sg:

+ if isinstance(s, SoftwareWithParameters):

+ yield s.software

+ else:

+ yield s

+

+ def _all_entities():

+ return itertools.chain(

+ self.entities, (t.entity for t in self.templates))

+

+ def _all_descriptor_software():

+ comps = frozenset(comp for e in _all_entities()

+ for comp in e.sequence)

+ for comp in comps:

+ if hasattr(comp, 'descriptors') and comp.descriptors:

+ for desc in comp.descriptors:

+ if desc.software:

+ yield desc.software

+ return (itertools.chain(

+ self.software, _all_software_in_groups(),

+ _all_descriptor_software()))

+

+ def _all_assemblies(self):

+ """Iterate over all Assemblies in the system.

+ This includes all Assemblies referenced from other objects, plus

+ any orphaned Assemblies. Duplicates may be present."""

+ return itertools.chain(

+ self.assemblies,

+ (model.assembly for group, model in self._all_models()

+ if model.assembly))

+

+ def _all_asym_units(self):

+ def _all_asym_in_assemblies():

+ for asmb in self.assemblies:

+ for a in asmb:

+ yield a.asym if hasattr(a, 'asym') else a

+ return itertools.chain(

+ self.asym_units, _all_asym_in_assemblies())

+

+ def _all_entities(self):

+ return itertools.chain(

+ self.entities,

+ (asym.entity for asym in self.asym_units))

+

+ def _all_model_groups(self, only_in_states=True):

+ return self.model_groups

+

+ def _all_data(self):

+ def _all_data_in_groups():

+ for dg in self.data_groups:

+ if isinstance(dg, list):

+ for data in dg:

+ yield data

+

+ def _all_data_in_files():

+ for repo in self.repositories:

+ for f in repo.files:

+ if f.data:

+ yield f.data

+ if hasattr(f, 'files'):

+ for subf in f.files:

+ if subf.data:

+ yield subf.data

+ return itertools.chain(

+ self.data,

+ self.templates,

+ self.entities,

+ self.alignments,

+ (model for group, model in self._all_models()),

+ _all_data_in_groups(),

+ _all_data_in_files())

+

+ def _all_data_groups(self):

+ """Return all DataGroup (or singleton Data) objects"""

+ return itertools.chain(

+ self.data_groups,

+ (step.input_data for p in self.protocols for step in p.steps

+ if step.input_data),

+ (step.output_data for p in self.protocols for step in p.steps

+ if step.output_data))

+

+ def _all_software_groups(self):

+ """Return all SoftwareGroup (or singleton Software) objects"""

+ return itertools.chain(

+ self.software_groups,

+ (aln.software for aln in self.alignments if aln.software),

+ (step.software for p in self.protocols for step in p.steps

+ if step.software),

+ (metric.software for group, model in self._all_models()

+ for metric in model.qa_metrics if metric.software))

+

+ def _all_features(self):

+ """Return all Feature objects"""

+ for _, model in self._all_models():

+ for m in model.qa_metrics:

+ if hasattr(m, '_all_features'):

+ for f in m._all_features:

+ yield f

+

+

+# Provide ma-specific docs for Entity

+Entity.__doc__ = """Represent a unique molecular sequence.

+

+This can be used both for template sequences (in which case the Entity is

+then used in a :class:`Template` object) or for target (model) sequences

+(where it is used in a :class:`AsymUnit` object).

+

+(Note that template sequence Entity objects are not written out to the

+entity, entity_poly etc. tables in the mmCIF/BinaryCIF file by default.

+Instead, sequence information is captured in template-specific categories.)

+

+:param sequence sequence: The primary sequence, as a sequence of

+ :class:`ihm.ChemComp` objects, and/or codes looked up in `alphabet`.

+ See `ihm.Entity <https://python-ihm.readthedocs.io/en/latest/main.html#ihm.Entity>`_ for examples.

+:param alphabet: The mapping from code to chemical components to use

+ (it is not necessary to instantiate this class).

+:type alphabet: :class:`ihm.Alphabet`

+:param str description: A short text name for the sequence.

+:param str details: Longer text describing the sequence.

+:param source: The method by which the sample for this entity was produced.

+:type source: :class:`ihm.source.Source`

+:param references: For a target (model) sequence, information about this

+ entity stored in external databases (for example the sequence in

+ UniProt). For references to structure databases for templates,

+ see :class:`Template` instead.

+:type references: sequence of :class:`reference.TargetReference` objects

+

+See `ihm.Entity <https://python-ihm.readthedocs.io/en/latest/main.html#ihm.Entity>`_ for more information.

+""" # noqa: E501

+

+

+# Provide ma-specific docs for Software

+Software.__doc__ = """Software used as part of the modeling protocol.

+

+:param str name: The name of the software.

+:param str classification: The major function of the software, for

+ example 'model building', 'sample preparation', 'data collection'.

+:param str description: A longer text description of the software.

+:param str location: Place where the software can be found (e.g. URL).

+:param str type: Type of software (program/package/library/other).

+:param str version: The version used.

+:param citation: Publication describing the software.

+:type citation: :class:`ihm.Citation`

+

+Generally these objects are added to groups (see :class:`SoftwareGroup`)

+which can then be used to describe the software used in various parts of the

+modeling (``Software`` objects can also be used any place

+:class:`SoftwareGroup` are accepted, in which case they will act as if a group

+containing only a single member was used).

+

+See also :attr:`System.software`.

+"""

+

+# Provide ma-specific docs for Assembly

+Assembly.__doc__ = """A collection of parts of the system that were modeled

+together.

+

+:param sequence elements: Initial set of parts of the system.

+:param str name: Short text name of this assembly.

+:param str description: Longer text that describes this assembly.

+

+This is implemented as a simple list of asymmetric units (or parts of

+them), i.e. a list of :class:`AsymUnit` and/or :class:`AsymUnitRange`

+objects. An Assembly is typically passed to the :class:`modelcif.model.Model`

+constructor.

+

+Note that the ModelCIF dictionary has deprecated the corresponding

+``ma_struct_assembly`` category, so any name or description of the assembly

+will not be written to the mmCIF file. The ModelCIF dictionary requires that

+all models have the same composition.

+"""

+

+

+class Database:

+ """Information about a System that is part of an official database.

+

+ If a :class:`System` is part of an official database (e.g. SwissModel,

+ ModBase), this class contains details of the database identifiers.

+ It should be passed to the :class:`System` constructor.

+

+ :param str id: Abbreviated name of the database (e.g. PDB)

+ :param str code: Identifier from the database (e.g. 1abc)

+ """

+ def __init__(self, id, code):

+ self.id, self.code = id, code

+

+

+class SoftwareGroup(list):

+ """A number of :class:`Software` and/or :class:`SoftwareWithParameters`

+ objects that are grouped together.

+

+ This class can be used to group together multiple :class:`Software`

+ objects if multiple pieces of software were used together to generate

+ a single alignment (see :class:`modelcif.alignment.AlignmentMode`), to

+ run a modeling step (see :class:`modelcif.protocol.Step`), or to

+ calculate a model quality score (see :mod:`modelcif.qa_metric`).

+ It behaves like a regular Python list.

+

+ :class:`SoftwareWithParameters` allows including both a piece of

+ software, and the parameters with which it was used, in the group.

+

+ :param sequence elements: Initial set of :class:`Software`

+ and/or :class:`SoftwareWithParameters` objects.

+ """

+

+ def __init__(self, elements=(), parameters=None):

+ super(SoftwareGroup, self).__init__(elements)

+ if parameters:

+ warnings.warn(

+ "Parameters for SofwareGroup are ignored. To specify "

+ "parameters for a piece of software, use the "

+ "SoftwareWithParameters class.")

+ self.parameters = [] if parameters is None else parameters

+

+

+class SoftwareWithParameters:

+ """A piece of software and the parameters with which it was used.

+

+ See :class:`SoftwareGroup`.

+

+ :param software: The software that was used.

+ :type software: :class:`modelcif.Software`

+ :param sequence parameters: sequence of parameters for the software,

+ as :class:`SoftwareParameter` objects.

+ """

+ def __init__(self, software, parameters=None):

+ self.software = software

+ self.parameters = [] if parameters is None else parameters

+

+ # Pass Software-specific fields through

+ name = property(lambda self: self.software.name)

+ classification = property(lambda self: self.software.classification)

+ description = property(lambda self: self.software.description)

+ location = property(lambda self: self.software.location)

+ type = property(lambda self: self.software.type)

+ version = property(lambda self: self.software.version)

+ citation = property(lambda self: self.software.citation)

+

+

+class SoftwareParameter:

+ """A single parameter given to software used in modeling.

+

+ See :class:`SoftwareWithParameters`, :class:`SoftwareGroup`.

+

+ :param str name: A short name for this parameter.

+ :param value: Parameter value.

+ :type value: ``int``, ``float``, ``str``, ``bool``, list of ``int``,

+ or list of ``float``.

+ :param str description: A longer description of the parameter.

+ """

+ def __init__(self, name, value, description=None):

+ self.name, self.value = name, value

+ self.description = description

+

+ def __repr__(self):

+ return ("<SoftwareParameter(name=%r, value=%r)>"

+ % (self.name, self.value))

+

+

+class Transformation:

+ """Rotation and translation applied to an object.

+

+ These objects are generally used to record the transformation that

+ was applied to a :class:`Template` to generate the starting structure

+ used in modeling.

+

+ :param rot_matrix: Rotation matrix (as a 3x3 array of floats) that

+ places the object in its final position.

+ :param tr_vector: Translation vector (as a 3-element float list) that

+ places the object in its final position.

+ """

+ def __init__(self, rot_matrix, tr_vector):

+ self.rot_matrix, self.tr_vector = rot_matrix, tr_vector

+

+ """Return the identity transformation.

+

+ :return: A new identity Transformation.

+ :rtype: :class:`Transformation`

+ """

+ @classmethod

+ def identity(cls):

+ if not hasattr(cls, '_identity_obj'):

+ cls._identity_obj = cls(

+ [[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]], [0., 0., 0.])

+ return cls._identity_obj

+

+

+class TemplateSegment:

+ """An aligned part of a template (see :class:`modelcif.alignment.Pair`).

+

+ Usually these objects are created from

+ a :class:`Template` using :meth:`Template.segment`, e.g. to get a

+ segment covering residues 1 through 3 in `tmpl` use::

+

+ tmpl = modelcif.Template(entity, ...)

+ seg = tmpl.segment('--ACG', 1, 3)

+ """

+ def __init__(self, template, gapped_sequence, seq_id_begin, seq_id_end):

+ self.template = template

+ self.gapped_sequence = gapped_sequence

+ self.seq_id_range = (seq_id_begin, seq_id_end)

+

+

+class _TemplateBase(modelcif.data.Data):

+ """Base class for all templates; use Template or CustomTemplate"""

+

+ data_content_type = "template structure"

+

+ def __init__(self, entity, asym_id, model_num, transformation,

+ name=None, strand_id=None, entity_id=None):

+ super(_TemplateBase, self).__init__(name)

+ self.entity = entity

+ self.asym_id, self.model_num = asym_id, model_num

+ self.transformation = transformation

+ self._strand_id = strand_id

+ self.entity_id = entity_id

+

+ def segment(self, gapped_sequence, seq_id_begin, seq_id_end):

+ """Get an object representing the alignment of part of this sequence.

+

+ :param str gapped_sequence: Sequence of the segment, including gaps.

+ :param int seq_id_begin: Start of the segment.

+ :param int seq_id_end: End of the segment.

+ """

+ # todo: cache so we return the same object for same parameters

+ return TemplateSegment(self, gapped_sequence, seq_id_begin, seq_id_end)

+

+ seq_id_range = property(lambda self: self.entity.seq_id_range,

+ doc="Sequence range")

+

+ template = property(lambda self: self)

+

+ strand_id = property(lambda self: self._strand_id or self.asym_id,

+ doc="PDB or author-provided strand/chain ID")

+

+

+class Template(_TemplateBase):

+ """A single database chain that was used as a template structure

+ for modeling.

+

+ After creating a polymer template, use :meth:`segment` to denote the

+ part of its sequence used in any modeling alignments

+ (see :class:`modelcif.alignment.Pair`).

+

+ Non-polymer templates do not have alignments, and should instead be

+ passed to one or more :class:`NonPolymerFromTemplate` objects.

+

+ Template objects can also be used as inputs or outputs in modeling

+ protocol steps; see :class:`modelcif.protocol.Step`.

+

+ This class is intended for templates that were taken from reference

+ databases such as PDB. For a non-deposited "custom" template,

+ use the :class:`CustomTemplate` class instead.

+

+ :param entity: The sequence of the chain.

+ :type entity: :class:`Entity`

+ :param str asym_id: The asym or chain ID in the template structure.

+ :param int model_num: The model number of the template structure.

+ :param transformation: Rotation and translation applied to the original

+ template structure to get the starting model used in modeling.

+ :type transformation: :class:`Transformation`

+ :param str name: A short name for this template.

+ :param references: A list of pointers to reference databases (such as

+ PDB) from which the template structure was taken.

+ :type references: list of :class:`modelcif.reference.TemplateReference`

+ objects

+ :param str strand_id: PDB or "author-provided" strand/chain ID.

+ If not specified, it will be the same as the regular asym_id.

+ :param str entity_id: If known, the ID of the entity for this template

+ in its own mmCIF file.

+ """

+

+ def __init__(self, entity, asym_id, model_num, transformation,

+ name=None, references=[], strand_id=None, entity_id=None):

+ super(Template, self).__init__(

+ entity=entity, asym_id=asym_id, model_num=model_num,

+ transformation=transformation, name=name, strand_id=strand_id,

+ entity_id=entity_id)

+ self.references = []

+ self.references.extend(references)

+

+

+class CustomTemplate(_TemplateBase):

+ """A chain that was used as a template structure for modeling.

+

+ This class is intended for templates that have not been deposited

+ in a database such as PDB (for deposited templates, use the

+ :class:`Template` class instead). The coordinates of the atoms

+ in these "custom" templates will be included in the mmCIF file;

+ see the :attr:`atoms` member.

+

+ :param str details: Information on how the template was created.

+

+ See :class:`Template` for a description of the other parameters.

+ """

+ def __init__(self, entity, asym_id, model_num, transformation,

+ name=None, strand_id=None, entity_id=None, details=None):

+ super(CustomTemplate, self).__init__(

+ entity=entity, asym_id=asym_id, model_num=model_num,

+ transformation=transformation, name=name, strand_id=strand_id,

+ entity_id=entity_id)

+ self.details = details

+

+ #: Coordinates of all atoms as :class:`TemplateAtom` objects

+ self.atoms = []

+

+

+class TemplateAtom:

+ """Coordinates of a single atom in a custom template.

+

+ This provides the coordinates for a template that has not been

+ deposited in a database. See :class:`CustomTemplate` for more

+ information. These objects are added to the

+ :attr:`CustomTemplate.atoms` list.

+

+ :param int seq_id: The sequence ID of the residue represented by this

+ atom. This should generally be a number starting at 1 for any

+ polymer chain, water, or oligosaccharide. For ligands, a seq_id

+ is not needed (as a given asym can only contain a single ligand),

+ so either 1 or None can be used.

+ :param str atom_id: The name of the atom in the residue

+ :param str type_symbol: Element name

+ :param float x: x coordinate of the atom

+ :param float y: y coordinate of the atom

+ :param float z: z coordinate of the atom

+ :param bool het: True for HETATM sites, False (default) for ATOM

+ :param float biso: Temperature factor or equivalent (if applicable)

+ :param float occupancy: Fraction of the atom type present

+ (if applicable)

+ :param float charge: Formal charge (if applicable)

+ :param int auth_seq_id: Author-provided sequence ID (if applicable;

+ this is optional for polymers but required for ligands).

+ :param str auth_atom_id: Author-provided atom name (if needed)

+ :param str auth_comp_id: Author-provided residue name (if needed)

+ """

+

+ # Reduce memory usage

+ __slots__ = ['seq_id', 'atom_id', 'type_symbol', 'x', 'y', 'z', 'het',

+ 'biso', 'occupancy', 'charge', 'auth_seq_id', 'auth_atom_id',

+ 'auth_comp_id']

+

+ def __init__(self, seq_id, atom_id, type_symbol, x, y, z,

+ het=False, biso=None, occupancy=None, charge=None,

+ auth_seq_id=None, auth_atom_id=None, auth_comp_id=None):

+ self.seq_id, self.atom_id = seq_id, atom_id

+ self.type_symbol = type_symbol

+ self.x, self.y, self.z = x, y, z

+ self.het, self.biso = het, biso

+ self.occupancy, self.charge = occupancy, charge

+ self.auth_seq_id = auth_seq_id

+ self.auth_atom_id, self.auth_comp_id = auth_atom_id, auth_comp_id

+

+

+class NonPolymerFromTemplate(AsymUnit):

+ """A non-polymer (e.g. ligand) in the model that is modeled from

+ a non-polymer template.

+

+ These objects act just like :class:`AsymUnit` and should be added

+ to :class:`Assembly`.

+

+ To represent a non-polymer that is modeled without a template, just

+ use a regular :class:`AsymUnit`.

+

+ :param template: The non-polymer template used to model

+ this non-polymer.

+ :type template: :class:`Template`

+ :param bool explicit: True iff the conformation of the template is

+ allowed to change (e.g. bond relaxation, flexible fitting)

+ during the modeling, or False if the template is treated as

+ a single rigid body.

+

+ For the other parameters, see :class:`AsymUnit`.

+ """

+

+ def __init__(self, template, explicit, details=None, auth_seq_id_map=0,

+ id=None, strand_id=None):

+ super(NonPolymerFromTemplate, self).__init__(

+ template.entity, details=details, auth_seq_id_map=auth_seq_id_map,

+ id=id, strand_id=strand_id)

+ self.template, self.explicit = template, explicit

+

+

+class ReferenceDatabase(modelcif.data.Data):

+ """A reference database used in the modeling. This is typically a

+ sequence database used for template search, alignments, etc.

+ These objects are passed as input or output to

+ :class:`modelcif.protocol.Step`. See also :class:`modelcif.data.Data`

+ for more details.

+

+ Compare with :class:`modelcif.reference.TargetReference`, which pertains

+ to just the modeled sequence itself; this class describes *multiple*

+ sequences.

+

+ :param str name: Name of the database.

+ :param str url: Location of the database.

+ :param str version: Version of the database.

+ :param release_date: Release date of the specified version.

+ :type release_date: :class:`datetime.date`

+ """

+ data_content_type = "reference database"

+

+ def __init__(self, name, url, version=None, release_date=None):

+ super(ReferenceDatabase, self).__init__(name)

+ self.url, self.version, self.release_date = url, version, release_date

+

+

+class Feature:

+ """Base class for selecting parts of the system.

+ This class should not be used itself; instead,

+ see :class:`AtomFeature`, :class:`PolyResidueFeature`,

+ and :class:`EntityInstanceFeature`.

+

+ Generally it is expected that the entities selected by a given

+ feature are all of the same type. For example, a feature should

+ not select both a ligand and a polymer.

+

+ Features are typically used in QA metrics, passed to

+ :class:`modelcif.qa_metric.Feature` or

+ :class:`modelcif.qa_metric.FeaturePairwise` objects.

+ """

+ details = None

+ type = ihm.unknown

+

+ def _get_entity_type(self, check=False):

+ return ihm.unknown

+

+ def _check_entity_types(self, types, check):

+ if check:

+ if len(types) > 1:

+ raise ValueError(

+ "Feature %r selects entities of multiple types: %s"

+ % (self, list(types)))

+ elif len(types) == 0:

+ raise ValueError("Feature %r doesn't select anything" % self)

+ return list(types)[0] if len(types) == 1 else 'other'

+

+

+class AtomFeature(Feature):

+ """Selection of one or more atoms from the system. See :class:`Feature`

+ for more information.

+

+ Note that currently support for atom features in python-modelcif

+ is rather rudimentary. They must be selected by their "id", not by

+ the Atom Python object.

+

+ :param sequence atoms: A list of atom indices (usually integers).

+ :param str details: Additional text describing this feature.

+ """

+

+ type = 'atom'

+

+ def __init__(self, atoms, details=None):

+ self.atoms, self.details = atoms, details

+

+ def _get_entity_type(self, check=False):

+ # We currently can't tell what type entity the atom IDs refer to

+ return 'other'

+

+ def _signature(self):

+ return tuple(self.atoms)

+

+

+class PolyResidueFeature(Feature):

+ """Selection of one or more polymer residues from the system.

+ See :class:`Feature` for more information.

+

+ :param sequence residues: A list of :class:`Residue` objects.

+ :param str details: Additional text describing this feature.

+ """

+ type = 'residue'

+

+ def __init__(self, residues, details=None):

+ self.residues, self.details = residues, details

+

+ def _get_entity_type(self, check=False):

+ types = frozenset(x.entity.type for x in self.residues)

+ return self._check_entity_types(types, check)

+

+ def _signature(self):

+ return tuple(self.residues)

+

+

+class EntityInstanceFeature(Feature):

+ """Selection of one or more asyms from the system.

+ See :class:`Feature` for more information.

+

+ :param sequence asym_units: A list of :class:`AsymUnit` objects.

+ :param str details: Additional text describing this feature.

+ """

+ type = 'entity instance'

+

+ def __init__(self, asym_units, details=None):

+ self.asym_units, self.details = asym_units, details

+

+ def _get_entity_type(self, check=False):

+ types = frozenset(x.entity.type for x in self.asym_units)

+ return self._check_entity_types(types, check)

+

+ def _signature(self):

+ return tuple(self.asym_units)

+"""Classes to handle alignments between template structure(s)

+ and target sequence(s).

+

+ To create an alignment, first declare a class for the given kind of

+ alignment by deriving from subclasses of :class:`AlignmentMode`

+ (e.g. :class:`Global`) and :class:`AlignmentType` (e.g. :class:`Pairwise`).

+ For example, a typical pairwise global alignment could be declared using::

+

+ class Alignment(modelcif.alignment.Global, modelcif.alignment.Pairwise):

+ pass

+"""

+

+import modelcif.data

+

+

+class Identity:

+ """Percent sequence identity between the template sequence and the target

+ sequence being modeled.

+ Use the correct subclass that corresponds to the denominator used

+ when calculating the identity, for example

+ :class:`ShorterSequenceIdentity`, or if the denominator is not covered

+ here, subclass this class and provide a docstring to describe the

+ denominator, e.g.::

+

+ class CustomIdentity(Identity):

+ "my custom sequence identity denominator"

+

+ :param float value: The percent sequence identity value.

+ """

+ denominator = "Other"

+

+ def __init__(self, value):

+ self.value = value

+

+ def _get_other_details(self):

+ if (type(self) is not Identity

+ and self.denominator == Identity.denominator):

+ return self.__doc__.split('\n')[0]

+

+ other_details = property(

+ _get_other_details,

+ doc="More information about a custom sequence identity denominator. "

+ "By default it is the first line of the docstring.")

+

+

+class ShorterSequenceIdentity(Identity):

+ """Sequence identity calculated using the length of the shorter sequence

+ as the denominator.

+ See :class:`Identity` for more information."""

+ other_details = None

+ denominator = "Length of the shorter sequence"

+

+

+class AlignedPositionsIdentity(Identity):

+ """Sequence identity calculated using the number of aligned positions

+ (including gaps) as the denominator.

+ See :class:`Identity` for more information."""

+ other_details = None

+ denominator = "Number of aligned positions (including gaps)"

+

+

+class AlignedResiduePairsIdentity(Identity):

+ """Sequence identity calculated using the number of aligned residue pairs

+ (not including gaps) as the denominator.

+ See :class:`Identity` for more information."""

+ other_details = None

+ denominator = "Number of aligned residue pairs (not including the gaps)"

+

+

+class MeanSequenceIdentity(Identity):

+ """Sequence identity calculated using the arithmetic mean of the sequence

+ lengths as the denominator.

+ See :class:`Identity` for more information."""

+ other_details = None

+ denominator = "Arithmetic mean sequence length"

+

+

+class Pair:

+ """A single pairwise alignment between a single target and template chain.

+ See :class:`AlignmentMode`. An alignment consists of one or more of

+ these pairs.

+

+ :param template: The template segment that is aligned, i.e. the

+ seq_id range for the template and the sequence (including gaps)

+ of one-letter codes.

+ :type template: :class:`modelcif.TemplateSegment`

+ :param target: The target segment that is aligned.

+ :type target: output from :meth:`ihm.AsymUnit.segment`

+ :param identity: The sequence identity between target and template,

+ if known.

+ :type identity: :class:`Identity`

+ :param score: A measure of the quality of the alignment, if known.

+ :type score: :class:`Score`

+ """

+ def __init__(self, template, target, identity=None, score=None):

+ self.template, self.target, self.score = template, target, score

+ self.identity = identity

+

+

+class AlignmentMode(modelcif.data.Data):

+ """Base class for all alignments. Actual alignments should derive

+ from both a subclass of this class (e.g. :class:`Global`) and a

+ subclass of :class:`AlignmentType`.

+

+ :param str name: A short description of this alignment.

+ :param pairs: List of individual target-template alignments.

+ :type pairs: list of :class:`Pair` objects

+ :param software: The software that was used to build the alignment.

+ :type software: :class:`modelcif.Software`

+ or :class:`modelcif.SoftwareGroup`

+ """

+ data_content_type = 'target-template alignment'

+

+ def __init__(self, name, pairs, software=None):

+ modelcif.data.Data.__init__(self, name)

+ self.pairs = pairs

+ self.software = software

+

+

+class Global(AlignmentMode):

+ """Base class for global alignments. See :class:`AlignmentMode` for

+ more details."""

+ mode = "global"

+

+

+class Local(AlignmentMode):

+ """Base class for local alignments. See :class:`AlignmentMode` for

+ more details."""

+ mode = "local"

+

+

+class AlignmentType:

+ """Base class for all alignment types. Actual alignments should derive

+ from both a subclass of this class (e.g. :class:`Pairwise`) and a

+ subclass of :class:`AlignmentMode`.

+ """

+ type = "other"

+

+

+class Pairwise(AlignmentType):

+ """An alignment between a single target and template.

+ See :class:`AlignmentType` for more details."""

+ type = "target-template pairwise alignment"

+ other_details = None

+

+

+class Multiple(AlignmentType):

+ """A multiple sequence alignment between target and template.

+ See :class:`AlignmentType` for more details."""

+ type = "target-template MSA"

+ other_details = None

+

+

+class Score:

+ """Base class for a quality score for a given target-template alignment.

+ Usually a derived class such as :class:`BLASTEValue` is used, and

+ passed to :class:`Pair` objects.

+

+ :param float value: The actual score value.

+ """

+ type = "Other"

+

+ def __init__(self, value):

+ self.value = value

+

+

+class BLASTEValue(Score):

+ """BLAST e-value for an alignment. See :class:`Score` for more details."""

+ type = "BLAST e-value"

+ other_details = None

+

+

+class HHblitsEValue(Score):

+ """E-value computed by HHblits for an alignment. See :class:`Score` for

+ more details."""

+ type = "HHblits e-value"

+ other_details = None

+"""Classes to associate extra files with the system.

+

+ Typically, one or more :class:`Repository` objects are created and

+ added to :attr:`modelcif.System.repositories`."""

+

+import posixpath

+import warnings

+

+

+class Repository:

+ """An online location where associated files can be found.

+ These objects are typically added to

+ :attr:`modelcif.System.repositories`.

+

+ :param str url_root: URL root that prefixes each file's path.

+ For example, if url_root is ``https://example.com`` then

+ a :class:`File` with path ``test.txt`` can be found at

+ ``https://example.com/test.txt``. If the files are not

+ available online, None can be used here.

+ :param list files: A list of :class:`File` objects.

+ """

+ def __init__(self, url_root, files):

+ self.url_root = url_root

+ self.files = files

+

+ def get_url(self, f):

+ """Get the full URL for the given :class:`File`"""

+ return posixpath.join(self.url_root or '', f.path)

+

+

+class File:

+ """A single associated file. These objects can be added to a

+ :class:`Repository` or a :class:`ZipFile`.

+

+ :param str path: File name.

+ :param str details: Any additional information about the file.

+ :param data: If available, the data (e.g. sequence, structure,

+ alignment) that are stored in the file.

+ :type data: :class:`~modelcif.data.Data`

+ """

+ file_type = 'file'

+ file_content = 'other'

+ file_format = 'other'

+

+ def __init__(self, path, details=None, data=None):

+ self.path, self.details, self.data = path, details, data

+

+

+class CIFFile(File):

+ """An associated file in mmCIF or BinaryCIF format.

+ See :class:`File` for more details.

+

+ :param str path: File name that will be used to construct URLs in the

+ main mmCIF file (see :class:`Repository` or :class:`ZipFile`).

+ :param str details: Any additional information about the file.

+ :param data: If available, the data (e.g. sequence, structure,

+ alignment) that are stored in the file.

+ :type data: :class:`~modelcif.data.Data`

+ :param list categories: If given, any mmCIF category names in this list

+ are written out to ``local_path`` by

+ :func:`modelcif.dumper.write` instead of to the primary file

+ handle.

+ :param list copy_categories: If given, any mmCIF category names in this

+ list are written out to both ``local_path`` by

+ :func:`modelcif.dumper.write` and the primary file handle.

+ :param str entry_id: Unique identifier for the associated file,

+ if written (by specifying ``categories`` or ``copy_categories``).

+ :param str entry_details: A comment to be added to the associated file,

+ if written (by specifying ``categories`` or ``copy_categories``).

+ :param str local_path: File name that will be used for ``categories``

+ or ``copy_categories``. If not given, it defaults to the same

+ as ``path``. (The file is always written directly to the local

+ disk, even if this object is placed inside a :class:`ZipFile`.)

+ :param bool binary: If False (the default), any output file is written

+ in mmCIF format; if True, the file is written in BinaryCIF.

+ """

+

+ _binary_ff_map = {True: 'bcif', False: 'cif'}

+

+ file_format = property(lambda self: self._binary_ff_map[self.binary],

+ doc="Format of the file (BinaryCIF or mmCIF)")

+

+ def __init__(self, path, details=None, categories=[], copy_categories=[],

+ entry_id='model', entry_details=None, local_path=None,

+ binary=False, data=None):

+ super(CIFFile, self).__init__(path, details, data)

+ self.categories = categories

+ self.copy_categories = copy_categories

+ self.id = entry_id

+ self.entry_details = entry_details

+ self.local_path = local_path or path

+ self.binary = binary

+

+

+class QAMetricsFile(CIFFile):

+ """An associated file in CIF format containing QA metrics.

+ See :class:`CIFFile` for more details.

+ """

+ file_content = 'QA metrics'

+

+

+# Map old class name to new equivalent

+class LocalPairwiseQAScoresFile(QAMetricsFile):

+ def __init__(self, *args, **keys):

+ warnings.warn("LocalPairwiseQAScoresFile is deprecated. "

+ "Use QAMetricsFile instead.", stacklevel=2)

+ super(LocalPairwiseQAScoresFile, self).__init__(*args, **keys)

+

+

+class ZipFile(File):

+ """An associated archive file in zip format, containing other files.

+ See :class:`File` for more details.

+

+ :param list files: A list of the :class:`File` objects contained

+ within this archive. Note that an archive cannot contain another

+ archive.

+ """

+ file_type = 'archive'

+ file_content = 'archive with multiple files'

+ file_format = 'zip'

+

+ def __init__(self, path, details=None, files=[], data=None):

+ super(ZipFile, self).__init__(path, details, data)

+ self.files = files

+"""Classes to track inputs/outputs of modeling protocols.

+

+ See also :class:`modelcif.protocol.Step`.

+"""

+

+

+class Data:

+ """Some part of the system that is input or output by part of

+ the modeling protocol, and/or stored in a file.

+

+ Usually a subclass is passed to :class:`modelcif.protocol.Step`

+ to describe the input or output, or to :class:`modelcif.associated.File`

+ to point to where the data are stored:

+

+ - A database of possible template sequences/structures to construct

+ or search (:class:`modelcif.ReferenceDatabase`)

+ - A template structure (:class:`modelcif.Template`)

+ - The sequence of the target (:class:`modelcif.Entity`)

+ - A target-template alignment (:mod:`modelcif.alignment`)

+ - Target structure coordinates (:class:`modelcif.model.Model`)

+

+ However, this class can also be used directly to describe other kinds

+ of input/output data.

+

+ :param str name: A short name for the data.

+ :param str details: A longer description of the data.

+ """

+ data_content_type = 'other'

+ data_other_details = None

+

+ def __init__(self, name, details=None):

+ self.name = name

+ self.data_other_details = details

+

+

+class DataGroup(list):

+ """A number of :class:`Data` objects that are grouped together.

+

+ This class can be used to group together multiple :class:`Data`

+ objects if a given modeling protocol step consumes or generates

+ multiple pieces of data. See :class:`modelcif.protocol.Step`. It behaves

+ like a regular Python list.

+ """

+ pass

+"""Classes to describe the chemistry of custom chemical components.

+

+ If a given :class:`ihm.ChemComp` is not defined in either the wwPDB

+ chemical component dictionary (CCD) or the ModelArchive CCD, its

+ chemistry can be described with one or more of these objects. They

+ are passed as the ``descriptors`` argument when creating a new

+ :class:`ihm.ChemComp`.

+"""

+

+

+class Descriptor:

+ """Base class for all descriptors.

+ This class is generally not used directly; instead, a subclass

+ such as :class:`IUPACName` or :class:`InChI` is employed.

+

+ :param str value: The actual name or identifier describing

+ the chemistry.

+ :param str details: Additional details about this descriptor.

+ :param software: The software used to generate the descriptor, if any.

+ :type software: :class:`modelcif.Software`

+ """

+

+ def __init__(self, value, details=None, software=None):

+ self.value, self.details = value, details

+ self.software = software

+

+ def __repr__(self):

+ return "<%s(%s)>" % (self.__class__.__name__, repr(self.value))

+

+

+class CanonicalSMILES(Descriptor):

+ """Simplified Molecular-Input Line-Entry System (SMILES) computed from

+ chemical structure devoid of isotopic and stereochemical information."""

+ type = 'Canonical SMILES'

+

+

+class IsomericSMILES(Descriptor):

+ """Simplified Molecular-Input Line-Entry System (SMILES) computed from

+ chemical structure containing isotopic and stereochemical information.

+

+ SMILES written with isotopic and chiral specifications are collectively

+ known as isomeric SMILES."""

+ type = 'Isomeric SMILES'

+

+

+class IUPACName(Descriptor):

+ """Chemical name computed from chemical structure that uses International

+ Union of Pure and Applied Chemistry (IUPAC) nomenclature standards."""

+ type = 'IUPAC Name'

+

+

+class InChI(Descriptor):

+ """International Chemical Identifier (InChI) computed from chemical

+ structure using the International Union of Pure and Applied Chemistry

+ (IUPAC) standard."""

+ type = 'InChI'

+

+

+class InChIKey(Descriptor):

+ """International Chemical Identifier hash (InChIKey) computed from

+ chemical structure using the International Union of Pure and Applied

+ Chemistry (IUPAC) standard."""

+ type = 'InChI Key'

+

+

+class PubChemCID(Descriptor):

+ """PubChem Compound ID."""

+ type = 'PubChem CID'

+"""Utility classes to dump out information in mmCIF or BinaryCIF format"""

+

+from datetime import date

+import itertools

+import operator

+import ihm.dumper

+import ihm

+from ihm import util

+import ihm.format

+import ihm.format_bcif

+from ihm.dumper import Dumper, Variant, _prettyprint_seq, _get_transform

+import modelcif.qa_metric

+import modelcif.data

+

+

+class _AuditConformDumper(Dumper):

+ URL = ("https://raw.githubusercontent.com/ihmwg/ModelCIF/%s/dist/" +

+ "mmcif_ma.dic")

+

+ def dump(self, system, writer):

+ with writer.category("_audit_conform") as lp:

+ # Update to match the version of the ModelCIF dictionary

+ # we support:

+ lp.write(dict_name="mmcif_ma.dic", dict_version="1.4.7",

+ dict_location=self.URL % "80e1e22")

+

+

+class _EntryLinkDumper(Dumper):

+ def dump(self, system, writer):

+ with writer.loop("_entry_link", ["id", "entry_id", "details"]) as lp:

+ lp.write(id=1, entry_id=system.id, details=system.entry_details)

+

+

+class _DatabaseDumper(Dumper):

+ def dump(self, system, writer):

+ if system.database:

+ with writer.category("_database_2") as lp:

+ lp.write(database_id=system.database.id,

+ database_code=system.database.code)

+

+

+class _ChemCompDumper(Dumper):

+ # Similar to ihm.dumper._ChemCompDumper, but we need to also include

+ # components referenced only by Templates, as their Entities are not

+ # included in system.entities by default

+

+ _prov_map = {'core': 'CCD Core', 'ma': 'CCD MA', 'local': 'CCD local'}

+

+ def _get_entities(self, system):

+ return itertools.chain(

+ system.entities, (t.entity for t in system.templates))

+

+ def _get_provenance(self, comp):

+ ccd = comp.ccd

+ if ccd is None:

+ ccd = 'core'

+ if comp.descriptors:

+ ccd = 'local'

+ val = self._prov_map.get(ccd)

+ if not val:

+ if not self._check:

+ return ihm.unknown

+ raise KeyError("Invalid ccd value %s for %s; can be %s, or None"

+ % (repr(comp.ccd), comp,

+ ", ".join(sorted(self._prov_map.keys()))))

+ return val

+

+ def dump(self, system, writer):

+ comps = frozenset(

+ comp for e in self._get_entities(system) for comp in e.sequence)

+

+ with writer.loop("_chem_comp", ["id", "type", "name",

+ "formula", "formula_weight",

+ "ma_provenance"]) as lp:

+ for comp in sorted(comps, key=operator.attrgetter('id')):

+ lp.write(id=comp.id, type=comp.type, name=comp.name,

+ formula=comp.formula,

+ formula_weight=comp.formula_weight,

+ ma_provenance=self._get_provenance(comp))

+

+

+class _ChemCompDescriptorDumper(Dumper):

+ def _get_entities(self, system):

+ return itertools.chain(

+ system.entities, (t.entity for t in system.templates))

+

+ def dump(self, system, writer):

+ ordinal = itertools.count(1)

+ comps = frozenset(

+ comp for e in self._get_entities(system) for comp in e.sequence)

+

+ with writer.loop("_ma_chem_comp_descriptor",

+ ["ordinal_id", "chem_comp_id", "chem_comp_name",

+ "type", "value", "details", "software_id"]) as lp:

+ for comp in sorted(comps, key=operator.attrgetter('id')):

+ if not hasattr(comp, 'descriptors') or not comp.descriptors:

+ continue

+ for desc in comp.descriptors:

+ lp.write(ordinal_id=next(ordinal), chem_comp_id=comp.id,

+ chem_comp_name=comp.name, type=desc.type,

+ value=desc.value, details=desc.details,

+ software_id=desc.software._id

+ if desc.software else None)

+

+

+class _TargetRefDBDumper(Dumper):

+ def dump(self, system, writer):

+ with writer.loop(

+ "_ma_target_ref_db_details",

+ ["target_entity_id", "db_name", "db_name_other_details",

+ "db_code", "db_accession", "seq_db_isoform",

+ "seq_db_align_begin", "seq_db_align_end",

+ "ncbi_taxonomy_id", "organism_scientific",

+ "seq_db_sequence_version_date",

+ "seq_db_sequence_checksum",

+ "is_primary"]) as lp:

+ for e in system.entities:

+ for r in e.references:

+ if r.align_begin is None:

+ db_begin = min(a.db_begin for a in r._get_alignments())

+ else:

+ db_begin = r.align_begin

+ if r.align_end is None:

+ aligns = [a for a in r._get_alignments()

+ if a.db_end is not None]

+ if aligns:

+ db_end = max(a.db_end for a in aligns)

+ else:

+ db_end = len(r.sequence)

+ else:

+ db_end = r.align_end

+ lp.write(target_entity_id=e._id, db_name=r.name,

+ db_name_other_details=r.other_details,

+ db_code=r.code, db_accession=r.accession,

+ seq_db_isoform=r.isoform,

+ seq_db_align_begin=db_begin,

+ seq_db_align_end=db_end,

+ ncbi_taxonomy_id=r.ncbi_taxonomy_id,

+ organism_scientific=r.organism_scientific,

+ seq_db_sequence_version_date=date.isoformat(

+ r.sequence_version_date)

+ if r.sequence_version_date else None,

+ seq_db_sequence_checksum=r.sequence_crc64,

+ is_primary=r.is_primary)

+

+

+class _EntityNonPolyDumper(Dumper):

+ def finalize(self, system):

+ self._ma_model_mode_map = {}

+ expmap = {True: 'explicit', False: 'implicit'}

+ for a in system.asym_units:

+ if isinstance(a, modelcif.NonPolymerFromTemplate):

+ self._ma_model_mode_map[a.template.entity] = \

+ expmap.get(a.explicit)

+

+ def dump(self, system, writer):

+ with writer.loop("_pdbx_entity_nonpoly",

+ ["entity_id", "name", "comp_id",

+ "ma_model_mode"]) as lp:

+ for entity in system.entities:

+ if entity.is_polymeric():

+ continue

+ lp.write(entity_id=entity._id, name=entity.description,

+ comp_id=entity.sequence[0].id,

+ ma_model_mode=self._ma_model_mode_map.get(entity))

+

+

+class _TargetEntityDumper(Dumper):

+ def dump(self, system, writer):

+ with writer.loop(

+ "_ma_target_entity",

+ ["entity_id", "data_id", "origin"]) as lp:

+ for e in system.entities:

+ lp.write(entity_id=e._id, data_id=e._data_id,

+ origin="reference database" if e.references

+ else "designed")

+

+ with writer.loop(

+ "_ma_target_entity_instance",

+ ["asym_id", "entity_id", "details"]) as lp:

+ for asym in system.asym_units:

+ lp.write(asym_id=asym._id, entity_id=asym.entity._id,

+ details=asym.details)

+

+

+class _SoftwareGroupDumper(Dumper):

+ def finalize(self, system):

+ # Map from id(list) to id

+ self._param_group_id = {}

+ self._param_groups = []

+ for n, s in enumerate(system.software_groups):

+ # Use _group_id rather than _id as the "group" might be a

+ # singleton Software, which already has its own id

+ s._group_id = n + 1

+ if isinstance(s, modelcif.SoftwareGroup):

+ for soft in s:

+ if (isinstance(soft, modelcif.SoftwareWithParameters)

+ and soft.parameters

+ and id(soft.parameters)

+ not in self._param_group_id):

+ self._param_groups.append(soft.parameters)

+ self._param_group_id[id(soft.parameters)] \

+ = len(self._param_groups)

+

+ def dump(self, system, writer):

+ self.dump_parameters(system, writer)

+ self.dump_groups(system, writer)

+

+ def dump_groups(self, system, writer):

+ ordinal = itertools.count(1)

+ with writer.loop(

+ "_ma_software_group",

+ ["ordinal_id", "group_id", "software_id",

+ "parameter_group_id"]) as lp:

+ for g in system.software_groups:

+ if isinstance(g, modelcif.Software):

+ # If a singleton Software, write a group containing one

+ # member

+ lp.write(ordinal_id=next(ordinal), group_id=g._group_id,

+ software_id=g._id)

+ else:

+ for s in g:

+ param = None

+ if isinstance(s, modelcif.SoftwareWithParameters):

+ soft_id = s.software._id

+ if s.parameters:

+ param = self._param_group_id[id(s.parameters)]

+ else:

+ soft_id = s._id

+ lp.write(ordinal_id=next(ordinal),

+ group_id=g._group_id, software_id=soft_id,

+ parameter_group_id=param)

+

+ def _handle_list(self, value):

+ list_type_map = {int: 'integer-csv', float: 'float-csv'}

+ types = frozenset(type(x) for x in value)

+ if types == frozenset((int,)):

+ data_type = list_type_map[int]

+ elif types == frozenset((float,)) or types == frozenset((int, float)):

+ # Treat mix of int and float as float

+ data_type = list_type_map[float]

+ else:

+ raise TypeError("Only lists of ints or floats are supported")

+ return data_type, ",".join(str(x) for x in value)

+

+ def dump_parameters(self, system, writer):

+ parameter_id = itertools.count(1)

+ type_map = {int: "integer", float: "float", str: "string",

+ bool: "boolean"}

+ with writer.loop(

+ "_ma_software_parameter",

+ ["parameter_id", "group_id", "data_type",

+ "name", "value", "description"]) as lp:

+ for g in self._param_groups:

+ group_id = self._param_group_id[id(g)]

+ for p in g:

+ if isinstance(p.value, (list, tuple)):

+ data_type, value = self._handle_list(p.value)

+ else:

+ data_type = type_map.get(type(p.value), str)

+ value = p.value

+ lp.write(parameter_id=next(parameter_id),

+ group_id=group_id, data_type=data_type,

+ name=p.name, value=value,

+ description=p.description)

+

+

+class _DataDumper(Dumper):

+ def finalize(self, system):

+ for n, d in enumerate(system.data):

+ d._data_id = n + 1

+

+ def dump(self, system, writer):

+ with writer.loop(

+ "_ma_data",

+ ["id", "name", "content_type",

+ "content_type_other_details"]) as lp:

+ for d in system.data:

+ # ihm.Entity isn't a subclass of Data, so we need

+ # to fill in missing attributes here

+ if isinstance(d, ihm.Entity):

+ lp.write(id=d._data_id, name=d.description,

+ content_type="target",

+ content_type_other_details=None)

+ else:

+ lp.write(id=d._data_id, name=d.name,

+ content_type=d.data_content_type,

+ content_type_other_details=d.data_other_details)

+

+

+class _DataGroupDumper(Dumper):

+ def finalize(self, system):

+ for n, d in enumerate(system.data_groups):

+ # Use _data_group_id rather than _id as the "group" might be a

+ # singleton Data, which already has its own id

+ d._data_group_id = n + 1

+

+ def dump(self, system, writer):

+ ordinal = itertools.count(1)

+ with writer.loop(

+ "_ma_data_group",

+ ["ordinal_id", "group_id", "data_id"]) as lp:

+ for g in system.data_groups:

+ if isinstance(g, (modelcif.data.Data, ihm.Entity)):

+ # If a singleton Data (or ihm.Entity, which isn't a

+ # subclass of Data), write a group containing one member

+ lp.write(ordinal_id=next(ordinal),

+ group_id=g._data_group_id, data_id=g._data_id)

+ else:

+ for d in g:

+ lp.write(ordinal_id=next(ordinal),

+ group_id=g._data_group_id, data_id=d._data_id)

+

+

+class _DataRefDBDumper(Dumper):

+ def dump(self, system, writer):

+ with writer.loop(

+ "_ma_data_ref_db",

+ ["data_id", "name", "location_url",

+ "version", "release_date"]) as lp:

+ for d in system.data:

+ if not isinstance(d, modelcif.ReferenceDatabase):

+ continue

+ lp.write(data_id=d._data_id, name=d.name, location_url=d.url,

+ version=d.version,

+ release_date=date.isoformat(d.release_date)

+ if d.release_date else None)

+

+

+class _TemplateTransformDumper(Dumper):

+ def finalize(self, system):

+ for n, trans in enumerate(system.template_transformations):

+ trans._id = n + 1

+

+ def dump(self, system, writer):

+ with writer.loop(

+ "_ma_template_trans_matrix",

+ ["id",

+ "rot_matrix[1][1]", "rot_matrix[2][1]", "rot_matrix[3][1]",

+ "rot_matrix[1][2]", "rot_matrix[2][2]", "rot_matrix[3][2]",

+ "rot_matrix[1][3]", "rot_matrix[2][3]", "rot_matrix[3][3]",

+ "tr_vector[1]", "tr_vector[2]", "tr_vector[3]"]) as lp:

+ for t in system.template_transformations:

+ lp.write(id=t._id,

+ **_get_transform(t.rot_matrix, t.tr_vector))

+

+

+class _AlignmentDumper(Dumper):

+ def finalize(self, system):

+ for n, tmpl in enumerate(system.templates):

+ tmpl._id = n + 1

+ for n, segment in enumerate(system.template_segments):

+ # Cannot use _id since segment might also be a complete template

+ # (with _id = template id)

+ segment._segment_id = n + 1

+ for n, aln in enumerate(system.alignments):

+ aln._id = n + 1

+

+ def dump(self, system, writer):

+ self.dump_template_details(system, writer)

+ self.dump_template_poly(system, writer)

+ self.dump_template_poly_segment(system, writer)

+ self.dump_template_non_poly(system, writer)

+ self.dump_template_ref_db(system, writer)

+ self.dump_target_template_poly_mapping(system, writer)

+ self.dump_template_customized(system, writer)

+ self.dump_template_coord(system, writer)

+ self.dump_info(system, writer)

+ self.dump_details(system, writer)

+ self.dump_sequences(system, writer)

+

+ def dump_template_details(self, system, writer):

+ ordinal = itertools.count(1)

+

+ def write_template(tmpl, tgt_asym, lp):

+ org = ("customized" if isinstance(tmpl, modelcif.CustomTemplate)

+ else "reference database")

+ poly = ("polymer" if tmpl.entity.is_polymeric()

+ else "non-polymer")

+ lp.write(ordinal_id=next(ordinal),

+ template_id=tmpl._id,

+ template_origin=org,

+ template_entity_type=poly,

+ template_trans_matrix_id=tmpl.transformation._id,

+ template_data_id=tmpl._data_id,

+ target_asym_id=tgt_asym._id if tgt_asym else None,

+ template_label_asym_id=tmpl.asym_id,

+ template_label_entity_id=tmpl.entity_id,

+ template_model_num=tmpl.model_num,

+ template_auth_asym_id=tmpl.strand_id)

+

+ with writer.loop(

+ "_ma_template_details",

+ ["ordinal_id", "template_id", "template_origin",

+ "template_entity_type", "template_trans_matrix_id",

+ "template_data_id", "target_asym_id",

+ "template_label_asym_id",

+ "template_label_entity_id", "template_model_num",

+ "template_auth_asym_id"]) as lp:

+ seen_templates = set()

+ for a in system.alignments:

+ for s in a.pairs:

+ # get Template from TemplateSegment

+ write_template(s.template.template, s.target.asym, lp)

+ seen_templates.add(s.template.template)

+ # Handle all non-polymer templates (not in alignments)

+ for a in system.asym_units:

+ if isinstance(a, modelcif.NonPolymerFromTemplate):

+ write_template(a.template, a, lp)

+ seen_templates.add(a.template)

+ # Handle all remaining non-aligned templates

+ for t in system.templates:

+ if t not in seen_templates:

+ write_template(t, None, lp)

+

+ def _get_sequence(self, entity):

+ """Get the sequence for an entity as a string"""

+ # Split into lines to get tidier CIF output

+ return "\n".join(_prettyprint_seq((comp.code if len(comp.code) == 1

+ else '(%s)' % comp.code

+ for comp in entity.sequence), 70))

+

+ def _get_canon(self, entity):

+ """Get the canonical sequence for an entity as a string"""

+ # Split into lines to get tidier CIF output

+ seq = "\n".join(_prettyprint_seq(

+ (comp.code_canonical for comp in entity.sequence), 70))

+ return seq

+

+ def dump_template_poly(self, system, writer):

+ with writer.loop(

+ "_ma_template_poly",

+ ["template_id", "seq_one_letter_code",

+ "seq_one_letter_code_can"]) as lp:

+ for tmpl in system.templates:

+ entity = tmpl.entity

+ if not entity.is_polymeric():

+ continue

+ lp.write(template_id=tmpl._id,

+ seq_one_letter_code=self._get_sequence(entity),

+ seq_one_letter_code_can=self._get_canon(entity))

+

+ def dump_template_poly_segment(self, system, writer):

+ with writer.loop("_ma_template_poly_segment",

+ ["id", "template_id", "residue_number_begin",

+ "residue_number_end"]) as lp:

+ for s in system.template_segments:

+ lp.write(

+ id=s._segment_id, template_id=s.template._id,

+ residue_number_begin=s.seq_id_range[0],

+ residue_number_end=s.seq_id_range[1])

+

+ def dump_template_non_poly(self, system, writer):

+ with writer.loop(

+ "_ma_template_non_poly",

+ ["template_id", "comp_id", "details"]) as lp:

+ for tmpl in system.templates:

+ entity = tmpl.entity

+ if entity.is_polymeric():

+ continue

+ lp.write(template_id=tmpl._id, comp_id=entity.sequence[0].id,

+ details=entity.description)

+

+ def dump_template_ref_db(self, system, writer):

+ with writer.loop(

+ "_ma_template_ref_db_details",

+ ["template_id", "db_name", "db_name_other_details",

+ "db_accession_code", "db_version_date"]) as lp:

+ for tmpl in system.templates:

+ if not isinstance(tmpl, modelcif.Template):

+ continue

+ for ref in tmpl.references:

+ lp.write(template_id=tmpl._id, db_name=ref.name,

+ db_name_other_details=ref.other_details,

+ db_accession_code=ref.accession,

+ db_version_date=date.isoformat(

+ ref.db_version_date)

+ if ref.db_version_date else None)

+

+ def dump_template_customized(self, system, writer):

+ with writer.loop(

+ "_ma_template_customized", ["template_id", "details"]) as lp:

+ for tmpl in system.templates:

+ if isinstance(tmpl, modelcif.CustomTemplate):

+ lp.write(template_id=tmpl._id, details=tmpl.details)

+

+ def dump_template_coord(self, system, writer):

+ ordinal = itertools.count(1)

+ with writer.loop(

+ "_ma_template_coord",

+ ["template_id", "group_PDB", "ordinal_id", "type_symbol",

+ "label_atom_id", "label_comp_id", "label_seq_id",

+ "label_asym_id", "auth_seq_id", "auth_asym_id",

+ "auth_atom_id", "auth_comp_id",

+ "Cartn_x", "Cartn_y", "Cartn_z",

+ "occupancy", "label_entity_id", "B_iso_or_equiv",

+ "formal_charge"]) as lp:

+ for tmpl in system.templates:

+ if not isinstance(tmpl, modelcif.CustomTemplate):

+ continue

+ e = tmpl.entity

+ for atom in tmpl.atoms:

+ lp.write(template_id=tmpl._id,

+ group_PDB='HETATM' if atom.het else 'ATOM',

+ ordinal_id=next(ordinal),

+ type_symbol=atom.type_symbol,

+ label_atom_id=atom.atom_id,

+ label_comp_id=e.sequence[atom.seq_id - 1].id,

+ label_seq_id=atom.seq_id,

+ label_asym_id=tmpl.asym_id,

+ auth_seq_id=atom.auth_seq_id,

+ auth_asym_id=tmpl.strand_id,

+ auth_atom_id=atom.auth_atom_id,

+ auth_comp_id=atom.auth_comp_id,

+ Cartn_x=atom.x, Cartn_y=atom.y, Cartn_z=atom.z,

+ occupancy=atom.occupancy,

+ label_entity_id=tmpl.entity_id,

+ B_iso_or_equiv=atom.biso,

+ formal_charge=atom.charge)

+

+ def dump_target_template_poly_mapping(self, system, writer):

+ ordinal = itertools.count(1)

+ with writer.loop("_ma_target_template_poly_mapping",

+ ["id", "template_segment_id", "target_asym_id",

+ "target_seq_id_begin", "target_seq_id_end"]) as lp:

+ for a in system.alignments:

+ for p in a.pairs:

+ lp.write(

+ id=next(ordinal),

+ template_segment_id=p.template._segment_id,

+ target_asym_id=p.target.asym._id,

+ target_seq_id_begin=p.target.seq_id_range[0],

+ target_seq_id_end=p.target.seq_id_range[1])

+

+ def dump_info(self, system, writer):

+ with writer.loop(

+ "_ma_alignment_info",

+ ["alignment_id", "data_id", "software_group_id",

+ "alignment_length", "alignment_type",

+ "alignment_mode"]) as lp:

+ for a in system.alignments:

+ if a.pairs:

+ align_len = max(len(s.gapped_sequence) for pair in a.pairs

+ for s in (pair.template, pair.target))

+ else:

+ align_len = None

+ lp.write(alignment_id=a._id, data_id=a._data_id,

+ software_group_id=a.software._group_id if a.software

+ else None,

+ alignment_type=a.type, alignment_mode=a.mode,

+ alignment_length=align_len,

+ alignment_type_other_details=a.other_details)

+

+ def dump_details(self, system, writer):

+ ordinal = itertools.count(1)

+ with writer.loop(

+ "_ma_alignment_details",

+ ["ordinal_id", "alignment_id", "template_segment_id",

+ "target_asym_id", "score_type",

+ "score_type_other_details", "score_value",

+ "percent_sequence_identity",

+ "sequence_identity_denominator",

+ "sequence_identity_denominator_other_details"]) as lp:

+ for a in system.alignments:

+ for s in a.pairs:

+ if s.identity is None:

+ denom = od = identity = None

+ else:

+ denom = s.identity.denominator

+ od = s.identity.other_details

+ identity = s.identity.value

+ if s.score is None:

+ score_type = score_other_details = score_value = None

+ else:

+ score_type = s.score.type

+ score_other_details = s.score.other_details

+ score_value = s.score.value

+ lp.write(ordinal_id=next(ordinal), alignment_id=a._id,

+ template_segment_id=s.template._segment_id,

+ target_asym_id=s.target.asym._id,

+ score_type=score_type,

+ score_type_other_details=score_other_details,

+ score_value=score_value,

+ percent_sequence_identity=identity,

+ sequence_identity_denominator=denom,

+ sequence_identity_denominator_other_details=od)

+

+ def dump_sequences(self, system, writer):

+ ordinal = itertools.count(1)

+ with writer.loop(

+ "_ma_alignment",

+ ["ordinal_id", "alignment_id", "target_template_flag",

+ "sequence"]) as lp:

+ for a in system.alignments:

+ # todo: don't duplicate sequences

+ for s in a.pairs:

+ # 1=target, 2=template

+ lp.write(ordinal_id=next(ordinal), alignment_id=a._id,

+ target_template_flag=1,

+ sequence=s.target.gapped_sequence)

+ lp.write(ordinal_id=next(ordinal), alignment_id=a._id,

+ target_template_flag=2,

+ sequence=s.template.gapped_sequence)

+

+

+class _ProtocolDumper(Dumper):

+ def finalize(self, system):

+ # Assign IDs to protocols and steps

+ for np, p in enumerate(system.protocols):

+ p._id = np + 1

+ for ns, s in enumerate(p.steps):

+ s._id = ns + 1

+

+ def dump(self, system, writer):

+ ordinal = itertools.count(1)

+ with writer.loop(

+ "_ma_protocol_step",

+ ['ordinal_id', 'protocol_id', 'step_id', 'method_type',

+ 'step_name', 'details', 'software_group_id',

+ 'input_data_group_id', 'output_data_group_id']) as lp:

+ for p in system.protocols:

+ for s in p.steps:

+ lp.write(ordinal_id=next(ordinal), protocol_id=p._id,

+ step_id=s._id, method_type=s.method_type,

+ step_name=s.name, details=s.details,

+ software_group_id=s.software._group_id

+ if s.software else None,

+ input_data_group_id=s.input_data._data_group_id

+ if s.input_data else None,

+ output_data_group_id=s.output_data._data_group_id

+ if s.output_data else None)

+

+

+class _ModelDumper(ihm.dumper._ModelDumperBase):

+ def dump(self, system, writer):

+ self.dump_model_list(system, writer)

+ self.dump_model_groups(system, writer)

+ seen_types = self.dump_atoms(system, writer, add_ihm=False)

+ self.dump_atom_type(seen_types, system, writer)

+

+ def dump_model_list(self, system, writer):

+ with writer.loop("_ma_model_list",

+ ["ordinal_id", "model_name",

+ "data_id", "model_type",

+ "model_type_other_details"]) as lp:

+ for group, model in sorted(system._all_models(),

+ key=lambda x: x[1]._id):

+ lp.write(ordinal_id=model._id, model_name=model.name,

+ data_id=model._data_id, model_type=model.model_type,

+ model_type_other_details=model.other_details)

+

+ def dump_model_groups(self, system, writer):

+ self.dump_model_group_summary(system, writer)

+ self.dump_model_group_link(system, writer)

+

+ def dump_model_group_summary(self, system, writer):

+ with writer.loop("_ma_model_group", ["id", "name", "details"]) as lp:

+ for group in system.model_groups:

+ # ihm.model.ModelGroup only supports details after v1.8

+ lp.write(id=group._id, name=group.name,

+ details=group.details

+ if hasattr(group, 'details') else None)

+

+ def dump_model_group_link(self, system, writer):

+ with writer.loop("_ma_model_group_link",

+ ["group_id", "model_id"]) as lp:

+ for group in system.model_groups:

+ for model_id in sorted(set(model._id for model in group)):

+ lp.write(model_id=model_id, group_id=group._id)

+

+

+class _AssociatedDumper(Dumper):

+ def finalize(self, system):

+ file_id = itertools.count(1)

+ in_archive_file_id = itertools.count(1)

+ for repo in system.repositories:

+ for f in repo.files:

+ f._id = next(file_id)

+ if hasattr(f, 'files'):

+ for af in f.files:

+ if hasattr(af, 'files'):

+ raise ValueError(

+ "An archive cannot contain another archive")

+ af._id = next(in_archive_file_id)

+

+ def dump(self, system, writer):

+ self.dump_files(system, writer)

+ self.dump_archive_files(system, writer)

+

+ def dump_files(self, system, writer):

+ with writer.loop(

+ "_ma_entry_associated_files",

+ ["id", "entry_id", "file_url", "file_type", "file_format",

+ "file_content", "details", "data_id"]) as lp:

+ for repo in system.repositories:

+ for f in repo.files:

+ lp.write(id=f._id, entry_id=system.id,

+ file_url=repo.get_url(f), file_type=f.file_type,

+ file_format=f.file_format,

+ file_content=f.file_content, details=f.details,

+ data_id=f.data._data_id if f.data else None)

+

+ def dump_archive_files(self, system, writer):

+ with writer.loop(

+ "_ma_associated_archive_file_details",

+ ["id", "archive_file_id", "file_path", "file_format",

+ "file_content", "description", "data_id"]) as lp:

+ for repo in system.repositories:

+ for f in repo.files:

+ if not hasattr(f, 'files'):

+ continue

+ for af in f.files:

+ lp.write(id=af._id, archive_file_id=f._id,

+ file_path=af.path, file_format=af.file_format,

+ file_content=af.file_content,

+ description=af.details,

+ data_id=af.data._data_id if af.data else None)

+

+

+class _FeatureDumper(Dumper):

+ def finalize(self, system):

+ seen_features = {}

+ self._features_by_id = []

+ for f in system._all_features():

+ util._remove_id(f)

+ for f in system._all_features():

+ util._assign_id(f, seen_features, self._features_by_id,

+ seen_obj=f._signature())

+

+ def dump(self, system, writer):

+ self.dump_list(writer)

+ self.dump_atom(writer)

+ self.dump_residue(writer)

+ self.dump_instance(writer)

+

+ def dump_list(self, writer):

+ with writer.loop("_ma_feature_list",

+ ["feature_id", "feature_type", "entity_type",

+ "details"]) as lp:

+ for f in self._features_by_id:

+ lp.write(feature_id=f._id, feature_type=f.type,

+ entity_type=f._get_entity_type(check=self._check),

+ details=f.details)

+

+ def dump_atom(self, writer):

+ ordinal = itertools.count(1)

+ with writer.loop("_ma_atom_feature",

+ ["ordinal_id", "feature_id", "atom_id"]) as lp:

+ for f in self._features_by_id:

+ if not isinstance(f, modelcif.AtomFeature):

+ continue

+ for a in f.atoms:

+ lp.write(ordinal_id=next(ordinal), feature_id=f._id,

+ atom_id=a)

+

+ def dump_residue(self, writer):

+ ordinal = itertools.count(1)

+ with writer.loop("_ma_poly_residue_feature",

+ ["ordinal_id", "feature_id", "label_asym_id",

+ "label_seq_id", "label_comp_id"]) as lp:

+ for f in self._features_by_id:

+ if not isinstance(f, modelcif.PolyResidueFeature):

+ continue

+ for r in f.residues:

+ seq = r.entity.sequence

+ lp.write(ordinal_id=next(ordinal), feature_id=f._id,

+ label_asym_id=r.asym._id,

+ label_seq_id=r.seq_id,

+ label_comp_id=seq[r.seq_id - 1].id)

+

+ def dump_instance(self, writer):

+ ordinal = itertools.count(1)

+ with writer.loop("_ma_entity_instance_feature",

+ ["ordinal_id", "feature_id", "label_asym_id"]) as lp:

+ for f in self._features_by_id:

+ if not isinstance(f, modelcif.EntityInstanceFeature):

+ continue

+ for a in f.asym_units:

+ lp.write(ordinal_id=next(ordinal), feature_id=f._id,

+ label_asym_id=a._id)

+

+

+class _QAMetricDumper(Dumper):

+ def finalize(self, system):

+ # Get all metric classes used by all systems

+ seen_metric_classes = set()

+ self._metric_classes_by_id = []

+ metric_id = itertools.count(1)

+ for group, model in system._all_models():

+ for m in model.qa_metrics:

+ cls = type(m)

+ if cls not in seen_metric_classes:

+ seen_metric_classes.add(cls)

+ cls._id = next(metric_id)

+ # We need an instance of the class in case name or

+ # description are provided by property()

+ self._metric_classes_by_id.append(m)

+

+ def dump(self, system, writer):

+ self.dump_metric_types(system, writer)

+ self.dump_metric_global(system, writer)

+ self.dump_metric_local(system, writer)

+ self.dump_metric_pairwise(system, writer)

+ self.dump_metric_feature(system, writer)

+ self.dump_metric_feature_pairwise(system, writer)

+

+ def dump_metric_types(self, system, writer):

+ with writer.loop(

+ "_ma_qa_metric",

+ ["id", "name", "description", "type", "mode",

+ "type_other_details", "software_group_id"]) as lp:

+ for m in self._metric_classes_by_id:

+ lp.write(id=m._id, name=m.name, description=m.description,

+ type=m.type, mode=m.mode,

+ type_other_details=m.other_details,

+ software_group_id=m.software._group_id if m.software

+ else None)

+

+ def dump_metric_global(self, system, writer):

+ ordinal = itertools.count(1)

+ with writer.loop(

+ "_ma_qa_metric_global",

+ ["ordinal_id", "model_id", "metric_id", "metric_value"]) as lp:

+ for group, model in system._all_models():

+ for m in model.qa_metrics:

+ if not isinstance(m, modelcif.qa_metric.Global):

+ continue

+ lp.write(ordinal_id=next(ordinal), model_id=model._id,

+ metric_id=m._id, metric_value=m.value)

+

+ def dump_metric_local(self, system, writer):

+ ordinal = itertools.count(1)

+ with writer.loop(

+ "_ma_qa_metric_local",

+ ["ordinal_id", "model_id", "label_asym_id", "label_seq_id",

+ "label_comp_id", "metric_id", "metric_value"]) as lp:

+ for group, model in system._all_models():

+ for m in model.qa_metrics:

+ if not isinstance(m, modelcif.qa_metric.Local):

+ continue

+ seq = m.residue.asym.entity.sequence

+ lp.write(ordinal_id=next(ordinal), model_id=model._id,

+ label_asym_id=m.residue.asym._id,

+ label_seq_id=m.residue.seq_id,

+ label_comp_id=seq[m.residue.seq_id - 1].id,

+ metric_id=m._id, metric_value=m.value)

+

+ def dump_metric_pairwise(self, system, writer):

+ ordinal = itertools.count(1)

+ with writer.loop(

+ "_ma_qa_metric_local_pairwise",

+ ["ordinal_id", "model_id", "label_asym_id_1", "label_seq_id_1",

+ "label_comp_id_1", "label_asym_id_2", "label_seq_id_2",

+ "label_comp_id_2", "metric_id", "metric_value"]) as lp:

+ for group, model in system._all_models():

+ for m in model.qa_metrics:

+ if not isinstance(m, modelcif.qa_metric.LocalPairwise):

+ continue

+ seq1 = m.residue1.asym.entity.sequence

+ seq2 = m.residue2.asym.entity.sequence

+ lp.write(ordinal_id=next(ordinal), model_id=model._id,

+ label_asym_id_1=m.residue1.asym._id,

+ label_seq_id_1=m.residue1.seq_id,

+ label_comp_id_1=seq1[m.residue1.seq_id - 1].id,

+ label_asym_id_2=m.residue2.asym._id,

+ label_seq_id_2=m.residue2.seq_id,

+ label_comp_id_2=seq2[m.residue2.seq_id - 1].id,

+ metric_id=m._id, metric_value=m.value)

+

+ def dump_metric_feature(self, system, writer):

+ ordinal = itertools.count(1)

+ with writer.loop(

+ "_ma_qa_metric_feature",

+ ["ordinal_id", "model_id", "feature_id", "metric_id",

+ "metric_value"]) as lp:

+ for group, model in system._all_models():

+ for m in model.qa_metrics:

+ if not isinstance(m, modelcif.qa_metric.Feature):

+ continue

+ lp.write(ordinal_id=next(ordinal), model_id=model._id,

+ feature_id=m.feature._id,

+ metric_id=m._id, metric_value=m.value)

+

+ def dump_metric_feature_pairwise(self, system, writer):

+ ordinal = itertools.count(1)

+ with writer.loop(

+ "_ma_qa_metric_feature_pairwise",

+ ["ordinal_id", "model_id", "feature_id_1", "feature_id_2",

+ "metric_id", "metric_value"]) as lp:

+ for group, model in system._all_models():

+ for m in model.qa_metrics:

+ if not isinstance(m, modelcif.qa_metric.FeaturePairwise):

+ continue

+ lp.write(ordinal_id=next(ordinal), model_id=model._id,

+ feature_id_1=m.feature1._id,

+ feature_id_2=m.feature2._id,

+ metric_id=m._id, metric_value=m.value)

+

+

+class _CopyWriter:

+ """Context manager to write loop or category to two mmCIF/BinaryCIF

+ files"""

+ def __init__(self, w1, w2):

+ self.w1, self.w2 = w1, w2

+

+ def write(self, *args, **keys):

+ self.w1.write(*args, **keys)

+ self.w2.write(*args, **keys)

+

+ def __enter__(self):

+ return self

+

+ def __exit__(self, exc_type, exc_value, traceback):

+ # This may not correctly handle exceptions raised within the loop

+ self.w1.__exit__(exc_type, exc_value, traceback)

+ self.w2.__exit__(exc_type, exc_value, traceback)

+

+

+class _SystemWriter:

+ """Utility class which normally just passes through to the default

+ ``base_writer``, but outputs selected categories to associated files."""

+ def __init__(self, base_writer, category_map, copy_category_map):

+ self._base_writer = base_writer

+ self.category_map = category_map

+ self.copy_category_map = copy_category_map

+

+ def category(self, category):

+ w = self.copy_category_map.get(category)

+ if w:

+ return _CopyWriter(w.category(category),

+ self._base_writer.category(category))

+ else:

+ w = self.category_map.get(category, self._base_writer)

+ return w.category(category)

+

+ def loop(self, category, keys):

+ w = self.copy_category_map.get(category)

+ if w:

+ return _CopyWriter(w.loop(category, keys),

+ self._base_writer.loop(category, keys))

+ else:

+ w = self.category_map.get(category, self._base_writer)

+ return w.loop(category, keys)

+

+ def end_block(self):

+ # Flush and close all file handles of associated files

+ for w in self.category_map.values():

+ if not hasattr(w, 'fh'):

+ continue

+ w.flush()

+ w.fh.close()

+ del w.fh

+

+ # Just pass through to base writer object

+ def flush(self):

+ return self._base_writer.flush()

+

+ def start_block(self, name):

+ return self._base_writer.start_block(name)

+

+ def write_comment(self, comment):

+ return self._base_writer.write_comment(comment)

+

+

+class ModelCIFVariant(Variant):

+ """Used to select typical PDBx/ModelCIF file output.

+ See :func:`write` and :class:`ihm.dumper.Variant`."""

+ _dumpers = [

+ ihm.dumper._EntryDumper, # must be first

+ ihm.dumper._StructDumper, ihm.dumper._CommentDumper,

+ _AuditConformDumper, _DatabaseDumper, ihm.dumper._CitationDumper,

+ ihm.dumper._SoftwareDumper, _SoftwareGroupDumper,

+ ihm.dumper._AuditAuthorDumper, ihm.dumper._AuditRevisionDumper,

+ ihm.dumper._DataUsageDumper, ihm.dumper._GrantDumper,

+ _ChemCompDumper, _ChemCompDescriptorDumper,

+ ihm.dumper._EntityDumper,

+ ihm.dumper._EntitySrcGenDumper, ihm.dumper._EntitySrcNatDumper,

+ ihm.dumper._EntitySrcSynDumper, ihm.dumper._StructRefDumper,

+ _TargetRefDBDumper,

+ ihm.dumper._EntityPolyDumper, _EntityNonPolyDumper,

+ ihm.dumper._EntityPolySeqDumper, ihm.dumper._StructAsymDumper,

+ ihm.dumper._PolySeqSchemeDumper, ihm.dumper._NonPolySchemeDumper,

+ _DataDumper, _DataGroupDumper, _DataRefDBDumper,

+ _TargetEntityDumper, _TemplateTransformDumper, _AlignmentDumper,

+ _ProtocolDumper, _ModelDumper, _AssociatedDumper, _FeatureDumper,

+ _QAMetricDumper]

+

+ def get_dumpers(self):

+ return [d() for d in self._dumpers]

+

+ def get_system_writer(self, system, writer_class, writer):

+ # Get a Writer-like object which outputs selected categories to

+ # associated files (the rest use the default writer)

+ category_map = {}

+ copy_category_map = {}

+

+ def _all_repo_files(r):

+ for f in r.files:

+ yield f

+ if hasattr(f, 'files'):

+ for subf in f.files:

+ yield subf

+ for r in system.repositories:

+ for f in _all_repo_files(r):

+ if (not hasattr(f, 'categories')

+ or (not f.categories and not f.copy_categories)):

+ continue

+ if f.binary:

+ w = ihm.format_bcif.BinaryCifWriter(

+ open(f.local_path, 'wb'))

+ else:

+ w = ihm.format.CifWriter(open(f.local_path, 'w'))

+ # Write header information to the associated file

+ dumpers = (ihm.dumper._EntryDumper(), _EntryLinkDumper())

+ # We are passing the File object to the dumpers here where

+ # they expect a System object, but the interfaces are similar

+ # enough, so we don't need a facade object.

+ for d in dumpers:

+ d.finalize(f)

+ for d in dumpers:

+ d.dump(f, w)

+ for c in f.categories:

+ # Allow for categories with or without leading underscore

+ category_map['_' + c.lstrip('_').lower()] = w

+ for c in f.copy_categories:

+ copy_category_map['_' + c.lstrip('_').lower()] = w

+ if category_map or copy_category_map:

+ return _SystemWriter(writer, category_map, copy_category_map)

+ else:

+ # If no categories, we can just use the base writer

+ return writer

+

+

+def write(fh, systems, format='mmCIF', dumpers=[],

+ variant=ModelCIFVariant, check=True):

+ """Write out all `systems` to the file handle `fh`.

+

+ See :func:`ihm.dumper.write` for more information. The function

+ here behaves similarly but writes out files compliant with the

+ ModelCIF extension directory rather than IHM."""

+ return ihm.dumper.write(fh, systems, format, dumpers, variant, check=check)

+import ihm.representation

+from ihm.model import Atom, ModelGroup # noqa: F401

+import modelcif.data

+from ihm.util import _check_residue_range

+

+

+# Provide ma-specific docs for Atom

+Atom.__doc__ = """Coordinates of part of the model represented by an atom.

+

+See :meth:`Model.get_atoms` for more details.

+

+:param asym_unit: The asymmetric unit that this atom represents

+:type asym_unit: :class:`modelcif.AsymUnit`

+:param int seq_id: The residue index represented by this atom

+ (can be None for HETATM sites)

+:param str atom_id: The name of the atom in the residue

+:param str type_symbol: Element name

+:param float x: x coordinate of the atom

+:param float y: y coordinate of the atom

+:param float z: z coordinate of the atom

+:param bool het: True for HETATM sites, False (default) for ATOM

+:param float biso: Temperature factor or equivalent (if applicable)

+:param float occupancy: Fraction of the atom type present

+ (if applicable)

+"""

+

+# Provide ma-specific docs for ModelGroup

+ModelGroup.__doc__ = """A set of related models. See :class:`Model`.

+It is implemented as a simple list of the models.

+

+These objects are typically stored directly in the system; see

+:attr:`modelcif.System.model_groups`.

+

+:param elements: Initial set of models in the group.

+:param str name: Descriptive name for the group.

+"""

+

+

+class Model(modelcif.data.Data):

+ """Base class for coordinates of a single structure.

+ Use a subclass such as :class:`HomologyModel` or

+ :class:`AbInitioModel`, or represent a custom model type by

+ creating a new subclass and providing a docstring to describe it, e.g.::

+

+ class CustomModel(Model):

+ "custom model type"

+

+ :param assembly: The :class:`modelcif.AsymUnit` objects that make up

+ this model.

+ :type assembly: :class:`modelcif.Assembly`

+ :param str name: Short name for this model.

+ """

+ data_content_type = 'model coordinates'

+ model_type = "Other"

+

+ def __init__(self, assembly, name=None):

+ modelcif.data.Data.__init__(self, name)

+ self.assembly = assembly

+ # Assume everything is atomic for ModelCIF models

+ self.representation = ihm.representation.Representation(

+ [ihm.representation.AtomicSegment(seg, rigid=False)

+ for seg in assembly])

+ self._atoms = []

+

+ #: List of residue ranges that were explicitly not modeled. See

+ #: :class:`NotModeledResidueRange`.

+ self.not_modeled_residue_ranges = []

+

+ #: Quality scores for the model or part of it (a simple list of

+ #: metric objects; see :mod:`modelcif.qa_metric`)

+ self.qa_metrics = []

+

+ def _get_other_details(self):

+ if (type(self) is not Model

+ and self.model_type == Model.model_type):

+ return self.__doc__.split('\n')[0]

+

+ other_details = property(

+ _get_other_details,

+ doc="More information about a custom model type. "

+ "By default it is the first line of the docstring.")

+

+ def get_atoms(self):

+ """Yield :class:`Atom` objects that represent this model.

+

+ The default implementation simply iterates over an internal

+ list of atoms, but this is not very memory-efficient, particularly

+ if the atoms are already stored somewhere else, e.g. in the

+ software's own data structures. It is recommended to subclass

+ and provide a more efficient implementation. For example,

+ `the modbase_pdb_to_cif script <https://github.com/salilab/modbase_utils/blob/main/modbase_pdb_to_cif.py>`_

+ uses a custom ``MyModel`` subclass that creates Atom objects on

+ the fly from PDB ATOM or HETATM lines.

+ """ # noqa: E501

+ for a in self._atoms:

+ yield a

+

+ def add_atom(self, atom):

+ self._atoms.append(atom)

+

+

+class HomologyModel(Model):

+ """Coordinates of a single structure generated using homology

+ or comparative modeling.

+

+ See :class:`Model` for a description of the parameters.

+ """

+ model_type = "Homology model"

+ other_details = None

+

+

+class AbInitioModel(Model):

+ """Coordinates of a single structure generated using ab initio modeling.

+

+ See :class:`Model` for a description of the parameters.

+ """

+ model_type = "Ab initio model"

+ other_details = None

+

+

+class NotModeledResidueRange:

+ """A range of residues that were explicitly not modeled.

+ See :attr:`Model.not_modeled_residue_ranges`.

+ These ranges are not explicitly stored in the mmCIF file,

+ but they will be excluded from the ``pdbx_poly_seq_scheme`` table.

+

+ :param asym_unit: The asymmetric unit to which the residues belong.

+ :type asym_unit: :class:`~modelcif.AsymUnit`

+ :param int seq_id_begin: Starting residue in the range.

+ :param int seq_id_end: Ending residue in the range.

+ """

+ def __init__(self, asym_unit, seq_id_begin, seq_id_end):

+ self.asym_unit = asym_unit

+ self.seq_id_begin, self.seq_id_end = seq_id_begin, seq_id_end

+ _check_residue_range((seq_id_begin, seq_id_end), asym_unit.entity)

+"""Classes for handling modeling protocols.

+"""

+

+

+class Step:

+ """A single step in a :class:`Protocol`.

+

+ This class describes a generic step in a modeling protocol. In most

+ cases, a more specific subclass should be used, such as

+ :class:`TemplateSearchStep`, :class:`ModelingStep`, or

+ :class:`ModelSelectionStep`.

+

+ :param input_data: Any objects that this step takes as input.

+ Any individual :class:`modelcif.data.Data` object (such as

+ a template structure, target sequence, alignment, or model

+ coordinates) can be given here, or a group of such objects (as a

+ :class:`modelcif.data.DataGroup` object) can be passed.

+ :type input_data: :class:`modelcif.data.DataGroup`

+ or :class:`modelcif.data.Data`

+ :param output_data: Any objects that this step creates as output,

+ similarly to ``input_data``.

+ :type output_data: :class:`modelcif.data.DataGroup`

+ or :class:`modelcif.data.Data`

+ :param str name: A short name for this step.

+ :param str details: Longer description of this step.

+ :param software: The software that was employed in this modeling step.

+ :type software: :class:`modelcif.Software`

+ or :class:`modelcif.SoftwareGroup`

+ """

+ method_type = "other"

+

+ def __init__(self, input_data, output_data, name=None, details=None,

+ software=None):

+ self.input_data, self.output_data = input_data, output_data

+ self.name, self.details, self.software = name, details, software

+

+

+class TemplateSearchStep(Step):

+ """A modeling protocol step that searches for templates.

+ See :class:`Step` for more details."""

+ method_type = "template search"

+

+

+class TemplateSelectionStep(Step):

+ """A modeling protocol step that selects one or more templates.

+ See :class:`Step` for more details."""

+ method_type = "template selection"

+

+

+class TargetTemplateAlignmentStep(Step):

+ """A modeling protocol step that creates a target-template alignment.

+ See :class:`Step` for more details."""

+ method_type = "target-template alignment"

+

+

+class CoevolutionMSAStep(Step):

+ """A modeling protocol step that creates a coevolution multiple sequence

+ alignment. See :class:`Step` for more details."""

+ method_type = "coevolution MSA"

+

+

+class ContactPredictionStep(Step):

+ """A modeling protocol step that predicts contacts.

+ See :class:`Step` for more details."""

+ method_type = "contact prediction"

+

+

+class ModelingStep(Step):

+ """A modeling protocol step that generates model coordinates.

+ See :class:`Step` for more details."""

+ method_type = "modeling"

+

+

+class ModelSelectionStep(Step):

+ """A modeling protocol step that filters candidates to select models.

+ See :class:`Step` for more details."""

+ method_type = "model selection"

+

+

+class ModelRefinementStep(Step):

+ """A modeling protocol step that refines models.

+ See :class:`Step` for more details."""

+ method_type = "model refinement"

+

+

+class Protocol:

+ """A modeling protocol.

+ Each protocol consists of a number of protocol steps."""

+ def __init__(self):

+ #: All modeling steps (:class:`Step` objects)

+ self.steps = []

+"""Classes to annotate models with quality scores.

+

+ To use, first declare a class for the desired score by deriving

+ from both a subclass of :class:`MetricMode` (which defines the part

+ of the system the metric applies to) and a subclass of :class:`MetricType`

+ (which describes the meaning of the score value). Set the ``software``

+ attribute to point to the software used to calculate the metric

+ (as a :class:`modelcif.SoftwareGroup` or :class:`modelcif.Software` object).

+ For example to declare a global distance score::

+

+ class MyScore(modelcif.qa_metric.Global, modelcif.qa_metric.Distance):

+ "My distance-based quality score"

+ software = modelcif.Software(...)

+

+ The name and description of the score in the mmCIF file will be taken from

+ the name and docstring of the Python class, unless the

+ :attr:`MetricMode.name` or :attr:`MetricMode.description` attributes are

+ overridden in the subclass.

+

+ QA metric objects should be added to

+ :attr:`modelcif.model.Model.qa_metrics`.

+"""

+

+

+class MetricMode:

+ """Base class for the mode of a quality metric.

+ Use a derived class such as :class:`Global`, :class:`Local`,

+ :class:`LocalPairwise`, :class:`Feature`, or :class:`FeaturePairwise`

+ for declaring a new score.

+ """

+ name = property(lambda x: type(x).__name__,

+ doc="Short name of this score. By default it is just the "

+ "class name, but this can be overridden in subclasses "

+ "(for example to create names containing spaces).")

+

+ description = property(lambda x: x.__doc__.split("\n")[0],

+ doc="Longer text description of this score. By "

+ "default it is the first line of the "

+ "docstring.")

+

+

+class Global(MetricMode):

+ """A score that is calculated per-model.

+

+ :param float value: The score value (see :class:`MetricType`).

+ """

+

+ mode = "global"

+

+ def __init__(self, value):

+ self.value = value

+

+ def __repr__(self):

+ return "<%s(value=%r)>" % (type(self).__name__, self.value)

+

+

+class Local(MetricMode):

+ """A score that is calculated on a single residue.

+

+ :param residue: The residue that is scored.

+ :type residue: :class:`modelcif.Residue`

+ :param float value: The score value (see :class:`MetricType`).

+ """

+

+ mode = "local"

+

+ def __init__(self, residue, value):

+ self.residue = residue

+ self.value = value

+

+ def __repr__(self):

+ return "<%s(residue=%r, value=%r)>" % (type(self).__name__,

+ self.residue, self.value)

+

+

+class LocalPairwise(MetricMode):

+ """A score that is calculated between two residues.

+

+ :param residue1: The first residue that is scored.

+ :type residue1: :class:`modelcif.Residue`

+ :param residue2: The second residue that is scored.

+ :type residue2: :class:`modelcif.Residue`

+ :param float value: The score value (see :class:`MetricType`).

+ """

+

+ mode = "local-pairwise"

+

+ def __init__(self, residue1, residue2, value):

+ self.residue1 = residue1

+ self.residue2 = residue2

+ self.value = value

+

+ def __repr__(self):

+ return ("<%s(residue1=%r, residue2=%r, value=%r)>"

+ % (type(self).__name__, self.residue1, self.residue2,

+ self.value))

+

+

+class Feature(MetricMode):

+ """A score that is calculated on a single feature.

+

+ :param feature: The feature that is scored.

+ :type feature: :class:`modelcif.Feature`

+ :param float value: The score value (see :class:`MetricType`).

+ """

+

+ mode = "per-feature"

+

+ def __init__(self, feature, value):

+ self.feature = feature

+ self.value = value

+

+ def __repr__(self):

+ return "<%s(feature=%r, value=%r)>" % (type(self).__name__,

+ self.feature, self.value)

+ _all_features = property(lambda self: (self.feature,))

+

+

+class FeaturePairwise(MetricMode):

+ """A score that is calculated between two features.

+

+ :param feature1: The first feature that is scored.

+ :type feature1: :class:`modelcif.Feature`

+ :param feature2: The second feature that is scored.

+ :type feature2: :class:`modelcif.Feature`

+ :param float value: The score value (see :class:`MetricType`).

+ """

+

+ mode = "per-feature-pair"

+

+ def __init__(self, feature1, feature2, value):

+ self.feature1 = feature1

+ self.feature2 = feature2

+ self.value = value

+

+ def __repr__(self):

+ return ("<%s(feature1=%r, feature2=%r, value=%r)>"

+ % (type(self).__name__, self.feature1, self.feature2,

+ self.value))

+ _all_features = property(lambda self: (self.feature1, self.feature2))

+

+

+class MetricType:

+ """Base class for the type of a quality metric.

+ Generally a derived class such as :class:`ZScore` or :class:`Distance`

+ is used to declare a new score, but a custom type can also be declared

+ by deriving from this class and providing a docstring to describe

+ the metric type::

+

+ class MPQSMetricType(modelcif.qa_metric.MetricType):

+ "composite score, values >1.1 are reliable"

+ """

+

+ type = "other"

+

+ def _get_other_details(self):

+ # Find most derived class of MetricType before we pulled in MetricMode

+ # and use the first line of its docstring as other_details

+ if self.type == MetricType.type:

+ for base in type(self).mro():

+ if (issubclass(base, MetricType)

+ and base is not MetricType

+ and not issubclass(base, MetricMode)):

+ return base.__doc__.split('\n')[0]

+

+ other_details = property(

+ _get_other_details,

+ doc="More information about this metric type. By default it is the "

+ "first line of the MetricType subclass docstring.")

+

+

+class ZScore(MetricType):

+ """Score that is the number of standard deviations from optimal/best.

+ See :class:`MetricType` for more information."""

+ type = "zscore"

+ other_details = None

+

+

+class Energy(MetricType):

+ """Energy score (the lower the energy, the better the quality).

+ See :class:`MetricType` for more information."""

+ type = "energy"

+ other_details = None

+

+

+class Distance(MetricType):

+ """Distance score (the lower the distance, the better the quality).

+ See :class:`MetricType` for more information."""

+ type = "distance"

+ other_details = None

+

+

+class NormalizedScore(MetricType):

+ """Normalized score ranging from 0 to 1.

+ See :class:`MetricType` for more information."""

+ type = "normalized score"

+ other_details = None

+

+

+class PAE(MetricType):

+ """Score that is a predicted aligned error.

+ See :class:`MetricType` for more information."""

+ type = "PAE"

+ other_details = None

+

+

+class ContactProbability(MetricType):

+ """Score that is a contact probability of a pairwise interaction.

+ See :class:`MetricType` for more information."""

+ type = "contact probability"

+ other_details = None

+

+

+class PLDDT(MetricType):

+ """Predicted lDDT-CA score in [0,100] (higher score, means better

+ accuracy). See :class:`MetricType` for more information."""

+ type = "pLDDT"

+ other_details = None

+

+

+class PLDDT01(MetricType):

+ """Predicted lDDT-CA score in [0,1] (higher score, means better

+ accuracy). See :class:`MetricType` for more information."""

+ type = "pLDDT in [0,1]"

+ other_details = None

+

+

+class PLDDTAllAtom(MetricType):

+ """Predicted lDDT all atom score in [0,100] (higher score, means better

+ accuracy). See :class:`MetricType` for more information."""

+ type = "pLDDT all-atom"

+ other_details = None

+

+

+class PLDDTAllAtom01(MetricType):

+ """Predicted lDDT all atom score in [0,1] (higher score, means better

+ accuracy). See :class:`MetricType` for more information."""

+ type = "pLDDT all-atom in [0,1]"

+ other_details = None

+

+

+class PLDDTToPolymer(MetricType):

+ """Predicted lDDT with distances from each atom to CA or C1' of nearby

+ polymer residues [0,100] (higher score, means better accuracy).

+ See :class:`MetricType` for more information."""

+ type = "pLDDT to polymer"

+ other_details = None

+

+

+class PTM(MetricType):

+ """Predicted TM-score in [0,1] (higher value means higher confidence).

+ See :class:`MetricType` for more information."""

+ type = "pTM"

+ other_details = None

+

+

+class IpTM(MetricType):

+ """Protein-protein interface score, based on TM-score in [0,1].

+ See :class:`MetricType` for more information."""

+ type = "ipTM"

+ other_details = None

+

+

+class Boolean(MetricType):

+ """0 or 1 depending on whether a check passed.

+ See :class:`MetricType` for more information."""

+ type = "boolean"

+ other_details = None

+"""Utility classes to read in information in mmCIF or BinaryCIF format"""

+

+import modelcif

+import modelcif.model

+import modelcif.protocol

+import modelcif.qa_metric

+import modelcif.alignment

+import modelcif.reference

+import modelcif.associated

+import modelcif.descriptor

+import ihm

+import ihm.source

+import ihm.reader

+from ihm.reader import Variant, Handler, IDMapper, _ChemCompIDMapper

+from ihm.reader import OldFileError, _make_new_entity

+from datetime import date

+import posixpath

+import operator

+import inspect

+import collections

+import functools

+import warnings

+

+

+def _get_date(iso_date_str):

+ """Get a datetime.date obj for a string in isoformat."""

+ if iso_date_str is None:

+ return None

+ return date(int(iso_date_str[0:4]),

+ int(iso_date_str[5:7]),

+ int(iso_date_str[8:10]))

+

+

+class _AuditConformHandler(Handler):

+ category = '_audit_conform'

+

+ def __call__(self, dict_name, dict_version):

+ # Reject old file versions if we can parse the version

+ if dict_name == "mmcif_ma.dic":

+ try:

+ major, minor, _ = [int(x) for x in dict_version.split('.')]

+ if (major, minor) < (1, 3):

+ raise OldFileError(

+ "This version of python-modelcif only supports "

+ "reading files that conform to version 1.3 or later "

+ "of the ModelCIF extension dictionary. This file "

+ "conforms to version %s." % dict_version)

+ except ValueError:

+ pass

+

+

+class _ReferenceIDMapper(IDMapper):

+ """Add extra handling to IDMapper for ihm.reference.Reference objects"""

+

+ def _make_new_object(self, newcls=None):

+ if newcls is None or newcls is ihm.reference.Sequence:

+ return self._cls(*(None,) * 4)

+ else:

+ return newcls(*(None,) * 3)

+

+

+class _TemplateIDMapper(IDMapper):

+ """Add extra handling to IDMapper for modelcif.Template objects"""

+

+ def _update_old_object(self, obj, newcls=None):

+ super(_TemplateIDMapper, self)._update_old_object(obj, newcls)

+ # Add missing members if the wrong class was originally instantianted

+ if newcls is modelcif.CustomTemplate and not hasattr(obj, 'atoms'):

+ obj.details = None

+ obj.atoms = []

+

+

+class _FeatureIDMapper(IDMapper):

+ """Add extra handling to IDMapper for QA metric features"""

+

+ def _make_new_object(self, newcls=None):

+ if newcls is None:

+ # Make Feature base class (takes no args)

+ return self._cls()

+ else:

+ # Make subclass (takes one atoms/residues/asyms argument)

+ return newcls([])

+

+ def _update_old_object(self, obj, newcls=None):

+ super(_FeatureIDMapper, self)._update_old_object(obj, newcls)

+ # Add missing members if the base class was originally instantianted

+ if (newcls is modelcif.PolyResidueFeature

+ and not hasattr(obj, 'residues')):

+ obj.residues = []

+ elif newcls is modelcif.AtomFeature and not hasattr(obj, 'atoms'):

+ obj.atoms = []

+ elif (newcls is modelcif.EntityInstanceFeature

+ and not hasattr(obj, 'asym_units')):

+ obj.asym_units = []

+

+

+class _SystemReader:

+ def __init__(self, model_class, starting_model_class, system=None):

+ self.system = system or modelcif.System()

+

+ #: Mapping from ID to :class:`ihm.Software` objects

+ self.software = IDMapper(self.system.software, ihm.Software,

+ *(None,) * 4)

+

+ #: Mapping from ID to :class:`ihm.Citation` objects

+ self.citations = IDMapper(self.system.citations, ihm.Citation,

+ *(None,) * 8)

+

+ #: Mapping from ID to :class:`ihm.Revision` objects

+ self.revisions = IDMapper(self.system.revisions, ihm.Revision,

+ *(None,) * 4)

+

+ #: Mapping from ID to :class:`ihm.Entity` objects

+ self.entities = IDMapper(self.system.entities, _make_new_entity)

+

+ #: Mapping from ID to :class:`ihm.source.Manipulated` objects

+ self.src_gens = IDMapper(None, ihm.source.Manipulated)

+

+ #: Mapping from ID to :class:`ihm.source.Natural` objects

+ self.src_nats = IDMapper(None, ihm.source.Natural)

+

+ #: Mapping from ID to :class:`ihm.source.Synthetic` objects

+ self.src_syns = IDMapper(None, ihm.source.Synthetic)

+

+ #: Mapping from ID to :class:`ihm.AsymUnit` objects

+ self.asym_units = IDMapper(self.system.asym_units, ihm.AsymUnit, None)

+

+ #: Mapping from ID to :class:`ihm.ChemComp` objects

+ self.chem_comps = _ChemCompIDMapper(self.system._orphan_chem_comps,

+ ihm.ChemComp, *(None,) * 3)

+

+ self.software_groups = IDMapper(self.system.software_groups,

+ modelcif.SoftwareGroup)

+

+ self.default_data_by_id = {}

+ self.data_by_id = {}

+ self.data_groups = IDMapper(self.system.data_groups,

+ modelcif.data.DataGroup)

+

+ self.transformations = IDMapper(self.system.template_transformations,

+ modelcif.Transformation, *(None,) * 2)

+

+ self.templates = _TemplateIDMapper(

+ self.system.templates, modelcif.Template, *(None,) * 4)

+

+ self.template_segments = IDMapper(

+ self.system.template_segments, modelcif.TemplateSegment,

+ *(None,) * 4)

+

+ self.default_model_class = model_class is modelcif.model.Model

+ self._all_seen_models = []

+ for group, model in self.system._all_models():

+ self._all_seen_models.append(model)

+ self.models = IDMapper(self._all_seen_models, model_class, [], None)

+

+ self.model_groups = IDMapper(self.system.model_groups,

+ modelcif.model.ModelGroup)

+

+ self.assemblies = IDMapper(self.system.assemblies, modelcif.Assembly)

+

+ self.protocols = IDMapper(self.system.protocols,

+ modelcif.protocol.Protocol)

+

+ self.references = _ReferenceIDMapper(None, ihm.reference.Sequence)

+ self.alignments = IDMapper(None, ihm.reference.Alignment)

+ self.features = _FeatureIDMapper(None, modelcif.Feature)

+

+ self.assoc_by_id = {}

+

+ self.qa_by_id = self.system._qa_by_id

+

+ self.software_parameters = collections.defaultdict(list)

+

+ self.alignment_pairs = collections.defaultdict(list)

+

+ self.alignment_seqs = collections.defaultdict(list)

+

+ # Correspondence between target and template sequence ranges

+ self.target_template_poly_mapping = {}

+

+ # Correspondence between target and template chains

+ self.target_asym_for_template = {}

+

+ # Mapping from Entity to bool ma_model_mode flag

+ self.ma_model_mode_map = {}

+

+ def finalize(self):

+ # make sequence immutable (see also _make_new_entity)

+ for e in self.system.entities:

+ e.sequence = tuple(e.sequence)

+

+ # If no Assembly is provided, assume each model consists of all Asyms

+ # Assume everything in every Model is atomic

+ for mg in self.system.model_groups:

+ for m in mg:

+ if not m.assembly:

+ m.assembly.extend(self.system.asym_units[:])

+ m.representation = ihm.representation.Representation(

+ [ihm.representation.AtomicSegment(seg, rigid=False)

+ for seg in m.assembly])

+

+

+class _DatabaseHandler(Handler):

+ category = '_database_2'

+

+ def __call__(self, database_code, database_id):

+ self.system.database = modelcif.Database(

+ id=database_id, code=database_code)

+

+

+class _ChemCompHandler(Handler):

+ """Similar to ihm.reader._ChemCompHandler but also handles

+ the ma_provenance data item"""

+ category = '_chem_comp'

+

+ _prov_map = {'ccd core': 'core', 'ccd ma': 'ma', 'ccd local': 'local'}

+

+ def __init__(self, *args):

+ super(_ChemCompHandler, self).__init__(*args)

+ # Map _chem_comp.type to corresponding subclass of ihm.ChemComp

+ self.type_map = dict((x[1].type.lower(), x[1])

+ for x in inspect.getmembers(ihm, inspect.isclass)

+ if issubclass(x[1], ihm.ChemComp))

+

+ def __call__(self, type, id, name, formula, ma_provenance):

+ typ = 'other' if type is None else type.lower()

+ s = self.sysr.chem_comps.get_by_id(

+ id, self.type_map.get(typ, ihm.ChemComp))

+ self.copy_if_present(s, locals(), keys=('name', 'formula'))

+ if ma_provenance:

+ s.ccd = self._prov_map.get(ma_provenance.lower())

+

+

+class _ChemCompDescriptorHandler(Handler):

+ category = '_ma_chem_comp_descriptor'

+

+ def __init__(self, *args):

+ super(_ChemCompDescriptorHandler, self).__init__(*args)

+ # Map _chem_comp_descriptor.type to corresponding subclass of

+ # modelcif.descriptor.Descriptor

+ self._type_map = dict(

+ (x[1].type.lower(), x[1])

+ for x in inspect.getmembers(modelcif.descriptor, inspect.isclass)

+ if issubclass(x[1], modelcif.descriptor.Descriptor)

+ and x[1] is not modelcif.descriptor.Descriptor)

+

+ def __call__(self, chem_comp_id, type, value, details, software_id):

+ s = self.sysr.chem_comps.get_by_id(chem_comp_id)

+ type_class = self._type_map.get(

+ type.lower(), modelcif.descriptor.Descriptor)

+ software = self.sysr.software.get_by_id_or_none(software_id)

+ desc = type_class(value=value, details=details, software=software)

+ if not hasattr(s, 'descriptors') or not s.descriptors:

+ s.descriptors = []

+ s.descriptors.append(desc)

+

+

+class _EntityNonPolyHandler(Handler):

+ category = '_pdbx_entity_nonpoly'

+ _mmmap = {'explicit': True, 'implicit': False}

+

+ def __call__(self, entity_id, comp_id, ma_model_mode):

+ s = self.sysr.entities.get_by_id(entity_id)

+ s.sequence = (self.sysr.chem_comps.get_by_id(comp_id),)

+ if ma_model_mode in (None, ihm.unknown):

+ self.sysr.ma_model_mode_map[s] = ma_model_mode

+ else:

+ self.sysr.ma_model_mode_map[s] = self._mmmap.get(

+ ma_model_mode.lower())

+

+

+class _TemplatePolyHandler(Handler):

+ category = '_ma_template_poly'

+

+ def __init__(self, sysr):

+ super(_TemplatePolyHandler, self).__init__(sysr)

+ # Use python-ihm's _EntityPolyHandler to do most of the work here.

+ # Note that we use Entity objects to store the sequence of the

+ # templates, but template Entities are *not* stored in the mmCIF

+ # file, so the 'entity ID' here is actually template_id and we

+ # don't look the Entity object up with sysr.entities.get_by_id().

+ self._eph = ihm.reader._EntityPolyHandler(sysr)

+

+ def __call__(self, template_id, seq_one_letter_code,

+ seq_one_letter_code_can):

+ self._eph(entity_id=template_id, type=None,

+ pdbx_seq_one_letter_code=seq_one_letter_code,

+ pdbx_seq_one_letter_code_can=seq_one_letter_code_can)

+

+ def finalize(self):

+ # No type given in _ma_template_poly, so assume amino acid

+ alphabet = ihm.LPeptideAlphabet()

+

+ def _get_seq(codes, codes_can):

+ for i, code in enumerate(codes):

+ # Hopefully non-standard codes are listed in chem_comp table

+ if code in alphabet:

+ yield alphabet[code]

+ else:

+ comp = self.sysr.chem_comps.get_by_id(code)

+ # chem_comp table doesn't define one-letter codes, so

+ # fill them in here if we have them

+ comp.code = code

+ if i < len(codes_can):

+ comp.code_canonical = codes_can[i]

+ yield comp

+ for t in self.system.templates:

+ ei = self._eph._entity_info.get(t._id)

+ if ei:

+ t.entity = ihm.Entity(sequence=_get_seq(ei.one_letter,

+ ei.one_letter_can))

+

+

+class _TemplateNonPolyHandler(Handler):

+ category = '_ma_template_non_poly'

+

+ def __call__(self, template_id, comp_id, details):

+ template = self.sysr.templates.get_by_id(template_id)

+ seq = (self.sysr.chem_comps.get_by_id(comp_id),)

+ template.entity = ihm.Entity(sequence=seq, description=details)

+

+

+class _SoftwareGroupHandler(Handler):

+ category = '_ma_software_group'

+

+ def __call__(self, group_id, software_id, parameter_group_id):

+ g = self.sysr.software_groups.get_by_id(group_id)

+ s = self.sysr.software.get_by_id(software_id)

+ # Don't need to handle None or ihm.unknown specially here; this will

+ # map them to an empty list

+ parameters = self.sysr.software_parameters[parameter_group_id]

+ if parameters:

+ s = modelcif.SoftwareWithParameters(software=s,

+ parameters=parameters)

+ g.append(s)

+

+

+class _SoftwareParameterHandler(Handler):

+ category = '_ma_software_parameter'

+

+ def _get_int_list(self, value):

+ return [int(x) for x in value.split(',')]

+

+ def _get_float_list(self, value):

+ return [float(x) for x in value.split(',')]

+

+ def __call__(self, group_id, data_type, name, value, description):

+ type_map = {"integer": self.get_int, "float": self.get_float,

+ "boolean": self.get_bool, "string": str,

+ "integer-csv": self._get_int_list,

+ "float-csv": self._get_float_list}

+ pg = self.sysr.software_parameters[group_id]

+ converter = type_map.get(data_type, str)

+ p = modelcif.SoftwareParameter(name=name, value=converter(value),

+ description=description)

+ pg.append(p)

+

+

+class _DataHandler(Handler):

+ category = '_ma_data'

+

+ def __call__(self, id, name, content_type_other_details):

+ d = modelcif.data.Data(name=name, details=content_type_other_details)

+ d._data_id = id

+ self.sysr.default_data_by_id[id] = d

+

+ def finalize(self):

+ for data_id, defdata in self.sysr.default_data_by_id.items():

+ data = self.sysr.data_by_id.get(data_id)

+ if not data:

+ # Add placeholder Data if only referenced in ma_data

+ self.sysr.data_by_id[data_id] = defdata

+ elif hasattr(data, 'name') and not data.name:

+ # Add data-specific fields if they are present in ma_data

+ # but not elsewhere

+ data.name = defdata.name

+ self.system.data[:] = sorted(self.sysr.data_by_id.values(),

+ key=operator.attrgetter('_data_id'))

+

+ for g in self.system.data_groups:

+ g[:] = [self.sysr.data_by_id.get(x) for x in g]

+

+

+class _DataGroupHandler(Handler):

+ category = '_ma_data_group'

+

+ def __call__(self, group_id, data_id):

+ g = self.sysr.data_groups.get_by_id(group_id)

+ # fill in real Data objects at _DataHandler.finalize time

+ g.append(data_id)

+

+

+class _DataRefDBHandler(Handler):

+ category = '_ma_data_ref_db'

+

+ def __call__(self, data_id, name, location_url, version, release_date):

+ d = modelcif.ReferenceDatabase(

+ name=name, url=location_url, version=version,

+ release_date=_get_date(release_date))

+ self.sysr.data_by_id[data_id] = d

+ d._data_id = data_id

+

+

+class _EnumerationMapper:

+ """Map an mmCIF enumerated value to the corresponding Python class"""

+ def __init__(self, module, base_class, attr="name"):

+ self._base_class = base_class

+ self._other_name = getattr(base_class, attr).upper()

+ self._attr = attr

+ self._map = dict(

+ (getattr(x[1], attr).upper(), x[1])

+ for x in inspect.getmembers(module, inspect.isclass)

+ if issubclass(x[1], base_class) and x[1] is not base_class)

+ self._other_map = {}

+

+ def get(self, name, other_det):

+ """Get the Python class that matches the given name

+ and other_details"""

+ name = name.upper()

+ typ = self._map.get(name)

+ if typ:

+ return typ

+ # If name is not Other this is an enumeration value we don't have

+ # a class for; make and cache a new class for the given name:

+ if name != self._other_name:

+ class ExtraType(self._base_class):

+ other_details = None

+ setattr(ExtraType, self._attr, name)

+ self._map[name] = ExtraType

+ return ExtraType

+ # If name is "Other" then treat other_details as the key

+ other_det_up = other_det if other_det is None else other_det.upper()

+ if other_det_up not in self._other_map:

+ class CustomType(self._base_class):

+ other_details = other_det

+ __doc__ = other_det

+ self._other_map[other_det_up] = CustomType

+ return self._other_map[other_det_up]

+

+

+class _TargetEntityHandler(Handler):

+ category = '_ma_target_entity'

+

+ def __call__(self, entity_id, data_id):

+ e = self.sysr.entities.get_by_id(entity_id)

+ self.sysr.data_by_id[data_id] = e

+ e._data_id = data_id

+

+

+class _TargetRefDBHandler(Handler):

+ category = '_ma_target_ref_db_details'

+

+ def __init__(self, *args):

+ super(_TargetRefDBHandler, self).__init__(*args)

+ # Map db_name to subclass of modelcif.reference.TargetReference

+ self.type_map = _EnumerationMapper(modelcif.reference,

+ modelcif.reference.TargetReference)

+

+ def __call__(self, target_entity_id, db_name, db_name_other_details,

+ db_code, db_accession, seq_db_isoform,

+ seq_db_align_begin: int, seq_db_align_end: int,

+ ncbi_taxonomy_id, organism_scientific,

+ seq_db_sequence_version_date, seq_db_sequence_checksum,

+ is_primary: bool):

+ e = self.sysr.entities.get_by_id(target_entity_id)

+ typ = self.type_map.get(db_name, db_name_other_details)

+ with warnings.catch_warnings():

+ warnings.simplefilter("ignore")

+ ref = typ(code=db_code, accession=db_accession,

+ align_begin=seq_db_align_begin,

+ align_end=seq_db_align_end,

+ isoform=seq_db_isoform,

+ ncbi_taxonomy_id=ncbi_taxonomy_id,

+ organism_scientific=organism_scientific,

+ sequence_version_date=_get_date(

+ seq_db_sequence_version_date),

+ sequence_crc64=seq_db_sequence_checksum,

+ is_primary=is_primary)

+ e.references.append(ref)

+

+ def finalize(self):

+ # Combine information from struct_ref (ihm.reference objects)

+ # with that from _ma_target_ref_db_details (modelcif.reference).

+ # Use db_name/db_code/accession as the key.

+ # We start with two distinct lists, as python-ihm uses struct_ref.id

+ # as the key, which _ma_target_ref_db_details does not use.

+ for e in self.system.entities:

+ ihm_refs = [r for r in e.references

+ if not isinstance(r,

+ modelcif.reference.TargetReference)]

+ ma_refs = [r for r in e.references

+ if isinstance(r, modelcif.reference.TargetReference)]

+ e.references = ma_refs

+ ma_refs = dict(((r.db_name, r.db_code, r.accession), r)

+ for r in ma_refs)

+ for ir in ihm_refs:

+ k = (ir.db_name, ir.db_code, ir.accession)

+ mr = ma_refs.get(k)

+ if mr is None:

+ # Change type from ihm to modelcif class

+ typ = self.type_map.get(ir.db_name, None)

+ ir.__class__ = typ

+ e.references.append(ir)

+ # Add missing fields only present in modelcif class

+ ir.isoform = ir.ncbi_taxonomy_id = None

+ ir.organism_scientific = ir.sequence_version_date = None

+ ir.sequence_crc64 = None

+ ir.align_begin = ir.align_end = ir.is_primary = None

+ else:

+ # Add struct_ref info to corresponding modelcif object

+ mr.sequence = ir.sequence

+ mr.details = ir.details

+ mr.alignments = ir.alignments

+

+

+class _TransformationHandler(Handler):

+ category = '_ma_template_trans_matrix'

+

+ def __call__(self, id, tr_vector1, tr_vector2, tr_vector3, rot_matrix11,

+ rot_matrix21, rot_matrix31, rot_matrix12, rot_matrix22,

+ rot_matrix32, rot_matrix13, rot_matrix23, rot_matrix33):

+ t = self.sysr.transformations.get_by_id(id)

+ t.rot_matrix = ihm.reader._get_matrix33(locals(), 'rot_matrix')

+ t.tr_vector = ihm.reader._get_vector3(locals(), 'tr_vector')

+

+

+class _TemplateDetailsHandler(Handler):

+ category = '_ma_template_details'

+

+ def __call__(self, template_id, template_trans_matrix_id,

+ template_data_id, target_asym_id, template_label_asym_id,

+ template_label_entity_id, template_model_num: int,

+ template_auth_asym_id, template_origin):

+ newcls = None

+ if template_origin and template_origin.lower() == 'customized':

+ newcls = modelcif.CustomTemplate

+ template = self.sysr.templates.get_by_id(template_id, newcls)

+ template.transformation = self.sysr.transformations.get_by_id(

+ template_trans_matrix_id)

+ # Add empty sequence (hopefully will fill in from _ma_template_poly

+ # or _ma_template_non_poly)

+ template.entity = ihm.Entity([])

+ template.entity_id = template_label_entity_id

+ template.asym_id = template_label_asym_id

+ template.model_num = template_model_num

+ template._strand_id = template_auth_asym_id

+ self.sysr.data_by_id[template_data_id] = template

+ template._data_id = template_data_id

+ self.sysr.target_asym_for_template[template_id] = target_asym_id

+

+

+class _TemplateRefDBHandler(Handler):

+ category = '_ma_template_ref_db_details'

+

+ def __init__(self, *args):

+ super(_TemplateRefDBHandler, self).__init__(*args)

+ # Map db_name to subclass of modelcif.reference.TemplateReference

+ self.type_map = _EnumerationMapper(

+ modelcif.reference, modelcif.reference.TemplateReference)

+

+ def __call__(self, template_id, db_name, db_name_other_details,

+ db_accession_code, db_version_date):

+ t = self.sysr.templates.get_by_id(template_id)

+ typ = self.type_map.get(db_name, db_name_other_details)

+ ref = typ(accession=db_accession_code,

+ db_version_date=_get_date(db_version_date))

+ t.references.append(ref)

+

+

+class _TemplatePolySegmentHandler(Handler):

+ category = '_ma_template_poly_segment'

+

+ def __call__(self, id, template_id, residue_number_begin,

+ residue_number_end):

+ segment = self.sysr.template_segments.get_by_id(id)

+ segment.template = self.sysr.templates.get_by_id(template_id)

+ segment.seq_id_range = (int(residue_number_begin),

+ int(residue_number_end))

+

+

+class _TemplateCustomizedHandler(Handler):

+ category = '_ma_template_customized'

+

+ def __call__(self, template_id, details):

+ template = self.sysr.templates.get_by_id(template_id,

+ modelcif.CustomTemplate)

+ template.details = details

+

+

+class _TemplateCoordHandler(Handler):

+ category = '_ma_template_coord'

+

+ def __call__(self, template_id, group_pdb, type_symbol, label_atom_id,

+ label_seq_id: int, auth_seq_id: int, auth_atom_id,

+ auth_comp_id, cartn_x: float, cartn_y: float, cartn_z: float,

+ occupancy: float, b_iso_or_equiv: float,

+ formal_charge: float):

+ template = self.sysr.templates.get_by_id(template_id,

+ modelcif.CustomTemplate)

+ atom = modelcif.TemplateAtom(

+ het=group_pdb is not None and group_pdb != 'ATOM',

+ type_symbol=type_symbol, atom_id=label_atom_id,

+ seq_id=label_seq_id, auth_seq_id=auth_seq_id,

+ auth_atom_id=auth_atom_id, auth_comp_id=auth_comp_id,

+ x=cartn_x, y=cartn_y, z=cartn_z, occupancy=occupancy,

+ biso=b_iso_or_equiv, charge=formal_charge)

+ template.atoms.append(atom)

+

+

+def _get_align_class(type_class, mode_class, align_class_map):

+ """Create and return a new class to represent an alignment"""

+ k = (type_class, mode_class)

+ if k not in align_class_map:

+ class Alignment(type_class, mode_class):

+ pass

+ align_class_map[k] = Alignment

+ return align_class_map[k]

+

+

+class _AlignmentInfoHandler(Handler):

+ category = '_ma_alignment_info'

+

+ def __init__(self, *args):

+ super(_AlignmentInfoHandler, self).__init__(*args)

+ # Map type to subclass of modelcif.alignment.AlignmentType

+ self._type_map = dict(

+ (x[1].type.upper(), x[1])

+ for x in inspect.getmembers(modelcif.alignment, inspect.isclass)

+ if issubclass(x[1], modelcif.alignment.AlignmentType)

+ and x[1] is not modelcif.alignment.AlignmentType)

+ # Map mode to subclass of modelcif.alignment.AlignmentMode

+ self._mode_map = dict(

+ (x[1].mode.upper(), x[1])

+ for x in inspect.getmembers(modelcif.alignment, inspect.isclass)

+ if issubclass(x[1], modelcif.alignment.AlignmentMode)

+ and x[1] is not modelcif.alignment.AlignmentMode)

+ # Cache created Alignment classes

+ self._align_class_map = {}

+

+ def __call__(self, alignment_id, data_id, software_group_id,

+ alignment_type, alignment_mode):

+ type_class = self._type_map.get(

+ alignment_type.upper(), modelcif.alignment.AlignmentType)

+ mode_class = self._mode_map.get(

+ alignment_mode.upper(), modelcif.alignment.AlignmentMode)

+ software = self.sysr.software_groups.get_by_id_or_none(

+ software_group_id)

+ align_class = _get_align_class(type_class, mode_class,

+ self._align_class_map)

+ alignment = align_class(name=None, pairs=[], software=software)

+ alignment._id = alignment_id

+ self.sysr.data_by_id[data_id] = alignment

+ alignment._data_id = data_id

+ self.sysr.system.alignments.append(alignment)

+

+ def finalize(self):

+ for aln in self.sysr.system.alignments:

+ for pair in self.sysr.alignment_pairs[aln._id]:

+ k = (pair.template._id, pair.target.asym._id)

+ pair.target.seq_id_range = \

+ self.sysr.target_template_poly_mapping.get(k)

+ aln.pairs.append(pair)

+ # todo: handle multiple alignments, multiple templates

+ for flag, sequence in self.sysr.alignment_seqs[aln._id]:

+ if flag == '2': # template

+ aln.pairs[0].template.gapped_sequence = sequence

+ else: # target

+ aln.pairs[0].target.gapped_sequence = sequence

+ # Handle nonpolymer templates

+ for tmpl_id, tgt_asym_id in self.sysr.target_asym_for_template.items():

+ template = self.sysr.templates.get_by_id(tmpl_id)

+ if not template.entity.is_polymeric():

+ asym = self.sysr.asym_units.get_by_id(tgt_asym_id)

+ asym.__class__ = modelcif.NonPolymerFromTemplate

+ asym.template = template

+ asym.explicit = self.sysr.ma_model_mode_map.get(

+ template.entity)

+

+

+class _AlignmentHandler(Handler):

+ category = '_ma_alignment'

+

+ def __call__(self, alignment_id, target_template_flag, sequence):

+ # Remember for later; processed by AlignmentInfoHandler.finalize()

+ self.sysr.alignment_seqs[alignment_id].append((target_template_flag,

+ sequence))

+

+

+class _AlignmentDetailsHandler(Handler):

+ category = '_ma_alignment_details'

+

+ def __init__(self, *args):

+ super(_AlignmentDetailsHandler, self).__init__(*args)

+ # Map denom to subclass of modelcif.alignment.Identity

+ self._ident_map = _EnumerationMapper(

+ modelcif.alignment, modelcif.alignment.Identity,

+ attr='denominator')

+ # Map score_type to subclass of modelcif.alignment.Score

+ self._score_map = _EnumerationMapper(

+ modelcif.alignment, modelcif.alignment.Score, attr='type')

+

+ def __call__(self, alignment_id, template_segment_id, target_asym_id,

+ score_type, score_type_other_details, score_value: float,

+ percent_sequence_identity: float,

+ sequence_identity_denominator,

+ sequence_identity_denominator_other_details):

+ if score_type:

+ score_class = self._score_map.get(score_type,

+ score_type_other_details)

+ score = score_class(score_value)

+ else:

+ score = None

+ if sequence_identity_denominator:

+ ident_class = self._ident_map.get(

+ sequence_identity_denominator,

+ sequence_identity_denominator_other_details)

+ ident = ident_class(percent_sequence_identity)

+ else:

+ ident = None

+ template = self.sysr.template_segments.get_by_id(template_segment_id)

+ asym = self.sysr.asym_units.get_by_id(target_asym_id)

+ # We don't know the target segment yet (will be filled in at finalize

+ # time from the ma_target_template_poly_mapping and ma_alignment

+ # tables)

+ tgt_seg = asym.segment(gapped_sequence=None, seq_id_begin=None,

+ seq_id_end=None)

+ p = modelcif.alignment.Pair(template=template, target=tgt_seg,

+ identity=ident, score=score)

+ # Cannot add to alignment yet as it might not exist; remember for

+ # now and we'll add in finalize() of AlignmentInfoHandler

+ self.sysr.alignment_pairs[alignment_id].append(p)

+

+

+class _TargetTemplatePolyMappingHandler(Handler):

+ category = '_ma_target_template_poly_mapping'

+

+ def __call__(self, template_segment_id, target_asym_id,

+ target_seq_id_begin: int, target_seq_id_end: int):

+ k = (template_segment_id, target_asym_id)

+ rng = (target_seq_id_begin, target_seq_id_end)

+ # Remember for now and we'll add in finalize() of AlignmentInfoHandler

+ self.sysr.target_template_poly_mapping[k] = rng

+

+

+class _AssemblyHandler(Handler):

+ category = '_ma_struct_assembly'

+

+ def __call__(self, assembly_id, asym_id, seq_id_begin, seq_id_end):

+ a = self.sysr.assemblies.get_by_id(assembly_id)

+ asym = self.sysr.asym_units.get_by_id(asym_id)

+ if seq_id_begin is None and seq_id_end is None:

+ a.append(asym)

+ else:

+ a.append(asym(int(seq_id_begin), int(seq_id_end)))

+

+ def finalize(self):

+ # Any AsymUnitRange which covers an entire asym,

+ # replace with AsymUnit object

+ for a in self.system.assemblies:

+ a[:] = [self._handle_component(x) for x in a]

+

+ def _handle_component(self, comp):

+ if isinstance(comp, modelcif.AsymUnitRange) \

+ and comp.seq_id_range == comp.asym.seq_id_range:

+ return comp.asym

+ else:

+ return comp

+

+

+class _AssemblyDetailsHandler(Handler):

+ category = '_ma_struct_assembly_details'

+

+ def __call__(self, assembly_id, assembly_name, assembly_description):

+ a = self.sysr.assemblies.get_by_id(assembly_id)

+ a.name = assembly_name

+ a.description = assembly_description

+

+

+class _ModelListHandler(Handler):

+ category = '_ma_model_list'

+

+ def __init__(self, *args):

+ super(_ModelListHandler, self).__init__(*args)

+ # Map model_type to subclass of modelcif.model.Model

+ self._type_map = _EnumerationMapper(

+ modelcif.model, modelcif.model.Model,

+ attr='model_type')

+ # Old-style model groups

+ self._old_group_for_model = {}

+

+ def finalize(self):

+ # Put all models not in a group in their own group

+ models_in_groups = frozenset(m._id for mg in self.system.model_groups

+ for m in mg)

+ # Get ungrouped models in the order encountered in the file

+ ungrouped = []

+ for m in self.sysr._all_seen_models:

+ if m._id not in models_in_groups:

+ # Use old-style group if present

+ mg = self._old_group_for_model.get(m._id)

+ if mg is None:

+ ungrouped.append(m)

+ else:

+ mg.append(m)

+

+ if ungrouped:

+ mg = modelcif.model.ModelGroup(ungrouped)

+ self.system.model_groups.append(mg)

+

+ def __call__(self, ordinal_id, model_group_id, model_name,

+ model_group_name, assembly_id, data_id, model_type,

+ model_type_other_details):

+ if self.sysr.default_model_class:

+ model_type = self._type_map.get(

+ model_type, model_type_other_details)

+ model = self.sysr.models.get_by_id(ordinal_id, model_type)

+ else:

+ model = self.sysr.models.get_by_id(ordinal_id)

+ model.model_type = model_type

+ model.name = model_name

+ self.sysr.data_by_id[data_id] = model

+ model._data_id = data_id

+ model.assembly = self.sysr.assemblies.get_by_id(assembly_id)

+ # Get group info if present (old dictionary)

+ if model_group_id not in (None, ihm.unknown):

+ mg = self.sysr.model_groups.get_by_id(model_group_id)

+ mg.name = model_group_name

+ self._old_group_for_model[ordinal_id] = mg

+

+

+class _ModelGroupHandler(Handler):

+ category = '_ma_model_group'

+

+ def __call__(self, id, name, details):

+ model_group = self.sysr.model_groups.get_by_id(id)

+ self.copy_if_present(model_group, locals(), keys=('name', 'details'))

+

+

+class _ModelGroupLinkHandler(Handler):

+ category = '_ma_model_group_link'

+

+ def __call__(self, group_id, model_id):

+ model_group = self.sysr.model_groups.get_by_id(group_id)

+ model = self.sysr.models.get_by_id(model_id)

+ model_group.append(model)

+

+

+class _ProtocolHandler(Handler):

+ category = '_ma_protocol_step'

+

+ def __init__(self, *args):

+ super(_ProtocolHandler, self).__init__(*args)

+ # Map method_type to subclass of modelcif.protocol.Step

+ self._method_map = dict(

+ (x[1].method_type.upper(), x[1])

+ for x in inspect.getmembers(modelcif.protocol, inspect.isclass)

+ if issubclass(x[1], modelcif.protocol.Step)

+ and x[1] is not modelcif.protocol.Step)

+

+ def __call__(self, protocol_id, method_type, step_name, details,

+ software_group_id, input_data_group_id, output_data_group_id):

+ p = self.sysr.protocols.get_by_id(protocol_id)

+ stepcls = self._method_map.get(method_type.upper(),

+ modelcif.protocol.Step)

+ indata = self.sysr.data_groups.get_by_id(input_data_group_id)

+ outdata = self.sysr.data_groups.get_by_id(output_data_group_id)

+ software = self.sysr.software_groups.get_by_id_or_none(

+ software_group_id)

+ step = stepcls(input_data=indata, output_data=outdata, name=step_name,

+ details=details, software=software)

+ p.steps.append(step)

+

+

+def _get_assoc_type_maps():

+ # Get a mapping from (file_content,file_format) to a subclass of

+ # modelcif.associated.File

+ cs = [x[1] for x in inspect.getmembers(modelcif.associated,

+ inspect.isclass)

+ if issubclass(x[1], modelcif.associated.File)

+ and x[1] is not modelcif.associated.File]

+ _type_map = dict(

+ ((x.file_content.upper(), x.file_format.upper()), x)

+ for x in cs if not hasattr(x, '_binary_ff_map'))

+ # Do the same thing for classes that take a 'binary' argument

+ _bin_type_map = {}

+ for x in cs:

+ if not hasattr(x, '_binary_ff_map'):

+ continue

+ file_content = x.file_content.upper()

+ for binary, file_format in x._binary_ff_map.items():

+ _bin_type_map[(file_content, file_format.upper())] = (x, binary)

+ return _type_map, _bin_type_map

+

+

+def _get_assoc_class(file_content, file_format, type_map, binary_type_map):

+ # Use previous mapping to get a subclass of modelcif.associated.File

+ # from (file_content, file_format)

+

+ # Map deprecated file_content to new equivalent

+ if file_content.upper() == 'LOCAL PAIRWISE QA SCORES':

+ file_content = 'QA METRICS'

+ k = (file_content.upper(), file_format.upper())

+

+ filecls_bin = binary_type_map.get(k)

+ if filecls_bin:

+ filecls, binary = filecls_bin

+ return functools.partial(filecls, binary=binary)

+ else:

+ return type_map.get(k, modelcif.associated.File)

+

+

+class _AssociatedHandler(Handler):

+ category = '_ma_entry_associated_files'

+

+ def __init__(self, *args):

+ super(_AssociatedHandler, self).__init__(*args)

+ self._repos_by_root = {}

+ self._type_map, self._binary_type_map = _get_assoc_type_maps()

+

+ def __call__(self, id, file_url, file_type, file_format, file_content,

+ details, data_id):

+ filecls = _get_assoc_class(

+ file_content, file_format, self._type_map, self._binary_type_map)

+ # Assume everything before last slash (if any) is URL root

+ url_root, path = posixpath.split(file_url)

+ url_root = url_root or None

+ r = self._repos_by_root.get(url_root)

+ if not r:

+ r = modelcif.associated.Repository(url_root=url_root, files=[])

+ self._repos_by_root[url_root] = r

+ self.system.repositories.append(r)

+ c = filecls(path=path, details=details, data=data_id)

+ r.files.append(c)

+ self.sysr.assoc_by_id[id] = c

+

+ def finalize(self):

+ # Map data_id to Data objects

+ for repo in self.system.repositories:

+ for f in repo.files:

+ f.data = self.sysr.data_by_id.get(f.data)

+

+

+class _AssociatedArchiveHandler(Handler):

+ category = '_ma_associated_archive_file_details'

+

+ def __init__(self, *args):

+ super(_AssociatedArchiveHandler, self).__init__(*args)

+ self._type_map, self._binary_type_map = _get_assoc_type_maps()

+ self._archive_files = collections.defaultdict(list)

+

+ def __call__(self, id, archive_file_id, file_path, file_format,

+ file_content, description, data_id):

+ filecls = _get_assoc_class(

+ file_content, file_format, self._type_map, self._binary_type_map)

+ c = filecls(path=file_path, details=description, data=data_id)

+ # Top-level archive file might not exist yet

+ self._archive_files[archive_file_id].append(c)

+

+ def finalize(self):

+ # Put files in archives

+ for archive_file_id, files in self._archive_files.items():

+ archive = self.sysr.assoc_by_id.get(archive_file_id)

+ if archive:

+ # Map data_id to Data objects

+ for f in files:

+ f.data = self.sysr.data_by_id.get(f.data)

+ archive.files = files

+

+

+class _FeatureListHandler(Handler):

+ category = '_ma_feature_list'

+

+ def __call__(self, feature_id, details):

+ if details:

+ f = self.sysr.features.get_by_id(feature_id)

+ f.details = details

+

+

+class _AtomFeatureHandler(Handler):

+ category = '_ma_atom_feature'

+

+ def __call__(self, feature_id, atom_id):

+ f = self.sysr.features.get_by_id(feature_id, modelcif.AtomFeature)

+ f.atoms.append(atom_id)

+

+

+class _PolyResidueFeatureHandler(Handler):

+ category = '_ma_poly_residue_feature'

+

+ def __call__(self, feature_id, label_seq_id: int, label_asym_id):

+ f = self.sysr.features.get_by_id(

+ feature_id, modelcif.PolyResidueFeature)

+ asym = self.sysr.asym_units.get_by_id(label_asym_id)

+ f.residues.append(asym.residue(label_seq_id))

+

+

+class _EntityInstanceFeatureHandler(Handler):

+ category = '_ma_entity_instance_feature'

+

+ def __call__(self, feature_id, label_asym_id):

+ f = self.sysr.features.get_by_id(

+ feature_id, modelcif.EntityInstanceFeature)

+ asym = self.sysr.asym_units.get_by_id(label_asym_id)

+ f.asym_units.append(asym)

+

+

+def _make_qa_class(type_class, mode_class, p_name, p_description, p_software):

+ """Create and return a new class to represent a QA metric"""

+ class QA(type_class, mode_class):

+ name = p_name

+ __doc__ = description = p_description

+ software = p_software

+ QA.__name__ = p_name

+ return QA

+

+

+class _QAMetricHandler(Handler):

+ category = '_ma_qa_metric'

+

+ def __init__(self, *args):

+ super(_QAMetricHandler, self).__init__(*args)

+ # Map mode to subclass of modelcif.qa_metric.MetricMode

+ self._mode_map = dict(

+ (x[1].mode.upper(), x[1])

+ for x in inspect.getmembers(modelcif.qa_metric, inspect.isclass)

+ if issubclass(x[1], modelcif.qa_metric.MetricMode)

+ and x[1] is not modelcif.qa_metric.MetricMode)

+ # Map type to subclass of modelcif.qa_metric.MetricType

+ # (also allow user-defined "other" classes)

+ self._type_map = _EnumerationMapper(

+ modelcif.qa_metric, modelcif.qa_metric.MetricType, attr="type")

+

+ def __call__(self, id, name, description, type, mode, type_other_details,

+ software_group_id):

+ type_class = self._type_map.get(type, type_other_details)

+ mode_class = self._mode_map.get(mode.upper(),

+ modelcif.qa_metric.MetricMode)

+ software = self.sysr.software_groups.get_by_id_or_none(

+ software_group_id)

+ self.sysr.qa_by_id[id] = _make_qa_class(

+ type_class, mode_class, name, description, software)

+

+

+class _QAMetricGlobalHandler(Handler):

+ category = '_ma_qa_metric_global'

+

+ def __call__(self, model_id, metric_id, metric_value: float):

+ model = self.sysr.models.get_by_id(model_id)

+ metric_class = self.sysr.qa_by_id[metric_id]

+ model.qa_metrics.append(metric_class(metric_value))

+

+

+class _QAMetricLocalHandler(Handler):

+ category = '_ma_qa_metric_local'

+

+ def __call__(self, model_id, label_asym_id, label_seq_id: int, metric_id,

+ metric_value: float):

+ model = self.sysr.models.get_by_id(model_id)

+ asym = self.sysr.asym_units.get_by_id(label_asym_id)

+ residue = asym.residue(label_seq_id)

+ metric_class = self.sysr.qa_by_id[metric_id]

+ model.qa_metrics.append(metric_class(residue, metric_value))

+

+

+class _QAMetricPairwiseHandler(Handler):

+ category = '_ma_qa_metric_local_pairwise'

+

+ def __call__(self, model_id, label_asym_id_1, label_seq_id_1: int,

+ label_asym_id_2, label_seq_id_2: int, metric_id,

+ metric_value: float):

+ model = self.sysr.models.get_by_id(model_id)

+ asym1 = self.sysr.asym_units.get_by_id(label_asym_id_1)

+ residue1 = asym1.residue(label_seq_id_1)

+ asym2 = self.sysr.asym_units.get_by_id(label_asym_id_2)

+ residue2 = asym2.residue(label_seq_id_2)

+ metric_class = self.sysr.qa_by_id[metric_id]

+ model.qa_metrics.append(metric_class(residue1, residue2, metric_value))

+

+

+class _QAMetricFeatureHandler(Handler):

+ category = '_ma_qa_metric_feature'

+

+ def __call__(self, model_id, feature_id, metric_id, metric_value: float):

+ model = self.sysr.models.get_by_id(model_id)

+ feature = self.sysr.features.get_by_id(feature_id)

+ metric_class = self.sysr.qa_by_id[metric_id]

+ model.qa_metrics.append(metric_class(feature, metric_value))

+

+

+class _QAMetricFeaturePairwiseHandler(Handler):

+ category = '_ma_qa_metric_feature_pairwise'

+

+ def __call__(self, model_id, feature_id_1, feature_id_2, metric_id,

+ metric_value: float):

+ model = self.sysr.models.get_by_id(model_id)

+ feature1 = self.sysr.features.get_by_id(feature_id_1)

+ feature2 = self.sysr.features.get_by_id(feature_id_2)

+ metric_class = self.sysr.qa_by_id[metric_id]

+ model.qa_metrics.append(metric_class(feature1, feature2, metric_value))

+

+

+class ModelCIFVariant(Variant):

+ """Used to select typical PDBx/ModelCIF file input.

+ See :func:`read` and :class:`ihm.reader.Variant`."""

+ system_reader = _SystemReader

+

+ _handlers = [

+ ihm.reader._StructHandler, ihm.reader._SoftwareHandler,

+ ihm.reader._CitationHandler, ihm.reader._AuditAuthorHandler,

+ ihm.reader._AuditRevisionHistoryHandler,

+ ihm.reader._AuditRevisionDetailsHandler,

+ ihm.reader._AuditRevisionGroupHandler,

+ ihm.reader._AuditRevisionCategoryHandler,

+ ihm.reader._AuditRevisionItemHandler, ihm.reader._DataUsageHandler,

+ ihm.reader._GrantHandler, ihm.reader._CitationAuthorHandler,

+ _ChemCompHandler, _ChemCompDescriptorHandler,

+ ihm.reader._EntityHandler,

+ ihm.reader._EntitySrcNatHandler, ihm.reader._EntitySrcGenHandler,

+ ihm.reader._EntitySrcSynHandler, ihm.reader._EntityPolyHandler,

+ ihm.reader._EntityPolySeqHandler, _EntityNonPolyHandler,

+ ihm.reader._StructAsymHandler, _SoftwareGroupHandler,

+ _DatabaseHandler, _SoftwareParameterHandler,

+ _DataHandler, _DataGroupHandler, _DataRefDBHandler,

+ _TargetEntityHandler, ihm.reader._StructRefHandler,

+ ihm.reader._StructRefSeqHandler, ihm.reader._StructRefSeqDifHandler,

+ _TargetRefDBHandler, _TransformationHandler, _TemplateDetailsHandler,

+ _TemplateRefDBHandler, _TemplatePolySegmentHandler,

+ _TemplateCustomizedHandler, _TemplateCoordHandler,

+ _TemplatePolyHandler, _TemplateNonPolyHandler,

+ _AlignmentHandler, _AlignmentInfoHandler, _AlignmentDetailsHandler,

+ _TargetTemplatePolyMappingHandler,

+ _AssemblyHandler, _AssemblyDetailsHandler, ihm.reader._AtomSiteHandler,

+ ihm.reader._PolySeqSchemeHandler, ihm.reader._NonPolySchemeHandler,

+ _ModelListHandler, _ModelGroupHandler, _ModelGroupLinkHandler,

+ _ProtocolHandler, _AssociatedHandler, _AssociatedArchiveHandler,

+ _FeatureListHandler, _AtomFeatureHandler,

+ _PolyResidueFeatureHandler, _EntityInstanceFeatureHandler,

+ _QAMetricHandler, _QAMetricGlobalHandler, _QAMetricLocalHandler,

+ _QAMetricPairwiseHandler, _QAMetricFeatureHandler,

+ _QAMetricFeaturePairwiseHandler]

+

+ def get_handlers(self, sysr):

+ return [h(sysr) for h in self._handlers]

+

+ def get_audit_conform_handler(self, sysr):

+ return _AuditConformHandler(sysr)

+

+

+def read(fh, model_class=modelcif.model.Model, format='mmCIF', handlers=[],

+ warn_unknown_category=False, warn_unknown_keyword=False,

+ reject_old_file=False, variant=ModelCIFVariant,

+ add_to_system=None):

+ """Read data from the file handle `fh`.

+

+ See :func:`ihm.reader.read` for more information. The function

+ here behaves similarly but reads in files compliant with the

+ ModelCIF extension directory rather than IHM.

+

+ Note that if a custom ``model_class`` is provided, any models present

+ in the file will be returned as that type, regardless of their type

+ stated in the mmCIF file (e.g. homology model, ab initio model).

+ (However, the ``model_type`` attribute will be set appropriately.)

+

+ If the input file references any associated files, they will be

+ listed in :attr:`modelcif.System.repositories`. The files will not be

+ automatically downloaded or read in, but it is straightforward to do

+ this in Python; see the

+ `associated files example <https://github.com/ihmwg/python-ma/blob/main/examples/associated.py>`_.

+

+ :return: A list of :class:`modelcif.System` objects.

+ """ # noqa: E501

+ return ihm.reader.read(

+ fh, model_class=model_class, format=format, handlers=handlers,

+ warn_unknown_category=warn_unknown_category,

+ warn_unknown_keyword=warn_unknown_keyword,

+ reject_old_file=reject_old_file, variant=variant,

+ add_to_system=add_to_system)