diff --git a/docs/release_notes.rst b/docs/release_notes.rst index 31666f1..65600d9 100644 --- a/docs/release_notes.rst +++ b/docs/release_notes.rst @@ -13,6 +13,7 @@ Notes for major and minor releases. Notes for Patch releases are deferred. **Of interest to the User**: - PR #137: Update final rebin and Q-Steps to be configurable per run or globally + - PR #138: Add user documentation for how binning parameters are used **Of interest to the Developer:** diff --git a/docs/user/binning.rst b/docs/user/binning.rst new file mode 100644 index 0000000..9912573 --- /dev/null +++ b/docs/user/binning.rst @@ -0,0 +1,98 @@ +.. _binning: + +Binning a Reduced Workspace in QuickNXS +======================================= + +Overview +-------- + +Binning is an essential process in reflectivity reduction within QuickNXS, organizing raw data into manageable intervals for accurate analysis. +It helps improve signal clarity, reduce noise, and ensure meaningful comparisons between datasets. This guide explains the available binning options +in QuickNXS and how to configure them for the best results. + +.. note:: All binning options are ultimately passed to the `MagnetismReflectometryReduction algorithm `_ in Mantid. + +Binning Options +--------------- + +The following options allow users to fine-tune binning behavior: + +1. **Bin Width** (Numeric Input, Applied Globally) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + - **Constraints:** Must be an integer value between 5 and 10000. + - **What It Does:** Defines the width of bins used to rebin the input workspace. + - **How It Works:** + + - This step **always occurs** and cannot be skipped. + - If the minimum TOF (Time-of-Flight) value is **≤ 0**, `Bin Width` is also used as the TOF minimum. + - The direct beam workspace is rebinned to match the binning of the input workspace before reflectivity is calculated. + + - **How to Use It:** Enter a numeric value to specify the desired bin width. + +2. **Final Rebin** (Checkbox, Per-Run or Global) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + - **What It Does:** Controls whether the final reduced workspace (converted to Q-space) undergoes additional rebinning. + - **How It Works:** + + - When enabled, rebinning is performed using `Q Steps` as the bin width. + - This option is **only available** if `Constant-Q Binning` is **disabled**. + - If `Constant-Q Binning` is enabled, it **takes priority** over `Final Rebin`. + - If `Final Rebin` is enabled **per-run**, the `Q Steps` values can be viewed and updated in the reduction data table under the `Q-Steps` column. If it is enabled globally, it takes priority over any per-run `Q Steps` values. + + - **How to Use It:** Check this box if you want to apply final rebinning. + +1. **Constant-Q Binning** (Checkbox, Applied Globally) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + - **What It Does:** Determines whether binning remains constant in Q-space. + - **How It Works:** + + - When enabled, `Final Rebin` is disregarded. + - `Q Steps` is used to determine binning: + + - If **positive**, bins are evenly spaced. + - If **negative**, bins are spaced logarithmically using a geometric progression. + + - This setting is **global** and cannot be adjusted per-run. + + - **How to Use It:** Check this box if you want to maintain constant-Q binning. Ensure `Q Steps` is set appropriately for either linear or logarithmic binning. + +1. **Q Steps** (Numeric Input, Per-Run or Global) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + - **Constraints:** Must be a floating point value between -0.1 and 0.1 + - **What It Does:** Defines the bin width for the final rebinning in Q-space. + - **How It Works:** + + - `Q Steps` is used in both `Final Rebin` and `Constant-Q Binning`. + - When `Final Rebin` is enabled, `Q Steps` sets the bin width for the final rebinning. + - When `Constant-Q Binning` is enabled, `Q Steps` determines whether binning follows a **linear** or **logarithmic** scale. + + - It controls the resolution of the final reduced workspace. + - If `Q Steps` is **positive**, linear binning is applied with evenly spaced bins. + - If `Q Steps` is **negative**, logarithmic binning is applied, where bin edges follow a geometric progression. + + - **How to Use It:** Enter a numeric value to specify the bin width for Q-space rebinning. Use negative values for logarithmic binning. + +Binning Workflow +---------------- + +To apply binning settings effectively, follow these steps: + +1. **Set the Input Workspace Binning:** +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + - Enter a `Bin Width` value to define the initial binning. + - If TOF min is ≤ 0, `Bin Width` will also be used as the TOF minimum. + - The direct beam workspace is automatically rebinned to match this setting. + +2. **Apply Final Binning (Optional):** +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + - If `Constant-Q Binning` is **enabled**, it takes priority over `Final Rebin`. + - If `Constant-Q Binning` is **disabled** and additional Q-space binning is required, check `Final Rebin` and specify a `Q Steps` value. + - If `Final Rebin` is enabled **per-run**, the `Q Steps` values can be viewed and updated in the reduction data table under the `Q-Steps` column. + - If using `Constant-Q Binning`, ensure `Q Steps` is appropriately set for linear or logarithmic binning. + +By adjusting these options, users can customize their reflectivity reduction workflow to achieve the desired data resolution and accuracy. diff --git a/docs/user/index.rst b/docs/user/index.rst index 33f1733..c2f7632 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -10,3 +10,4 @@ TODO dead_time_correction advanced_parameters + binning