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

Calibration Implementation Details

This file is concerned with calibrating a specified set of tubes

The main function is getCalibration() which is at the end of this file. It populates an empty Calibration Table Workspace with the new positions of the pixel detectors after calibration. This Calibration Table Workspace can be used later to move the pixel detectors to the calibrated positions.

Users should not need to directly call any other function other than getCalibration() from this file.

tube_calib.constructIdealTubeFromRealTube(ws, tube, fitPar, funcForm)

Construct an ideal tube from an actual tube (assumed ideal)

Parameters:

  • ws – integrated workspace

  • tube – specification of one tube (if several tubes, only first tube is used)

  • fitPar – initial fit parameters for peak of the tube

  • funcForm – listing the type of known positions 1=Gaussian; 2=edge

Return type:

IdealTube

tube_calib.correct_tube(AP, BP, CP, nDets)

Corrects position errors in a tube in the same manner as is done for MERLIN according to an algorithm used by Rob Bewley in his MATLAB code.

@param AP: Fit position of left (in pixels) @param BP: Fit position of right (in pixels) @param CP: Fit position of centre (in pixels) @param nDets: Number of pixel detectors in tube

Return Value: Array of corrected Xs (in pixels)

tube_calib.correct_tube_to_ideal_tube(tube_points: List, ideal_tube_points: List, n_detectors: int, test_mode: bool = False, polin_fit: int = 2, parameters_table: str | None = None) → ndarray

Corrects position errors in a tube given an array of points and their ideal positions.

Note that any element of tubePoints not between 0.0 and nDets is considered a rogue point and so is ignored.

Parameters:

  • tube_points – Array of Slit Points along tube to be fitted (in pixels)

  • ideal_tube_points – The corresponding points in an ideal tube (Y-coords advised)

  • n_detectors – Number of pixel detectors in tube

  • test_mode – If true, detectors at the position of a slit will be moved out of the way to show the reckoned slit positions when the instrument is displayed.

  • polin_fit – Order of the polynomial to fit for the ideal positions

  • parameters_table – name of output TableWorkspace containing values and errors for optimized polynomial coefficients, as well as goodness-of-fit chi-square value. If None, no table is returned

Returns:

Array of corrected Xs (in same units as ideal tube points)

tube_calib.create_tube_calibration_ws_by_ws_index_list(integrated_workspace, output_workspace, workspace_index_list)

Creates workspace with integrated data for one tube against distance along tube The tube is specified by a list of workspace indices of its spectra

@param integrated_workspace: Workspace of integrated data @param workspace_index_list: list of workspace indices for the tube @param x_unit: unit of distance ( Pixel) @param show_plot: True = show plot of workspace created, False = just make the workspace.

Return Value: Workspace created

tube_calib.getCalibratedPixelPositions(input_workspace: str | EventWorkspace | Workspace2D, tube_positions: List[int] | ndarray, ideal_tube_positions: List[int] | ndarray, which_tube: List[int] | ndarray, peak_test_mode: bool = False, polin_fit: int = 2, parameters_table: str | None = None) → Tuple[List[int], List[int]]

Get the calibrated detector positions for one tube.

The tube is specified by a list of workspace indices of its spectra. The calibration is assumed to be done parallel to the Y-axis.

Parameters:

  • input_workspace – Workspace with tubes to be calibrated - may be integrated or raw

  • tube_positions – Array of calibration positions (in pixels)

  • ideal_tube_positions – Where these calibration positions should be (in Y coords)

  • which_tube – a list of workspace indices for the tube

  • peak_test_mode – true if shoving detectors that are reckoned to be at peak away (for test purposes)

  • polin_fit – Order of the polynomial to fit for the ideal positions

  • parameters_table – name of output TableWorkspace containing values and errors for optimized polynomial coefficients, as well as goodness-of-fit chi-square value. If None, no table is returned

Returns:

list of pixel detector IDs, and list of their calibrated positions

tube_calib.getCalibration(input_workspace: str | Workspace2D, tubeSet: TubeSpec, calibTable: TableWorkspace, fitPar: TubeCalibFitParams, iTube: IdealTube, peaksTable: TableWorkspace, overridePeaks: Dict[int, List[Any]] = {}, excludeShortTubes: float = 0.0, plotTube: List[int] = [], range_list: List[int] | None = None, polinFit: int = 2, peaksTestMode: bool = False, parameters_table_group: str | None = None) → None

