Setup and Import

f_user_input

Code

function [settings, results, sb] = f_user_input(model_folders, analysis_options, user_choices)
% This function processes user input for model, analysis options, and
% settings files, and returns settings, results, and sbTab data structures.
% It utilizes helper functions to validate user input, apply settings, and
% manage persistent variables.
%
% Inputs:
% - model_folders: Model folders structure
% - analysis_options: Array of available analysis options
% - user_choices: Cell array of user input choices for model folder,
% analysis, and settings
%
% Outputs:
% - settings: Struct containing all settings for the chosen analysis
% - results: Struct containing the results of the analysis
% - sbTab: Struct containing SBtab data
%
% Used Functions:
% - getValidInput: Validates user input for model folder, analysis option,
% and settings file
% - apply_settings: Updates settings based on chosen settings file and
% checks for changes
% - choose_options: Helps user choose valid options from available choices
% - parse_choices: Presents list of choices to user and validates input
% - compare_and_update: Checks if current and previous values are different
% and clears functions if necessary
%
% Variables:
% Loaded:
% - None
%
% Initialized:
% - results: Empty struct for storing analysis results
% - settings: Empty struct for storing analysis settings
% - sbTab: Empty struct for storing SBtab data
%
% Persistent:
% - last_settings_file_text: Stores the last settings file text
% - last_settings_file_date: Stores the last settings file date
% - last_model_folder: Stores the last chosen model folder
% - last_analysis_text: Stores the last chosen analysis option
% - last_settings_file_text: Stores the last chosen settings file text
% - last_SBtab_date: Stores the last SBtab date
% - functions_cleared: Flag indicating if functions have been cleared or
% not



% Define persistent variables to store the last settings file text and
% date.
persistent last_settings_file_text
persistent last_settings_file_date

% Initialize the results, settings and sbTab variables.
results = [];
settings = [];
sb = [];
functions_cleared = 0;

% Set model folder paths
general_model_folder = model_folders.main + "Model/";

% Get the valid model folder based on user input.
model_folder =...
    getValidInput(general_model_folder, user_choices{1}, "model folder");
specific_model_folder = general_model_folder + model_folder;

% Get the valid analysis option based on user input.
analysis_text =...
    getValidInput(analysis_options, user_choices{2}, "analysis option");

% Store the name of the chosen analysis in the settings struct
settings.analysis = analysis_text;

% Process user input for analysis options 1-5 and 8
if any(contains(analysis_options([1:5, 8]), analysis_text))

    % Set settings folder path based on user input
    settings_folder = specific_model_folder + "/Matlab/Settings/";
    settings_file_text =...
        getValidInput(settings_folder, user_choices{3}, "settings file");

    % Apply settings and return the settings struct
    [settings,last_settings_file_text,last_settings_file_date] = ...
        apply_settings(settings, settings_folder, settings_file_text,...
        last_settings_file_date,last_settings_file_text, analysis_options,...
        analysis_text, specific_model_folder, functions_cleared);

    % Process user input for analysis options 6-7
elseif any(contains(analysis_options(6:7), analysis_text))

    % Set results folder path
    results_folder = specific_model_folder + "/Matlab/Results";

    % Get the analysis to be reproduced based on user input.
    last_choice = [];
    prompt = "\nWhat analysis should be reproduced?\n";

    [r_analysis_text,~] =...
        choose_options(results_folder,prompt,last_choice);

    specific_results_folder = results_folder + "/" + ...
        r_analysis_text;

    % Get the date of the original analysis based on user input.
    last_choice = [];
    prompt = "\nWhen was this analysis run originaly?\n";

    [r_analysis_date_text,~] =...
        choose_options(specific_results_folder,prompt,last_choice);

    specific_results_folder_date = specific_results_folder + "/" + ...
        r_analysis_date_text;

    % Load the settings file and the SBtab struct
    load(specific_results_folder_date + "/Analysis.mat","settings","sb")

    % Set inport to false since we don't want to overwrite anything
    settings.import = false;

    % If the reproduction of an analysis is chosen, clear the functions
    % because the settings most likely changed.
        f_functions_to_clear()

    % If the reproduction of the plots of an analysis is chosen, set the
    % code to produce plots and load the results that were previously
    % obtained.
    if contains(analysis_options(7),analysis_text)
        % Store the name of the chosen analysis in the settings struct
        settings.analysis = analysis_text;

        settings.plot = true;
        load(specific_results_folder_date + "/Analysis.mat","results")
    end
end

% % Store the name of the chosen analysis in the settings struct
% settings.analysis = analysis_text;

% Set the chosen model folder in the settings struct
settings.folder_model = model_folder;
end

function [settings, last_settings_file_text, last_settings_file_date] = ...
    apply_settings(settings, settings_folder, settings_file_text, ...
    last_settings_file_date, last_settings_file_text, analysis_options, ...
    analysis_text, specific_model_folder, functions_cleared)
% Function apply_settings updates the settings based on the chosen settings
% file and checks if any changes have been made to the settings file or the
% SBtab since the last analysis

persistent last_SBtab_date

settings_file = strrep(settings_file_text, ".m", "");

% Add the default settings to the struct
stg_add_default = eval("default_settings()");

% Iterate through the fields of the default settings struct and add them to
% the settings struct
f = fieldnames(stg_add_default);
for i = 1:length(f)
    settings.(f{i}) = stg_add_default.(f{i});
end

% Add chosen settings to the struct overwriting defaults when appropriate
[stg_add] = eval(settings_file + "()");

% Iterate through the fields of the chosen settings struct and add them to
% the settings struct, overwriting the default values if necessary
f = fieldnames(stg_add);
for i = 1:length(f)
    settings.(f{i}) = stg_add.(f{i});
end

% Check if the date of the settings file changed, if so clear functions
listing = dir(settings_folder);
for n = 1:size(listing, 1)
    if matches(settings_file_text, listing(n).name, "IgnoreCase", true)
        settings_file_date = listing(n).date;
    end
end

if isempty(last_settings_file_date)
    settings.import = true;
else
    settings.import = false;
end

% Check if the date of the settings file changed, if so clear functions
[last_settings_file_date, functions_cleared] = ...
    compare_and_update(settings_file_date, last_settings_file_date, functions_cleared);

% Check if the name of the settings file changed, if so clear functions
[last_settings_file_text, functions_cleared] = ...
    compare_and_update(settings_file_text, last_settings_file_text, functions_cleared);

% Check if the date of the SBtab changed, if so clear functions
listing = dir(specific_model_folder);

for n = 1:size(listing, 1)
    if matches(settings.sbtab_excel_name, listing(n).name, "IgnoreCase", true)
        sbtab_date = listing(n).date;
    end
end

[last_SBtab_date, functions_cleared] = ...
    compare_and_update(sbtab_date, last_SBtab_date, functions_cleared);

if functions_cleared == 1
    settings.import = true;
end

if contains(analysis_options(8), analysis_text)
    settings.import = true;
    settings.save_results = false;
    settings.plot = false;
end
end

function valid_input = getValidInput(options, user_choice, input_type)
% Function getValidInput validates the user input for the model folder,
% settings file, and analysis option

persistent last_model_folder
persistent last_analysis_text
persistent last_settings_file_text

valid_input = user_choice;

