update README

conversion_examples/README

@@ -1,5 +1,11 @@
-These examples are essentially built by hand as proof-of-principle
-and as points of discussion to drive the pynxxas and NXxas definition.
+These examples ilustrate early attempts to convert "raw" or "as collected" beamline data
+into HDF5/NeXuS NXxas groups, and also into "new style" XDI files that map directly to
+the NXxas groups.
+
+There files here are essentially built "by hand", using a "make_xas.py" script
+in each folder.  This is meant to be a proof-of-principle, and to allow for
+discussion about these formats.  These examples are also meant to drive the
+development of pynxxas and NXxas definition.
 
 
 For all datasets:
@@ -8,32 +14,38 @@ For all datasets:
     done with xraylarch, but in a way (linear pre-edge, constant edge step),
     that it should be easy to reproduce.
 
-2. "New" XDI files are written to very, very closely match the NXxas Groups.
-
-3. The group "rawdata" holds the "original" column data.  It also
-   includes (in column 2, the "intensity"/"normalized mu(E)" so that
-   the data shape is identical to the new XDI file
+2. "energy" is strictly in eV.
 
+3. "New" XDI files are written to very, very closely match the NXxas Groups,
+   though they do not have the full range of "hierarchy" or automated setting
+   of attributes. An important goal is that data can be converted between these
+   two forms without any loss of data or important metadata.
 
-The scripts are pretty "hacky" and not meant for real use in pynnxas, but more
-of a guide.  My intention is to *not* rely on larch, but to port code to
-robustly read text files, and do basic processing (including pre-edge
-subtraction and normalization) into pynxxas.
-
+4. The group "rawdata" holds a 2-d array (Ncolumns, Nenergy) with all data that
+   maps to the columns of data from the original data file. Usually, these will
+   be identical to the original data.  But note that some files (Fe_XDIFiles)
+   had "mufluor" as a column, and the new files have converted these to
+   "ifluor": The rawdata also includes (in column 2) the "intensity" or
+   "normalized mu(E)".  That is, the data shape is identical to the output
+   XDI file.
 
+The "make_xas.py" scripts are not very sophisticated and are not meant for real
+use in pynnxas, but more of a guide of what operations and steps to do.  Also,
+the intention is to *not* rely on xraylarch, but to port code to robustly read
+text files, and do basic processing (including pre-edge subtraction and
+normalization) into pynxxas.
 
 Folders and Files (so far):
 =============================
 
-Fe_XDIFiles:  3 XDI files (all Fe K edge, transmsission XAFS)
+Fe_XDIFiles:  3 XDI files (all Fe K edge, transmission XAFS)
       are put into a single nexus file.
 
-MultiElementFluor:  12 data files (XDI-ish) for V K-edge fluoresence XAFS
+KEK_PF: 1 data file from Photon Factory, KEK.  Fluorescence XAFS,
+      that was recorded as a function of angle
+
+MultiElementFluor:  12 data files (XDI-ish) for V K-edge fluorescence XAFS
       using a 4-element detector.  The original files have columns saved
-      for "V Ka" and a "Deadtime Correction Factor" for MCAs 1 through 4.
+      for "V Ka" and a "Dead-time Correction Factor" for MCAs 1 through 4.
       The script sums the deadtime-corrected chanbels to make "ifluor".
       V_XANES_nexus.h5
-
-
-KEK_PF: 1 data file from Photon Factory, KEK.  Fluorescence XAFS,
-      recorded as a function of angle