Get the results the calibration and put them in the calibration table provided.

Parameters:

  • input_workspace – Integrated Workspace with tubes to be calibrated

  • tubeSet – Specification of Set of tubes to be calibrated ( TubeSpec object)

  • calibTable – Empty calibration table into which the calibration results are placed. It is composed by ‘Detector ID’ and a V3D column ‘Detector Position’. It will be filled with the IDs and calibrated positions of the detectors.

  • fitPar – A TubeCalibFitParams object for fitting the peaks

  • iTube – The IdealTube which contains the positions in metres of the shadows of the slits, bars or edges used for calibration.

  • peaksTable – Peaks table into which the peaks positions will be put

  • overridePeaks – dictionary with tube indexes keys and an array of peaks in pixels to override those that would be fitted for one tube

  • excludeShortTubes – Exlude tubes shorter than specified length from calibration

  • plotTube – List of tube indexes that will be ploted

  • range_list – list of the tube indexes that will be calibrated. Default None, means all the tubes in tubeSet

  • polinFit – Order of the polynomial to fit against the known positions. Acceptable: 2, 3

  • peaksTestMode – true if shoving detectors that are reckoned to be at peak away (for test purposes)

  • parameters_table_group – name of the WorkspaceGroup containing individual TableWorkspace tables. Each table holds values and errors for the optimized coefficients of the polynomial that fits the peak positions (in pixel coordinates) to the known slit positions (along the Y-coordinate). The last entry in the table holds the goodness-of-fit, chi-square value. The name of each individual TableWorkspace is the string parameters_table_group plus the suffix _I, where I is the tube index as given by list range_list. If None, no group workspace is generated.

This is the main method called from calibrate() to perform the calibration.

tube_calib.getCalibrationFromPeakFile(ws, calibTable, iTube, PeakFile)

Get the results the calibration and put them in the calibration table provided.

@param ws: Integrated Workspace with tubes to be calibrated @param calibTable: Calibration table into which the calibration results are placed @param iTube: The ideal tube @param PeakFile: File of peaks for calibration

tube_calib.getPoints(integrated_ws, func_forms, fit_params, which_tube, show_plot=False)

Get the centres of N slits or edges for calibration

It does look for the peak position in pixels by fitting the peaks and edges. It is the method responsible for estimating the peak position in each tube.

Note

This N slit method is suited for WISH or the five sharp peaks of MERLIN .

Parameters:

  • integrated_ws – Workspace of integrated data

  • func_forms – array of function form 1=slit/bar, 2=edge

  • fit_params – a TubeCalibFitParams object contain the fit parameters

  • which_tube – a list of workspace indices for one tube (define a single tube)

  • show_plot – show plot for this tube

Return type:

array of the slit/edge positions (-1.0 indicates failed to find position)

tube_calib.get_ideal_tube_from_n_slits(integrated_workspace, slits)

Given N slits for calibration on an ideal tube convert to Y values to form a ideal tube for correctTubeToIdealTube()

@param integrated_workspace: Workspace of integrated data @param slits: positions of slits for ideal tube (in pixels)

Return Value: Ideal tube in Y-coords for use by correctTubeToIdealTube()

tube_calib.read_peak_file(file_name)

Load the file calibration

It returns a list of tuples, where the first value is the detector identification and the second value is its calibration values.

Example of usage:
for (det_code, cal_values) in readPeakFile(‘pathname/TubeDemo’):

print(det_code) print(cal_values)

TubeSpec

class tube_spec.TubeSpec(input_workspace: str | Workspace)

The python class TubeSpec provides a way of specifying a set of tubes for calibration, so that the necessary information about detectors etc. is forthcoming. The function getCalibration() of tube_calib needs such an object.

Configuration methods:

There are some functions useful for getting information about a tube specification. It is not necessary to call them in a calibration script, but they may be useful for checking the specification. These methods are:

Note

Tubes are currently ordered in the specification in the same order as they appear in the IDF. This may differ from the order they appear in the workspace indices.

getComponent()

Returns instrument component corresponding to specification

Return type:

instrument component

getComponents()

Returns instrument components corresponding to specification

Return type:

array of instrument components

getDetectorInfoFromTube(tubeIx)

Returns detector info for one tube.

Returns information about detectors in the ( tubeIx +1)st tube in the specification, where tubeIx is the argument. Three integers are returned:

the ID for the first detector, the number of detectors in the tube and the increment step of detector IDs in the tube (usually 1, but may be -1).

