\(\renewcommand\AA{\unicode{x212B}}\)

ISIS Powder Diffraction Scripts - PEARL Reference¶

Creating PEARL Object ¶

This method assumes you are familiar with the concept of objects in Python. If not more details can be read here: A quick introduction to objects

To create a PEARL object the following parameters are required:

calibration_directory
output_directory
user_name

Optionally a configuration file may be specified if one exists using the following parameter:

config_file

See Using configuration files on YAML configuration files for more details

Example ¶

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:

create_vanadium
focus
create_cal

For information on creating a PEARL object see: Creating PEARL Object

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:

calibration_mapping_file
do_absorb_corrections
long_mode
run_in_cycle
tt_mode

Example ¶

# 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 ¶

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:

calibration_mapping_file
focus_mode
long_mode
perform_attenuation
run_number
tt_mode
vanadium_normalisation

The following parameter is required if perform_attenuation is set to True

attenuation_file

The following parameters may also be optionally set:

file_ext
suffix

Example ¶

# Notice how the filename ends with .yaml
cal_mapping_file = r"C:\path\to\cal_mapping.yaml"

pearl_example.focus(calibration_mapping_file=cal_mapping_file,
                    focus_mode="all", long_mode=True,
                    perform_attenuation=True,
                    attenuation_file="ZTA",
                    run_number="100-110", tt_mode="tt88",
                    vanadium_normalisation=True)

create_cal ¶

The create_cal method creates the offset calibration file for PEARL scripts. The following parameters are required:

calibration_mapping_file
focus_mode
long_mode
run_number

Example ¶

# Notice how the filename ends with .yaml
cal_mapping_file = r"C:\path\to\cal_mapping.yaml"

pearl_example.create_cal(run_number=95671,
                         tt_mode="tt70",
                         long_mode=True,
                         calibration_mapping_file=cal_mapping_file)

How the PEARL object holds state ¶

The PEARL object does not behave as described in How objects hold state in ISIS Powder. For PEARL, any settings given in the constructor for the PEARL object, either explicitly or via a config file, are taken as defaults. If these are overridden in a call to either focus, create_vanadium or create_cal, then these settings only apply to that line, and are reverted to the defaults when the line has finished executing.

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: Cycle mapping files

The layout on PEARL should look as follows substituting the example values included for appropriate values:

1-100:
  label: "1_1"
  offset_file_name: "offset_file.cal"
  empty_run_numbers: "10"
  vanadium_run_numbers: "20"

Example ¶

1-100:
  label: "1_1"
  offset_file_name: "offset_file.cal"
  empty_run_numbers: "10"
  vanadium_run_numbers: "20"

101-:
  label: "1_2"
  offset_file_name: "offset_file.cal"
  empty_run_numbers: "110"
  vanadium_run_numbers: "120"

Parameters ¶

The following parameters for PEARL are intended for regular use when using the ISIS Powder scripts.

absorb_corrections_out_filename ¶

Required if generate_absorb_corrections is set to True.

The full path to save generated absorption corrects file to.

Note: The path to the file must include the file extension

Example Input:

pearl_example.focus(generate_absorb_corrections=True,
                    absorb_corrections_out_filename=r"C:\PEARL\pearl_absorb_sphere_17_2.nxs"...)

attenuation_file ¶

Required if perform_attenuation is set to True

The name of the attenuation file to use within the focus method. The name must match the name of one of the entries in the attenuation_files setting

The workspace will be attenuated with the specified file if the focus_mode is set to all or trans. For more details see PearlMCAbsorption

Example Input:

pearl_example.focus(attenuation_file="ZTA", ...)

attenuation_files ¶

A list of attenuation file names and paths that are available for use in the Focus process. It is expected that this setting will be specified in a configuration yaml file as follows:

attenuation_files:
  - name : ZTA
    path : C:\path\to\anvil_atten_files\PRL112_DC25_10MM_FF.OUT
  - name : WC
    path : C:\path\to\anvil_atten_files\PRL985_WC_HOYBIDE_NK_10MM_FF.OUT

It can alternatively be supplied as part of the call to focus:

pearl_example.focus(attenuation_file="ZTA", attenuation_files=r'[{"name": "ZTA", "path": r"C:\path\to\anvil_atten_files\PRL112_DC25_10MM_FF.OUT"}]' ...)

Note: The path to the file must include the file extension

calibration_directory ¶

This parameter should be the full path to the calibration folder. Within the folder the following should be present:

Grouping .cal files:
Vanadium Absorption File (see: vanadium_absorb_filename)
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 focus method.

Example Input:

pearl_example = Pearl(calibration_directory=r"C:\path\to\calibration_dir", ...)

calibration_mapping_file ¶

This parameter gives the full path to the YAML file containing the calibration mapping. For more details on this file see: Calibration Mapping File

Note: This should be the full path to the file including extension

Example Input:

# Notice the filename always ends in .yaml
pearl_example = Pearl(calibration_mapping_file=r"C:\path\to\file\calibration_mapping.yaml", ...)

