Re #18666 Documented functions within common.py file

scripts/Diffraction/isis_powder/routines/common.py

@@ -6,6 +6,14 @@ from isis_powder.routines.common_enums import InputBatchingEnum
 
 
 def crop_banks_in_tof(bank_list, crop_values_list):
+    """
+    Crops the each bank by the specified tuple values from a list of tuples in TOF. The number
+    of tuples must match the number of banks to crop. A list of [(100,200), (150,250)] would crop
+    bank 1 to the values 100, 200 and bank 2 to 150 and 250 in TOF.
+    :param bank_list: The list of workspaces each containing one bank of data to crop
+    :param crop_values_list: The cropping values to apply to each bank
+    :return: A list of cropped workspaces
+    """
     if not isinstance(crop_values_list, list):
         raise ValueError("The cropping values were not in a list type")
     if len(bank_list) != len(crop_values_list):
@@ -19,6 +27,14 @@ def crop_banks_in_tof(bank_list, crop_values_list):
 
 
 def crop_in_tof(ws_to_crop, x_min=None, x_max=None):
+    """
+    Crops workspaces to the specified minimum and maximum values in TOF. If x_min or x_max is
+    not specified the lower/upper end of the workspace is not modified
+    :param ws_to_crop: The workspace to apply the cropping. This can either be a list of single workspace.
+    :param x_min: (Optional) The minimum value in TOF to crop to
+    :param x_max: (Optional) The maximum value in TOF to crop to
+    :return: The cropped workspace
+    """
     if isinstance(ws_to_crop, list):
         cropped_ws = []
         for ws in ws_to_crop:
@@ -30,6 +46,16 @@ def crop_in_tof(ws_to_crop, x_min=None, x_max=None):
 
 
 def dictionary_key_helper(dictionary, key, throws=True, exception_msg=None):
+    """
+    Checks if the key is in the dictionary and performs various different actions if it is not depending on
+    the user parameters. If set to not throw it will return none. Otherwise it will throw a custom user message
+    or the default python exception depending on what the user has specified.
+    :param dictionary: The dictionary to search for the key
+    :param key: The key to search for in the dictionary
+    :param throws: (Optional) Defaults to true, whether this should throw on a key not being present
+    :param exception_msg: (Optional) The error message to print in the KeyError instead of the default Python message
+    :return: The key if it was found, None if throws was set to false and the key was not found.
+    """
     if key in dictionary:
         return dictionary[key]
     elif not throws:
@@ -44,10 +70,16 @@ def dictionary_key_helper(dictionary, key, throws=True, exception_msg=None):
 
 
 def extract_ws_spectra(ws_to_split):
+    """
+    Extracts individual spectra from the workspace into a list of workspaces. Each workspace will contain
+    one of the spectra from the workspace and will have the form of "<ws_name>_<spectrum number>".
+    :param ws_to_split: The workspace to split into individual workspaces
+    :return: A list of extracted workspaces - one per spectra in the original workspace
+    """
     num_spectra = ws_to_split.getNumberHistograms()
     spectra_bank_list = []
     for i in range(0, num_spectra):
-        output_name = "bank-" + str(i + 1)
+        output_name = ws_to_split.getName() + "-" + str(i + 1)
         # Have to use crop workspace as extract single spectrum struggles with the variable bin widths
         spectra_bank_list.append(mantid.CropWorkspace(InputWorkspace=ws_to_split, OutputWorkspace=output_name,
                                                       StartWorkspaceIndex=i, EndWorkspaceIndex=i))
@@ -55,12 +87,27 @@ def extract_ws_spectra(ws_to_split):
 
 
 def extract_and_crop_spectra(focused_ws, instrument):
+    """
+    Extracts the individual spectra from a focused workspace (see extract_ws_spectra) then applies
+    the user specified cropping. This is the smallest cropping window for use on focused data that
+    is applied on a bank by bank basis. It then returns the extracted and cropped workspaces as a list.
+    :param focused_ws: The focused workspace to extract and crop the spectra of
+    :param instrument: The instrument object associated to this workspace
+    :return: The extracted and cropped workspaces as a list
+    """
     ws_spectra = extract_ws_spectra(ws_to_split=focused_ws)
     ws_spectra = instrument._crop_banks_to_user_tof(ws_spectra)
     return ws_spectra
 
 
 def generate_run_numbers(run_number_string):
+    """
+    Generates a list of run numbers as a list from the input. This input can be either a string or int type
+    and uses the same syntax that Mantid supports i.e. 1-10 generates 1,2,3...9,10 inclusive and commas can specify
+    breaks between runs
+    :param run_number_string: The string or int to convert into a list of run numbers
+    :return: A list of run numbers generated from the string
+    """
     # Check its not a single run
     if isinstance(run_number_string, int) or run_number_string.isdigit():
         return [int(run_number_string)]  # Cast into a list and return
