ISIS Powder Diffraction Scripts - GEM Reference¶

Example¶

from isis_powder import Gem

calibration_dir = r"C:\path\to\calibration_dir"
output_dir = r"C:\path\to\output_dir"

gem_example = Gem(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
gem_example = Gem(config_file=config_file_path,
                  user_name="Mantid", ...)

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 GEM the following parameters are required when executing create_vanadium:

• calibration_mapping_file
• do_absorb_corrections
• first_cycle_run_no
• mode

If do_absorb_corrections is set to True the following parameter is required in addition to the above:

• multiple_scattering

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

gem_example.create_vanadium(calibration_mapping_file=cal_mapping_file,
                            do_absorb_corrections=True,
                            first_cycle_run_no=100,
                            mode="PDF",
                            multiple_scattering=False)

focus¶

The focus method processes the user specified run(s). It aligns, focuses and optionally applies corrections if the user has requested them.

On GEM the following parameters are required when executing focus:

• calibration_mapping_file
• do_absorb_corrections
• input_mode
• mode
• run_number
• vanadium_normalisation

If do_absorb_corrections is set to True the following parameter is required in addition to the above:

• multiple_scattering

The following parameters may also be optionally set:

• file_ext
• sample_empty
• suffix
• unit_to_keep

If sample_empty is set then the following parameter is also required:

• sample_empty_scale

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

gem_example.focus(calibration_mapping_file=cal_mapping_file,
                  do_absorb_corrections=False,
                  file_ext=".s01", input_mode="Individual",
                  mode="Rietveld", run_number="100-105",
                  vanadium_normalisation=True)

set_sample¶

The set_sample method allows a user to specify a SampleDetails object which contains the sample properties used when do_absorb_corrections is True whilst focusing.

For more details on the SampleDetails object and how to set it see: ISIS Powder Diffraction Scripts - SampleDetails Reference

The following parameter is required when calling set_sample

• sample - This must be a SampleDetails object with the material set already.

sample_obj = SampleDetails(...)
sample_obj.set_material(...)

gem_example.set_sample(sample=sample_obj)

Example¶

1-100:
  label: "1_1"
  offset_file_name: "offset_file.cal"
  PDF:
    vanadium_run_numbers: "10"
    empty_run_numbers: "20"
  Rietveld:
    vanadium_run_numbers: "30"
    empty_run_numbers: "40"

101-:
  label: "1_2"
  offset_file_name: "offset_file.cal"
  PDF:
    vanadium_run_numbers: "110"
    empty_run_numbers: "120"
  Rietveld:
    vanadium_run_numbers: "130"
    empty_run_numbers: "140"

calibration_directory¶

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

• Grouping .cal file (see: grouping_file_name)
• 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:

gem_example = Gem(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
gem_example = Gem(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
gem_example = Gem(config_file=r"C:\path\to\file\configuration.yaml", ...)

do_absorb_corrections¶

Indicates whether to perform vanadium absorption corrections in create_vanadium mode. In focus mode sample absorption corrections require the sample be set first with the set_sample method.

Accepted values are: True or False

Note: If this is set to ‘True’ multiple_scattering must be set

Example Input:

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

# Or (this assumes sample details have already been set)
gem_example.focus(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:

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

first_cycle_run_no¶

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
gem_example.create_vanadium(first_cycle_run_no=100, ...)

input_mode¶

Indicates how to interpret the parameter run_number whilst calling the focus method. If the input_mode is set to Summed it will process to sum all runs specified. If set to Individual it will process all runs individually (i.e. One at a time)

Accepted values are: Summed and Individual

Note: This parameter is not case sensitive

Example Input:

gem_example.focus(input_mode="Summed", ...)

mode¶

The current chopper mode to use in the create_vanadium and focus method. This determines which vanadium and empty run numbers to use whilst processing.

Accepted values are: PDF and Rietveld

Note: This parameter is not case sensitive

Example Input:

gem_example.create_vanadium(mode="PDF", ...)
# Or
gem_example.focus(mode="Rietveld", ...)

multiple_scattering¶

Indicates whether to account for the effects of multiple scattering when calculating absorption corrections. If do_absorb_corrections is set to True this parameter must be set.

Accepted values are: True or False

Note: Calculating multiple scattering effects will add around 10-30 minutes to the script runtime depending on the speed of the computer you are using

Example Input:

gem_example.create_vanadium(multiple_scattering=True, ...)
# Or
gem_example.focus(multiple_scattering=False, ...)

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:

gem_example = Gem(output_directory=r"C:\path\to\output_dir", ...)

run_number¶

Specifies the run number(s) to process when calling the focus 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.

In addition the input_mode parameter determines what effect a range of inputs has on the data to be processed

Example Input:

# Process run number 1, 3, 5, 6, 7
gem_example.focus(run_number="1, 3, 5-7", ...)
# Or just a single run
gem_example.focus(run_number=100, ...)

sample_empty¶

Optional

This parameter specifies a/several sample empty run(s) to subtract from the run in the focus method. If multiple runs are specified it will sum these runs before subtracting the result.

This input uses the same syntax as run_number. Please visit the above page for more details.

Example Input:

# Our sample empty is a single number
gem_example.focus(sample_empty=100, ...)
# Or a range of numbers
gem_example.focus(sample_empty="100-110", ...)

sample_empty_scale¶

Required if sample_empty is set to True

Sets a factor to scale the sample empty run(s) to before subtracting. This value is multiplied after summing the sample empty runs and before subtracting the empty from the data set. For more details see: Scale.

Example Input:

# Scale sample empty to 90% of original
gem_example.focus(sample_empty_scale=0.9, ...)

unit_to_keep¶

Optional

Specifies a single unit to keep in Mantid after processing using the focus method. For example if dSpacing is set after processing only banks in d-spacing will be present.

Accepted values are: dSpacing and TOF

Note: All units will still be saved out in the output_directory regardless of this property

Note: This parameter is not case sensitive

Example Input:

gem_example.focus(unit_to_keep="dSpacing", ...)

suffix¶

Optional

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

Example Input:

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

user_name¶

Specifies the name of the current user when creating a new GEM object. This is only used when saving data to sort data into respective user folders. See output_directory for more details.

Example Input:

gem_example = Gem(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:

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

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_cropping_values

On GEM this is set to the following TOF windows:

focused_cropping_values = [(550, 19900),  # Bank 1
                           (550, 19900),  # Bank 2
                           (550, 19900),  # Bank 3
                           (550, 19900),  # Bank 4
                           (550, 19480),  # Bank 5
                           (550, 17980)   # Bank 6
                           ]

grouping_file_name¶

Determines the name of the grouping cal file which is located within top level of the calibration_directory.

The grouping file determines the detector ID to bank mapping to use whilst focusing the spectra into banks.

On GEM this is set to the following:

grouping_file_name: "GEM_Instrument_grouping.cal"

raw_tof_cropping_values¶

Determines the TOF window to crop all spectra down to before any processing in the create_vanadium and focus methods.

This helps remove negative counts where at very low TOF the empty counts can exceed the captured neutron counts of the run to process.

On GEM this is set to the following:

raw_tof_cropping_values: (500, 20000)

spline_coefficient¶

Determines the spline coefficient to use after processing the vanadium in create_vanadium method. For more details see: SplineBackground

Note that if this value is changed ‘create_vanadium’ will need to be called again.

On GEM this is set to the following:

spline_coefficient: 30

vanadium_cropping_values¶

Determines the TOF windows to crop to on a bank by bank basis within the create_vanadium method. This is applied after focusing and before a spline is taken.

It is used to remove low counts at the start and end of the vanadium run to produce a spline which better matches the data.

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

On GEM this is set to the following:

vanadium_cropping_values = [(510, 19997),  # Bank 1
                            (510, 19997),  # Bank 2
                            (510, 19997),  # Bank 3
                            (510, 19997),  # Bank 4
                            (510, 19500),  # Bank 5
                            (510, 18000)   # Bank 6
                            ]

Vanadium sample details¶

chemical_formula = "V0.9486 Nb0.0514"

number_density = 0.071

cylinder_sample_height = 4.0

cylinder_sample_radius = 0.4

cylinder_position = [0.0, 0.0, 0.0]