Additionalfunctions

CreateClusterAndRAtables[source]

Build cluster and relative-abundance tables from WBM flux results

Reads WBM relative abundances, regression coefficients and processed fluxes, then builds clusters of the top-contributing microbes for the reactions of interest together with their relative-abundance tables.

combineFluxResults(directory1, directory2, resultdirectory, set_regexp)[source]

This function merges & prunes the FBA solutions between two runs of the optimiseRxnMultipleWBMs.m function. Reaction fluxes, FBA statistics, & shadow prices get therefore concatenated. Note that in case the sample filenames differ from the standard, the regular expression needs to be adapted.

USAGE:

combineFluxResults (directory1, directory2, resultdirectory, set_regexp)

INPUTS:

  • directory1 – [char array] directory to flux solutions from the first run

  • directory2 – [char array] directory to flux solutions from the second run

  • resultdirectory – [char array] directory to the empty folder where the combined fluxes will be saved

OPTIONAL INPUTS:

set_regexp – [char array] alternative regular expression for when the sample filenames differ from the standard optimiseRxnMultipleWBMs.m output

completeSpeciesFolder(agoraPath, panPath)[source]

Some strains in AGORA2 only have one strain. These strains are not moved to the pan model folder, resulting in some soecies not being captured in the models. By converting the strain reconstructions with only a single strain to the species folder, you can solve this problem.

USAGE:

completeSpeciesFolder (agoraPath, panPath)

INPUTS:

  • agoraPath – path to the folder with strain reconstructions

  • panPath – path to the folder with pan species models

convertToStr(element)[source]

Convert a char array or a single-cell element to a char array

USAGE:

str = convertToStr (element)

INPUT:

element – char array, or a cell whose contents are converted with cell2mat

OUTPUT:

str – char array representation of element

convertVMHIDName(metNames, VMHIDs, suggestSimilar)[source]

FOUR FUNCTIONS:

  1. Retrieve metabolite IDs corresponding to the given metabolite names AND/OR

  2. Retrieve metabolite names corresponding to a given metabolite ID or some

    reactions

  3. Convert metabolite tranport reactions e.g., DM_glc_d[bc] to D-Glucose or

    EX_glc_D[c] to metabolite name e.g., D-Glucose.

  4. Suggest similar names for metabolite names provided that are

    not found in the data base

USAGE:

[foundVMHIDs, foundMetNames, similarMets] = convertVMHIDName (metNames, VMHIDs, suggestSimilar)

INPUTS:

  • metNames – EITHER a cell array of metabolite names (strings) or metabolite transport reactions (can be mixed) for which IDs are required, or a flag indicating to skip this step (0)

  • VMHIDs – cell array of metabolite IDs (strings) for which names are required, or a flag indicating to skip this step (0)

  • suggestSimilar – flag indicating whether to generate suggestions (1) or not (0)

OUTPUTS:

  • foundVMHIDs – cell array of metabolite IDs corresponding to the input names

  • foundMetNames – cell array of metabolite names corresponding to the input IDs

  • similarMets – cell array of possible matches for each unfound metabolite name, when searching for names

dimensionalityReductionAndMultivariateAnalysis(measuresTable, metadataTable, varOfInterest, results_path, varargin)[source]

Dimensionality reduction of high-dimensional measures (e.g. microbiome relative abundances or reaction relative abundances) by RPCA following data preprocessing OR beta-diversity measures by PCoA, with the aim to:

1. Find whether there are general differences between groups of a metadata variable of interest (e.g. disease vs ctrl status), in case variable is categorical. 2. Identify variables from the measures (e.g. microbial taxa, reactions) which contribute the most to the first principle component (PC1) of RPCA & therefore its explained variance. 3. Perform linear regression on PC1 ~ metadata variable (e.g. Sex, disease vs Ctrl status) to find metadata variables which might be important confounders in follow-up analysis in case they are significantly correlated & explain a lot of the variance of PC1 from RPCA/PCoA.

USAGE:

dimensionalityReductionAndMultivariateAnalysis (measuresTable, metadataTable, varOfInterest, results_path, varargin)

INPUTS:

  • measuresTable – [table] high-dimensional measures (e.g. microbiome relative abundances or reaction relative abundances), with columns = samples and rows = measured groups (e.g. taxa/reactions):

    • .Properties - table metadata (variable and row names)

  • metadataTable – [table] metadata for the samples (e.g. sex), with columns = variables (e.g. Sex) and rows = samples:

    • .Properties - table metadata (variable and row names)

  • varOfInterest – [string] variable (e.g. Sex or disease status) contained in the metadata

  • results_path – [string] directory path where results are stored (figures and statistical results in spreadsheet format)

