X-ray Photon Correlation Spectroscopy (XPCS) data (results). ...
X-ray Photon Correlation Spectroscopy (XPCS) data (results).
The purpose of NXxpcs is to document and communicate an accepted vernacular for various XPCS results data
in order to support development of community software tools. The definition presented here only
represents a starting point and contains fields that a common software tool should support for
community acceptance.
Additional fields may be added to XPCS results file (either formally or informally). It is expected
that this XPCS data will be part of multi-modal data set that could involve e.g., NXcanSAS or
1D and/or 2D data.
Symbols:
The symbol(s) listed here will be used below to coordinate datasets with the same shape.
The results data captured here are most commonly required for high throughpu ...
The results data captured here are most commonly required for high throughput, equilibrium dynamics experiments. Data (results)
describing on-equilibrium dynamics consume more memory resources so these data are separated.
Typically, \(g_2\) is a quantity calculated for a group of pixels representing a specific
region of reciprocal space. These groupings, or bins, are generically described as \(q\). Some
open-source XPCS libraries refer to these bins as “rois”, which are not to be confused with
EPICS AreaDetector ROI. See usage guidelines for q_lists and roi_maps within a mask. [1]
In short, \(g_2\) should be ordered according to the roi_map value. In principle, any format is acceptable if
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 \(g_2\) with 1 file (key) per \(q\), where q is called by the nth roi_map value
2D array [2] with shape (\(g_2\), \(q\)), where q is represented by the nth roi_map value, not the value q value
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.
See references below for related implementation information:
The derivation of the error is left up to the implemented code. Symmetric error will be
expected (\(\pm\) error). The data should be in the same format as g2.
two-time correlation of speckle intensity for a given q-bin or roi (repres ...
two-time correlation of speckle intensity for a given 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:
\[C(\boldsymbol Q, t_1, t_2) = \frac{ \langle I(\boldsymbol Q, t_1)I(\boldsymbol Q, t_2)\rangle }{ \langle I(\boldsymbol Q,t_1)\rangle \langle I(\boldsymbol Q,t_2)\rangle }\]
in which time is quantized by frames. In principle, any data format is acceptable if
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 \(q\) is represented by the nth roi_map value, not the value q value
The computation of this result can be customized. These customizations can affect subsequently derived results (below). The
following attributes will be used to manage the customization.
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
specify the time=0 origin location of the 2D array for each \(q\).
A method to reduce data storage needs is to only record half of the 2D array by populating
array elements above or below the array diagonal.
frame weighted average along the diagonal direction in ``two_time_corr_fun ...
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”
iterable list of linked files for each \(g_2\) with 1 file per \(q\)
2D array with shape (\(g_2\), \(q\))
Note that delay_difference is not included here because it is derived from the shape of
extracted \(g_2\) because all frames are considered, which is not necessarily the case for \(g_2\).
The computation of this result can be customized. The customization can affect the fitting required to extract quantitative results. The
following attributes will be used to manage the customization.
first_point_for_fit describes if the first point should or should not be ...
first_point_for_fit describes if the first point should or should not be used in fitting the functional form of the dynamics to extract quantitative time-scale information.
The first_point_for_fit is True (“1”) or False (“0”). This value is required.
subset of frame weighted average along the diagonal direction in ``two_tim ...
subset of frame weighted average along the diagonal direction in two_time_corr_func
Time slicing along the diagonal can be very sophisticated. This entry currently assumes
equal frame-binning. The data formats are highly dependent on the implantation of various analysis libraries.
In principle, any data format is acceptable if 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 partial \(g_2\) of each q-bin represented by the roi_map value
3D array with shape (\(g_2\), \(q\), nth_partial)
Note that delay_difference is not included here because it is derived from the shape of
extracted \(g_2\).
Spread of incident beam line energy (either keV or eV). This quantity is ...
Spread of incident beam line energy (either keV or eV). This quantity is otherwise known
as the energy resolution, which is related to the longitudinal coherence length.
XPCS data is typically produced by area detector (likely EPICS AreaDetecto ...
XPCS data is typically produced by area detector (likely EPICS AreaDetector) as a stack of 2D images. Sometimes
this data is represented in different ways (sparse arrays or photon event list), but this detail
is left to the analysis software. Therefore, we only include requirements based on full array data.
We note that the image origin (pixel coordinates (0,0)) are found at the top left of a single 2D image array. This
is the standard expected by Coherent X-ray Imaging Data Bank. [3]
See CXI version 1.6 and Maia, Nature Methods (2012). This seems to be consistent with matplotlib and
the practiced implementation of EPICS AreaDetector. However, some exceptions may exists in the CXI
documentation (See Fig 11 vs Fig 12).
Additionally, not all NXdetector dependencies are inherited from AreaDetector or other control systems. frame_time is used to
convert delay_difference to seconds. frame_time field could be missing from AreaDetector or may
either be acquire_period or acquire_time, depending on the detector model and the local implementation.
Data masks or mappings to regions of interest (roi) for specific :math:`Q` ...
Data masks or mappings to regions of interest (roi) for specific \(Q\) values
Fields in this masks group describe regions of interest
in the data by either a mask to select pixels or to associate
a map of rois with a (one-dimensional) list of values.
“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
NXxpcs/entry/two_time.
“Static” refers to finer binning used for computation not strictly used for the final
XPCS results. Implementation of _static_ binning is left for individual libraries to
document. We encourage usage of NXcanSAS to represent standard SAXS results or
development of new NeXus definitions for GI-SAXS or other reciprocal space
intensity mapping.
The values of this mask index (or map to) the \(Q\) value from the
the dynamic_q_list field. Not 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"
indicating arbitrary units.
1-D list of :math:`Q` values, one for each roi index value. ...
1-D list of \(Q\) values, one for each roi index value.
List order is determined by the index value of the associated roi map starting at 1.
The only requirement for the list is that it may be iterable. Some expected formats are:
iterable list of floats (i.e., \(Q(r)\))
iterable list of tuples (i.e., \(Q(r)\), \(\varphi\)), but preferable use the seperate \(\varphi\) field below
iterable list of tuples (e.g., (H, K, L); (qx, qy, qz); (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.
The lists can be accessed as lists, arrays or via keys
NAME: The NeXus convention, to use all upper case
to indicate the name (here NOTE), is left to the file
writer. In our case, follow the suggested name
pattern and sequence: note_1, note_2, note_3, …
Start with note_1 if the first one, otherwise
pick the next number in this sequence.