From 0d2783cd2a70ff637a3dd0a48886df18e8e406da Mon Sep 17 00:00:00 2001
From: David Fairbrother <DavidFair@users.noreply.github.com>
Date: Tue, 10 Jan 2017 18:54:02 +0000
Subject: [PATCH] Re #18108 Added docs on PEARL parameters
---
.../api/python/techniques/ISISPowder-v1.rst | 209 ++++++++++++++++++
.../pearl_routines/pearl_advanced_config.py | 6 +-
scripts/Diffraction/isis_powder/polaris.py | 3 +-
.../polaris_routines/polaris_param_mapping.py | 1 -
.../routines/InstrumentSettings.py | 4 +
5 files changed, 218 insertions(+), 5 deletions(-)
create mode 100644 docs/source/api/python/techniques/ISISPowder-v1.rst
diff --git a/docs/source/api/python/techniques/ISISPowder-v1.rst b/docs/source/api/python/techniques/ISISPowder-v1.rst
new file mode 100644
index 00000000000..0bfbd98a8ac
--- /dev/null
+++ b/docs/source/api/python/techniques/ISISPowder-v1.rst
@@ -0,0 +1,209 @@
+.. _isis-powder-diffraction-ref
+
+================================
+ISIS Powder Diffraction Scripts
+================================
+
+.. 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.
+
+.. contents:: Table of Contents
+ :local:
+
+Overview
+--------
+These objective of these scripts are to combine the work-flows of several powder
+diffraction instruments into a single collection of scripts whilst catering to
+their individual requirements. At the most fundamental level it provides the
+functionality to calculate and apply vanadium calibrations and subsequently
+apply these corrections to experimental data.
+
+Data Files Setup
+^^^^^^^^^^^^^^^^^
+Users must setup their input directories so Mantid can find the input files. Instructions
+on completing this are located `here <http://www.mantidproject.org/ManageUserDirectories>`_.
+*Note: Mantid will not search folders recursively each folder must be added*
+
+Additionally *Search Data Archive* can be ticked if the device is located on the ISIS
+network to automatically handle finding the files whilst it is on the network.
+
+.. _yaml_isis-powder-diffraction-ref:
+
+YAML Configuration Files
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+
+PEARL
+-----
+
+.. _pearl_cal_folder_isis-powder-diffraction-ref:
+
+Calibration Folder
+^^^^^^^^^^^^^^^^^^
+TODO talk about structure of calibration folder/required folders and what is put in
+...etc.
+
+.. _pearl_cal_map_isis-powder-diffraction-ref:
+
+Calibration Configuration File
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+TODO talk about the calibration mapping file
+
+.. _pearl_focus_mode_isis-powder-diffraction-ref:
+
+Focus Modes
+^^^^^^^^^^^
+TODO talk about various focus modes
+
+Script configuration parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The following parameters must be included in the object construction step.
+They be either manually specified or set in the configuration file:
+
+ - `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.
+
+ - `user_name` - Used to create a folder with that name in the output directory
+
+ - `output_directory` - This folder is where all processed data will be saved.
+
+Basic Script Parameters
+^^^^^^^^^^^^^^^^^^^^^^^
+The following parameters can be set at any point (e.g. during configuration or
+just before calling a method). If there was previously a value set a notice will appear
+in the output window informing the user of the old and new values.
+
+TODO talk about defaults?
+
+ - `attenuation_file_name` - The attenuation file name, this file must be located in
+ the top level directory of the calibration directory. More information
+ here: :ref:`pearl_cal_folder_isis-powder-diffraction-ref`
+
+ - `config_file` - The full path to the YAML configuration file. This is described
+ in more detail here: :ref:`yaml_isis-powder-diffraction-ref`
+
+ - `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`
+
+ - `do_absorb_corrections` - Used during a vanadium calibration if set to true the
+ calibration will correct for absorption and scattering in a cylindrical sample
+
+ - `focus_mode` - More information found here: :ref:`pearl_focus_mode_isis-powder-diffraction-ref` .
+ Acceptable options: `all`, `groups`, `trans` and `mods`.
+
+ - `long_mode` - Processes data in 20,000-40,000μs instead of the usual 0-20,000μs window.
+
+ - `perform_attenuation` - If set to true uses the user specified attenuation file
+ (see `attenuation_file_name`) and applies the correction.
+
+ - `tt_mode` - Specifies the detectors to be considered whilst focussing.
+ Acceptable options: `tt35`, `tt70`, `tt88`.
+
+ - `vanadium_normalisation` - If set to true divides the sample by the vanadium
+ vanadium calibration during the focusing step.
+
+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.
+
+ - `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.
+
+ - `monitor_spectrum_number` - The spectrum number of the current monitor.
+
+ - `monitor_spline_coefficient` - The number of b-spline coefficients to use whilst
+ taking a background spline of the monitor.
+
+ - `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`
+
+ - `spline_coefficient` - The number of b-spline coefficients to use whilst taking
+ a background spline of the focused vanadium data.
+
+ - `tof_cropping_values` - Stores per bank the TOF which the focussed 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.
+
+ - `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`
+
+ - `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.
+
+ - `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.
+
+ - `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`
+
+ - `vanadium_tof_cropping` - The range in TOF to crop the calibrated vanadium
+ file to after focussing. 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.
+
+
+Configuring the scripts
+^^^^^^^^^^^^^^^^^^^^^^^^
+Code example with comments:
+::
+
+ # First import the relevant scripts for PEARL
+ from isis_powder.pearl import Pearl
+
+The scripts can be setup in 3 ways:
+
+1. Explicitly setting parameters for example :- user_name, calibration_directory
+and output_directory...etc.:
+::
+
+ pearl_manually_specified = Pearl(user_name="Mantid",
+ calibration_directory="<Path to calibration folder>",
+ output_directory="<Path to output folder>", ...etc.)
+
+2. Using user configuration files. This eliminates having to specify several parameters
+::
+
+ config_file_path = <path to your configuration file>
+ pearl_object_config_file = Pearl(user_name="Mantid2", config_file=config_file_path)
+
+3. Using a combination of both, any parameter can be overridden from the
+configuration file without changing it:
+::
+
+ # 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")
+
+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>*.
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
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 1ca341e252c..105ace3b3dd 100644
--- a/scripts/Diffraction/isis_powder/pearl_routines/pearl_advanced_config.py
+++ b/scripts/Diffraction/isis_powder/pearl_routines/pearl_advanced_config.py
@@ -4,15 +4,17 @@ general_params = {
"monitor_spectrum_number": 1,
"monitor_spline_coefficient": 20,
"spline_coefficient": 60
-}
-long_mode_off_params = {
"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"
},
+}
+
+long_mode_off_params = {
+
"monitor_lambda_crop_range": (0.03, 6.00),
"monitor_integration_range": (0.6, 5.0),
diff --git a/scripts/Diffraction/isis_powder/polaris.py b/scripts/Diffraction/isis_powder/polaris.py
index bcfaf8d17a8..cbee58c1d0b 100644
--- a/scripts/Diffraction/isis_powder/polaris.py
+++ b/scripts/Diffraction/isis_powder/polaris.py
@@ -34,14 +34,13 @@ class Polaris(AbstractInst):
def create_calibration_vanadium(self, run_in_range, **kwargs):
self._inst_settings.update_attributes(kwargs=kwargs)
-
run_details = self.get_run_details(run_number_string=int(run_in_range))
run_details.run_number = run_details.vanadium_run_numbers
return self._create_calibration_vanadium(
vanadium_runs=run_details.vanadium_run_numbers, empty_runs=run_details.empty_runs,
do_absorb_corrections=self._inst_settings.do_absorb_corrections,
- gen_absorb_correction=self._inst_settings.gen_absorb_corrections)
+ gen_absorb_correction=None) # TODO POLARIS doesn't need this flag to gen abs. corrections does PEARL?
def get_run_details(self, run_number_string):
input_run_number_list = common.generate_run_numbers(run_number_string=run_number_string)
diff --git a/scripts/Diffraction/isis_powder/polaris_routines/polaris_param_mapping.py b/scripts/Diffraction/isis_powder/polaris_routines/polaris_param_mapping.py
index 93114324423..7f14c85b42b 100644
--- a/scripts/Diffraction/isis_powder/polaris_routines/polaris_param_mapping.py
+++ b/scripts/Diffraction/isis_powder/polaris_routines/polaris_param_mapping.py
@@ -8,7 +8,6 @@ attr_mapping = [("apply_solid_angle", "solid_angle_on"),
("config_file", "config_file"),
("do_van_normalisation", "do_van_normalisation"),
("do_absorb_corrections", "do_absorb_corrections"),
- ("generate_absorb_corrections", "gen_absorb_corrections"),
("masking_file_name", "masking_file_name"),
("multiple_scattering", "multiple_scattering"),
("raw_data_cropping_values", "raw_data_crop_values"),
diff --git a/scripts/Diffraction/isis_powder/routines/InstrumentSettings.py b/scripts/Diffraction/isis_powder/routines/InstrumentSettings.py
index 0bd2bb1e1e1..515902d0046 100644
--- a/scripts/Diffraction/isis_powder/routines/InstrumentSettings.py
+++ b/scripts/Diffraction/isis_powder/routines/InstrumentSettings.py
@@ -34,6 +34,10 @@ class InstrumentSettings(object):
raise AttributeError("The parameter with name: '" + str(map_entry[0]) + "' is required but was not set or "
"passed.\nPlease set this configuration option and try again")
else:
+ # If you have got here from a grep or something similar this error message means the line caller
+ # has asked for a class attribute which does not exist. These attributes are set in a mapping file which
+ # is passed in whilst InstrumentSettings is being constructed. Check that the 'script name' (i.e. not user
+ # friendly name) is typed correctly in both the script(s) and mapping file.
raise AttributeError("The attribute in the script with name " + str(item) + " is unknown to the mapping."
"\nPlease contact the development team.")
--
GitLab