E-CELL2 User's Manual
Chapter 4 E-CELL2 Creating Rule Files [ Chapter 1 : Chapter 2 : Chapter 3 : Chapter 5 ][ TOP ]
2 Filling out spreadsheets
2.2 The SYSTEM SECTION
2.3 The SUBSTANCE SECTION
2.4 The REACTOR SECTION
2.5 The INCLUDE SECTION
3 Saving and Converting spreadsheet files
3.1 Saving spread sheets
3.2 Converting of er files
Rule Files are data files in which users specify the information required to run a simulation in E-CELL2. In this file, all substances (including enzymes), interactions (reactions) between substances, and environmental parameters such as the volume of the system are defined. Furthermore, Rule Files can also describe specifications of the integration system used for calculation.
Users can also create Reactor Files (see Chapter 3), which are programs that compute rates of particular reactions, and changes the quantity ,such as of a substance etc. according to the formula by specification of Rule Files.
There are three types of Rule File:
In order to create Rule Files, users can use a spreadsheet or write the er files manually. It is easier to use spreadsheet to create Rule Files, because it is easy to understand visually when wide-used spreadsheet software is used. As er files are text files, they can be modified with macros. Both txt and er files need to be converted into eri files before they can be loaded into the E-CELL2 system. (If spreadsheet is used, it is converted into er files first, then into eri files.) Rule files consists of four sections: the SYSTEM SECTION which defines the model's environment, the SUBSTANCE SECTION which defines all substances in the model, the REACTOR SECTION which defines reactions and interactions, and the INCLUDE SECTION for merging with other Rule Files. The specific order of the four SECTIONS within a Rule File is not important, so they can be specified in the intelligible arbitrary order. This chapter explains how to create Rule Files using spreadsheets (additional information on er files are at the end of this chapter).
- txt files (tab-delimited files)
- er files
- eri files
2 Filling out spreadsheets
This chapter explains headers of, which divide parts and the four parts giving examples of Rule Files. The following characters are forbidden to use for describing the contents of E-CELL2 spread sheets:
Each column is distinguished from the others by tabs as delimiter. Therefore, spreadsheet entries containing these characters will cause errors when trying to convert the spreadsheet into an er file.
- Single quotes (')
- Double quotes (")
In a spread sheet, it is necessary to give headers in each part. The rows containing Headers are called Header Lines, and are necessary to separate the different sections of the E-CELL2 spread sheet. The first line in every SECTION must, therefore, be a Header Line.
Figure 1 shows a typical E-CELL2 spread sheet with the Header Lines highlighted in blue.
Headers are case insensitive and can appear in any order within a single Header Line.
An optional Header, named Memo, can be added to the end of any Header Line. This is intended for miscellaneous comments, and will be ignored when the spread sheet is converted into an eri file.
Figure 1 Headers
2.2 The SYSTEM SECTION
The structure of the cell model and some environmental parameters for the simulation must be defined in the SYSTEM SECTION. The various compartments of the cell model are defined in the SYSTEM SECTION, together with information about the location of SYSTEMS and their volume.
The Headers used in the SYSTEM SECTION, their definitions and default values are shown in Table 1.
Header Definition Default Value Type
Input required Class Location(System) Input required Path System location in tree structure Input required ID System ID Input required Name System name ID Inside Internal System (Used only in Membrane Class) Input required for Membrane Class Outside External System (Used only in Membrane Class) Input required for Membrane Class VolumeIndex FQEN of Reactor indicating Volume Input required for Systems with volume
Table 1 Headers in SYSTEM SECTION
To define a System in the SYSTEM SECTION, enter [System] in " Type " column. In the " Class " column, specify which class will be used for this System in the simulation. The four classes are Cell, Environment, Cytoplasm and Membrane. All of these classes can contain Substances and Reactors, and also have a volume parameter. However, the Environment and Membrane classes cannot contain any SubSystems. Table 2 outlines the features of the four classes.
Class Substance Reactor Volume Subsystem Cell o o o o Environment o o o x Cytoplasm o o o o Membrane o o o x
Table 2 Class Type Features
Enter the location of the System in the " Path " column. The Path of an E-CELL2 System begins in RootSystem(/), and the subordinate Systems (Subsystems) can be defined by the user.
The complete Path must be specified, using " / " to separate directories (e.g. " /system1/system2/system3 " ). Paths are case sensitive.
The concept of FQEN (Fully Qualified Entry Name) is a method of indicating the location of Substances and Reactors in the tree structure of the System hierarchy. On the other hand, FQEN is a combination of the Path and ID connected by " : " (e.g. " /system0/system1/system2:ID " ). For example, if the Path is " /CELL/CYTOPLASM " and the ID is " ATP " , the FQEN would be " /CELL/CYTOPLASM:ATP " . With FQEN the differences between Systems, Substances and Reactors cannot be distinguished. Therefore this type of information is included in FQPN instead, expressed in the form of [Type] : [FQEN]. With FQPN, the above example would be written as " Substance:/CELL/CYTOPLASM:ATP " . Both FQEN and FQPN are case sensitive.
The ID attribute is a unique identifier for each System, and may not be used more than once in the same System. If the same ID is used more than once in a single System, a warning message will appear during the conversion of the txt file into the er file, and only the first of the entries will be processed. Unlike Headers, IDs are case sensitive.
Enter the ID of the System in the " ID " column, and the name of the System in the " Name " column.
When specifying the Membrane class type, the Inside and Outside columns are used to specify the Systems located on either side of the membrane. Although the current version of E-CELL2 does not utilize this information, development is underway to limit Substance access to relevant Systems only. In the above example (figure 5), the MEMBRANE System exists between the CYTOPLASM and ENVIRONMENT.
In E-CELL2, the System volume is given by a Reactor (see Chapter 5 for details). When defining Systems, therefore, the volume is not specified directly as an attribute of the system. The volume(L) of a System is expressed as the activity of a Reactor, and can be specified in the VolumeIndex column using its FQEN. The user must ensure that the Reactor specified here is defined in the REACTOR SECTION of the spreadsheet. There are some cases where specification of System volume is unnecessary. For example, volume need not be specified for the MEMBRANE System as above. However, it is necessary to define the VolumeIndex of a System if Reactor calculations require Substance concentrations, or if the amount of Substances are specified as concentration values (in the CONC column of the SUBSTANCE SECTION). This is because volume information is necessary to convert concentration values into molecular quantity values used internally by E-CELL2.
2.3 The SUBSTANCE SECTION
All Substances used in the simulation must be defined in the Rule Files. Information concerning each Substance is specified in the SUBSTANCE SECTION.
Headers used in the SUBSTANCE SECTION are as follows:
Header Definition Default Value Type [Substance] Input required Class Usually, [Substance]. This can be blank. Input required Path Location (System) of Substance Input required ID Substance ID Input required Name Substance name ID QTY Initial quantity of Substance(incompatible with Conc) 0 CONC Initial concentration of Substance in M (mol/l)(incompatible with QTY) QTY Arg_tag In case accumulation method of decimal numbers to be specified[Accumulator] This can be blank Arg_coeff Accumulation method of decimal numbers are chosen[Accumulator class] Input required if Accumulator is specified in Arg_tag
Table 3 List of Headers in the SUBSTANCE SECTION
To begin a Substance entry, enter [Substance] in the " Type " column.
In the " Class " column, specify the Class used in each row. At present, only " Substance " can be specified as a Class in the SUBSTANCE SECTION. Therefore, type " Substance " in the " Class " column.The software will assign " Substance " as a Class by default if this column is left blank.
Enter the System location of Substance in the Path column. The Path is denoted using " / " characters as delimiters between parent and child systems (e.g. " /system1/system2/system3 " ),same as the Path column in the System Section.Note that in cases where two Substances with the same ID and Name exist in different Systems, E-CELL2 recognizes them as different Substances. This attribute is case sensitive.
Specify the Substance ID and Name in the " ID " and " Name " columns. These entries are case sensitive.
The " QTY " (Quantity) attribute defines the initial quantity of molecules. The QTY attribute cannot be used with the CONC attribute. If both values are defined, a warning message will appear and only the QTY value alone will be loaded into E-CELL2. If neither the QTY nor CONC values are specified, the QTY value will be set to zero. The " Fix " option can be used to make the value constant. Refer to the later section for the fix function.
Enter Concentration M (mol/l) of Substances in the " CONC " column. When converting er files to eri files, concentration values are converted to QTY values at runtime using the volume specified in the " init_act " column of REACTOR SECTION in system, and the Avogadro constant. The values of QTY and CONC are exclusive of each other (only one should be specified), and if Conc cell is left blank, Qty value would be printed in eri file. Similarly, note that when VolumeIndex is not specified even if Conc value is specified, it will be assumed as Volume=0. The value can be fixed using Fix function.
The Fix Function
The Fix function sets QTY or CONC values to be constant during simulation, as specified substance is not influenced by increase and decrease of Reactor. Enter the word " Fix " below the QTY or CONC value.
The Accumulator class encapsulates methods to accumulate substance quantities. When specifying Accumulators, enter the word " Accumulator " in Arg_tag column, and specify the Accumulator class name in the Arg_coeff column.
A list of available classes is shown below (Table.4). However, calculation accuracy has not been guaranteed when specifying the different accumulation method for every substance.
Type the Accumulator class which encapsulated the accumulation method of substance in Arg_coeff.
Classname Function ReserveAccumulator Utilizes reserve accumulation methods where integers and decimals of a number are calculated separately. Only integers are expressed in the simulation while decimal numbers are reserved. When reserved decimal values become greater than or equal to 1.0, or less than 0.0, the integer value is incremented or decremented.
The amount of change Integers Decimal numbers initial value 0 0 0.8 0 0.8 0.8 1 0.6 0.8 2 0.4 SimpleAccumulator Calculates real numbers directly. Decimal numbers will be expressed as decimal numbers instead of integers. Precision is dependent on the CPU and compiler, with a maximum of 18 digits for an i386 CPU, and 15 digits for an alpha CPU. RoundDownAccumulator Numbers are rounded down to the integer. Numbers after the decimal point are ignored. (e.g. if the calculated result of a reactor 5.25, the value is expressed as 5). RoundOffAccumulator Numbers are rounded up or down to the nearest whole number. (e.g. if the calculated result of a reactor is 5.74, the value is expressed as 6). MonteCarloAccumulator Integers and decimal numbers are calculated separately. Decimal numbers calculated by reactors are converted to integers stochastically. (e.g. if the calculated result is 3.4, the integer is expressed the number 3 on probability 0.6, number 4 on probability 0.4.)
Table 4 List of Accumulator Classes
2.4 The REACTOR SECTION
The REACTOR SECTION defines reactions and other interactions involving the Substances defined in the SUBSTANCE SECTION, interaction between substances for example, as well as equations controlling dynamic environmental variables such as the System volumes. In this section, specific instances of Reactors are defined, by specifying the class of Reactor to be used, as well as information on its substrates, products, and stoichiometry.
Headers in the REACTOR SECTION are as follows:
Header Definition Default Value Type [Reactor] Input required Class Reactor name Input required Path Location (System) Input required ID Reaction ID (Add " ! " before the ID when using PReactors) Input required Name Reaction name ID init_act Initial value of Reactor activity Input required except special cases (VolumeIndex is defined.etc) S_ID Substrate ID Input required S_Path Substrate location(System) Path S_Coeff Stoichiometric coefficient of Substrate 1 P_ID Product ID Input required P_Path Product location(System) Path P_Coeff Stoichiometric coefficient of Product 1 C_ID Catalyst ID Input required C_Path Catalyst location Path arg_tag Name of constant (used in the reaction equation) Input required if it is required for Reactor arg_coeff Value of constant Input required if arg_tag is specified E_ID Substance which affect reaction (Effector) Input required E_Path Effector location(System) Path E_Coeff Coefficient of Effector (depends on Reactor) 1
Table 5 List of Headers in REACTOR SECTION
Specify the class of Reactor to be used in the " Class " column. In the above example, the MichaelisBiBiReactor, which is based on Michaelis-Menten kinetics has been specified. The bottom two lines of the example define the Reactors for System volume. Details for all other standard Reactor types can be found in in the spec sheets, distributed anywhere, maybe through our web site. The reaction ID is specified in the " ID " column. If the reaction uses Postern Reactors, add the character " ! " before the ID name. The Type, Class and ID attributes are case sensitive.
The location of the reaction is specified in the " Path " column. The definition of " Path " is the same as in the other sections. In the above example, the reaction occurs in " /CELL/CYTOPLASM " . Note that this attribute is case sensitive.
Specify the name of the reaction in the " Name " column. If this cell is left blank, the information in the ID cell will be used as the Name attribute when converting to eri.
It is desirable to give Name that is easy to identify whether it has volume for Reactor with volume. If the reaction uses a Postern Reactor, it is necessary to add the character " ! " before the ID name(refer Chapter 5). Note that it is not guaranteed when using " ! " in the beginning of conventional Reactor ID like FluxReactor system.
The " init_act " column is used when it is necessary before starting the simulation. This activity of a Reactor is calculated in each step of calculation. This value must be specified for Reactors which are specified as the VolumeIndex for a System in the SYSTEM SECTION. This int_act is specified as an initial value when the E-CELL2 system read an activity value for the Reactor. If this value is not defined, E-CELL2 will automatically assume a value of zero for volume, resulting in simulation error. The above example is a ConstantParameterReactor representing System volume, with the initial volume defined.
The attribute S_ID is the ID of the substrate(s), and S_Path is the Path specifying the location of the substrate(s). In the above example, " ATP " and " Glc " in the CYTOPLASM act as substrates in the defined reaction. The S_Coeff attribute is used to specify the stoichiometric coefficient for each substrate.
The P_ID attribute is the ID of a product, and P_Path is the Path specifying the location(System) of the product. In the example above, the products " ADP " and " G6P " are located in the CYTOPLASM. The P_Coeff attribute is used to specify the stoichiometric coefficient for each product.
The C_ID attribute is the ID of the catalyst, and C_Path is the Path specifying the location of the catalyst. The C_ID and C_Path attributes are usually identical to the ID and Path of the reaction itself.
The " arg_tag " column is used to declare the constants which are used by the Reactor (this value will be used in the equation of the Reactor). The types of constants that can be used limited by the specification of each Reactor class. Since the MichaelisBiBiReactor is used in this example, the arg_tag's, KcF, KmS are declared (refer to the spec sheet for information on standard Reactors and their arg_tag). When more than one arg_tag needs to be defined, use the row below the previous arg_tag for each additional arg_tag. There is no need to re-specify the other attributes of the Reactor for the additional rows (Figure 17). The " Arg_tag " attributes are case sensitive. If the ConstantParameterReactor (the Reactor used for volume calculations in the sample rule file) is to be used, the " Value " constant must be declared in this column(Figure 20).
Enter the value of each constant in the " arg_coeff " column next to the " arg_tag " column. The values for each constant declared in the " arg_tag " column are specified here. In this example of the MichaelisBiBiReactor, the values for KcF, KmS are entered in their respective rows.
When the ConstantParameterReactor is used, the System volume should be specified here as the value of the " Value " constant (Figure 18). E-CELL2 refers to " init_act " for the initial volume (used in the first step of simulation only). In subsequent steps of simulation, E-CELL2 refers to the output of the Reactor for the volume value.
Effectors are Substances, like Substrate or Product, which influence the rate of reaction, but are synthesized or degraded by the reaction. The E_ID and E_Path attributes specify the ID and location of the effector. The E_Coeff attribute is the effector coefficient to be used in computing the rate of reaction. The use of " E_Coeff " depends on each Reactor (refer to Chapter 5).
2.5 The INCLUDE SECTION
The INCLUDE SECTION allows specification of other er files, the contents of which should be merged with the contents of this file when generating the final eri file. This function is useful when there are definitions in other er files that can be reused. The INCLUDE SECTION is omitted in cases where all the information needed for the simulation is written in one spreadsheet. Specify the other file in the INCLUDE SECTION , and the information will be printed in the eri file. In the " Type " column, the word " Include " is entered. The " Filename " column specifies the filename of the er file to be included. In the example above, a file named " sample.er " will be merged with this file when generating the final eri file.
3 Saving and Converting spread sheets
3.1 Saving spread sheets
Spread sheets must be saved in text format with the field delimiter option set to tabs, which is the format recognized by the converting script, to convert into eri file. This is written in the only format to be read by the E-CELL2 System. When creating text with tabs, it is useful to use software like EXCEL. A few samples of text files with tabs are shown in the directory " standard\SAMPLE " with the extension " .txt " . By default this directory will be " C:\E-CELL2\standard\SAMPLE " , and on Cygwin, it will be recognized as " /cygdrive/c/E-CELL2/standard/SAMPLE " . The software that helps creating Rule Files is in the directory " tools\rule " , and " C:\E-CELL2\tools2rule " is the directory when the software was installed, which is identical to , " /cygdrive/c/E-CELL2/tools/rule " on Cygwin. The Perl, language must be available on Cygwin.
3.2 Conversion of er files
To simulate in the E-CELL2 System, spread sheets must be converted into eri files using ss2er.pl, which convert spreadsheets into er files, and er2eri.sh, which convert er files into eri files. A spreadsheet is saved as a text file with tabs, so that ss2er.pl can analyze the file. In this situation, it is assumed that the directory to save the file in is " C:\E-CELL2\tools\rule " ,by default. This directory is recognized as " /cygdrive/c/E-CELL2/tools/rule " on Cygwin. After your spread sheet was finished, use " cd " command to move to this directory, and type.% ./ss2er.pl < filename.txt > filename.er
This will convert the spreadsheet file into an er file. Note that the extension must be " .er " . This step is unnecessary if an er file has been written manually. Then, an er file will be converted into an eri file, which is the last type of file that the E-CELL2 System read, using er2eri.sh
To run the er2eri program, type:% ./er2eri.sh filename
Note that the extension " .er " must be omitted when use this command. When executing this shell script, the corresponding Rule Intermediate file " .eri " will be created. In the GUI mode, chose [Load Rule] in [File] menu in the ControlPanel to open the file selection window to read a " .eri " file. Refer to Section 1 of Chapter 2 for E-CELL2 startup.
E-CELL2 User's Manual
Last Update $Date: 2002/07/16 16:45:42 $
Chapter 4 E-CELL2 Creating Rule Files[ Chapter 1 : Chapter 2 : Chapter 3 : Chapter 5 ][ TOP ]