diff --git a/contributed_definitions/NXxpcs.nxdl.xml b/contributed_definitions/NXxpcs.nxdl.xml index 9839fbb2a..a258147e0 100644 --- a/contributed_definitions/NXxpcs.nxdl.xml +++ b/contributed_definitions/NXxpcs.nxdl.xml @@ -59,7 +59,7 @@ **Locally** unique identifier for the experiment (a.k.a. run or scan). - * For bluesky users, this is the run's `"scan_id"`. + * For bluesky users, this is the run's ``"scan_id"``. If ``scan_id`` is not available, use the run's ``uid``. * For SPEC users, this is the scan number (``SCAN_N``). @@ -134,10 +134,10 @@ the data and its axes are self-describing as per NeXus recommendations. However, the data is preferred in one of the following two formats: - * iterable list of linked files (or keys) for each :math:`g_2` with 1 file (key) per :math:`q`, where `q` is called by the nth roi_map value - * 2D array [#]_ with shape (:math:`g_2`, :math:`q`), where `q` is represented by the nth roi_map value, not the value `q` value + * iterable list of linked files (or keys) for each :math:`g_2` with one file (key) per :math:`q`, where `q` is called by the nth roi_map value + * 2D array [#]_ with shape (:math:`g_2`, :math:`q`), where :math:`q` is represented by the nth roi_map value, not the value :math:`q` value - Note it is expected that "g2" and all quantities following it will be of the same length. + .. note:: It is expected that ``g2`` and all quantities following it will be of the same length. Other formats are acceptable with sufficient axes description. @@ -152,8 +152,8 @@ We encourage the documentation of other formats not represented here. - * one array representing entire data set ("one_array") - * data exchange format with each key representing one ``q`` by its corresponding roi_map value ("data_exchange_keys") + * one array representing entire data set (``"one_array"``) + * data exchange format with each key representing one :math:`q` by its corresponding roi_map value (``"data_exchange_keys"``). @@ -194,14 +194,14 @@ - delay_difference (also known as delay or lag step) + (Also known as delay or lag step.) This is quantized difference so that the "step" between two consecutive frames is one frame (or step ``= dt = 1 frame``) It is the "quantized" delay time corresponding to the ``g2`` values. - The unit of delay_differences is ``NX_INT`` for units of frames (i.e., integers) preferred, + The unit of delay_differences is ``NX_INT`` (i.e., integers) for units of frames preferred, refer to :ref:`NXdetector` for conversion to time units. @@ -220,7 +220,7 @@ - two-time correlation of speckle intensity for a given q-bin or roi (represented by the nth roi_map value) + two-time correlation of speckle intensity for a given :math:`q`-bin or roi (represented by the nth roi_map value) See Fluerasu, Phys Rev E (2007), Eq 1 and Sutton, Optics Express (2003) for an early description applied to X-ray scattering: @@ -231,8 +231,8 @@ the data and its axes are self-describing as per NeXus recommendations. However, the data is preferred in one of the following two formats: - * iterable list of linked files (or keys) for each q-bin called by the nth roi_map value. data for each bin is a 2D array - * 3D array with shape (frames, frames, q) or (q, frames, frames), where :math:`q` is represented by the nth roi_map value, not the value `q` value + * Iterable list of linked files (or keys) for each :math:`q`-bin called by the nth roi_map value. data for each bin is a 2D array. + * 3D array with shape (frames, frames, :math:`q`) or (q:math:`q`, frames, frames), where :math:`q` is represented by the nth roi_map value, not the :math:`q` value. The computation of this result can be customized. These customizations can affect subsequently derived results (below). The @@ -241,7 +241,7 @@ * Other normalization methods may be applied, but the method will not be specified in this definition. Some of these normalization methods result in a baseline value of ``0``, not ``1``. - * The various software libraries use different programming languages. Therefore, we need to + * To avoid committing to one specific programming language, we need to specify the ``time = 0`` origin location of the 2D array for each :math:`q`. * A method to reduce data storage needs is to only record half of the 2D array by populating @@ -251,7 +251,7 @@ - storage_mode describes the format of the data to be loaded + The format of the data to be loaded. We encourage the documention of other formats represented here. @@ -264,9 +264,9 @@ - baseline is the expected value of a full decorrelation + The expected value of a full decorrelation. - The baseline is a constant value added to the functional form of the auto-correlation + The ``baseline_reference`` is a constant value added to the functional form of the auto-correlation function. This value is required. @@ -276,7 +276,7 @@ - time_origin_location is the location of the origin + Location of the time origin. @@ -285,7 +285,7 @@ - populated_elements describe the elements of the 2D array that are populated with data + Describes how elements of the 2D array are populated with data. @@ -298,10 +298,10 @@ frame weighted average along the diagonal direction in ``two_time_corr_func`` - The data format and description should be consistent with that found in "/NXxpcs/entry/data/g2" + The data format and description should be consistent with that found in ``g2``. - * iterable list of linked files for each :math:`g_2` with 1 file per :math:`q` - * 2D array with shape (:math:`g_2`, :math:`q`) + * Iterable list of linked files for each :math:`g_2` with one file per :math:`q`. + * 2D array with shape (:math:`g_2`, :math:`q`). Note that delay_difference is not included here because it is derived from the shape of extracted :math:`g_2` because all frames are considered, which is not necessarily the case for :math:`g_2`. @@ -493,7 +493,7 @@ "roi_maps" provide for representation of pixel binning that are arbitrary and irregular, which is geometry scattering agnostic and most flexible. The maps work as a labeled array for N rois. - "Dynamic" represents quantities directly related to XPCS and NXxcps/entry/data and + "Dynamic" represents quantities directly related to XPCS and NXxpcs/entry/data and NXxpcs/entry/two_time. "Static" refers to finer binning used for computation not strictly used for the final @@ -507,7 +507,7 @@ roi index array or labeled array The values of this mask index (or map to) the :math:`Q` value from the - the ``dynamic_q_list`` field. Not that the value of ``0`` represents in-action. XPCS computations + ``dynamic_q_list`` field. Note that the value of ``0`` represents in-action. XPCS computations are performed on all pixels with a value > 0. The ``units`` attribute should be set to ``"au"`` @@ -523,8 +523,8 @@ The only requirement for the list is that it may be iterable. Some expected formats are: * iterable list of floats (i.e., :math:`Q(r)`) - * iterable list of tuples (i.e., :math:`Q(r)`, :math:`\varphi`), but preferable use the seperate :math:`\varphi` field below - * iterable list of tuples (e.g., (H, K, L); (qx, qy, qz); (horizontal_pixel, vertical_pixel)) + * iterable list of tuples (i.e., :math:`Q(r)`, :math:`\varphi`), but preferable use the separate :math:`\varphi` field below + * iterable list of tuples (e.g., :math:`(H, K, L)`; :math:`(q_x, q_y, q_z)`; (horizontal_pixel, vertical_pixel)) * iterable list of integers (for Nth roi_map value) or strings This format is chosen because results plotting packages are not common and simple I/O is required by end user. @@ -543,7 +543,7 @@ roi index array. The values of this mask index the :math:`|Q|` value from the - the ``static_q_list`` field. + ``static_q_list`` field. The ``units`` attribute should be set to ``"au"`` indicating arbitrary units. @@ -551,7 +551,14 @@ - 1-D list of :math:`|Q|` values, 1 for each roi. + 1-D list of :math:`|Q|` values, one for each roi. + + + + + Array of :math:`\varphi` value for each pixel. + + List order is determined by the index value of the associated roi map starting at ``1``.