Merge pull request #10 from diffpy/readme

working version ready for 3m

MANIFEST.in

@@ -3,6 +3,7 @@ include CONTRIBUTING.rst
 include LICENSE
 include README.rst
 include requirements.txt
+include docs/examples/*
 
 recursive-exclude * __pycache__
 recursive-exclude * *.py[co]

README.rst

@@ -15,7 +15,73 @@ An app for preprocessing data from laboratory x-ray diffractometers before using
 * Free software: 3-clause BSD license
 * Documentation: (COMING SOON!) https://sbillinge.github.io/diffpy.labpdfproc.
 
-Features
---------
+Background
+----------
 
-* TODO
+PDFgetX3 has revolutionized how PDF methods can be applied to solve nanostructure problems.  However, the program was designed for use with Rapid Acquisition PDF (RAPDF) data from synchrotron sources.  A key approximation inherent in the use of PDFgetX3 for RAPDF data is that absorption effects are negligible.  This is typically not the case for laboratory x-ray diffractometers, where absorption effects can be significant.
+
+This app is designed to preprocess data from laboratory x-ray diffractometers before using PDFgetX3 to obtain PDFs.  The app currently carries out an absorption correction assuming a parallel beam capillary geometry which is the most common geometry for lab PDF measurements.
+
+The theory is described in the following paper:
+
+An ad hoc Absorption Correction for Reliable
+Pair-Distribution Functions from Low Energy x-ray Sources
+Yucong Chen, Till Schertenleib, Andrew Yang, Pascal Schouwink,
+Wendy L. Queen and Simon J. L. Billinge, in preparation.
+
+The related experimental data acquisition protocols are described in the following paper:
+
+Protocols for Obtaining Reliable PDFs from Laboratory
+x-ray Sources Using PDFgetX3,
+Till Schertenleib, Daniel Schmuckler, Yucong Chen, Geng Bang Jin,
+Wendy L. Queen and Simon J. L. Billinge, in preparation.
+
+Installation
+------------
+
+The package is available on conda-forge and on pypi.  Assuming you are using conda/mamba (we recommend using miniconda), create a virtual environment and install the package as follows:
+
+.. code-block:: python
+
+   mamba create -n labpdfproc python=3.12
+   mamba activate labpdfproc
+   cd path/to/diffpy.labpdfproc
+   mamba install -c conda-forge diffpy.labpdfproc
+
+The code may also be installed from pipy using pip.  This is not recommended as the package has not been tested on all platforms.
+
+Usage
+-----
+
+Navigate to the directory that contains 1D diffraction patterns that you would like to process.  Activate the conda environment (`conda activate labpdfproc`) that contains the package and run the following command:
+
+.. code-block:: python
+
+   labpdfproc <muD> -i <path/to/inputfile.txt> --anode-type Mo
+
+
+Here replace <muD> with the value of muD for your sample and  <path/to/inputfile.txt> with the path and filename of your input file.  For example, if the uncorrected data case isc alled  zro2_mo.xy and is in the current directory and it has a muD of 2.5 then the commands would be
+
+.. code-block:: python
+
+   labpdfproc 2.5 -i zro2_mo.xy --anode-type Mo
+
+Please type
+.. code-block:: python
+
+   labpdfproc --help
+
+for more information on the available options.
+
+
+Getting Started
+---------------
+
+An example input file can be found in the docs/examples directory in the distribtuion (you should find it in your miniconda envs locateion).  The file is called zro2_mo.xy.
+
+1. Copy this file to a new scratch directory
+2. Navigate to that directory in a terminal
+3. Activate the conda environment that contains the package
+4. Run the command (see above)
+
+An example output is also present in the example data and you can compare your output to this file.  The example was processed with a muD of 2.5, though for experimentation you can try processing data with different muD values.

diffpy/labpdfproc/_version.py

@@ -16,7 +16,6 @@
 import sys
 
 
-
 def get_keywords():
     """Get the keywords needed to look up the version information."""
     # these strings will be replaced by git during git-archive.

diffpy/labpdfproc/functions.py

@@ -1,14 +1,15 @@
-from diffpy.utils.scattering_objects.diffraction_objects import Diffraction_object
-import numpy as np
 import math
 
+import numpy as np
+
+from diffpy.utils.scattering_objects.diffraction_objects import Diffraction_object
+
 RADIUS_MM = 1
 N_POINTS_ON_DIAMETER = 249
 TTH_GRID = np.arange(1, 141, 1)
-WAVELENGTHS = {"Mo": 0.71, "Ag": 0.59, "Cu": 1.54}
 
 
-class Gridded_circle_paths:
+class Gridded_circle:
     def __init__(self, radius=1, n_points_on_diameter=N_POINTS_ON_DIAMETER, mu=None):
         self.radius = radius
         self.npoints = n_points_on_diameter
@@ -52,7 +53,7 @@ def set_distances_at_angle(self, angle):
         """
         self.primary_distances, self.secondary_distances, self.distances = [], [], []
         for coord in self.grid:
-            distance, primary, secondary = self.get_path_length(coord, angle, self.radius)
+            distance, primary, secondary = self.get_path_length(coord, angle)
             self.distances.append(distance)
             self.primary_distances.append(primary)
             self.secondary_distances.append(secondary)
@@ -79,7 +80,6 @@ def set_muls_at_angle(self, angle):
         for distance in self.distances:
             self.muls.append(np.exp(-mu * distance))
 
-
     def _get_entry_exit_coordinates(self, coordinate, angle):
         """
         get the coordinates where the beam enters and leaves the circle for a given angle and grid point
@@ -138,10 +138,12 @@ def _get_entry_exit_coordinates(self, coordinate, angle):
 
         return entry_point, exit_point
 
-
     def get_path_length(self, grid_point, angle):
         """
-        return the path length of a horizontal line entering the circle to the grid point then exiting at angle angle
+        return the path length
+
+        This is the pathlength of a horizontal line entering the circle at the
+        same height to the grid point then exiting at angle angle
 
         Parameters
         ----------
@@ -210,7 +212,15 @@ def compute_cve(diffraction_data, mud, wavelength):
     orig_grid = diffraction_data.on_tth[0]
     newcve = np.interp(orig_grid, TTH_GRID, cve)
     abdo = Diffraction_object(wavelength=wavelength)
-    abdo.insert_scattering_quantity(orig_grid, newcve, "tth")
+    abdo.insert_scattering_quantity(
+        orig_grid,
+        newcve,
+        "tth",
+        metadata=diffraction_data.metadata,
+        name=f"absorption correction, cve, for {diffraction_data.name}",
+        wavelength=diffraction_data.wavelength,
+        scat_quantity="cve",
+    )
 
     return abdo
 
@@ -234,9 +244,3 @@ def apply_corr(diffraction_pattern, absorption_correction):
 
     corrected_pattern = diffraction_pattern * absorption_correction
     return corrected_pattern
-
-
-# to be added in diffpy.utils
-# def dump(base_name, do):
-#    data_to_save = np.column_stack((do.on_tth[0], do.on_tth[1]))
-#    np.savetxt(f'{base_name}_proc.chi', data_to_save)

diffpy/labpdfproc/labpdfprocapp.py

@@ -1,44 +1,103 @@
 import sys
 from argparse import ArgumentParser
+from pathlib import Path
 
-import numpy as np
-from diffpy.labpdfproc.functions import compute_cve, apply_corr, WAVELENGTHS
+from diffpy.labpdfproc.functions import apply_corr, compute_cve
 from diffpy.utils.parsers.loaddata import loadData
-from diffpy.utils.scattering_objects.diffraction_objects import Diffraction_object
-
+from diffpy.utils.scattering_objects.diffraction_objects import XQUANTITIES, Diffraction_object
 
+WAVELENGTHS = {"Mo": 0.71, "Ag": 0.59, "Cu": 1.54}
 known_sources = [key for key in WAVELENGTHS.keys()]
 
 
 def get_args():
     p = ArgumentParser()
-    p.add_argument("data_file", help="the filename of the datafile to load")
-    p.add_argument("mud", help="mu*D for your sample", type=float)
-    p.add_argument("--anode_type", help=f"x-ray source, allowed values:{*[known_sources],}", default="Mo")
+    p.add_argument("mud", help="Value of mu*D for your " "sample. Required.", type=float)
+    p.add_argument("-i", "--input-file", help="The filename of the " "datafile to load")
+    p.add_argument(
+        "-a", "--anode-type", help=f"X-ray source, allowed " f"values: {*[known_sources], }", default="Mo"
+    )
+    p.add_argument(
+        "-w",
+        "--wavelength",
+        help="X-ray source wavelength. Not needed if the anode-type "
+        "is specified. This will override the wavelength if anode "
+        "type is specified",
+        default=None,
+        type=float,
+    )
+    p.add_argument(
+        "-o",
+        "--output-directory",
+        help="the name of the output directory. If it doesn't exist it "
+        "will be created.  Not currently implemented",
+        default=None,
+    )
+    p.add_argument(
+        "-x",
+        "--xtype",
+        help=f"the quantity on the independnt variable axis. allowed "
+        f"values: {*XQUANTITIES, }. If not specified then two-theta "
+        f"is assumed for the independent variable. Only implemented for "
+        f"tth currently",
+        default="tth",
+    )
+    p.add_argument(
+        "-c",
+        "--output-correction",
+        action="store_true",
+        help="the absorption correction will be output to a file if this "
+        "flag is set. Default is that it is not output",
+        default="tth",
+    )
+    p.add_argument(
+        "-f",
+        "--force-overwrite",
+        action="store_true",
+        help="outputs will not overwrite existing file unless --force is spacified",
+    )
     args = p.parse_args()
     return args
 
 
 def main():
-    # we want the user to type the following:
-    # labpdfproc <input_file> <mu> <diameter> <Ag, ag, Mo, mo, Cu, cu>
+    args = get_args()
+    wavelength = WAVELENGTHS[args.anode_type]
+    filepath = Path(args.input_file)
+    outfilestem = filepath.stem + "_corrected"
+    corrfilestem = filepath.stem + "_cve"
+    outfile = Path(outfilestem + ".chi")
+    corrfile = Path(corrfilestem + ".chi")
 
-    # if they give less or more than 4 positional arguments, we return an error message.
-    if len(sys.argv) < 4:
-        print("usage: labpdfproc <input_file> <mu> <diameter> <lambda>")
+    if outfile.exists() and not args.force_overwrite:
+        sys.exit(
+            f"output file {str(outfile)} already exists. Please rerun "
+            f"specifying -f if you want to overwrite it"
+        )
+    if corrfile.exists() and args.output_correction and not args.force_overwrite:
+        sys.exit(
+            f"corrections file {str(corrfile)} was requested and already "
+            f"exists. Please rerun specifying -f if you want to overwrite it"
+        )
 
-    args = get_args()
-    wavelength = wavelengths[args.anode_type]
     input_pattern = Diffraction_object(wavelength=wavelength)
-    xarray, yarray = loadData(args.data_file, unpack=True)
-    input_pattern.insert_scattering_quantity(xarray, yarray, "tth")
+    xarray, yarray = loadData(args.input_file, unpack=True)
+    input_pattern.insert_scattering_quantity(
+        xarray,
+        yarray,
+        "tth",
+        scat_quantity="x-ray",
+        name=str(args.input_file),
+        metadata={"muD": args.mud, "anode_type": args.anode_type},
+    )
 
-    abdo = compute_cve(input_pattern, args.mud, wavelength)
-    abscormodo = apply_corr(input_pattern, abdo)
+    absorption_correction = compute_cve(input_pattern, args.mud, wavelength)
+    corrected_data = apply_corr(input_pattern, absorption_correction)
+    corrected_data.name = f"Absorption corrected input_data: {input_pattern.name}"
+    corrected_data.dump(f"{outfile}", xtype="tth")
 
-    base_name = args.data_file.split(".")[0]
-    data_to_save = np.column_stack((abscormodo.on_tth[0], abscormodo.on_tth[1]))
-    np.savetxt(f"{base_name}_proc.chi", data_to_save)
+    if args.output_correction:
+        absorption_correction.dump(f"{corrfile}", xtype="tth")
 
 
 if __name__ == "__main__":