doc: Add documentation reflecting new CLI

docs/source/api/diffpy.labpdfproc.rst

@@ -1,9 +1,7 @@
 :tocdepth: -1
 
-|title|
-=======
-
-.. |title| replace:: diffpy.labpdfproc package
+diffpy.labpdfproc package
+=========================
 
 .. automodule:: diffpy.labpdfproc
     :members:
@@ -14,17 +12,33 @@ Subpackages
 -----------
 
 .. toctree::
-   diffpy.labpdfproc.example_package
+    :titlesonly:
+
+    diffpy.labpdfproc.data
 
 Submodules
 ----------
 
-|module|
---------
+diffpy.labpdfproc.functions module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.labpdfproc.functions
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+diffpy.labpdfproc.tools module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automodule:: diffpy.labpdfproc.tools
+    :members:
+    :undoc-members:
+    :show-inheritance:
 
-.. |module| replace:: diffpy.labpdfproc.example_submodule module
+diffpy.labpdfproc.labpdfprocapp module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. automodule:: diffpy.labpdfproc.example_submodule
+.. automodule:: diffpy.labpdfproc.labpdfprocapp
     :members:
     :undoc-members:
     :show-inheritance:

docs/source/examples/labpdfprocapp-example.rst

@@ -10,121 +10,206 @@ to apply absorption correction to your 1D diffraction data using the command-lin
 Check ``labpdfproc --help`` for more information.
 A graphical user interface (GUI) is also available and is designed to be intuitive and easy to use.
 
+There are three ways to correct dirraction data within ``diffpy.labpdfproc``, these are,
 
-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.
+1. ``labpdfproc mud``: Provide the diffraction data file(s) and muD value directly.
+2. ``labpdfproc zscan``: Provide the diffraction data file(s) and a z-scan file, which will be used to calculate the muD value.
+3. ``labpdfproc sample``: Provide the diffraction data file(s) and information about the sample to calculate the theoretical muD value.
 
+We will go through all three methods in this tutorial.
 
-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:
+.. admonition:: Example Data
 
-.. code-block:: python
+    Example data for these examples can be found at: https://github.com/diffpy/diffpy.labpdfproc/tree/main/docs/source/examples/example-data
 
-    labpdfproc zro2_mo.xy --mud 2.5
 
+Launching the Graphical User Interface (GUI)
+--------------------------------------------
 
-3. You must provide at least one file path, and filepath(s) should immediately follow ``labpdfproc``.
+To launch the GUI, run one of the following commands in your terminal,
 
-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:: bash
 
-.. code-block:: python
+   labpdfproc
+   labpdfproc --gui
 
