mmcif: Read and write mmCIF files

mmcif: mmCIF format support

Read mmCIF files.

class CIFTable

Bases: object

Supported API. Present a table interface for a (mm)CIF category

Tags should be in the mixed case version given in the associated dictionary

extend(table)

Supported API . Extend mmCIF table

Parameters:

  • table (CIFTable to add on to current table)

  • exists (If a column with a given tag)

  • extended. (then that column is)

  • Otherwise

  • table. (a new column is added to the)

field_has(field_name, value)

Supported API . Return if given field has the given value

fields(field_names, *, allow_missing_fields=False, missing_value='')

Supported API . Return subset of rows of the table for the given fields

Parameters:

  • field_names – a sequence of the field names

  • allow_missing_fields – optional boolean (default False)

  • missing_value – optional missing_value object (default ‘’)

A list of tuples is return where each tuple’s items are the values corresponding to the given field names in the given order. If missing fields are allowed, then the corresponding items are the missing_value object.

has_field(field_name)

Supported API . Return if given field name is in the table

mapping(key_names, value_names, foreach_names=None)

Supported API . Return a dictionary for subset of the table

Parameters:

  • key_names – a field name or list of field names

  • value_names – a field name or list of field names

  • foreach_names – optional field name or list of field names

If foreach_names is not given, then the resulting dictionary is whose keys are the values of the key field(s) and the values are the values of the value field(s). If foreach_names is given, then the result is a dicttionary of dictionaries, with the nested dictionaries as above, and the outer dictionary’s keys are the values of the foreach fields.

num_rows()

Supported API . Return number of rows in table

print(file=None, *, fixed_width=False)

Supported API . Print contents of table to given file

Parameters:

  • file – CIFTable to add on to current table

  • fixed_width – true if fixed width columns should be used

The fixed width column output matches the PDBx/mmCIF style syntax. If fixed_width is asked for and it is not possible to have fixed width columns (e.g., there is a newline in a string field), then the first row is broken up into multiple lines.

exception TableMissingFieldsError

Bases: ValueError

Supported API. Required field is missing

add_citation(model, citation_id, info, authors=(), editors=(), *, metadata=None)

Experimental API . Add citation to model’s mmCIF metadata

Parameters:

  • model – instance of a AtomicStructure The model.

  • citation_id – string The citation identifier.

  • info – dictionary Information about citation

  • authors – sequence Optional sequence of the authors.

  • editors – sequence Optional sequence of book or book chapter editors.

  • metadata – optional metadata dictonary Allow reuse of existing metadata dictionary.

Update the mmCIF ‘citation’, ‘citation_author’, and ‘citation_editor’ tables with the given informaiton. If the citation_id is already present in the citation table, then nothing is done.

The info dictionary is for the relevant data items from the mmCIF citation category, https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v40.dic/Categories/citation.html except for the citation id which is given as an argument to this function. The capitalization should match that in the mmCIF dictionary. In particular, the following data items are supported:

‘title’, ‘journal_abbrev’, ‘journal_volume’, ‘year’, ‘page_first’, ‘page_last’, ‘journal_issue’, ‘pdbx_database_id_PubMed’, ‘pdbx_database_id_DOI’

add_software(model, name, info, *, metadata=None)

Experimental API . Add citation to model’s mmCIF metadata

Parameters:

  • model – instance of a AtomicStructure The model.

  • info – dictionary Information about software

  • metadata – optional metadata dictonary Allow reuse of existing metadata dictionary.

Update the mmCIF ‘software’ table with the given informaiton. If the name is already present in the software table, then nothing is done.

The info dictionary is for the relevant data items from the mmCIF softare category, https://mmcif.wwpdb.org/dictionaries/mmcif_pdbx_v40.dic/Categories/software.html except for the name, which is given as an argument to the function, and pdbx_ordinal, which is computed. The capitalization should match that in the mmCIF dictionary. In particular, the following data items are supported:

‘name’, ‘version’, ‘location’, ‘classification’, ‘os’, ‘type’, ‘citation_id’

citations(model, only=None, metadata=None)

Experimental API . Return APA-style HTML citations for model

Parameters:

model (instance of a AtomicStructure) – The model.

fetch_ccd(session, ccd_id, ignore_cache=False)

Experimental API . Get structure for CCD component

fetch_mmcif(session, pdb_id, fetch_source='rcsb', ignore_cache=False, structure_factors=False, over_sampling=1.5, **kw)

Experimental API . Get mmCIF file by PDB identifier via the Internet

fetch_pdb_redo(session, pdb_id, ignore_cache=False, **kw)

Experimental API . Get mmCIF file from PDB-REDO repository

find_template_residue(session, name)

Supported API . Lookup mmCIF component template residue.

The component is fetched from the web if not already loaded

get_cif_tables(filename, table_names, *, all_data_blocks=False)

Supported API . Extract CIF tables from a file

Parameters:

  • filename (str) – The name of the file.

  • table_names (list of str) – A list of CIF category names.

  • all_data_blocks (bool) – If true, return tables from data blocks in file. Default is False.

Returns:

list

If all_data_blocks is false, return list of CIF tables found and all of the data values in a CIFTable. If all_data_blocks is true, return a list of (dat-block-name, list of CIP-tables) tuples.

get_mmcif_tables(filename, table_names)

Experimental API . Deprecated API. Use get_cif_tables() instead.

get_mmcif_tables_from_metadata(obj, table_names, *, metadata=None)

Supported API . Extract mmCIF tables from previously read metadata

Parameters:

  • obj (object) – An object with a ‘metadata’ attribute. For example: an AtomicStructure instance or a TmplResidue instance.

  • table_names (list of str) – A list of mmCIF category names.

  • metadata (optional metadata dictonary) – Allow reuse of existing metadata dictionary.

:param Returns a list of CIFTable`s or :external+python:ref:`None: :param : :param one for each table name.:

load_mmCIF_templates(filename)

Supported API . Load mmCIF component templates from given file

The file format should match the components.cif file from the PDB