How to configure custom apps¶

Apps provide customized views of data for specific domains, making it easier for the users to navigate and understand the data. This typically means that certain domain-specific properties are highlighted, different units may be used for physical properties, and specialized dashboards may be presented. This becomes crucial for NOMAD installations to be able to scale with data that contains a mixture of experiments and simulations, different techniques, and physical properties spanning different time and length scales.

Apps only affect the way data is displayed for the user: if you wish to affect the underlying data structure, you will need to define a custom Python schema or YAML schema. It is common that a custom schema has an app associated with it, but apps can also provide different views of the same underlying data.

Apps are defined with a static YAML configuration file, which means that no special programming skills are needed and app definitions can be shared easily.

App example¶

Here is an example of a simple app definition in YAML. A full breakdown of the configuration options are given in the reference below.

# Label of the App
label: 'My App'
# Path used in the URL, must be unique
path: 'myapp'
# Used to categorize apps in the explore menu
category: 'Simulations'
# Brief description used in the app menu
description: 'An app customized for me.'
# Longer description that can also use markdown
readme: 'Here is a much longer description of this app'
# Controls which columns are shown in the results table
columns:
  selected:
    - 'entry_type'
  options:
    entry_type:
      label: 'Entry type'
      align: 'left'
    upload_create_time:
      label: 'Upload time'
      align: 'left'
# Dictionary of search filters that are always enabled for queries made within
# this app. This is especially important to narrow down the results to the
# wanted subset. Any available search filter can be targeted here.
filters_locked:
  upload_create_time:
    gte: 0
# Controls the filter menus shown on the left
filter_menus:
  options:
    material:
      label: 'Material'
      level: 0
    elements:
      label: 'Elements / Formula'
      level: 1
      size: 'xl'
# Controls the default dashboard shown in the search interface
dashboard:
  widgets:
  - type: histogram
    showinput: false
    autorange: true
    nbins: 30
    scale: linear
    quantity: results.material.n_elements
    layout:
      lg:
        minH: 3
        minW: 3
        h: 4
        w: 12
        y: 0
        x: 0

Customizing default apps in a NOMAD installation¶

Each NOMAD installation has a set of built-in apps, which are controlled through the ui.apps field in the nomad.yaml configuration file. These are the apps that are defined by default in a NOMAD installation:

entries: Search entries across all domains
calculations: Search calculations
materials: Search materials that are identified from calculations
eln: Search electronic lab notebooks
eels: Search electron energy loss spectroscopy experiments
solarcells: Search solar cells
mofs: Search metal-organic frameworks (MOFs)

In nomad.yaml, it is easy to to select which apps to include or exclude like this:

ui:
  apps:
    include: ['entries', 'materials']

It is also possible to customize specific parts of an existing app definition:

ui:
  apps:
    options:
      entries:
        columns:
          exclude: ['upload_create_time']

Completely new apps can also be defined by adding new entries to the ui.apps.options dictionary:

ui:
  apps:
    options:
      myapp:
        label: 'My App'
        ...

If no explicit rules are added in ui.apps.include or ui.apps.exclude, these new options will be included by default.

Using schema quantities in an app¶

Each app may define additional filters that should be enabled in it. Filters have a special meaning in the app context: filters are pieces of (meta)info than can be queried in the search interface of the app, but also targeted in the rest of the app configuration as explained below in. By default, none of the quantities from custom schemas are loaded as filters, and they need to be explicitly added.

Note

Note that not all of the quantities from a custom schema can be exposed as filters. At the moment we only support targeting scalar quantities from custom schemas.

Each schema has a unique name within the NOMAD ecosystem, which is needed to target them in the configuration. The name depends on the resource in which the schema is defined in:

Python schemas are identified by the python path for the class that inherits from EntryData. For example, if you have a python package called myschema, which has a module called schema.py, which contains the class MySchema, then the schema name will be myschema.schema.MySchema.
YAML schemas are identified by the entry id of the schema file together with the name of the section defined in the YAML schema. For example if you have uploaded a schema YAML file containing a section definition called MySchema, and it has been assigned an entry_id, the schema name will be entry_id:<entry_id>.MySchema.

The quantities from schemas may be included or excluded as filter by using the filters field in the app config. This option supports a wildcard/glob syntax for including/excluding certain filters. For example, to include all filters from the Python schema defined in the class myschema.schema.MySchema, you could use:

myapp:
  filters:
    include:
      - '*#myschema.schema.MySchema'

The same thing for a YAML schema could be achieved with:

