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
parsing_options	`TabularParsingOptions`	Options on how to extract the data from csv/xlsx file. Under the hood, NOMAD uses pandas `Dataframe` to parse the data from tabular files. These are the available options that can be passed down to the parser. The supported values are: `skiprows`: Number of rows to be skipped while reading the file. `sep`: The character used to separate cells (specific to csv files). `comment`: The character denoting the commented lines. `separator`: An alias for `sep`. default: Complex object, default value not displayed.
mapping_options	`List[TabularMappingOptions]`	A list of directives on how to map the extracted data from the csv/xlsx file to NOMAD. Each directive is a distinct directive, which allows for more modular definition of your tabular parser schema. If no item is provided, the entire schema is treated to be parsed under column mode. The supported values in each item of this list are: `mapping_mode`: 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. `file_mode`: The character used to separate cells (specific to csv files). `with_file`: A boolean variable to dump the processed/parsed data into a ascii-formatted YAML/JSON file. `sections`: The character denoting the commented lines. default: `[]`

TabularParsingOptions¶

name	type
skiprows	`int`	Number of rows to skip
sep	`str`	Character identifier of a separator
comment	`str`	Character identifier of a commented line
separator	`str`	Alias for `sep`

TabularMappingOptions¶

name	type
mapping_mode	`str`	This controls the behaviour of mapping of the extracted data onto NOMAD schema. The supported values are: `row`: 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. `column`: 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. `enrty`: 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: `column` options: - `row` - `column` - `entry`
file_mode	`str`	This controls the behaviour of the parser towards working physical files in file system. The supported values are: `current_entry`: Processing the data into the same NOMAD entry. `single_new_entry`: Creating a new entry and processing the data into this new NOMAD entry. `multiple_new_entries`: Creating many new entries and processing the data into these new NOMAD entries. options: - `current_entry` - `single_new_entry` - `multiple_new_entries`
with_file	`int`	A boolean variable to set creation of new file(s) for each new entry. By default it is set to false default: `False`
sections	`List[str]`	A `list` of paths to the (sub)sections where the tabular quantities are to be filled from the data extracted from the tabular file.

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`