diff --git a/README.rst b/README.rst index 46e6d6c..b50d20a 100644 --- a/README.rst +++ b/README.rst @@ -48,14 +48,14 @@ 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 +An 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 +Testing 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. diff --git a/doc/source/examples/example_data/zro2_mo.xy b/doc/source/examples/example-data/zro2_mo.xy similarity index 100% rename from doc/source/examples/example_data/zro2_mo.xy rename to doc/source/examples/example-data/zro2_mo.xy diff --git a/doc/source/examples/examples.rst b/doc/source/examples/examples.rst index 61859a7..a1faeb5 100644 --- a/doc/source/examples/examples.rst +++ b/doc/source/examples/examples.rst @@ -7,5 +7,6 @@ Examples Landing page for diffpy.labpdfproc examples. .. toctree:: + labpdfprocapp_example functions_example tools_example diff --git a/doc/source/examples/functions_example.rst b/doc/source/examples/functions_example.rst index cc833ea..2a909e1 100644 --- a/doc/source/examples/functions_example.rst +++ b/doc/source/examples/functions_example.rst @@ -9,14 +9,14 @@ This example will demonstrate how to use ``diffpy.labpdfproc.functions`` module to apply absorption correction to your 1D diffraction data. 1. First, you will need to prepare and load your input diffraction data. -For example, if you want to load data from ``zro2_mo.xy`` in the ``example_data`` directory, you can write: +For example, if you want to load data from ``zro2_mo.xy`` in the ``example-data`` directory, you can write: .. code-block:: python from diffpy.utils.parsers.loaddata import loadData from diffpy.utils.diffraction_objects import DiffractionObject - filepath = "../example_data/zro2_mo.xy" + filepath = "../example-data/zro2_mo.xy" xarray, yarray = loadData(filepath, unpack=True) input_pattern = DiffractionObject( xarray=xarray, @@ -28,7 +28,8 @@ For example, if you want to load data from ``zro2_mo.xy`` in the ``example_data` metadata={"beamline": "28ID-2"}, ) -For the full tutorial, please refer to https://www.diffpy.org/diffpy.utils/examples/diffraction_objects_example.html. +For the full tutorial on working with diffraction objects, +please refer to https://www.diffpy.org/diffpy.utils/examples/diffraction_objects_example.html. 2. Assume you have created your ``input_pattern`` and specified mu*D value as ``muD`` (e.g., ``muD=2``). You can now compute the absorption correction (cve) for the given mu*D using the ``compute_cve`` function, @@ -55,7 +56,7 @@ by plotting the original and corrected diffraction patterns. import matplotlib.pyplot as plt plt.plot(input_pattern.xarray, input_pattern.yarray, label="Original Intensity") plt.plot(corrected_pattern.xarray, corrected_pattern.yarray, label="Corrected Intensity") - plt.xlabel("tth (degrees)") + plt.xlabel("tth (degree)") plt.ylabel("Intensity") plt.legend() plt.title("Original vs. Corrected Intensity") @@ -70,5 +71,5 @@ for better accuracy, but keep in mind that this will increase computation time. For optimal results, we recommend setting it to an even number. Currently, the interpolation coefficients were computed using ``N_POINTS_ON_DIAMETER=2000``, -which ensures good accuracy within the mu*D range of 0.5 to 6. -This value also provides flexibility if we decide to extend the interpolation range in the future. +which ensures good accuracy within the muD range of 0.5 to 7. +This resolution also provides flexibility for extending the interpolation range in the future. diff --git a/doc/source/examples/labpdfprocapp_example.rst b/doc/source/examples/labpdfprocapp_example.rst new file mode 100644 index 0000000..a553c8f --- /dev/null +++ b/doc/source/examples/labpdfprocapp_example.rst @@ -0,0 +1,130 @@ +.. _labpdfprocapp Example: + +:tocdepth: -1 + +labpdfprocapp Example +##################### + +This example provides a quick-start tutorial for using ``diffpy.labpdfproc`` +to apply absorption correction to your 1D diffraction data using the command-line (CLI). +Check ``labpdfproc --help`` for more information. +A graphical user interface (GUI) is also available and is designed to be intuitive and easy to use. + + +1. To use this application, you will need: +(1) your input diffraction data file(s), and (2) information required to compute the muD value. +To launch the GUI, use ``labpdfproc`` or ``labpdfproc --gui``. +Note that the GUI is currently not supported on Python 3.13. + + +2. Here we first provide a basic CLI example. +Assume you have an uncorrected diffraction data file named ``zro2_mo.xy`` in the current directory +with a muD of 2.5 on the two-theta x-axis. Then the minimum command would be: + +.. code-block:: python + + labpdfproc zro2_mo.xy --mud 2.5 + + +3. You must provide at least one file path, and filepath(s) should immediately follow ``labpdfproc``. + +To process multiple files at once in the CLI, separate each file path with a whitespace. +In general, avoid spaces in filenames, but if necessary, enclose them in quotes; otherwise, quotes are optional. +For example, the following is a valid and more complex CLI command: + +.. code-block:: python + + labpdfproc "SiO2 uncorrected.xy" input_dir file_list.txt ./*.chi data* --mud 2.5 + +This command will process ``"SiO2 uncorrected.xy"``, +all files in the ``input_dir`` directory, all files listed in ``file_list.txt``, +all ``.chi`` files in the current directory, and all files matching the pattern ``data``, +using a muD value of 2.5. +Check ``labpdfproc --help`` to see all supported file types. + +In the GUI, you can select multiple individual files via the file browser, but not entire directories. +To include directories, you can either: +(1) create a text file named ``file_list.txt`` containing the desired paths and load it, +(2) manually select all files in a folder, or +(3) enter paths manually separated by a colon with no spaces. + +We will now continue using ``zro2_mo.xy`` as the example input throughout the rest of this tutorial. + + +4. The muD value is required for absorption correction, and you can specify it in one of the four ways: + +.. code-block:: python + + # Option 1: Manual value + labpdfproc zro2_mo.xy --mud 2.5 + # Option 2: From a z-scan file + labpdfproc zro2_mo.xy -z zscan.xy + # Option 3: Using sample mass density + labpdfproc zro2_mo.xy -d ZrO2,17.45,1.2 + # Option 4: Using packing fraction + labpdfproc zro2_mo.xy -p ZrO2,17.45,0.2 + +Note that you can only use one method at a time. The following examples are not allowed: + +.. code-block:: python + + labpdfproc zro2_mo.xy --mud 2.5 -z zscan.xy + labpdfproc zro2_mo.xy --mud 2.5 -d ZrO2,17.45,1.2 + +If the packing fraction option is not supported at the moment, you can approximate the sample mass density as: +``mass density = packing fraction * material density``, where the material density can be looked up manually. + + +5. You can specify the wavelength in two ways: + +.. code-block:: python + + # Option 1: Manually enter wavelength + labpdfproc zro2_mo.xy --mud 2.5 -w 0.71303 + # Option 2: Use a known anode type + labpdfproc zro2_mo.xy --mud 2.5 -a Mo + +Do not use both ``-w`` and ``-a`` at the same time. For example: + +.. code-block:: python + + labpdfproc zro2_mo.xy --mud 2.5 -w 0.71303 -a Mo + +is not valid. This is to avoid confusion when wavelength conflicts with anode type. +To avoid retyping, you can save your wavelength or anode type in a diffpy configuration file. +See full instructions at https://www.diffpy.org/diffpy.labpdfproc/examples/tools_example.html. + + +6. You are also encouraged to provide your information (name, email, and orcid) for reproducibility: + +.. code-block:: python + + labpdfproc zro2_mo.xy --mud 2.5 -n Joe -e Joe@email.com --orcid 0000-0000-0000-0000 + + +Alternatively, you can enter this information during the interactive prompts +or save it in your diffpy configuration file. +For more details, refer to https://www.diffpy.org/diffpy.utils/examples/tools_example.html. + + +7. You can further customize the diffraction correction process using the following options: + +- Choose xtype: use ``-x`` to specify your input data's xtype, which will be used for the output. +- Select correction method: use ``-m`` to choose between "brute_force" or "polynomial_interpolation" (faster and preferred for muD 0.5-7). +- Specify output directory: use ``-o`` to save the corrected file(s) to a specific folder. +- Add custom metadata: use ``-u`` to provide key-value pair for information tracking (e.g., experimental details). +- Output the cve file: use ``-c`` to export the cve file along with the corrected data. +- Overwrite existing files: use ``-f`` to replace any previous corrected files with the same names. + + +8. To summarize, a full command might look like this: + +.. code-block:: python + + labpdfproc zro2_mo.xy --mud 2.5 -w 0.71303 -n Joe -x q -m brute_force -o results -u "facility=NSLS II" beamline=28ID-2 -c -f + +After running the command, check your output folder (in this case, ``results``) +for the corrected data file and cve file (if ``-c`` was used). +In this example, the corrected and cve files are called ``zro2_mo_corrected.chi`` and ``zro2_mo_cve.chi``. +The headers include all the arguments you provided +—such as diffraction settings, personal information, and metadata—making it easy to track your analysis. diff --git a/doc/source/examples/tools_example.rst b/doc/source/examples/tools_example.rst index c66df93..674d244 100644 --- a/doc/source/examples/tools_example.rst +++ b/doc/source/examples/tools_example.rst @@ -19,28 +19,14 @@ You can do this in one of the following four ways: args = Namespace(mud=2) # Option 2: From a z-scan file args = Namespace(z_scan_file="zscan.xy") - # Option 3: Using mass density - args = Namespace(sample_composition="ZrO2", energy=1.745, density=1.2) + # Option 3: Using sample mass density + args = Namespace(theoretical_from_density="ZrO2,17.45,1.2") # Option 4: Using packing fraction - args = Namespace(sample_composition="ZrO2", energy=1.745, packing_fraction=0.3) + args = Namespace(theoretical_from_packing="ZrO2,17.45,0.3") # Set and view the computed mu*D value args = set_mud(args) print(args.mud) -Note that only one method should be used at a time. The following are invalid examples: - -.. code-block:: python - - # Invalid example 1: manual mu*D and z-scan file both provided - args = Namespace(mud=2, z_scan_file="zscan.xy") - # Invalid example 2: missing required energy - args = Namespace(sample_composition="ZrO2", density=1.2) - # Invalid example 3: both mass density and packing fraction specified - args = Namespace(sample_composition="ZrO2", energy=1.745, density=1.2, packing_fraction=0.3) - -If the packing fraction option is not supported at the moment, you can approximate -``mass density = packing fraction * material density``, where the material density can be looked up manually. - 2. Next, we load the input files for correction using ``set_input_lists(args)``: diff --git a/doc/source/utilities/functions_utility.rst b/doc/source/utilities/functions_utility.rst index 6b15422..bf40b65 100644 --- a/doc/source/utilities/functions_utility.rst +++ b/doc/source/utilities/functions_utility.rst @@ -7,17 +7,18 @@ The ``diffpy.labpdfproc.functions`` module provides tools for computing and applying absorption correction (cve) to 1D diffraction patterns. - ``Gridded_circle``: This class supports absorption correction by - creating a uniform grid of points within a circle for a given radius and mu (linear absorption coefficient), + creating a uniform grid of points within a circle for a given radius and linear absorption coefficient mu, and computing the path length and effective volume for each grid point at a given angle. -- ``compute_cve``: This function computes the absorption correction curve for a given mu*D - (absorption coefficient mu and capillary diameter D). - For brute force computation, it averages the effective volume across all grid points, - then computes the cve values as the reciprocal of this average. - For polynomial interpolation, it uses pre-computed coefficients to quickly interpolate cve values for a given mu*D. - Polynomial interpolation is available for mu*D values between 0.5-6. +- ``compute_cve``: This function computes the absorption correction curve for a given muD value + (the product of mu and capillary diameter D). + For brute-force computation, it averages the effective volume across all grid points + and computes the cve values as the reciprocal of this average. + Alternatively, for fast calculation, + it uses polynomial interpolation with pre-computed coefficients to estimate cve values for a given muD. + Polynomial interpolation is available for muD values between 0.5-7. - ``apply_corr``: This function applies the computed absorption correction to the input diffraction pattern - by multiplying it with the computed cve, resulting in a corrected diffraction pattern. + by multiplying it with the corresponding cve, resulting in a corrected diffraction pattern. For a more in-depth tutorial for how to use these tools, click :ref:`here `. diff --git a/doc/source/utilities/labpdfprocapp_utility.rst b/doc/source/utilities/labpdfprocapp_utility.rst new file mode 100644 index 0000000..13ed3ed --- /dev/null +++ b/doc/source/utilities/labpdfprocapp_utility.rst @@ -0,0 +1,15 @@ +.. _labpdfprocapp Utility: + +labpdfprocapp Utility +===================== + +The ``diffpy.labpdfproc.labpdfprocapp`` module provides both a command-line (CLI) and graphical user interface (GUI) +for processing diffraction data, applying absorption correction, and saving the output files. + +- ``get_args()``: This function parses all CLI arguments. + +- ``gooey_parser()``: This function provides a GUI for argument input. + +- ``main()``: This function validates all arguments, performs preprocessing, and saves the output files. + +For a more in-depth tutorial for how to get started, click :ref:`here `. diff --git a/doc/source/utilities/tools_utility.rst b/doc/source/utilities/tools_utility.rst index 8fafcd3..74dd58d 100644 --- a/doc/source/utilities/tools_utility.rst +++ b/doc/source/utilities/tools_utility.rst @@ -7,8 +7,8 @@ The ``diffpy.labpdfproc.tools`` module provides functions to manage user inputs, output directories, and diffraction information. These functions work mostly with an ``argparse.Namespace`` object and help prepare data for diffraction processing. -- ``set_mud()``: This function determines the mu*D value used to compute absorption correction. - Users can either provide mu*D directly, upload a z-scan file, +- ``set_mud()``: This function determines the muD value used to compute absorption correction. + Users can either provide the value directly, upload a z-scan file, or specify relevant chemical information to get a theoretical estimation. - ``set_input_lists()``: This function parses all specified input files. @@ -42,7 +42,7 @@ These functions work mostly with an ``argparse.Namespace`` object and help prepa - ``load_package_info()``: This functions stores the package name and version for record-keeping. - ``preprocessing_args()``: This is a convenience function that runs all standard setup steps listed above. - It ensures the input/output paths, wavelength, mu*D value, metadata, and user and package info are + It ensures the input/output paths, wavelength, muD value, metadata, and user and package info are fully initialized before applying the correction. - ``load_metadata()``: This function transfers all collected information from the ``argparse.Namespace`` object diff --git a/doc/source/utilities/utilities.rst b/doc/source/utilities/utilities.rst index 05fa8ca..fc75d11 100644 --- a/doc/source/utilities/utilities.rst +++ b/doc/source/utilities/utilities.rst @@ -10,5 +10,6 @@ Check the :ref:`examples` provided for how to use these. .. contents:: :depth: 2 +.. include:: labpdfprocapp_utility.rst .. include:: functions_utility.rst .. include:: tools_utility.rst diff --git a/news/main-doc.rst b/news/main-doc.rst new file mode 100644 index 0000000..b4674dd --- /dev/null +++ b/news/main-doc.rst @@ -0,0 +1,23 @@ +**Added:** + +* Utility and example documentation for the main module. + +**Changed:** + +* + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* + +**Security:** + +* diff --git a/src/diffpy/labpdfproc/tools.py b/src/diffpy/labpdfproc/tools.py index 0f1e7fa..f53373d 100644 --- a/src/diffpy/labpdfproc/tools.py +++ b/src/diffpy/labpdfproc/tools.py @@ -272,7 +272,7 @@ def set_wavelength(args): def set_xtype(args): - f"""Set the xtype based on the given input arguments, + """Set the xtype based on the given input arguments, raise an error if xtype is not one of {*XQUANTITIES, }. Parameters