public class Parameter extends SBase
A Parameter
is used in SBML to define a symbol associated with a value
this symbol can then be used in mathematical formulas in a model. By
default, parameters have constant value for the duration of a
simulation, and for this reason are called parameters instead of
variables in SBML, although it is crucial to understand that SBML
parameters represent both concepts. Whether a given SBML
parameter is intended to be constant or variable is indicated by the
value of its 'constant' attribute.
SBML's Parameter
has a required attribute, 'id', that gives the
parameter a unique identifier by which other parts of an SBML model
definition can refer to it. A parameter can also have an optional
'name' attribute of type string.
Identifiers and names must be used
according to the guidelines described in the SBML specifications.
The optional attribute 'value' determines the value (of type double
)
assigned to the parameter. A missing value for 'value' implies that
the value either is unknown, or to be obtained from an external source,
or determined by an initial assignment. The unit of measurement
associated with the value of the parameter can be specified using the
optional attribute 'units'. Here we only mention briefly some notable
points about the possible unit choices, but readers are urged to consult
the SBML specification documents for more information:
Model
object (unlike the case for, e.g.,
Species
and Compartment
).
'substance'
, 'time'
, 'volume'
, 'area'
or
'length'
or the identifier of a new unit defined in the list of unit
definitions in the enclosing Model
structure. There are no constraints
on the units that can be chosen from these sets. There are no default
units for parameters.
The Parameter
structure has another boolean attribute named 'constant'
that is used to indicate whether the parameter's value can vary during a
simulation. (In SBML Level 3, the attribute is mandatory and must
be given a value in SBML Levels below Level 3, the attribute is
optional.) A value of true
indicates the parameter's value cannot be
changed by any construct except InitialAssignment
. Conversely, if the
value of 'constant' is false
, other constructs in SBML, such as rules
and events, can change the value of the parameter.
SBML Level 3 uses a separate object class, LocalParameter
, for
parameters that are local to a Reaction
's KineticLaw
. In Levels prior
to SBML Level 3, the Parameter
class is used both for definitions
of global parameters, as well as reaction-local parameters stored in a
list within KineticLaw
objects. Parameter
objects that are local to a
reaction (that is, those defined within the KineticLaw
structure of a
Reaction
) cannot be changed by rules and therefore are implicitly
always constant consequently, in SBML Level 2, parameter
definitions within Reaction
structures should not have their
'constant' attribute set to false.
What if a global parameter has its 'constant' attribute set to false
,
but the model does not contain any rules, events or other constructs
that ever change its value over time? Although the model may be
suspect, this situation is not strictly an error. A value of false
for 'constant' only indicates that a parameter can change value, not
that it must.
As with all other major SBML components, Parameter
is derived from
SBase
, and the methods defined on SBase
are available on Parameter
.
ListOfParameters
Parameter
construct with the boolean flag
'constant' indicating which flavor it is. In any case, readers are
implored to look past their particular definition of a parameter and
simply view SBML's Parameter
as a single mechanism for defining both
constants and (additional) variables in a model. (We write
additional because the species in a model are usually considered to be
the central variables.) After all, software tools are not required to
expose to users the actual names of particular SBML constructs, and
thus tools can present to their users whatever terms their designers
feel best matches their target audience.
In SBML Level 3 Version 2, many restrictions were lifted
requiring only Boolean values in Boolean contexts, and numeric
values in numeric contexts. This means that a Parameter
may now
be used as a Boolean, despite canonically having a numeric value.
To be consistent, one should always assign it a value of true
or false
, and use it in Boolean contexts exclusively. It would
be appropriate to give it an SBO
value of 602 ('Logical parameter')
if one chooses to do this.
Constructor and Description |
---|
Parameter(long level,
long version)
|
Parameter(Parameter orig)
Copy constructor creates a copy of a
Parameter . |
Parameter(SBMLNamespaces sbmlns)
|
Modifier and Type | Method and Description |
---|---|
Parameter |
cloneObject()
Creates and returns a deep copy of this
Parameter object. |
void |
delete()
Explicitly deletes the underlying native object.
|
boolean |
getConstant()
Gets the value of the 'constant' attribute of this
Parameter instance. |
UnitDefinition |
getDerivedUnitDefinition()
Constructs and returns a
UnitDefinition that corresponds to the units
of this Parameter 's value. |
java.lang.String |
getElementName()
Returns the XML element name of this object, which for
Parameter , is
always 'parameter'. |
java.lang.String |
getId()
Returns the value of the 'id' attribute of this
Parameter . |
java.lang.String |
getName()
Returns the value of the 'name' attribute of this
Parameter object. |
int |
getTypeCode()
Returns the libSBML type code for this SBML object.
|
java.lang.String |
getUnits()
Gets the units defined for this
Parameter . |
double |
getValue()
Gets the numerical value of this
Parameter . |
boolean |
hasRequiredAttributes()
Predicate returning
true if
all the required attributes for this Parameter object
have been set. |
void |
initDefaults()
Initializes the fields of this
Parameter object to 'typical' defaults
values. |
boolean |
isSetConstant()
Predicate returning
true if the
'constant' attribute of this Parameter is set. |
boolean |
isSetId()
Predicate returning
true if this
Parameter 's 'id' attribute is set. |
boolean |
isSetName()
Predicate returning
true if this
Parameter 's 'name' attribute is set. |
boolean |
isSetUnits()
Predicate returning
true if the
'units' attribute of this Parameter is set. |
boolean |
isSetValue()
Predicate returning
true if the
'value' attribute of this Parameter is set. |
void |
renameUnitSIdRefs(java.lang.String oldid,
java.lang.String newid)
Renames all the
UnitSIdRef attributes on this element. |
int |
setConstant(boolean flag)
Sets the 'constant' attribute of this
Parameter to the given boolean
flag . |
int |
setId(java.lang.String sid)
Sets the value of the 'id' attribute of this
Parameter . |
int |
setName(java.lang.String name)
Sets the value of the 'name' attribute of this
Parameter . |
int |
setUnits(java.lang.String units)
Sets the 'units' attribute of this
Parameter to a copy of the given
units identifier units . |
int |
setValue(double value)
Sets the 'value' attribute of this
Parameter to the given double
value and marks the attribute as set. |
int |
unsetConstant()
Unsets the value of the 'constant' attribute of this
Parameter object. |
int |
unsetName()
Unsets the value of the 'name' attribute of this
Parameter . |
int |
unsetUnits()
Unsets the 'units' attribute of this
Parameter instance. |
int |
unsetValue()
Unsets the 'value' attribute of this
Parameter instance. |
addCVTerm, addCVTerm, appendAnnotation, appendAnnotation, appendNotes, appendNotes, connectToChild, deleteDisabledPlugins, deleteDisabledPlugins, disablePackage, enablePackage, equals, getAncestorOfType, getAncestorOfType, getAnnotation, getAnnotationString, getColumn, getCVTerm, getCVTerms, getDisabledPlugin, getElementByMetaId, getElementBySId, getIdAttribute, getLevel, getLine, getListOfAllElements, getListOfAllElements, getListOfAllElementsFromPlugins, getListOfAllElementsFromPlugins, getMetaId, getModel, getModelHistory, getNamespaces, getNotes, getNotesString, getNumCVTerms, getNumDisabledPlugins, getNumPlugins, getPackageCoreVersion, getPackageName, getPackageVersion, getParentSBMLObject, getPlugin, getPlugin, getPrefix, getResourceBiologicalQualifier, getResourceModelQualifier, getSBMLDocument, getSBOTerm, getSBOTermAsURL, getSBOTermID, getURI, getVersion, hashCode, hasValidLevelVersionNamespaceCombination, isPackageEnabled, isPackageURIEnabled, isPkgEnabled, isPkgURIEnabled, isSetAnnotation, isSetIdAttribute, isSetMetaId, isSetModelHistory, isSetNotes, isSetSBOTerm, isSetUserData, matchesRequiredSBMLNamespacesForAddition, matchesSBMLNamespaces, removeFromParentAndDelete, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, removeTopLevelAnnotationElement, renameMetaIdRefs, renameSIdRefs, replaceTopLevelAnnotationElement, replaceTopLevelAnnotationElement, setAnnotation, setAnnotation, setIdAttribute, setMetaId, setModelHistory, setNamespaces, setNotes, setNotes, setNotes, setSBOTerm, setSBOTerm, toSBML, toXMLNode, unsetAnnotation, unsetCVTerms, unsetId, unsetIdAttribute, unsetMetaId, unsetModelHistory, unsetNotes, unsetSBOTerm, unsetUserData
public Parameter(long level, long version) throws SBMLConstructorException
level
- a long integer, the SBML Level to assign to this Parameter
.
version
- a long integer, the SBML Version to assign to this
Parameter
.
SBMLConstructorException
- Thrown if the given level
and version
combination are invalid
or if this object is incompatible with the given level and version.
SBMLDocument
having a different
combination of SBML Level, Version and XML namespaces than the object
itself will result in an error at the time a caller attempts to make the
addition. A parent object must have compatible Level, Version and XML
namespaces. (Strictly speaking, a parent may also have more XML
namespaces than a child, but the reverse is not permitted.) The
restriction is necessary to ensure that an SBML model has a consistent
overall structure. This requires callers to manage their objects
carefully, but the benefit is increased flexibility in how models can be
created by permitting callers to create objects bottom-up if desired. In
situations where objects are not yet attached to parents (e.g.,
SBMLDocument
), knowledge of the intented SBML Level and Version help
libSBML determine such things as whether it is valid to assign a
particular value to an attribute.public Parameter(SBMLNamespaces sbmlns) throws SBMLConstructorException
Parameter
using the given SBMLNamespaces
object
sbmlns
.
The SBMLNamespaces
object encapsulates SBML Level/Version/namespaces
information. It is used to communicate the SBML Level, Version, and (in
Level 3) packages used in addition to SBML Level 3 Core. A
common approach to using libSBML's SBMLNamespaces
facilities is to create an
SBMLNamespaces
object somewhere in a program once, then hand that object
as needed to object constructors that accept SBMLNamespaces
as arguments.
It is worth emphasizing that although this constructor does not take
an identifier argument, in SBML Level 2 and beyond, the 'id'
(identifier) attribute of a Parameter
is required to have a value.
Thus, callers are cautioned to assign a value after calling this
constructor if no identifier is provided as an argument. Setting the
identifier can be accomplished using the method
setId(String id).
sbmlns
- an SBMLNamespaces
object.
SBMLConstructorException
- Thrown if the given sbmlns
is inconsistent or incompatible
with this object.
SBMLDocument
having a different
combination of SBML Level, Version and XML namespaces than the object
itself will result in an error at the time a caller attempts to make the
addition. A parent object must have compatible Level, Version and XML
namespaces. (Strictly speaking, a parent may also have more XML
namespaces than a child, but the reverse is not permitted.) The
restriction is necessary to ensure that an SBML model has a consistent
overall structure. This requires callers to manage their objects
carefully, but the benefit is increased flexibility in how models can be
created by permitting callers to create objects bottom-up if desired. In
situations where objects are not yet attached to parents (e.g.,
SBMLDocument
), knowledge of the intented SBML Level and Version help
libSBML determine such things as whether it is valid to assign a
particular value to an attribute.public Parameter(Parameter orig) throws SBMLConstructorException
Parameter
.
orig
- the Parameter
instance to copy.SBMLConstructorException
public void delete()
In general, application software will not need to call this method directly. The Java language binding for libSBML is implemented as a language wrapper that provides a Java interface to libSBML's underlying C++/C code. Some of the Java methods return objects that are linked to objects created not by Java code, but by C++ code. The Java objects wrapped around them will be deleted when the garbage collector invokes the corresponding C++ finalize()
methods for the objects. The finalize()
methods in turn call the Parameter.delete()
method on the libSBML object.
This method is exposed in case calling programs want to ensure that the underlying object is freed immediately, and not at some arbitrary time determined by the Java garbage collector. In normal usage, callers do not need to invoke Parameter.delete()
themselves.
public Parameter cloneObject()
Parameter
object.
cloneObject
 in class SBase
