Skip to content

Improve _refine_ls.abs_structure_z-score description#619

Merged
jamesrhester merged 2 commits into
COMCIFS:mainfrom
danielnrainer:abs_structure_zscore_description_update
Jun 29, 2026
Merged

Improve _refine_ls.abs_structure_z-score description#619
jamesrhester merged 2 commits into
COMCIFS:mainfrom
danielnrainer:abs_structure_zscore_description_update

Conversation

@danielnrainer

Copy link
Copy Markdown
Contributor

I'd like to suggest (also based on a recent email conversation with @lukaspalatinus) a slight tweak to the description text in the new data name _refine_ls.abs_structure_z-score to clarify that further description and details about the origin of the stated z-score value are to be given in the data name _refine_ls.abs_structure_details.
Although the principle of the z-score calculation for the case of determination of the absolute structure of a crystal structure is presumably always the same, details about the calculation itself may differ, potentially leading significantly different values (even if the conclusion remains the same). One such case is the difference between "raw" z-score values and "noise-adjusted" ones, which is also discussed in the Klar et al reference.

I also added the links to the two references, in line with references given in the descriptions of other data names throughout the dictionary.

- explicitly mention _refine_ls.abs_structure_details to provide details on how the z-score value was calculated
- add links to references

@jamesrhester jamesrhester left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a useful clarification. Automated methods won't be able to work with the arbitrary text of refine_ls.abs_structure_details, and if the z-score can vary by so much, is it worth having a separate data name that enumerates the possible ways of calculating the z-score? Or different data names for different calculation methods?

@rowlesmr

Copy link
Copy Markdown
Collaborator

I've been told previously that we don't like the interpretation of a value to be affected by the value of something else; so different data names for different methods?

@lukaspalatinus

Copy link
Copy Markdown

My understanding is that the CIF standard does not always specify the exact formulas for individual values. It would be very impractical and often impossible. A trivial example: the intensity e.s.d.s can be determined in a bazillion different ways, yet there are no keywords in the CIF dictionary enumerating the possibilities, nor a definition of how exactly the e.s.d.s should be calculated. An example more closely related to the current problem: there are various ways to calculate the Flack parameter, and the definition of the CIF entry _refine_ls.abs_structure_flack does not specify which variant is acceptable and which is not. The various ways to calculate the z-score fall in a similar category as different variants of calculating the Flack parameter. The important aspect is the meaning of the value - the significance level of reliability of the absolute structure determination. That the value is calculated correctly and appropriately is the responsibility of the person creating the CIF.
For these reasons, I am still in favor of keeping the current general definition and not restricting it to one specific method of calculating the z-score. It would also allow for accommodating better ways to estimate the z-score in the future.

@jamesrhester

Copy link
Copy Markdown
Contributor

I've been told previously that we don't like the interpretation of a value to be affected by the value of something else; so different data names for different methods?

Yes, that's true. The Klar et. al. reference discusses two types of scores, the z-score and the "adjusted" z-score, so we could make a second definition to cover the adjusted one as well.

However, if the situation is as complicated as @lukaspalatinus says, there's no point picking out particular variations until the community has settled on one or two that are best. It is also true that the interpretation of the z-score does not depend on the way it was calculated (just like background or esd): it provides a measure of how likely the enantiomorph assignment is correct, regardless of how calculated, so what I call the "downstream" meaning does not vary.

In my opinion we can just accept this PR.

@jamesrhester jamesrhester merged commit e276ebf into COMCIFS:main Jun 29, 2026
3 checks passed
@danielnrainer danielnrainer deleted the abs_structure_zscore_description_update branch June 29, 2026 08:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants