Skip to content

Adds docstring for contrasts and some refactors #389

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
StephenNneji merged 9 commits into from
Apr 11, 2025
Merged

Adds docstring for contrasts and some refactors #389

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
b0f092d
Adds docstrings and refactors for contrastsClass
StephenNneji Apr 3, 2025
0906d2c
more refactors
StephenNneji Apr 3, 2025
34627a2
More docstring
StephenNneji Apr 5, 2025
6343d21
Adds check for missing data in to struct
StephenNneji Apr 7, 2025
18c5457
refactors
StephenNneji Apr 7, 2025
d51b121
Some tests
StephenNneji Apr 8, 2025
cb045da
Addresses review comments
StephenNneji Apr 9, 2025
1f40e0d
Fixes commented tests
StephenNneji Apr 10, 2025
9276962
Addresses review comments
StephenNneji Apr 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion API/enums/actions.m → API/enums/backgroundActions.m
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
classdef actions < customEnum
classdef backgroundActions < customEnum
% Ways in which a background can be included in a contrast.
methods (Static)
function s = toStruct()
Expand Down
2 changes: 1 addition & 1 deletion API/enums/coderEnums.m
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
classdef coderEnums
% An Enum class which lets MATLAB Coder use Enums without redefinition or hardcoding.
properties (Constant)
actions = actions.toStruct()
allowedTypes = allowedTypes.toStruct()
backgroundActions = backgroundActions.toStruct()
boundHandlingOptions = boundHandlingOptions.toStruct()
calculationTypes = calculationTypes.toStruct()
errorCodes = errorCodes.toStruct()
Expand Down
292 changes: 186 additions & 106 deletions API/projectClass/baseContrasts.m
View file
Open in desktop

Large diffs are not rendered by default.

263 changes: 176 additions & 87 deletions API/projectClass/contrastsClass.m
View file
Open in desktop

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion API/projectClass/dataClass.m
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@
% varTable : table
% A table object that contains the data entries.

properties (Constant, Access = private)
properties (Constant, Hidden)
defaultSimRange = [0.005, 0.7]
end

Expand Down
57 changes: 35 additions & 22 deletions API/projectClass/domainContrastsClass.m
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,25 @@
classdef domainContrastsClass < baseContrasts

% A simplified version of the contrast class that allows specification
% of the model only (i.e. with no data). This is used for domains
% calculations.

methods

function names = getDisplayNames(~)
names = ["Name"; "Model"];
end

function contrastStruct = toStruct(obj, allowedNames, ~, ~)
% Convert the contrasts class to a struct.
% This routine builds on that in the base class by dealing with
% the additional properties defined in this subclass.
% The expected input is the allowed names for each parameter.
%
% domainContrasts.toStruct(allowedNames, ~, ~)

% Call superclass version for common properties
% Converts the domains contrasts class to a struct.
%
% Parameters
% ----------
% allowedNames: struct
% A struct containing the valid names that can be referenced in the contrast.
%
% Returns
% -------
% contrastStruct : struct
% A struct which contains the properties for all the contrast entries.
contrastStruct = toStruct@baseContrasts(obj);

nContrasts = obj.numberOfContrasts;
Expand All @@ -44,7 +45,17 @@
% values are of the correct type, and included in the list of
% allowed names where necessary.
%
% contrastsClass.parseContrastInput(~, allowedNames, 'name', 'Contrast Name')
% Parameters
% ----------
% allowedNames: struct
% A struct containing the valid names that can be referenced in the contrast.
% inputValues: cell
% A cell containing keyword/value pairs of properties for the contrast.
%
% Returns
% -------
% inputBlock : struct
% A struct containing properties of the contrast with empty fields set to default.
defaultName = '';
defaultModel = '';

Expand All @@ -67,6 +78,19 @@
methods(Access = private)

function model = validateDomainContrastModel(~, input, allowedModelNames)
% Validates domain contrast model.
%
% Parameters
% ----------
% input: string or char array or cell string
% The name(s) in the domain contrast model.
% allowedNames: struct
% A struct containing the valid names that can be referenced in the domain contrast.
%
% Returns
% -------
% model: cell string
% The validated name(s) in the domain contrast model.
if isempty(input)
model = '';
return
Expand All @@ -86,15 +110,4 @@

