Project Class#

Domains Class#

RAT currently supports two calculation types (normal and Domains). The Domains Class is a project class with extra parameters (domainRatio, domainContrasts) for the Domains calculation.

Reference#

API.createProject(options)#

Creates a normal project or domain project object depending on the given calculation type. This is the recommended way to create a RAT project not via the projectClass or domainsClass.

Examples

To create a normal, standard layers project.

>>> project = createProject(name='New experiment', calcType='normal');

To create a domains, custom layers project with absorption.

>>> project = createProject(name='Domains experiment', calcType='domains', model='custom layers', absorption=true);

Parameters:

• name (string or char array, default: '') – The name of the project.

• calcType (calculationTypes, default: calculationTypes.Normal) – The calculation type which can be ‘normal’ or ‘domains’.

• model (modelTypes, default: modelTypes.StandardLayers) – The layer model type which can be ‘standard layers’, ‘custom layers’, or ‘custom xy’.

• geometry (geometryOptions, default: geometryOptions.AirSubstrate) – The geometry to use which can be ‘air/substrate’ or ‘substrate/liquid’.

• absorption (logical, default: false) – Indicates whether imaginary component is used for the SLD value in layers.

Returns:

obj – A new normal project class or domains project class initialised with given parameters.

Return type:

projectClass or domainsClass

class API.projectClass.projectClass(experimentName, modelType, geometry, absorption)#

projectClass stores all the information that describes the experiment which is essential for running a RAT calculation. There are several components of a project such as the parameters, backgrounds, resolutions, custom files, data, contrast etc, the projectClass provides a number of methods to add, remove, and update these components. For example, for parameters, the addParameter, removeParameter, and setParameter methods are available for adding, removing, and updating parameters.

Examples

>>> project = projectClass();
>>> project = projectClass("Example Project");
>>> project = projectClass("Example Project", 'custom layers', 'substrate/liquid', true);

Parameters:

• experimentName (string or char array, default: '') – The name of the project.

• modelType (modelTypes, default: modelTypes.StandardLayers) – The layer model type which can be ‘standard layers’, ‘custom layers’, or ‘custom xy’.

• geometry (geometryOptions, default: geometryOptions.AirSubstrate) – The geometry to use which can be ‘air/substrate’ or ‘substrate/liquid’.

• absorption (logical, default: false) – Indicates whether imaginary component is used for the SLD value in layers.

parameters#

The project parameters.

Type:

parametersClass

bulkIn#

The bulkIn parameters.

Type:

parametersClass

bulkOut#

The bulkOut parameters.

Type:

parametersClass

scalefactors#

The scalefactors parameters.

Type:

parametersClass

layers#

An object which contains the layers information.

Type:

layersClass

data#

An object which contains the data table.

Type:

dataClass

customFile#

An object which contains the defined customFiles.

Type:

Custom file object

background#

An object which contains defined backgrounds and background parameters.

Type:

backgroundsClass object

resolution#

An object which contains defined resolutions and resolution parameters.

Type:

resolutionClass object

contrasts#

An object which contains contrast information.

Type:

contrastsClass object

addBackground(name, type, source, value1, value2, value3, value4, value5)#

Adds a new background to the project.

Examples

To add a new constant background with name only.

>>> project.addBackground('New Background');

To add a constant background.

>>> project.addBackground('New Background', 'constant', 'param name');

To add a function background with 2 parameters.

>>> project.addBackground('New Background', 'function', 'function name', 'param name', ''param name 2'');

To add a data background with an offset.

>>> project.addBackground('New Background', 'data', 'data name', 'offset param name');

Parameters:

• 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.

addBackgroundParam(name, min, value, max, fit, priorType, mu, sigma)#

Adds a new background parameter to project.

Examples

To add a new background parameter with no properties and an autogenerated name.

>>> project.addBackgroundParam();

To add a background parameter with all available properties.