@@ -73,6 +120,16 @@ def generate_run_numbers(run_number_string):
 
 
 def get_monitor_ws(ws_to_process, run_number_string, instrument):
+    """
+    Extracts the monitor spectrum into its own individual workspaces from the input workspace
+    based on the number of this spectrum in the instrument object. The run number is used
+    to determine the monitor spectrum number on instruments who potentially have differing
+    monitor numbers depending on the age of the run.
+    :param ws_to_process: The workspace to extract the monitor from
+    :param run_number_string: The run number as a string to determine the correct monitor position
+    :param instrument: The instrument to query for the monitor position
+    :return: The extracted monitor as a workspace
+    """
     number_list = generate_run_numbers(run_number_string)
     monitor_spectra = instrument._get_monitor_spectra_index(number_list[0])
     load_monitor_ws = mantid.ExtractSingleSpectrum(InputWorkspace=ws_to_process, WorkspaceIndex=monitor_spectra)
@@ -80,6 +137,17 @@ def get_monitor_ws(ws_to_process, run_number_string, instrument):
 
 
 def load_current_normalised_ws_list(run_number_string, instrument, input_batching=None):
+    """
+    Loads a workspace using Mantid and then performs current normalisation on it. Additionally it will either
+    load a range of runs individually or summed depending on the user specified behaviour queried from the instrument.
+    This can behaviour can be overridden by using the optional parameter input_batching. For
+    example if the caller must have the workspaces summed regardless of user selection. The input_batching must be
+    from common_enums.InputBatchingEnum
+    :param run_number_string: The run number string to turn into a list of run(s) to load
+    :param instrument: The instrument to query for the behaviour regarding summing workspaces
+    :param input_batching: (Optional) Used to override the user specified choice where a specific batching is required
+    :return: The normalised workspace(s) as a list.
+    """
     if not input_batching:
         input_batching = instrument._get_input_batching_mode()
 
