From laboratory to in silico medium

The refineGEMs toolbox allows users to add their own media definition to the workflows or to their models. Personal media definitions can be converted into a Medium object by calling the function load_external_medium() or added to the media config by using the external_base / add_external options. The input for both is a path to a tab-separated (TSV) file containing the medium information.

The format of the input TSV file and the conversion of a medium definition to an in silico medium will be discussed in the following sections.

Hint

Please contact the developers or leave a comment in this GitHub issue for any suggestions on new media for the internal database.

Medium file format of the toolbox

The file format for a medium usable with the refineGEMs toolbox is a TSV in the following format (with example):

# name: Example minimal glucose medium
# description: Exemplary external medium file compatible with refinegems.classes.medium.load_external_medium.
# reference: https://github.com/draeger-lab/refinegems/issues/165
name	formula	flux	source	BiGG	MetaNetX	SEED	ChEBI	KEGG
Water	H2O	10.0	water	h2o	MNXM2	cpd00001	15377	C00001
Proton	H	10.0	buffer	h	MNXM1	cpd00067	15378	C00080
Dioxygen	O2	20.0	aeration	o2	MNXM4	cpd00007	15379	C00007
Ammonium	NH4	10.0	ammonium chloride	nh4	MNXM15	cpd00013	28938	C01342
Chloride	Cl	10.0	ammonium chloride	cl	MNXM29	cpd00099	17996	C00698
Potassium	K	10.0	potassium phosphate	k	MNXM30	cpd00205	29103	C00238
Phosphate	HO4P	10.0	potassium phosphate	pi	MNXM9	cpd00009	18367	C00009
Sulfate	O4S	10.0	magnesium sulfate	so4	MNXM3	cpd00048	16189	C00059
Magnesium	Mg	10.0	magnesium sulfate	mg2	MNXM726457	cpd00254	18420	C00305
Calcium	Ca	10.0	calcium chloride	ca2	MNXM128	cpd00063	29108	C00076
Iron(II)	Fe	10.0	iron sulfate	fe2	MNXM726711	cpd10515	29033	C14818
D-Glucose	C6H12O6	10.0	glucose	glc__D	MNXM41	cpd00027	4167	C00031

This table is the substance table, containing all the substances, that can be found in the medium, and their corresponding information.

The first non-comment line needs to be the header. The TSV has to contain at least the first four columns as specified in REQUIRED_SUBSTANCE_ATTRIBUTES. An arbitrary amount of additional columns can be added. However, only columns with a name listed in ALLOWED_DATABASE_LINKS will be transferred into the Medium object. These are specifically the databases, that are covered (or soon to be covered) in the database and are therefore kept for mapping purposes.

In addition to the substances, more information about the medium can be added to the file as comment lines. To be correctly identified, these lines need to start with a #. If the descriptor is either name, reference or description, the information will be added as the name, doi and description attribute of the Medium object, respectively.

How to get from a lab medium to the in silico one

To create your own in silico medium definition, follow the steps listed below:

Search papers or provider information for a medium that could be interesting for your organism.
If the paper already contains an in silico definition:
1. Rearrange the data into the format described in Medium file format of the toolbox
2. Go to step 3.
If not, create a table based on Medium file format of the toolbox:
1. Check which substances should be in the medium.
  
  Note
  
  Substance means an independent chemical entity in the context of the medium, e.g., an ion in a salt. Each type of ion in a salt is one substance, even though the salt is one component in the medium recipe, since chemically, they dissolve in aqueous solution. Thus, they can react independently from one another.
  
  If the substances already have an entry in refineGEMs’ database, directly add the information to the TSV.
  
  If they are not in the database, the information needs to be collected:
  The name of the substance needs to be unique if it should later be added to the database. Hence, choosing the IUPAC name of the substance can be a good start. For better human readability, a trivial name can be added, and the full name can be put in brackets instead.
  
  Databases like ChEBI are good sources for the formula. Note that in the case of multi-charge states, the charge state should correspond to the name and formula.
  
  The flux is dependent on the organism but is correlated to the amount of the substance in the medium, as the organism can at most take up as much substance as is in the medium.
  
  Caution
  
  Converting concentrations to fluxes is difficult. Getting the right flux values for your organism directly from a laboratory would be the best option.
  
  The source describes where the substance originates from, e.g. if salt was added to the medium, the substances Na+ and CL- need to be added to the medium, but both originate from the same source, which is written down in the source column. Additionally, a substance can originate from different sources.
  
  Extend and fill the database columns of your choice; the more, the better.
  
  Hint
  
  ChEBI can be a good place to start looking for the substances and often provides links to other databases.
  
  Furthermore, MetaNetX is often well-connected, so searching there first can speed up the process.
  
  When searching for the substance in the different databases, using different synonyms, e.g. found in ChEBI or the formula (with different charge / number of H-atoms), can improve the chance of finding a hit.
  
  Note
  
  If you want to use this medium only for your model with known namespaces, you could potentially add the information only for that specific namespace.
Check if the medium definition lacks relevant components like water, iron, oxygen or carbon dioxide. Trace components like iron are easily missed, as a miniscule amount is often enough to enable growth of bacteria. This amount can already be added by just using tap water instead of distilled water.
If relevant components are missing, search for reasonable explanations to add the corresponding components or justify why these are missing.
The medium is now ready to be used for growth simulation! :)