config_file ¶

The full path to the YAML configuration file. This file is described in detail here: Using configuration files 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:

# Notice the filename always ends in .yaml
pearl_example = Pearl(config_file=r"C:\path\to\file\configuration.yaml", ...)

custom_grouping_filename ¶

The name of a custom grouping cal file to use. The file needs to be located within top level of the calibration_directory

custom_grouping_filename: "DAC_group.cal"

do_absorb_corrections ¶

Indicates whether to perform vanadium absorption corrections when calling create_vanadium. If set to True the vanadium absorption file (described here: vanadium_absorb_filename) will be loaded and the vanadium sample will be divided by the pre-calculated absorption corrections.

Accepted values are: True or False

Example Input:

pearl_example.create_vanadium(do_absorb_corrections=True, ...)

file_ext ¶

Optional

Specifies a file extension to use when using the focus 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:

pearl_example.focus(file_ext=".s01", ...)

focus_mode ¶

Determines how the banks are grouped when using the focus method. Each mode is further described below.

Accepted values are: all, groups, mods, trans_custom and trans

all ¶

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 perform_attenuation 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. 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 spectrum then scaled down to 1/9 original scale.

The workspace is also attenuated if perform_attenuation is set to True.

All banks are also output as individual workspaces with appropriate names with no additional processing applied.

trans_custom ¶

This mode behaves the same as trans except the user can optionally supply which modules in the transverse banks to focus/sum using the input parameter e.g. trans_mod_nums=”1-3,5” which would focus modules 1,2,3 and 5. The output spectrum is similarly normalised by the number of modules requested.

If any module numbers are duplicated or outside the range 1-9 inclusive then all transverse modules are included - i.e. it defaults to the behaviour of focus_mode=”trans” and the trans_mod_nums argument is ignored.

mods ¶

In mods mode every bank is left as individual workspaces with appropriate names. No additional processing is performed.

Example Input:

pearl_example.focus(focus_mode="all", ...)

long_mode ¶

Determines the TOF window to process data in. This affects both the create_vanadium and focus methods.

As this affects the vanadium spline used the create_vanadium 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.

When long_mode is False the TOF window processed is between 0-20,000 μs

When long_mode is True the TOF window processed is between 20,000-40,000 μs

This also affects the Advanced Parameters used. More detail can be found for each individual parameter listed under the advanced parameters section.

Accepted values are: True or False

Example Input:

pearl_example.create_vanadium(long_mode=False, ...)
# Or
pearl_example.focus(long_mode=True, ...)

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 calibration_mapping_file and within that create another folder for the current user_name.

Within this folder processed data will be saved out in several formats.

Example Input:

pearl_example = Pearl(output_directory=r"C:\path\to\output_dir", ...)

perform_attenuation ¶

Indicates whether to perform attenuation corrections whilst running focus. For more details of the corrections performed see: PearlMCAbsorption

If this is set to True attenuation_file must be set too.

Note: This correction will only be performed if ‘focus_mode’ is in All or Trans. See: focus_mode for more details.

Accepted values are: True or False

Example Input:

pearl_example.focus(perform_attenuation=True, ...)

run_in_cycle ¶

Indicates a run from the current cycle to use when calling create_vanadium. 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 Calibration Mapping File.

Example Input:

# In this example assume we mean a cycle with run numbers 100-200
pearl_example.create_vanadium(run_in_cycle=100, ...)

run_number ¶

Specifies the run number(s) to process when calling the focus and create_cal methods.

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:

# 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, ...)

suffix ¶

Optional

This parameter specifies a suffix to append the names of output files during a focus.

Example Input:

pearl_example.focus(suffix="-corr", ...)

tt_mode ¶

Specifies the detectors to be considered from the grouping files. This is used in the create_vanadium and focus methods.

For more details of the grouping file which is selected between see the following:

tt35_grouping_filename
tt70_grouping_filename
tt88_grouping_filename
custom_grouping_filename

Accepted values are: tt35, tt70, tt80 and custom

When calling create_vanadium all can be used to implicitly process all of the ttXX values indicated above.

When the custom tt_mode is used a focus mode of “Mods” is always used

Example Input:

pearl_example.create_vanadium(tt_mode="all", ...)
# Or
pearl_example.focus(tt_mode="tt35", ...)

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 output_directory for more details.

Example Input:

pearl_example = Pearl(user_name="Mantid", ...)

vanadium_normalisation ¶

Indicates whether to divide the focused workspace within focus mode with a previously generated vanadium spline.

This requires a vanadium to have been previously created with the create_vanadium method

Accepted values are: True or False

Example Input:

pearl_example.focus(vanadium_normalisation=True, ...)

Advanced Parameters ¶

Warning

These values are not intended to be changed and should reflect optimal defaults for the instrument. For more details please read: Instrument advanced properties

This section is mainly intended to act as reference of the current settings distributed with Mantid

