Merge pull request #177 from yucongalicechen/docs-main

docs: for main module and also serves as a quick-start tutorial

Author: sbillinge

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.

doc/source/examples/example_data/zro2_mo.xy renamed to doc/source/examples/example-data/zro2_mo.xy

@@ -7,5 +7,6 @@ Examples
 Landing page for diffpy.labpdfproc examples.
 
 .. toctree::
+    labpdfprocapp_example
     functions_example
     tools_example

doc/source/examples/examples.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.

doc/source/examples/functions_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.

doc/source/examples/labpdfprocapp_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)``:
 

doc/source/examples/tools_example.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 <Functions Example>`.

doc/source/utilities/functions_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 <labpdfprocapp Example>`.

doc/source/utilities/labpdfprocapp_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

doc/source/utilities/tools_utility.rst

@@ -10,5 +10,6 @@ Check the :ref:`examples<Examples>` provided for how to use these.
 .. contents::
    :depth: 2
 
+.. include:: labpdfprocapp_utility.rst
 .. include:: functions_utility.rst
 .. include:: tools_utility.rst

doc/source/utilities/utilities.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* Utility and example documentation for the main module.
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

news/main-doc.rst

@@ -278,7 +278,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