myapp:
  filters:
    include:
      - '*#entry_id:<entry_id>.MySchema'

Once quantities from a schema are included in an app as filters, they can be targeted in the rest of the app. The app configuration often refers to specific filters to configure parts of the user interface. For example, one could configure the results table to show a new column using one of the schema quantities with:

myapp:
  columns:
    include:
      - 'data.mysection.myquantity#myschema.schema.MySchema'
      - 'entry_id'
    options:
      data.mysection.myquantity#myschema.schema.MySchema:
      ...

The syntax for targeting quantities depends on the resource:

For python schemas, you need to provide the path and the python schema name separated by a hashtag (#), for example data.mysection.myquantity#myschema.schema.MySchema.
For YAML schemas, you need to provide the path and the YAML schema name separated by a hashtag (#), for example data.mysection.myquantity#entry_id:<entry_id>.MySchema.
Quantities that are common for all NOMAD entries can be targeted by using only the path without the need for specifying a schema, e.g. results.material.symmetry.space_group.

App configuration reference¶

App¶

Defines the layout and functionality for an App.

name	type
label	`str`	Name of the App.
path	`str`	Path used in the browser address bar.
resource	`str`	Targeted resource. default: `entries` options: - `entries` - `materials`
breadcrumb	`str`	Name displayed in the breadcrumb, by default the label will be used.
category	`str`	Category used to organize Apps in the explore menu.
description	`str`	Short description of the App.
readme	`str`	Longer description of the App that can also use markdown.
pagination	`Pagination`	Default result pagination. default: Complex object, default value not displayed.
columns	`Columns`	Controls the columns shown in the results table.
rows	`Rows`	Controls the display of entry rows in the results table. default: Complex object, default value not displayed.
filter_menus	`FilterMenus`	Filter menus displayed on the left side of the screen.
filters	`Filters`	Controls the filters that are available in this app. default: Complex object, default value not displayed.
dashboard	`Dashboard`	Default dashboard layout.
filters_locked	`dict`	Fixed query object that is applied for this search context. This filter will always be active for this context and will not be displayed to the user by default.
search_syntaxes	`SearchSyntaxes`	Controls which types of search syntax are available.

Columns¶

Contains column definitions, controls their availability and specifies the default selection.

name	type
include	`List[str]`	List of included options. If not explicitly defined, all of the options will be included by default.
exclude	`List[str]`	List of excluded options. Has higher precedence than include.
options	`Dict[str, Column]`	All available column options. Note here that the key must correspond to a quantity path that exists in the metadata.
selected	`List[str]`	Selected options.

Column¶

Option for a column show in the search results.

name	type
label	`str`	Label shown in the header. Defaults to the quantity name.
align	`str`	Alignment in the table. default: `left` options: - `left` - `right` - `center`
unit	`str`	Unit to convert to when displaying. If not given will be displayed in using the default unit in the active unit system.
format	`Format`	Controls the formatting of the values.

Format¶

Value formatting options.

name	type
decimals	`int`	Number of decimals to show for numbers. default: `3`
mode	`str`	Display mode for numbers. default: `standard` options: - `standard` - `scientific` - `separators`

Dashboard¶

Dashboard configuration.

name	type
widgets	`List[Union[WidgetTerms, WidgetHistogram, WidgetScatterPlot, WidgetPeriodicTable]]`	List of widgets contained in the dashboard.

WidgetPeriodicTable¶

Periodic table widget configuration.

name	type
type	`str`	Set as `periodictable` to get this widget type.
layout	`Dict[str, Layout]`	Defines widget size and grid positioning for different breakpoints. The following breakpoints are supported: `sm`, `md`, `lg`, `xl` and `xxl`.
quantity	`str`	Targeted quantity.
scale	`str`	Statistics scaling. options: - `linear` - `1/2` - `1/4` - `1/8`

Layout¶

Defines widget size and grid positioning for different breakpoints.

name	type
minH	`int`	Minimum height in grid units.
minW	`int`	Minimum width in grid units.
h	`int`	Height in grid units
w	`int`	Width in grid units.
x	`int`	Horizontal start location in the grid.
y	`int`	Vertical start location in the grid.

WidgetTerms¶

Terms widget configuration.

name	type
type	`str`	Set as `terms` to get this widget type.
layout	`Dict[str, Layout]`	Defines widget size and grid positioning for different breakpoints. The following breakpoints are supported: `sm`, `md`, `lg`, `xl` and `xxl`.
quantity	`str`	Targeted quantity.
scale	`str`	Statistics scaling. options: - `linear` - `1/2` - `1/4` - `1/8`
showinput	`int`	Whether to show text input field. default: `True`

WidgetHistogram¶

Histogram widget configuration.

name	type
type	`str`	Set as `histogram` to get this widget type.
layout	`Dict[str, Layout]`	Defines widget size and grid positioning for different breakpoints. The following breakpoints are supported: `sm`, `md`, `lg`, `xl` and `xxl`.
quantity	`str`	Targeted quantity.
scale	`str`	Statistics scaling. options: - `linear` - `1/2` - `1/4` - `1/8`
autorange	`int`	Whether to automatically set the range according to the data limits. default: `True`
showinput	`int`	Whether to show input text fields for minimum and maximum value. default: `True`
nbins	`int`	Maximum number of histogram bins. Notice that the actual number of bins may be smaller if there are fewer data items available.

WidgetScatterPlot¶

Scatter plot widget configuration.

name	type
type	`str`	Set as `scatterplot` to get this widget type.
layout	`Dict[str, Layout]`	Defines widget size and grid positioning for different breakpoints. The following breakpoints are supported: `sm`, `md`, `lg`, `xl` and `xxl`.
x	`str`	X-axis quantity.
y	`str`	Y-axis quantity.
color	`str`	Quantity used for coloring points.
size	`int`	Maximum number of data points to fetch. Notice that the actual number may be less. default: `1000`
autorange	`int`	Whether to automatically set the range according to the data limits. default: `True`

SearchSyntaxes¶

Controls the availability of different search syntaxes. These syntaxes determine how raw user input in e.g. the search bar is parsed into queries supported by the API.

Currently you can only exclude items. By default, the following options are included:

existence: Used to query for the existence of a specific metainfo field in the data.
equality: Used to query for a specific value with exact match.
range_bounded: Queries values that are between two numerical limits, inclusive or exclusive.
range_half_bounded: Queries values that are above/below a numerical limit, inclusive or exclusive.
free_text: For inexact, queries. Requires that a set of keywords has been filled in the entry.

name	type
exclude	`List[str]`	List of excluded options.

Rows¶

Controls the visualization of rows in the search results.

name	type
actions	`RowActions`
details	`RowDetails`
selection	`RowSelection`

RowActions¶

Controls the visualization of row actions that are shown at the end of each row.

name	type
enabled	`int`	Whether to enable row actions. default: `True`

RowDetails¶

Controls the visualization of row details that are shown upon pressing the row and contain basic details about the entry.

name	type
enabled	`int`	Whether to show row details. default: `True`

RowSelection¶

Controls the selection of rows. If enabled, rows can be selected and additional actions performed on them.

name	type
enabled	`int`	Whether to show the row selection. default: `True`

FilterMenus¶

Contains filter menu definitions and controls their availability.

name	type
include	`List[str]`	List of included options. If not explicitly defined, all of the options will be included by default.
exclude	`List[str]`	List of excluded options. Has higher precedence than include.
options	`Dict[str, FilterMenu]`	Contains the available filter menu options.

FilterMenu¶

Defines the layout and functionality for a filter menu.

name	type
label	`str`	Menu label to show in the UI.
level	`int`	Indentation level of the menu. default: `0`
size	`str`	Width of the menu. default: `s` options: - `s` - `m` - `l` - `xl`
actions	`FilterMenuActions`

FilterMenuActions¶

Contains filter menu action definitions and controls their availability.

name	type
include	`List[str]`	List of included options. If not explicitly defined, all of the options will be included by default.
exclude	`List[str]`	List of excluded options. Has higher precedence than include.
options	`Dict[str, FilterMenuActionCheckbox]`	Contains options for filter menu actions.

FilterMenuActionCheckbox¶

Contains definition for checkbox action in the filter menu.

name	type
type	`str`	Action type. options: - `checkbox`
label	`str`	Label to show.
quantity	`str`	Targeted quantity

Pagination¶

name	type
order_by	`str`	Field used for sorting. default: `upload_create_time`
order	`str`	Sorting order. default: `desc`
page_size	`int`	Number of results on each page. default: `20`

Filters¶

Controls the availability of filters in the app. Filters are pieces of (meta)info than can be queried in the search interface of the app, but also targeted in the rest of the app configuration. The include and exlude attributes can use glob syntax to target metainfo, e.g. results.* or *.#myschema.schema.MySchema.

name	type
include	`List[str]`	List of included options. Supports glob/wildcard syntax.
exclude	`List[str]`	List of excluded options. Supports glob/wildcard syntax. Has higher precedence than include.