Welcome to the DynPop documentation¶

What is DynPop ?¶

DynPop or Dynamic Population simulation is a tool used to simulate the behavior of organisms in a certain defined environment over time either individually or interacting with other organisms.
It uses curated metabolic models, regulatory networks (optional) and a set of defined rules/constraints to mimic real world behavior.
It can also be used to simulate the behavior of organisms inside certain fermentors using feeds and effluxes.

DynPop files¶

1. Main parameters file (Required)¶

The main parameters file represents an Excel file (.xlsx) with a specific sheet for each part of the simulation:

1.1. Organisms¶

This is the sheet that defines the organisms to be used for the simulation and their respective parameters.
It contains the following columns:

• Organism Name: The name of the organism

• Biomass_concentration (gDW/L): The initial biomass concentration of the organism

• Growth_rate_max: The maximum growth rate of the organism (h-1)

• Death_rate: The death rate of the organism (h-1)

• NGAM (ATPM): The maintenance ATP ratio

• Efflux factor: The efflux factor

• Used: 1 if the organism should be used for the simulation and 0 otherwise.

• Model file name: The name of the organism’s model file (should contain the extension .xml or .sbml)

• Model constraints file name: The name of the organism’s model constraints file (should contain the extension .xlsx)

1.2. Environment¶

This is the sheet that defines the initial metabolites present in the external environment and their corresponding parameters.
It contains the following columns:
• Metabolite: The name of the metabolite

Note

The name of the metabolite should be the name that is defined in the organism’s model file.

Generally, the metabolite names are set with the “M_” prefix followed by the actual name and then the localization suffix like “_e”.

The metabolite name defined in the environment sheet should have the same structure minus the “M_” prefix.

For example, if the metabolite’s name is “M_h2o_e”, then the name defined in the environment sheet should be “h2o_e”

• Initial concentration (mmol/L): The initial concentration of the metabolite in the external environment.

• Type: Either “constant” or “variable”. Determines whether the initial concentration defined should stay constant over time or not.

• Target / Source: Either 1 for target, 2 for source or 0 for neither. This is used to calculate statistics at the end of the simulation.
Note
- Target : metabolite of interest
  
  For each target metabolite, there will be the concentration values (final, max, min), the productivity (target final concentration / final time) and if there are any source metabolites, a yield value (target final concentration / consumed source concentration) will be calculated for each source metabolite.
- Source : metabolite that is used by the organism to grow.
- A metabolite that is neither a target nor a source is just a metabolite that is present in the environment.

1.3. Simulation¶

This is the sheet that defines the simulation parameters.
It contains the following columns:

• solver: The solver to be used for the FBA (Flux Balance Analysis) optimization. (currently only the glpk solver is available)

1.4. Initial volume¶

This is the sheet that defines the initial volume of the experiment.
It contains the following columns:

• Initial volume (l): The initial volume of the experiment. It is useful when simulating a fermentation process.

Info

An initial volume value is required even if not simulating a fermentation process.

1.5. Feeds¶

This is the sheet that defines the different input feeds during a fermentation process.
It contains the following columns:

• Feed: The name of the feed

• t_start (h): The time at which the feed will start.

• t_end (h): The time at which the feed will end.

• rate (ml/l/h): The rate at which the feed will be introduced.

• starting / current: The type of feed. Either “starting” or “current”. Determines whether the feed rate is relative to the starting volume (initial volume) or current volume of the experiment.

Info

This sheet should be present in the parameters file with all its columns but could be kept empty (with no values) if no feeds are to be defined
For each defined feed a new sheet should be created with the following columns:

• Metabolite: Name of the metabolite present in the feed. (See metabolite name in environment sheet for more details)

• Metabolite concentration (mmol/L): The concentration of the metabolite in the feed.

Info

The name of the sheet should be the same as the name of the feed defined in the feeds sheet.

For example, if the feed’s name is “Feed1” then the sheet’s name should be “Feed1”.

1.6. Effluxes¶

This is the sheet that defines the different effluxes or output fluxes in a fermentation process.
It contains the following columns:

• Efflux: Name of the efflux

• t_start (h): The time at which the efflux will start.

• t_end (h): The time at which the efflux will end.

• rate (ml/l/h): The rate at which the environment will be reduced.

• starting / current: The type of efflux. Either “starting” or “current”. Determines whether the efflux rate is relative to the starting volume (initial volume) or current volume of the experiment.

Info

This sheet should be present in the parameters file with all its columns but could be kept empty (with no values) if no effluxes are to be defined

1.7. Regulatory Network¶

This is the sheet that defines the regulatory network and initial values files to be used of the RSA (Regulatory Steady-State Analysis) part of the simulation.
It contains the following columns:

• Regulatory network file: The name of the regulatory network file (sbml / xml) to be used in the simulation. (The extension should be included in the name)

• Initial values file: The name of the initial values file (xlsx) to be used in the simulation alongside the regulatory network file. (The extension should be included in the name)

Info

This sheet should be present in the parameters file with all its columns but could be kept empty (with no values) if no regulatory network is to be used.

1.8. ph (optional)¶

This is the sheet that defines the acidic metabolites present in the environment that will be tracked and used to calculate the pH of the environment.
It contains the following columns:

• Metabolite: The name of the acidic metabolite.

• pka: The pKa of the acidic metabolite.
Info

This sheet will only be verified and used if the simulate pH option is checked (Advanced options).

