Implementing reviewer suggestions of @prjemian, @phyy-nx, and @PeterC…

…-DLS

contributed_definitions/NXem.nxdl.xml

@@ -60,12 +60,12 @@ that it is required-->
 
  Multiple specimens have to be described with multiple :ref:`NXentry` instances.
 
- **Electron microscopes motivate the development of an embracing data schema:**
+ **Electron microscopes motivate the development of a comprehensive data schema:**
  There are research groups who use an EM in a manner where it is exclusively
  operated by a single, instrument-responsible scientists or a team of scientists.
  These users may perform analyses for other users as a service task, especially
  in large research facility settings. Oftentimes, though, and especially for
- cutting-edge instruments, the scientists guide the process maybe even control
+ cutting-edge instruments, the scientists guide the process and maybe even control
  the microscope. Instruments are usually controlled on-premises but also more
  and more functionalities for remote control have become available.
  Scientists oftentimes can ask technicians for support. In all cases,
@@ -91,7 +91,7 @@ that it is required-->
  radiation/specimen interactions. Often these detectors have a similar design
  and technology or are even used both in SEMs and TEMs.
 
- **An embracing schema instead of specific SEM or TEM schemas**:
+ **A comprehensive schema instead of specific SEM or TEM schemas**:
  Given these physical and technical differences, different instruments have
  been developed. This led to a coexistence of two broad interacting
  communities: SEM and TEM users. From a data science perspective, we
@@ -110,16 +110,8 @@ that it is required-->
  schemas such as NXem_ebsd, NXem_eels, NXem_edx, or NXem_imaging.
 
  However, the history of electron microscopy has shown that these activities led
- to a zoo of schemas and especially vocabulary in use with implementations of these
- into many data and file formats. There is nothing which prevents the communities
- to make these schemas open and interoperable. Open here means not that all
- data stored according to such schemas have to end up in the open-source domain.
- There can be embargo periods first of all.
-
- Open means that the metadata and associated schemata are documented in a manner
- that as many details are open as possible in the sense that others can understand
- what the (meta)data mean conceptually. Instead of trying of maintain a zoo
- of eventually difficult to make interoperable formats and schema we would like
+ to a zoo of schemas and vocabulary, with implementation in many data and file formats,
+ difficult to make interoperable. Instead of trying to maintain this, we would like
  to advocate that the `FAIR principles <https://doi.org/10.1038/sdata.2016.18>`_
  should guide all decisions how data and metadata should be stored.
 
@@ -181,10 +173,7 @@ that it is required-->
  analysis needs. Consumers can be again specific software tools, like vendor
  software for controlling the instrument or a scientific software for doing
  artificial intelligence analyses on EM data). Such changes of a schema lead
- to new versions. Strictly speaking an application definition can only be
- fully general if it does not make a single entry required, in which case however
- it would also not offer much value as even empty datasets would be compliant
- with such a schema.
+ to new versions.
 
  **Verification of constraints and conditions**:
  Tools like NeXus so far do not avoid or protect against all such possible
@@ -343,29 +332,26 @@ that it is required-->
  These descriptions can be implemented and stored in JSON, HDF5, XML, or HSDS, 
  file storage, or even other formats, although HDF5 is often used. 
  * When two- and three-dimensional geometric primitive data are stored, it is useful 
- to write additional optional XDMF fields which support additional plotting of 
- the data with visualization software like Paraview or Blender. 
+ 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. 
  * Consumable results of EM characterization tasks are usually a sub-set of 
  data artifacts, as there is not an infinite amount of possible 
  electron/ion beam-specimen interactions. 
- * Images of electron counts detected in specific operation modes (bright 
- field, dark field in TEM, secondary/back-scattered, Kikuchi). 
- * Spectra (X-ray quanta or Auger electron counts) 
+ * Images based on electron counts are typically detected with specific operation modes
+ such as bright field or dark field imaging in TEM or secondary/back-scattered electron
+ imaging in SEM. 
+ * Also spectra (X-ray quanta or Auger electron counts) typically are referred to
+ under the assumption of a specific operation mode of the microscope.
  * These data are in virtually all cases a result of some numerical processing. 
  These data and processing steps are modelled as instances of :ref:`NXprocess` 
  which use terms from a controlled vocabulary e.g. SE (secondary electron), 
  BSE (back-scattered electron), Kikuchi, X-ray, Auger, Cathodolum(inescence). 
 
  **A key question often asked with EM experiments is how the actual (meta)data
- should be stored (in memory or on disk)**. To this end the schema here makes no
- specific assumptions, not even that all the fields/group of a schema instance
- have to be stored at all into a single file. Instead, the schema specifies the
- relations between metadata, some of the constraints and conditions on how the
- data should be formatted, what the data conceptually represent, and which terms
- (controlled vocabulary) is practical to store to index specific quantities.
+ should be stored (in memory or on disk)**.
 
- In effect, the application definition is a graph which describes how
- numerical data and (meta)data for EM research are related to one another.
+ The application definition NXem is a graph which describes how numerical data
+ and (meta)data for EM research are related to one another.
 
  Electron microscopy experiments are usually controlled/performed via
  commercial integrated acquisition and instrument control software.

manual/source/classes/contributed_definitions/cgms-structure.rst