>>> project.addBackgroundParam('Background Value D2O'', 1e-8, 2.8e-6, 1e-5, true, 'gaussian', 1, 5);

Other examples of adding background parameters with a subset of properties.

>>> project.addBackgroundParam('Background Value D2O');  % Background parameter name only with others set to default
>>> project.addBackgroundParam('Background Value D2O', 1e-8);  % Background parameter name and min only. Value and max will be set to 1e-8 to keep limits valid
>>> project.addBackgroundParam('Background Value D2O', 1e-8, 2.8e-6, 1e-5, true);  % priors will be default

Parameters:

• name (string or char array, default: auto-generated name) – The name of the background parameter.

• min (double, default: 0.0) – The minimum value that the background parameter could take when fitted.

• value (double, default: 0.0) – The value of the background parameter, default will be equal to min if this is not set.

• max (double, default: 0.0) – The maximum value that the background parameter could take when fitted, default will be equal to value if this is not set.

• fit (logical, default: false) – Whether the background parameter should be fitted in a calculation.

• priorType (PriorTypes, default: PriorTypes.Uniform) – For Bayesian calculations, whether the prior likelihood is assumed to be ‘uniform’, ‘gaussian’, or ‘jeffreys’.

• mu (double, default: 0.0) – If the prior type is Gaussian, the mean of the Gaussian function for the prior likelihood.

• sigma (double, default: Inf) – If the prior type is Gaussian, the standard deviation of the Gaussian function for the prior likelihood.

addContrast(varargin)#

Adds a new contrast parameter. Expects a parameter name, and with key-value pairs with one or more of the following “data”, “background”, “bulk in”, “bulk out”, “scalefactor”, “resolution”, “resample”, “model”

project.addContrast(‘contrast 1’, ‘bulkIn’, ‘Silicon’);

addCustomFile(varargin)#

Adds a new custom file parameter. Expects a parameter name, filename, language (matlab, octave, or cpp), and working directory

project.addCustomFile(‘model 1’, ‘custom.m’, ‘matlab’, pwd);

addData(varargin)#

Adds a new data parameter. Expects the name of data and the data array

project.addData(‘Sim 2’, data);

addLayer(varargin)#

Adds a single layer to the layers object. Expects layer details which are name, thickness, SLD, roughness, hydration, and hydrate with, or provide with no details, or just a name, to create an empty layer.

project.addLayer(‘New Layer’);

addLayerGroup(layerGroup)#

Adds a group of layers to the layers object. Expects a cell array of layer cell arrays

project.addLayerGroup({{‘Layer 1’}, {‘Layer 2’}});

addResolution(name, type, source, value1, value2, value3, value4, value5)#

Adds a new resolution to the project.

Examples

To add a new constant resolution with name only.

>>> project.addResolution('New Resolution');

To add a constant resolution.

>>> project.addResolution(New Resolution', 'constant', 'param name');

To add a data resolution.

>>> project.addResolution('New Resolution', 'data');

Parameters:

• name (string or char array, default: auto-generated name) – The name of the resolution.

• type (allowedTypes, default: allowedTypes.Constant) – The type of resolution (constant or data).

• source (string or char array, default: '') – The source of the resolution. if type is ‘constant’, this should be the name (or the row index) of a resolution parameter. if type is ‘data’, this should be empty. RAT will expect a fourth column in the datafile.

• value1 (string or char array, default: '') – Any extra values required by the resolution. if type is ‘constant’, all values will be ignored. if type is ‘data’, all values will be ignored.

• value2 (string or char array, default: '') – Any extra values required by the resolution. if type is ‘constant’, all values will be ignored. if type is ‘data’, all values will be ignored.

• value3 (string or char array, default: '') – Any extra values required by the resolution. if type is ‘constant’, all values will be ignored. if type is ‘data’, all values will be ignored.

• value4 (string or char array, default: '') – Any extra values required by the resolution. if type is ‘constant’, all values will be ignored. if type is ‘data’, all values will be ignored.

• value5 (string or char array, default: '') – Any extra values required by the resolution. if type is ‘constant’, all values will be ignored. if type is ‘data’, all values will be ignored.

addResolutionParam(name, min, value, max, fit, priorType, mu, sigma)#

Adds a new resolution parameter to the project.

Examples

To add a new resolution parameter with no properties and an autogenerated name.

>>> project.addResolutionParam();

To add a resolution parameter with all available properties.

>>> project.addResolutionParam('Resolution Param 1', 20, 50, 60, true, 'gaussian', 1, 5);

Other examples of adding resolution parameters with a subset of properties.

>>> project.addResolutionParam('Resolution Param 1');  % Resolution parameter name only with others set to default
>>> project.addResolutionParam('Resolution Param 1', 23);  % Resolution parameter name and min only. Value and max will be set to 23 to keep limits valid
>>> project.addResolutionParam('Resolution Param 1', 23, 24, 25, true);  % priors will be default

Parameters:

• name (string or char array, default: auto-generated name) – The name of the resolution parameter.

• min (double, default: 0.0) – The minimum value that the resolution parameter could take when fitted.

• value (double, default: 0.0) – The value of the resolution parameter, default will be equal to min if this is not set.

• max (double, default: 0.0) – The maximum value that the resolution parameter could take when fitted, default will be equal to value if this is not set.

• fit (logical, default: false) – Whether the resolution parameter should be fitted in a calculation.

• priorType (PriorTypes, default: PriorTypes.Uniform) – For Bayesian calculations, whether the prior likelihood is assumed to be ‘uniform’, ‘gaussian’, or ‘jeffreys’.

• mu (double, default: 0.0) – If the prior type is Gaussian, the mean of the Gaussian function for the prior likelihood.

• sigma (double, default: Inf) – If the prior type is Gaussian, the standard deviation of the Gaussian function for the prior likelihood.

background#

backgroundsClass object

clone()#

Creates a clone of the project.

Examples

>>> clonedProject = project.clone();

Returns:

clonedProject – A new instance of projectClass with the same properties defined in the current projectClass.

Return type:

projectClass

contrasts#

contrastsClass object

customFile#

Custom file object

data#

dataClass object

delete()#

Destroys the wrappers

getAllAllowedNames()#

Returns a struct with all currently set names of normal parameters, background and resolution parameters, backgrounds, resolutions, bulk-ins, bulk-outs, scalefactors, data, custom files and contrasts for the project.

Returns:

names – A struct with names of all the normal parameters, background and resolution parameters, backgrounds, resolutions, bulk-ins, bulk-outs, scalefactors, data, custom files and contrasts entries in the project.

Return type:

struct

layers#

layersClass object

removeBackground(row)#

Removes a background from the project.

Examples

To remove the second background in the table (background in row 2).

>>> project.removeBackground(2);

To remove background with a specific name.

>>> project.removeBackground('Background 1');

Parameters:

row (string or char array or whole number) – If row 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.

removeBackgroundParam(row)#

Removes a given background parameter from the project.

Examples

To remove the second background parameter in the table (parameter in row 2).

>>>  project.removeBackgroundParam(2);

To remove background parameter with a specific name.

>>>  project.removeBackgroundParam('Background Value D2O');

Parameters:

row (string or char array or whole number) – If row is an integer, it is the row number of the background parameter to remove. If it is text, it is the name of the background parameter to remove.

removeContrast(row)#

Removes a given contrast from the project.

Examples

To remove the second contrast in the table (contrast in row 2).

>>>  project.removeContrast(2);

To remove contrast with a specific name.

>>>  project.removeContrast('contrast 1');

Parameters:

row (string or char array or whole number) – If row is an integer, it is the row number of the contrast to remove. If it is text, it is the name of the contrast to remove.

removeCustomFile(row)#

Removes a given custom file from the project.

Examples

To remove the second custom file in the table (custom file in row 2).

>>>  project.removeCustomFile(2);

To remove custom file with a specific name.

>>>  project.removeCustomFile('custom file 1');

Parameters:

row (string or char array or whole number) – If row is an integer, it is the row number of the custom file to remove. If it is text, it is the name of the custom file to remove.

removeData(row)#

Removes a given dataset from the project.

Examples

To remove the second dataset in the table (dataset in row 2).

>>>  project.removeData(2);

To remove dataset with a specific name.

>>>  project.removeData('D2O');

Parameters:

row (string or char array or whole number) – If row is an integer, it is the row number of the dataset to remove. If it is text, it is the name of the dataset to remove.

removeLayer(layer)#

Removes a given layer from the project.

Examples

To remove the second layer in the table (layer in row 2).

>>>  project.removeLayer(2);

To remove layer with a specific name.

>>>  project.removeLayer('D2O');

Parameters:

row (string or char array or whole number) – If row is an integer, it is the row number of the layer to remove. If it is text, it is the name of the layer to remove.

removeResolution(row)#

Removes a resolution from project.

Examples

To remove the second resolution in the table (resolution in row 2).

>>> project.removeResolution(2);

To remove resolution with a specific name.

>>> project.removeResolution('Resolution 1');

Parameters:

row (string or char array or whole number) – If row is an integer, it is the row number of the resolution to remove. If it is text, it is the name of the resolution to remove.

removeResolutionParam(row)#

Removes a resolution parameter from the project.

Examples

To remove the second resolution parameter in the table (parameter in row 2).

>>> project.removeResolutionParam(2);

To remove resolution parameter with a specific name.

>>> project.removeResolutionParam('Resolution Param 1');

Parameters:

row (string or char array or whole number) – If row is an integer, it is the row number of the resolution parameter to remove. If it is text, it is the name of the resolution parameter to remove.

resolution#

resolutionClass object

setBackground(row, 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).

>>> backgrounds.setBackground(2, name='Background 1', type='constant', source='param name');

To change the properties of a background called ‘Background 1’.

>>> backgrounds.setBackground('Background 1', name='New Background', type='function', source='custom file name', value1='param name');

Parameters:

• row (string or char array or whole number) – If row 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.

• 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.

setBackgroundParam(row, options)#

General purpose method for updating properties of an existing parameter. Any unset property will remain unchanged.

Examples

To change the name and value of the second background parameter in the table (parameter in row 2).

>>> project.setBackgroundParam(2, 'name', 'Background 2', 'value', 50);

To change the all properties of a background parameter called ‘Background Value D2O’.

>>> project.setBackgroundParam('Background Value D2O', 'name', 'Background 2', 'min', 20, 'value', 50, 'max', 60, ...
>>>                            'fit', true, 'priorType', 'gaussian', 'mu', 1, 'sigma', 5);

Parameters:

• row (string or char array or whole number) – If row is an integer, it is the row number of the background parameter to update. If it is text, it is the name of the background parameter to update.

• options –

  Keyword/value pair to properties to update for the specific background parameter.

  • name (char array or string, default: ‘’) the new name of the background parameter.

  • min (double, default: []) the new minimum value of the background parameter.

  • value (double, default: []) the new value of the background parameter.

  • max (double, default: []) the new maximum value of the background parameter.

  • fit (logical, default: logical.empty()) the new fit flag of the background parameter.

  • priorTypes (priorTypes, default: priorTypes.empty()) the new prior type of the background parameter.

  • mu (double, default: []) the new mean of the Gaussian function for the prior.

  • sigma (double, default: []) The new standard deviation of the Gaussian function for the prior.

setContrast(row, varargin)#

Allow setting of all parameters in terms of name value pairs. First input must be contrast number or name, subsequent inputs are name / value pairs for the parts involved

project.setContrast(1, ‘name’, ‘contrast’)

setContrastModel(row, model)#

Edits the model of an existing contrast parameter. Expects the index of contrast parameter and cell array of layer names. Multiple models can be set simultaneously by using an 1D array of indices or cell of strings

project.setContrastModel(1, {‘layer 1’}) project.setContrastModel(1:3, {‘layer 1’})

setCustomFile(row, varargin)#

Edits an existing custom file parameter. Expects the index of custom file to edit and key-value pairs

project.setCustomFile(2, ‘filename’, ‘custom.cpp’);

setData(varargin)#

Edits an existing data parameter. Expects the index of data to edit and key-value pairs

project.setData(1, ‘name’, ‘Sim 1’, ‘data’, zeros(4, 3));

setLayerValue(row, col, value)#

Sets a value of a given layer. Expects the row/name and column of layer value to set, then the name/index of the parameter to set the value to.

project.setLayerValue(1, 2, ‘Tails Thickness’);

setResolution(row, options)#

General purpose method for updating properties of an existing resolution.

Examples

To change the name and value of the second resolution in the table (resolution in row 2).

>>> project.setResolution(2, name='Resolution 1', type='constant', source='param name');

To change the properties of a resolution called ‘Resolution 1’.

>>> project.setResolution('Resolution 1', name='New Resolution 1', type='data');

Parameters:

• row (string or char array or whole number) – If row is an integer, it is the row number of the resolution to update. If it is text, it is the name of the resolution to update.

• options –

  Keyword/value pair to properties to update for the specific resolution.

  • name (char array or string, default: ‘’) the new name of the resolution.

  • type (allowedTypes, default: allowedTypes.empty()) the type of resolution (constant or data).

  • source (char array or string, or whole number, default: ‘’) the new source of the resolution.

  • value1, value2, value3, value4, value5 (char array or string or whole number, default: ‘’) any extra values required for the resolution.

setResolutionParam(row, options)#

General purpose method for updating properties of an existing resolution parameter. Any unset property will remain unchanged.

Examples

To change the name and value of the second resolution parameter in the table (parameter in row 2).

>>> project.setResolutionParam(2, 'name', 'Resolution Param 1', 'value', 50);

To change the all properties of a resolution parameter called ‘Resolution Param 2’.

>>> project.setResolutionParam('Resolution Param 2', 'name', 'Resolution Param 1', 'min', 20, 'value', 50, 'max', 60, ...
>>>                            'fit', true, 'priorType', 'gaussian', 'mu', 1, 'sigma', 5);

Parameters:

• row (string or char array or whole number) – If row is an integer, it is the row number of the resolution parameter to update. If it is text, it is the name of the resolution parameter to update.

• options –

  Keyword/value pair to properties to update for the specific resolution parameter.

  • name (char array or string, default: ‘’) the new name of the resolution parameter.

  • min (double, default: []) the new minimum value of the resolution parameter.

  • value (double, default: []) the new value of the resolution parameter.

  • max (double, default: []) the new maximum value of the resolution parameter.

  • fit (logical, default: logical.empty()) the new fit flag of the resolution parameter.

  • priorTypes (priorTypes, default: priorTypes.empty()) the new prior type of the resolution parameter.

  • mu (double, default: []) the new mean of the Gaussian function for the prior.

  • sigma (double, default: []) The new standard deviation of the Gaussian function for the prior.

toDomainsClass()#

Creates a new domainsClass object and copies the properties from current projectClass.

Examples

>>> domainsProject = project.toDomainsClass();

Returns:

domainsObj – An instance of domainsClass with the same properties defined in the projectClass.

Return type:

domainsClass

toStruct()#

Converts the projectClass into a structure array.

Returns:

outStruct – A struct which contains the properties from the projectClass.

Return type:

struct

writeScript(options)#

Writes a MATLAB script to a given file path. This script can be run to reproduce the current projectClass object.

Examples

>>> project.writeScript(path="newScript.m");

Parameters:

• objName (string or char array, default: 'project') – The name to use for the project object in the script.

• path (string or char array, default: 'projectScript.m') – The relative or absolute file path where the script should be written to.

class API.projectClass.domainsClass(experimentName, modelType, geometry, absorption)#

addDomainContrast(varargin)#

Adds a new domainContrast parameter. Expects a parameter name, and with key-value pairs with one or more of the following “bulk in”, “bulk out”, “model”

project.addDomainContrast(‘domainContrast 1’, ‘bulkIn’, ‘Silicon’);

addDomainRatio(varargin)#

Adds a new domain ratio parameter. Expects the name of domain ratio, min, value, max, and if fit is off or on

project.addDomainRatio(‘Domain Ratio 2’, 0.4, 0.5, 0.6, true);

domainContrasts#

Modified contrast class with no data for domains

domainRatio#

Class for specifying the ratio between domains

domainsClass(experimentName, modelType, geometry, absorption)#

Creates a Project object for a domains calculation. The input arguments are the experiment name which is a char array; the model type, which is a modelTypes enum; the geometry, which is a geometryOptions enum; and a logical to state whether or not absorption terms are included in the refractive index. All of the arguments are optional.

project = domainsClass(‘New experiment’);

getAllAllowedNames()#

Returns a cell array of all currently set parameter names for the project.

removeDomainContrast(row)#

Removes a specified domainContrast parameter. Expects index or name of resolution to remove

project.removeDomainContrast(1);

removeDomainRatio(varargin)#

Removes specified domain ratio parameter. Expects the name/index of domain ratio to remove

project.removeDomainRatio(2);

setContrastModel(row, model)#

Edits the model of an existing contrast parameter. Expects the index of contrast parameter and cell array of layer names

project.setContrastModel(1, {‘layer 1’})

setDomainContrast(row, varargin)#

Allow setting of all parameters in terms of name value pairs. First input must be domainContrast number or name, subsequent inputs are name / value pairs for the parts involved

project.setContrast(1, ‘name’, ‘domainContrast’)

setDomainContrastModel(row, model)#

Edits the model of an existing contrast parameter. Expects the index of contrast parameter and cell array of layer names

project.setDomainContrastModel(1, {‘layer 1’})

setDomainRatio(varargin)#

Edits an existing domain ratio parameter. Expects the index of domain ratio to edit and key-value pairs

project.setDomainRatio(1, ‘name’,’Domain Ratio 1’, ‘value’, 0.55);

toProjectClass()#

Alias of the converter routine from domainsClass to projectClass. This routine takes the currently defined project and converts it to a normal calculation, preserving all currently defined properties.

normalProject = project.toProjectClass();

toStruct()#

Converts the domains class parameters into a struct array for input into the RAT toolbox