Parameter
object.public void initDefaults()
Parameter
object to 'typical' defaults
values.
The SBML Parameter
component has slightly different aspects and
default attribute values in different SBML Levels and Versions. Many
SBML object classes defined by libSBML have an initDefaults() method
to set the values to certain common defaults, based mostly on what
they are in SBML Level 2. In the case of Parameter
, this method
only sets the value of the 'constant' attribute to true.
public java.lang.String getId()
Parameter
.
getId
 in class SBase
Parameter
.
SBase.getIdAttribute()
,
SBase.setIdAttribute(String sid)
,
SBase.isSetIdAttribute()
,
SBase.unsetIdAttribute()
The identifier given by an object's 'id' attribute value
is used to identify the object within the SBML model definition.
Other objects can refer to the component using this identifier. The
data type of 'id' is always SId
or a type derived
from that, such as UnitSId
, depending on the object in
question. All data types are defined as follows:
letter .= 'a'..'z','A'..'Z' digit .= '0'..'9' idChar .= letter | digit | '_' SId .= ( letter | '_' ) idChar*
The characters (
and )
are used for grouping, the
character *
'zero or more times', and the character
|
indicates logical 'or'. The equality of SBML identifiers is
determined by an exact character sequence match i.e., comparisons must be
performed in a case-sensitive manner. This applies to all uses of SId
,
SIdRef
, and derived types.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, check, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The exception to this rule is that for InitialAssignment
, EventAssignment
,
AssignmentRule
, and RateRule
objects, the getId() function and the isSetId()
functions (though not the setId() or unsetId() functions) would instead
reference the value of the 'variable' attribute (for the rules and event
assignments) or the 'symbol' attribute (for initial assignments).
The AlgebraicRule
fell into this category as well, though because it
contained neither a 'variable' nor a 'symbol' attribute, getId() would
always return an empty string, and isSetId() would always return false.
For this reason, four new functions are now provided
(getIdAttribute(), setIdAttribute(String),
isSetIdAttribute(), and unsetIdAttribute()) that will always
act on the actual 'id' attribute, regardless of the object's type. The
new functions should be used instead of the old ones unless the old behavior
is somehow necessary.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have identifiers). If the object in question does not posess an 'id' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the identifier to be set, nor will it read or write 'id' attributes for those objects.
public java.lang.String getName()
Parameter
object.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The 'name' attribute is
optional and is not intended to be used for cross-referencing purposes
within a model. Its purpose instead is to provide a human-readable
label for the component. The data type of 'name' is the type
string
defined in XML Schema. SBML imposes no
restrictions as to the content of 'name' attributes beyond those
restrictions defined by the string
type in XML Schema.
The recommended practice for handling 'name' is as follows. If a software tool has the capability for displaying the content of 'name' attributes, it should display this content to the user as a component's label instead of the component's 'id'. If the user interface does not have this capability (e.g., because it cannot display or use special characters in symbol names), or if the 'name' attribute is missing on a given component, then the user interface should display the value of the 'id' attribute instead. (Script language interpreters are especially likely to display 'id' instead of 'name'.)
As a consequence of the above, authors of systems that automatically generate the values of 'id' attributes should be aware some systems may display the 'id''s to the user. Authors therefore may wish to take some care to have their software create 'id' values that are: (a) reasonably easy for humans to type and read and (b) likely to be meaningful, for example by making the 'id' attribute be an abbreviated form of the name attribute value.
An additional point worth mentioning is although there are restrictions on the uniqueness of 'id' values, there are no restrictions on the uniqueness of 'name' values in a model. This allows software applications leeway in assigning component identifiers.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have names). If the object in question does not posess a 'name' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the name to be set, nor will it read or write 'name' attributes for those objects.
getName
 in class SBase
