MATLAB · chapter 1 of 13

Getting started

GRNLab generates gene-expression data from gene regulatory networks (GRNs) with Hill-function kinetics. Every dataset it produces comes with the ground truth that generated it: the signed regulatory network, every kinetic parameter, the initial conditions, the seed, and the solver settings. GRNLab is a data generator only. It does not infer, recover, or score networks.

Installation

Two options:

Packaged toolbox. Double-click releases/GRNLab.mltbx. MATLAB installs it as an add-on, puts it on the path, and registers this guide in the Help browser (Help > Supplemental Software > GRNLab).
From source. Add the toolbox folder to the path:

addpath("toolbox")

Requirements: MATLAB R2021b or newer. No other toolboxes are needed. Parallel computing is not used.

Ten lines to a dataset

grn.catalog()                                        % what is available

S     = grn.randomNetwork(30, Topology = "scalefree", Seed = 2);   % ground truth
model = grn.buildModel(S, Logic = "multiplicative", Seed = 2);      % kinetics
sol   = grn.simulate(model, Cells = 50, RandomIC = true, ...
            Noise = "langevin", NoiseStrength = 0.2, Seed = 2);     % data

size(sol.x)            % 501 x 30 x 50: samples x genes x cells
sol.S                  % the signed adjacency that generated the data
grn.plotNetwork(model);            % arrowheads = activation, bars = repression
grn.plotExpression(sol, Cell = 3);
grn.export(sol, "grn30.csv");      % + grn30_truth.csv, grn30_adjacency.csv

Output

Regulatory motifs (grn.motif / grn.buildModel):
         <strong>motif</strong>          <strong>genes</strong>                                 <strong>description</strong>                              
    <strong>________________</strong>    <strong>_____</strong>    <strong>______________________________________________________________________</strong>

    "toggle"              2      "Toggle switch: mutual repression, bistable for cooperative binding"  
    "repressilator"       3      "Repressilator: three-gene ring of repressors, limit-cycle oscillator"
    "nar"                 1      "Negative autoregulation: fast, robust response"                      
    "par"                 1      "Positive autoregulation: slow, possibly bistable"                    
    "ffl_coherent"        3      "Coherent type-1 feed-forward loop: sign-sensitive delay"             
    "ffl_incoherent"      3      "Incoherent type-1 feed-forward loop: pulse generator"                
    "cascade"             4      "Linear activation cascade of 4 genes"                                
    "sim"                 4      "Single-input module: one TF driving 3 targets"                       
    "bifan"               4      "Bi-fan: two TFs jointly regulating two targets"                      
    "goodwin"             3      "Goodwin oscillator: activation chain closed by repression"           

Random topologies (grn.randomNetwork Topology option):
    erdosrenyi   independent edges, Poisson in-degree
    scalefree    preferential attachment on regulators (hub TFs)
    smallworld   directed ring lattice with random rewiring
    modular      dense modules with sparse inter-module edges

Output

ans =

   501    30    50

ans =

     0    -1     1     0     0     0
    -1     0    -1     0     0     0
     1    -1     0     0     0     0
     1     0    -1     0     0     0
     1     1     0     0     0     0
    -1    -1     0     0     0     0

ans = 

  1×6 <a href="matlab:helpPopup('string')" style="font-weight:bold">string</a> array

    "G1"    "G2"    "G3"    "G4"    "G5"    "G6"

The ground truth of the example: 30 genes, 60 edges. Arrowheads mark activation, bars mark repression, and node size grows with the number of targets, so the three hub regulators G1, G2, G3 stand out.

Cell 3 of the 50 cells. Top: the twelve most variable genes, with the other 49 cells drawn faintly behind. Bottom: all 30 genes as a genes-by-time heat map. Genes without regulators sit at their constitutive level; most others are held down by the repressor-heavy hubs.

Output

    "/private/var/folders/4p/lyl8zns92f533lvhlldbpm0w0000gq/T/grn30.csv"
    "/private/var/folders/4p/lyl8zns92f533lvhlldbpm0w0000gq/T/grn30_truth.csv"
    "/private/var/folders/4p/lyl8zns92f533lvhlldbpm0w0000gq/T/grn30_adjacency.csv"

The three objects you will handle

Object	Made by	What it holds
Adjacency `S`	`grn.randomNetwork`, `grn.motif`, or your own matrix	The signed network: `S(i,j) = +1` if gene j activates gene i, `-1` if it represses it, `0` otherwise
Model	`grn.buildModel`	`S` plus every kinetic parameter, the initial condition, and function handles for the right-hand side and Jacobian
Solution / screen	`grn.simulate`, `grn.knockoutScreen`	The data, the time grid, the model that produced it, and the options used

Everything downstream (perturbations, stimuli, steady states, plots, export) takes a model or a solution and never loses the ground truth.

Motifs by name

Ten classic motifs are registered with parameter presets that reproduce their textbook behaviour. A motif name can be used wherever a model is expected:

sol = grn.simulate("repressilator");             % oscillates
model = grn.buildModel("toggle");                % bistable
hi = grn.steadyState(model, InitialCondition = [5; 0]);
lo = grn.steadyState(model, InitialCondition = [0; 5]);
grn.plotMotifs();                                % gallery of all ten

Output

The ten registered motifs. Feed-forward motifs are laid out with regulators above their targets; autoregulation is a loop.

Reproducibility

Every random choice is driven by a Seed option that defaults to 0. Network topology, parameter sampling, random initial conditions, process noise, and observation noise are all seeded, and cell k of a multi-cell simulation uses seed Seed + k - 1. Rerunning the same call gives bit-identical data. The solution struct records the seed and every option, so sol.options and sol.model are a complete recipe.

Where next

Concepts and conventions: the equations, the orientation of S, and the fields of a model.
Simulating expression data: solvers, cells, noise, and the solution struct.
Recipes: complete workflows for benchmark datasets, dose-response experiments, and DREAM-style packages.
Function reference: every function and option on one page.

Concepts and conventions →