Getting Started with BiGGViz

Version: 1.0.0
Authors: Shu-Liang Yu and Rachael Hageman Blair
Maintainer: Shu-Liang Yu
Last Updated: May 2026
BiGGViz is a MATLAB App for interactive visualization and annotation-driven exploration of BiGG/COBRA metabolic models. This tutorial demonstrates how to use BiGGViz with two BiGG models:
1. The iAB_RBC_283 red blood cell model.
2. The e_coli_core model with user-supplied reaction and metabolite annotation tables.
The tutorial covers model loading, annotation overlay, reaction-reaction and metabolite-metabolite network visualization, node coloring, node sizing, label selection, pathway highlighting, neighborhood exploration, filtering, and export.

0. Quick Start

0.1 Quick Start

  1. Add src/ to the MATLAB path.
  2. Launch BiGGViz.
  3. Load a COBRA-compatible BiGG model from data/models/.
  4. Optionally load a reaction or metabolite annotation table from data/annotations/.
  5. Use Network Type, Label By, Color By, Size By, pathway highlighting, neighborhood exploration, and Capture View export.

0.2 Requirements

1. Project setup

%% 1. Initialize project paths
 
% This live script is expected to be saved as:
% BiGGViz/docs/GettingStarted.mlx
%
% The project root is therefore one folder above docs/.
 
try
thisFile = matlab.desktop.editor.getActiveFilename;
docDir = fileparts(thisFile);
projectRoot = fileparts(docDir);
catch
% Fallback if this script is run outside the Live Editor.
projectRoot = 'D:\RHB\BiGGViz';
end
 
srcDir = fullfile(projectRoot, 'src');
modelDir = fullfile(projectRoot, 'data', 'models');
annoDir = fullfile(projectRoot, 'data', 'annotations');
figDir = fullfile(projectRoot, 'docs', 'figures');
 
addpath(genpath(srcDir));

2. Required example files

Required example files

This tutorial assumes that the following files are available:
- data/models/iAB_RBC_283.mat or data/models/iAB_RBC_283.xml
- data/models/e_coli_core.mat or data/models/e_coli_core.xml
- data/annotations/e_coli_core_reaction_annotations_rich.xlsx
- data/annotations/e_coli_core_metabolite_annotations_rich.xlsx
The rich annotation tables can be generated by running:
examples/makeEcCoreAnnotationTables.m
%% 2. Check required files
 
rbcMatPath = fullfile(modelDir, 'iAB_RBC_283.mat');
rbcXmlPath = fullfile(modelDir, 'iAB_RBC_283.xml');
 
ecoliMatPath = fullfile(modelDir, 'e_coli_core.mat');
ecoliXmlPath = fullfile(modelDir, 'e_coli_core.xml');
 
rxnAnnoPath = fullfile(annoDir, 'e_coli_core_reaction_annotations_rich.xlsx');
metAnnoPath = fullfile(annoDir, 'e_coli_core_metabolite_annotations_rich.xlsx');
 
if isfile(rbcMatPath)
rbcModelPath = rbcMatPath;
elseif isfile(rbcXmlPath)
rbcModelPath = rbcXmlPath;
else
rbcModelPath = "";
end
 
if isfile(ecoliMatPath)
ecoliModelPath = ecoliMatPath;
elseif isfile(ecoliXmlPath)
ecoliModelPath = ecoliXmlPath;
else
ecoliModelPath = "";
end
 
requiredFiles = table( ...
["RBC model"; "E. coli core model"; "Reaction annotation table"; "Metabolite annotation table"], ...
[string(rbcModelPath); string(ecoliModelPath); string(rxnAnnoPath); string(metAnnoPath)], ...
[isfile(rbcModelPath); isfile(ecoliModelPath); isfile(rxnAnnoPath); isfile(metAnnoPath)], ...
'VariableNames', {'FileType', 'Path', 'Found'});
 
requiredFiles
requiredFiles = 4x3 table
FileTypePathFound
1"RBC model""D:\RHB\BiGGViz\data\models\iAB_RBC_283.mat"true
2"E. coli core model""D:\RHB\BiGGViz\data\models\e_coli_core.mat"true
3"Reaction annotation table""D:\RHB\BiGGViz\data\annotations\e_coli_core_reaction_annotations_rich.xlsx"true
4"Metabolite annotation table""D:\RHB\BiGGViz\data\annotations\e_coli_core_metabolite_annotations_rich.xlsx"true

3. Generate example annotation tables if needed

If the annotation tables are not already present under data/annotations/, generate them using the example script.
%% 3. Generate rich e_coli_core annotation tables if needed
 
