/** @page libsbml-octave-reading-files Reading and writing SBML content with Octave

This section summarizes how to read and write SBML content using the
facilities provided by libSBML's Octave interface.

<em><p><strong>Note</strong>: The libSBML Octave interface is functionally
identical to the MATLAB interface, <strong>with the exception</strong> that
browsing for files is not available in Octave and, therefore, filenames are
required arguments when using the Octave functions.</em>

@section rf-started Getting started: the 1-minute introduction

The libSBML Octave interface centers around two functions: one called
@c TranslateSBML that can read an SBML document and convert it to a
structure within Octave, and another function called @c OutputSBML that can
convert and write this kind of structure as an SBML document file.  The
following code examples shows how easy it is to use @c TranslateSBML to
read in an SBML file:
@verbatim
octave-3.2.4:21> model = TranslateSBML('test.xml')
model =
{
  typecode = SBML_MODEL
  metaid = 
  notes = <notes>
  <body xmlns="http://www.w3.org/1999/xhtml">
    <p>Simple branch system.</p>
    <p>The reaction looks like this:</p>
    <p>reaction-1:   X0 -&gt; S1; k1*X0;</p>
    <p>reaction-2:   S1 -&gt; X1; k2*S1;</p>
    <p>reaction-3:   S1 -&gt; X2; k3*S1;</p>
  </body>
</notes>
  annotation = 
  SBML_level = 2
  SBML_version = 1
  name = 
  id = Branch
  functionDefinition =
  {
    1x0 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      name
      id
      math
  }

  unitDefinition =
  {
    1x0 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      name
      id
      unit
  }

  compartment =
  {
    typecode = SBML_COMPARTMENT
    metaid = 
    notes = 
    annotation = 
    name = 
    id = compartmentOne
    spatialDimensions = 3
    size =  1
    units = 
    outside = 
    constant = 1
    isSetSize = 1
    isSetVolume = 1
  }

  species =
  {
    1x4 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      name
      id
      compartment
      initialAmount
      initialConcentration
      substanceUnits
      spatialSizeUnits
      hasOnlySubstanceUnits
      boundaryCondition
      charge
      constant
      isSetInitialAmount
      isSetInitialConcentration
      isSetCharge
  }

  parameter =
  {
    1x0 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      name
      id
      value
      units
      constant
      isSetValue
  }

  rule =
  {
    1x0 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      formula
      variable
      species
      compartment
      name
      units
  }

  reaction =
  {
    1x3 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      name
      id
      reactant
      product
      modifier
      kineticLaw
      reversible
      fast
      isSetFast
  }

  event =
  {
    1x0 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      name
      id
      trigger
      delay
      timeUnits
      eventAssignment
  }

  time_symbol = 
  delay_symbol = 
  namespaces =
  {
    prefix = 
    uri = http://www.sbml.org/sbml/level2
  }

}

octave-3.2.4:22>
@endverbatim

The @c TranslateSBML function accepts some additional arguments too, and
can produce additional output values, as described below.


@section rf-reading TranslateSBML

Throughout this documentation, we use the term <em>the MATLAB_SBML
structure</em> to refer to the in-memory Octave data structure used by @c
TranslateSBML and @c OutputSBML.  As mentioned above, the job of @c
TranslateSBML is to create this in-memory structure from an SBML file.

@subsection rf-translate-input-args  Input arguments

@c TranslateSBML accepts up to three possible arguments.  They are, in
order, as follows:

@li @em filename:
This is the name of the file to be imported.  If the file is not in the
current directory, then the argument must be a full pathname (either
absolute or relative to the current working directory).  The @em filename is a
required argument.
@li @em validateFlag:
This flag tells libSBML whether to perform full validation of the SBML file
being read.  The default value is @c 0, which signifies not to perform
validation.  (Note libSBML will still check for and report basic XML parsing
errors regardless of the value of this flag.)
@li @em verboseFlag:
A value of @c 1 (the default) indicates that @c TranslateSBML should
perform the validation process interactively, displaying errors and
prompting the user for feedback if the model is invalid.  A value of @c 0
will suppress user interaction, and is useful when calling @c TranslateSBML
from within another Octave function/script.
The following example illustrates the behavior of @c TranslateSBML when it
is given the additional arguments for validation and verbosity:
@verbatim
octave-3.2.4:28> model = TranslateSBML('test.xml', 1, 1)
The model contains 0 errors and 6 warnings.

Do you want to exclude the warnings from the list? Enter y/n n

************************************
Line ErrorId Severity Message
34: (99505)  Warning  In situations when a mathematical expression contains 
literal numbers or parameters whose units have not been declared, it is not 
possible to verify accurately the consistency of the units in the expression.  
The units of the <kineticLaw> <math> expression 'k1 * X0' cannot be fully 
checked. Unit consistency reported as either no errors or further unit errors 
related to this object may not be accurate.

54: (99505)  Warning  In situations when a mathematical expression contains 
literal numbers or parameters whose units have not been declared, it is not 
possible to verify accurately the consistency of the units in the expression.  
The units of the <kineticLaw> <math> expression 'k2 * S1' cannot be fully 
checked. Unit consistency reported as either no errors or further unit errors 
related to this object may not be accurate.

74: (99505)  Warning  In situations when a mathematical expression contains 
literal numbers or parameters whose units have not been declared, it is not 
possible to verify accurately the consistency of the units in the expression.  
The units of the <kineticLaw> <math> expression 'k3 * S1' cannot be fully 
checked. Unit consistency reported as either no errors or further unit errors 
related to this object may not be accurate.

43: (80701)  Warning  As a principle of best modeling practice, the units of 
a <parameter> should be declared rather than be left undefined. Doing so 
improves the ability of software to check the consistency of units and helps 
make it easier to detect potential errors in models.

63: (80701)  Warning  As a principle of best modeling practice, the units of 
a <parameter> should be declared rather than be left undefined. Doing so 
improves the ability of software to check the consistency of units and helps 
make it easier to detect potential errors in models.

83: (80701)  Warning  As a principle of best modeling practice, the units of 
a <parameter> should be declared rather than be left undefined. Doing so 
improves the ability of software to check the consistency of units and helps 
make it easier to detect potential errors in models.


Do you want to load the model anyway? Enter y/n y
model =
{
  typecode = SBML_MODEL
  metaid = 
  notes = <notes>
  <body xmlns="http://www.w3.org/1999/xhtml">
    <p>Simple branch system.</p>
    <p>The reaction looks like this:</p>
    <p>reaction-1:   X0 -&gt; S1; k1*X0;</p>
    <p>reaction-2:   S1 -&gt; X1; k2*S1;</p>
    <p>reaction-3:   S1 -&gt; X2; k3*S1;</p>
  </body>
</notes>
  annotation = 
  SBML_level = 2
  SBML_version = 1
  name = 
  id = Branch
  functionDefinition =
  {
    1x0 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      name
      id
      math
  }

  unitDefinition =
  {
    1x0 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      name
      id
      unit
  }

  compartment =
  {
    typecode = SBML_COMPARTMENT
    metaid = 
    notes = 
    annotation = 
    name = 
    id = compartmentOne
    spatialDimensions = 3
    size =  1
    units = 
    outside = 
    constant = 1
    isSetSize = 1
    isSetVolume = 1
  }

  species =
  {
    1x4 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      name
      id
      compartment
      initialAmount
      initialConcentration
      substanceUnits
      spatialSizeUnits
      hasOnlySubstanceUnits
      boundaryCondition
      charge
      constant
      isSetInitialAmount
      isSetInitialConcentration
      isSetCharge
  }

  parameter =
  {
    1x0 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      name
      id
      value
      units
      constant
      isSetValue
  }

  rule =
  {
    1x0 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      formula
      variable
      species
      compartment
      name
      units
  }

  reaction =
  {
    1x3 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      name
      id
      reactant
      product
      modifier
      kineticLaw
      reversible
      fast
      isSetFast
  }

  event =
  {
    1x0 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      name
      id
      trigger
      delay
      timeUnits
      eventAssignment
  }

  time_symbol = 
  delay_symbol = 
  namespaces =
  {
    prefix = 
    uri = http://www.sbml.org/sbml/level2
  }

}

octave-3.2.4:29>
@endverbatim

@subsection rf-translate-output-args Output values

The main output value from @c TranslateSBML is a @em MATLAB_SBML structure
that captures the content of an SBML file in a form that can be manipulated
within Octave.  However, @c TranslateSBML can actually return multiple
values.  We describe them in the list below:

@li @em model:
This is the @em MATLAB_SBML structure corresponding to the content of an
SBML document.
@li @em errors:
The output of validation performed by libSBML can be captured into a second
value returned by @c TranslateSBML.  The value is an array of structures
detailing the warnings and errors encountered while reading and translating
the SBML file.  Capturing this output can be especially handy when
calling the function from other Octave code.

The following illustrates how the output of the errors reported for the
previous @c TranslateSBML example could be captured using the error output
variable:
@verbatim
octave-3.2.4:23> [model, errors] = TranslateSBML('test.xml', 1, 0)
model =
{
  typecode = SBML_MODEL
  metaid = 
  notes = <notes>
  <body xmlns="http://www.w3.org/1999/xhtml">
    <p>Simple branch system.</p>
    <p>The reaction looks like this:</p>
    <p>reaction-1:   X0 -&gt; S1; k1*X0;</p>
    <p>reaction-2:   S1 -&gt; X1; k2*S1;</p>
    <p>reaction-3:   S1 -&gt; X2; k3*S1;</p>
  </body>
</notes>
  annotation = 
  SBML_level = 2
  SBML_version = 1
  name = 
  id = Branch
  functionDefinition =
  {
    1x0 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      name
      id
      math
  }

  unitDefinition =
  {
    1x0 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      name
      id
      unit
  }

  compartment =
  {
    typecode = SBML_COMPARTMENT
    metaid = 
    notes = 
    annotation = 
    name = 
    id = compartmentOne
    spatialDimensions = 3
    size =  1
    units = 
    outside = 
    constant = 1
    isSetSize = 1
    isSetVolume = 1
  }

  species =
  {
    1x4 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      name
      id
      compartment
      initialAmount
      initialConcentration
      substanceUnits
      spatialSizeUnits
      hasOnlySubstanceUnits
      boundaryCondition
      charge
      constant
      isSetInitialAmount
      isSetInitialConcentration
      isSetCharge
  }

  parameter =
  {
    1x0 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      name
      id
      value
      units
      constant
      isSetValue
  }

  rule =
  {
    1x0 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      formula
      variable
      species
      compartment
      name
      units
  }

  reaction =
  {
    1x3 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      name
      id
      reactant
      product
      modifier
      kineticLaw
      reversible
      fast
      isSetFast
  }

  event =
  {
    1x0 struct array containing the fields:

      typecode
      metaid
      notes
      annotation
      name
      id
      trigger
      delay
      timeUnits
      eventAssignment
  }

  time_symbol = 
  delay_symbol = 
  namespaces =
  {
    prefix = 
    uri = http://www.sbml.org/sbml/level2
  }

}

errors =
{
  1x6 struct array containing the fields:

    line
    errorId
    severity
    message
}

octave-3.2.4:24> errors(1)
ans =
{
  line = 34
  errorId = 99505
  severity = Warning 
  message = In situations when a mathematical expression contains 
  literal numbers or parameters whose units have not been declared, 
  it is not possible to verify accurately the consistency of the 
  units in the expression.  The units of the <kineticLaw> <math> 
  expression 'k1 * X0' cannot be fully checked. Unit consistency 
  reported as either no errors or further unit errors related to 
  this object may not be accurate.

}

octave-3.2.4:25>
@endverbatim

Each error structure returned by @c TranslateSBML contains four fields: a
@em line number, indicating approximately where in the SBML file the error
occurred; @em errorId, the libSBML error/warning identification code; @em
severity, indicating how serious the issue is; and @em message, the text of
the error or warning for the issue reported by libSBML.  


@section rf-writing OutputSBML

The function @c OutputSBML is the converse of @c TranslateSBML: it writes
an @em MATLAB_SBML structure to an XML file.  It accepts three arguments:

@li @em model: This argument must be a @em MATLAB_SBML structure
representing the model to be written out to a file.  Note that the
structure will <em>not be validated</em> to check if it is fully correct
SBML; @c OutputSBML will only verify the basic integrity of the structure
(i.e., to make sure it has the form expected of a @em MATLAB_SBML
structure), but nothing more.
@li @em filename: The name of the file where the SBML content should 
be written.
@li @em extensions_allowed: An optional argument indicating that when 
determining whether the @em MATLAB_SBML structure represents a valid 
structure any additional fields are ignored. The default value is @c 1.
If this argument is set to @c 0, a structure will be considered 
valid if it contains only the expected fields and no additional fields.
 



@section rf-matlab-sbml The MATLAB_SBML structure

As mentioned above, The @em MATLAB_SBML structure used by libSBML's Octave
interface captures the content of an SBML file in a form that can be
manipulated within Octave.  The structure contains many fields, and many of
these fields are arrays of other structures that correspond to SBML
components.  Indexing into the array allows the user to access specific
model elements and attributes.

The following is an example of accessing the first species in a model:
@verbatim
octave-3.2.4:25> model.species(1)
ans =
{
  typecode = SBML_SPECIES
  metaid = 
  notes = 
  annotation = 
  name = 
  id = S1
  compartment = compartmentOne
  initialAmount = NaN
  initialConcentration = 0
  substanceUnits = 
  spatialSizeUnits = 
  hasOnlySubstanceUnits = 0
  boundaryCondition = 0
  charge = 0
  constant = 0
  isSetInitialAmount = 0
  isSetInitialConcentration = 1
  isSetCharge = 0
}

octave-3.2.4:26>
@endverbatim



@section rf-misc Other functions provided by the libSBML Octave interface

LibSBML's Octave interface comes with a few other scripts that are called
internally by @c TranslateSBML and @c OutputSBML, but may also be useful
independently:

@li <code>isSBML_Model(model, extensions_allowed)</code> returns true 
(@c 1) or false (@c 0), depending on whether the @em model supplied as 
argument matches the expected form of a @em MATLAB_SBML structure. The
optional argument @em extensions_allowed (default = @c 1) determines
whether additional fields are ignored. This argument is described in more
detail in teh text on OutputSBML above. 
(@c OutputSBML uses this function to determine whether it can proceed 
with writing out a given structure.)
@li <code>isoctave()</code> returns true (@c 1) or false (@c 0), depending
on whether the run-time environment is Octave or MATLAB.


*/