% Check the validity of the input based on the input_type
switch input_type
    case "model folder"

        % If the input is a valid model folder, return it
        if isstring(user_choice) && isfolder(options + valid_input)
            disp("The " + input_type + " chosen was: " + valid_input)
            return;
            % Otherwise, prompt the user to choose a valid one
        else
            disp("The chosen " + input_type + " is not valid, please choose a valid " + input_type)
            prompt = "What " + input_type + " should be used?\n";
            [valid_input, last_model_folder] = choose_options(options, prompt, last_model_folder);
        end

    case "settings file"
        % If the input is a valid settings file, return it
        if isstring(user_choice) && isfile(options + valid_input)
            disp("The " + input_type + " chosen was: " + valid_input)
            return;
            % Otherwise, prompt the user to choose a valid one
        else
            disp("The chosen " + input_type + " is not valid, please choose a valid " + input_type)
            prompt = "What " + input_type + " should be used?\n";
            [valid_input, last_settings_file_text] = choose_options(options, prompt, last_settings_file_text);
        end
    case "analysis option"
        % If the input is not a valid analysis, prompt the user to choose a
        % valid analysis
        if isstring(user_choice) || ~(user_choice >= 1) || ~(user_choice <= 8)
            disp("The chosen " + input_type + " is not valid, please choose a valid " + input_type)
            prompt = "What " + input_type + " should be used?\n";
            [valid_input, last_analysis_text] = parse_choices(prompt, options, last_analysis_text);
            % Otherwise, if the analysis is valid, return it
        else
            valid_input = options(user_choice);
            disp("The " + input_type + " chosen was: " + valid_input)
        end
end
end

function [choice, last_choice] = choose_options(folder, prompt, last_choice)
% Function choose_options helps user to choose valid options from available
% choices

listing = dir(folder);

% Remove unnecessary entries from the listing
for n = size(listing, 1):-1:1
    if any(matches(listing(n).name, [".", "..", "Place models here.txt"]))
        listing(n) = [];
    end
end

% Create an options array containing the names of the valid choices
for n = 1:size(listing, 1)
    folder(n) = string(listing(n).name);
end

% Call parse_choices to handle user input
[choice, last_choice] = parse_choices(prompt, folder, last_choice);
end

function [choice, last_choice] = parse_choices(prompt, options, last_choice)
% Function parse_choices presents a list of choices to the user and
% validates their input, then returns the chosen option

% Build the prompt string with the available options
for n = 1:size(options, 2)
    prompt = prompt + "\n" + n + ": " + options(n);
end

% If there's a last_choice, include it in the prompt as the default
if ~isempty(last_choice)
    if any(contains(options, last_choice))
        prompt = prompt + "\n\nPress enter to use " + last_choice;
    else
        last_choice = [];
    end
end

prompt = prompt + "\n";

% Get userinput and handle it accordingly
i = input(prompt);

% If the user input is empty, set the choice to an empty array
if isempty(i)
    choice = [];
    % If the user input is a valid index, set the choice to the
    % corresponding option
elseif i > 0 && i < size(options, 2) + 1
    choice = options(i);
    disp("The option chosen was: " + choice)
    % If the user input is invalid, call parse_choices recursively with an
    % updated prompt
else
    prompt = "Please choose from the provided options";
    [choice, last_choice] = parse_choices(prompt, options, last_choice);
end

% If the choice is empty and there's a last_choice, set the choice to
% last_choice
if isempty(choice)
    if ~isempty(last_choice)
        choice = last_choice;
        disp("The option chosen was: " + last_choice)
    else
        prompt = "Please choose from the provided options";
        [choice, last_choice] = parse_choices(prompt, options, last_choice);
    end
else
    last_choice = choice;
end
end

function [previous, is_cleared] = compare_and_update(current, previous, is_cleared)
% Function compare_and_update checks if the current and previous values are
% different and clears the functions if necessary

% If there's a previous value, compare it with the current value
if ~isempty(previous)
    % If the current and previous values are different, clear functions if
    % not already cleared
    if ~contains(current, previous)
        if is_cleared == false
            disp("Settings file changed, clearing functions")
            f_functions_to_clear()
            is_cleared = true;
        end
    end
end
% Update the previous value to the current value
previous = current;
end

In this code, the main function f_user_input is responsible for processing user inputs related to model folder, analysis options, and settings file. Based on these inputs, the function returns the necessary settings, results, and SBtab data.

Inputs:

• mmf: a struct containing the main folder path.

• analysis_options: an array containing the available analysis options.

• user_choices: a cell array containing user inputs for the model folder, analysis option, and settings file.

Outputs:

• settings: a struct containing the necessary settings for the chosen analysis.

• results: a struct containing the results (if any) of the chosen analysis.

• sbTab: a struct containing the SBtab data (if any) associated with the chosen analysis.

The main function relies on several helper functions to process the user input, update settings, and handle user choices.

1. apply_settings: This function updates the settings based on the chosen settings file, and checks if any changes have been made to the settings file or SBtab since the last analysis.

   Inputs: settings, settings_folder, settings_file_text, last_settings_file_date, last_settings_file_text, analysis_options, analysis_text, specific_model_folder, functions_cleared

   Outputs: settings, last_settings_file_text, last_settings_file_date

2. getValidInput: This function validates the user input for the model folder, settings file, and analysis option, and returns the valid input.

   Inputs: options, user_choice, input_type

   Outputs: valid_input

3. choose_options: This function helps the user to choose valid options from available choices in a folder.

   Inputs: folder, prompt, last_choice

   Outputs: choice, last_choice

4. parse_choices: This function presents a list of choices to the user, validates their input, and returns the chosen option.

   Inputs: prompt, options, last_choice

   Outputs: choice, last_choice

5. compare_and_update: This function compares the current and previous values, and clears functions if necessary.

   Inputs: current, previous, is_cleared

   Outputs: previous, is_cleared

The main function starts by initializing the results, settings, and sbTab variables, and setting the model folder paths. It then calls the getValidInput function to obtain valid user input for the model folder and analysis option. Depending on the user’s chosen analysis option, the code proceeds differently. For analysis options 1-5 and 8, the apply_settings function is called to update the settings. For analysis options 6-7, the function loads the settings file and SBtab struct from a previous analysis, and processes the user input accordingly. Finally, the chosen model folder is set in the settings struct, and the function returns the updated settings, results, and sbTab data.

f_import

Code

function [settings,sb] = f_import(settings,model_folder)
% Function f_import: Import a model from an SBtab file, generate model
% files, and setup necessary inputs for experiments
%
% Inputs:
% - settings: A struct containing settings for the model import process
% - model_folder: A string specifying the folder where the model and
% related files should be saved
%
% Outputs:
% - settings: Updated struct with additional information about the number
% of experiments and outputs
% - sb: A struct containing data from the imported SBtab file
%
% Used Functions:
% - f_excel_sbtab_importer: Converts an SBtab file into a .mat file and tsv
% files
% - f_generate_sbtab_struct: Generates a struct based on the SBtab and
% updates settings with the number of experiments and outputs
% - f_sbtab_to_model: Saves the model in .mat, .sbproj, and .xml formats,
% and creates a data file with required settings for running the model in
% various experimental settings
% - f_setup_input: Generates code to load inputs for each experiment into a
% .mat file and creates code to read these inputs during simulation
% - f_build_model_exp: Creates .mat files for each experiment containing
% rules, species, and parameters based on the SBtab for equilibrium,
% default, and detailed simulation runs
%
% Variables:
% Loaded:
% - None
%
% Initialized:
% - None
%
% Persistent:
% - None

disp("Generating model files and folder from SBtab")

% Convert the SBtab file into a .mat file and tsv files
f_excel_sbtab_importer(model_folder);

% Creates a struct based on the SBtab that is used elswhere in the code and
% also adds the number of experiments and outputs to the settings struct
[settings,sb] = f_generate_sbtab_struct(settings,model_folder);

% Save the model in .mat, .sbproj, and .xml formats, and create a data file
% with the required settings for running the model in various  experimental
% settings defined in the SBtab
f_sbtab_to_model(settings,sb,model_folder)

