# Value Types¶

Value is a generic term for the information contained in an attribute. A Value may be one of the following Value Types:

Value Type Variant Description
RealValue `NominalReal`
`NormalReal`
`UniformReal`
A double value and a unit (e.g., 32F, 45 meters, 14 kg).

Each variation provides a different mechanism for defining uncertainty.
IntegerValue `NominalInteger`
`UniformInteger`
A whole integer value.
Categorical `NominalCategorical`
`DiscreteCategorical`
Categorical values are distributions over the valid category names representing the probability of each category. For DiscreteCategorical, the values must sum to 1.0.
Composition `NominalComposition`
`EmpiricalFormula`
A value containing the composition of the material as a map from the names of the components to their numerical quantities. The quantities are not required to be expressed on a unit or fractional basis.
Molecular `Smiles`
`Inchi`
Molecular structure using popular encoding schemes.

Many of these values represent probability distributions, such as normal and uniform distributions over continuous bounds or discrete distributions over categorical ones.

Each of the Value Types is described below. Every field is required.

## Real Values¶

Two common distributions are supported: normal (i.e., Gaussian) and uniform. In cases when there is no distributional information, the "nominal" value type can be used to specify the expected value.

### Normal Real Value¶

Normally distributed value parameterized by a real-valued mean and standard deviation.

A normal distribution is considered valid with a set of Real Bounds if the mean lies between the upper and lower bound; the width of the distribution is not considered. From a computational perspective, this means Normal Real Values are actually truncated Gaussians, though this is only significant for a distribution near the boundary.

Field name Value type Description
`type` String "normal_real"
`mean` Number Mean of the distribution
`std` Number Standard deviation of the normal distribution
`units` String A String describing the units
##### Constraints¶
Field name Relationship Field Name
`std` >= 0
##### Example¶
``````{
"type" : "normal_real",
"units" : "kelvin",
"mean": 350,
"std": 1.03
}
``````

### Uniform Real Value¶

A Uniform continuous distribution value, with inclusive lower and upper bounds. These are especially useful for expressing uncertainty when the number of digits is truncated. In order to be valid, the entirety of the distribution must fall within the bounds.

Field name Value type Description
`type` String "uniform_real"
`lower_bound` Number Lower bound of the distribution
`upper_bound` Number Upper bound of the distribution
`units` String A String describing the units
##### Constraints
Field name Relationship Field Name
`lower_bound` <= `upper_bound`
##### Example¶

A value field read off a digital display with 3 decimal points.

``````{
"type" : "uniform_real",
"units" : "meter",
"lower_bound": 0.9995,
"upper_bound": 1.0005
}
``````

### Nominal Real Value¶

Nominal value, which does not specify an uncertainty but is not to be assumed to be exact.

Field name Value type Description
`type` String "nominal_real"
`nominal` Number A nominal value - not assumed to be exact
`units` String A String describing the units

None

##### Example¶
``````{
"type" : "nominal_real",
"units" : "meter",
"nominal": 1.0
}
``````

## Integer Values¶

Currently, there are two integer types: a uniform (i.e., range) distribution and a nominal (i.e., specified) value.

### Uniform Integer Value¶

A uniform integer distribution value, with inclusive lower and upper bounds. These are especially useful for expressing uncertainty when the number of digits is truncated. In order to be valid, the entirety of the distribution must fall within the bounds.

Field name Value type Description
`type` String "uniform_integer"
`lower_bound` Integer Lower bound of the distribution
`upper_bound` Integer Upper bound of the distribution
##### Constraints¶
Field name Relationship Field Name
`lower_bound` <= `upper_bound`
##### Example¶

A value field recorded from a digital display recording an approximate number of counts (e.g., Geiger counter reading "250").

``````{
"type" : "uniform_integer",
"lower_bound": 245,
"upper_bound": 254
}
``````

### Nominal Integer Value¶

Nominal value, which does not specify an uncertainty but is not to be assumed to be exact.

Field name Value type Description
`type` String "nominal_integer"
`nominal` Integer A nominal value - not assumed to be exact

None

##### Example¶
``````{
"type" : "nominal_integer",
"nominal": 42
}
``````

## Categorical¶

Categorical values are distributions over the valid category names representing the probability of each category. These are different than mixtures; 60% water and 40% ethanol is not a categorical distribution. For those, see `Composition`.

Currently, there are two categorical types: a discrete (i.e., enumerated) distribution and a nominal (i.e., specified) value.

### Discrete Categorical Value¶

Discrete categorical values represent a distribution of categories stored as a map from the string label to the probability.

Field name Value type Description
`type` String "discrete_categorical"
`probabilities` Map[String, Number] A map from string category names to their probability.
##### Constraints¶
Field name Relationship Field Name
abs(sum(probabilities.values()) - 1.0) < 1.0e-9
each probability value >= 0

In other words, a probability cannot be negative and the probabilities sum to one.

##### Example¶
``````{
"type":"discrete_categorical",
"probabilities" : {
"red" : 0.54,
"blue" : 0.46
}
}
``````

### Nominal Categorical Value¶

Nominal value, which does not specify an uncertainty but is not to be assumed to be exact.

Field name Value type Description
`type` String "nominal_categorical"
`category` String The category of the value

None

##### Example¶
``````{
"type" : "nominal_categorical",
"category" : "red"
}
``````

## Composition¶

A value representing the composition of the material as a set of component names and their respective quantities. The quantities are not required to be expressed on a unit or fractional basis. For example, "one part flour two parts sugar" is acceptable.

### Nominal Composition¶

A composition represented as a map from the component name to the quantity. The quantities do not express an uncertainty, but also do not imply that there is absolute certainty in their values.

Field name Value type Description
`type` String "nominal_composition"
`quantities` Map[String, Number] Map[String, Number]
##### Constraints¶
Field name Relationship Field Name
each quantity value >= 0
##### Example¶
``````{
"type" : "nominal_composition",
"quantities" : {
"water" : 120,
"ethanol" : 80
}
}
``````

### Empirical Formula¶

A composition represented as a chemical formula string. The order and grouping of the elements is ignored.

Field name Value type Description
`type` String "empirical_formula"
`formula` String Chemical formula to be parsed as an empirical formula
##### Example¶
``````{
"type" : "empirical_formula",
"formula" : "SiO2"
}
``````

## Molecular Structure¶

Molecular structure types are used to define attributes that contain information about the structure and composition of a molecule. Given a molecular structure, one can infer the chemical formula, existence of functional groups, and local chemical environment of each atom in the molecule. Most commonly a molecular structure will refer to the entire material, but multiple molecular structures can be used to define fragments of a material, e.g., monomers of a polymer.

There are two ways to represent a molecular structure:

• SMILES string
• InChI string

### SMILES Value¶

A value containing a SMILES string.

Field name Value type Description
`type` String "smiles"
`smiles` String A SMILES string
##### Example¶
``````{
"type" : "smiles",
"smiles" : "c1(C=O)cc(OC)c(O)cc1"
}
``````

### InChI Value¶

A value containing an InChI string. Note: this is not the same as the InChI key.

Field name Value type Description
`type` String "inchi"
`inchi` String An InChI string
##### Example¶
``````{
"type" : "inchi",
"inchi" : "InChI=1/C8H8O3/c1-11-8-4-6(5-9)2-3-7(8)10/h2-5,10H,1H3"
}
``````