chore: resolve merge conflicts

Author: ycexiao

CITATION.cff

@@ -0,0 +1,57 @@
+cff-version: 1.2.0
+title: diffpy.morph
+message: >-
+  If you use this software, please cite the manuscript
+  associated with this repository (will be included here
+  when published).
+type: software
+authors:
+  - given-names: Andrew
+    family-names: Yang
+    email: ayang2@caltech.edu
+    affiliation: Caltech
+    orcid: "https://orcid.org/0000-0003-0553-715X"
+  - given-names: Christopher
+    family-names: Farrow
+    orcid: "https://orcid.org/0000-0001-5768-6654"
+  - given-names: Chia-Hao
+    family-names: Liu
+    affiliation: Columbia University
+    orcid: "https://orcid.org/0000-0002-3216-0354"
+  - given-names: Luis
+    family-names: Kitsu
+    orcid: "https://orcid.org/0000-0002-9292-4416"
+    affiliation: University of Colorado Boulder
+    email: Luis.Kitsu@echemes.ethz.ch
+  - given-names: Simon
+    family-names: Billinge
+    email: sb2896@columbia.edu
+    affiliation: Columbia University
+    orcid: "https://orcid.org/0000-0002-9734-4998"
+abstract: >-
+  diffpy.morph is an open-source and free-to-use Python
+  package that increases the insight researchers can obtain
+  when comparing experimentally measured 1D functions such
+  as diffraction patterns and atomic distribution functions
+  (PDFs). For example, it is often difficult to identify
+  whether or not structural changes have occurred between
+  two diffraction patterns or PDFs of the same material
+  measured at different temperatures due to the presence of
+  benign thermal effects such as lattice expansion and
+  increased atomic motion. These contribute large signals in
+  the difference curves and Rw factors when comparing two
+  curves, which can hide small but significant structural
+  changes. diffpy.morph does its best to correct for these
+  benign effects by applying simple transformations, or
+  “morphs”, to a diffraction pattern or PDF prior to
+  comparison. Other morphs are also possible such as
+  corrections for nanoparticle shape effects on the PDF.
+  diffpy.morph is model-independent and also could be used
+  on other non-diffraction spectra, though it has not been
+  extensively tested beyond powder diffraction patterns
+  and the PDF.
+keywords:
+  - diffpy
+  - pdf
+  - data interpretation
+license: BSD-3-Clause

README.rst

@@ -35,34 +35,35 @@
 .. |Tracking| image:: https://img.shields.io/badge/issue_tracking-github-blue
         :target: https://github.com/diffpy/diffpy.morph/issues
 
-Python package for manipulating and comparing PDF profiles
+Python package for manipulating and comparing diffraction data
 
 ``diffpy.morph`` is a Python software package designed to increase the insight
-researchers can obtain from measured atomic pair distribution functions
+researchers can obtain from measured diffraction data
+and atomic pair distribution functions
 (PDFs) in a model-independent way. The program was designed to help a
 researcher answer the question: "Has my material undergone a phase
 transition between these two measurements?"
 
-One approach is to compare the two PDFs in a plot and view the difference
-curve underneath. However, significant signal can be seen in the
-difference curve from benign effects such as thermal expansion (peak
-shifts) and increased thermal motion (peak broadening) or a change in
+One approach is to compare the two diffraction patterns in a plot
+and view the difference curve underneath. However, significant signal can
+be seen in the difference curve from benign effects such as thermal expansion
+(peak shifts) and increased thermal motion (peak broadening) or a change in
 scale due to differences in incident flux, for example. ``diffpy.morph`` will
 do its best to correct for these benign effects before computing and
