Inconsistent field naming

[kalcutter]

There seems to be an inconsistency how fields are named. For example: beam_center_x vs. x_pixel_size. I think having _x as a suffix (like beam_center_x) would be preferable. What is the proper way to get this change considered?

[prjemian]

@kalcutter: Thanks for the question. This is the proper place to raise the question. As I recall, the NIAC has discussed this previously and decided that to tolerate the inconsistency for compatibility with existing data files. (Readers that expect these fields would need to be modified to handle multiple variations. While this instance seems quite easy to accommodate, other design aspects pose substantial special-case code, such as finding the default NXdata group to plot).

That said, one way is to preserve the existing name (x_pixel_size) but mark it as deprecated with documentation describing the suggested replacement. This would keep older data files valid while providing a more-consistent naming style. Here is an example of a deprecated field:

definitions/base_classes/NXdetector.nxdl.xml

Lines 53 to 54 in 30bab98

	<attribute name="axis" type="NX_POSINT"
	deprecated="see: https://github.com/nexusformat/definitions/issues/436">

A pull request would be helpful.

[prjemian]

Note:

definitions/nxdl.xsd

Lines 143 to 158 in 66d70f4

	The presence of the ``deprecated`` attribute
	indicates to the data file validation process that
	an advisory message (specified as the content of the
	``deprecated`` attribute) will be reported.
	Future versions of the NXDL file might
	not define (or even re-use) the component marked with this attribute.
	The value of the attribute will be printed in the documentation.
	Make it descriptive (limited to no line breaks).
	For example::
	deprecated="as of release MAJOR.MINOR"
	Note: because ``deprecated`` is an attribute,
	the XML rules do not permit it to have any
	element content.

[kalcutter]

Thanks for the clarification. I think deprecation makes sense in this case. Another broader question I have is: why are x and y prefixes and suffixes used at all? I think it would be more consistent to represent these things as multi-dimensional datasets like is done for data_origin and data_size from NXdetector_module (also consider NXtransformations and many other examples). I can make a PR for these changes if there is consensus on how I should proceed.

[benajamin]

Proposal is to recommend that names including a common part and a specific part start with the common and then adding the specific parts later (e.g. beam_center_x). This does not include changing any existing names - just making a recommendation for the creation of new names.

• thumbs up to accept
• thumbs down to reject
• any other emoji to abstain

[prjemian]

At NIAC2020, we discussed this and decided to leave the existing cases as-is but to make a recommendation for the future to put the modifying term last rather than first (e.g., some_term_x, some_term_y). We also discussed whether to be explicit (separate x and y) or make a list such as (x, y) that matches the dimensionality of the data described. That is a separate discussion.

[prjemian]

The recommendation would go into the design chapter.

[prjemian]

Specifically, the change would be added to the datarules page under the Naming Conventions section.