Schema annotations¶

Definitions in a schema can have annotations. These annotations provide additional information that NOMAD can use to alter its behavior around these definitions. Annotations are named blocks of key-value pairs:

definitions:
  sections:
    MyAnnotatedSection:
      m_annotations:
        annotation_name:
          key1: value
          key2: value

Many annotations control the representation of data in the GUI. This can be for plots or data entry/editing capabilities.

eln¶

These annotations control how data can be entered and edited. Use the key eln to add this annotations. For example:

class Sample(EntryData):
    sample_id = Quantity(type=str, a_eln=dict(component='StringEditQuantity'))`)

or in YAML schemas:

Sample:
  quantities:
    sample_id:
      type: str
      m_annotations:
        eln:
          component: StringEditQuantity

An eln annotation can be added to section and quantity definitions to different effects. In both cases, it controls how sections and quantities are represented in the GUI with different parameters; see below.

The UI gives an overview about all ELN edit annotations and components here.

name	type
component	`str`	The form field component that is used to make the annotated quantity editable. If no component is given, the quantity won't be editable. This can be used on quantities only. The supported values are: `StringEditQuantity`: For editing simple short string values. `URLEditQuantity`: For editing strings that are validated to be URLs. `EnumEditQuantity`: For Editing enum values. Uses a dropdown list with enum values. This component may be used for short enumerates. `RadioEnumEditQuantity`: For Editing enum values. Uses radio buttons. `AutocompleteEditQuantity`: For editing enum values. Uses an autocomplete form with dropdown list. This component may be used for longer enumerates. `FileEditQuantity`: For editing a reference to a file. Will allow to choose a file or upload a file. `BoolEditQuantity`: For editing boolean choices. `NumberEditQuantity`: For editing numbers with our without unit. `SliderEditQuantity`: For editing numbers with a horizontal slider widget. `DateTimeEditQuantity`: For editing datetimes. `RichTextEditQuantity`: For editing long styled text with a rich text editor. `ReferenceEditQuantity`: For editing references to other sections. `UserEditQuantity`: For entering user information. Lets you choose a nomad user or enter information manually. `AuthorEditQuantity`: For entering author information manually. options: - `StringEditQuantity` - `URLEditQuantity` - `EnumEditQuantity` - `RadioEnumEditQuantity` - `AutocompleteEditQuantity` - `FileEditQuantity` - `BoolEditQuantity` - `NumberEditQuantity` - `SliderEditQuantity` - `DateTimeEditQuantity` - `RichTextEditQuantity` - `ReferenceEditQuantity` - `UserEditQuantity` - `AuthorEditQuantity`
label	`str`	Custom label for the quantity shown on the form field.
props	`Dict[str, typing.Any]`	A dictionary with additional props that are passed to the editcomponent.
default	`typing.Any`	Prefills any set form field component with the given value. This is different from the quantities `default` property. The quantities default is not stored in the data; the default value is assumed if no other value is given. The ELN form field default value will be stored, even if not changed.
defaultDisplayUnit	`str`	Allows to define a default unit to initialize a `NumberEditQuantity` with. The unit has to be compatible with the unit of the annotation quantity and the annotated quantity must have a unit. Only applies to quantities and with `component=NumberEditQuantity`.
minValue	`Union[int, float]`	Allows to specify a minimum value for quantity annotations with number type. Will show an error, if outside numbers are entered. Only works on quantities and in conjunction with `component=NumberEditQuantity`.
maxValue	`Union[int, float]`	Allows to specify a maximum value for quantity annotations with number type. Will show an error, if outside numbers are entered. Only works on quantities and in conjunction with `component=NumberEditQuantity`.
showSectionLabel	`int`	To customize the ReferenceEditQuantity behaviour. If true the section label will be shown instead of referenced file name and the path to the section.
hide	`List[str]`	The annotation "hide" is deprecated. Use "visible" key of "properties" annotation instead. Allows you to hide certain quantities from a section editor. Give a list of quantity names. Quantities must exist in the section that this annotation is added to. Can only be used in section annotations. deprecated
overview	`int`	Shows the annotation section on the entry's overview page. Can only be used on section annotations.
lane_width	`Union[str, int]`	Value to overwrite the css width of the lane used to render the annotation section and its editor.
properties	`SectionProperties`	The value to customize the quantities and sub sections of the annotation section. The supported keys: `visible`: To determine the visible quantities and sub sections by their names `editable`: To render things visible but not editable, e.g. in inheritance situations `order`: # To order things, properties listed in that order first, then the rest

SectionProperties¶

A filter defined by an include list or and exclude list of the quantities and subsections.

name	type
visible	`Filter`	Defines the visible quantities and subsections. default: `1`
editable	`Filter`	Defines the editable quantities and subsections.
order	`List[str]`	To customize the order of the quantities and subsections.

Filter¶

A filter defined by an include list or and exclude list of the quantities or subsections.

name	type
include	`List[str]`	The list of quantity or subsection names to be included.
exclude	`List[str]`	The list of quantity or subsection names to be excluded.

Tabular data¶

tabular_parser¶

Instructs NOMAD to treat a string valued scalar quantity as a file path and interprets the contents of this file as tabular data. Supports both .csv and Excel files.

name	type
comment	`str`	The character denoting the commented lines in `.csv` files. This is passed to pandas to parse the file. Has to be used to annotate the quantity that holds the path to the `.csv` or excel file.
sep	`str`	The character used to separate cells in a `.csv` file. This is passed to pandas to parse the file. Has to be used to annotate the quantity that holds the path to the `.csv` or excel file.
skiprows	`int`	Number of `.csv` file rows that are skipped. This is passed to pandas to parse the file. Has to be used to annotate the quantity that holds the path to the `.csv` or excel file.
separator	`str`	An alias for `sep`
target_sub_section	`List[str]`	this feature is deprecated and will be removed in future release. Use `row_sections` instead. A `list` of paths to the repeating sub-sections where the tabular quantities are to be filled from individual rows of the excel/csv file (i.e. in the row mode). Each path is a `/` separated list of nested sub-sections. The targeted sub-sections, will be considered when mapping table rows to quantities. Has to be used to annotate the quantity that holds the path to the `.csv` or excel file. default: `[]`
mode	`str`	This is optional. It will be removed in future release. Either `column`, `row`, or `entry`. With `column` the whole column is mapped into a quantity (needs to be a list). With `row` each row (and its cells) are mapped into instances of a repeating sub section, where each section represents a row (quantities need to be scalars). With `entry` new entry is created and populated from each row (and its cells) where all quantities should remain to be scalars. Has to be used to annotate the quantity that holds the path to the `.csv` or excel file. default: `column` options: - `row` - `column` - `root` - `entry`
current_entry	`CurrentEntryOptions`	Append a list of `row_sections` and `column_sections` here to parse the tabular data in the same NOMAD entry default: `[]`
new_entry	`List[NewEntryOptions]`	Append a list of `row_sections` and `column_sections` and `row_to_entries` here to parse the tabular data in new entries. default: `[]`

NewEntryOptions¶

name	type
row_to_sections	`List[str]`	A `list` of paths to the repeating sub-sections where the tabular quantities are to be filled from individual rows of the excel/csv file (i.e. in the row mode). Each path is a `/` separated list of nested sub-sections. The targeted sub-sections, will be considered when mapping table rows to quantities. Has to be used to annotate the quantity that holds the path to the `.csv` or excel file. default: `[]`
column_to_sections	`List[str]`	A `list` of paths to the sub-sections where the tabular quantities are to be filled from the entire column of the excel/csv file (i.e. in the column mode). Each path is a `/` separated list of nested sub-sections. The targeted sub-sections, will be considered when mapping table columns to quantities. Has to be used to annotate the quantity that holds the path to the `.csv` or excel file. default: `[]`
row_to_entries	`List[str]`	A `list` of paths to the (sub)sections where the tabular quantities are to be filled from individual rows of the excel/csv file, to create distinct entries. Each path is a `/` separated list of nested sub-sections. The targeted (sub)sections, will be considered when mapping table rows to quantities. The schema of the resultant entry follows the (sub)section's schema. In order to parse the entire schema using entry mode, then set the first item in this list to `root`. Has to be used to annotate the quantity that holds the path to the `.csv` or excel file. default: `[]`

CurrentEntryOptions¶

name	type
row_to_sections	`List[str]`	A `list` of paths to the repeating sub-sections where the tabular quantities are to be filled from individual rows of the excel/csv file (i.e. in the row mode). Each path is a `/` separated list of nested sub-sections. The targeted sub-sections, will be considered when mapping table rows to quantities. Has to be used to annotate the quantity that holds the path to the `.csv` or excel file. default: `[]`
column_to_sections	`List[str]`	A `list` of paths to the sub-sections where the tabular quantities are to be filled from the entire column of the excel/csv file (i.e. in the column mode). Each path is a `/` separated list of nested sub-sections. The targeted sub-sections, will be considered when mapping table columns to quantities. Has to be used to annotate the quantity that holds the path to the `.csv` or excel file. default: `[]`

tabular¶

Allows to map a quantity to a row of a tabular data-file. Should only be used in conjunction with tabular_parser.

name	type
name	`str`	The column name that should be mapped to the annotation quantity. Has to be the same string that is used in the header, i.e. first `.csv` line or first excel file `row`. For excel files with multiple sheets, the name can have the form `<sheet name>/<column name>`. Otherwise, only the first sheets is used. Has to be applied to the quantity that a column should be mapped to.
unit	`str`	The unit of the value in the file. Has to be compatible with the annotated quantity's unit. Will be used to automatically convert the value. If this is not defined, the values will not be converted. Has to be applied to the quantity that a column should be mapped to.

plot¶

This annotation can be used to add a plot to a section or quantity. Example:

class Evaporation(MSection):
    m_def = Section(a_plot={
        'label': 'Temperature and Pressure',
        'x': 'process_time',
        'y': ['./substrate_temperature', './chamber_pressure'],
        'config': {
            'editable': True,
            'scrollZoom': False
        }
    })
    time = Quantity(type=float, shape=['*'], unit='s')
    substrate_temperature = Quantity(type=float, shape=['*'], unit='K')
    chamber_pressure = Quantity(type=float, shape=['*'], unit='Pa')

You can create multi-line plots by using lists of the properties y (and x). You either have multiple sets of y-values over a single set of x-values. Or you have pairs of x and y values. For this purpose the annotation properties x and y can reference a single quantity or a list of quantities. For repeating sub sections, the section instance can be selected with an index, e.g. "sub_section_name/2/parameter_name" or with a slice notation start:stop where negative values index from the end of the array, e.g. "sub_section_name/1:-5/parameter_name".

The interactive examples of the plot annotations can be found here.

name	type
label	`str`	Is passed to plotly to define the label of the plot.
x	`Union[List[str], str]`	A path or list of paths to the x-axes values. Each path is a `/` separated list of sub-section and quantity names that leads from the annotation section to the quantity. Repeating sub sections are indexed between two `/`s with an integer or a slice `start:stop`.
y	`Union[List[str], str]`	A path or list of paths to the y-axes values. list of sub-section and quantity names that leads from the annotation section to the quantity. Repeating sub sections are indexed between two `/`s with an integer or a slice `start:stop`.
lines	`List[dict]`	A list of dicts passed as `traces` to plotly to configure the lines of the plot. See https://plotly.com/javascript/reference/scatter/ for details.
layout	`dict`	A dict passed as `layout` to plotly to configure the plot layout. See https://plotly.com/javascript/reference/layout/ for details.
config	`dict`	A dict passed as `config` to plotly to configure the plot functionallity. See https://plotly.com/javascript/configuration-options/ for details.

browser¶

The browser annotation allows to specify if the processed data browser needs to display a quantity differently. It can be applied to quantities. For example

    class Experiment(EntryData):
        description = Quantity(type=str, a_browser=dict(render_value='HtmlValue'))

or in yaml

Experiment:
  quantities:
    description:
      type: str
      m_annotations:
        browser:
          render_value: HtmlValue

name	type
adaptor	`str`	Allows to change the Adaptor implementation that is used to render the lane for this quantity. Possible values are: `RawFileAdaptor`: An adopter that is used to show files, including all file actions, like file preview. options: - `RawFileAdaptor`
render_value	`str`	Allows to change the Component used to render the value of the quantity. Possible values are: `HtmlValue`: Renders a string as HTML. `JsonValue`: Renders a dict or list in a collapsable tree. options: - `JsonValue` - `HtmlValue`