charite.christo.metannogen.MetannogenMain

Starting Metannogen - command line options

Metannogen requires Java version 1.5 or higher. It consists of a single -file metannogen.jar. Further data-files or program parts are automatically downloaded at runtime from the Web-server. Therefore the computer needs to be connected to the internet. The file metannogen.jar can be started in two different ways:

Using the java-command:
```
  java -Xmx200M -jar metannogen.jar  [options]
```
The option -Xmx200M increases the maximum amount of memory allocated by the Java Virtual Machine to 200 MBytes.
Using (): The command javaws acts on the file metannogen.jnlp. The JNLP file may be inspected with any text editor. A modified copy can be saved. It contains the command line parameters and the the value for the maximum memory.
```
  javaws http://www.charite.de/bioinf/strap/metannogen/metannogen.jnlp
```

Web proxy
In some institutions all Internet connections are going through a Web proxy (see ). In this case the proxy must be set correctly, otherwise downloading of files from the Web will fail. Detailed explanation is found in "Menu-bar>Options>Internet settings" or by clicking the button "Test Web Proxy" in the start frame of Metannogen.

Command line parameters of Metannogen
Metannogen takes a number of optional command line parameters. If Metannogen is started using the Java-Web-Start mechanism, the command line options are defined in the JNLP file. Some command line options are followed by one or more text files. Files can be given as a relative or absolute file path or in form of an URL.

General format of dictionaries:
For the syntax of most dictionaries two options exist:

Lines with Tab-separated entries: If the dictionary file contains tabulator characters then Metannogen assumes that each line contains a key-value pair such that both are separated by tabulator. The first column in the tab-separated file contains the keys and the second column the values.
This can be altered with a suffix of the URL or file path. For example appending "(3,4)" to the url, the key will be read from the 3rd and the value from the 4th column (numbering starting with "1").
Lines with Space-separated entries: However, if the file does not contain any tab, then Metannogen assumes that white space is the separator of keys and values. With space as separator, lines with different keys but identical values might be combined to one line. The advantage is, that the resulting file is more compact. For example the two lines:
```
      C00124  C00962
      C01582  C00962
    
```
can be written as one line (If the file does not contain any tab-character.)
```
      C01582 C00124  C00962
    
```

