.. algorithm::

.. summary::

.. relatedalgorithms::

.. properties::

Description
-----------

This algorithm transforms an input workspace in wavelength to :math:`Q_{x}, Q_{z}`
or momentum space for reflectometry workspaces. Prior to the transformation, the
algorithm corrects the detector position to an angle :math:`\theta_f`, where
:math:`\theta_f` is extracted from the log value :literal:`stheta`, if it exists;
otherwise, no correction is done, and detectors are assumed to be at :math:`2\theta`.

For conversion of single histogram workspaces to :math:`Q_{z}`, see
:ref:`ConvertUnits <algm-ConvertUnits>` or
:ref:`ReflectometryMomentumTransfer <algm-ReflectometryMomentumTransfer>`.

This version of the algorithm takes :math:`\theta_f` from :math:`2\theta - \theta_i`,
whereas version 2 takes :math:`\theta_f` from :math:`2\theta`.

Prerequisites
#############

The workspace spectrum axis should be converted to signed\_theta using
:ref:`algm-ConvertSpectrumAxis` and the x axis should be
converted to Wavelength using :ref:`algm-ConvertUnits` before
running this algorithm. Histogram input workspaces are expected.

The algorithm will look for a specific log value called :literal:`stheta`, which
contains the incident theta angle :math:`\theta_i`. If the input
workspace does not contain this value, or if you wish to override this
value you can do so by providing your own :literal:`IncidentTheta` property and
enabling :literal:`OverrideIncidentTheta`.

The algorithm also has the ability to produce additional debugging information from the Tableworkspace
that can be used to create a patch plot of results before any 2D fractional rebinning has happened.

To create this table there are certain properties that must be present in the algorithm:

- The transform method must be NormalisedPolygon
- The option to Output as MD workspace must not be selected
- The option to DumpVertexes must be selected

Transformations
###############

Output workspaces are always 2D MD Histogram workspaces, but the
algorithm will perform one of three possible transformations.

-  Convert to :math:`Q_x`, :math:`Q_z`
-  Convert to :math:`K_i`, :math:`K_f`
-  Convert to :math:`P_i-P_f`, :math:`P_i+P_f`. Note that P and K are
   interchangeable.

where

:math:`Q_x = \frac{2\pi}{\lambda}(cos\theta_f - cos\theta_i)`

:math:`Q_z = \frac{2\pi}{\lambda}(sin\theta_f + sin\theta_i)`

:math:`K_i = \frac{2\pi}{\lambda}sin\theta_i`

:math:`K_f = \frac{2\pi}{\lambda}sin\theta_f`


After Transformation
####################

You will usually want to rebin using :ref:`algm-BinMD` or
:ref:`algm-SliceMD` after transformation because the output workspaces
are not regularly binned.

Binning Methods
###############

The *Method* property allows the binning method used when applying the
coordinate transformations to be selected. The default method,
*Centre*, takes center point of each input bin, and locates the
corresponding output bin, adding the input bins value to it. Centre point rebinning is faster.

*NormalisedPolygon* is a more sophisticated approach. It takes longer to run but gives better
accuracy. Please consult the :ref:`FractionalRebinning <FractionalRebinning>`
page for more information.

Usage
-----
Normalised Polygon Transformation
#################################

**Example - Normalised Polygon transformation**

.. testcode:: ExConvReflQSimple

    workspace_name = "POLREF4699"
    workspace_nexus_file = workspace_name + ".nxs"

    Load(Filename=workspace_nexus_file,OutputWorkspace=workspace_name)
    X = mtd[workspace_name]
    X = ConvertUnits(InputWorkspace=X,Target="Wavelength",AlignBins="1")
    # Reference intensity to normalise by
    CropWorkspace(InputWorkspace=X,OutputWorkspace='Io',XMin=0.8,XMax=14.5,StartWorkspaceIndex=2,EndWorkspaceIndex=2)
    # Crop out transmission and noisy data
    CropWorkspace(InputWorkspace=X,OutputWorkspace='D',XMin=0.8,XMax=14.5,StartWorkspaceIndex=3)
    Io=mtd['Io']
    D=mtd['D']

    # Perform the normalisation step
    Divide(LHSWorkspace=D,RHSWorkspace=Io,OutputWorkspace='I',AllowDifferentNumberSpectra='1',ClearRHSWorkspace='1')
    I=mtd['I'][0]

    # Move the detector so that the detector channel matching the reflected beam is at 0,0
    PIX = 1.1E-3 #m
    SC = 75
    avgDB = 29
    zOffset = -PIX * ((SC - avgDB) * 0.5 + avgDB)
    MoveInstrumentComponent(Workspace = I, ComponentName = "lineardetector", X = 0, Y = 0, Z = zOffset)

    # Should now have signed theta vs Lambda
    ConvertSpectrumAxis(InputWorkspace=I,OutputWorkspace='SignedTheta_vs_Wavelength',Target='signed_theta')

    qxqy, vertexes_qxqy = ConvertToReflectometryQ(InputWorkspace='SignedTheta_vs_Wavelength', OutputDimensions='Q (lab frame)', Extents='-0.0005,0.0005,0,0.12', OutputAsMDWorkspace=False,Method='NormalisedPolygon')

    kikf, vertexes_kikf = ConvertToReflectometryQ(InputWorkspace='SignedTheta_vs_Wavelength', OutputDimensions='K (incident, final)', Extents='0,0.05,0,0.05', OutputAsMDWorkspace=False,Method='NormalisedPolygon')

    pipf, vertexes_pipf = ConvertToReflectometryQ(InputWorkspace='SignedTheta_vs_Wavelength', OutputDimensions='P (lab frame)', Extents='0,0.1,-0.02,0.15', OutputAsMDWorkspace=False,Method='NormalisedPolygon')

    print("{} {}".format(qxqy.getDimension(0).name, qxqy.getDimension(1).name))
    print("{} {}".format(kikf.getDimension(0).name, kikf.getDimension(1).name))
    print("{} {}".format(pipf.getDimension(0).name, pipf.getDimension(1).name))


