Utilities#

RAT contains a variety of utility functions, mostly for development but some are for file reading and conversion.

File reading and conversion#

utilities.readOrso(filename)#

Read data from an .ort file.

Parameters:: filename (string) – The path to the .ort file.
Returns:: output_data – The data array from the .ort file.
Return type:: array

utilities.misc.projectClassToR1(project, varargin)#

Converts projectClass instance to RasCAL1 (r1) struct. Also creates the datafiles directory and saves the data if asked. The functions takes in a projectClass instance and other optional arguments then outputs r1 struct.

Examples

>>> r1Struct = projectClassToR1(project, 'saveProject', false);

Parameters:

project (projectClass) – An instance of the projectClass to convert to r1.
varargin –
Keyword/value pair to configure conversion, the following are allowed
- r1Problem (struct, default: defaultR1ProjectTemplate) a r1 struct which will be updated with equivalent projectClass values.
- dirName (string or char array, default: ‘newDirectory’) directory where the files are saved.
- dirPath (string or char array, default: pwd) path where the new directory is created.
- saveProject (logical, default: false) indicates if files are saved to filesystem.
- fileName (string or char array, default: newFile appended with current timestamp): The filename of the resulting r1 struct.

Returns:

newR1Problem – r1 struct which should be equivalent to the given RAT projectClass instance.

Return type:

struct

utilities.misc.r1ToProjectClass(r1Problem)#

Converts RasCAL1 (r1) struct to an equivalent projectClass instance. The function takes the path of the r1 struct .mat file.

Examples

>>> project = r1ToProjectClass('DSPCBilayerStructInput.mat');  % Load from current directory
>>> project = r1ToProjectClass('examples/DSPCBilayerStructInput.mat');  % Load from the example subdirectory

Parameters:: r1Problem (string or char array) – The path of a mat file that contains a RasCAL1 struct.
Returns:: project – An instance of the projectClass which should be equivalent to the given R1 problem.
Return type:: projectClass

Developer utilities#

utilities.copyProperties(oldObj, newObj)#

Copy public, non-dependent property values between two instances of a class.

Parameters:

oldObj (object) – The object to copy from.
newObj (object) – The object to copy to.

utilities.isFigure(figure)#

Checks whether input is either a figure object or a figure number.

Parameters:: figure (Any) – The input to check if it is a figure.
Raises:: Generic Error – if input is not a figure or a figure number.

utilities.isText(input)#

Checks whether input is either a character array or a string.

isText(‘char array’);

utilities.mustBeScalarOrEmptyLogical(input)#

utilities.textProgressBar(curm, pct, varargin)#

Draws a progress bar in the console. The inputs are the message (char array) and percentage progress expressed as a decimal (i.e., between 0 and 1). Optionally a boolean value can be provided to disable the progress bar.

textProgressBar(“DREAM”, 0.5, false)

utilities.validateLimits(min, value, max)#

Validates the value, minimum and maximum limit variables.

Examples

Incorrect bounds throws exception.

>>> validateLimits(2, 4, 1);  % throws exception as max is less than min

Parameters:

min (double) – The minimum value to validate.
value (double) – The value to validate.
max (double) – The maximum value to validate.

Returns:

index – A valid row index.

Return type:

whole number

Raises:

invalidValue – If min is greater than max or value is outside the limits.

utilities.validateLogical(input, message)#

Checks input is logical and throws an exception with given message.

validateLogical(2, ‘Input must be logical’);

utilities.validateNumber(input, message, validateInt)#

Checks input is a number and throws an exception with given message.

If validateInt is true, also check that input is a whole number.

validateNumber(2, ‘This is not a number’); validateNumber(2.5, ‘This is not a whole number’, true);

utilities.validateOption(input, enum, message)#

Checks input is a valid member of enum and throws an exception with given message. Returns the enum as a char array

validateOption(‘uniform’, ‘priorTypes’, ‘This is not a valid PriorType’);

utilities.validateParameter(param, paramList, paramDesc)#

Checks that the given parameter index or name is valid in the given list of parameters, then returns the parameter name from the list.

Examples

>> param = validateParameter(‘d2o’, {‘D2O’, ‘SMW’}); This should return D2O as name check is case insensitive.

Parameters:

param – The parameter name or index to validate.
paramList – The list of parameter to check for param.
paramDesc – The description or type of the parameter to find in the list.

utilities.validatePriors(priorType, mu, sigma)#

Validates the prior types, mu and sigma variables. If mu and sigma are set on a uniform prior, they would be changed to 0 and Inf respectively and a warning issued.

Examples

To validate a uniform prior.

>>> prior = validatePriors('uniform', 2, 3);
>>> prior