-networks List of files
The given SBML files are loaded into Metannogen and can be browsed offline. They form a repository of information that can be used for network reconstruction. Three widely used networks can be referenced by abbreviations, for all other networks the full URL or file pathe of the SBML file must be written.
- "KEGG" is a symbol for the database,
- "RECON1" stands for the Human Metabolic Network of the Palsson group http://www.charite.de/bioinf/strap/metannogen/data/Palsson_human_2007_04_ascii.sbml.gz
- "EHMN" designates the Edinburgh human metabolic network.
- Networks within network databases can be given with the database ID followed by the network ID. Examples: JWS:Lambeth BIOMD0000000001
-dictionaryOfSpecies List of text files containing identifier replacements
Example:
```
      ...
      C00124  C00962 # D-Galactose
      C01582  C00962 # D-Galactose
      C00984  C00962 # D-Galactose
      C00159  C00936 # D-Mannose
      C02209  C00936 # D-Mannose
      ...
    
```
Read: "Replace metabolite C00124" by "C00962". The value to be replaced is at the left and the replacement is at the rigth position. The identifiers are separated by white space. The same can be written in a more compact way:
```
      ...
      C00124 C01582 C00984 C00962 # D-Galactose
      C00159 C02209 C00936  # D-Mannose
      ...
    
```
The SBML output will contain C00936 even if C00159 or C02209 appear in the biochemical equation.
-dictionaryOfCompartments List of text files translating compartment names.
For some reactions the exact subcellular localization may be found in the literature, while for other reactions less specific information may be found. Metannogen supports subcellular localizations of individual reactions at level that is more specific than the final model. For example there may be evidence that a reaction takes place at a certain part of a golgi. This information may be recorded by the curator. But for metabolic network analysis distinction between cis- and transgoli is not suitable. Example:
```
      ...
      cisGolgi   golgi
      transGolgi golgi
      ...
	
```
or shorter
```
      ...
      cisGolgi transGolgi  golgi
      ...
	
```
The compartment names are separated by white space. The left compartment name is replaced by the right compartment name. In this example the SBML output will contain only "golgi" and not "cisGolgi" and "transGolgi". During data curation the compartments are recorded in more detail than needed.
-names List of text files for associating a human readable name to metabolite identifier
The two columns are separated by tab.
```
      ...
      C05928\t10-Formyltetrahydrofolyl
      C05931\tN-Succinyl-L-glutamate
      ...
	
```
-replaceInEquation List of text files providing a dictionary for metabolite replacements.
This replacement is applied when the network model is generated from datasets. The replacement is performed before the dataset is parsed. It is possible to replace sets of species by single entries. For example the following line is valid:
```
      LEUKOTRIENE\tleua4 leub4 leuc4 leud4 leue4 leuf4
    
```
Having this declaration, typing "LEUKOTRIENE" in the equation is semantically equivalant as typing "leua4 leub4 leuc4 leud4 leue4 leuf4". This notion might be useful in conjunction with brace expansion for example for transmembrane transport processes. Please note that in this example the first whitespce is a tabulator and the following white spaces are space-character.
-replaceWhileTyping List of text files providing a dictionary for metabolite replacements.
The replacement is applied in the text-field for the biochemical equation if the respective option is activated in the Menu-bar>Options. When biochemical equations are typed, the specified replacements will be applied automatically after the user has finished typing a metabolite. This is triggered by inserting a white space character after the identifier or by inserting longer text using Ctrl-V or the middle mouse button. In the example below C00022 is the KEGG identifier for Pyruvate and pyr my be a display name for pyruvate. If the user types "pyr" and hits the space bar, "pyr" would be replaced by "C00001".
```
      ...
      H2O water C00001
      pyr C00022
      ...
	
```
Loading networks like KEGG or RECON1 automatically activates replacement of metabolite names by identifiers. This replacement works independent of the option "-replaceWhileTyping". The identifiers and names are separated by white space.
-dictionaryOfSimilarSpecies List of text files associating a representative identifier to similar compound identifiers.
Example:
```
      ...
      C01342  C00014  #  Ammonia NH3 NH4+
      C01353  C00288 C00011 #  H2CO3 HCO3-  CO2
      ...
    
```
Biochemical reactions are sometimes written in different ways as a question of taste: Either with NH3 or NH4⁺ or either with CO2 or HCO3^-. As a consequence, Metannogen may fail to recognize that two biochemical equations denote the same catalytic process. This is avoided by providing a dictionary of similar species metabolites and by ignoring H+. Including NH3/NH4⁺ and HCO3^-/CO2 into the dictionary, for additional 53 reactions in KEGG an identical counterpart is found in Recon1. The identifiers and names are separated by white space.
This dictionary does not affect network output. It is only used in the GUI to determine whether two reactions are identical.
-proton List of identifiers designating protons. When two reactions are checked for identity, protons are not regarded. To recognize that two reactions are equal if they differ only by one H⁺, the metabolite identifiers for H⁺ must be known. This is used for the GUI but does not affect the exported model.
-datasetForms List of input masks for datasets. Input masks are free text containing empty variable declarations to be filled in by the curator. This allows to enter information in a structured form. All information written in variables are accessible with the API and can be used for the output file.
-listOfCompartments File with a list of compartments.. This list is used for the compartment selector menu.
-mapAffymetrixRid file or URL
Mappings of or identifiers to reaction identifiers. This dictionary is important for two features in Metannogen: Expression values provided in a -separated_value text file can be displayed graphically in the KEGG Pathway maps. Each text line of the data file is assigned to one or several KEGG reactions. If a text line contains a KEGG identifier then the assignment is straight forward, but if the lines contain other identifiers such as, Ensembl- or Affymetrix-identifiers the respective KEGG reaction is found with the use of the dictionary. The dictionary is also used for highlighting certain reactions in the graphical map using a list of KEGG identifiers or Affymetrix or Ensembl identifiers. A reaction is selected by ctrl-left-click the reaction box in the graphical map. It is unselected by shift-ctrl-left-click. The file as the following structure:
```
      ...
      208308_s_at \t R02740
      204704_s_at 202022_at 200966_x_at \t R01070 R01068
      ...
	
```
In the left column are one or several or identifiers which denote a gene or an oligonucleotide, respectively. In the right column are one or several reaction identifiers. Please note, that a respective mapping is already automatically generated from the KEGG database for human and murine Ensembl identifiers via KEGG-orthologies but for other species the user must provide the mapping.
-customizeAddScriptByRegex File with List of shell scripts
Executing shell command. In general, customizable text can be changed with the option -customizeAddName.

Metannogen for network reconstruction - non-graphical mode

