The following sections provide examples of how one might approach each of these extensions.
This is the simplest type of modification in which a new data item definition
is appended to an existing category. The first step in adding an item
to an existing dictionary is to verify that the data item is not already defined
within that dictionary. If the item cannot be found in the
mmCIF dictionary it may be worthwhile to post a message to the mmCIF
Discussion List (
verify that the item is indeed not included in the dictionary and
that it has not already been defined locally by someone else.
After determining that the data item represents new content, the next step is to select an appropriate item name. In this example, the data item is being added to an existing category so that portion of the item name is fixed. The remaining portion should be chosen to conform with the style of other data item names within the category. At the moment, the recommended practice is to prefix local data items with an institutional acronym. These acronyms can be registered and reserved with the IUCr, which maintains the clearinghouse of these reserved prefixes.
Having chosen a data name, then the item definition can be constructed.
In building the definition a description must be crafted and some consideration
should be given to a default value, examples, and any range restrictions. Check
the table of know data types in
known units in
ITEM_UNITS_LIST for an appropriate value.
If an appropriate value cannot be found, then additional entries
in these categories are required in order to create the new data type or
system of units. Extending the list of known units also requires
extensions to the table of unit conversions,
Here is template for the new item definition.
save__existing_category.acronym_new_item_name _item_description.description ; Description goes here ... ; _item.name '_existing_category.acronym_new_item_name' _item.category_id existing_category _item.mandatory_code no _item_default.value ? loop_ _item_examples.case _item_examples.detail ? ? loop_ _item_range.maximum _item_range.minimum ? ? _item_type.code ? _item_units.code ? save_
If the new data item can only have a discrete set of values, then
the data items in the
ITEM_RANGE category in the above example
should be replaced by items from the
The choice of the data items which compose the unique identifier for each row of the category is crucial. In most cases this should be a straightforward decision. However, when the choice is not clear it may indicate that multiple categories are required to properly represent the collection of data items.
Once the category key has been selected, an appropriate set of category and data item names must be chosen. In this case, the category name can carry the institutional prefix that will identify the category and its associated data items as locally developed. In building the category definition, a description must be created and some examples of the full category should be developed. Some consideration should also be given to the membership of the new category in an existing category group.
Here is template for the new category definition.
save_ACRONYM_NEW_CATEGORY _category.description ; Description goes here ... ; _category.id acronym_new_category _category.mandatory_code no loop_ _category_key.name '_acronym_new_category.key_item_1' loop_ _category_group.id 'inclusive_group' ? loop_ _category_examples.detail _category_examples.case ? ? save_
A new category may contain subsets of items which have relationships
which can be described in categories
ITEM_DEPENDENT. Data items from these categories
should be added to item definitions as required.
save__acroynm_new_category.entity_id _item_description.description ; This data item is a pointer to item _entity.id defined in the ENTITY category. ; _item.name '_acroynm_new_category.entity_id' _item.category_id acronym_new_category _item.mandatory_code yes _item_linked.parent_name '_entity.id' _item_linked.child_name '_acroynm_new_category.entity_id' save_