OPTIONAL INPUTS:

varargin – parameter name/value pairs:

  • numLoadings - [numeric] number of PC loadings shown in the plot of strongest feature contributions (default: 15)

  • inputDataType - [char/string] whether input is of type “abundance” or “betaDiversityMatrix” (default: “abundance”)

  • PCofInterest - [numeric] principle component/coordinate of interest on which the analysis is performed (default: 1)

OUTPUTS:

In form of tables & plots into dir at results_path location.

Authors

  • Jonas Widder, 12/2024 & 01/2025

downloadAGORA2(directory)[source]

Download and unpack AGORA2

USAGE:

AGORA2_dir = downloadAGORA2 (directory)

INPUT:

directory – directory indicating where to download AGORA2

OUTPUT:

AGORA2_dir – directory to the AGORA2 folder

filterMetabolitesNotPresentInWBMmodel(metabolitesOfInterest, WBM_compartment)[source]

Filters a table with metabolites for their presence in selected compartment(s) of the unpersonalized Harvey & Harvetta WBM models and returns both the present & absent metabolites in seperate tables. This process ensures that all metabolites of interest are actually present in the models & fluxes can be calculated for.

USAGE:

[metabolitesPresentInWBM, metabolitesNotPresentInWBM] = filterMetabolitesNotPresentInWBMmodel (metabolitesOfInterest, WBM_compartment)

INPUTS:

  • metabolitesOfInterest – table with VMH abbreviations of unique metabolites of interest, with column:

    • .ID - VMH abbreviations of the metabolites of interest

  • WBM_compartment – specification of the WBM compartment as a string, e.g. “[bc]”

OUTPUTS:

  • metabolitesPresentInWBM – table with metabolites of interest that are present in the selected compartment(s) of the WBM models

  • metabolitesNotPresentInWBM – table with metabolites of interest that are not present in the selected compartment(s) of the WBM models

AUTHOR:

  • Jonas Widder, 10/2024

findOptimalCoreCount(modelDir, solver)[source]

Find the optimal number of parallel workers for the whole-body models being investigated

USAGE:

[totalFBAtime, timeTable] = findOptimalCoreCount (modelDir, solver)

INPUTS:

  • modelDir – path to the folder with COBRA models

  • solver – name of the LP solver to use for the tests

OUTPUTS:

  • totalFBAtime – table of total FBA solve time and derived timing metrics for each tested worker configuration

  • timeTable – table of per-model FBA solve times for each worker configuration

generateAGORA2MappingStatTable[source]
generatePanAGORA2database()[source]

Create a lookup file recording which reactions and metabolites are present in which AGORA2 strains

USAGE:

lookupFilePath = generatePanAGORA2database()

OUTPUT:

lookupFilePath – path to the generated lookup file

generatePanDatabase(inputDir)[source]

Create a lookup file recording which reactions and metabolites are present in which AGORA2 models

USAGE:

lookupFilePath = generatePanDatabase (inputDir)

INPUT:

inputDir – directory with the AGORA2 models (default: ‘AGORA2’)

OUTPUT:

lookupFilePath – path to the generated lookup file

generateStackedBarPlot(input_relAbundances, saveDir)[source]

Generates stacked bar plots from relative abundances of taxa for single or multiple samples.

USAGE:

generateStackedBarPlot (input_relAbundances, saveDir)

INPUTS:

  • input_relAbundances – [table] taxa and their relative abundances for all samples, with:

    • .Taxon - taxon identifiers

    • .Properties - table metadata (variable names)

  • saveDir – [char/string] path to the directory where the stacked bar plot is saved

AUTHOR:

  • Jonas Widder, 12/2024 & 01/2025

getDirectorySize(dirPath)[source]

Determine the total size on disk of a selected directory

USAGE:

totalSize = getDirectorySize (dirPath)

INPUT:

dirPath – path to the directory whose size is calculated

OUTPUT:

totalSize – total size of the directory contents in bytes

getMicrobeFluxMappingStats[source]

Compute summary statistics for the microbe-to-metabolite flux mapping and write them to the statistics results directory INPUT: saveDirStats

getPanSpeciesMetProdCapacity[source]

Create lookup file for checking which reactions and metabolites are present in which AGORA2 taxa

OUTPUT lookupFilePath Path to the generated lookup file

Authors: Tim Hensen, 2024