SBase.getIdAttribute()
,
Parameter.isSetName()
,
Parameter.setName(String sid)
,
Parameter.unsetName()
public double getValue()
Parameter
.
Parameter
, as a
number of type double.
Parameter.isSetValue()
,
Parameter.setValue(double value)
,
Parameter.getUnits()
Parameter.getValue()
without first using Parameter.isSetValue()
to
determine whether a value has ever been set. Otherwise, the value
return by Parameter.getValue()
may not actually represent a value
assigned to the parameter. The reason is simply that the data type
double
in a program always has some value. A separate test is
needed to determine whether the value is a true model value, or
uninitialized data in a computer's memory location.
public java.lang.String getUnits()
Parameter
.
The value of an SBML parameter's 'units' attribute establishes the unit of measurement associated with the parameter's value.
Parameter
, as a
string. An empty string indicates that no units have been assigned.
Parameter.isSetUnits()
,
Parameter.setUnits(String)
,
Parameter.getValue()
dimensionless
. In SBML, default units are never
attributed to numbers, and numbers without units are not automatically
assumed to have the unit dimensionless
. Please consult the
relevant SBML specification document for a more in-depth explanation of
this topic and the SBML unit system.
public boolean getConstant()
Parameter
instance.
true
if this Parameter
is declared as being constant,
false
otherwise.
Parameter.isSetConstant()
,
Parameter.setConstant(boolean)
LocalParameter
may be
confused about the presence of this method. LibSBML derives
LocalParameter
from Parameter
however, this does not precisely match
the object hierarchy defined by SBML Level 3, where
LocalParameter
is derived directly from SBase
and not Parameter
. We
believe this arrangement makes it easier for libSBML users to program
applications that work with both SBML Level 2 and SBML
Level 3, but programmers should also keep in mind this difference
exists. A side-effect of libSBML's scheme is that certain methods on
LocalParameter
that are inherited from Parameter
do not actually have
relevance to LocalParameter
objects. An example of this is the
methods pertaining to Parameter
's attribute 'constant' (i.e.,
isSetConstant(), setConstant(), and getConstant()).
public boolean isSetId()
isSetId
 in class SBase
