> | E-CELL2 User's Manual |  | Chapter 4 E-CELL2 Creating Rule Files [ Chapter 1 : Chapter 2 : Chapter 3 : Chapter 5 ][ TOP ]

> INDEX

> 1 Introduction 2 Filling out spreadsheets 2.1 Headers 2.2 The SYSTEM SECTION FQEN,FQPN 2.3 The SUBSTANCE SECTION Fix function Accumulators 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

> # 1 Introduction

> 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:

> - txt files (tab-delimited files)
> - er files
> - eri files
> 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).

> # 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:

> - Tabs
> - Single quotes (')
> - Double quotes (")
> 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.

> ## 2.1 Headers

> 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 | `System` | 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 `System`s with volume

> Table 1 Headers in SYSTEM SECTION
> Figure 2

> 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 `Substance`s and `Reactor`s, and also have a volume parameter. However, the Environment and Membrane classes cannot contain any Sub`System`s. 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

> Figure 3

> Enter the location of the `System` in the " Path " column. The Path of an E-CELL2 System begins in RootSystem(/), and the subordinate `System`s (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.

> ### FQEN, FQPN

> The concept of FQEN (Fully Qualified Entry Name) is a method of indicating the location of `Substance`s and `Reactor`s 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 `System`s, `Substance`s and `Reactor`s 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.

> Figure 4

> 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.

> Figure 5

> When specifying the Membrane class type, the Inside and Outside columns are used to specify the `System`s 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 `System`s only. In the above example (figure 5), the MEMBRANE `System` exists between the CYTOPLASM and ENVIRONMENT.

> Figure 6

> In E-CELL2, the `System` volume is given by a `Reactor` (see Chapter 5 for details). When defining `System`s, 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 `Substance`s 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 `Substance`s 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
> Figure 7

> To begin a `Substance` entry, enter [Substance] in the " Type " column.

> Figure 8

> 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.

> Figure 9

> 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 `Substance`s with the same ID and Name exist in different `System`s, E-CELL2 recognizes them as different `Substance`s. This attribute is case sensitive.

> Figure 10

> Specify the `Substance` ID and Name in the " ID " and " Name " columns. These entries are case sensitive.

> Figure 11

> 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.

> Figure 12

> Enter Concentration M (mol/l) of `Substance`s 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

> Figure 13

> 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.

> ### Accumulators

> 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. For example:
> 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 `Substance`s 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 `Reactor`s 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
> Figure 14

> 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 `Reactor`s 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.

> Figure 15

> 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.

> Figure 16

> 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 `Reactor`s 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.

> Figure 17

> 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.

> Figure 18

> 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.

> Figure 19

> 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.

> Figure 20

> 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 `Reactor`s 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

> Figure 21

> 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 ]