getVMHID(mets, suggest)[source]

Retrieve metabolite IDs corresponding to the given metabolite names

USAGE:

[metIDs, suggestedMets] = getVMHID (mets, suggest)

INPUTS:

  • mets – cell array of metabolite names (strings) for which IDs are required

  • suggest – flag indicating whether to generate suggestions (1) or not (0)

OUTPUTS:

  • metIDs – cell array of metabolite IDs corresponding to the input names

  • suggestedMets – cell array of possible matches for each unfound metabolite name

interrogateWBmodelsQP(directory, resPath, solver, param)[source]

Performs FBA on a all whole-body models in a folder with the quadratic flux minimisation algorithm (QP) and saves the QP FBA results in a separate results folder.

USAGE:

interrogateWBmodelsQP (directory, resPath, solver, param)

INPUTS:

  • directory – [char] path to the folder with whole-body models

  • resPath – [char] path to the location where FBA results are saved

  • solver – [char] solver name, e.g. gurobi

OPTIONAL INPUTS:

param – [struct] FBA parameters. See optimizeWBModel.m or optimizeCbModel.m for more information. All FBA parameters are set to their defaults except for the following:

  • .minNorm - norm used for flux minimisation (default 1e-6)

  • .secondsTimeLimit - solver time limit in seconds (default 500)

microbiomeMappingStats(rawPath, marsPath, saveDir, metadataPath)[source]

Function for obtaining statistics on AGORA2 mapping

USAGE:

microbiomeMappingStats (rawPath, marsPath, saveDir, metadataPath)

INPUTS:

  • rawPath – path to the unfiltered microbiome data

  • marsPath – path to the mapped microbiome data

  • saveDir – path to the folder where the results are saved

  • metadataPath – path to the sample metadata table

physiologicalConstraintsHMDBbasedTEMP(model, IndividualParameters, ExclList, Type, InputData, Biofluid, setDefault, ExclMet, ExclMetAbbr)[source]

This function applies constraints to the whole-body metabolic model metabolite concentrations have to be given in uM organ weights have to be given in g Please note that reaction specific constraints are applied at the end of the function, which have been derived from the literature.

USAGE:

modelConstraint = physiologicalConstraintsHMDBbasedTEMP (model, IndividualParameters, ExclList, Type, InputData, Biofluid, setDefault, ExclMet, ExclMetAbbr)

INPUTS:

  • model – whole-body metabolic model structure

  • IndividualParameters – structure of physiological parameters, as generated by standardPhysiolDefaultParameters, with fields:

    • .sex - sex of the individual

    • .CardiacOutput - cardiac output

    • .MConDefaultBc - default blood compartment metabolite concentration range

    • .MConDefaultCSF - default cerebrospinal fluid metabolite concentration range

    • .MConDefaultUrMax - default maximum urine metabolite concentration

    • .MConDefaultUrMin - default minimum urine metabolite concentration

    • .MConUrCreatinineMax - maximum urine creatinine concentration

    • .MConUrCreatinineMin - minimum urine creatinine concentration

    • .CSFFlowRate - cerebrospinal fluid flow rate

    • .CSFBloodFlowRate - cerebrospinal fluid blood flow rate

    • .UrFlowRate - urine flow rate

    • .Hematocrit - hematocrit

    • .bloodFlowData - per-organ blood flow data

    • .bloodFlowPercCol - column index of the blood flow percentage in bloodFlowData

    • .bloodFlowOrganCol - column index of the organ name in bloodFlowData

    • .bodyWeight - body weight

  • ExclList – list of reaction(s) to which no updated bound is assigned

  • Type – input type, either ‘xlsx’ (default, loads ‘Parsed_hmdbConc.xlsx’) or ‘direct’ (InputData must be provided)

  • InputData – data whose first column holds VMH IDs of metabolites and second column the data points (set as lb and ub)

  • Biofluid – ‘all’ (default when Type is ‘xlsx’); for ‘direct’ one of ‘bc’, ‘u’, ‘csf’

  • setDefault – if the input data lacks a concentration for a metabolite, a default concentration range is used to compute the constraints (default: 1); ranges come from IndividualParameters

  • ExclMet – whether certain metabolites (and their reactions) are excluded from the constraint application (default: 0)

  • ExclMetAbbr – list of metabolites to be excluded

OUTPUT:

modelConstraint – model structure with updated constraints

plotAbsentTaxaEffectOnMARScoverage(mars_preprocessedInput, absentTaxa_abundanceMetrics, readCounts, results_path, varargin)[source]