end

methods(Static)

function contrast = setDefaultValues(contrast)
% Set non-empty default values when adding a contrast.
if ~isempty(contrast.model)
contrast.model = cellstr(contrast.model);
end
end

end

end
516 changes: 428 additions & 88 deletions API/projectClass/domainsClass.m
View file
Open in desktop

Large diffs are not rendered by default.

175 changes: 133 additions & 42 deletions API/projectClass/projectClass.m
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,32 +17,32 @@
% 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'.
% 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.
%
% Attributes
% ----------
% parameters : parametersClass
% The project parameters.
% The project parameters.
% bulkIn : parametersClass
% The bulkIn parameters.
% The bulkIn parameters.
% bulkOut : parametersClass
% The bulkOut parameters.
% The bulkOut parameters.
% scalefactors : parametersClass
% The scalefactors parameters.
% The scalefactors parameters.
% layers : layersClass
% An object which contains the layers information.
% An object which contains the layers information.
% data : dataClass
% An object which contains the data table.
% An object which contains the data table.
% customFile : Custom file object
% An object which contains the defined customFiles.
% An object which contains the defined customFiles.
% background : backgroundsClass object
% An object which contains defined backgrounds and background parameters.
% An object which contains defined backgrounds and background parameters.
% resolution : resolutionClass object
% An object which contains defined resolutions and resolution parameters.
% An object which contains defined resolutions and resolution parameters.
% contrasts : contrastsClass object
% An object which contains contrast information.
% An object which contains contrast information.

properties
experimentName
Expand Down Expand Up @@ -176,14 +176,14 @@ function delete(obj)
function names = getAllAllowedNames(obj)
% 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.
% contrast model for the project.
%
% Returns
% -------
% names : struct
% 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.
% contrast model entries in the project.
names.paramNames = obj.parameters.getNames();
names.backgroundNames = obj.background.getNames();
names.backgroundParamNames = obj.background.backgroundParams.getNames();
Expand Down Expand Up @@ -1035,14 +1035,52 @@ function delete(obj)
% ----------------------------------------------------------------
% Editing of Contrasts Block