true
if the 'id' attribute of this SBML object is
set, false
otherwise.
SBase.getIdAttribute()
,
SBase.setIdAttribute(String sid)
,
SBase.unsetIdAttribute()
,
SBase.isSetIdAttribute()
The identifier given by an object's 'id' attribute value
is used to identify the object within the SBML model definition.
Other objects can refer to the component using this identifier. The
data type of 'id' is always SId
or a type derived
from that, such as UnitSId
, depending on the object in
question. All data types are defined as follows:
letter .= 'a'..'z','A'..'Z' digit .= '0'..'9' idChar .= letter | digit | '_' SId .= ( letter | '_' ) idChar*
The characters (
and )
are used for grouping, the
character *
'zero or more times', and the character
|
indicates logical 'or'. The equality of SBML identifiers is
determined by an exact character sequence match i.e., comparisons must be
performed in a case-sensitive manner. This applies to all uses of SId
,
SIdRef
, and derived types.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, check, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The exception to this rule is that for InitialAssignment
, EventAssignment
,
AssignmentRule
, and RateRule
objects, the getId() function and the isSetId()
functions (though not the setId() or unsetId() functions) would instead
reference the value of the 'variable' attribute (for the rules and event
assignments) or the 'symbol' attribute (for initial assignments).
The AlgebraicRule
fell into this category as well, though because it
contained neither a 'variable' nor a 'symbol' attribute, getId() would
always return an empty string, and isSetId() would always return false.
For this reason, four new functions are now provided
(getIdAttribute(), setIdAttribute(String),
isSetIdAttribute(), and unsetIdAttribute()) that will always
act on the actual 'id' attribute, regardless of the object's type. The
new functions should be used instead of the old ones unless the old behavior
is somehow necessary.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have identifiers). If the object in question does not posess an 'id' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the identifier to be set, nor will it read or write 'id' attributes for those objects.
public boolean isSetName()
true
if this
Parameter
's 'name' attribute is set.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The 'name' attribute is
optional and is not intended to be used for cross-referencing purposes
within a model. Its purpose instead is to provide a human-readable
label for the component. The data type of 'name' is the type
string
defined in XML Schema. SBML imposes no
restrictions as to the content of 'name' attributes beyond those
restrictions defined by the string
type in XML Schema.
The recommended practice for handling 'name' is as follows. If a software tool has the capability for displaying the content of 'name' attributes, it should display this content to the user as a component's label instead of the component's 'id'. If the user interface does not have this capability (e.g., because it cannot display or use special characters in symbol names), or if the 'name' attribute is missing on a given component, then the user interface should display the value of the 'id' attribute instead. (Script language interpreters are especially likely to display 'id' instead of 'name'.)
As a consequence of the above, authors of systems that automatically generate the values of 'id' attributes should be aware some systems may display the 'id''s to the user. Authors therefore may wish to take some care to have their software create 'id' values that are: (a) reasonably easy for humans to type and read and (b) likely to be meaningful, for example by making the 'id' attribute be an abbreviated form of the name attribute value.
An additional point worth mentioning is although there are restrictions on the uniqueness of 'id' values, there are no restrictions on the uniqueness of 'name' values in a model. This allows software applications leeway in assigning component identifiers.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have names). If the object in question does not posess a 'name' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the name to be set, nor will it read or write 'name' attributes for those objects.
isSetName
 in class SBase