% Generate code to load inputs for each experiment into a .mat file, and
% create code to read these inputs during simulation, stored in the Input
% functions folder
f_setup_input(settings,model_folder)

% Create three .mat files for each experiment containing the necessary
% rules, species, and parameters based on the SBtab, for equilibrium,
% default, and detailed simulation runs
f_build_model_exp(settings,sb,model_folder)

disp("Model files and folders generated successfully")
end

Creates the necessary folders inside the model folder. Calls subfunctions that convert the SBtab from an Excel into MATLAB® files useful for the workflow, TSVs and a SBML.

f_excel_sbtab_importer

Code

function f_excel_sbtab_importer(model_folders)
% This function, f_excel_sbtab_importer, takes a model_folders structure as
% input, which contains paths to the source Excel SBtab file and the
% destination folders for the parsed data (MATLAB .mat file) and TSV files.
% The function processes the Excel file with multiple sheets in the SBtab
% format, imports the data from each sheet, replaces missing values with
% empty spaces, and exports the processed data as .mat and TSV files.
%
% Inputs:
% - model_folders: A structure containing the following fields:
% - model.sbtab: Path to the source Excel SBtab file.
% - model.data.sbtab: Path to the destination folder for the parsed .mat
% file.
% - model.tsv.model_name: Path to the destination folder for the TSV files.
%
% Outputs: - No direct output. The parsed data is saved as .mat and TSV
% files in the specified folders.
%
% Functions called:
% - impexp: This function is called for each sheet in the Excel SBtab file.
% It imports the sheet's data, replaces missing values with empty spaces,
% and exports the processed data as a TSV file.
% - cell_write_tsv: This function writes the data in a cell array to a TSV
% file, taking care of transposing the array and converting numeric values
% to strings.
% 
% Variables:
% Loaded:
% - Source_sbtab: Path to the source Excel SBtab file.
% - Matlab_sbtab: Path to the destination folder for the parsed .mat file.
% - sheets: Cell array containing the names of sheets in the Excel SBtab
% file.
% - sbtab_excel: A cell array containing the processed data for each sheet.
%
% Initialized:
% - None
%
% Persistent:
% - None


% Get the folders for the model SBtab file and the destination for the
% parsed data
Source_sbtab = model_folders.model.sbtab;
Matlab_sbtab = model_folders.model.data.sbtab;

% Get the total number of sheets in the SBTAB
sheets = sheetnames(Source_sbtab);

% Attempt to run the import of sheets in parallel, depending on the version
% of Excel being used, this may not work
try
    parfor i = 1:size(sheets,1)
        sbtab_excel{i} = impexp (i,model_folders);
    end
catch
    for i = 1:size(sheets,1)
        sbtab_excel{i} = impexp (i,model_folders);
    end
end

% Save the parsed SBTAB tables in .mat format
save(Matlab_sbtab,'sbtab_excel');
disp("SBtab with " + size(sheets,1) + " sheets parsed successfully")
end

function sbtab_excel = impexp (i,model_folders)

% Load the source SBTAB file and the folder to save the TSV files
Source_sbtab = model_folders.model.sbtab;
tsv_name_folder = model_folders.model.tsv.model_name;

% Import the SBTAB sheet as a cell array
sbtab_excel = readcell(Source_sbtab,'sheet',i);

% Replace missing values with empty spaces
mask = cellfun(@ismissing, sbtab_excel,'UniformOutput',false);
mask = cellfun(@min, mask);
mask = logical(mask);
sbtab_excel(mask) = {[]};

% Get the name for the TSV file to be exported
field = regexp(sbtab_excel{1,2},"TableName='[^']*'",'match');
field = string(replace(field,["TableName='","'"," "],["","","_"]));

% Export the TSV file
cell_write_tsv(tsv_name_folder + field + ".tsv",sbtab_excel)
end

function cell_write_tsv(filename,origCell)

% Create a new version of the cell for reference
modCell = origCell;

% Find the indices of numeric cells
iNum = cellfun(@isnumeric,origCell);

% % Replace numeric cells with cell strings
for n = 1:size(iNum,1)
    for m = 1:size(iNum,2)
        modCell(n,m) = cellstr(num2str(origCell{n,m}));
    end
end

% Transpose the cell array to have the correct orientation
modCell = transpose(modCell);

% Create a format string for saving the TSV file
[rNum,cNum] = size(origCell);
frmt = repmat([repmat('%s\t',1,cNum-1),'%s\n'],1,rNum);
fid = fopen(filename,'wt');

% Save the TSV file using the format string
fprintf(fid,frmt,modCell{:});
fclose(fid);
end

Loads the information in the SBtab and creates a . mat file that contains the sbtab and TSVs corresponding to all the SBtab tabs.

• Inputs - stg

• Saves

  • .mat file containing the SBtab in the “Model/Data” folder

  • TSVs containing the SBtab in the “Model/tsv” folder

f_generate_sbtab_struct

Code

function [stg,sb] = f_generate_sbtab_struct(stg,mmf)
% This function is used to load an SBtab data file, convert the SBtab data
% into a structure, and extract the number of experiments and outputs. The
% function takes two input arguments, stg and mmf, and returns two output
% arguments, the modified stg and the generated sb structure. The function
% calls the helper function convert_sbtab_to_struct to convert the SBtab
% data into a structure. The SBtab data file is loaded into the variable
% sbtab_excel.
%
% Inputs:
% - stg: An existing structure that will be updated with the number of
% experiments and outputs.
% - mmf: A structure containing the model information, including the SBtab
% data file name.
%
% Outputs:
% - stg: The updated structure containing the number of experiments
% and outputs.
% - sb: A structure generated from the SBtab data.
%
% Called functions:
% - convert_sbtab_to_struct: A helper function that converts SBtab data
% into a structure.
%
% Variables:
% Loaded:
% sbtab_excel: A variable that holds the loaded SBtab data from the
% specified file.
%
% Initialized:
% - None
%
% Persistent:
% - None


% Extract the sbtab file name from the mmf structure
Matlab_sbtab = mmf.model.data.sbtab;

% Check if the sbtab file exists
if isfile(Matlab_sbtab)

    % Load the sbtab data into a variable called 'sbtab_excel'
    load(Matlab_sbtab,'sbtab_excel');

    % Convert the sbtab data into a structure
    sb = convert_sbtab_to_struct(sbtab_excel);

    % Extract the number of experiments and outputs
    stg.expn = size(sb.Experiments.ID,1);
    stg.outn = size(sb.Output.ID,1);
end
end

% Helper function that converts sbtab data into a structure
function sb = convert_sbtab_to_struct(sbtab_excel)

% Initialize an empty structure
sb = struct();

% Loop through all columns in the sbtab data
for col = 1:size(sbtab_excel,2)

    % Check if the first row of the column contains a table name
    if ~isempty(sbtab_excel{1,col}{1,2})

        % Extract the table name from the first row of the column
        field =...
            regexp(sbtab_excel{1,col}{1,2},...
            "TableName='([^']*)'", 'tokens');
        field = string(replace(field{1}, " ", "_"));

        % Loop through all rows in the column
        for row = 1:size(sbtab_excel{1,col},2)

            % Check if the current row contains a subfield name
            if ~isempty(sbtab_excel{1,col}{2,row})
                % Extract the subfield name from the current row
                subfield = sbtab_excel{1,col}{2,row};
                subfield = regexprep(subfield, '[!>]', '');
                subfield = regexprep(subfield, '[:\s]', '_');

                % Extract the subfield values from the column
                sb.(field).(subfield)(:,1) = sbtab_excel{1,col}(3:end,row)';

                % Remove empty values from the subfield
                sb.(field).(subfield) = sb.(field).(subfield)...
                    (~cellfun('isempty', sb.(field).(subfield)));
            end
        end
    end
