From 5d4accf4a824abb7772d4eb60bd42872edf21ad9 Mon Sep 17 00:00:00 2001 From: yucongalicechen Date: Tue, 28 Jan 2025 12:51:21 -0500 Subject: [PATCH 1/4] docs: initial commit --- doc/examples/{ => example_data}/zro2_mo.xy | 0 doc/examples/examples.rst | 10 ++++++++++ doc/examples/functions_example.rst | 10 ++++++++++ doc/utilities/functions_utility.rst | 4 ++++ doc/utilities/utilities.rst | 13 +++++++++++++ 5 files changed, 37 insertions(+) rename doc/examples/{ => example_data}/zro2_mo.xy (100%) create mode 100644 doc/examples/examples.rst create mode 100644 doc/examples/functions_example.rst create mode 100644 doc/utilities/functions_utility.rst create mode 100644 doc/utilities/utilities.rst diff --git a/doc/examples/zro2_mo.xy b/doc/examples/example_data/zro2_mo.xy similarity index 100% rename from doc/examples/zro2_mo.xy rename to doc/examples/example_data/zro2_mo.xy diff --git a/doc/examples/examples.rst b/doc/examples/examples.rst new file mode 100644 index 0000000..6e7d024 --- /dev/null +++ b/doc/examples/examples.rst @@ -0,0 +1,10 @@ +.. _Examples: + +:tocdepth: -1 + +Examples +######## +Landing page for diffpy.labpdfproc examples. + +.. toctree:: + functions_example diff --git a/doc/examples/functions_example.rst b/doc/examples/functions_example.rst new file mode 100644 index 0000000..d38f26d --- /dev/null +++ b/doc/examples/functions_example.rst @@ -0,0 +1,10 @@ +.. _Functions Example: + +:tocdepth: -1 + +Functions Example +################# + +This example will demonstrate how to use ``diffpy.labpdfproc.functions`` modules to apply absorption correction to their intensity data. + +1) diff --git a/doc/utilities/functions_utility.rst b/doc/utilities/functions_utility.rst new file mode 100644 index 0000000..f50d20e --- /dev/null +++ b/doc/utilities/functions_utility.rst @@ -0,0 +1,4 @@ +.. _Functions Utility: + +Functions Utility +================= diff --git a/doc/utilities/utilities.rst b/doc/utilities/utilities.rst new file mode 100644 index 0000000..715063b --- /dev/null +++ b/doc/utilities/utilities.rst @@ -0,0 +1,13 @@ +.. _Utilities: + +:tocdepth: -1 + +Utilities +######### +Overview of utilities offered by ``diffpy.labpdfproc``. +Check the :ref:`examples` provided for how to use these. + +.. contents:: + :depth: 2 + +.. include:: functions_utility.rst From 09d6638364c28816d91cf2c6a3cd8b44f8f9b3d1 Mon Sep 17 00:00:00 2001 From: yucongalicechen Date: Fri, 31 Jan 2025 16:36:31 -0500 Subject: [PATCH 2/4] docs: add utility for functions.py --- doc/utilities/functions_utility.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/doc/utilities/functions_utility.rst b/doc/utilities/functions_utility.rst index f50d20e..dc44508 100644 --- a/doc/utilities/functions_utility.rst +++ b/doc/utilities/functions_utility.rst @@ -2,3 +2,22 @@ Functions Utility ================= + +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), + 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. + +- `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. + +For a more in-depth tutorial for how to use these tools, click :ref:`here `. From aff934c516b6b3f2167c94e2e0d9de50d0ce50ea Mon Sep 17 00:00:00 2001 From: yucongalicechen Date: Fri, 31 Jan 2025 18:22:28 -0500 Subject: [PATCH 3/4] docs: add functions examples, move files around to make docs appear correctly --- doc/examples/functions_example.rst | 10 --- doc/source/api/diffpy.labpdfproc.rst | 8 -- .../examples/example_data/zro2_mo.xy | 0 doc/{ => source}/examples/examples.rst | 0 doc/source/examples/functions_example.rst | 74 +++++++++++++++++++ doc/source/index.rst | 2 + .../utilities/functions_utility.rst | 8 +- doc/{ => source}/utilities/utilities.rst | 0 8 files changed, 80 insertions(+), 22 deletions(-) delete mode 100644 doc/examples/functions_example.rst rename doc/{ => source}/examples/example_data/zro2_mo.xy (100%) rename doc/{ => source}/examples/examples.rst (100%) create mode 100644 doc/source/examples/functions_example.rst rename doc/{ => source}/utilities/functions_utility.rst (74%) rename doc/{ => source}/utilities/utilities.rst (100%) diff --git a/doc/examples/functions_example.rst b/doc/examples/functions_example.rst deleted file mode 100644 index d38f26d..0000000 --- a/doc/examples/functions_example.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. _Functions Example: - -:tocdepth: -1 - -Functions Example -################# - -This example will demonstrate how to use ``diffpy.labpdfproc.functions`` modules to apply absorption correction to their intensity data. - -1) diff --git a/doc/source/api/diffpy.labpdfproc.rst b/doc/source/api/diffpy.labpdfproc.rst index 941776e..a3f53e1 100644 --- a/doc/source/api/diffpy.labpdfproc.rst +++ b/doc/source/api/diffpy.labpdfproc.rst @@ -35,14 +35,6 @@ diffpy.labpdfproc.tools module :undoc-members: :show-inheritance: -diffpy.labpdfproc.mud_calculator module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. automodule:: diffpy.labpdfproc.mud_calculator - :members: - :undoc-members: - :show-inheritance: - diffpy.labpdfproc.labpdfprocapp module ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/examples/example_data/zro2_mo.xy b/doc/source/examples/example_data/zro2_mo.xy similarity index 100% rename from doc/examples/example_data/zro2_mo.xy rename to doc/source/examples/example_data/zro2_mo.xy diff --git a/doc/examples/examples.rst b/doc/source/examples/examples.rst similarity index 100% rename from doc/examples/examples.rst rename to doc/source/examples/examples.rst diff --git a/doc/source/examples/functions_example.rst b/doc/source/examples/functions_example.rst new file mode 100644 index 0000000..cc833ea --- /dev/null +++ b/doc/source/examples/functions_example.rst @@ -0,0 +1,74 @@ +.. _Functions Example: + +:tocdepth: -1 + +Functions Example +################# + +This example will demonstrate how to use ``diffpy.labpdfproc.functions`` module independently +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: + +.. code-block:: python + + from diffpy.utils.parsers.loaddata import loadData + from diffpy.utils.diffraction_objects import DiffractionObject + + filepath = "../example_data/zro2_mo.xy" + xarray, yarray = loadData(filepath, unpack=True) + input_pattern = DiffractionObject( + xarray=xarray, + yarray=yarray, + xtype="tth", + wavelength=0.7, + scat_quantity="x-ray", + name="input diffraction data", + metadata={"beamline": "28ID-2"}, + ) + +For the full tutorial, 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, +apply it to your input pattern, and save the corrected file. + +.. code-block:: python + + from diffpy.labpdfproc.functions import apply_corr, compute_cve + absorption_correction = compute_cve(input_pattern, muD) # compute cve, default method is "polynomial_interpolation" + corrected_pattern = apply_corr(input_pattern, absorption_correction) # apply cve correction + corrected_data.dump("corrected pattern.chi", xtype="tth") # save the corrected pattern + +If you want to use brute-force computation instead, you can replace the first line with: + +.. code-block:: python + + absorption_correction = compute_cve(input_pattern, muD, method="brute_force") + +3. Now, you can visualize the effect of the absorption correction +by plotting the original and corrected diffraction patterns. + +.. code-block:: python + + 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.ylabel("Intensity") + plt.legend() + plt.title("Original vs. Corrected Intensity") + plt.show() + +4. You can modify the global parameters +``N_POINTS_ON_DIAMETER`` (the number of points on each diameter to sample the circle) +and ``TTH_GRID`` (the range of angles) when using the brute-force method. + +To speed up computation, you can reduce the range of ``TTH_GRID``. You can also increase ``N_POINTS_ON_DIAMETER`` +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. diff --git a/doc/source/index.rst b/doc/source/index.rst index 7fc14b4..1de5c3f 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -34,6 +34,8 @@ Table of contents license release + Utilities + Examples Package API ======= diff --git a/doc/utilities/functions_utility.rst b/doc/source/utilities/functions_utility.rst similarity index 74% rename from doc/utilities/functions_utility.rst rename to doc/source/utilities/functions_utility.rst index dc44508..6b15422 100644 --- a/doc/utilities/functions_utility.rst +++ b/doc/source/utilities/functions_utility.rst @@ -3,21 +3,21 @@ Functions Utility ================= -The `diffpy.labpdfproc.functions` module provides tools +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 +- ``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), 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 +- ``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. -- `apply_corr`: This function applies the computed absorption correction to the input diffraction pattern +- ``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. For a more in-depth tutorial for how to use these tools, click :ref:`here `. diff --git a/doc/utilities/utilities.rst b/doc/source/utilities/utilities.rst similarity index 100% rename from doc/utilities/utilities.rst rename to doc/source/utilities/utilities.rst From c3f19d80a249c44e042ef0762c12097f5fb5972e Mon Sep 17 00:00:00 2001 From: yucongalicechen Date: Fri, 31 Jan 2025 18:31:13 -0500 Subject: [PATCH 4/4] docs: add news --- news/functions-docs.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 news/functions-docs.rst diff --git a/news/functions-docs.rst b/news/functions-docs.rst new file mode 100644 index 0000000..8142dc4 --- /dev/null +++ b/news/functions-docs.rst @@ -0,0 +1,23 @@ +**Added:** + +* Documentation for functions module. + +**Changed:** + +* + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* + +**Security:** + +*