It assumes that all the pixels along the tube have consecutive detector IDs.

Parameters:

tubeIx – index of Tube in specified set

Return type:

ID of first detector, number of detectors and step between detectors +1 or -1

getNumTubes()

Returns number of tubes specified. May also save info about these tubes

Return type:

Value, number of tubes (-1 for erroneous specification)

getTube(tubeIx)

Returns list of workspace indices of a tube

Parameters:

tubeIx – index of Tube in specified set

Return type:

list of indices

getTubeByString(tubeIx)

Returns list of workspace indices of a tube set that has been specified by string It assumes that all the pixels along the tube have consecutive detector IDs

Parameters:

tubeIx – index of Tube in specified set

Return type:

list of indices

getTubeLength(tubeIx)

Returns length of the ( tubeIx +1)st tube.

Parameters:

tubeIx – index of Tube in specified set

Return type:

Length of tube (first pixel to last pixel) in metres. 0.0 if tube not found.

getTubeName(tubeIx)

Returns name of tube.

This function is not used in tube calibration, but may be useful as a diagnostic. It is used in creating the peakfile, which lists the peaks found for each tube.

Parameters:

tubeIx – index of Tube in specified set

Return type:

Name of tube as in IDF or ‘unknown’ if not found.

isTube(comp)

Determines whether the component is a tube.

Parameters:

comp – the component

Return type:

Value, true if component passes test as being a tube

searchForTubes(comp)

Searches the component for tubes and saves them in array, appending if array is not empty.

Parameters:

comp – the component

setTubeSpecByString(tubeSpecString)

Define the sets of tube from the workspace.

Sets tube specification by string. The string specifies a component of the instrument as in the instrument tree of its IDF file. This component may contain one or more tubes and possibly all the tunes in the instrument. If the tube specification is not empty this component is added to those already in the specification. No checking is done for repeated or overlapping components.

Parameters:

tubeSpecString – string specifying tubes of a component of the instrument

The tubeSpecString may be the full path name for the component or steps may be missed out provided it remains unique. For example panel03 of WISH can be specified by just panel03, because panel03 is unique within the instrument. Also tube012 of this panel, which is unique within the panel but not within the instrument can be specified by panel03/tube012 but not tube012. If the specification is not unique, the first found will be used and there will be no error message. So if in doubt don’t skip a step.

setTubeSpecByStringArray(tubeSpecArray)

Define the sets of tube from the workspace with an array of strings.

Set tube specification like setTubeSpecByString, but with an array of string to enable multiple components to be calibrated.

This function allows you to calibrate a set of tubes that is not defined by a single component. For example a set of windows. It takes an array of strings as its argument. Each string specifies a component such as a window or a single tube in the same manner as for setTubeSpecByString(). The components must be disjoint.

Parameters:

tubeSpecArray – array of strings (ex. [‘door1’, ‘door2’])

TubeCalibFitParams

class tube_calib_fit_params.TubeCalibFitParams(peaks, height=1000.0, width=30.0, threePointMethod=False, outEdge=30.0, inEdge=50.0, edgeGrad=6.0, margin=15)

IdealTube

class ideal_tube.IdealTube

The IdealTube specifies where the peaks formed by slits or edges should occur.

They can be considered as the known positions as well. It does also keep informatin about the shape of the known_positions, if they are peaks or edges.

First you create an ideal tube by calling the empty constructor idealTube(). Then call another function to populate it.

You may fill it up with the following methods:

You may than query the known positions and functional forms through :

constructTubeFor3PointsMethod(idealAP, idealBP, idealCP, activeTubeLen)

Construct and ideal tube for Merlin 3-point calibration

Parameters:

  • idealAP – Ideal left (AP) in pixels

  • idealBP – ideal right (BP) in pixels

  • idealCP – ideal centre (CP) in pixels

  • activeTubeLen – Active tube length in metres

getArray()

Return the array of of points where the peaks should be in Metres

getFunctionalForms()

Return the array of of points where the peaks should be in Metres

setArray(array)

Construct an ideal tube directly from an array of positions

Parameters:

array – Array of points where the peaks should be in Metres

setForm(form)

Define the functional form for the peaks

setPositionsAndForm(pos, form)

Construct and ideal tube directly from an array of positions and functional forms

Parameters:

  • pos – Array of points where the peaks or edges should be in Metres

  • form – Array of functional forms of the points 1=peak, 2=edge

Category: Techniques