true
if the 'name' attribute of this SBML object is
set, false
otherwise.
Parameter.getName()
,
Parameter.setName(String sid)
,
Parameter.unsetName()
public boolean isSetValue()
true
if the
'value' attribute of this Parameter
is set.
In SBML definitions after SBML Level 1 Version 1,
parameter values are optional and have no defaults. If a model read
from a file does not contain a setting for the 'value' attribute of a
parameter, its value is considered unset it does not default to any
particular value. Similarly, when a Parameter
object is created in
libSBML, it has no value until given a value. The
Parameter.isSetValue()
method allows calling applications to
determine whether a given parameter's value has ever been set.
In SBML Level 1 Version 1, parameters are required to have
values and therefore, the value of a Parameter
should always be
set. In Level 1 Version 2 and beyond, the value is
optional and as such, the 'value' attribute may or may not be set.
true
if the value of this Parameter
is set,
false
otherwise.
Parameter.getValue()
,
Parameter.setValue(double value)
public boolean isSetUnits()
true
if the
'units' attribute of this Parameter
is set.
true
if the 'units' attribute of this Parameter
is
set, false
otherwise.
dimensionless
. In SBML, default units are never
attributed to numbers, and numbers without units are not automatically
assumed to have the unit dimensionless
. Please consult the
relevant SBML specification document for a more in-depth explanation of
this topic and the SBML unit system.public boolean isSetConstant()
true
if the
'constant' attribute of this Parameter
is set.
true
if the 'constant' attribute of this Parameter
is
set, false
otherwise.
Parameter.getConstant()
,
Parameter.setConstant(boolean)
LocalParameter
may be
confused about the presence of this method. LibSBML derives
LocalParameter
from Parameter
however, this does not precisely match
the object hierarchy defined by SBML Level 3, where
LocalParameter
is derived directly from SBase
and not Parameter
. We
believe this arrangement makes it easier for libSBML users to program
applications that work with both SBML Level 2 and SBML
Level 3, but programmers should also keep in mind this difference
exists. A side-effect of libSBML's scheme is that certain methods on
LocalParameter
that are inherited from Parameter
do not actually have
relevance to LocalParameter
objects. An example of this is the
methods pertaining to Parameter
's attribute 'constant' (i.e.,
isSetConstant(), setConstant(), and getConstant()).
public int setId(java.lang.String sid)
Parameter
.
The string sid
is copied.
The identifier given by an object's 'id' attribute value
is used to identify the object within the SBML model definition.
Other objects can refer to the component using this identifier. The
data type of 'id' is always SId
or a type derived
from that, such as UnitSId
, depending on the object in
question. All data types are defined as follows:
letter .= 'a'..'z','A'..'Z' digit .= '0'..'9' idChar .= letter | digit | '_' SId .= ( letter | '_' ) idChar*
The characters (
and )
are used for grouping, the
character *
'zero or more times', and the character
|
indicates logical 'or'. The equality of SBML identifiers is
determined by an exact character sequence match i.e., comparisons must be
performed in a case-sensitive manner. This applies to all uses of SId
,
SIdRef
, and derived types.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, check, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The exception to this rule is that for InitialAssignment
, EventAssignment
,
AssignmentRule
, and RateRule
objects, the getId() function and the isSetId()
functions (though not the setId() or unsetId() functions) would instead
reference the value of the 'variable' attribute (for the rules and event
assignments) or the 'symbol' attribute (for initial assignments).
The AlgebraicRule
fell into this category as well, though because it
contained neither a 'variable' nor a 'symbol' attribute, getId() would
always return an empty string, and isSetId() would always return false.
For this reason, four new functions are now provided
(getIdAttribute(), setIdAttribute(String),
isSetIdAttribute(), and unsetIdAttribute()) that will always
act on the actual 'id' attribute, regardless of the object's type. The
new functions should be used instead of the old ones unless the old behavior
is somehow necessary.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have identifiers). If the object in question does not posess an 'id' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the identifier to be set, nor will it read or write 'id' attributes for those objects.
setId
 in class SBase