end
end

Loads the SBtab saved in the .mat file and creates a MATLAB® struct that can be more easily parsed.

• Inputs - stg

• Outputs - sb, stg.expn, stg.outn.

f_sbtab_to_model

Code

function f_sbtab_to_model(stg,sb,mmf)
% This function, f_sbtab_to_model, converts an SBtab data structure into a
% model format that can be used for simulations and analysis. It then saves
% the model in .mat, .sbproj, and .xml formats for future use. The function
% also processes experimental settings defined in the SBtab data structure,
% adding compartments, species, parameters, reactions, expressions, inputs,
% constants, and boundary conditions to the model.
% 
% Inputs:
% - stg: Settings structure containing configuration information
% - sb: SBtab data structure containing information about species,
% reactions, compartments, and parameters
% - mmf: Model management files structure containing the paths to save the
% model
%
% Outputs:
% - No direct outputs, but the function saves the model in .mat, .sbproj,
% and .xml formats
%
% Used Functions:
% - add_reactions_to_model: Adds reactions from the SBtab data structure to
% the model object
% - set_boundary_Condition: Sets boundary conditions for the model
% - add_expressions_to_model: Adds expressions from the SBtab data
% structure to the model object
% - add_inputs_to_model: Adds inputs from the SBtab data structure to the
% model object
% - add_constants_to_model: Adds constants from the SBtab data structure to
% the model object
% - process_experiments: Processes experimental data from the SBtab data
% structure
%
% Variables
% Loaded:
% - sbtab.species: Species related data from the SBtab data structure
% - sbtab.defpar: Default parameter related data from the SBtab data
% structure
% - sbtab.sim_time: Simulation time extracted from the SBtab data structure
%
% Initialized:
% - modelobj: Initialized model object
% - compobj: Initialized compartment object
%
% Persistent:
% - None

% Initialize the model object and compartment object
modelobj = sbiomodel(stg.name);
compobj = [];

% Combine species related data into sbtab.species
sbtab.species = [sb.Compound.Name, sb.Compound.InitialValue, sb.Compound.IsConstant, sb.Compound.Unit, sb.Compound.Location];
% Combine default parameter related data into sbtab.defpar
sbtab.defpar = [sb.Parameter.Comment, sb.Parameter.Value_linspace, sb.Parameter.Unit];

% Add compartments to the model Iterate through each compartment in the
% SBtab data structure and add it to the model
for n = 1:size(sb.Compartment.ID,2)
    compobj{n} = addcompartment(modelobj, sb.Compartment.Name{n});
    set(compobj{n}, 'CapacityUnits', sb.Compartment.Unit{n});
    set(compobj{n}, 'Value', sb.Compartment.Size{n});
end

% Add species to the compartments Iterate through each species in the SBtab
% data structure and add it to the appropriate compartment
for n = 1:size(sbtab.species,1)
    compartment_number_match = find_compartment_number(compobj, sb.Compound.Location{n});
    addspecies (compobj{compartment_number_match}, sb.Compound.Name{n},...
        sb.Compound.InitialValue{n}, 'InitialAmountUnits', sb.Compound.Unit{n});
end

% Add species to the compartments Iterate through each species in the SBtab
% data structure and add it to the appropriate compartment
for n = 1:size(sbtab.defpar,1)
    addparameter(modelobj,sb.Parameter.Name{n},...
        sb.Parameter.Value_linspace{n},'ValueUnits',sb.Parameter.Unit{n},'Notes',sb.Parameter.Comment{n});
end

% Add reactions, expressions, inputs, constants, and boundary conditions to
% the model
modelobj = add_reactions_to_model(sb,modelobj);
modelobj = set_boundary_Condition(sb,modelobj);
modelobj = add_expressions_to_model(sb,modelobj);
modelobj = add_inputs_to_model(sb,modelobj);
modelobj = add_constants_to_model(sb,modelobj);

% Extract simulation time from the SBtab data structure
sbtab.sim_time = [sb.Experiments.Sim_Time{:}];
% Process experimental data from the SBtab data structure
[sbtab,Data] = process_experiments(sb,sbtab);

% Save the model in .mat, .sbproj, and .xml formats
sbproj_model = mmf.model.data.sbproj_model;
matlab_model = mmf.model.data.mat_model;
data_model = mmf.model.data.data_model;
xml_model = mmf.model.data.xml_model;

sbiosaveproject(sbproj_model,'modelobj')
save(matlab_model,'modelobj')
save(data_model,'Data','sbtab','sb')
sbmlexport(modelobj,xml_model)
end

function modelobj = add_constants_to_model(sb,modelobj)
% This function adds constants from sb to the given model object. This
% function checks if the sb structure has a "Constant" field, and if so,
% iterates through the constants and adds them as parameters to the model
% object.

% Check if the sb object has a "Constant" field
if isfield(sb,"Constant")
    % Iterate through the constants and add them to the model object
    for m = 1:size(sb.Constant.ID,1)
        addparameter(modelobj,char(sb.Constant.Name(m)),...
            str2double(string(sb.Constant.Value{m})),...
            'ValueUnits',sb.Constant.Unit{m});
    end
end
end

function modelobj = add_inputs_to_model(sb,modelobj)
% This function adds inputs from sb to the given model object. This
% function checks if the sb structure has an "Input" field, and if so,
% iterates through the inputs and adds them as parameters, species, and
% rules to the model object according to the input properties.

% Check if the sb structure contains the 'Input' field
if isfield(sb,"Input")
    % Iterate through all inputs
    for m = 1:size(sb.Input.ID,1)
        % Check if the input contains the 'Formula' field
        if isfield(sb.Input,'Formula')
            % If the input formula is a double, add it as a species
            if isa(sb.Input.Formula{m},'double')
                addspecies (modelobj, char(sb.Input.Name(m)),...
                    str2double(string(sb.Input.DefaultValue{m})),...
                    'InitialAmountUnits',sb.Input.Unit{m});
                % Otherwise, try adding it as a species with initial amount
                % 0
            else
                try
                    addspecies (modelobj, char(sb.Input.Name(m)),0,...
                        'InitialAmountUnits',sb.Input.Unit{m});
                catch
                end
                % Add a rule for the species using the input formula
                addrule(modelobj, char({convertStringsToChars(...
                    string(sb.Input.Location{m}) + "." +...
                    string(sb.Input.Name{m}) + " = " +...
                    string(sb.Input.DefaultValue{m}))}),...
                    'repeatedAssignment');
            end
        else
            % If no 'Formula' field, add the input as a parameter
            addparameter(modelobj,char(sb.Input.Name(m)),...
                str2double(string(sb.Input.DefaultValue{m})),...
                'ValueUnits',sb.Input.Unit{m});
        end
    end
end
end

function compartment_number = find_compartment_number(compobj, location)
% This function finds the compartment number in compobj corresponding to
% the given location. This function iterates through all compartments in
% compobj and returns the index of the compartment whose name matches the
% given location.

% Iterate through all compartments
for m = 1:size(compobj,2)
    % Check if the current compartment's name matches the given location
    if strcmp(compobj{m}.Name,location)
        % If it matches, return the index and break the loop
        compartment_number = m;
        break;
    end
end
end

function [sbtab,Data] = process_experiments(sb,sbtab)
% This function processes experiments from sb and stores data in sbtab and
% Data. This function extracts relevant data from sb, a structured
% representation of an SBML model, and stores it in sbtab, a structured
% representation of an SBtab file, and Data structures, used for further
% analysis and processing.