Based on MARS mapping input, this function generates a plot which visualizes how much of an effect the addition of currently unmapped taxa to the microbiome community model would have in terms of read coverage, starting from the most abundant taxa.

USAGE:

plotAbsentTaxaEffectOnMARScoverage (mars_preprocessedInput, absentTaxa_abundanceMetrics, readCounts, results_path, varargin)

INPUTS:

  • mars_preprocessedInput – [table] MARS “preprocessed_input” output with read counts per pre-mapped taxon:

    • .Taxon - taxon identifiers

  • absentTaxa_abundanceMetrics – [table] MARS output listing all unmapped taxa with summary statistics on their relative abundance across samples (mean relative abundance is used):

    • .Taxon - taxon identifiers

  • readCounts – [table] original data table with read counts per taxon

  • results_path – [string] directory path where results are stored (figure)

OPTIONAL INPUTS:

varargin – parameter name/value pairs:

  • numAbsentTaxaToInvestigate - [numeric] number of unmapped taxa whose effect is tested and plotted (default: full list of unmapped taxa)

Authors

  • Jonas Widder, 11/2024 & 01/2025

runStatisticsOnModerationAnalysisResults(data, metadata, formula, regressionResults, moderationThreshold_usePValue, moderationThreshold, saveDir)[source]

Filters regression results from moderation analysis for significantly correlating metabolites fluxes/bacterial taxa. Then stratifies the filtered flux/rel. abundances data for the moderator & performs new statistical analysis on the stratified data. Notes: The moderator needs to be categorical.

USAGE:

statResults = runStatisticsOnModerationAnalysisResults (data, metadata, formula, regressionResults, moderationThreshold_usePValue, moderationThreshold, saveDir)

INPUTS:

  • data – [table] processed flux/relative-abundance data

  • metadata – [table] metadata containing ID and possible additional variables (confounders, moderators)

  • formula – [string] regression formula in Wilkinson notation

  • regressionResults – [struct] structure containing tables for flux and relative-abundance regression results

  • moderationThreshold_usePValue – [boolean] whether the cutoff threshold is the pValue (true) or the FDR (false) (default: true)

  • moderationThreshold – [numeric] cutoff threshold for the maximal FDR value a metabolite/taxon must pass to be included in the stratified analysis (default: 0.05)

  • saveDir – [char] path to the working directory

OUTPUT:

statResults – [struct] structure containing tables of regression results for the moderator-stratified data of the significant hits from the initial moderation regressions; empty if the regression contains no flux or relative-abundance results

AUTHOR:

Jonas Widder, 11/2024

setResultPath(solutionDir)[source]

Function for creating a common path to all flux results

USAGE:

saveDir = setResultPath (solutionDir)

INPUT:

solutionDir – path to the folder with flux solution results

OUTPUT:

saveDir – path to the created common results folder

slimDownFBAresults(FBAsolutionDir)[source]

This function prunes FBA solution results obtained in optimiseRxnMultipleWBM.m and saves the slimmed down solution results in a new folder. The function first creates a new folder and generates paths for the flux results in that folder. Then, only the following data is loaded: ‘rxns’,’ID’,’sex’,’f’, and’stat’. If microbiome data was available: ‘speciesBIO’,’shadowPriceBIO’, and ‘relAbundances’. Then, the solutions are saved to the new paths.

USAGE:

smallFBAsolutionPaths = slimDownFBAresults (FBAsolutionDir)

INPUT:

FBAsolutionDir – character array with the path to the FBA solutions

OUTPUT:

smallFBAsolutionPaths – paths to the slimmed-down FBA results

validateDietPath(Diet, resPath)[source]

validateDietPath checks if ‘Diet’ is a valid COBRA Toolbox diet or file path and either loads the corresponding data or saves it to a text file.

USAGE:

outputFilePath = validateDietPath (Diet, resPath)

INPUTS:

  • Diet – a string or character array; either a COBRA Toolbox diet name (e.g. ‘EUAverageDiet’, ‘HighFiberDiet’) or a file path to a ‘.txt’ or ‘.m’ file containing diet data

  • resPath – folder path where the diet data is saved as a text file

OUTPUT:

outputFilePath – path to the saved text file, or the input file path if no saving is needed

Note

If ‘Diet’ is a COBRA Toolbox diet name, the corresponding data is loaded. If ‘Diet’ is a file path, ‘.txt’ files are skipped and ‘.m’ files are executed to load the diet data. If no valid input is provided, an error is thrown.