All values changed in the advanced configuration file requires the user to restart Mantid for the new values to take effect. Please read Instrument advanced properties before proceeding to change values within the advanced configuration file.

create_cal_rebin_1_params ¶

The rebin parameters to use in the first rebin operation in create_cal. On PEARL this is set to the following:

# Long mode OFF:
      create_cal_rebin_1_params: "100,-0.0006,19950"

# Long mode ON:
      create_cal_rebin_1_params: "20300,-0.0006,39990"

create_cal_rebin_2_params ¶

The rebin parameters to use in the second rebin operation in create_cal. On PEARL this is set to the following:

create_cal_rebin_2_params: "1.8,0.002,2.1"

cross_corr_reference_spectra ¶

The Workspace Index of the spectra to correlate all other spectra against in the cross-correlation step of create_cal. On PEARL this is set to the following:

cross_corr_reference_spectra: 20

cross_corr_ws_index_max ¶

The workspace index of the last member of the range of spectra to cross-correlate against in create_cal. On PEARL this is set to the following:

cross_corr_ws_index_max: 1063

cross_corr_ws_index_min ¶

The workspace index of the first member of the range of spectra to cross-correlate against in create_cal. On PEARL this is set to the following:

cross_corr_ws_index_min: 9

cross_cor_x_max ¶

The ending point of the region to be cross correlated in create_cal. On PEARL this is set to the following:

cross_corr_x_max: 2.1

cross_cor_x_min ¶

The starting point of the region to be cross correlated in create_cal. On PEARL this is set to the following:

cross_corr_x_min: 1.8

custom_focused_bin_widths ¶

The dt-upon-t binning for the focused data when using tt_mode=custom

On PEARL this is set to -0.0006 for all banks in the custom grouping file

custom_focused_cropping_values ¶

Indicates a list of TOF values to crop the focused workspace which was created by focus on a bank by bank basis when using tt_mode=custom

focused_bin_widths ¶

The dt-upon-t binning for the focused data.

On PEARL this is set to -0.0006 for all 14 banks

focused_cropping_values ¶

Indicates a list of TOF values to crop the focused workspace which was created by focus on a bank by bank basis.

This parameter is a list of bank cropping values with one list entry per bank. The values must have a smaller TOF window than the vanadium_tof_cropping

Note: The value passed with the long_mode parameter determines the set of values used.

On PEARL this is set to the following TOF windows:

# Long mode OFF:
      focused_cropping_values: [
      (1500, 19900),  # Bank 1
      (1500, 19900),  # Bank 2
      (1500, 19900),  # Bank 3
      (1500, 19900),  # Bank 4
      (1500, 19900),  # Bank 5
      (1500, 19900),  # Bank 6
      (1500, 19900),  # Bank 7
      (1500, 19900),  # Bank 8
      (1500, 19900),  # Bank 9
      (1500, 19900),  # Bank 10
      (1500, 19900),  # Bank 11
      (1500, 19900),  # Bank 12
      (1500, 19900),  # Bank 13
      (1500, 19900)   # Bank 14
    ]

# Long mode ON:
      focused_cropping_values: [
      (20300, 38830),  # Bank 1
      (20300, 38830),  # Bank 2
      (20300, 38830),  # Bank 3
      (20300, 38830),  # Bank 4
      (20300, 38830),  # Bank 5
      (20300, 38830),  # Bank 6
      (20300, 38830),  # Bank 7
      (20300, 38830),  # Bank 8
      (20300, 38830),  # Bank 9
      (20300, 38830),  # Bank 10
      (20300, 38830),  # Bank 11
      (20300, 38830),  # Bank 12
      (20300, 38830),  # Bank 13
      (20300, 38830)   # Bank 14
    ]

generate_absorb_corrections ¶

Indicates whether to generate the absorption corrections, instead of reading them from a file. Allowed values are: True and False. If set to True, absorb_corrections_out_filename must also be set. On PEARL this is set to the following:

generate_absorb_corrections: False

get_det_offsets_d_ref ¶

Center of reference peak in d-space for GetDetectorOffsets in create_cal. On PEARL this is set to the following:

get_det_offsets_d_ref: 1.912795

get_det_offsets_step ¶

Step size used to bin d-spacing data in GetDetectorOffsets when running create_cal. On PEARL this is set to the following:

get_det_offsets_step: 0.002

get_det_offsets_x_max ¶

Maximum of CrossCorrelation data to search for peak, usually negative, in create_cal. On PEARL this is set to the following:

get_det_offsets_x_max: -200

get_det_offsets_x_min ¶

Minimum of CrossCorrelation data to search for peak, usually negative, in create_cal. On PEARL this is set to the following:

get_det_offsets_x_min: -200

monitor_lambda_crop_range ¶

The range in dSpacing to crop a monitor spectra to when generating a spline of the current to the target. This is should be stored as a tuple of both values (lower and upper bound).

Note: The value passed with the long_mode parameter determines the set of values used.