sid
- the string to use as the identifier of this object.
SBase.getIdAttribute()
,
SBase.setIdAttribute(String sid)
,
SBase.isSetIdAttribute()
,
SBase.unsetIdAttribute()
public int setName(java.lang.String name)
Parameter
.
The string in name
is copied.
public int setValue(double value)
Parameter
to the given double
value and marks the attribute as set.
value
- a double
, the value to assign.
public int setUnits(java.lang.String units)
Parameter
to a copy of the given
units identifier units
.
units
- a string, the identifier of the units to assign to this
Parameter
instance.
public int setConstant(boolean flag)
Parameter
to the given boolean
flag
.
flag
- a boolean, the value for the 'constant' attribute of this
Parameter
instance.
Parameter.getConstant()
,
Parameter.isSetConstant()
LocalParameter
may be
confused about the presence of this method. LibSBML derives
LocalParameter
from Parameter
however, this does not precisely match
the object hierarchy defined by SBML Level 3, where
LocalParameter
is derived directly from SBase
and not Parameter
. We
believe this arrangement makes it easier for libSBML users to program
applications that work with both SBML Level 2 and SBML
Level 3, but programmers should also keep in mind this difference
exists. A side-effect of libSBML's scheme is that certain methods on
LocalParameter
that are inherited from Parameter
do not actually have
relevance to LocalParameter
objects. An example of this is the
methods pertaining to Parameter
's attribute 'constant' (i.e.,
isSetConstant(), setConstant(), and getConstant()).
public int unsetName()
Parameter
.
In SBML Level 3 Version 2, the 'id' and 'name' attributes were
moved to SBase
directly, instead of being defined individually for many
(but not all) objects. Libsbml has for a long time provided functions
defined on SBase
itself to get, set, and unset those attributes, which
would fail or otherwise return empty strings if executed on any object
for which those attributes were not defined. Now that all SBase
objects
define those attributes, those functions now succeed for any object with
the appropriate level and version.
The 'name' attribute is
optional and is not intended to be used for cross-referencing purposes
within a model. Its purpose instead is to provide a human-readable
label for the component. The data type of 'name' is the type
string
defined in XML Schema. SBML imposes no
restrictions as to the content of 'name' attributes beyond those
restrictions defined by the string
type in XML Schema.
The recommended practice for handling 'name' is as follows. If a software tool has the capability for displaying the content of 'name' attributes, it should display this content to the user as a component's label instead of the component's 'id'. If the user interface does not have this capability (e.g., because it cannot display or use special characters in symbol names), or if the 'name' attribute is missing on a given component, then the user interface should display the value of the 'id' attribute instead. (Script language interpreters are especially likely to display 'id' instead of 'name'.)
As a consequence of the above, authors of systems that automatically generate the values of 'id' attributes should be aware some systems may display the 'id''s to the user. Authors therefore may wish to take some care to have their software create 'id' values that are: (a) reasonably easy for humans to type and read and (b) likely to be meaningful, for example by making the 'id' attribute be an abbreviated form of the name attribute value.
An additional point worth mentioning is although there are restrictions on the uniqueness of 'id' values, there are no restrictions on the uniqueness of 'name' values in a model. This allows software applications leeway in assigning component identifiers.
Regardless of the level and version of the SBML, these functions allow client applications to use more generalized code in some situations (for instance, when manipulating objects that are all known to have names). If the object in question does not posess a 'name' attribute according to the SBML specification for the Level and Version in use, libSBML will not allow the name to be set, nor will it read or write 'name' attributes for those objects.
unsetName
 in class SBase