function obj = addContrast(obj, 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');
obj.contrasts.addContrast(obj.getAllAllowedNames(), varargin{:});
function obj = addContrast(obj, options)
Copy link
Copy Markdown
Collaborator

@DrPaulSharp DrPaulSharp Apr 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's all written down somewhere . . .

Copy link
Copy Markdown
Collaborator Author

@StephenNneji StephenNneji Apr 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't understand what is written down somewhere? addContrast has always been in projectClass

Copy link
Copy Markdown
Collaborator

@DrPaulSharp DrPaulSharp Apr 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, I'd gone a bit mad by this point. I just mean that I've written the comments elsewhere, i.e., the same points as the other addContrast docstrings.

% Add a new contrast to the project.
%
% Examples
% --------
% To add a new contrast with name only.
%
% >>> project.addContrast(name='new contrast');
%
% To add a new contrast with other properties.
%
% >>> project.addContrast(name='new contrast', bulkIn='Silicon', bulkOut='D2O', background='D2O Background', ...
% resolution='Resolution 1', scalefactor='Scalefactor 1', data='DSPC Bilayer D2O', model={'Oxide', 'Bilayer tails'});
%
% Parameters
% ----------
% options
% Keyword/value pair to properties to update for the specific contrast.
% * name (char array or string, default: '') the name of the contrast.
% * data (char array or string, default: '') the name of the dataset parameter used by the contrast.
% * background (char array or string, default: '') the name of the background for the contrast.
% * backgroundAction (backgroundActions, default: backgroundActions.Add) whether the background should be added to the simulation ('add') or subtracted from the data ('subtract').
% * bulkIn (char array or string, default: '') the name of the bulk-in parameter which defines the SLD of the interface between the first layer and the environment.
% * bulkOut (char array or string, default: '') the name of the bulk-out parameter which defines the SLD of the interface between the last layer and the environment.
% * scalefactor (char array or string, default: '') the name of the scalefactor parameter which defines how much the data for this contrast should be scaled.
% * resolution (char array or string, default: '') the name of the instrument resolution for this contrast.
% * resample (logical, default: false) whether adaptive resampling should be used for interface microslicing.
% * repeatLayers (whole number, default: 1) indicates the number of times the layers should be repeated, this is only supported for standard layers.
% * model (cell) if this is a standard layers model, this should be a list of layer names that make up the slab model for this contrast.
% For custom models, this should be a single custom file name for the custom model function.
arguments
obj
options.name
options.data
options.background
options.backgroundAction
options.bulkIn
options.bulkOut
options.scalefactor
options.resolution
options.resample
options.repeatLayers
options.model
end
args = namedargs2cell(options);
obj.contrasts.addContrast(obj.getAllAllowedNames(), args{:});
end

function obj = removeContrast(obj, row)
Expand All @@ -1066,30 +1104,83 @@ function delete(obj)
obj.contrasts.removeContrast(row);
end

function obj = setContrast(obj, 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
function obj = setContrast(obj, row, options)
Copy link
Copy Markdown
Collaborator

@DrPaulSharp DrPaulSharp Apr 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

deja vu all over again . . .

Copy link
Copy Markdown
Collaborator

@DrPaulSharp DrPaulSharp Apr 9, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, see previous setContrast docstring comments.

% General purpose method for updating properties of an existing contrast.
%
% project.setContrast(1, 'name', 'contrast')

% Get the list of allowed values depending on what is
% set for the other contrasts.
allowedValues = obj.getAllAllowedNames();

% Call the setContrast method
obj.contrasts.setContrast(row, allowedValues, varargin{:});
% Examples
% --------
% To change the properties of the second contrast in the object.
%
% >>> project.setContrast(2, name='new contrast', bulkIn='Silicon', bulkOut='D2O', background='D2O Background', ...
% resolution='Resolution 1', scalefactor='Scalefactor 1', data='DSPC Bilayer D2O', model='Oxide Model'});
%
% To change the properties of a contrast called 'Contrast 1'.
%
% >>> project.setContrast('Contrast 1', name='new contrast', scalefactor='Scalefactor 1', data='DSPC Bilayer D2O'});
%
% Parameters
% ----------
% row : string or char array or whole number
% If ``row`` is an integer, it is the row number of the contrast to update. If it is text,
% it is the name of the contrast to update.
% options
% Keyword/value pair to properties to update for the specific contrast.
% * name (char array or string, default: '') the name of the contrast.
% * data (char array or string, default: '') the name of the dataset parameter used by the contrast.
% * background (char array or string, default: '') the name of the background for the contrast.
% * backgroundAction (backgroundActions, default: backgroundActions.Add) whether the background should be added to the simulation ('add') or subtracted from the data ('subtract').
% * bulkIn (char array or string, default: '') the name of the bulk-in parameter which defines the SLD of the interface between the first layer and the environment.
% * bulkOut (char array or string, default: '') the name of the bulk-out parameter which defines the SLD of the interface between the last layer and the environment.
% * scalefactor (char array or string, default: '') the name of the scalefactor parameter which defines how much the data for this contrast should be scaled.
% * resolution (char array or string, default: '') the name of the instrument resolution for this contrast.
% * resample (logical, default: false) whether adaptive resampling should be used for interface microslicing.
% * repeatLayers (whole number, default: 1) indicates the number of times the layers should be repeated, this is only supported for standard layers.
% * model (char array or string or cell string) if this is a standard layers model, this should be a list of layer names that make up the slab model for this contrast.
% For custom models, this should be a single custom file name for the custom model function.
arguments
obj
row
options.name
options.data
options.background
options.backgroundAction
options.bulkIn
options.bulkOut
options.scalefactor
options.resolution
options.resample
options.repeatLayers
options.model
end
args = namedargs2cell(options);
obj.contrasts.setContrast(row, obj.getAllAllowedNames(), args{:});
end