@@ -91,13 +159,20 @@ def load_current_normalised_ws_list(run_number_string, instrument, input_batchin
         remove_intermediate_workspace(raw_ws_list)
         raw_ws_list = [summed_ws]
 
-    normalised_ws_list = _normalise_workspaces(ws_list=raw_ws_list, run_information=run_information,
+    normalised_ws_list = _normalise_workspaces(ws_list=raw_ws_list, run_details=run_information,
                                                instrument=instrument)
 
     return normalised_ws_list
 
 
 def remove_intermediate_workspace(workspaces):
+    """
+    Removes the specified workspace(s) from the ADS. Can accept lists of workspaces. It
+    does not perform any checks whether the ADS contains those workspaces and it is up
+    to the caller to ensure this is a safe operation
+    :param workspaces: The workspace(s) either individual or a list of to remove from the ADS
+    :return: None
+    """
     if isinstance(workspaces, list):
         for ws in workspaces:
             mantid.DeleteWorkspace(ws)
@@ -106,11 +181,17 @@ def remove_intermediate_workspace(workspaces):
 
 
 def spline_vanadium_for_focusing(focused_vanadium_spectra, num_splines):
-    bank_index = 1
+    """
+    Splines a list of workspaces in TOF and returns the splines in new workspaces in a
+    list of said splined workspaces. The input workspaces should have any Bragg peaks
+    masked before performing this step.
+    :param focused_vanadium_spectra: The workspaces to spline as a list
+    :param num_splines: The coefficient to use within SplineBackground
+    :return: A list of splined workspaces
+    """
     tof_ws_list = []
-    for ws in focused_vanadium_spectra:
-        out_name = "spline_bank_" + str(bank_index)
-        bank_index += 1
+    for bank_index, ws in enumerate(focused_vanadium_spectra):
+        out_name = "spline_bank_" + str(bank_index + 1)
         tof_ws_list.append(mantid.ConvertUnits(InputWorkspace=ws, Target="TOF", OutputWorkspace=out_name))
 
     splined_ws_list = []
@@ -121,6 +202,14 @@ def spline_vanadium_for_focusing(focused_vanadium_spectra, num_splines):
 
 
 def subtract_sample_empty(ws_to_correct, empty_sample_ws_string, instrument):
+    """
+    Loads the list of empty runs specified by the empty_sample_ws_string and subtracts
+    them from the workspace specified. Returns the subtracted workspace.
+    :param ws_to_correct: The workspace to subtract the empty instrument runs from
+    :param empty_sample_ws_string: The empty run numbers to subtract from the workspace
+    :param instrument: The instrument object these runs belong to
+    :return: The workspace with the empty runs subtracted
+    """
     if empty_sample_ws_string:
         empty_sample = load_current_normalised_ws_list(run_number_string=empty_sample_ws_string, instrument=instrument,
                                                        input_batching=InputBatchingEnum.Summed)
@@ -131,6 +220,14 @@ def subtract_sample_empty(ws_to_correct, empty_sample_ws_string, instrument):
 
 
 def _crop_single_ws_in_tof(ws_to_rebin, x_max, x_min):
+    """
+    Implementation of cropping the single workspace in TOF. First converts to TOF, crops then converts
+    back to the original unit.
+    :param ws_to_rebin: The workspace to crop
+    :param x_max: (Optional) The minimum TOF values to crop to
+    :param x_min: (Optional) The maximum TOF values to crop to
+    :return: The cropped workspace with the original units
+    """
     previous_units = ws_to_rebin.getAxis(0).getUnit().unitID()
     if previous_units != "TOF":
         ws_to_rebin = mantid.ConvertUnits(InputWorkspace=ws_to_rebin, Target="TOF", OutputWorkspace=ws_to_rebin)
@@ -141,15 +238,30 @@ def _crop_single_ws_in_tof(ws_to_rebin, x_max, x_min):
     return cropped_ws
 
 
-def _normalise_workspaces(ws_list, instrument, run_information):
+def _normalise_workspaces(ws_list, instrument, run_details):
+    """
+    Normalises the workspace list by current by calling the instrument implementation
+    :param ws_list: A list of workspace to perform normalisation on
+    :param instrument: The instrument these runs belong to
+    :param run_details: The run details object associated to this run
+    :return: The list of workspaces normalised by current.
+    """
     output_list = []
     for ws in ws_list:
-        output_list.append(instrument._normalise_ws_current(ws_to_correct=ws, run_details=run_information))
+        output_list.append(instrument._normalise_ws_current(ws_to_correct=ws, run_details=run_details))
 
     return output_list
 
 
 def _check_load_range(list_of_runs_to_load):
+    """
+    Checks the length of the list of runs which are about to be loaded to determine
+    if they are larger than a threshold. Currently this is 1000 as it allows
+    users to automatically process all runs within a cycle but detects if they
+    have missed a digit which is usually 10,000 runs.
+    :param list_of_runs_to_load: The generated run numbers to load as a list
+    :return: None - If the list is greater than the specified maximum a ValueError is raised.
+    """
     maximum_range_len = 1000  # If more than this number of runs is entered probably wrong
     if len(list_of_runs_to_load) > maximum_range_len:
         raise ValueError("More than " + str(maximum_range_len) + " runs were selected."
@@ -157,12 +269,26 @@ def _check_load_range(list_of_runs_to_load):
 
 
 def _load_raw_files(run_number_string, instrument):
+    """
+    Uses the run number string to generate a list of run numbers to load in
+    :param run_number_string: The run number string to generate
+    :param instrument: The instrument to generate the prefix filename for these runs
+    :return: A list of loaded workspaces
+    """
     run_number_list = generate_run_numbers(run_number_string=run_number_string)
     load_raw_ws = _load_list_of_files(run_number_list, instrument)
     return load_raw_ws
 
 
 def _load_list_of_files(run_numbers_list, instrument):
+    """
+    Loads files based on the list passed to it. If the list is
+    greater than the maximum range it will raise an exception
+    see _check_load_range for more details
+    :param run_numbers_list: The list of runs to load
+    :param instrument: The instrument to generate the prefix for
+    :return: The loaded workspaces as a list
+    """
     read_ws_list = []
     _check_load_range(list_of_runs_to_load=run_numbers_list)
 
@@ -175,6 +301,12 @@ def _load_list_of_files(run_numbers_list, instrument):
 
 
 def _sum_ws_range(ws_list):
+    """
+    Sums a list of workspaces into a single workspace. This will take the name
+    of the first and last workspaces in the list and take the form: "summed_<first>_<last>"
+    :param ws_list: The workspaces as a list to sum into a single workspace
+    :return: A single summed workspace
+    """
     # Sum all workspaces
     out_ws_name = "summed_" + ws_list[0].name() + '_' + ws_list[-1].name()
     summed_ws = mantid.MergeRuns(InputWorkspaces=ws_list, OutputWorkspace=out_ws_name)
@@ -182,6 +314,11 @@ def _sum_ws_range(ws_list):
 
 
 def _run_number_generator(processed_string):
+    """
+    Uses Mantid to generate a list of run numbers from a string input
+    :param processed_string: The string representation of run numbers to convert into a list
+    :return: A list of run numbers based on the input string
+    """
     try:
         number_generator = kernel.IntArrayProperty('array_generator', processed_string)
         return number_generator.value.tolist()