Parameter.getName()
,
Parameter.setName(String sid)
,
Parameter.isSetName()
public int unsetConstant()
Parameter
object.
Parameter.isSetConstant()
,
Parameter.setConstant(boolean)
,
Parameter.getConstant()
public int unsetValue()
Parameter
instance.
In SBML Level 1 Version 1, parameters are required to have
values and therefore, the value of a Parameter
should always be
set. In SBML Level 1 Version 2 and beyond, the value
is optional and as such, the 'value' attribute may or may not be set.
public int unsetUnits()
Parameter
instance.
public UnitDefinition getDerivedUnitDefinition()
UnitDefinition
that corresponds to the units
of this Parameter
's value.
Parameters in SBML have an attribute ('units') for declaring the units
of measurement intended for the parameter's value. No defaults are
defined by SBML in the absence of a definition for 'units'. This
method returns a UnitDefinition
object based on the units declared for
this Parameter
using its 'units' attribute, or it returns null
if
no units have been declared.
Note that unit declarations for Parameter
objects are specified in
terms of the identifier of a unit (e.g., using setUnits()), but
this method returns a UnitDefinition
object, not a unit
identifier. It does this by constructing an appropriate
UnitDefinition
.For SBML Level 2 models, it will do this even when
the value of the 'units' attribute is one of the special SBML
Level 2 unit identifiers 'substance'
, 'volume'
, 'area'
,
'length'
or 'time'.
Callers may find this useful in conjunction
with the helper methods provided by the UnitDefinition
class for
comparing different UnitDefinition
objects.
getDerivedUnitDefinition
 in class SBase