If the simulate pH option is not checked, this sheet will be ignored and not used in the simulation.

Once the simulate pH option is checked, the pH sheet will be required and the simulation will not run if it is not present.

The following checks will be performed on the pH sheet:
- All metabolites defined in the pH sheet should be present in the environment sheet.
- If an acidic metabolite is present in both the pH sheet and the environment sheet but not in any of the models, it will be considered a system buffer in the simulation.
- If an acidic metabolite is present in the pH sheet and in at least one of the models, it will be considered as a regular acidic metabolite in the simulation.
Important notes
- When the simulate pH option is used, the hydrogen "h_e" should not be set as constant otherwise it will be overwritten to be variable if it is.
- If the hydrogen "h_e" is:
  - not present in the environment sheet, it will be added automatically and the initial concentration will be calculated using the predefined initial pH of 6.8.
  - present in the environment sheet but does not have an initial concentration between 0 and 1000 mmol/L, it will be overwritten and the initial concentration will be calculated using the predefined initial pH of 6.8.
  - present in the environment sheet and has an initial concentration between 0 and 1000 mmol/L, it will be kept as is and the pH will be calculated using the initial concentration of hydrogen.
- The initial concentration of each metabolite mentioned in the pH sheet will be considered as the total concentration of both forms (acid and base) of the metabolite and the initial concentration of each form will be calculated using the pKa value of the metabolite.
- The values in the output are those of the base form.

2. Model file(s) (Required)¶

This is the sbml/xml file representing the curated metabolic model of the organism.

3. Model constraints file(s) (Required)¶

For each model file a complementary constraints file should be created.
The constraints file is an Excel file (.xslx) with multiple sheets:

3.1. R_EX¶

This sheet defines the upper and lower bounds of the exchange reactions of the model.
It contains the following columns:

• Name: The name of the exchange reaction.

Note

In the model file all exchange reactions have the prefix “R_EX_”. However in the constraints file the name of the exchange reaction should have the prefix "EX_”.

For example: if the exchange reaction’s name in the model is “R_EX_h2_eb” it should be “EX_h2_eb” in the Name column.

• Lower_bound: The minimum value to be used as a constraint on the flux of the reaction. Unit: h-1.

• Upper_bound: The maximum value to be used as a constraint on the flux of the reaction. Unit: h-1.

3.2. Reactions¶

This sheet defines the upper and lower bounds of the non-exchange reactions of the model.
It contains the following columns:

• Name: The name of the reaction.

Note

In the model file all reactions have the prefix “R_”. However in the constraints file the name of the reaction should have no prefix.

For example: if the reaction’s name in the model is “R_ H2Ot_ec” it should be “H2Ot_ec” in the Name column.

• Lower_bound: The minimum value to be used as a constraint on the flux of the reaction. Unit: h-1.

• Upper_bound: The maximum value to be used as a constraint on the flux of the reaction. Unit: h-1.

3.3. Genes¶

This sheet defines the gene constraints (active or inactive).
It contains the following columns:

• Name: The name of the gene.

Note

In the model file all genes have the prefix “G_”. However in the constraints file the name of the reaction should have no prefix.

For example: if the reaction’s name in the model is “G_BSD11” it should be “BSAD11” in the Name column.

• Value: either 0 if the gene should be inactive or 1 if the gene should be active.

3.4. Equations¶

This sheet defines the constraints that link reactions to each other.
It contains the following columns:
• Equation string: The string that defines the replationship between multiple reactions.
Note

The equation string should be written in the following format:
- The reaction names should not have the “R_” prefix. (For example: if the reaction’s name in the model is “R_H2Ot_ec” it should be “H2Ot_ec” in the equation string.)
- The reaction names can either be separated by “+” or “-”. (For example: “H2_ec + H2Ot_ec” or “H2_ec - H2Ot_ec”.)
- Only one equality (or inequality) is possible by line. (For example : 0 < a < 3*b will have to be written over two lines.)
- Variables can be written without coefficient. If they have one, it must be placed before the variable name separated by a “*”. (Example 3*a + 4*b < 5.)
- The coefficient can be decimal with either a “.” or a “,”. (Example 3.5*a + 4*b < 5 or 3,5*a + 4*b < 5.)
- The negative sign must be on the coefficient. (Example : a+3*-b must be written : a + -3*b.)
- If the equation has a seperate number on either side of the equality sign, it must be written at the end of the side it belongs to. (Example : a + b = c + 3 is acceptable but a + b = 3 + c is not.)

4. Regulatory Network file (optional)¶

The regulatory network file is an sbml/xml file that defines the components of the regulatory network as well as the regulatory rules between them.

5. Initial values file (optional)¶

This initial values file is an Excel file (.xlsx) that is complementary to the regulatory network file.
It is optional for the simulation but required when a regulatory network file is used.
It defines the initial states of each component in the regulatory network.
It is composed of a single sheet with 2 columns:

5.1. Initial states¶

This sheet defines the initial states of the components in the regulatory network.
It contains the following columns:

• Id: The id of the component in the regulatory network.

Note

Unlike the names of metabolites and reactions in the parameters and constraints files (which are stripped of their prefixes), the names of components here are the same as the ones in the model.

• Initial Level: The initial level of the component.

Note

The component’s initial level should be an integer between 0 and the maximum level of the component.

For example, if a component has 3 possible states (0 or 1 or 2), the initial level can be any one of those states.