function obj = setContrastModel(obj, 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
% Updates the model of an existing contrast.
%
% Examples
% --------
% To change the model of the second contrast in the project.
%
% >>> project.setContrastModel(2, 'Oxide Model'});
%
% project.setContrastModel(1, {'layer 1'})
% project.setContrastModel(1:3, {'layer 1'})
allowedValues = obj.getAllAllowedNames();
% To change the properties of a contrast called 'Contrast 1'.
%
% >>> project.setContrastModel('Contrast 1', 'Oxide Model');
%
% To change multiple contrasts at once. The snippet below will change 1, 2, and 3.
%
% >>> project.setContrastModel(1:3, {'Layer 1', 'Layer 2'});
%
% Parameters
% ----------
% row : string or char array or whole number
% If ``row`` is an integer, it is the row number of the contrast to update. If it is text,
% it is the name of the contrast to update.
% model: char array or string or cell string
% If this is a standard layers model, this should be a list of layer names that make up the slab model for this contrast.
% For custom models, this should be a single custom file name for the custom model function.

% Call the setContrastModel method
if isText(row)
Expand All @@ -1098,7 +1189,7 @@ function delete(obj)
row = num2cell(row);
end
for i=1:length(row)
obj.contrasts.setContrastModel(row{i}, allowedValues, model);
obj.setContrast(row{i}, model=model);
end
end

Expand Down Expand Up @@ -1281,7 +1372,7 @@ function writeScript(obj, options)

% Need to treat contrasts separately due to changes in the
% class for domains calculations
domainsObj.contrasts = copyProperties(obj.contrasts, contrastsClass(domains=true));
domainsObj.contrasts = copyProperties(obj.contrasts, contrastsClass(true));
for i=1:domainsObj.contrasts.numberOfContrasts
domainsObj.contrasts.contrasts{i}.domainRatio = '';
end
Expand Down
Binary file modified examples/tutorialFiles/twoContrastExample.mat
View file
Open in desktop
Binary file not shown.
4 changes: 2 additions & 2 deletions minimisers/DREAM/functions/metropolisRule.m
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,10 +27,10 @@
% Calculate the likelihood ratio
alfa_L = exp ( log_L_xnew - log_L_xold );

% Calculate the prior ration
% Calculate the prior ratio
alfa_PR = exp ( log_PR_xnew - log_PR_xold );

% Calculate product of two probabily ratios
% Calculate product of two probability ratios
alfa = alfa_L .* alfa_PR;

% Generate random numbers
Expand Down
4 changes: 2 additions & 2 deletions targetFunctions/common/callReflectivity/applyBackgroundCorrection.m
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,11 @@
backError = background(lowIndex:highIndex,3);

switch backgroundAction
case coderEnums.actions.Add
case coderEnums.backgroundActions.Add
% Add the data to the simulation
reflectivity(:,2) = reflectivity(:,2) + backData;
simulation(:,2) = simulation(:,2) + background(:,2);
case coderEnums.actions.Subtract
case coderEnums.backgroundActions.Subtract
% Subtract the background data from the shiftedData
shiftedData(:,2) = shiftedData(:,2) - backData;
shiftedData(:,3) = sqrt(shiftedData(:,3).^2 + backError.^2); % Propagate the errors
Expand Down
2 changes: 1 addition & 1 deletion tests/domainsTFReflectivityCalculation/domainsCustomLayers.m
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@
project.addContrast('name', 'D2O Conrast', ...
'Data', 'Simulation',...
'Background', 'Background 1',...
'backgroundAction', actions.Add,...
'backgroundAction', backgroundActions.Add,...
'bulkIn', 'Silicon',...
'bulkOut', 'SLD D2O',...
'Scalefactor','Scalefactor 1', ...
Expand Down
Binary file modified tests/domainsTFReflectivityCalculation/domainsCustomLayersInputs.mat
View file
Open in desktop
Binary file not shown.
Binary file modified tests/domainsTFReflectivityCalculation/domainsCustomLayersOutputs.mat
View file
Open in desktop
Binary file not shown.
Binary file modified tests/domainsTFReflectivityCalculation/domainsCustomLayersTFParams.mat
View file
Open in desktop
Binary file not shown.
Loading