makeAnnoScript = fullfile(projectRoot, 'examples', 'makeEcCoreAnnotationTables.m');
 
if ~isfile(rxnAnnoPath) || ~isfile(metAnnoPath)
if isfile(makeAnnoScript)
run(makeAnnoScript);
else
warning('Annotation-generation script not found: %s', makeAnnoScript);
end
else
disp('Rich annotation tables already exist.');
end
Rich annotation tables already exist.

4. Preview the reaction annotation table

The reaction annotation table provides reaction-level metadata for the reaction-reaction network. Example columns may include pathway labels, enzyme annotations, FBA fluxes, FVA summaries, knockout effects, statistical scores, node-size values, and external analysis identifiers.
%% 4. Preview reaction annotation table
 
if isfile(rxnAnnoPath)
rxnAnno = readtable(rxnAnnoPath, 'VariableNamingRule', 'preserve');
 
fprintf('Reaction annotation table: %d rows, %d columns\n', ...
height(rxnAnno), width(rxnAnno));
 
disp(string(rxnAnno.Properties.VariableNames)');
head(rxnAnno)
else
warning('Reaction annotation table not found: %s', rxnAnnoPath);
end
Reaction annotation table: 20 rows, 22 columns
"ReactionKey" "Name" "PathwayKey" "EnzymeKey" "ECNumber" "GeneAssociation" "Compartment" "SubsystemSource" "FBAFlux" "FVA_Min" "FVA_Max" "FluxVariabilityWidth" "KnockoutGrowthRatio" "EssentialityClass" "DifferentialFlux" "StatisticalScore" "AdjustedPValue" "EvidenceLevel" "PubMedID" "ExternalDataset" "NodeSize" "Notes"
ReactionKey Name PathwayKey EnzymeKey ECNumber GeneAssociation Compartment SubsystemSource FBAFlux FVA_Min FVA_Max FluxVariabilityWidth KnockoutGrowthRatio EssentialityClass DifferentialFlux StatisticalScore AdjustedPValue EvidenceLevel PubMedID ExternalDataset NodeSize Notes ___________ ____________________________________________ ______________________________ __________________________________ ____________ __________________ ___________ ____________________ _______ _______ _______ ____________________ ___________________ ___________________ ________________ ________________ ______________ ________________________ ____________ ________________ ________ _____________________________________________________________ {'HEX1'} {'Hexokinase' } {'Glycolysis/Gluconeogenesis'} {'Hexokinase' } {'2.7.1.1' } {'b2388' } {'c'} {'BiGG e_coli_core'} 7.48 7.28 7.73 0.45 0.72 {'Non-essential' } 1.1 3.5 0.004 {'Curated + simulation'} {'20118174'} {'FBA_baseline'} 8.7353 {'Illustrative rich reaction annotation for BiGGViz testing'} {'PGI' } {'Glucose-6-phosphate isomerase' } {'Glycolysis/Gluconeogenesis'} {'Glucose-6-phosphate isomerase' } {'5.3.1.9' } {'b4025' } {'c'} {'BiGG e_coli_core'} 4.86 4.51 5.16 0.65 0.85 {'Non-essential' } -0.35 1.2 0.21 {'Curated' } {'20118174'} {'FBA_baseline'} 7.427 {'Illustrative rich reaction annotation for BiGGViz testing'} {'PFK' } {'Phosphofructokinase' } {'Glycolysis/Gluconeogenesis'} {'6-phosphofructokinase' } {'2.7.1.11'} {'b3916 or b1723'} {'c'} {'BiGG e_coli_core'} 7.48 7.38 7.63 0.25 0.18 {'Growth-limiting'} 0.92 4.8 0.0008 {'Curated + knockout' } {'20118174'} {'KO_screen_A' } 8.7353 {'Illustrative rich reaction annotation for BiGGViz testing'} {'FBA' } {'Fructose-bisphosphate aldolase' } {'Glycolysis/Gluconeogenesis'} {'Fructose-bisphosphate aldolase'} {'4.1.2.13'} {'b2097 or b2925'} {'c'} {'BiGG e_coli_core'} 7.48 7.33 7.63 0.3 0.41 {'Growth-limiting'} 0.75 3.1 0.012 {'Curated + simulation'} {'20118174'} {'FVA_screen_A'} 8.7353 {'Illustrative rich reaction annotation for BiGGViz testing'} {'TPI' } {'Triose-phosphate isomerase' } {'Glycolysis/Gluconeogenesis'} {'Triose-phosphate isomerase' } {'5.3.1.1' } {'b3919' } {'c'} {'BiGG e_coli_core'} 7.48 7.33 7.63 0.3 0.62 {'Non-essential' } 0.7 2.7 0.031 {'Curated' } {'20118174'} {'FVA_screen_A'} 8.7353 {'Illustrative rich reaction annotation for BiGGViz testing'} {'GAPD'} {'Glyceraldehyde-3-phosphate dehydrogenase'} {'Glycolysis/Gluconeogenesis'} {'GAPDH' } {'1.2.1.12'} {'b1779' } {'c'} {'BiGG e_coli_core'} 16.02 15.52 16.47 0.95 0.05 {'Essential' } 1.85 5.6 0.0001 {'Curated + knockout' } {'20118174'} {'KO_screen_A' } 13 {'Illustrative rich reaction annotation for BiGGViz testing'} {'PGK' } {'Phosphoglycerate kinase' } {'Glycolysis/Gluconeogenesis'} {'Phosphoglycerate kinase' } {'2.7.2.3' } {'b2926' } {'c'} {'BiGG e_coli_core'} -16.02 -16.52 -15.57 0.95 0.08 {'Essential' } -1.7 5.1 0.0002 {'Curated + knockout' } {'20118174'} {'KO_screen_A' } 13 {'Illustrative rich reaction annotation for BiGGViz testing'} {'PGM' } {'Phosphoglycerate mutase' } {'Glycolysis/Gluconeogenesis'} {'Phosphoglycerate mutase' } {'5.4.2.12'} {'b0755' } {'c'} {'BiGG e_coli_core'} -14.72 -15.12 -14.37 0.75 0.55 {'Non-essential' } -0.8 2 0.08 {'Curated' } {'20118174'} {'FBA_baseline'} 12.351 {'Illustrative rich reaction annotation for BiGGViz testing'}

5. Preview the metabolite annotation table

The metabolite annotation table provides metabolite-level metadata for the metabolite-metabolite network. Example columns may include metabolite class, compartment, external database identifiers, node-size values, concentration-like variables, statistical scores, and external analysis labels.
%% 5. Preview metabolite annotation table
 
if isfile(metAnnoPath)
metAnno = readtable(metAnnoPath, 'VariableNamingRule', 'preserve');
 
fprintf('Metabolite annotation table: %d rows, %d columns\n', ...
height(metAnno), width(metAnno));
 
disp(string(metAnno.Properties.VariableNames)');
head(metAnno)
else
warning('Metabolite annotation table not found: %s', metAnnoPath);
end
Metabolite annotation table: 20 rows, 20 columns
"MetaboliteKey" "Name" "MetaboliteClass" "Compartment" "PathwayContext" "Formula" "Charge" "CarbonCount" "ConcentrationFoldChange" "Log2FoldChange" "AdjustedPValue" "CentralityScore" "MetaboliteEssentialityScore" "KnockoutPerturbationScore" "FVA_LinkedFluxSpan" "ExternalConfidence" "ExternalDataset" "PubChemCID" "NodeSize" "Notes"
MetaboliteKey Name MetaboliteClass Compartment PathwayContext Formula Charge CarbonCount ConcentrationFoldChange Log2FoldChange AdjustedPValue CentralityScore MetaboliteEssentialityScore KnockoutPerturbationScore FVA_LinkedFluxSpan ExternalConfidence ExternalDataset PubChemCID NodeSize Notes _____________ ___________________________________ __________________________ ___________ ______________________________ ______________ ______ ___________ _______________________ ______________ ______________ _______________ ___________________________ _________________________ __________________ __________________ ____________________________ __________ ________ _______________________________________________________________ {'glc__D_c'} {'D-Glucose' } {'Sugar' } {'c'} {'Glycolysis/Gluconeogenesis'} {'C6H12O6' } 0 6 1.45 0.53605 0.005 0.95 0.4 0.3 8 {'High' } {'Metabolomics_condition_A'} {'5793' } 15 {'Illustrative rich metabolite annotation for BiGGViz testing'} {'g6p_c' } {'D-Glucose 6-phosphate' } {'Sugar phosphate' } {'c'} {'Glycolysis/Gluconeogenesis'} {'C6H13O9P' } -2 6 1.28 0.35614 0.014 0.88 0.55 0.48 7.2 {'High' } {'Metabolomics_condition_A'} {'5958' } 14.263 {'Illustrative rich metabolite annotation for BiGGViz testing'} {'f6p_c' } {'D-Fructose 6-phosphate' } {'Sugar phosphate' } {'c'} {'Glycolysis/Gluconeogenesis'} {'C6H13O9P' } -2 6 1.22 0.28688 0.019 0.84 0.52 0.44 7.1 {'High' } {'Metabolomics_condition_A'} {'69507' } 13.842 {'Illustrative rich metabolite annotation for BiGGViz testing'} {'fdp_c' } {'D-Fructose 1,6-bisphosphate' } {'Sugar phosphate' } {'c'} {'Glycolysis/Gluconeogenesis'} {'C6H14O12P2'} -4 6 1.3 0.37851 0.011 0.7 0.47 0.38 6.8 {'High' } {'Metabolomics_condition_A'} {'10267' } 12.368 {'Illustrative rich metabolite annotation for BiGGViz testing'} {'dhap_c' } {'Dihydroxyacetone phosphate' } {'Sugar phosphate' } {'c'} {'Glycolysis/Gluconeogenesis'} {'C3H7O6P' } -2 3 0.82 -0.2863 0.08 0.61 0.3 0.22 5 {'Moderate'} {'Metabolomics_condition_A'} {'668' } 11.421 {'Illustrative rich metabolite annotation for BiGGViz testing'} {'g3p_c' } {'Glyceraldehyde 3-phosphate' } {'Sugar phosphate' } {'c'} {'Glycolysis/Gluconeogenesis'} {'C3H7O6P' } -2 3 0.86 -0.21759 0.09 0.66 0.35 0.25 5.2 {'Moderate'} {'Metabolomics_condition_A'} {'729' } 11.947 {'Illustrative rich metabolite annotation for BiGGViz testing'} {'13dpg_c' } {'3-Phospho-D-glyceroyl phosphate'} {'Organic acid phosphate'} {'c'} {'Glycolysis/Gluconeogenesis'} {'C3H8O10P2' } -4 3 1.55 0.63227 0.002 0.73 0.62 0.51 9.5 {'High' } {'Metabolomics_condition_A'} {'439191'} 12.684 {'Illustrative rich metabolite annotation for BiGGViz testing'} {'3pg_c' } {'3-Phospho-D-glycerate' } {'Organic acid phosphate'} {'c'} {'Glycolysis/Gluconeogenesis'} {'C3H7O7P' } -3 3 1.42 0.50589 0.004 0.76 0.58 0.49 9.2 {'High' } {'Metabolomics_condition_A'} {'724' } 13 {'Illustrative rich metabolite annotation for BiGGViz testing'}

6. Launch BiGGViz

%% 6. Launch BiGGViz
 
app = BiGGViz;

7. Workflow 1: iAB-RBC-283 RBC reaction model

This workflow demonstrates how to load and explore a BiGG model without a user-supplied annotation table.
Steps:
1. Click Load BiGG Model.
2. Select data/models/iAB_RBC_283.mat or where the model is located.
3. When prompted for an annotation table, click Cancel.
4. Start with the Reaction Network view.
5. Try the following controls:
- Label By: None, Node ID, Name, Pathway, Formula, Degree, Reversibility, or Gene Association.
- Color By: Pathway, Reversibility, Gene Association, or FBA value.
- Size By: Uniform, Degree, or FBA value.
- Highlight Pathway: select a pathway from the dropdown.
- Neighborhood Mode: Graph Hop or Pathway-Restricted Hop.
- Neighborhood Depth: 1, 2, or 3.

7.1 Reaction-reaction network colored by pathway

Steps:
  1. Click Load BiGG Model.
  2. Select data/models/iAB_RBC_283.mat or where the model is located.
  3. When prompted for an annotation table, click Cancel.
  4. The Network Type is defaulted to Reaction Network.
  5. Select Pathway from the Color By dropdown.

7.2 Reaction-reaction network colored by FBA value, filtered by max degree and minimum component size, with node sized by degree

Steps following 7.1:
  1. Select FBA Flux from the Color By dropdown.
  2. Select Degree from the Size By dropdown.
  3. Enter 5 in the Max Degree (0 = off) box.
  4. Enter 3 in the Min Component Size box.
  5. Click Apply Filters.

7.3 Reaction-reaction network of glycerophopholipid metabolism neighborhood

Steps following 7.2:
  1. Click Reset Filters.
  2. Select Reversibility from the Color By dropdown.
  3. Select Uniform from the Size By dropdown.
  4. Select Glycerophospholipid Metabolism from the Highlight Pathway dropdown.
  5. Select Pathway-Restricted Hop from the Neighborhood Mode dropdown.
  6. The Neighborhood Depth is defaulted to 1.
  7. Click Show Neighborhood.

7.4 Export to interactive HTML

Steps following 7.3:
  1. Select Interactive HTML from the Capture View dropdown.
  2. Save the network to an HTML file in the prompted saving window.

8. Workflow 2: E. coli core metabolite model with user-supplied annotations

This workflow demonstrates how to load and explore a BiGG model with a user-supplied annotation table.
Steps:
1. Click the Metabolite Network view.
2. Click Load BiGG Model.
3. Select data/models/e_coli_core.xml or where the model is located.
4. When prompted for an annotation table, select data/annotations/e_coli_core_metabolite_annotations_rich.xlsx or where the annotation table is located.
5. Try the following controls:
- Label By: None, Node ID, Name, Pathway, Formula, Degree, Reversibility, or Gene Association.
- Color By: Pathway, Reversibility, Gene Association, or FBA value.
- Size By: Uniform, Degree, or FBA value.
- Highlight Pathway: select a pathway from the dropdown.
- Neighborhood Mode: Graph Hop or Pathway-Restricted Hop.
- Neighborhood Depth: 1, 2, or 3.

8.1 Metabolite-metabolite network colored by compartment

Steps:
  1. Click the Metabolite Network view.
  2. Click Load BiGG Model.
  3. Select data/models/e_coli_core.xml or where the model is located.
  4. When prompted for an annotation table, select data/annotations/e_coli_core_metabolite_annotations_rich.xlsx or where the annotation table is located.
  5. Select Compartment from the Color By dropdown.
  6. Select Node Size from the Size By dropdown. This annotation is from the user-supplied annotation table.

8.2 Metabolite-metabolite network of 2-hop neighborhood around glucose-6-phosphate

Steps following 8.1:
  1. Select g6p [c] from the Select Node Key dropdown. This is the glucose-6-phosphate in the cytosol, a metabolite central to glycolysis/gluconeogenesis.
  2. The Neighborhood Mode is defaulted to Graph Hop for metabolite-metabolite network.
  3. Select 2 from the Neighborhood Depth dropdown.
  4. Select Name from the Label By dropdown.
  5. Click Show Neighborhood.

8.3 Metabolite-metabolite network of 1-hop neighborhood around pyruvate

Steps following 8.2:
  1. Click Back to Full Neighborhood.
  2. Select pyr[c] from the Select Node Key dropdown. This is the pyruvate in the cytosol, useful in showing pathway cross-talk between glycolysis, fermentation, and central carbon metabolism.
  3. The Neighborhood Mode is defaulted to Graph Hop for metabolite-metabolite network.
  4. Select 1 from the Neighborhood Depth dropdown.
  5. Select Compartment from the Label By dropdown.
  6. Select Metabolite Class from the Color By dropdown.
  7. Click Show Neighborhood.

8.4 Export tables for use in Cytoscape

Steps following 8.3:
  1. Select Cytoscape Tables (.xlsx) from the Capture View dropdown.
  2. Save the tables to an XLSX file in the prompted saving window.
An example of the exported file looks like:

9. Notes on annotation tables

As demonstrated in section 8, BiGGViz accepts user-supplied annotation tables for reaction or metabolite networks.
Reaction-reaction tables should contain a reaction identifier column, such as:
Metabolite-metabolite tables should contain a metabolite identifier column, such as:
Additional columns are preserved and can be used for tooltip display, node labels, node sizing, and Cytoscape annotations. Examples include:
If FBAFlux is supplied in a reaction annotation table, BiGGViz uses the provided flux values for FBA-based coloring or sizing. If FBAFlux is not supplied, BiGGViz can compute FBA flux values internally through the COBRA Toolbox when the FBA Flux option is selected.
If NodeSize is supplied in an annotation table, BiGGViz exposes Node Size as an option in the Size By dropdown menu, allowing user-defined quantitative values to control node scaling.

10. Troubleshooting

The app cannot find BiGGViz

Make sure the src/ folder has been added to the MATLAB path: addpath(genpath(fullfile(projectRoot, 'src')))

The model does not load

Check that the selected file is a COBRA-compatible MAT .mat model or an SBML .xml model.

FBA Flux does not work

Make sure COBRA Toolbox is installed and initialized. Also make sure an LP solver is available.

The annotation table does not load

Check that reaction annotation tables contain a reaction identifier column and metabolite annotation tables contain a metabolite identifier column.

Capture View PDF export does not work

The PDF export uses a local Google Chrome installation. Make sure Chrome is installed in a standard location.

Cytoscape export

Use the Edges sheet as the network edge table and the Nodes sheet as the node attribute table.