Re: [ddlm-group] Proposal to update dREL, part II
- To: Group finalising DDLm and associated dictionaries <firstname.lastname@example.org>
- Subject: Re: [ddlm-group] Proposal to update dREL, part II
- From: "Bollinger, John C" <John.Bollinger@STJUDE.ORG>
- Date: Wed, 19 Sep 2018 18:11:36 +0000
- Accept-Language: en-US
- authentication-results: spf=none (sender IP is )smtp.mailfrom=John.Bollinger@STJUDE.ORG;
- DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=SJCRH.onmicrosoft.com; s=selector1-stjude-org;h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck;bh=9zhtHAo+NRWf4GtY5T66FVonzHIMJd7QfM0BSrM77a0=;b=Tgu819lQGQqlcr/62OkOOkMJ+XjUWete0Ebs8pU/qPvOaXxA5HIUTIaDpoAeJSrnfcXvbCyYB+SSGCGHsHXxd7X60+A1ac1agbKsJhGIFvwdU4RQeMh+1KUKCkcNqvxaCfyUFjMbiJiSZsnDdz8hEC87ZYti+5Mqtbz4U29M3fw=
- In-Reply-To: <CAM+dB2c-rOHjEDqQcZ3+AJsoKP9JwERvV2f=B5_HMVXoM3kKMw@mail.gmail.com>
- References: <CAM+dB2c-rOHjEDqQcZ3+AJsoKP9JwERvV2f=B5_HMVXoM3kKMw@mail.gmail.com>
- spamdiagnosticmetadata: NSPM
- spamdiagnosticoutput: 1:99
Dear DDLm group,
With respect to proposal 3, I agree in principle that the proposed syntax extension seems to yield an improvement, but the details are not completely clear to me. Specifically,
- May the _category.key_id be used in the expanded syntax? Including if it is not named as a _category_key.name?
- More generally, which attributes are permitted to be used to index a category? Must they be among those whose names are listed in the category’s own _category_key.name attribute, or is this to become a more general facility?
- Is it necessary to specify a complete key when this syntax is used for a category with a compound natural key?
- In the proposed syntax, are the key names given as simple attribute names or as full CIF item names?
With respect to proposal 4, I agree with the general idea that dREL should prefer to avoid requiring method implementations to explicitly express category keys that can reliably be determined from context. How that applies here depends to some extent on proposal 3, however.
Additionally, before considering going forward with this proposal, I think we need to describe more formally the cases in which the key values can be conveyed implicitly. For example, the description remarks that “this short cut is not possible where more than one data name is linked to the same category key”, but I’m not confident that I know how to recognize all such cases programmatically.
Also relevant: are we assuming that linked items are always [components of] their categories’ keys? Does anything break under this proposal if non-key attributes are linked?
John C. Bollinger, Ph.D.
Computing and X-Ray Scientist
Department of Structural Biology
St. Jude Children's Research Hospital
(901) 595-3166 [office]
From: ddlm-group [mailto:email@example.com]
On Behalf Of James Hester
It appears that after preparing part II I completely forgot to send it to the group. The marked-up version of this second proposal is available at https://github.com/COMCIFS/dREL/blob/master/drel_changes_2.rst
Proposed changes to dREL, part II
dREL is a machine-actionable language describing data relationships
and designed to be embedded in DDLm dictionaries. The language is
defined both explicitly in the dREL publication  and implicitly by
the dREL code appearing in the DDLm core CIF dictionary. Note that
the code in the core CIF dictionary significantly expands the language
presented in the paper, for example, by adding category methods.
The present changes were foreshadowed in the discussion about allowing
set methods to become looped . They are aimed at removing the
current dREL-imposed requirement that all categories must have a
single data name that acts as a key.
Proposal 3: compound key specification
dREL as published permits a particular row in a loop to be specified
by providing the value of the key for that loop using the syntax
``<category>[keyvalue]``, so for example, ``atom_site['O1']`` would be the
row in the atom_site loop for which ``_atom_site.label`` (the key data
name for category ``atom_site``) is 'O1'. We propose expanding
this syntax to allow multiple key values to be specified:
``<category>[name1=value1,name2=value2]`` would specify the row of
``<category>`` for which category objects ``name1`` and ``name2`` take
values of ``value1`` and ``value2`` respectively.
The current core CIF dictionary treats multi-key categories by
defining a synthetic data name for each such category. These synthetic
data names are currently just a list of the values of the multiple
keys. Having such single-dataname keys allows the dREL syntax to
be unambiguous for all Loop categories.
This approach is suboptimal because:
(1) The synthetic data names have no scientific relevance
(2) A considerable amount of DDLm machinery has been developed simply
because of the resulting inhomogeneous lists. Without
these synthetic data names, there would be *no* need in the current
core dictionary for ragged and nested dimensions and multiple
data types within a single list, and therefore no requirement
for DDLm and dREL implementors to cope with such structures.
(3) dREL methods wishing to index into a multi-key category have to
construct the synthetic keys from the individual values; the new
syntax would save that line of boilerplate
(4) If a set category becomes looped, a number of looped categories
will acquire a new key data name. If single-key loops remain a
dREL requirement, previously single-key loops will require a new,
synthetic data name to be created. Note that it could be argued
that this is the way the system was designed to work.
The previous syntax will still be acceptable in those situations where
there is a single key, or where the values of the remaining keys are
unambiguous in context (see next proposal).
This proposed syntax has been included in the example EBNF for dREL
and the transformation to Python code implements the proposed semantics.
Proposal 4: elide keys where they are clear from context
If category A contains data names which are parents or children of key
data names in category B, dREL methods in category A do not need to
explicitly specify the key values of category B when accessing rows of
If b.k1 and b.k2 are the keys of category B, and data names A.a1 and
A.a2 are linked through ``_name.linked_item_id`` DDLm declarations to
those keys, then any dREL method in category A can simply write ``b.d3``
to access a specific value of dataname ``d3`` in category ``b``. This is
equivalent to writing ``b[k1=a.a1,k2=a.a2].d3`` under proposal 3.
Note that this short cut is not possible where more than one data name
is linked to the same category key, for example, in ``geom_bond``
two data names are linked to ``atom_site.label``.
Note that partial resolution of data names is also possible, so that
key references that are missing from the original form may be resolved
using linked data names.
The net result of the above two proposals is to make looping Set
categories relatively painless. A dREL reference like ``cell.vector_a``
may remain untouched when multiple cells are present, as long as the
category within which the dREL method appears has only a single
data name that is a child of the single key data name of ``cell``.
However, in situations where the ``<category>[value]`` syntax has
been used and ``<category>`` acquires a new key data name because
some other category has become looped, dREL methods will need
to be rewritten to explicitly specify the key data name that
``value`` corresponds to. Going forward, the ``[key=value]``
syntax should be preferred to minimise the need to rewrite
methods in advanced looping applications.
We should also be aware the dREL methods in our dictionaries are
curated, and therefore we can apply style guidelines to prefer the
explicit notation of proposal 3 as we see fit.
 Spadaccini et. al,
(2012) *J. Chem. Inf. Model.* **52**(8) pp 1917-1925
T +61 (02) 9717 9907
Email Disclaimer: www.stjude.org/emaildisclaimer
Consultation Disclaimer: www.stjude.org/consultationdisclaimer
_______________________________________________ ddlm-group mailing list firstname.lastname@example.org http://mailman.iucr.org/cgi-bin/mailman/listinfo/ddlm-group
Reply to: [list | sender only]
- Re: [ddlm-group] Proposal to update dREL, part II (James Hester)
- [ddlm-group] Proposal to update dREL, part II (James Hester)