% Initialize species_inp_indices to store the indices of species present in
% sb.Experiments
species_inp_indices = {};
% Iterate through sb.Compound.ID to find species present in sb.Experiments
for n = 1:size(sb.Compound.ID, 1)
    field_name = "S" + (n - 1);
    % Check if sb.Experiments has the field specified in field_name
    if isfield(sb.Experiments, field_name)
        species_inp_indices{end + 1, 1} = n;
    end
end
% Iterate through sb.Experiments.ID to process each experiment
for n = 1:size(sb.Experiments.ID,1)
    start_amount = cell(1,size(species_inp_indices,1));
    n_start_amount = 0;
    n_input_time = 0;
    n_input = 0;
    n_output = 0;

    % Check if sb.Experiments has a Normalize field, and store it in
    % sbtab.datasets(n).Normalize
    if isfield(sb.Experiments,"Normalize")
        sbtab.datasets(n).Normalize = sb.Experiments.Normalize{n};
    else
        sbtab.datasets(n).Normalize = [];
    end

    % Retrieve the Time data for the current experiment and store it in
    % Data(n).Experiment.t
    experiment_field_name = "E" + (n - 1);
    if isfield(sb.(experiment_field_name), "Time")
        Data(n).Experiment.t = transpose([sb.(experiment_field_name).Time{:}]);
    end

    % Process input species data for the current experiment
    experiment_input_field_name = "E" + (n - 1) + "I";
    start_amount_name = cell(1, size(species_inp_indices, 1));
    for m = 1:size(sb.Compound.ID, 1)
        field_name = "S" + (m - 1);
        if isfield(sb.Experiments, field_name)
            n_start_amount = n_start_amount + 1;
            start_amount{n_start_amount} = sb.Experiments.(field_name)(n);
            start_amount_name{n_start_amount} = sb.Compound.Name(m);
        end
        % Retrieve input time data for the current experiment and species
        if isfield(sb.(experiment_input_field_name), "Input_Time_S" + (m - 1))
            n_input_time = n_input_time + 1;
            sbtab.datasets(n).input_time{1, n_input_time} = ...
                [sb.(experiment_input_field_name).("Input_Time_S" + (m - 1)){:}];
        end
        % Retrieve input value data for the current experiment and species
        if isfield(sb.(experiment_input_field_name), "S" + (m - 1))
            n_input = n_input + 1;
            sbtab.datasets(n).input_value{1, n_input} = ...
                [sb.(experiment_input_field_name).("S" + (m - 1)){:}];
            sbtab.datasets(n).input{n_input} = char("S" + (m - 1));
        end
    end

    % Process output data for the current experiment
    for m = 1:size(sb.Output.ID, 1)
        if isfield(sb.(experiment_field_name), "Y" + (m - 1))
            n_output = n_output + 1;
            % Retrieve output values for the current experiment and output
            Data(n).Experiment.x(:, n_output) = ...
                [sb.(experiment_field_name).("Y" + (m - 1)){:}];
            % Retrieve standard deviation of output values for the current
            % experiment and output
            Data(n).Experiment.x_SD(:, n_output) = ....
                [sb.(experiment_field_name).("SD_Y" + (m - 1)){:}];
            % Store output related information in sbtab.datasets(n)
            sbtab.datasets(n).output{n_output} = sb.Output.Name(m);
            sbtab.datasets(n).output_value{n_output} = ...
                {convertStringsToChars(...
                strrep(string(sb.Output.Location{m}) + "." + ...
                string(sb.Output.Name{m}) + " = " + ...
                string(sb.Output.Formula{m}), 'eps', '0.0001'))};
            sbtab.datasets(n).output_unit{n_output} = sb.Output.Unit{m};
            sbtab.datasets(n).output_name{n_output} = sb.Output.Name(m);
            sbtab.datasets(n).output_ID{n_output} = sb.Output.ID(m);
            sbtab.datasets(n).output_location{n_output} = sb.Output.Location(m);
        end
    end
    % Store output count and start amount information in sbtab.datasets(n)
    sbtab.datasets(n).stg.outnumber = n_output;
    sbtab.datasets(n).start_amount = cat(2,start_amount_name(:),...
        transpose([start_amount{:}]),species_inp_indices);
end
end


function model_obj = add_expressions_to_model(sb,model_obj)
% This function adds expressions to the given model object by iterating
% through sb.Expression fields and populating the model object with
% parameters, species, and rules according to the expression properties

% Check if the sb structure contains the 'Expression' field
if isfield(sb,"Expression")
    % Iterate through all expressions
    for m = 1:size(sb.Expression.ID,1)
        % Check if the expression contains the 'Formula' field
        if isfield(sb.Expression,'Formula')
            % If the expression formula is a double, add it as a species
            if isa(sb.Expression.Formula{m},'double')
                addspecies (model_obj, char(sb.Expression.Name(m)),...
                    str2double(string(sb.Expression.Formula{m})),...
                    'InitialAmountUnits',sb.Expression.Unit{m});
                % Otherwise, try adding it as a species with initial amount
                % 0
            else
                try
                    addspecies (model_obj, char(sb.Expression.Name(m)),0,...
                        'InitialAmountUnits',sb.Expression.Unit{m});
                catch
                end
                % Add a rule for the species using the expression formula
                addrule(model_obj, char({convertStringsToChars(...
                    string(sb.Expression.Location{m}) + "." +...
                    string(sb.Expression.Name{m}) + " = " +...
                    string(sb.Expression.Formula{m}))}),...
                    'repeatedAssignment');
            end
        else
            % If no 'Formula' field, add the expression as a parameter
            addparameter(model_obj,char(sb.Expression.Name(m)),...
                str2double(string(sb.Expression.DefaultValue{m})),...
                'ValueUnits',sb.Expression.Unit{m});
        end
    end
end
end

function model_obj = add_reactions_to_model(sb,model_obj)

num_reactions = size(sb.Reaction.ID, 1);
num_compounds = size(sb.Compound.Name, 1);

% Add reactions to the model
for reaction_idx = 1:num_reactions

    is_reversible = sb.Reaction.IsReversible{reaction_idx};
    reaction_formula = sb.Reaction.ReactionFormula{reaction_idx};
    location = sb.Reaction.Location{reaction_idx};

    % Determine reaction reversibility and modify reaction_name accordingly
    if ischar(is_reversible)
        if contains(is_reversible, "true",'IgnoreCase',true)
            arrow = ' <-> ';
        else
            arrow = ' -> ';
        end
    else
        if is_reversible
            arrow = ' <-> ';
        else
            arrow = ' -> ';
        end
    end
    reaction = strrep(reaction_formula, '<=>', arrow);
    % Add compartment location to the reaction name
    for compound_idx = 1:num_compounds
        compound_name = string(sb.Compound.Name{compound_idx});
        reaction = insertBefore(string(reaction), " " + compound_name,...
            " " + location);
    end

    % Remove extra locations that were added when patterns get recognized
    % twice because we are not matching properly
    while contains(reaction, location + " " + location)
        reaction = strrep(reaction, location + " " + location," " + location);
    end

    % Remove unnecessary spaces and characters
    while contains(reaction,"  ")
        reaction = strrep(reaction,"  "," ");
    end

    % Replace the space between the location and the species with a dot
    reaction = strrep(reaction,...
        location + " ", location+".");

    % Add the location to the first species of the reaction
    reaction = location + "." + reaction;

    % Add the reaction to the model
    reaction_object = addreaction(model_obj,reaction);
    set(reaction_object,'ReactionRate',sb.Reaction.KineticLaw{reaction_idx});
end
end

function model_obj = set_boundary_Condition(sb,model_obj)
% This function sets the boundary conditions for the species in a model
% object based on information in the sb structure.

