3.6

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.correctTube(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.correctTubeToIdealTube(tubePoints, idealTubePoints, nDets, TestMode=False, polinFit=2)

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

Parameters:
  • tubePoints – Array of Slit Points along tube to be fitted (in pixels)
  • idealTubePoints – The corresponding points in an ideal tube (Y-coords advised)
  • nDets – Number of pixel detectors in tube
  • Testmode – 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.
  • polinFit – Order of the polinomial to fit for the ideal positions

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

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

tube_calib.createTubeCalibtationWorkspaceByWorkspaceIndexList(integratedWorkspace, outputWorkspace, workspaceIndexList, xUnit='Pixel', showPlot=False)

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 IntegratedWorkspace: Workspace of integrated data @param workspaceIndexList: list of workspace indices for the tube @param xUnit: unit of distance ( Pixel) @param showPlot: True = show plot of workspace created, False = just make the workspace.

Return Value: Workspace created

tube_calib.doi() → str :

Returns the DOI for this release of Mantid

tube_calib.getCalibratedPixelPositions(ws, tubePts, idealTubePts, whichTube, peakTestMode=False, polinFit=2)

Get the calibrated detector positions for one tube The tube is specified by a list of workspace indices of its spectra Calibration is assumed to be done parallel to the Y-axis

Parameters:
  • ws – Workspace with tubes to be calibrated - may be integrated or raw
  • tubePts – Array of calibration positions (in pixels)
  • idealTubePts – Where these calibration positions should be (in Y coords)
  • whichtube – a list of workspace indices for the tube
  • PeakTestMode – true if shoving detectors that are reckoned to be at peak away (for test purposes)
  • polinFit – Order of the polinominal to fit for the ideal positions

Return Array of pixel detector IDs and array of their calibrated positions

tube_calib.getCalibration(ws, tubeSet, calibTable, fitPar, iTube, peaksTable, overridePeaks={}, excludeShortTubes=0.0, plotTube=, []rangeList=None, polinFit=2, peaksTestMode=False)

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

Parameters:
  • ws – 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 wich the peaks positions will be put
  • overridePeak – dictionary with tube indexes keys and an array of peaks in pixels to override those that would be fitted for one tube
  • exludeShortTubes – Exlude tubes shorter than specified length from calibration
  • plotTube – List of tube indexes that will be ploted
  • rangelist – list of the tube indexes that will be calibrated. Default None, means all the tubes in tubeSet
  • polinFit – Order of the polinomial to fit against the known positions. Acceptable: 2, 3
  • peakTestMode – true if shoving detectors that are reckoned to be at peak away (for test purposes)

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 calibtation

tube_calib.getIdealTubeFromNSlits(IntegratedWorkspace, slits)

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

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

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

tube_calib.getPoints(IntegratedWorkspace, funcForms, fitParams, whichTube, showPlot=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:
  • IntegratedWorkspace – Workspace of integrated data
  • funcForms – array of function form 1=slit/bar, 2=edge
  • fitParams – a TubeCalibFitParams object contain the fit parameters
  • whichTube – a list of workspace indices for one tube (define a single tube)
  • showPlot – show plot for this tube
Return type:

array of the slit/edge positions (-1.0 indicates failed to find position)
tube_calib.paper_citation() → str :

Returns The citation for the Mantid paper

tube_calib.readPeakFile(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
tube_calib.release_date() → str :

Returns the date of the last commit

tube_calib.release_notes_url() → str :

Returns the url to the most applicable release notes

tube_calib.revision() → str :

Returns the abbreviated SHA-1 of the last commit

tube_calib.revision_full() → str :

Returns the full SHA-1 of the last commit

tube_calib.version_str() → str :

Returns the Mantid version string in the form “major.minor.patch”

TubeSpec

class tube_spec.TubeSpec(ws)

The python class TubeSpec provides a way of specifying a set of tubes for calibration, so that the necessary information about detectors etc. is forethcoming. This class is provide by the python file tube_spec.py. 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.

__init__(ws)

The constructor creates empty tube specification for specified instrument. :param ws: workspace containing the specified instrument with one pixel detector per spectrum.

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 intrument 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)
__init__(peaks, height=1000.0, width=30.0, threePointMethod=False, outEdge=30.0, inEdge=50.0, edgeGrad=6.0, margin=15)

Holds the parameters needed for fitting the positions of the peaks formed by the slits or edges.

The constructor has the following arguments:

Parameters:
  • peaks – expected positions of the peaks in pixels
  • height – expect height of peaks
  • width – expected width (sigma for Gaussian fitting) of peaks
  • threePointMethod – True if three point method is used (first and last peaks are the extreme ends of very wide peaks).
  • margin – defines the region around the peak that will be considered for fitting

This class has also an attribute, called automatic, accessed through getAutomatic(), that defines it a dynamic evaluation of the fit parameters can be used or not (see calibrate() to check how the automatic flag will be used).

The function getCalibration() of tube_calib needs such an object.

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 :

__init__()

Create empty instance

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()

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

getFunctionalForms()

Reurn 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:points – 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