-    labpdfproc "SiO2 uncorrected.xy" input_dir file_list.txt ./*.chi data* --mud 2.5
+.. note:: Note that the GUI is currently not supported on Python>=3.12.
 
-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.
+This will open the GUI, which should look something like,
 
-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.
+.. image:: ../img/labpdfproc-gui.jpeg
+   :align: center
 
-We will now continue using ``zro2_mo.xy`` as the example input throughout the rest of this tutorial.
+Below we will go through all the commands using the CLI, but the same principles apply to the GUI.
 
+.. note:: The first time you run any of the below commands,
+    you will be prompted to enter your name, email, and ORCID. This will be
+    appended to metadata in the output file header for reproducibility and tracking purposes.
 
-4. The muD value is required for absorption correction, and you can specify it in one of the four ways:
 
-.. code-block:: python
+``labpdfproc mud`` Command
+---------------------------
 
-    # 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
+If you know the muD value for your sample, you can use the ``labpdfproc mud``
+command to apply absorption correction directly.
 
-Note that you can only use one method at a time. The following examples are not allowed:
+To see all the options for this command, type,
 
-.. code-block:: python
+.. code-block:: bash
 
-    labpdfproc zro2_mo.xy --mud 2.5 -z zscan.xy
-    labpdfproc zro2_mo.xy --mud 2.5 -d ZrO2,17.45,1.2
+    labpdfproc mud -h
 
-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.
+To run the correction, specify the path to your diffraction data file(s) and the muD value,
 
+.. code-block:: bash
 
-5. You can specify the wavelength in two ways:
+    labpdfproc mud <diffraction-data-file.xy> <mud>
+    labpdfproc mud zro2_mo.xy 2.5
 
-.. code-block:: python
+If the flag ``--wavelength`` is not specified, the program will attempt to fetch
+the wavelength from a configuration file.
+If the wavelength is not found in the configuration file, a ``ValueError``
+will be raised, prompting you to provide the wavelength either through the CLI or the configuration file.
 
-    # 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
+To provide the wavelength through the CLI, you can use the ``-w`` or ``--wavelength`` flag followed by the wavelength value in angstroms or the X-ray source.
+For example,
 
-Do not use both ``-w`` and ``-a`` at the same time. For example:
+.. code-block:: bash
 
-.. code-block:: python
+    labpdfproc mud zro2_mo.xy 2.5 -w 0.71303
+    labpdfproc mud zro2_mo.xy 2.5 -w Mo
 
-    labpdfproc zro2_mo.xy --mud 2.5 -w 0.71303 -a Mo
+This will then save the corrected file in the same directory as the input file with the name ``zro2_mo_corrected.chi``.
 
-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.
+To save the correction file, specify the ``-c`` or ``--output-correction`` flag,
 
+.. code-block:: bash
 
-6. You are also encouraged to provide your information (name, email, and orcid) for reproducibility:
+    labpdfproc mud zro2_mo.xy 2.5 -w 0.71303 -c
 
-.. code-block:: python
+This will then save the correction file in the same directory as the input file with the name ``zro2_mo_cve.chi``.
 
-    labpdfproc zro2_mo.xy --mud 2.5 -n Joe -e Joe@email.com --orcid 0000-0000-0000-0000
+``labpdfproc zscan`` Command
+----------------------------
 
+The ``labpdfproc zscan`` command allows you to calculate the muD value from a z-scan file and apply absorption correction to your diffraction data.
+For more information on what a z-scan is, please see the "Examples --> Linear Absorption Coefficient Examples"
+section in the ``diffpy.utils`` documentation: https://www.diffpy.org/diffpy.utils/examples/mu_calc_examples.html.
 
-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.
+To see the options for this command, type,
 
+.. code-block:: bash
 
-7. You can further customize the diffraction correction process using the following options:
+    labpdfproc zscan -h
 
-- 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.
+To run this command, provide the path to your diffraction data file(s) and the z-scan file,
 
+.. code-block:: bash
 
-8. To summarize, a full command might look like this:
+    labpdfproc zscan <diffraction-data-file.xy> <zscan-file.xy>
+    labpdfproc zscan CeO2_635um_accum_0.xy CeO2_635um_zscan.xy
 
-.. code-block:: python
+Like the ``labpdfproc mud`` command, you can also specify the
+wavelength or source type using the ``-w`` flag if it's not found in the configuration file,
 
-    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
+.. code-block:: bash
 
-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.
+    labpdfproc zscan CeO2_635um_accum_0.xy CeO2_635um_zscan.xy -w 0.71303
+    labpdfproc zscan CeO2_635um_accum_0.xy CeO2_635um_zscan.xy -w Mo
+
+This will save the corrected file in the same directory as the input file with the name ``CeO2_635um_accum_0.chi``.
+
+To save the correction file, specify the ``-c`` or ``--output-correction`` flag,
+
+.. code-block:: bash
+
+    labpdfproc zscan CeO2_635um_accum_0.xy CeO2_635um_zscan.xy -w 0.71303 -c
+
+This will then save the correction file in the same directory as the input file with the name ``CeO2_635um_accum_0_cve.chi``.
+
+``labpdfproc sample`` Command
+-----------------------------
+
+The ``labpdfproc sample`` command allows you to calculate the muD value from information
+about your sample and apply absorption correction to your diffraction data.
+
+To see the options for this command, type,
+
+.. code-block:: bash
+
+    labpdfproc sample -h
+
+To run this command, provide the path to your diffraction data file(s) along with:
+
+1) ``sample_composition``: The chemical formula of your sample.
+2) ``sample_mass_density``: The mass density of your sample in g/cm^3. If you don't know the mass density, a good approximation is typically ~1/3 of the theoretical packing fraction.
+3) ``diameter``: The outer diameter of your capillary.
+
+.. code-block:: bash
+
+    labpdfproc sample <diffraction-data-file.xy> <sample_composition> <sample_mass_density> <diameter>
+    labpdfproc sample zro2_mo.xy ZrO2 17.45 1.2
+
+Once again, you can specify the wavelength or source type using the ``-w`` flag if it's not found in the configuration file,
+
+.. code-block:: bash
+
+    labpdfproc sample zro2_mo.xy ZrO2 17.45 1.2 -w 0.71303
+    labpdfproc sample zro2_mo.xy ZrO2 17.45 1.2 -w Mo
+
+This will save the corrected file in the same directory as the input file with the name ``zro2_mo.chi``.
+
+To save the correction file, specify the ``-c`` or ``--output-correction`` flag,
+
+.. code-block:: bash
+
+    labpdfproc sample zro2_mo.xy ZrO2 17.45 1.2 -w 0.71303 -c
+
+This will then save the correction file in the same directory as the input file with the name ``zro2_mo_cve.chi``.
+
+Additional CLI options
+----------------------
+
+Below is a summary of all the additional flags that can be used with all three commands,
+
+- ``-h, --help``
+  Show this help message and exit.
+
+- ``-w, --wavelength WAVELENGTH``
+  X-ray wavelength in angstroms (numeric) or X-ray source name.
+  Allowed: ``Ag``, ``AgKa1``, ``AgKa1Ka2``, ``Cu``, ``CuKa1``, ``CuKa1Ka2``, ``Mo``, ``MoKa1``, ``MoKa1Ka2``.
+  Will be loaded from config files if not specified.
+
+- ``-x, --xtype XTYPE``
+  X-axis type (default: ``tth``). Allowed values: ``angle``, ``tth``, ``twotheta``, ``2theta``, ``d``, ``dspace``, ``q``.
+
+- ``-m, --method {brute_force, polynomial_interpolation}``
+  Method for cylindrical volume element (CVE) calculation (default: ``polynomial_interpolation``).
+  Allowed methods: ``brute_force``, ``polynomial_interpolation``.
+
+- ``-o, --output-directory OUTPUT_DIRECTORY``
+  Directory to save corrected files (created if needed). Defaults to current directory.
+
+- ``-f, --force``
+  Overwrite existing files.
+
+- ``-c, --output-correction``
+  Also output the absorption correction to a separate file.
+
+- ``-u, --user-metadata KEY=VALUE [KEY=VALUE ...]``
+  Specify key-value pairs to be loaded into metadata. Format: ``key=value``.
+  - Separate multiple pairs with whitespace.
+  - No spaces before or after ``=``.
+  - Avoid using ``=`` in keys. Only the first ``=`` separates key and value.
+  - If a key or value contains whitespace, enclose it in quotes.
+    Examples:
+    ``facility='NSLS II', beamline=28ID-2, 'favorite color'=blue``.
+
+- ``--username USERNAME``
+  Your name (optional, for dataset credit). Will be loaded from config files if not specified.
+
+- ``--email EMAIL``
+  Your email (optional, for dataset credit). Will be loaded from config files if not specified.
+
+- ``--orcid ORCID``
+  Your ORCID ID (optional, for dataset credit). Will be loaded from config files if not specified.