ans =

1×3 cell array: {‘uniform’} {[0]} {[Inf]}

Parameters:

priorType (PriorTypes) – The prior type to validate.
mu (double, default: []) – The Gaussian mean value to validate.
sigma (double, default: []) – The Gaussian standard deviation value to validate.

Returns:

priors – A cell array containing the valid prior type, mu and sigma.

Return type:

cell

Warns:

generic warning – If mu or sigma is set on a uniform prior.

class utilities.pythonWrapper(libPath, functionName)#

A custom function wrapper for a python file.

delete()#: Removes the temporary runner file

disp()#: Displays library path and function name

getHandle()#: Gets the name of the temporary runner file

pythonWrapper(libPath, functionName)#

Creates a pythonWrapper object. It creates a temporary function which runs the python code using the python executable connected to MATLAB pyenv. The arguments should be full or relative path of the python file with extension and the name of the function to call in the python file

wrapper = pythonWrapper(‘customBilayer.py’, ‘customBilayer’); wrapper = pythonWrapper(‘D:/MATLAB/customBilayer.py’, ‘customDomains’);

class utilities.customEnum(value)#

customEnum(value)#

Creates a customEnum object. This is a base class used to associate separate values to an enumeration.

enum = customEnum();

static fromValue(name, value, acceptIndex)#

Gets the enumeration with the given value. An empty value is returned if value is not found. Expects the name of the enumeration class and the value of an enumeration. If acceptIndex is true the function will accept an index in place of the value (it will not work if enum values are numeric)

bulkInEnum = enum.fromValue(‘hydrationTypes’, ‘bulk in’);

static toStruct(name, useIndexAsValue)#

Returns a structure containing all the enumeration names and values. Expects the name of the enumeration class

structure = enum.toStruct(‘priorTypes’)

static values(name)#

Returns a cell array containing all the values of the given enumeration class. Expects the name of the enumeration class

array = enum.values(‘priorTypes’);

class utilities.dyLibWrapper(libPath, functionName)#

A custom function wrapper for c++ dynamic library. The library should be a .dll (Windows), .so (Linux), or .dylib (MacOS).

delete()#: Destroys the callback class instance in wrapperMex

disp()#: Displays libarary path and function name

dyLibWrapper(libPath, functionName)#

Creates a dyLibWrapper object. It creates a callback interface for the library via wrapperMex.The arguments should be full or relative path of the library with extension and the name of the function to call in the dynamic library

wrapper = dyLibWrapper(‘customBilayer.so’, ‘customBilayer’); wrapper = dyLibWrapper(‘D:/MATLAB/customBilayer.dll’, ‘customDomains’);

getHandle()#: Gets the wrapper object handle

utilities.misc.randSample(population, numItems, weights)#

Take a random sample of values. GPL-licensed replacement for randsample from Statistics and Machine Learning Toolbox.

Note that unweighted sampling is without replacement, and weighted sampling is with replacement!

Parameters:

population (vector or a whole number) – if a vector, sample k values from the vector. if an whole number, sample k values from 1:n.
numItems (whole number) – the number of items to sample.
weights (vector, optional) – a weight vector, where the i’th index of weights is the weight for the i’th member of the population.

Returns:

outputSample – The resulting sample of values.

Return type:

vector

utilities.misc.kde(data, n, MIN, MAX)#

Estimate kernel density for one-dimensional data.

Reliable and extremely fast kernel density estimator for one-dimensional data; Gaussian kernel is assumed and the bandwidth is chosen automatically; Unlike many other implementations, this one is immune to problems caused by multimodal densities with widely separated modes (see example). The estimation does not deteriorate for multimodal densities, because we never assume a parametric model for the data.

Parameters:

data (vector) – The vector of data from which the density estimate is constructed.
n (int) – The number of mesh points used in the discretisation of the interval. Must be a power of two; if not, then it is rounded up (to n=2^ceil(log2(n)))
MIN (float, optional) – The minimum for the interval over which the estimate is constructed. Defaults to min(data) - range / 10, where range is the data range.
MAX (float, optional) – The maximum for the interval over which the estimate is constructed. Defaults to max(data) + range / 10, where range is the data range.

Returns:

bandwidth (float) – The optimal bandwidth for a Gaussian kernel over the data.
density (vector) – Column vector with the values of the density estimate at the grid points.
xmesh (vector) – The grid over which the density estimate is coputed.
cdf (vector) – Column vector with the values of the CDF.

Examples

>>> data=[randn(100,1);randn(100,1)*2+35 ;randn(100,1)+55];
    kde(data,2^14,min(data)-5,max(data)+5);