UnitDefinition
that expresses the units of this
Parameter
, or null
if one cannot be constructed.
Parameter.isSetUnits()
Parameter
object has not yet been added to
a model, or the model itself is incomplete, unit analysis is not
possible, and consequently this method will return null.
public int getTypeCode()
LibSBML attaches an identifying code to every kind of SBML object. These
are integer constants known as SBML type codes. The names of all
the codes begin with the characters SBML_
.
In the Java language interface for libSBML, the
type codes are defined as static integer constants in the interface class
libsbmlConstants
. Note that different Level 3
package plug-ins may use overlapping type codes to identify the package
to which a given object belongs, call the
method on the object.
SBase.getPackageName()
getTypeCode
 in class SBase
SBML_PARAMETER
(default).
Parameter.getElementName()
,
SBase.getPackageName()
public java.lang.String getElementName()
Parameter
, is
always 'parameter'.
getElementName
 in class SBase
'parameter'.
public boolean hasRequiredAttributes()
true
if
all the required attributes for this Parameter
object
have been set.
The required attributes for a Parameter
object are:
hasRequiredAttributes
 in class SBase
true
if the required attributes have been set, false
otherwise.public void renameUnitSIdRefs(java.lang.String oldid, java.lang.String newid)
UnitSIdRef
attributes on this element.
In SBML, unit definitions have identifiers of type UnitSId
. In
SBML Level 3, an explicit data type called UnitSIdRef
was
introduced for attribute values that refer to UnitSId
values in
previous Levels of SBML, this data type did not exist and attributes were
simply described to as 'referring to a unit identifier', but the effective
data type was the same as UnitSIdRef
in Level 3. These and
other methods of libSBML refer to the type UnitSIdRef
for all
Levels of SBML, even if the corresponding SBML specification did not
explicitly name the data type.
This method works by looking at all unit identifier attribute values
(including, if appropriate, inside mathematical formulas), comparing the
unit identifiers to the value of oldid
. If any matches are found,
the matching identifiers are replaced with newid
. The method does
not descend into child elements.
renameUnitSIdRefs
 in class SBase
oldid
- the old identifier.newid
- the new identifier.