From 80051e2ea11941694af72db49bd3e5d1a8aa3627 Mon Sep 17 00:00:00 2001 From: mkuehbach Date: Mon, 15 Jan 2024 15:36:40 +0100 Subject: [PATCH] Providing feedback to hidden conversations --- contributed_definitions/NXem.nxdl.xml | 39 ++++++-------- .../cgms-structure.rst | 53 +++++++++---------- .../contributed_definitions/em-structure.rst | 6 +-- .../transport-structure.rst | 10 +++- 4 files changed, 50 insertions(+), 58 deletions(-) diff --git a/contributed_definitions/NXem.nxdl.xml b/contributed_definitions/NXem.nxdl.xml index 508d808cdb..fd980b67b2 100644 --- a/contributed_definitions/NXem.nxdl.xml +++ b/contributed_definitions/NXem.nxdl.xml @@ -176,9 +176,9 @@ that it is required--> to new versions. **Verification of constraints and conditions**: - Tools like NeXus so far do not avoid or protect against all such possible - inconsistencies; however NeXus offers a mechanism and toolset, through which - schemas can be documented and defined. In effect, having an openly documented + Tools like NeXus do not avoid or protect against all such possible inconsistencies; + however NeXus offers a mechanism and toolset, through which schemas can be + documented and defined. In effect, having an openly documented (at a case-specific level of technical detail) schema is a necessary but alone not a sufficient step to take EM research on a route of machine-actionable and interoperable FAIR data. @@ -269,17 +269,11 @@ that it is required--> **This application definition has the following components at the top-level:** - * Generic experimental details (time-zone-aware timestamp, identifiers, name); - conceptually these are session details. A session at a microscope may - involve the characterization of multiple specimens. For each specimen - an instance of an (NXentry) is created. Details of the instrument have to - be stored at least in an entry. Other entries should refer to these - metadata via links to reduce redundancies. * Each signal, such as a spectrum or image taken at the microscope, should have an associated time-zone-aware time stamp and report of the specific settings of the microscope at that point in time when the image was taken. - This is why instances of :ref:`NXevent_data_em` have an own em_lab section. - The reason is that EMs can be highly dynamic, be used to illuminate the specimen + This is why instances of :ref:`NXevent_data_em` have their own em_lab section. + The reason is that EMs can be highly dynamic, used to illuminate the specimen differently or show drift during signal acquisition, to name but a few effects. What constitutes a single EM experiment/measurement? This can be the collecting of a single diffraction pattern with a scanning TEM (STEM), @@ -294,25 +288,25 @@ that it is required--> relevant for documenting as exactly as practically possible settings when images and spectra were taken. * :ref:`NXinstrument`; - conceptually this is a container to store arbitrary level of detail of the + conceptually this is a container to store an arbitrary level of detail of the technical components of the microscope as a device and the lab in which the microscope is operated. * :ref:`NXuser`; conceptually, this is a set with at least one NXuser instance which details who operated or performed the measurement. Additional NXusers can be referred to in an NXevent_data_em instance to store - individualized details who executed an event of data acquisition or processing. + individualized details of who executed an event of data acquisition or processing. * :ref:`NXevent_data_em` instances as an NXevent_data_em_set; each NXevent_data_em instance is a container to group specific details about the state of the microscope when a measurement was taken and relevant data and eventual processing steps were taken (on-the-fly). - * :ref:`NXdata`; at the top-level, conceptually, this is a place for documenting - available default plottable data. A default plottable can be useful for - research data management systems to show a visual representation of some + * :ref:`NXdata`; at the top-level, this is a place for documenting available + default plottable data. A default plottable can be useful for research data + management systems to show a visual representation of some aspect of the content of the EM session. - Default plottables not intended to serve every possible analysis and - visualization demand but be a preview. We made this choice because what - constitutes a useful default plot is often a matter of interpretation, + Default plottables are not intended to serve every possible analysis and + visualization demand but are instead a preview. We made this choice + because what constitutes a useful default plot is often a matter of interpretation, somewhat of personal taste, and community standards. In effect, default plottables are case- and method-specific. @@ -326,11 +320,8 @@ that it is required--> * Images and spectra should be stored as :ref:`NXimage_set` and :ref:`NXspectrum_set` instances to hold data at the earliest possible step in the computational processing (which is usually performed with the microscope control and or - integrated analysis software). The formatting of the NXdata groups enables to - display image and spectra with web technology visualization software. - NeXus specifies only the data model, i.e. the terms and their relations. - These descriptions can be implemented and stored in JSON, HDF5, XML, or HSDS, - file storage, or even other formats, although HDF5 is often used. + integrated analysis software). The formatting of the NXdata groups enables the + display of image and spectra with web technology visualization software. * When two- and three-dimensional geometric primitive data are stored, it is useful to write additional optional `XDMF <https://www.xdmf.org/index.php/XDMF_Model_and_Format>`_ fields which support additional plotting of the data with visualization software. diff --git a/manual/source/classes/contributed_definitions/cgms-structure.rst b/manual/source/classes/contributed_definitions/cgms-structure.rst index f58017fc14..6190f0a30d 100644 --- a/manual/source/classes/contributed_definitions/cgms-structure.rst +++ b/manual/source/classes/contributed_definitions/cgms-structure.rst @@ -85,10 +85,10 @@ properties at a coarser-scale. The key motivation to such coarse-graining is to reduce the complexity of the description. On the one hand to support visualization and scientific analyses - not only of crystal defect arrangements. On the other hand it is the hope that using descriptors -at a coarser level, i.e. nanometer, micrometer, and larger, it is still possible -to find sufficiently accurate and precise descriptors which avoid that one has -to account for the dynamics of each atom to predict or understand the properties -of defects and their dynamics. +at a coarser level, i.e. nanometre, micrometre, and larger, it is still possible +to find sufficiently accurate and precise descriptors that avoid one having to account +for the dynamics of each atom to predict or understand the properties of defects +and their dynamics. Nevertheless, experience has shown that computational-geometry-based descriptions when combined with hierarchical clustering/labeling methods, applied on set of @@ -109,19 +109,19 @@ for frequently used shapes and geometric primitives are proposed: A description for a set of possibly dissimilar spheres. :ref:`NXcg_ellipsoid_set`: - A description for a set of possibly dissimilar rotated ellipsoids. + A description for a set of possibly dissimilar oriented ellipsoids. :ref:`NXcg_cylinder_set`: - A description for a set of possibly dissimilar rotated cylinders. + A description for a set of possibly dissimilar oriented cylinders. :ref:`NXcg_point_set`: - A collection of points with labels or mark data. + A collection of points with labels. :ref:`NXcg_polyline_set`: - A collection of lines and linearized segments. + A collection of lines and linear segments. :ref:`NXcg_triangle_set`: - A collection (or soup) of triangles. + A collection of triangles. :ref:`NXcg_parallelogram_set`: A collection of possibly dissimilar parallelograms. @@ -130,31 +130,32 @@ for frequently used shapes and geometric primitives are proposed: A mesh of triangles. :ref:`NXcg_polygon_set`: - A collection (or soup) of polygons. + A collection of polygons. :ref:`NXcg_polyhedron_set`: - A collection (or soup) of polyhedra. + A collection of polyhedra. :ref:`NXcg_roi_set`: A container to host a number of different types of primitives. :ref:`NXcg_tetrahedron_set`: - A collection (or soup) of tetrahedra. + A collection of tetrahedra. :ref:`NXcg_hexahedron_set`: - A collection (or soup) of hexahedra with capabilities to represent + A collection of hexahedra with capabilities to represent also simpler (bounding) boxes for e.g. binary trees. -These base classes make use of base classes which describe data structures: +These base classes describe data structures used for more complex geometries: :ref:`NXcg_face_list_data_structure`: In essence, the usual way how polygon/polyhedra data are reported: - Via a list of vertices and faces with identifier and properties. + A list of vertices and faces with identifier and properties. :ref:`NXcg_half_edge_data_structure`: - A half-edge data structure is a useful complementary descriptor for - polygon/polyhedra which enables topological analyses and traversal - of the graph how polygons and polyhedra can alternatively be described. + A half-edge data structure (also known as a doubly connected edge list) + is a useful complementary descriptor for polygon/polyhedra which enables + topological analyses and traversal of the graph of how polygons and + polyhedra are connected. :ref:`NXcg_unit_normal_set`: As an additional structuring element especially for meshes, well-documented @@ -169,9 +170,8 @@ These base classes make use of base classes which describe data structures: convex hull, are frequently used geometrical models for describing a boundary or edge to a set of geometric primitives. -Furthermore, a few base classes are defined for documenting the working with -discretized representations of material (area or volume) which can be useful -not only for stencil-based methods: +Next, a few base classes are defined for documenting discretized representations +of material (area or volume) which can be useful not only for stencil-based methods: :ref:`NXcg_grid`: A grid of cells. @@ -182,24 +182,23 @@ not only for stencil-based methods: :ref:`NXcg_marching_cubes`: An approach to store metadata of a specific implementation of the Marching Cubes algorithm, whose sensitivity to specific topological - configurations is known to result in different triangle soups. + configurations is known to result in different triangle collections. :ref:`NXdelocalization`: An approach to document procedures whereby a scalar field - is smoothened in a controlled manner. + is smoothed in a controlled manner. :ref:`NXsimilarity_grouping`: - An alias for NXclustering. + An alternative for NXclustering. :ref:`NXclustering`: A description for clustering of objects (such as atoms or features). :ref:`NXorientation_set`: - A set of rotations to describe the relative orientation of members of a set of features/objects. + A set of parameters to describe the relative orientation of members of a set of features/objects. :ref:`NXslip_system_set`: - Metadata to a set of slip system/slip system family for - a given crystal structure. + Metadata for a set of slip systems in a given crystal structure. :ref:`NXms_feature_set`: Generic base class to describe any nested set of features diff --git a/manual/source/classes/contributed_definitions/em-structure.rst b/manual/source/classes/contributed_definitions/em-structure.rst index ab45ab4b54..6f011c62fa 100644 --- a/manual/source/classes/contributed_definitions/em-structure.rst +++ b/manual/source/classes/contributed_definitions/em-structure.rst @@ -8,7 +8,6 @@ Electron microscopy IntroductionEm EmAppDef EmBC - EmPartnerClasses .. _IntroductionEm: @@ -113,13 +112,10 @@ The following base classes are proposed to support modularizing the storage of p :ref:`NXstage_lab`: As it was mentioned for atom probe microscopy, this is a base class to describe the stage/specimen holder which offers place for the documentation of the small-scale laboratory functionalities which modern stages of electron microscopes frequently offer. - -.. _EmPartnerClasses: - Method-specific concepts and their usage in application definitions ################################################################### -It became clear during the design of the electron microscopy specific additions to NeXus that there are sets of pieces of information (data and metadata) which are relevant for a given experiment but have usually only few connections to the detailed description of the workflow of processing these data into knowledge, motivating the granularization of these pieces of information in their own application definition. In fact, one limitation of application definitions in NeXus is that they define a set of constraints on their graph of controlled concepts and terms. If we take for example diffraction experiments with an electron microscope it is usually the case that (diffraction) patterns are collected in the session at the microscope but all scientifically relevant conclusions are drawn later, i.e. through post-processing these data. These numerical and algorithmic steps define computational workflows where data from the application definitions such as NXem are used as input but many additional concepts and constraints may apply without any need for changing constraints on fields or groups of NXem. If we were to modify NXem for these cases, NXem would likely combinatorially diverge as every different combination of required constraints would demand having their own but almost similar application definition. For this reason, the concept of method-specific concepts which have fields/links where specifically relevant sources of information are connected to them e.g. NXem. +It became clear during the design of the electron-microscopy-specific additions to NeXus that there are sets of pieces of information (data and metadata) which are relevant for a given experiment but have usually only few connections to the detailed description of the workflow of processing these data into knowledge, motivating the granularization of these pieces of information in their own application definition. In fact, one limitation of application definitions in NeXus is that they define a set of constraints on their graph of controlled concepts and terms. If we take for example diffraction experiments with an electron microscope it is usually the case that (diffraction) patterns are collected in the session at the microscope but all scientifically relevant conclusions are drawn later, i.e. through post-processing these data. These numerical and algorithmic steps define computational workflows where data from the application definitions such as NXem are used as input but many additional concepts and constraints may apply without any need for changing constraints on fields or groups of NXem. If we were to modify NXem for these cases, NXem would likely combinatorially diverge as every different combination of required constraints would demand having their own but almost similar application definition. For this reason, we propose to define the following base classes: More consolidation through the use of NXsubentry classes should be considered in the future. diff --git a/manual/source/classes/contributed_definitions/transport-structure.rst b/manual/source/classes/contributed_definitions/transport-structure.rst index 8238b52196..6aaf6844e5 100644 --- a/manual/source/classes/contributed_definitions/transport-structure.rst +++ b/manual/source/classes/contributed_definitions/transport-structure.rst @@ -20,7 +20,13 @@ Introduction Application Definitions ####################### -Work on handshaking between EPICS-controlled experiments and NeXus resulted in one application definition for temperature dependent IV curve measurements. +We realize that many experiments in condensed-matter physics and materials engineering belong to the category +of measurements of transparent phenomena. A possible example of such experiments are temperature-dependent +current-voltage (IV) curve measurements (or JV for engineers) measurements. In this case, electrical charge is transported +and the temperature-dependent current response as a function of applied voltage is recorded. + +Below is an example for such an application definition for an experiment. This application definition has exemplar parts +which show how such an experiment can be controlled with the `EPICS system `_: :ref:`NXiv_temp`: - Application definition for temperature dependent IV curve measurements. + Application definition for temperature-dependent current-voltage (IV) curve measurements.