This chapter explains, how a network reconstructed with Metannogen can be exported using different file formats like SBML. This does not apply to the case that metannogen is used to annotate an SBML file. Though the file export function is accessible in the GUI (Menu-bar>File), the prefered way is to run Metannogen as a command line tool without GUI. This allows Metannogen to be included in shell scripts. Complex pipelines can be constructed to directly couple Metannogen with data analysis. The option "-datasets" and an option like "-toSBML1" are required. The other options are optional.

-datasets File with datasets
Loads the dataset files from the given file or URL. The URL usually points to a Perl or PHP script which concatenates the single text files of each dataset to one text files. Two possible applications:
1. When Metannogen is used from another program to access the data programmatically. In this case the other program invokes:
```
charite.christo.metannogen.Metannogen.main("-datasets","file.txt"); 
```
2. To export the data in non-interactive mode. In this case it is used together with an option like -toSBML1 output-file

-toModifiedSBML OutputFile
Example:

      java -jar metannogen.jar -datasets datasetFile -networks "http://www.ebi.ac.uk/biomodels-main/download?mid=BIOMD0000000001" -toModifiedSBML output.sbml

The given file here BIOMD0000000001 is written to output.sbml. Annotations found in datasetFile are inserted into output.sbml.

-toSBML1 OutputFile
The customizable output script No 1 is used to generate output. If script No 1 was not modified by the user, then the default SBML output is used. This command line option requires, that the dataset source is specified with the -datasets option.
Different versions of export scripts: The user may also refer to Export_SBML2.java by using the option -toSBML2. Each export script Export_SBML[number].java can be modified at runtime using the GUI. Without restarting Metannogen, the modified export script can be run to export the file. The following options are analogous: -toSBML2, -toSBML3 ... or -toTXT2 or -toSQL2 or -toLIBSBML2. The latter requires installation of the program library libsbml (http://sbml.org/Software/libSBML). Detailed instructions are found in the source code of the export script and in the respective tutorial.
-attributes List of text files with variable declarations
The two columns are separated by tab. The first column contains the dataset identifier, the second column contains one or several variable declarations separated by white space. Content containing white space must be quoted with double quotes.
```
      ...
      R00959\t$VAR1="variable one for dataset R00959 "   $VAR2_cyto="This is only valid for cytosol"
      R00960\t$VAR1="variable one for Dataset R00960 "   $VAR2_cyto="This is only valid for cytosol"
      ...
	
```
-annotationFormats List of text files with annotation formats
The text files describe how attributes like $IS_PART=" UNIPROT:P0A7B8 UNIPROT:HSLV_ECOLI " are translated into annotation texts like The two columns are separated by tab. The left column contains the attribute name and the right column the xml text. The files contains also the mapping of Metannogen database IDs to Miriam-urns. The string "REPLACE" will be replaced by the respective urn:ID. The file http://www.bioinformatics.org/strap/metannogen/data/annotationFormats.txt will always be loaded.
-useReactionAttributes List of attribute names for export.
Attributes contain additional information for elements (Also see http://www.w3schools.com/Xml/xml_attributes.asp). In SBML several standard attributes for reaction and species elements are well defined. Nevertheless, the possibility for additional (non-standard) attributes had been included in Metannogen for two reasons.
- The set of standard attributes may be extended in future SBML versions.
- A computer program that takes SBML as input may accept information in form of non-standard attributes.
Attributes are defined by the user in the comment text area of datasets using a syntax which is similar to variable declarations in . They may also be defined in text files given in the command line after the "-useReactionAttributes" option.
-useSpeciesAttributes Equivalent to "-useReactionAttributes".
-attributesOverride List of text files with variable declarations
Same as "-attributes" with the difference that the variables override the variables defined in the comment text of datasets.
-exportReactionIDs List of text files providing a set of reaction identifiers to be exported
```
      R01271
      R00301
      HR05020.*
    
```
Tokens containing asterisk are treated as ion. The compartment suffix like "@cyto" ist optional. If this option is given, only the specified reactions are included in the output. All other reactions are skipped.
-exportReactionIDs one file defining shell scripts which are applied to selected texts and Object IDs

The following command line options are only important under very special circumstances:

-noExit
Metannogen will not terminate the Java-process. This option is only important when the main-method charite.christo.metannogen.Metannogen.main(String[]) is called from another program.

Specifying the command line options jnlp file: The command line options are specified in the jnlp file that is behind the Web-start button. This file need to be modified when other program options are required. It can be downloaded to the Desktop and edited with a text editor. When the file is clicked on the Desktop Metannogen is started.