% Loop over each compound in the sb structure
for n = 1:size(sb.Compound.ID, 1)

    % Extract information about the boundary condition for the current
    % compound
    assignment = sb.Compound.Assignment{n};
    interpolation = sb.Compound.Interpolation{n};
    is_constant = sb.Compound.IsConstant{n};

    % Determine whether the current compound has a boundary condition set
    if ischar(assignment) && contains(lower(assignment), "true")
        % If the assignment field is the string "true", set the boundary
        % condition to 1
        Boundary_Condition = 1;
    elseif isnumeric(assignment) && assignment == 1
        % If the assignment field is the number 1, set the boundary
        % condition to 1
        Boundary_Condition = 1;
    elseif assignment
        Boundary_Condition = 1;
    elseif ischar(interpolation) && contains(lower(interpolation), "true")
        % If the interpolation field is the string "true", set the boundary
        % condition to 1
        Boundary_Condition = 1;
    elseif isnumeric(interpolation) && interpolation == 1
        % If the interpolation field is the number 1, set the boundary
        % condition to 1
        Boundary_Condition = 1;
    elseif interpolation
        Boundary_Condition = 1;
    elseif ischar(is_constant) && contains(lower(is_constant), "true")
        % If the is_constant field is the string "true", set the boundary
        % condition to 1
        Boundary_Condition = 1;
    elseif isnumeric(is_constant) && is_constant == 1
        % If the is_constant field is the number 1, set the boundary
        % condition to 1
        Boundary_Condition = 1;
    elseif is_constant
        Boundary_Condition = 1;
    else
        % If none of the fields indicate a boundary condition, set the
        % boundary condition to 0
        Boundary_Condition = 0;
    end

    model_obj.species(n).BoundaryCondition = Boundary_Condition;
end
end

This function, f_sbtab_to_model, converts an SBtab data structure into a model format that can be used for simulations and analysis. It then saves the model in .mat, .sbproj, and .xml formats for future use. The function also processes experimental settings defined in the SBtab data structure, adding compartments, species, parameters, reactions, expressions, inputs, constants, and boundary conditions to the model.

Inputs

• stg: A structure containing the settings for the model conversion.

• sb: An SBtab data structure containing the model data.

• mmf: A structure containing the file names for saving the model in different formats.

Outputs

The function saves the generated model in .mat, .sbproj, and SBML(.xml) formats.

Functions called:

• addcompartment: Adds a compartment to the SimBiology model object.

• addspecies: Adds a species to a specific compartment within the model.

• addparameter: Adds a parameter to the model, including its value, unit, and associated notes.

• find_compartment_number: Locates the index of the compartment based on its name within the compobj cell array.

• add_reactions_to_model: Adds reactions to the model by processing the reaction-related data in the SBtab data structure.

• set_boundary_Condition: Sets the boundary conditions for the model using the information provided in the SBtab data structure.

• add_expressions_to_model: Adds algebraic expressions to the model using the information provided in the SBtab data structure.

• add_inputs_to_model: Adds input variables to the model using the information provided in the SBtab data structure.

• add_constants_to_model: Adds constant variables to the model using the information provided in the SBtab data structure.

• process_experiments: Processes experimental data from the SBtab data structure and returns the updated SBtab and a Data structure containing the processed experimental data.

• sbiosaveproject: Saves the SimBiology model object as an .sbproj file.

• save: Saves the SimBiology model object as a .mat file, and the experimental data as a separate .mat file.

• sbmlexport: Exports the SimBiology model object as an .xml file in the Systems Biology Markup Language (SBML) format.

Loaded variables:

• modelobj: A SimBiology model object.

• compobj: A cell array containing compartment objects.

• sbtab.species: A table containing species-related data.

• sbtab.defpar: A table containing default parameter-related data.

• sbtab.sim_time: A table containing simulation time data.

• Data: A structure containing processed experimental data.

• sbproj_model, matlab_model, data_model, xml_model: Variables for saving the model in .sbproj, .mat, SBML(.xml) formats, and the experimental data(file), respectively.

f_setup_input

Code

function f_setup_input(stg,mmf)
% The f_setup_input function is designed to generate code for loading
% experiment inputs into a .mat file and create code to read these inputs
% during the simulation of the experiments. The generated code is stored in
% the "Input_functions" folder.
% 
% Inputs:
% - stg: A structure containing information about the simulation settings.
% - mmf: A structure containing information about the model, including the
% model data, main folder, and input functions.
%
% Outputs:
% - This function creates input function files and an input creator function
% file in the "Input_functions" folder. The input functions are used to
% calculate input values based on the simulation time, while the input
% creator function is used to create input data from the sbtab.datasets.
%
% Used Functions :
% - template1: Generates code for input functions.
% - template2: Generates code for the first input of the first experiment in
% the input creator function.
% - template3: Generates code for the rest of the inputs in the input creator
% function.
%
% Loaded Variables:
% - matlab_model: Loaded from mmf.model.data.mat_model.
% - data_model: Loaded from mmf.model.data.data_model.
% - inp_model_data: Loaded from mmf.model.data.input_model_data.
% - Model_folder: Loaded from mmf.model.main.
% - model_input: Loaded from mmf.model.input_functions.input.
% - sbtab: Loaded from the data_model file.
% - modelobj: Loaded from the matlab_model file.


% Load required data from mmf.model.data:
matlab_model = mmf.model.data.mat_model;
data_model = mmf.model.data.data_model;
inp_model_data = mmf.model.data.input_model_data;
Model_folder = mmf.model.main;
model_input = mmf.model.input_functions.input;

% Load the sbtab and modelobj variables from the respective files:
load(data_model,'sbtab')
load(matlab_model,'modelobj');

% Iterate over the experiments and their inputs to generate input functions
% and an input creator function:
for Exp_n = 1:size(sbtab.datasets,2)
    for index = 1:size(sbtab.datasets(Exp_n).input,2)
        % If input size is larger than 100, generate input function file
        % for each input
        if size(sbtab.datasets(Exp_n).input_value{index},2) > 100
            
            % Generate input names by replacing "." with an empty string,
            % and concatenating the "X", "T", "h1", and "h2" suffixes:
            input_name = strrep(modelobj.species(1+str2double(strrep(...
                sbtab.datasets(Exp_n).input(index),'S',''))).name,".","");
            input_X = input_name + "X";
            input_T = input_name + "T";
            input_h1 = input_name + "h1";
            input_h2 = input_name + "h2";
            input_h3 = input_name + "h3";

            % Create a new .m file for each input and write the generated
            % code to that file, based on the template1() function:
            fullFileName = sprintf('%s.m',...
                model_input + Exp_n + "_" + input_name  );

            fileID = fopen(fullFileName, 'wt');

            inp_str = template1();
            inp_str = replace(inp_str,...
                ["SBtab_name","Exp_n","input_name",...
                "input_X", "input_T", "input_h1", "input_h2","input_h3", "inp_model_data",...
                "sbtab.sim_time(Exp_n)"],[stg.name,Exp_n,...
                input_name, input_X, input_T, input_h1,...
                input_h2,input_h3, inp_model_data,...
                sbtab.sim_time(Exp_n)]);

            fprintf(fileID,inp_str);
            fclose(fileID);
        end
    end
end

% Create the input creator function file:
fullFileName = sprintf('%s.m',model_input + "_creator"  );
fileID = fopen(fullFileName, 'wt');

