From 267085bfc647015889691db584d1dccd139409cf Mon Sep 17 00:00:00 2001
From: David Fairbrother <DavidFair@users.noreply.github.com>
Date: Mon, 22 May 2017 19:56:50 +0100
Subject: [PATCH] Re #19575 Added initial reference guide for Pearl
---
.../python/techniques/ISISPowder-GEM-v1.rst | 44 +-
.../python/techniques/ISISPowder-Pearl-v1.rst | 749 +++++++++++++-----
.../techniques/ISISPowder-Polaris-v1.rst | 45 +-
scripts/Diffraction/isis_powder/pearl.py | 2 +-
.../pearl_routines/pearl_advanced_config.py | 34 +-
.../isis_powder/pearl_routines/pearl_algs.py | 5 +-
.../pearl_routines/pearl_param_mapping.py | 12 +-
7 files changed, 614 insertions(+), 277 deletions(-)
diff --git a/docs/source/api/python/techniques/ISISPowder-GEM-v1.rst b/docs/source/api/python/techniques/ISISPowder-GEM-v1.rst
index 563cb646a74..9c5b36d8dca 100644
--- a/docs/source/api/python/techniques/ISISPowder-GEM-v1.rst
+++ b/docs/source/api/python/techniques/ISISPowder-GEM-v1.rst
@@ -346,8 +346,6 @@ the run number corresponding to the vanadium. However it
must be in the correct cycle according to the
:ref:`calibration_mapping_gem-isis-powder-ref`.
-Additionally the run
-
Example Input:
.. code-block:: Python
@@ -422,6 +420,27 @@ Example Input:
# Or
gem_example.focus(multiple_scattering=False, ...)
+.. _output_directory_gem_isis-powder-diffraction-ref:
+
+output_directory
+^^^^^^^^^^^^^^^^
+Specifies the path to the output directory to save resulting files
+into. The script will automatically create a folder
+with the label determined from the
+:ref:`calibration_mapping_file_gem_isis-powder-diffraction-ref`
+and within that create another folder for the current
+:ref:`user_name_gem_isis-powder-diffraction-ref`.
+
+Within this folder processed data will be saved out in
+several formats.
+
+Example Input:
+
+.. code-block:: Python
+
+ output_dir = r"C:\path\to\output_dir"
+ gem_example = Gem(output_directory=output_dir, ...)
+
.. _run_number_gem_isis-powder-diffraction-ref:
run_number
@@ -479,27 +498,6 @@ Example Input:
# Or a range of numbers
gem_example.focus(sample_empty="100-110", ...)
-.. _output_directory_gem_isis-powder-diffraction-ref:
-
-output_directory
-^^^^^^^^^^^^^^^^
-Specifies the path to the output directory to save resulting files
-into. The script will automatically create a folder
-with the label determined from the
-:ref:`calibration_mapping_file_gem_isis-powder-diffraction-ref`
-and within that create another folder for the current
-:ref:`user_name_gem_isis-powder-diffraction-ref`.
-
-Within this folder processed data will be saved out in
-several formats.
-
-Example Input:
-
-.. code-block:: Python
-
- output_dir = r"C:\path\to\output_dir"
- gem_example = Gem(output_directory=output_dir, ...)
-
.. _unit_to_keep_gem_isis-powder-diffraction-ref:
unit_to_keep
diff --git a/docs/source/api/python/techniques/ISISPowder-Pearl-v1.rst b/docs/source/api/python/techniques/ISISPowder-Pearl-v1.rst
index f87c4126a0b..0c5735f0e8d 100644
--- a/docs/source/api/python/techniques/ISISPowder-Pearl-v1.rst
+++ b/docs/source/api/python/techniques/ISISPowder-Pearl-v1.rst
@@ -1,291 +1,636 @@
.. _isis-powder-diffraction-pearl-ref:
-=======================================
-ISIS Powder Diffraction Scripts - Pearl
-=======================================
-
-.. warning:: These scripts and documentation are still undergoing active development.
- They can change in any way during these stages and the validity of all
- data has not been tested.
+=====================================================
+ISIS Powder Diffraction Scripts - PEARL Reference
+=====================================================
.. contents:: Table of Contents
:local:
+.. _creating_pearl_object-isis-powder-diffraction-ref:
-.. _pearl_cal_folder_isis-powder-diffraction-ref:
+Creating PEARL Object
+--------------------
+This method assumes you are familiar with the concept of objects in Python.
+If not more details can be read here: :ref:`intro_to_objects-isis-powder-diffraction-ref`
-Calibration Folder
--------------------
-Within the top level of the calibration folder the following files must be present:
+To create a PEARL object the following parameters are required:
-- .cal files containing grouping information (for all tt_modes)
-- .nxs file with absorption corrections (if using absorption corrections)
-- Folder for each cycle label (e.g. 10_2) containing a .cal file with detector offsets
- for that cycle
+- :ref:`calibration_directory_pearl_isis-powder-diffraction-ref`
+- :ref:`output_directory_pearl_isis-powder-diffraction-ref`
+- :ref:`user_name_pearl_isis-powder-diffraction-ref`
-The names of the .cal grouping files and .nxs absorption file is set in the advanced
-configuration file: :ref:`pearl_adv_script_params_isis-powder-diffraction-ref`
+Optionally a configuration file may be specified if one exists
+using the following parameter:
-The label for the run the user is processing and the appropriate offset filename is
-taken from the calibration mapping file: :ref:`pearl_cal_map_isis-powder-diffraction-ref`.
+- :ref:`config_file_pearl_isis-powder-diffraction-ref`
-.. _pearl_cal_map_isis-powder-diffraction-ref:
+See :ref:`configuration_files_isis-powder-diffraction-ref`
+on YAML configuration files for more details
-Calibration Configuration File
-------------------------------
-An example layout is below:
+Example
+^^^^^^^
-File structure:
+.. code-block:: Python
-.. code-block:: yaml
- :linenos:
+ from isis_powder import Pearl
+
+ calibration_dir = r"C:\path\to\calibration_dir"
+ output_dir = r"C:\path\to\output_dir"
+
+ pearl_example = Pearl(calibration_directory=calibration_dir,
+ output_directory=output_dir,
+ user_name="Mantid")
+
+ # Optionally we could provide a configuration file like so
+ # Notice how the file name ends with .yaml
+ config_file_path = r"C:\path\to\config_file.yaml
+ pearl_example = Pearl(config_file=config_file_path,
+ user_name="Mantid", ...)
+
+Methods
+--------
+The following methods can be executed on a PEARL object:
+
+- :ref:`create_vanadium_pearl_isis-powder-diffraction-ref`
+- :ref:`focus_pearl_isis-powder-diffraction-ref`
+
+For information on creating a PEARL object see:
+:ref:`creating_pearl_object-isis-powder-diffraction-ref`
+
+.. _create_vanadium_pearl_isis-powder-diffraction-ref:
+
+create_vanadium
+^^^^^^^^^^^^^^^
+The *create_vanadium* method allows a user to process a vanadium run.
+Whilst processing the vanadium run the scripts can apply any corrections
+the user enables and will spline the resulting workspace(s) for later focusing.
+
+On PEARL the following parameters are required when executing *create_vanadium*:
+
+- :ref:`calibration_mapping_file_pearl_isis-powder-diffraction-ref`
+- :ref:`do_absorb_corrections_pearl_isis-powder-diffraction-ref`
+- :ref:`long_mode_pearl_isis-powder-diffraction-ref`
+- :ref:`run_in_cycle_pearl_isis-powder-diffraction-ref`
+- :ref:`tt_mode_pearl_isis-powder-diffraction-ref`
+
+Example
+=======
+
+.. code-block:: Python
+
+ # Notice how the filename ends with .yaml
+ cal_mapping_file = r"C:\path\to\cal_mapping.yaml"
+
+ pearl_example.create_vanadium(calibration_mapping_file=cal_mapping_file,
+ do_absorb_corrections=True, long_mode=False,
+ run_in_cycle="100", tt_mode="tt88")
+
+.. _focus_pearl_isis-powder-diffraction-ref:
+
+focus
+^^^^^
+The *focus* method processes the user specified run(s). It aligns,
+focuses and optionally applies corrections if the user has requested them.
+
+On PEARL the following parameters are required when executing *focus*:
+
+- :ref:`calibration_mapping_file_pearl_isis-powder-diffraction-ref`
+- :ref:`focus_mode_pearl_isis-powder-diffraction-ref`
+- :ref:`long_mode_pearl_isis-powder-diffraction-ref`
+- :ref:`perform_attenuation_pearl_isis-powder-diffraction-ref`
+- :ref:`run_number_pearl_isis-powder-diffraction-ref`
+- :ref:`tt_mode_pearl_isis-powder-diffraction-ref`
+- :ref:`vanadium_normalisation_pearl_isis-powder-diffraction-ref`
+
+
+The following parameter is required if
+:ref:`perform_attenuation_pearl_isis-powder-diffraction-ref` is set to **True**
+
+- :ref:`attenuation_file_path_pearl_isis-powder-diffraction-ref`
+
+The following parameter may also be optionally set:
+
+- :ref:`file_ext_pearl_isis-powder-diffraction-ref`
+
+Example
+=======
+
+.. code-block:: Python
+
+ # Notice how the filename ends with .yaml
+ cal_mapping_file = r"C:\path\to\cal_mapping.yaml"
+
+ attenuation_path = r"C:\path\to\attenuation_file"
+
+ pearl_example.focus(calibration_mapping_file=cal_mapping_file,
+ focus_mode="all", long_mode=True,
+ perform_attenuation=True,
+ attenuation_file_path=attenuation_path,
+ run_number="100-110", tt_mode="tt88",
+ vanadium_normalisation=True)
+
+.. _calibration_mapping_pearl_isis-powder-diffraction-ref:
- 123-130, 135-140:
- label : "10_1"
- vanadium_run_numbers : "123-125"
- empty_run_numbers : "135-137"
- offset_file_name : "offsets_example_10_1.cal"
+Calibration Mapping File
+------------------------
+The calibration mapping file holds the mapping between
+run numbers, current label, offset filename and the empty
+and vanadium numbers.
+
+For more details on the calibration mapping file see:
+:ref:`cycle_mapping_files_isis-powder-diffraction-ref`
- 141-145: ...etc.
+The layout on PEARL should look as follows
+substituting the example values included for appropriate values:
+
+.. code-block:: yaml
-Line 1 is documented here: :ref:`calibration_map_isis-powder-diffraction-ref`
+ 1-100:
+ label: "1_1"
+ offset_file_name: "offset_file.cal"
+ empty_run_numbers: "10"
+ vanadium_run_numbers: "20"
-Lines 2 - 5 can be placed in any order and specifies various properties common to these files.
+Example
+^^^^^^^^
+.. code-block:: yaml
-- Line 2 specifically holds the label which is used in the calibration and output directories.
-- Line 3 is the vanadium run numbers to use when creating a calibration for this label
-- Line 4 holds the instrument empty run numbers
-- Line 5 is the name of the offsets file which will be used whilst aligning detectors. See
- :ref:`pearl_cal_folder_isis-powder-diffraction-ref`
+ 1-100:
+ label: "1_1"
+ offset_file_name: "offset_file.cal"
+ empty_run_numbers: "10"
+ vanadium_run_numbers: "20"
-.. _pearl_focus_mode_isis-powder-diffraction-ref:
+ 101-:
+ label: "1_2"
+ offset_file_name: "offset_file.cal"
+ empty_run_numbers: "110"
+ vanadium_run_numbers: "120"
-Focus Modes
+Parameters
-----------
+The following parameters for PEARL are intended for regular use
+when using the ISIS Powder scripts.
+
+.. _attenuation_file_path_pearl_isis-powder-diffraction-ref:
+
+attenuation_file_path
+^^^^^^^^^^^^^^^^^^^^^
+Required if :ref:`perform_attenuation_pearl_isis-powder-diffraction-ref`
+is set to **True**
+
+The full path to the attenuation file to use within the
+:ref:`focus_pearl_isis-powder-diffraction-ref` method.
+
+The workspace will be attenuated with the specified file
+if the :ref:`focus_mode_pearl_isis-powder-diffraction-ref`
+is set to **all** or **trans**. For more details see
+:ref:`PearlMCAbsorption<algm-PearlMCAbsorption>`
+
+*Note: The path to the file must include the file extension*
+
+Example Input:
+
+.. code-block:: Python
+
+ attenuation_path = r"C:\path\to\attenuation_file.out
+ pearl_example(attenuation_file_path=attenuation_path, ...)
+
+.. _calibration_directory_pearl_isis-powder-diffraction-ref:
+
+calibration_directory
+^^^^^^^^^^^^^^^^^^^^^
+This parameter should be the full path to the calibration folder.
+Within the folder the following should be present:
+
+- Grouping .cal files:
+ - :ref:`tt35_grouping_filename_pearl_isis-powder-diffraction-ref`
+ - :ref:`tt70_grouping_filename_pearl_isis-powder-diffraction-ref`
+ - :ref:`tt80_grouping_filename_pearl_isis-powder-diffraction-ref`
+- Vanadium Absorption File
+ (see: :ref:`vanadium_absorb_filename_pearl_isis-powder-diffraction-ref`)
+- Folder(s) with the label name specified in mapping file (e.g. "1_1")
+ - Inside each folder should be the offset file with name specified in mapping file
+
+The script will also save out vanadium splines into the relevant
+label folder which are subsequently loaded and used within the
+:ref:`focus_pearl_isis-powder-diffraction-ref` method.
+
+Example Input:
+
+.. code-block:: Python
+
+ calibration_dir = r"C:\path\to\calibration_dir"
+ pearl_example = Pearl(calibration_directory=calibration_dir, ...)
+
+.. _calibration_mapping_file_pearl_isis-powder-diffraction-ref:
+
+calibration_mapping_file
+^^^^^^^^^^^^^^^^^^^^^^^^
+This parameter gives the full path to the YAML file containing the
+calibration mapping. For more details on this file see:
+:ref:`calibration_mapping_pearl-isis-powder-ref`
+
+*Note: This should be the full path to the file including extension*
+
+Example Input:
+
+.. code-block:: Python
+
+ # Notice the filename always ends in .yaml
+ cal_mapping_file = r"C:\path\to\file\calibration_mapping.yaml"
+ pearl_example = Pearl(calibration_mapping_file=cal_mapping_file, ...)
+
+.. _config_file_pearl_isis-powder-diffraction-ref:
+
+config_file
+^^^^^^^^^^^
+The full path to the YAML configuration file. This file is
+described in detail here: :ref:`configuration_files_isis-powder-diffraction-ref`
+It is recommended to set this parameter at object creation instead
+of on a method as it will warn if any parameters are overridden
+in the scripting window.
+
+*Note: This should be the full path to the file including extension*
+
+Example Input:
+
+.. code-block:: Python
+
+ # Notice the filename always ends in .yaml
+ configuration_file = r"C:\path\to\file\configuration.yaml"
+ pearl_example = Pearl(config_file=configuration_file, ...)
+
+.. _do_absorb_corrections_pearl_isis-powder-diffraction-ref:
+
+do_absorb_corrections
+^^^^^^^^^^^^^^^^^^^^^
+Indicates whether to perform vanadium absorption corrections
+when calling :ref:`create_vanadium_pearl_isis-powder-diffraction-ref`.
+If set to True the vanadium absorption file
+(described here: :ref:`vanadium_absorb_filename_pearl_isis-powder-diffraction-ref`)
+will be loaded and the vanadium sample will be divided by the pre-calculated
+absorption corrections.
+
+Accepted values are: **True** or **False**
+
+Example Input:
+
+.. code-block:: Python
+
+ pearl_example.create_vanadium(do_absorb_corrections=True, ...)
+
+.. _file_ext_pearl_isis-powder-diffraction-ref:
+
+file_ext
+^^^^^^^^
+*Optional*
+
+Specifies a file extension to use when using the
+:ref:`focus_pearl_isis-powder-diffraction-ref` method.
+
+This should be used to process partial runs. When
+processing full runs (i.e. completed runs) it should not
+be specified as Mantid will automatically determine the
+best extension to use.
+
+*Note: A leading dot (.) is not required but
+is preferred for readability*
+
+Example Input:
+
+.. code-block:: Python
+
+ pearl_example.focus(file_ext=".s01", ...)
+
+.. _focus_mode_pearl_isis-powder-diffraction-ref:
+
+focus_mode
+^^^^^^^^^^
+Determines how the banks are grouped when using the
+:ref:`focus_pearl_isis-powder-diffraction-ref` method.
+Each mode is further described below.
+
+Accepted values are: **All**, **Groups**, **Mods** and **Trans**
All
-^^^
-In `all` mode banks 1-9 (inclusive) are summed into a single spectra then scaled
-down by 1/9. The workspace is then attenuated if the correction is on. Workspaces
-10-14 are left as separate workspaces with appropriate names.
+====
+In all mode banks 1-9 (inclusive) are summed into a single spectra
+then scaled down to 1/9 of their original values.
+
+The workspace is also attenuated if
+:ref:`perform_attenuation_pearl_isis-powder-diffraction-ref`
+is set to **True**.
+
+Workspaces containing banks 10-14 are left as
+separate workspaces with appropriate names.
Groups
-^^^^^^
-In `groups` mode banks 1+2+3, 4+5+6, 7+8+9 are summed into three (3) separate
-workspaces then scaled down by 1/3. The workspaces containing banks 4-9 (inclusive)
-are then added into a separate workspace and scaled down by 1/2. Banks 10-14
-are left as separate workspaces with appropriate names.
+======
+In groups mode banks 1+2+3, 4+5+6, 7+8+9 are summed into three (3)
+separate workspaces. Each workspace is scaled down to a 1/3 of original scale.
+
+The workspaces containing banks 4-9 (inclusive) are then added
+into a separate workspace and scaled down to 1/2 original scale.
+
+Banks 10-14 are left as separate workspaces with appropriate names.
Trans
-^^^^^
-In `trans` mode banks 1-9 (inclusive) are summed into a single spectra then scaled
-down by 1/9. The workspace is then attenuated if the correction is on. The individual
-banks 1-9 (inclusive) are also output as individual workspaces with appropriate names.
+======
+In trans mode banks 1-9 (inclusive) are summed into a single spectra
+then scaled down to 1/9 original scale.
+
+The workspace is also attenuated if
+:ref:`perform_attenuation_pearl_isis-powder-diffraction-ref`
+is set to **True**.
+
+All banks are also output as individual workspaces with appropriate names
+with no additional processing applied.
Mods
-^^^^
-In `mods` mode each bank is left as an individual workspace with an appropriate
-name. No additional processing is performed.
+====
+In mods mode every bank is left as individual workspaces with
+appropriate names. No additional processing is performed.
-Basic Script Parameters
------------------------
-For background on script parameters and how they are evaluated see:
-:ref:`script_param_overview_isis-powder-diffraction-ref`
+Example Input:
-TODO talk about defaults?
+.. code-block:: Python
-- `attenuation_file_path` - The full path to the attenuation file. This is used with
- the algorithm :ref:`PearlMCAbsorption<algm-PearlMCAbsorption>`
+ pearl_example.focus(focus_mode="all", ...)
-- `calibration_directory` - This folder must contain various files such as
- detector offsets and detector grouping information. Additionally calibrated
- vanadium data will be stored here for later data processing.
+.. _long_mode_pearl_isis-powder-diffraction-ref:
-- `config_file` - The full path to the YAML configuration file. This is described
- in more detail here: :ref:`yaml_basic_conf_isis-powder-diffraction-ref`
+long_mode
+^^^^^^^^^
+Determines the TOF window to process data in. This
+affects both the :ref:`create_vanadium_pearl_isis-powder-diffraction-ref`
+and :ref:`focus_pearl_isis-powder-diffraction-ref` methods.
-- `calbiration_config_path` - The full path to the calibration configuration file
- a description of the file is here: :ref:`pearl_cal_map_isis-powder-diffraction-ref`
+As this affects the vanadium spline used the
+:ref:`create_vanadium_pearl_isis-powder-diffraction-ref` method
+will need to be called once for each *long_mode* value (**True** and/or **False**)
+if the user intends to use a different mode. This will create
+a spline for the relevant mode which is automatically used when focusing.
-- `do_absorb_corrections` - Used during a vanadium calibration and focusing:
- In a vanadium calibration if set to true the calibration will correct for
- absorption and scattering in a cylindrical sample.
+When *long_mode* is **False** the TOF window processed is
+between 0-20,000 μs
- During focusing if set to true this will load a calibration which
- has had the absorption corrections performed, if false it will use a calibration
- where the absorption corrections have not been performed.
+When *long_mode* is **True** the TOF window processed is
+between 0-40,000 μs
-- `focus_mode` - More information found here: :ref:`pearl_focus_mode_isis-powder-diffraction-ref` .
- Acceptable options: `all`, `groups`, `trans` and `mods`.
+This also affects the :ref:`advanced_parameters_pearl_isis-powder-diffraction-ref`
+used. More detail can be found for each individual parameter
+listed under the advanced parameters section.
-- `long_mode` - Processes data in 20,000-40,000μs instead of the usual 0-20,000μs window.
+Accepted values are: **True** or **False**
-- `output_directory` - This folder is where all processed data will be saved.
+Example Input:
-- `perform_attenuation` - If set to true uses the user specified attenuation file
- (see `attenuation_file_name`) and applies the correction.
+.. code-block:: Python
-- `run_in_cycle` - Only used during vanadium calibration. The run specified
- here is used with the calibration mapping file see:
- :ref:`pearl_cal_map_isis-powder-diffraction-ref` to determine the current cycle
- and the vanadium/empty run numbers for the subsequent processing.
+ pearl_example.create_vanadium(long_mode=False, ...)
+ # Or
+ pearl_example.focus(long_mode=True, ...)
-- `run_number` - Used during focusing a single run or range of runs can be specified
- here. This range is inclusive e.g. 10-12 will be runs 10,11,12.
- These runs will be first summed together before any processing is performed
- on them if there are multiple runs specified.
-- `tt_mode` - Specifies the detectors to be considered.
- Acceptable options: `tt35`, `tt70`, `tt88`, `all` (when creating vanadium).
+.. _output_directory_pearl_isis-powder-diffraction-ref:
-- `user_name` - Used to create a folder with that name in the output directory
+output_directory
+^^^^^^^^^^^^^^^^
+Specifies the path to the output directory to save resulting files
+into. The script will automatically create a folder
+with the label determined from the
+:ref:`calibration_mapping_file_pearl_isis-powder-diffraction-ref`
+and within that create another folder for the current
+:ref:`user_name_pearl_isis-powder-diffraction-ref`.
-- `vanadium_normalisation` - If set to true divides the sample by the vanadium
- vanadium calibration during the focusing step.
+Within this folder processed data will be saved out in
+several formats.
-.. _pearl_adv_script_params_isis-powder-diffraction-ref:
+Example Input:
-Advanced Script Parameters
---------------------------
-- `monitor_lambda_crop_range` - The range in dSpacing to crop a monitor workspace
- to whilst calculating the current normalisation. This is should be stored as a tuple
- of both values. This is used with `long_mode` so there is a set of values for
- `long_mode` off and on.
+.. code-block:: Python
-- `monitor_integration_range` - The maximum and minimum contribution a bin can provide
- whilst integrating the monitor spectra. Any values that fall outside of this range
- are not added in. This should be stored as a tuple of both values. This is
- used with `long_mode` so there is a set of values for `long_mode` off and on.
+ output_dir = r"C:\path\to\output_dir"
+ pearl_example = Pearl(output_directory=output_dir, ...)
-- `monitor_spectrum_number` - The spectrum number of the current monitor.
+.. _perform_attenuation_pearl_isis-powder-diffraction-ref:
-- `monitor_spline_coefficient` - The number of b-spline coefficients to use whilst
- taking a background spline of the monitor.
+perform_attenuation
+^^^^^^^^^^^^^^^^^^^^
+Indicates whether to perform attenuation corrections
+whilst running :ref:`focus_pearl_isis-powder-diffraction-ref`.
+For more details of the corrections performed see:
+:ref:`PearlMCAbsorption<algm-PearlMCAbsorption>`
-- `raw_data_tof_cropping` - Stores the window in TOF which the data should be
- cropped down to before any processing. This is used with `long_mode` so there
- is a set of values for `long_mode` off and on. Each should be a tuple of the minimum
- and maximum time of flight. It should also be greater than `vanadium_tof_cropping`
- and `tof_cropping_values`
+If this is set to **True**
+:ref:`attenuation_file_path_pearl_isis-powder-diffraction-ref`
+must be set too.
-- `spline_coefficient` - The number of b-spline coefficients to use whilst taking
- a background spline of the focused vanadium data.
+*Note: This correction will only be performed if
+*focus_mode* is in **All* or **Trans**. See:
+:ref:`focus_mode_pearl_isis-powder-diffraction-ref`
+for more details.*
-- `tof_cropping_values` - Stores per bank the TOF which the focused data should
- be cropped to. This does not affect the `vanadium_tof_cropping` which must be larger
- than the interval between the smallest and largest cropping values. This is
- stored as a list of tuple pairs with one tuple per bank. This is used with `long_mode`
- so there is a set of values for `long_mode` off and on.
+Accepted values are: **True** or **False**
-- `tt_88_grouping` - The file name for the `.cal` file with grouping details for
- the instrument in `TT88` mode. This must be located in the top level directory
- of the calibration folder. More information can be found
- here: :ref:`pearl_cal_folder_isis-powder-diffraction-ref`
+Example Input:
-- `tt_70_grouping` - The file name for the `.cal` file with grouping details for
- the instrument in `TT70` mode. See `tt_88_grouping` for more details.
+.. code-block:: Python
-- `tt_35_grouping` - The file name for the `.cal` file with grouping details for
- the instrument in `TT35` mode. See `tt_88_grouping` for more details.
+ pearl_example.focus(perform_attenuation=True, ...)
-- `vanadium_absorb_file` - The file name for the vanadium absorption corrections.
- This must be located in the top level directory of the calibration folder.
- More information here: :ref:`pearl_cal_folder_isis-powder-diffraction-ref`
+.. _run_in_cycle_pearl_isis-powder-diffraction-ref:
-- `vanadium_tof_cropping` - The range in TOF to crop the calibrated vanadium
- file to after focusing. This must be less than `raw_data_tof_cropping` and
- larger than `tof_cropping_values`. The cropping is applied before a spline is
- taken of the vanadium sample.
+run_in_cycle
+^^^^^^^^^^^^
+Indicates a run from the current cycle to use when calling
+:ref:`create_vanadium_pearl_isis-powder-diffraction-ref`.
+This does not have the be the first run of the cycle or
+the run number corresponding to the vanadium. However it
+must be in the correct cycle according to the
+:ref:`calibration_mapping_pearl-isis-powder-ref`.
-.. _pearl_config_scripts_isis-powder-diffraction-ref:
+Example Input:
-Configuring the scripts
-------------------------
-The scripts are object oriented for more information on this concept see
-:ref:`script_param_overview_isis-powder-diffraction-ref`
+.. code-block:: Python
+
+ # In this example assume we mean a cycle with run numbers 100-200
+ pearl_example.create_vanadium(run_in_cycle=100, ...)
+
+.. _run_number_pearl_isis-powder-diffraction-ref:
+
+run_number
+^^^^^^^^^^
+Specifies the run number(s) to process when calling the
+:ref:`focus_pearl_isis-powder-diffraction-ref` method.
+
+This parameter accepts a single value or a range
+of values with the following syntax:
+
+**-** : Indicates a range of runs inclusive
+(e.g. *1-10* would process 1, 2, 3....8, 9, 10)
+
+**,** : Indicates a gap between runs
+(e.g. *1, 3, 5, 7* would process run numbers 1, 3, 5, 7)
+
+These can be combined like so:
+*1-3, 5, 8-10* would process run numbers 1, 2, 3, 5, 8, 9, 10.
+
+On Pearl any ranges of runs indicates the runs will be summed
+before any additional processing takes place. For example
+a run input of *1, 3, 5* will sum runs 1, 3 and 5 together
+before proceeding to focus them.
+
+Example Input:
+
+.. code-block:: Python
+
+ # Sum and process run numbers 1, 3, 5, 6, 7
+ pearl_example.focus(run_number="1, 3, 5-7", ...)
+ # Or just a single run
+ pearl_example.focus(run_number=100, ...)
+
+.. _tt_mode_pearl_isis-powder-diffraction-ref:
+
+tt_mode
+^^^^^^^^
+Specifies the detectors to be considered from the
+grouping files. This is used in the
+:ref:`create_vanadium_pearl_isis-powder-diffraction-ref` and
+:ref:`focus_pearl_isis-powder-diffraction-ref` methods.
+
+For more details of the grouping file which is selected between
+see the following:
+
+- :ref:`tt35_grouping_filename_pearl_isis-powder-diffraction-ref`
+- :ref:`tt70_grouping_filename_pearl_isis-powder-diffraction-ref`
+- :ref:`tt88_grouping_filename_pearl_isis-powder-diffraction-ref`
+
+Accepted values are: **tt35**, **tt70** and **tt80**
+
+When calling :ref:`create_vanadium_pearl_isis-powder-diffraction-ref`
+**all** can be used to implicitly process all of the supported
+values indicated above.
+
+Example Input:
+
+.. code-block:: Python
+
+ pearl_example.create_vanadium(tt_mode="all", ...)
+ # Or
+ pearl_example.focus(tt_mode="tt35", ...)
+
+.. _user_name_pearl_isis-powder-diffraction-ref:
+
+user_name
+^^^^^^^^^
+Specifies the name of the current user when creating a
+new PEARL object. This is only used when saving data to
+sort data into respective user folders.
+See :ref:`output_directory_pearl_isis-powder-diffraction-ref`
+for more details.
+
+Example Input:
+
+.. code-block:: Python
+
+ pearl_example = Pearl(user_name="Mantid", ...)
+
+.. _vanadium_normalisation_pearl_isis-powder-diffraction-ref:
+
+vanadium_normalisation
+^^^^^^^^^^^^^^^^^^^^^^
+Indicates whether to divide the focused workspace within
+:ref:`focus_pearl_isis-powder-diffraction-ref` mode with a
+previously generated vanadium spline.
+
+This requires a vanadium to have been previously created
+with the :ref:`create_vanadium_pearl_isis-powder-diffraction-ref`
+method
+
+Accepted values are: **True** or **False**
+
+Example Input:
+
+.. code-block:: Python
+
+ pearl_example.focus(vanadium_normalisation=True, ...)
+
+.. _advanced_parameters_pearl_isis-powder-diffraction-ref:
-The following parameters must be included in the object construction step.
-They can either be manually specified or set in the configuration file:
+Advanced Parameters
+--------------------
+.. warning:: These values are not intended to be changed and should
+ reflect optimal defaults for the instrument. For more
+ details please read:
+ :ref:`instrument_advanced_properties_isis-powder-diffraction-ref`
+
+ This section is mainly intended to act as reference of the
+ current settings distributed with Mantid
-- calibration_directory
-- output_directory
-- user_name
+All values changed in the advanced configuration file
+requires the user to restart Mantid for the new values to take effect.
+Please read :ref:`instrument_advanced_properties_isis-powder-diffraction-ref`
+before proceeding to change values within the advanced configuration file.
-First the relevant scripts must be imported with the instrument specific customisations
-as follows:
+.. _focused_cropping_values_pearl_isis-powder-diffraction-ref:
-.. code-block:: python
+focused_cropping_values
+^^^^^^^^^^^^^^^^^^^^^^^
- # First import the relevant scripts for PEARL
- from isis_powder.pearl import Pearl
+.. _monitor_lambda_crop_range_pearl_isis-powder-diffraction-ref:
-The scripts can be setup in 3 ways:
+monitor_lambda_crop_range
+^^^^^^^^^^^^^^^^^^^^^^^^^
-1. Explicitly setting parameters for example :- user_name, calibration_directory
-and output_directory...etc.:
+.. _monitor_integration_range_pearl_isis-powder-diffraction-ref:
-.. code-block:: python
+monitor_integration_range
+^^^^^^^^^^^^^^^^^^^^^^^^^
- pearl_manually_specified = Pearl(user_name="Mantid",
- calibration_directory="<Path to calibration folder>",
- output_directory="<Path to output folder>", ...etc.)
+.. _monitor_spectrum_number_pearl_isis-powder-diffraction-ref:
-2. Using user configuration files see :ref:`yaml_basic_conf_isis-powder-diffraction-ref`.
- This eliminates having to specify several common parameters
+monitor_spectrum_number
+^^^^^^^^^^^^^^^^^^^^^^^
-.. code-block:: python
+.. _monitor_spline_coefficient_pearl_isis-powder-diffraction-ref:
- config_file_path = <path to your configuration file>
- pearl_object_config_file = Pearl(user_name="Mantid2", config_file=config_file_path)
+monitor_spline_coefficient
+^^^^^^^^^^^^^^^^^^^^^^^^^^
-3. Using a combination of both, any parameter can be overridden from the
-configuration file without changing it:
+.. _raw_data_tof_cropping_pearl_isis-powder-diffraction-ref:
-.. code-block:: python
+raw_data_tof_cropping
+^^^^^^^^^^^^^^^^^^^^^
- # This will use "My custom location" instead of the location set in the configuration file
- pearl_object_override = Pearl(user_name="Mantid3", config_file=config_file_path,
- output_directory="My custom location")
+.. _spline_coefficient_pearl_isis-powder-diffraction-ref:
-Each object remembers its own properties - changing properties on another
-object will not affect others: In the above examples `pearl_object_override`
-will save in *"My custom location"* whilst `pearl_manually_specified` will have user
-name *"Mantid"* and save in *<Path to output folder>*.
+spline_coefficient
+^^^^^^^^^^^^^^^^^^
-Vanadium Calibration
----------------------
-Following on from the examples configuring the scripts (see:
-:ref:`pearl_config_scripts_isis-powder-diffraction-ref`) we can run a vanadium
-calibration with the `create_vanadium` method.
+.. _tt35_grouping_filename_pearl_isis-powder-diffraction-ref:
-TODO the following parameters are needed...
+tt35_grouping_filename
+^^^^^^^^^^^^^^^^^^^^^^
-.. code-block:: python
+.. _tt70_grouping_filename_pearl_isis-powder-diffraction-ref:
- # Lets use the "pearl_object_override" which stores in "My custom location"
- # from the previous examples
- pearl_object_override.create_vanadium(run_in_range=12345,
- do_absorb_corrections=True
- long_mode=False, tt_mode=tt88)
+tt70_grouping_filename
+^^^^^^^^^^^^^^^^^^^^^^
-This will generate a calibration for the specified vanadium and empty runs
-specified in the calibration mapping file (see: :ref:`pearl_cal_map_isis-powder-diffraction-ref`)
-and store it in the calibration folder - more details here: :ref:`pearl_cal_folder_isis-powder-diffraction-ref`
+.. _tt88_grouping_filename_pearl_isis-powder-diffraction-ref:
-*Note: This only needs to be completed once per cycle as the splined vanadium workspace will be
-automatically loaded and used for future focusing where that vanadium is used.
-This means that it should not be part of your focusing scripts as it will recalculate the same
-values every time it is ran.*
+tt88_grouping_filename
+^^^^^^^^^^^^^^^^^^^^^^
-Focusing
-----------
-Using the examples from the configured scripts (see: :ref:`pearl_config_scripts_isis-powder-diffraction-ref`)
-we can run focusing with the `focus` method:
+.. _vanadium_absorb_filename_pearl_isis-powder-diffraction-ref:
-TODO list the parameters which are mandatory
+vanadium_absorb_filename
+^^^^^^^^^^^^^^^^^^^^^^^^
-.. code-block:: python
+.. _vanadium_tof_cropping_pearl_isis-powder-diffraction-ref:
- # Using pearl_object_config_file which was using a configuration file
- # We will focus runs 10000-10010 which sums up the runs inclusively
- pearl_object_config_file.focus(run_number="10000-10010")
+vanadium_tof_cropping
+^^^^^^^^^^^^^^^^^^^^^
\ No newline at end of file
diff --git a/docs/source/api/python/techniques/ISISPowder-Polaris-v1.rst b/docs/source/api/python/techniques/ISISPowder-Polaris-v1.rst
index d1e7bc7020c..1e05840c71f 100644
--- a/docs/source/api/python/techniques/ISISPowder-Polaris-v1.rst
+++ b/docs/source/api/python/techniques/ISISPowder-Polaris-v1.rst
@@ -124,7 +124,6 @@ set then the following parameter is also required:
- :ref:`sample_empty_scale_polaris_isis-powder-diffraction-ref`
-
Example
=======
@@ -387,8 +386,6 @@ the run number corresponding to the vanadium. However it
must be in the correct cycle according to the
:ref:`calibration_mapping_polaris-isis-powder-ref`.
-Additionally the run
-
Example Input:
.. code-block:: Python
@@ -443,6 +440,27 @@ Example Input:
# Or
polaris_example.focus(multiple_scattering=False, ...)
+.. _output_directory_polaris_isis-powder-diffraction-ref:
+
+output_directory
+^^^^^^^^^^^^^^^^
+Specifies the path to the output directory to save resulting files
+into. The script will automatically create a folder
+with the label determined from the
+:ref:`calibration_mapping_file_polaris_isis-powder-diffraction-ref`
+and within that create another folder for the current
+:ref:`user_name_polaris_isis-powder-diffraction-ref`.
+
+Within this folder processed data will be saved out in
+several formats.
+
+Example Input:
+
+.. code-block:: Python
+
+ output_dir = r"C:\path\to\output_dir"
+ polaris_example = Polaris(output_directory=output_dir, ...)
+
.. _run_number_polaris_isis_powder-diffraction-ref:
run_number
@@ -524,27 +542,6 @@ Example Input:
# Scale sample empty to 90% of original
polaris_example.focus(sample_empty_scale=0.9, ...)
-.. _output_directory_polaris_isis-powder-diffraction-ref:
-
-output_directory
-^^^^^^^^^^^^^^^^
-Specifies the path to the output directory to save resulting files
-into. The script will automatically create a folder
-with the label determined from the
-:ref:`calibration_mapping_file_polaris_isis-powder-diffraction-ref`
-and within that create another folder for the current
-:ref:`user_name_polaris_isis-powder-diffraction-ref`.
-
-Within this folder processed data will be saved out in
-several formats.
-
-Example Input:
-
-.. code-block:: Python
-
- output_dir = r"C:\path\to\output_dir"
- polaris_example = Polaris(output_directory=output_dir, ...)
-
.. _user_name_polaris_isis-powder-diffraction-ref:
user_name
diff --git a/scripts/Diffraction/isis_powder/pearl.py b/scripts/Diffraction/isis_powder/pearl.py
index 19ded99dbae..03570e5e1c5 100644
--- a/scripts/Diffraction/isis_powder/pearl.py
+++ b/scripts/Diffraction/isis_powder/pearl.py
@@ -63,7 +63,7 @@ class Pearl(AbstractInst):
def _generate_output_file_name(self, run_number_string):
inst = self._inst_settings
- return pearl_algs.generate_out_name(run_number_string=run_number_string, absorb_on=inst.absorb_corrections,
+ return pearl_algs.generate_out_name(run_number_string=run_number_string,
long_mode_on=inst.long_mode, tt_mode=inst.tt_mode)
def _attenuate_workspace(self, input_workspace):
diff --git a/scripts/Diffraction/isis_powder/pearl_routines/pearl_advanced_config.py b/scripts/Diffraction/isis_powder/pearl_routines/pearl_advanced_config.py
index 1776a4657fc..51811853240 100644
--- a/scripts/Diffraction/isis_powder/pearl_routines/pearl_advanced_config.py
+++ b/scripts/Diffraction/isis_powder/pearl_routines/pearl_advanced_config.py
@@ -6,10 +6,10 @@ general_params = {
"spline_coefficient": 60,
"file_names": {
- "vanadium_absorb_file": "pearl_absorp_sphere_10mm_newinst2_long.nxs",
- "tt88_grouping": "pearl_group_12_1_TT88.cal",
- "tt70_grouping": "pearl_group_12_1_TT70.cal",
- "tt35_grouping": "pearl_group_12_1_TT35.cal"
+ "vanadium_absorb_filename": "pearl_absorp_sphere_10mm_newinst2_long.nxs",
+ "tt88_grouping_filename": "pearl_group_12_1_TT88.cal",
+ "tt70_grouping_filename": "pearl_group_12_1_TT70.cal",
+ "tt35_grouping_filename": "pearl_group_12_1_TT35.cal"
},
}
@@ -19,7 +19,7 @@ long_mode_off_params = {
# This needs to be greater than the bank TOF cropping values or you will get data that divides to 0/inf
"raw_data_tof_cropping": (0, 19995),
"vanadium_tof_cropping": (1400, 19990),
- "tof_cropping_ranges": [
+ "focused_cropping_values": [
(1500, 19900), # Bank 1
(1500, 19900), # Bank 2
(1500, 19900), # Bank 3
@@ -44,7 +44,7 @@ long_mode_on_params = {
# you will get data that divides to 0 or inf
"raw_data_tof_cropping": (20280, 39995),
"vanadium_tof_cropping": (20295, 39993),
- "tof_cropping_ranges": [
+ "focused_cropping_values": [
(20300, 39990), # Bank 1
(20300, 39990), # Bank 2
(20300, 39990), # Bank 3
@@ -66,17 +66,17 @@ long_mode_on_params = {
variable_help = {
"long_mode_<on/off>_params": {
"file_names": {
- "vanadium_absorb_file_name": "Takes the name of the calculated vanadium absorption corrections. This file "
- " must be located in the top level of the calibration folder",
+ "vanadium_absorb_filename": "Takes the name of the calculated vanadium absorption corrections. This file "
+ " must be located in the top level of the calibration folder",
- "tt88_grouping_name": "The name of the .cal file that defines the grouping of detectors in banks for TT88. "
- "This file must be located in the top level of the calibration folder.",
+ "tt88_grouping_filename": "The name of the .cal file that defines the grouping of detectors in banks for "
+ "TT88. This file must be located in the top level of the calibration folder.",
- "tt70_grouping_name": "The name of the .cal file that defines the grouping of detectors in banks for TT70. "
- "This file must be located in the top level of the calibration folder.",
+ "tt70_grouping_filename": "The name of the .cal file that defines the grouping of detectors in banks for "
+ "TT70. This file must be located in the top level of the calibration folder.",
- "tt35_grouping_name": "The name of the .cal file that defines the grouping of detectors in banks for TT35. "
- "This file must be located in the top level of the calibration folder.",
+ "tt35_grouping_filename": "The name of the .cal file that defines the grouping of detectors in banks for "
+ "TT35. This file must be located in the top level of the calibration folder.",
},
"monitor_lambda_crop_range": "The range in wavelength to crop a monitor workspace to before calculating "
@@ -86,9 +86,9 @@ variable_help = {
"raw_data_tof_cropping": "The crop values for to apply when loading raw data. This step is applied before any "
"processing takes place. This is to crop from 40,000 microseconds in the "
"raw data to 20,000 microseconds worth of data",
- "tof_cropping_ranges": "These values are used to determine the TOF range to crop a focused (not Vanadium "
- "calibration) workspace to. These are applied on a bank by bank basis. They must be "
- "less than the values specified for raw_data_tof_cropping."
+ "focused_cropping_values": "These values are used to determine the TOF range to crop a focused (not Vanadium "
+ "calibration) workspace to. These are applied on a bank by bank basis. They must "
+ "be less than the values specified for raw_data_tof_cropping."
},
"general_params": {
diff --git a/scripts/Diffraction/isis_powder/pearl_routines/pearl_algs.py b/scripts/Diffraction/isis_powder/pearl_routines/pearl_algs.py
index 2f102fa336c..f11d52d65c3 100644
--- a/scripts/Diffraction/isis_powder/pearl_routines/pearl_algs.py
+++ b/scripts/Diffraction/isis_powder/pearl_routines/pearl_algs.py
@@ -40,11 +40,10 @@ def apply_vanadium_absorb_corrections(van_ws, run_details):
return van_ws
-def generate_out_name(run_number_string, absorb_on, long_mode_on, tt_mode):
+def generate_out_name(run_number_string, long_mode_on, tt_mode):
output_name = "PRL" + str(run_number_string)
# Append each mode of operation
output_name += "_" + str(tt_mode)
- output_name += "_absorb" if absorb_on else ""
output_name += "_long" if long_mode_on else ""
return output_name
@@ -70,8 +69,6 @@ def generate_vanadium_absorb_corrections(van_ws):
def get_run_details(run_number_string, inst_settings, is_vanadium_run):
splined_name_list = ["_tt-" + inst_settings.tt_mode]
- if inst_settings.absorb_corrections:
- splined_name_list.append("_abs")
if inst_settings.long_mode:
splined_name_list.append("_long")
diff --git a/scripts/Diffraction/isis_powder/pearl_routines/pearl_param_mapping.py b/scripts/Diffraction/isis_powder/pearl_routines/pearl_param_mapping.py
index f2e2b408a32..edbaf72dc27 100644
--- a/scripts/Diffraction/isis_powder/pearl_routines/pearl_param_mapping.py
+++ b/scripts/Diffraction/isis_powder/pearl_routines/pearl_param_mapping.py
@@ -8,10 +8,11 @@ attr_mapping = \
[
ParamMapEntry(ext_name="attenuation_file_path", int_name="attenuation_file_path"),
ParamMapEntry(ext_name="config_file", int_name="config_file_name"),
- ParamMapEntry(ext_name="calibration_config_path", int_name="cal_mapping_path"),
+ ParamMapEntry(ext_name="calibration_mapping_file", int_name="cal_mapping_path"),
ParamMapEntry(ext_name="calibration_directory", int_name="calibration_dir"),
ParamMapEntry(ext_name="do_absorb_corrections", int_name="absorb_corrections"),
ParamMapEntry(ext_name="file_ext", int_name="file_extension", optional=True),
+ ParamMapEntry(ext_name="focused_cropping_values", int_name="tof_cropping_values"),
ParamMapEntry(ext_name="focus_mode", int_name="focus_mode", enum_class=PEARL_FOCUS_MODES),
ParamMapEntry(ext_name="long_mode", int_name="long_mode"),
ParamMapEntry(ext_name="monitor_lambda_crop_range", int_name="monitor_lambda"),
@@ -24,13 +25,12 @@ attr_mapping = \
ParamMapEntry(ext_name="run_in_cycle", int_name="run_in_range"),
ParamMapEntry(ext_name="run_number", int_name="run_number"),
ParamMapEntry(ext_name="spline_coefficient", int_name="spline_coefficient"),
- ParamMapEntry(ext_name="tof_cropping_ranges", int_name="tof_cropping_values"),
- ParamMapEntry(ext_name="tt88_grouping", int_name="tt88_grouping"),
- ParamMapEntry(ext_name="tt70_grouping", int_name="tt70_grouping"),
- ParamMapEntry(ext_name="tt35_grouping", int_name="tt35_grouping"),
+ ParamMapEntry(ext_name="tt88_grouping_filename", int_name="tt88_grouping"),
+ ParamMapEntry(ext_name="tt70_grouping_filename", int_name="tt70_grouping"),
+ ParamMapEntry(ext_name="tt35_grouping_filename", int_name="tt35_grouping"),
ParamMapEntry(ext_name="tt_mode", int_name="tt_mode", enum_class=PEARL_TT_MODES),
ParamMapEntry(ext_name="user_name", int_name="user_name"),
- ParamMapEntry(ext_name="vanadium_absorb_file", int_name="van_absorb_file"),
+ ParamMapEntry(ext_name="vanadium_absorb_filename", int_name="van_absorb_file"),
ParamMapEntry(ext_name="vanadium_tof_cropping", int_name="van_tof_cropping"),
ParamMapEntry(ext_name="vanadium_normalisation", int_name="van_norm")
]
--
GitLab