@@ -26,10 +26,10 @@ computational-geometry-based descriptions of the structure of materials and
 atomic configurations used when characterizing materials in experiments
 and computer simulations.
 
-As far as NeXus is concerned, the here proposed distinct sets of simple
-geometric primitives and shapes offer a complementary alternative to the
-already existent base classes in NeXus for constructive solid geometry
-such as :ref:`NXcsg`, :ref:`NXoff_geometry`, or :ref:`NXquadric` to name but a few.
+As far as NeXus is concerned, this proposed set of simple geometric primitives
+and shapes offer a complementary alternative to the current set of base classes in
+NeXus for constructive solid geometry such as :ref:`NXcsg`, :ref:`NXoff_geometry`, 
+or :ref:`NXquadric` to name but a few.
 
 Second, we would like to explore with this proposal how we can harmonize terms
 frequently used by materials scientists in the field of condensed-matter physics
@@ -52,7 +52,7 @@ Physics background
 Microstructural features or crystal defects are spatial arrangements of atoms.
 Given their specific atomic arrangement and composition, such features have
 specific constraints on the degrees of freedom how atoms can arrange. This causes
-that these defects have specific properties.
+these defects to have specific properties.
 Provided well-defined coarse-graining procedures are used and regions-of-interest
 and/or regions-of-applicability are defined, microstructural features are often
 characterized and modelled to have associated thermodynamic descriptors.
@@ -75,12 +75,12 @@ common terminology and using controlled vocabularies more frequently.
 These are the foundation for more sophisticated thoughts about practically
 useful ontologies.
 
-Defining crystal defects is a question of how to coarse-grain a given spatio-
-temporal set of atoms, each having a nuclid type and position/trajectory.
-In most cases, such a coarse-graining is an ill-posed task because different
-mathematical/geometrical methods exists how a point, a line, a surface, or a volumetric defect
-can be described and be spatio-temporally constrained through a geometrical model
-with defined geometric primitives and associated coarser-scale properties.
+Defining crystal defects is a question of how to coarse-grain a given spatiotemporal
+set of atoms, each having a nuclide type and position/trajectory. Different mathematical/geometrical
+methods exists to coarse-grain and thus determine how a point, a line, a surface, or
+a volumetric defect can be described and be spatiotemporally constrained through
+a geometrical model with defined geometric primitives and associated (materials)
+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
@@ -216,9 +216,8 @@ not only for stencil-based methods:
  :ref:`NXchemical_composition`:
  (Chemical) composition of a sample or a set of things.
 
-Furthermore, it can be useful to have a set of base classes with
-which software documents it state and gives a summary for users about the performance
-and elapsed time measured while processing data. These utility classes include:
+Finally, the following base classes allow data processing software to document its input
+parameters and to summarize its performance statistics:
 
  :ref:`NXprogram`:
  A named and version of a program of library/component.
@@ -261,26 +260,26 @@ Application definitions for ICME models
 
 It is important to embrace the large research community of materials engineers
 as they are frequent users of electron microscopy and atom probe microscopy.
-In this community frequently ICME microstructure models are used. ICME is an
-abbreviation for Integrated Computational Materials Engineering, which is a
-design strategy and workflow whereby physics-based modelling of microstructure
-evolution at the mesoscopic scale is used to understand the relations between
+In this community frequently ICME (Integrated Computational Materials Engineering)
+microstructure models are used. These models are derived from a design strategy
+and workflow whereby physics-based modelling of microstructure evolution, typically
+at the mesoscopic scale, is used to understand the relations between
 the microstructure and technological relevant descriptors for the properties
 of materials.
 
-The following application definitions are proposed to support the discussion
-how materials engineering-specific data models and connect to or be mapped on
+The following application definitions are proposed to support discussion on
+how materials engineering-specific data models connect to or can be mapped on
 concepts which are equally modellable with NeXus:
 
  :ref:`NXms`:
  An application definition for arbitrary spatiotemporally resolved simulations.
 
  :ref:`NXms_score_config`:
- A specific example how :ref:`NXapm_paraprobe_config_ranger` can be
+ A specific example of how :ref:`NXapm_paraprobe_config_ranger` can be
  specialized for documenting the configuration of a computer simulation
  with the static recrystallization cellular automata model SCORE.
 
  :ref:`NXms_score_results`:
- A specific example how :ref:`NXms` can be specialized for documenting
+ A specific example of how :ref:`NXms` can be specialized for documenting
  results of computer simulations with the static recrystallization
  cellular automata model SCORE.

manual/source/classes/contributed_definitions/ellipsometry-structure.rst

@@ -25,7 +25,7 @@ Application Definitions
 -----------------------
 
  :ref:`NXopt`:
- A generic application definition for optial spectorscopy measurements, including complex systems up to variable angle spectroscopic ellipsometry. 
+ A generic application definition for optical spectroscopy measurements, including complex systems up to variable angle spectroscopic ellipsometry. 
 
  :ref:`NXellipsometry`:
  An application definition for ellipsometry measurements, including complex systems up to variable angle spectroscopic ellipsometry. 
@@ -34,7 +34,7 @@ Application Definitions
 Base Classes
 ------------
 
-There is a set of base classes for describing an optical experiment.
+This is the set of base classes for describing an optical experiment.
 
  :ref:`NXbeam_path`
  A beam path consisting of one or more optical elements.