% Write the content of the input creator function:
fprintf(fileID, "function " + stg.name + "_input_creator(~)\n");
helper = 0;
for Exp_n = 1:size(sbtab.datasets,2)
    for index =1:size(sbtab.datasets(Exp_n).input,2)
        if size(sbtab.datasets(Exp_n).input_value{index},2) > 100
            input_name = strrep(modelobj.species(1+str2double(strrep(...
                sbtab.datasets(Exp_n).input(index),'S',''))).name,".","");
            if helper == 0
                helper = 1;
                helper2 = Exp_n;
            end
            % Write code to the input creator function file, using either
            % template2() or template3() functions:
            if index == 1 && Exp_n == helper2
                fprintf(fileID,"load('" + data_model + "','sbtab');\n");
                inp_creator_str = template2();
                inp_creator_str = replace(inp_creator_str,...
                    ["Exp_n", "input_name", "index", "inp_model_data"],...
                    [Exp_n, input_name, index, inp_model_data]);
            else
                inp_creator_str = template3();
                inp_creator_str = replace(inp_creator_str,...
                    ["Exp_n", "input_name", "index", "inp_model_data"],...
                    [Exp_n, input_name, index, inp_model_data]);
            end
            fprintf(fileID,inp_creator_str);
        end
    end
end
fprintf(fileID, "end\n");
fclose(fileID);

eval(stg.name + "_input_creator()");
end

% The template1() function generates the code for the input functions,
% which calculate the input based on the simulation time.
function inp_str = template1()
inp_str =...
    "function thisAmp = SBtab_name_inputExp_n_input_name(times)\n"+...
    "persistent input_X\n"+...
    "persistent input_T\n"+...
    "persistent input_h1\n"+...
    "persistent input_h2\n"+...
    "if isempty(input_X)\n"+...
    "Data = coder.load('inp_model_data','expExp_n_input_name');\n"+...
    "input_X = Data.expExp_n_input_name(:,2);\n"+...
    "input_T = Data.expExp_n_input_name(:,1);\n"+...
    "input_h2 = input_T(2)-input_T(1);\n"+...
    "input_h1 = 1;\n"+...
    "thisAmp = input_X(1);\n"+...
    "elseif times <= 0\n"+...
    "thisAmp = input_X(1);\n"+...
    "elseif times >= 20\n"+...
    "thisAmp = input_X(end);\n"+...
    "else\n"+...
    "while times > input_T(input_h1)\n"+...
    "input_h1 = input_h1 + 1;\n"+...
    "end\n"+...
    "while times < input_T(input_h1-1)\n"+...
    "input_h1  = input_h1-1;\n"+...
    "end\n"+...
    "input_h3 = (input_T(input_h1)-times)/input_h2;\n"+...
    "thisAmp = input_X(input_h1-1)*input_h3 + input_X(input_h1)*(1-input_h3);\n"+...
    "end\n"+...
    "end";
end
   
% The template2() function generates the code for the first input of the
% first experiment in the "_input_creator()" function.
function inp_creator_str = template2()
inp_creator_str = ...
    "expExp_n_input_name(:,1) = sbtab.datasets(Exp_n).input_time{index};\n"+...
    "expExp_n_input_name(:,2) = sbtab.datasets(Exp_n).input_value{index};\n"+...
    "save('inp_model_data','expExp_n_input_name');\n";
end

% The template3() function generates the code for the rest of the inputs in
% the "_input_creator()" function.
function inp_creator_str = template3()
inp_creator_str = ...
    "expExp_n_input_name(:,1) = sbtab.datasets(Exp_n).input_time{index};\n"+...
    "expExp_n_input_name(:,2) = sbtab.datasets(Exp_n).input_value{index};\n"+...
    "save('inp_model_data','expExp_n_input_name','-append');\n";
end

The f_setup_input function is designed to generate code for loading experiment inputs into a .mat file and create code to read these inputs during the simulation of the experiments. The generated code is stored in the “Input_functions” folder.

param stg:

A structure containing information about the simulation settings.

type stg:

structure

param mmf:

A structure containing information about the model, including the model data, main folder, and input functions.

type mmf:

structure

return:

This function creates input function files and an input creator function file in the “Input_functions” folder. The input functions are used to calculate input values based on the simulation time, while the input creator function is used to create input data from the sbtab.datasets.

rtype:

None

The function calls the following helper functions:

• template1: Generates code for input functions.

• template2: Generates code for the first input of the first experiment in the input creator function.

• template3: Generates code for the rest of the inputs in the input creator function.

The function loads the following variables:

• matlab_model: Loaded from mmf.model.data.mat_model.

• data_model: Loaded from mmf.model.data.data_model.

• inp_model_data: Loaded from mmf.model.data.input_model_data.

• Model_folder: Loaded from mmf.model.main.

• model_input: Loaded from mmf.model.input_functions.input.

• sbtab: Loaded from the data_model file.

• modelobj: Loaded from the matlab_model file.

f_build_model_exp

Code

function f_build_model_exp(stg,sb,mmf)
% This function generates .mat files for equilibrium and proper simulation
% runs for a set of experiments. It reads experiment settings from an sbtab
% structure, configures the simulation settings, processes input and output
% species, and saves the resulting .mat files.
%
% Inputs:
% - stg: A structure containing settings for the simulations, including
% maximum wall clock time, stop times, dimensional analysis, unit
% conversion, tolerances, step sizes, and time units.
% - sb: An sbtab structure containing information about experiments, such
% as output values, output species, output units, input times, input
% values, and input species.
% - mmf: A model management framework structure containing the data and mat
% models, which include data_model, mat_model, model_exp_eq,
% model_exp_default, and model_exp_detail.
%
% Outputs:
% - Equilibrium and proper simulation run .mat files for each experiment,
% saved with filenames based on model_exp_eq, model_exp_default, and
% model_exp_detail.
%
% Called Functions:
% - getconfigset: Retrieves the configuration set object from a SimBiology
% model.
% - copyobj: Creates a copy of a SimBiology model object.
% - set: Sets properties of a SimBiology object.
% - load: Loads variables from .mat files.
% - save: Saves variables to .mat files.
% - addspecies: Adds species to a SimBiology model compartment.
% - addrule: Adds rules to a SimBiology model.
% - addparameter: Adds parameters to a SimBiology model.
% - addevent: Adds events to a SimBiology model.
% 
% Variables:
% Loaded:
% - data_model: File path of the data_model .mat file containing Data and
% sbtab.
% - mat_model: File path of the mat_model .mat file containing the
% SimBiology model object.
% - model_exp_eq: File path prefix for saving equilibrium simulation run
% .mat files.
% - model_exp_default: File path prefix for saving proper simulation run
% .mat files.
% - model_exp_detail: File path prefix for saving detailed simulation run
% .mat files.
% - Data: Data structure containing experiment time points.
% - sbtab: sbtab structure containing experiment settings and information.
% - modelobj: SimBiology model object loaded from the mat_model file.
%
% Initialized:
% - None
%
% Persistent:
% - None
%
% Notes:
% - The function iterates through all experiments, configuring simulation
% settings and processing species for each experiment, then saves the
% corresponding .mat files.

% Load data_model and mat_model files
data_model = mmf.model.data.data_model;
mat_model = mmf.model.data.mat_model;
model_exp_eq = mmf.model.data.model_exp.equilibration;
model_exp_default = mmf.model.data.model_exp.default;
model_exp_detail = mmf.model.data.model_exp.detail;

% Load Data and modelobj from data_model and mat_model files
load(data_model,'Data','sbtab')
load(mat_model,'modelobj');

% Initialize model_run and configsetObj arrays
model_run = cell(size(sb.Experiments.ID,1),1);
configsetObj = cell(size(sb.Experiments.ID,1),1);

