m = pwConvertCustomFormatToPW(inFile, outFile, opt, verbosity, openFile, addModel)

 Converts a custom model file into a valid PottersWheel model definition file.


Arguments for pwConvertCustomFormatToPW

 inFile        File that will be converted.
 outFile       Created PottersWheel model definition file.
 opt           Struct or a string corresponding to a predefined setting.
               See below for details.
 verbosity     1: error messages (default)
               2: also matched headers
               3: also matched lines (good for debugging of custom regular expressions)
 openFile      Open converted file when conversion is finished.
               Default: false
 addModel      If true, the converted model is added to PottersWheel directly.
               Default: true (this might change in a future version)

 Predefined settings for opt:

 'BNG'                   BioNetGen
 'Numerica_Jacobian'     Numerica Jacobian
 'CellML_MatlabExport'   CellML Matlab export using
 'SB_Toolbox'            SB Toolbox model file (sbtoolbox)


Specifying the custom file structure

 The following fields belong to the opt struct.


Ignoring comments

 Lines starting with a comment symbol (either # or % or //) will be ignored:

  .commentStyle = 'shell' or 'matlab' or 'c' or 'c++'


Deleting and replacing characters and strings


Important ASCII characters

10Line feed \n
12Form feed \f
13Carriage return \r
34Quotation marks "

Ascii characters

    .AsciiCharToBeDeleted % Decimal representation of ASCII characters to be deleted
    .AsciiCharReplaceIgnoreSection % no replacement in sections bounded by the given character


Normal expressions

    .ToBeDeleted       (cell array)
    .ToBeReplacedOld   (cell array)
    .ToBeReplacedNew   (cell array)


Regular expressions

    .ToBeDeletedWithRegExp (cell array)
    .ToBeReplacedOldRegExp (cell array)
    .ToBeReplacedNewRegExp (cell array)


Replacement of normal expressions listed in a file

    .FileBasedReplacementFilenames (cell array of filenames)
    .FileBasedReplacementPatterns  (cell array of regular expression with named tags <old> and <new>)


Object matching

.parse(i)Struct array with the following elements
.patternRegular expression with named fields.
The field names must be a subset of fields of
the given class.
.headerExpression after which lines are compared with pattern.
A new header terminates parsing of other elements
.footerExpression after which lines are no longer compared with pattern.
Note that repetitions of header/footer sections are permitted.
The footer itself is not compared with the pattern, too.
Footers are optional.
.classModel field classes
'a', 'c', 'f', 'k', 'o', 'p', 'r', 's', 'u', 'v', 'x', 'y', 'z'
a) pwAddA, algebraic equation/assignment rule
c) pwAddC, compartment
f) pwAddUserFunction, user defined function
k) pwAddK, dynamic parameter
o) pwAddO, ODE
p) pwAddP, derived parameter
r) pwAddR, reaction
s) pwAddS, observation / scaling parameter
u) pwAddU, driving input
v) pwAddV, reaction rate
x) pwAddX, dynamic variable
y) pwAddY, observable
z) pwAddZ, derived variable
This field should not be mistaken with the classname of a variable.
.splitterCell array, where splitter{i} contains all delimiters
that are used to split matched field i into a cell arry.
Empty, if no field of pattern should be splitted.
If splitter{i} is empty, than field i is not splitted.
.commandIf no class is specified, a custom Matlab command can be used,
e.g. to specify the ID of a model. Expressions in the command
which are identical to a named token in the regular expression
and which are embraced by <> are replaced, e.g.
pattern = '(?<ID>\w+)'; command = 'm.ID = ''<ID>'';'


 This function provides a convenient and powerful way to map elements of a
 custom model file structure to a PottersWheel model definition file.

 Sections of the custom file are compared line by line with regular expressions
 as specified in one or more 'parse' structs. Each section of the custom model
 should start with a header and may end with a footer. The patterns of the
 regular expressions should have named tags, e.g., (?<reactants>.+)
 The names will be compared with the field names of PottersWheel
 model definition classes, e.g. the ID and value fields of the class 'x',
 the dynamic variables. The converter knows whether a field must be transferred
 e.g. into a number or a string. If a field belongs to a string array, as
 for example the reactants and products of a reaction, it will be splitted
 using the delimiters given in parse(i).splitter.


Field names

 Available fields of a variable class are available using pwGetClassFields.
 The following command will list all fields of an x variable:



Advanced usage

 Several parse structs may share the same header and consequently different
 patterns may be applied to the same section. If a line matches any footer
 no matching is applied any more. The same holds if a new header is found
 - then only matches are applied of the parse structs that correspond to the
 new header.



 1. A custom model definition file

 A + B -> C; kf1
 B <-> D; kf2, kr2
 D -> A + E; kf3

 Start values
 A = 1
 B = 0
 C = 0
 D = 0
 E = 0

 k1 = 0.1
 k2 = 0.5
 k3 = 1

 2. The corresponding parsing structs:

 opt = [];

 opt.parse(1).header   = 'Reactions';
 opt.parse(1).pattern  = '(?<reactants>.+) (->|<->) (?<products>.+); (?<parameters>.+)';
 opt.parse(1).class    = 'r';
 opt.parse(1).splitter = {'+', '+', ','};

 opt.parse(2).header   = 'Start values';
 opt.parse(2).pattern  = '(?<ID>.+) = (?<startValue>.+)';
 opt.parse(2).class    = 'x';

 opt.parse(3).header   = 'Parameters';
 opt.parse(3).pattern  = '(?<ID>.+) = (?<value>.+)';
 opt.parse(3).class    = 'k';

See also