Backgrounds Class#
This class makes the backgrounds in RAT. Backgrounds are defined in a two stage process. Firstly we define the actual fitted parameters. These are held in a ‘ParametersClass’ table. Then, we group these into the backgrounds themselves using a multiTypeTable(table). So, we can then use the background parameters to either define background as constant, data or a function.
Method in Project Class |
Method in backgroundsClass |
---|---|
projectClass.addBackgroundParam() |
backgroundsClass.backgroundParams.addParameter() |
projectClass.removeBackgroundParam() |
backgroundsClass.backgroundParams.removeParameter() |
projectClass.setBackgroundParamValue() |
backgroundsClass.backgroundParams.setValue() |
projectClass.addBackground() |
backgroundsClass.addBackground() |
projectClass.removeBackground() |
backgroundsClass.removeBackground() |
Note
For constant, only one parameter is supplied to multi type table.
For data, only the data itself is supplied as a cell.
For function, the function name is supplied, along with up to three parameters (from the parameters table) which are then supplied to the function to calculate the background.
In each case, the background can either be added to the simulation or subtracted from the data.
% Change the name of the existing parameters to refer to D2O
problem.setBacksPar(1,'name','Backs par D2O','fit',true,'min',1e-8,'max',1e-5);
% Add a new constant background
problem.addBackground('Background SMW','constant','Backs par SMW');
Reference#
- class API.projectClass.backgroundsClass(parameters, startBackground, allowedNames)#
Backgrounds are defined in a two-stage process. Firstly, we define the actual fitted parameters. These background parameters are held in a
parametersClass
object and can be used define backgrounds as constant, data or a function.For constant backgrounds, only one background parameter is supplied.
For data backgrounds, an entry in the data table and an optional offset is required
For function, the function name is supplied, along with up to five parameters (from the background parameters table) which are then passed to the function to calculate the background.
In each case, the background can either be added to the simulation or subtracted from the data.
Examples
>>> allowedNames = project.getAllAllowedNames(); >>> backgroundParams = parametersClass('Background Parameter SMW', 1e-8, 1e-5, 1e-3, true); >>> background = backgroundClass(backgroundParams, {'Background SMW','constant','Background Parameter SMW'}, allowedNames);
- Parameters:
parameters (
parameterClass
) – The background parameters.startBackground (
cell
) – A cell array containing the properties for the first background.allowedNames (
struct
) – A struct containing the valid names of data, and custom files that can be referenced in the background.
- backgroundParams#
The background parameters.
- Type:
parameterClass
- backgrounds = multiTypeTable
A custom table object that contains the background entries.
- addBackground(allowedNames, name, type, source, value1, value2, value3, value4, value5)#
Adds a new background to the background table.
Examples
To add a new constant background with name only.
>>> allowedNames = project.getAllAllowedNames(); >>> background.addBackground(allowedNames, 'New Background');
To add a constant background.
>>> background.addBackground(allowedNames, 'New Background', 'constant', 'param name');
To add a function background with 2 parameters.
>>> background.addBackground(allowedNames, 'New Background', 'function', 'function name', 'param name', 'param name 2');
To add a data background with an offset.
>>> background.addBackground(allowedNames, 'New Background', 'data', 'data name', 'offset param name');
- Parameters:
allowedNames (
struct
) – A struct containing the valid names of data, and custom files that can be referenced in the background.name (
string or char array, default: auto-generated name
) – The name of the background.type (
allowedTypes, default: allowedTypes.Constant
) – The type of background (constant, function or data).source (
string or char array or whole number, default: ''
) – The source of the background. if type is ‘constant’, this should be the name (or the row index) of a background parameter. if type is ‘data’, this should be the name (or the row index) of a dataset defined in projectClass.data. if type is ‘function’, this should be the name (or the row index) of a custom function defined in projectClass.customFiles.value1 (
string or char array or whole number, default: ''
) – Any extra values required for the background. if type is ‘constant’, all values will be ignored. if type is ‘data’, value1 may be the name (or the row index) of a background parameter for an optional offset. Other values are ignored. if type is ‘function’, these values may be the names (or the row index) of up to 5 parameters which are passed to the function.value2 (
string or char array or whole number, default: ''
) – Any extra values required for the background. if type is ‘constant’, all values will be ignored. if type is ‘data’, value1 may be the name (or the row index) of a background parameter for an optional offset. Other values are ignored. if type is ‘function’, these values may be the names (or the row index) of up to 5 parameters which are passed to the function.value3 (
string or char array or whole number, default: ''
) – Any extra values required for the background. if type is ‘constant’, all values will be ignored. if type is ‘data’, value1 may be the name (or the row index) of a background parameter for an optional offset. Other values are ignored. if type is ‘function’, these values may be the names (or the row index) of up to 5 parameters which are passed to the function.value4 (
string or char array or whole number, default: ''
) – Any extra values required for the background. if type is ‘constant’, all values will be ignored. if type is ‘data’, value1 may be the name (or the row index) of a background parameter for an optional offset. Other values are ignored. if type is ‘function’, these values may be the names (or the row index) of up to 5 parameters which are passed to the function.value5 (
string or char array or whole number, default: ''
) – Any extra values required for the background. if type is ‘constant’, all values will be ignored. if type is ‘data’, value1 may be the name (or the row index) of a background parameter for an optional offset. Other values are ignored. if type is ‘function’, these values may be the names (or the row index) of up to 5 parameters which are passed to the function.
- displayTable(showPriors)#
Prints the backgrounds and background parameters tables to the console.
Examples
To print the background parameters table with the prior information.
>>> backgrounds.displayTable(true);
- Parameters:
showPriors (
logical, default: false
) – Indicates if the prior type, mu, and sigma columns in the background parameters table should be displayed.
- getNames()#
Returns a N x 1 cell array of names of the backgrounds in the object.
- Returns:
names – A cell array which contains the names of background entries.
- Return type:
cell
- removeBackground(row)#
Removes a background entry from the table.
Examples
To remove the second background in the table (background in row 2).
>>> backgrounds.removeBackground(2);
To remove background with a specific name.
>>> backgrounds.removeBackground('Background 1');
- Parameters:
row (
string or char array or whole number
) – Ifrow
is an integer, it is the row number of the background to remove. If it is text, it is the name of the background to remove.
- setBackground(row, allowedNames, options)#
General purpose method for updating properties of an existing background.
Examples
To change the name and value of the second background in the table (background in row 2).
>>> allowedNames = project.getAllAllowedNames(); >>> backgrounds.setBackground(2, allowedNames, name='Background 1', type='constant', source='param name');
To change the properties of a background called ‘Background 1’.
>>> backgrounds.setBackground('Background 1', allowedNames, name='New Background', type='function', source='custom file name', value1='param name');
- Parameters:
row (
string or char array or whole number
) – Ifrow
is an integer, it is the row number of the background to update. If it is text, it is the name of the background to update.allowedNames (
struct
) – A struct containing the valid names of data, and custom files that can be referenced in the background.options –
- Keyword/value pair to properties to update for the specific background.
name (char array or string, default: ‘’) the new name of the background.
type (allowedTypes, default: allowedTypes.empty()) the type of background (constant, function or data).
source (char array or string or whole number, default: ‘’) the new source of the background.
value1, value2, value3, value4, value5 (char array or string or whole number, default: ‘’) any extra values required for the background.
- setBackgroundName(row, name)#
Sets the name of a given background in the table.
Examples
To change the name of the second background in the table (background in row 2)
>>> backgrounds.setBackgroundName(2, 'new name');
To change the name of a background called ‘old name’ to ‘new name’
>>> backgrounds.setBackgroundName('old name', 'new name');
- Parameters:
row (
string or char array or whole number
) – Ifrow
is an integer, it is the row number of the background to update. If it is text, it is the name of the background to update.name (
string or char array
) – The new name of the background.
- toStruct()#
Converts the backgroundClass into a structure array.
- Returns:
backgroundStruct – A struct which contains the properties for all the backgrounds and background parameters.
- Return type:
struct