-plotting the difference curve. One measured PDF (typically that collected
-at higher temperature) is identified as the target PDF and the second
-PDF is then morphed by "stretching" (changing the r-axis to simulate a
+plotting the difference curve. One measured function (typically that collected
+at higher temperature) is identified as the target function and the second
+function is then morphed by "stretching" (changing the r-axis to simulate a
 uniform lattice expansion), "smearing" (broadening peaks through a
 uniform convolution to simulate increased thermal motion), and "scaling"
 (self-explanatory). ``diffpy.morph`` will vary the amplitude of the morphing
 transformations to obtain the best fit between the morphed and the target
-PDFs, then plot them on top of each other with the difference plotted
+functions, then plot them on top of each other with the difference plotted
 below.
 
 There are also a few other morphing transformations in the program.
 
-Finally, we note that ``diffpy.morph`` should work on other spectra that are not
-PDFs, though it has not been extensively tested beyond the PDF.
+Finally, we note that ``diffpy.morph`` should work on other spectra,
+though it has not been extensively tested beyond spectral data and the PDF.
 
 
 For more information about the diffpy.morph library, please consult our `online documentation <https://diffpy.github.io/diffpy.morph>`_.
@@ -153,9 +154,9 @@ If installed correctly, this last command should return the version
 of ``diffpy.morph`` that you have installed on your system. To begin using
 ``diffpy.morph``, run a command like ::
 
-	diffpy.morph <target PDF file> <morphed PDF file>
+	diffpy.morph <morph file> <target file>
 
-where both PDFs file are text files which contain PDF data, such as ``.gr``
+where both files are text files which contain two-column data, such as ``.gr``
 or ``.cgr`` files that are produced by ``PDFgetX2``, ``PDFgetX3``,
 or ``PDFgui``. File extensions other than ``.gr`` or ``.cgr``,
 but with the same content structure, also work with ``diffpy.morph``.

TUTORIAL.rst

@@ -132,10 +132,10 @@ Basic diffpy.morph Workflow
               superficial and in most cases can be ignored.
 
        We see that this has had hardly any effect on our PDF. To see
-       an effect, we restrict the ``rmin`` and ``rmax`` values to
+       an effect, we restrict the ``xmin`` and ``xmax`` values to
        reflect relevant data range by typing ::
 
-            diffpy.morph --scale=0.8 --smear=0.5 --rmin=1.5 --rmax=30 darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr
+            diffpy.morph --scale=0.8 --smear=0.5 --xmin=1.5 --xmax=30 darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr
 
        Now, we see that the difference Rw = 0.204 and that the optimized
        ``smear=-0.084138``.
@@ -151,7 +151,7 @@ Basic diffpy.morph Workflow
     8. Finally, we will examine the stretch factor. Provide an initial
        guess by typing ::
 
-            diffpy.morph --scale=0.8 --smear=-0.08 --stretch=0.5 --rmin=1.5 --rmax=30 -a darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr
+            diffpy.morph --scale=0.8 --smear=-0.08 --stretch=0.5 --xmin=1.5 --xmax=30 -a darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr
 
        And noting that the difference has increased. Before continuing,
        see if you can see which direction (higher or lower) our initial
@@ -160,7 +160,7 @@ Basic diffpy.morph Workflow
 
        If you cannot, type ::
 
-            diffpy.morph --scale=0.8 --smear=-0.08 --stretch=0.005 --rmin=1.5 --rmax=30 -a darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr
+            diffpy.morph --scale=0.8 --smear=-0.08 --stretch=0.005 --xmin=1.5 --xmax=30 -a darkSub_rh20_C_01.gr darkSub_rh20_C_44.gr
 
        to observe decreased difference and then remove ``-a`` to see
        the optimized ``--stretch=0.001762``. We have now reached

docs/source/funcxy.rst

@@ -0,0 +1,181 @@
+.. _funcxy:
+
+Using funcxy with Commonly-Used Diffraction Software
+####################################################
+
+The general xy morph ``funcxy`` can be used to tune parameters
+of many popular diffraction software functions.
+
+Below, we give templates for how one can use ``funcxy``
+with `PDFgetx3 <https://www.diffpy.org/products/pdfgetx.html>`_
+and `PyFai <https://pyfai.readthedocs.io/en/stable/>`_.
+
+Getting a Better PDF with PDFgetx3
+==================================
+
+In PDFgetx3, the ``PDFGetter`` takes in a 1D diffraction
+pattern I(Q) and returns a PDF G(r).
+
+There are many parameters you can specify, such as
+  - ``qmin``: Lower Q-cutoff for the Fourier transform giving the PDF
+  - ``qmax``: Upper Q-cutoff for the Fourier transform giving the PDF
+  - ``qmaxinst``: Upper Q-boundary for meaningful signal
+  - ``rpoly``: Approximately the low-r bound of meaningful G(r) values
+
+Furthermore, you can supply a background file ``backgroundfile``
+and subtract a scaled version of the background file by the
+scaling factor ``bgscale``.
+
+We will showcase an example of how one would refine over the
+``PDFGetter`` parameters using ``funcxy`` to obtain a PDF.
+
+Let's say you have a measured I(Q) with Q in angstroms of
+glass (composition SiO2) named ``sample.chi`` taken on a
+kapton background. We want to match a target calculated PDF G(r)
+stored in a file named ``target.cgr``.
+Let's also say we have a measured I(Q) of the
+kapton background ``background.chi``.
+
+.. code-block:: python
+
+     from diffpy.pdfgetx.pdfgetter import PDFGetter
+     from diffpy.morph.morphpy import morph_arrays
+     from diffpy.utils.parsers.loaddata import loadData
+
+     pg = PDFGetter()
+
+     backgroundfile = "background.chi"
+     composition = "SiO2"
+
+
+     def wrap(x, y, **kwargs):
+         xy_out = pg.__call__(
+                         x=x, y=y, dataformat="QA",
+                         composition=composition,
+                         backgroundfile=backgroundfile,
+                         **kwargs
+                     )
+         r = xy_out[0]
+         gr = xy_out[1]
+         return (r, gr)
+
+
+     sample_iq = loadData("sample.chi")
+     target_gr = loadData("target.cgr")
+     params_to_morph = {
+         "bgscale": 1.0,
+         "qmin": 0.0, "qmax": 25.0,
+         "qmaxinst": 25.0, "rpoly": 0.9
+     }
+
+     morph_info, morphed_gr = morph_arrays(
+                                     sample_iq, target_gr,
+                                     funcxy=(wrap, params_to_morph)
+                                 )
+
+You can now plot ``morphed_gr`` against your ``target_gr`` to see
+how well your morphing refinement of the PDF-getting parameters
+as done!
+To see what the refined values of the parameters are,
+print out ``morph_info``.
+You can freely add and remove entries in
+``params_to_morph`` to include or not include them as
+parameters to refine over.
+
+If you expect to see thermal effect differences between your
+measured PDF and ``target_gr``, you can also include
+the ``stretch``, ``scale``, and ``smear`` morphs in your
+call to ``morph_arrays``.
+
+
+Performing Detector Calibration with PyFai
+==========================================
+
+When performing azimuthal integration, it is important to
+ensure your beam center and detector distances are calibrated.
+However, it is possible that they have shifted
+across measurements. Here, we will use morphing to the rescue!
+
+Let's say we just measured a diffraction pattern stored
+as a NumPy object in ``diffraction_image.npy``, but some
+of the detector geometries are off.
+Our azimuthally integrated ``sample.chi`` looks a bit off.
+Before this measurement, you measured an amazing
+I(Q) pattern ``target.chi`` with a perfectly calibrated
+sample-to-detector distance and beam center.
+We will use morphing to try to match the integration of
+the 2D pattern to the target 1D function.
+
+For the integration, we will need some information, such as
+the wavelength of the beam,
+the size of each pixel in the 2D image
+(``pixel1`` is the horizontal length in meters and
+``pixel2`` is the vertical length in meters),
+and a guess of the beam center.
+This information can be found on the
+`PyFai documentation <https://pyfai.readthedocs.io/en/stable/usage/cookbook/integration_with_python.html>`_.
+For our example, let's say we have a ``1024``x``1024`` pixel image
+where each pixel is a ``100`` micron by ``100`` micron region, and
+our wavelength was ``1.11`` angstroms.
+
+.. code-block:: python
+
+     import numpy as np
+     import pyFAI.integrator.azimuthal as pyfai
+     import pyFAI.detectors as pfd
+     from diffpy.morph.morphpy import morph_arrays
+     from diffpy.utils.parsers.loaddata import loadData
+
+     pattern_2d = np.load("diffraction_image.npy")
+     wavelength = 0.1110e-9  # in m
+     pixel1 = 1e-4  # in m
+     pixel2 = 1e-4  # in m
+     cent_x = 511   # in number of pixels
+     cent_y = 511   # in number of pixels
+
+     ai = pyfai.AzimuthalIntegrator()
+     ai.wavelength = wavelength
+     detector = pfd.Detector()
+     detector.max_shape = pattern_2d.shape
+
+
+     def wrap(x, y, sample_to_detector_dist, cent_offset_x, cent_offset_y):
+         detector.pixel1 = pixel1
+         detector.pixel2 = pixel2
+         ai.detector = detector
+
+         ai.setFit2D(
+             directDist=sample_to_detector_dist,
+             centerX=cent_x+cent_offset_x,
+             centerY=cent_y+cent_offset_y
+         )
+
+         return ai.integrate1d_ng(
+                 pattern_2d,
+                 npt=1000, unit="q_A^-1",
+                 method="mean"
+             )
+
+
+     params_to_morph = {
+         "sample_to_detector_dist": 60,  # in mm
+         "cent_offset_x": 0,  # in number of pixels
+         "cent_offset_y": 0  # in number of pixels
+     }
+
+     sample_chi = loadData("sample.chi")
+     target_chi = loadData("target.chi")
+
+     morph_info, morphed_chi = morph_arrays(
+                                     sample_chi, target_chi,
+                                     funcxy=(wrap, params_to_morph)
+                                 )
+
+You can now plot ``morphed_chi`` against your ``target_chi``
+to see if the refinement has helped in the calibration!
+To see the calibrated values, you can print out ``morph_info``.
+
+If you would like to morph over other PyFai parameters
+(e.g. ``rot1``, ``tilt``, ``wavelength``),
+you can adjust the wrapper function ``wrap`` to take in
+these parameters.

docs/source/index.rst

@@ -34,10 +34,11 @@ plotted below.
 
 There are also a few other morphing transformations in the program.
 If no morphing transformation is specified, ``diffpy.morph`` will return just
-the plotted PDFs.
+the plotted functions.
 
 Finally, we note that though ``diffpy.morph`` should work on other spectra
-that are not PDFs, it has not been extensively tested beyond the PDF.
+that are not from diffraction, it has not been extensively tested beyond 1D
+diffraction patterns and PDFs.
 
 To get started, please visit the `quickstart tutorial <quickstart.html>`__.
 For those looking to see more advanced features, you can read our