% Loop through all experiments
for number_exp = 1:size(sb.Experiments.ID,1)
    
    % Load sbtab dataset information
    output_value = sbtab.datasets(number_exp).output_value;
    output = sbtab.datasets(number_exp).output;
    output_unit = sbtab.datasets(number_exp).output_unit;
    input_time = sbtab.datasets(number_exp).input_time;
    input_value = sbtab.datasets(number_exp).input_value;
    input_species = sbtab.datasets(number_exp).input;
    
    % Initialize model and configuration set objects for the current experiment
    model_run{number_exp} = copyobj(modelobj);
    configsetObj{number_exp} = getconfigset(model_run{number_exp});
    
    % Configure simulation settings for the equilibrium simulation run
    set(configsetObj{number_exp}, 'MaximumWallClock', stg.maxt);
    set(configsetObj{number_exp}, 'StopTime', stg.eqt);
    set(configsetObj{number_exp}.CompileOptions,...
        'DimensionalAnalysis', stg.dimenanal);
    set(configsetObj{number_exp}.CompileOptions,...
        'UnitConversion', stg.UnitConversion);
    set(configsetObj{number_exp}.SolverOptions,...
        'AbsoluteToleranceScaling', stg.abstolscale);
    set(configsetObj{number_exp}.SolverOptions,...
        'RelativeTolerance', stg.reltol);
    set(configsetObj{number_exp}.SolverOptions,...
        'AbsoluteTolerance', stg.abstol);
    set(configsetObj{number_exp}.SolverOptions,...
        'AbsoluteToleranceStepSize', stg.abstolstepsize_eq);
    set(configsetObj{number_exp}.SolverOptions, 'OutputTimes', stg.eqt);
    set(configsetObj{number_exp}, 'TimeUnits', stg.simtime);
    set(configsetObj{number_exp}.SolverOptions, 'MaxStep', stg.maxstepeq);

    % Save equilibrium simulation run .mat file
    model_exp = model_run{number_exp};
    config_exp = configsetObj{number_exp};
    save(model_exp_eq + number_exp + ".mat",'model_exp','config_exp')
    
    % Update simulation settings for the proper simulation run
    set(configsetObj{number_exp}, 'StopTime', sbtab.sim_time(number_exp));
    set(configsetObj{number_exp}.SolverOptions, 'OutputTimes',...
        Data(number_exp).Experiment.t);
    set(configsetObj{number_exp}.SolverOptions, 'MaxStep', stg.maxstep);
    
    % Process output species. Adds output species and rules
    for n = 1:size(output,2)
        % Check if output species exist in the model
        m = 0;
        for k = 1:size(model_run{number_exp}.species,1)
            if model_run{number_exp}.species(k).name == string(output{1,n})
                model_run{number_exp}.species(k).BoundaryCondition = 1;
                m = 1;
            end
        end
        % If output species does not exist, add it to the model
        if m == 0
            if strcmp( output_unit{1,n},'dimensionless' )
                warning('off','SimBiology:InvalidSpeciesInitAmtUnits')
            else
                warning('on','SimBiology:InvalidSpeciesInitAmtUnits')
            end
            addspecies (model_run{number_exp}.Compartments(1),...
                char(output{1,n}),0,...
                'InitialAmountUnits',output_unit{1,n});
        end
        % Add repeated assignment rule for output species
        addrule(model_run{number_exp}, char(output_value{1,n}),...
            'repeatedAssignment');
    end
    
    % Process input species. Adds input species and rules, either as events
    % or repeated assignments
    for j = 1:size(input_species,2)
        
        input_indexcode = str2double(strrep(input_species(j),'S',''));
        input_name = string(model_run{number_exp}.species(1 +...
                input_indexcode).name);
        
        % If the input time is less than 100, add events
        if size(input_time{j},2) < 100
            
            model_run{number_exp}.species(...
                1 + input_indexcode).BoundaryCondition = 1;
            for n = 1:size(input_time{j},2)
                if ~isnan(input_time{j}(n))

                    % Add parameters for time and input values
                    addparameter(model_run{number_exp},char("time_event_t_" + j + "_" +  n),...
                        str2double(string(input_time{j}(n))),...
                        'ValueUnits',char(stg.simtime));
                    
                    addparameter(model_run{number_exp},char("time_event_r_" + j + "_" +  n),...
                        str2double(string(input_value{j}(n))),...
                        'ValueUnits',char(model_run{number_exp}.species(1 +...
                        input_indexcode).InitialAmountUnits));

                    % Add event for input species
                    addevent(model_run{number_exp}, ...
                        char("time>=time_event_t_" + j + "_" +  n),...
                        cellstr(sbtab.datasets(number_exp).output_location{1} +...
                        "." + input_name + " = time_event_r_" + j + "_" +  n));
                end
            end
        else
            % If the input time is greater than or equal to 100, add repeated assignment rule
            addrule(model_run{number_exp}, char(sbtab.datasets(...
                number_exp).output_location{1} + "." + input_name +...
                "=" + string(model_run{number_exp}.name)+ "_input" + ...
                number_exp + "_" + input_name + "(time)"), 'repeatedAssignment');
        end
    end

    % Save proper simulation run .mat file (default)
    model_exp = model_run{number_exp};
    config_exp = configsetObj{number_exp};
    save(model_exp_default + number_exp + ".mat",'model_exp','config_exp')

    % Update simulation settings for detailed simulation run
    set(configsetObj{number_exp}.SolverOptions,'OutputTimes', []);
    set(configsetObj{number_exp}.SolverOptions,'MaxStep', stg.maxstepdetail);

    % Save detailed simulation run .mat file
    model_exp = model_run{number_exp};
    config_exp = configsetObj{number_exp};
    save(model_exp_detail + number_exp + ".mat",'model_exp','config_exp')
    
end
end

Creates two .mat files for each experiment, one for the equilibrium simulation run and one for the proper simulation. These files have all the added rules, species and parameters needed depending on the inputs and outputs specified on the SBtab.

• Inputs - stg, sb

• Saves - Ready to run models

Function: f_build_model_exp Description: This function creates two .mat files for each experiment: one for the equilibrium simulation run and one for the proper run. The .mat files contain necessary rules, species, and parameters based on the inputs and outputs specified in the sbtab. The function also configures simulation settings for the equilibrium and proper simulation runs, processes output and input species, and saves the .mat files for each experiment.

Inputs: - stg: A structure containing settings for the simulations - sb: An sbtab structure containing information about experiments - mmf: A model management framework structure containing the data and mat models

Outputs: - .mat files for equilibrium and proper runs for each experiment

Called Functions: - getconfigset - copyobj - set - load - save - addspecies - addrule - addparameter - addevent

Loaded Variables: - data_model - mat_model - model_exp_eq - model_exp_default - model_exp_detail - Data - sbtab - modelobj

Notes: - The function has a loop that iterates through all experiments and saves the corresponding .mat files.

Usage example:

% Initialize stg, sb, and mmf structures
stg = ...
sb = ...
mmf = ...

% Call the f_build_model_exp function
f_build_model_exp(stg, sb, mmf);

This will create .mat files for equilibrium and proper runs for each experiment based on the information provided in the stg, sb, and mmf structures. The function f_build_model_exp processes the input structures stg, sb, and mmf to create .mat files for each experiment. The stg structure contains simulation settings such as time units, maximum wall clock, and tolerances. The sb structure contains information about the experiments, while the mmf structure contains data and mat models.

The function loads data from the data_model and mat_model files and initializes arrays for model_run and configsetObj. It then iterates through all experiments, configuring the simulation settings for both the equilibrium and proper simulation runs.

For each experiment, the function processes the output species, adding them to the model if they don’t already exist and setting up the appropriate rules. It then processes the input species, adding them either as events or repeated assignments based on the input time.

Finally, the function saves the .mat files for each experiment, creating separate files for the equilibrium, proper (default), and detailed simulation runs.