"""Functionality to access data in a ModelCIF file"""
[docs]
def get_table(block, category, items=None):
"""Get a |gemmi.cif.Table|_ from a |gemmicifBlock| for a category.
It is much more convenient to work with |gemmi.cif.Table|_ objects instead
of Gemmi's loops and pairs directly. Imagine a ModelCIF file in which a
certain category is represented as loop, while another ModelCIF file stores
the same category as list of pairs. Both representations may be valid
ModelCIF files and would require two separate handlers implemented for
essentially the same data.
By using |gemmi.cif.Table|_ as a wrapper, loops and pairs can be treated
uniformly, allowing you to handle both cases through a single code base.
Gemmi provides two functions to retrieve tables,
:func:`find_mmcif_category()` and :func:`find()`. One of them just needs a
category name and the other requires a category name and a list of columns
to fetch. So, different behaviour again and... lets just accept:
:func:`get_table()` hides these details away and happily returns a table,
whether you provide a list of items or not. If a list of items is given,
the resulting table will contain only those columns. Plus, in case the
category can't be found in block, ``None`` is returned, which feels more
pythonic than getting an empty table back of length 0.
Example:
>>> from gemmi import cif
>>> from modelarchive.modelcif import access
>>> # get sample CIF data
>>> cif_data = '''data_test
... _ma_qa_metric.id 1
... _ma_qa_metric.description test_score
... loop_
... _ma_qa_metric_local.ordinal_id
... _ma_qa_metric_local.metric_value
... _ma_qa_metric_local.metric_id
... 1 1.0 1
... 2 1.5 1
... '''
>>> block = cif.read_string(cif_data).sole_block()
>>> table = access.get_table(block, "_ma_qa_metric")
>>> len(table)
1
>>> table[-1]["description"]
'test_score'
>>> table = access.get_table(
... block,
... "_ma_qa_metric_local",
... items=["metric_id", "metric_value"],
... )
>>> # table should have 2 columns and 2 rows
>>> table
<gemmi.cif.Table 2 x 2>
>>> # columns are sorted as requested, not as stored
>>> table.tags[0]
'_ma_qa_metric_local.metric_id'
>>> table.tags[1]
'_ma_qa_metric_local.metric_value'
Args:
block (|gemmicifBlock|): CIF data block holding the categories of the
CIF document.
category (str): Category to fetch from ``block``, single category only,
no Joins. Gemmi requires category names to end with ``.``, so this
function adds it if missing.
items (list[str]): List of items to fetch as columns. Order of columns
(items) follows the provided list. If ``None``, the whole category
with all its items as columns will be fetched. In case of ``None``,
items are fetched in the same order as they are found in the CIF
document.
Returns:
|gemmi.cif.Table|_ | ``None``: The requested table if category can be
found, otherwise ``None``.
"""
if category[-1] != ".":
category = f"{category}."
if items is None:
table = block.find_mmcif_category(category)
else:
table = block.find(category, items)
if len(table) == 0:
return None
return table
# LocalWords: mmcif param str gemmi cif pythonic Gemmi's func