Output:

.. testoutput:: ExConvReflQSimple

    Qx Qz
    Ki Kf
    Pz_i + Pz_f Pz_i - Pz_f

Plot of the SignedTheta vs Wavelength workspace:
================================================
Before the ConvertToReflectometryQ algorithm is executed in the usage example above, the plot of the 'SignedTheta_vs_Wavelength' workspace should resemble this plot:

.. figure:: /images/SignedThetaVSlam_plot.png
   :alt: plot of Signed theta vs lambda.

Patch Plot with Dumped Vertexes
###############################

ConvertToReflectometryQ has the functionality to produce a table of vertexes before they are
fitted to a normalised polygon. The plotting of these vertexes results in a patch plot that can be
achieved by running the algorithm below.

**Example - Patch Plot using the Dumped vertexes from QxQy Transformation**

.. code-block:: python

    import numpy as np
    import matplotlib
    from matplotlib.patches import Polygon
    from matplotlib.collections import PatchCollection
    import matplotlib.pyplot as plt
    from matplotlib.colors import LogNorm

    # full reduction on workspace
    Load(Filename='data_th_lam.nxs', OutputWorkspace='data_th_lam')
    CropWorkspace('data_th_lam', StartWorkspaceIndex=124, OutputWorkspace='data_th_lam')
    data_th_lam = Rebin('data_th_lam', [1e-2])

    out_ws, dump_vertexes = ConvertToReflectometryQ(InputWorkspace='data_th_lam',OutputWorkspace='QxQy_poly', OutputDimensions='Q (lab frame)',
    Extents='-0.0005,0.0005,-0,0.2', OutputAsMDWorkspace=False,Method='NormalisedPolygon',  IncidentTheta=0.44, OverrideIncidentTheta=True, NumberBinsQx=100, NumberBinsQz=100,DumpVertexes=True, OutputVertexes='dump_vertexes')

    #plot the conversion
    plotSlice(out_ws)

    def patch_plot(vertex_table):
        fig, ax = plt.subplots()

        patches = list()
        colors = list()
        polygon_vertexes = list()

        for vertex in vertex_table:
            #Column of vertex i.e 'Qx' in this case, is dependent on the type of transform.
            #'Ki' and 'Kf' are used for the K transformation.
            #'Pi+Pf' and 'Pi-Pf' are used for the P transformation.
            polygon_vertexes.append((vertex['Qx'], vertex['Qy'] ))
            if len(polygon_vertexes) == 4:
                poly = Polygon(polygon_vertexes, True,edgecolor='none',linewidth=0)
                patches.append(poly)
                colors.append(vertex['CellSignal'])
                polygon_vertexes = list()

        p = PatchCollection(patches, cmap=matplotlib.cm.jet,norm=LogNorm(vmin=1e-3, vmax=1e5),linewidths=(0,))
        p.set_array(np.array(colors))
        ax.add_collection(p)
        plt.colorbar(p)
        axes = plt.gca()
        axes.set_xlim([-0.0004,0.0004])
        axes.set_ylim([0,0.2])

        fig.show()

    threadsafe_call(patch_plot, dump_vertexes)

**Output:**

Patch plot for QxQy Transformation:

.. figure:: /images/ConvertToReflectometryQ_PatchPlotQ.png
   :alt: patch plot of dumped vertexes using Q transformation

Patch plots from other transformations
######################################

Patch plots can also be produced using the other Transformations :math:`K_i, K_f` and :math:`P_i-P_f, P_i+P_f`


**Patch plot for KiKf Transformation:**


.. figure:: /images/ConvertToReflectometryQ_PatchPlotK.PNG
   :alt: patch plot of dumped vertexes using K transformation


**Patch plot for P Transformation:**


.. figure:: /images/ConvertToReflectometryQ_PatchPlotP.PNG
   :alt: patch plot of dumped vertexes using P transformation

.. categories::

.. sourcelink::