How to create an app¶

Apps provide customized views of data in the GUI, making it easier for the users to navigate and understand the data related to a specific domain. This typically means that certain domain-specific properties are highlighted, different units may be used for physical properties, and specialized widgets 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 write a Python schema package or a YAML schema package.

This documentation shows you how to create a plugin entry point for an app. You should read the introduction to plugins to have a basic understanding of how plugins and plugin entry points work in the NOMAD ecosystem.

Getting started¶

You can use our template repository to create an initial structure for a plugin containing an app. The relevant part of the repository layout will look something like this:

nomad-example
   ├── src
   │   └── nomad_example
   │       └── apps
   │           └── __init__.py
   ├── LICENSE.txt
   ├── README.md
   └── pyproject.toml

See the documentation on plugin development guidelines for more details on the best development practices for plugins, including linting, testing and documenting.

App entry point¶

The entry point defines basic information about your app and is used to automatically load the app into a NOMAD distribution. It is an instance of an AppEntryPoint and unlike many other plugin entry points, it does not have a separate resource that needs to be lazy-loaded as the entire app is defined in the configuration as an instance of nomad.config.models.ui.App. You will learn more about the App class in the next sections. The entry point should be defined in */apps/__init__.py like this:

from nomad.config.models.plugins import AppEntryPoint
from nomad.config.models.ui import App

myapp = AppEntryPoint(name='MyApp', description='My custom app.', app=App(...))

Here we have instantiated an object myapp in which you specify the default parameterization and other details about the app. In the reference you can see all of the available configuration options for an AppEntryPoint.

The entry point instance should then be added to the [project.entry-points.'nomad.plugin'] table in pyproject.toml in order for the app to be automatically detected:

[project.entry-points.'nomad.plugin']
myapp = "nomad_example.apps:myapp"

Creating an `App`¶

The definition fo the actual app is given as an instance of the App class specified as part of the entry point. A full breakdown of the model is given below in the app reference, but here is a small example:

from nomad.config.models.plugins import AppEntryPoint
from nomad.config.models.ui import (
    App,
    Axis,
    Column,
    Dashboard,
    Format,
    Layout,
    Menu,
    MenuItemHistogram,
    MenuItemPeriodicTable,
    MenuItemTerms,
    WidgetHistogram,
)

schema = 'nomad_example.schema_packages.mypackage.MySchema'
myapp = AppEntryPoint(
    name='MyApp',
    description='App defined using the new plugin mechanism.',
    app=App(
        # 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='Theory',
        # 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=[
            Column(search_quantity='entry_id', selected=True),
            Column(
                search_quantity=f'data.mysection.myquantity#{schema}',
                label='My Quantity Name',
                unit='eV',
                align='left',
                format=Format(decimals=2, mode='standard'),
                selected=True,
            ),
            Column(
                search_quantity=f'data.my_repeated_section[*].myquantity#{schema}',
                align='middle',
                selected=False,
            ),
            Column(search_quantity='upload_create_time'),
        ],
        # 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. This example makes sure that only entries that use
        # MySchema are included.
        filters_locked={'section_defs.definition_qualified_name': [schema]},
        # Controls the menu shown on the left
        menu=Menu(
            title='Material',
            items=[
                Menu(
                    title='elements',
                    items=[
                        MenuItemPeriodicTable(
                            search_quantity='results.material.elements',
                        ),
                        MenuItemTerms(
                            search_quantity='results.material.chemical_formula_hill',
                            width=6,
                            options=0,
                        ),
                        MenuItemTerms(
                            search_quantity='results.material.chemical_formula_iupac',
                            width=6,
                            options=0,
                        ),
                        MenuItemHistogram(
                            x='results.material.n_elements',
                        ),
                    ],
                )
            ],
        ),
        # Controls the default dashboard shown in the search interface
        dashboard=Dashboard(
            widgets=[
                WidgetHistogram(
                    title='Histogram Title',
                    show_input=False,
                    autorange=True,
                    nbins=30,
                    scale='linear',
                    x=Axis(search_quantity=f'data.mysection.myquantity#{schema}'),
                    layout={'lg': Layout(w=12, h=4, x=0, y=0)},
                )
            ]
        ),
    ),
)

Tip

If you want to load an app definition from a YAML file, this can be easily done with the pydantic parse_obj function:

import yaml
from nomad.config.models.plugins import AppEntryPoint
from nomad.config.models.ui import App

yaml_data = """
    label: My App
    path: myapp
    category: Theory
"""
myapp = AppEntryPoint(
    name='MyApp',
    description='App defined using the new plugin mechanism.',
    app=App.parse_obj(yaml.safe_load(yaml_data)),
)

Search quantities¶

Apps can only display and work on values that are indexed in the NOMAD search index. Not all values can/should be meaningfully indexed, as they would otherwise overcrowd and slow down the search functionality. By default, apps can work on scalar quantities that are present in the schemas, as they are automatically indexed. This means that, for example, values from lists or multidimensional arrays are not available for search.

Quantities that are indexed and can thus be searched are in this document referred to as search quantities, and the app configuration often refers to them. E.g. to display a specific search quantity as an app column, one would define it like this:

from nomad.config.models.ui import Column

columns = [
    Column(
        search_quantity='data.mysection.myquantity#nomad_example.schema_packages.mypackage.MySchema',
        label='My Quantity Name',
        selected=True,
    ),
]

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#nomad_example.schema_packages.mypackage.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.

Narrowing down search results in the app¶

The search results that will show up in the app can be narrowed down by passing a dictionary to the filters_locked option. In the example app, only entries that use MySchema are included.

filters_locked = {'section_defs.definition_qualified_name': [schema]}

It is also possible to filter by quantities defined in the results section. For example, if you want to limit your app to entries that have the property catalytic filled in the results section:

filters_locked = {'quantities': ['results.properties.catalytic']}

Columns¶

Controls columns show in the table of search results. Here you can control the order, units, labelling, and the data source for the colums. Here is an example:

from nomad.config.models.ui import Column, Format

schema = 'nomad_example.schema_packages.mypackage.MySchema'
columns = [
    Column(
        search_quantity=f'data.mysection.myquantity#{schema}',
        label='My Quantity Name',
        unit='eV',
        align='left',
        format=Format(decimals=2, mode='standard'),
        selected=True,
    ),
    Column(
        search_quantity=f'data.my_repeated_section[*].myquantity#{schema}',
        align='middle',
        selected=False,
    ),
]

See the Column and Format options for more details.

The menu field controls the structure of the menu shown on the left side of the search interface. Menus have a controllable width, and they contain items that are displayed on a 12-based grid. You can also nest menus within each other. For example, this defines a menu with two levels:

from nomad.config.models.ui import Axis, Menu, MenuItemHistogram, MenuItemTerms

# This is a top level menu that is always visible. It shows two items: a terms
# item and a submenu beneath it.
menu = Menu(
    size='sm',
    items=[
        MenuItemTerms(search_quantity='authors.name', options=5),
        # This is a submenu whose items become visible once selected. It
        # contains three items: one full-width histogram and two terms items
        # which are displayed side-by-side.
        Menu(
            title='Submenu',
            size='md',
            items=[
                MenuItemHistogram(x=Axis(search_quantity='upload_create_time')),
                # These items target data from a custom schema
                MenuItemTerms(
                    width=6,
                    search_quantity='data.quantity1#nomad_example.schema_packages.mypackage.MySchema',
                ),
                MenuItemTerms(
                    width=6,
                    search_quantity='data.quantity2#nomad_example.schema_packages.mypackage.MySchema',
                ),
            ],
        ),
    ],
)

The following items are supported in menus, and you can read more about them in the App reference:

Menu: Defines a nested submenu.
MenuItemTerms: Used to display a set of possible text options.
MenuItemHistogram: Histogram of numerical values.
MenuItemPeriodicTable: Displays a periodic table.
MenuItemVisibility: Controls for the query visibility.
MenuItemNestedObject: Used to group together menu items so that their query is performed using an Elasticsearch nested query. Note that you cannot yet use nested queries for search quantities originating from custom schemas.

Widgets¶

The app may display widgets which contain interactive visualizations about the data and statistics, and can be controlled in size and position. Here is an example of a widget configuration:

from nomad.config.models.ui import (
    Axis,
    Dashboard,
    Layout,
    WidgetBoxPlot,
    WidgetHistogram,
    WidgetPeriodicTable,
    WidgetScatterPlot,
    WidgetTerms,
)

schema = 'nomad_example.schema_packages.mypackage.MySchema'

dashboard = Dashboard(
    widgets=[
        WidgetPeriodicTable(
            title='Elements of the material',
            search_quantity='results.material.elements',
            scale='linear',
            layout={'lg': Layout(w=12, h=6, x=0, y=0)},
        ),
        WidgetTerms(
            title='Widget Terms Title',
            search_quantity=f'data.mysection.myquantity#{schema}',
            showinput=True,
            scale='linear',
            layout={'lg': Layout(w=12, h=6, x=0, y=6)},
        ),
        WidgetBoxPlot(
            title='Widget Box Plot Title',
            y=Axis(
                search_quantity=f'data.mysection.mynumericalquantity#{schema}',
                title='quantity y',
            ),
            autorange=True,
            subgroup_by_size=5,
            subgroup_by='data.mysection.mycategoricalquantity#{schema}',
            group_by_size=5,
            group_by='data.mysection.myothercategoricalquantity#{schema}',
            show_points=True,
            sample_size=1000,
            layout={'lg': Layout(w=12, h=6, x=0, y=12)},
        ),
        WidgetHistogram(
            title='Histogram Title',
            show_input=False,
            autorange=True,
            nbins=30,
            scale='linear',
            x=Axis(search_quantity=f'data.mysection.myquantity#{schema}'),
            layout={'lg': Layout(w=12, h=6, x=0, y=18)},
        ),
        WidgetScatterPlot(
            title='Scatterplot title',
            autorange=True,
            x=Axis(
                search_quantity=f'data.mysection.mynumericalquantity#{schema}',
                title='quantity x',
            ),
            y=Axis(search_quantity=f'data.mysection.myothernumericalquantity#{schema}'),
            color=f'data.mysection.myquantity#{schema}',  # optional, if set has to be scalar value
            size=1000,  # maximum number of entries loaded
            layout={'lg': Layout(w=12, h=6, x=0, y=24)},
        ),
    ]
)

These are the available widgets:

WidgetTerms: Displays the most frequently appearing values for a categorical search quantity.
WidgetHistogram: Displays the frequency of a numerical search quantity by grouping values into bins.
WidgetScatterplot: Displays a scatter plot for two numerical search quantities.
WidgetBoxPlot: Displays a box plot for a numerical search quantity, optionally grouped and subgrouped by a categorical search quantity.
WidgetPeriodicTable: Displays a periodic table with occurrence of each element using a search quantity that contains chemical element names.

Row actions¶

You may add specific, always-visible row actions for each result table row. These actions are shown as buttons at the end of the table rows, and can open new pages for different resources linked to the entry. Here is an example of two actions, one opening up a NORTH tool, and the other for opening up a link.

from nomad.config.models.ui import RowActionNorth, RowActions, RowActionURL, Rows

rows = Rows(
    actions=RowActions(
        items=[
            RowActionURL(icon='launch', path='data.url', description='Open a link.'),
            RowActionNorth(
                icon='launch',
                filepath='data.filepath',
                tool_name='jupyter',
                description='Open file in Jupyter',
            ),
        ]
    )
)

The following actions types are supported:

RowActionNorth: Opening up a specific filepath read from the entry using a specific NORTH tool.
RowActionURL: Opening up a link by reading a URL from the entry.

App reference¶

Here is the full reference for all app configration options.

App¶

Defines the layout and functionality for an App.

name	type
label	`str`	Name of the App. default: `PydanticUndefined`
path	`str`	Path used in the browser address bar. default: `PydanticUndefined`
resource	`str`	Targeted resource. default: `entries` options: - `entries` - `materials`
category	`str`	Category used to organize Apps in the explore menu. default: `PydanticUndefined`
pagination	`Pagination`	Default result pagination. default: Complex object, default value not displayed.
breadcrumb	`str \| None`	Name displayed in the breadcrumb, by default the label will be used.
description	`str \| None`	Short description of the App.
readme	`str \| None`	Longer description of the App that can also use markdown.
columns	`list[Column] \| None`	List of columns for the results table.
rows	`Rows \| None`	Controls the display of entry rows in the results table. default: Complex object, default value not displayed.
menu	`Menu \| None`	Filter menu displayed on the left side of the screen.
filter_menus	`FilterMenus \| None`	deprecated
filters	`Filters \| None`	deprecated
search_quantities	`SearchQuantities \| None`	Controls the quantities that are available for search in this app. default: Complex object, default value not displayed.
dashboard	`Dashboard \| None`	Default dashboard layout.
filters_locked	`dict \| None`	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 \| None`	Controls which types of search syntax are available.

Filters¶

Alias for SearchQuantities.

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

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`

Rows¶

Controls the visualization of rows in the search results.

name	type
actions	`RowActions`	default: Complex object, default value not displayed.
details	`RowDetails`	default: Complex object, default value not displayed.
selection	`RowSelection`	default: Complex object, default value not displayed.

RowSelection¶

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

name	type
enabled	`bool`	Whether to show the row selection. 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	`bool`	Whether to show row details. default: `True`

RowActions¶

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

name	type
enabled	`bool`	Whether to enable row actions. default: `True`
include	`list[str] \| None`	List of included options. If not explicitly defined, all of the options will be included by default.
exclude	`list[str] \| None`	List of excluded options. Has higher precedence than include.
options	`dict[str, RowActionNorth \| RowActionURL] \| None`	deprecated
items	`list[RowActionNorth \| RowActionURL] \| None`	List of actions to show for each row.

RowActionNorth¶

Action that will open a NORTH tool given its name in the archive.

name	type
icon	`str`	The icon to show for the action. You can browse the available icons at: https://fonts.google.com/icons?icon.set=Material+Icons. Note that you have to give the icon name in snake_case. In addition, the following extra icons are available: - `github`: @material-ui/icons/GitHub default: `launch`
filepath	`str`	JMESPath pointing to a path in the archive that contains the filepath. default: `PydanticUndefined`
tool_name	`str`	Name of the NORTH tool to open. default: `PydanticUndefined`
description	`str \| None`	Description of the action shown to the user.

RowActionURL¶

Action that will open an external link read from the archive.

name	type
icon	`str`	The icon to show for the action. You can browse the available icons at: https://fonts.google.com/icons?icon.set=Material+Icons. Note that you have to give the icon name in snake_case. In addition, the following extra icons are available: - `github`: @material-ui/icons/GitHub default: `launch`
path	`str`	JMESPath pointing to a path in the archive that contains the URL. default: `PydanticUndefined`
description	`str \| None`	Description of the action shown to the user.

Menu¶

Defines a menu that is shown on the left side of the search interface. Menus have a controllable width, and contains items. Items in the menu are displayed on a 12-based grid and you can control the width of each item by using the width field. You can also nest menus within each other.

name	type
width	`int`	Width of the item, 12 means maximum width. Note that the menu size can be changed. default: `12`
show_header	`bool`	Whether to show the header. default: `True`
title	`str \| None`	Custom item title.
size	`str \| str \| None`	Size of the menu. Either use presets as defined by MenuSizeEnum, or then provide valid CSS widths. default: `MenuSizeEnum.SM`
indentation	`int \| None`	Indentation level for the menu. default: `0`
items	`list[MenuItemTerms \| MenuItemHistogram \| MenuItemPeriodicTable \| MenuItemNestedObject \| MenuItemVisibility \| MenuItemDefinitions \| MenuItemOptimade \| MenuItemCustomQuantities \| Menu] \| None`	List of items in the menu.

MenuItemHistogram¶

Menu item that shows a histogram for numerical or timestamp quantities.

name	type
show_input	`bool`	Whether to show text input field. default: `True`
x	`Axis \| str`	Configures the information source and display options for the x-axis. default: `PydanticUndefined`
y	`AxisScale \| str`	Configures the information source and display options for the y-axis. default: `PydanticUndefined`
autorange	`bool`	Whether to automatically set the range according to the data limits. default: `False`
width	`int`	Width of the item, 12 means maximum width. Note that the menu size can be changed. default: `12`
show_header	`bool`	Whether to show the header. default: `True`
show_statistics	`bool`	Whether to show the full histogram, or just a range slider. default: `True`
quantity	`str \| None`	deprecated
scale	`str \| None`	deprecated
showinput	`bool \| None`	deprecated
n_bins	`int \| None`	Maximum number of histogram bins to request. Notice that the returned number of bins may be smaller if there are fewer data items available.
nbins	`int \| None`	deprecated
title	`str \| None`	Custom item title.

AxisScale¶

Basic configuration for a plot axis.

name	type
scale	`str \| None`	Defines the axis scaling. Defaults to linear scaling. default: `ScaleEnum.LINEAR`

Axis¶

Configuration for a plot axis with limited scaling options.

name	type
search_quantity	`str`	Path of the targeted search quantity. Note that you can most of the features JMESPath syntax here to further specify a selection of values. This becomes especially useful when dealing with repeated sections or statistical values. default: `PydanticUndefined`
title	`str \| None`	Custom title to show for the axis.
unit	`str \| None`	Custom unit used for displaying the values.
quantity	`str \| None`	deprecated
scale	`str \| None`	Defines the axis scaling. Defaults to linear scaling. default: `ScaleEnum.LINEAR`

MenuItemPeriodicTable¶

Menu item that shows a periodic table built from values stored into a text quantity.

name	type
search_quantity	`str`	The targeted search quantity. default: `PydanticUndefined`
width	`int`	Width of the item, 12 means maximum width. Note that the menu size can be changed. default: `12`
show_header	`bool`	Whether to show the header. default: `True`
show_statistics	`bool`	Whether to show statistics for the options. default: `True`
quantity	`str \| None`	deprecated
scale	`str \| None`	Statistics scaling. default: `ScaleEnum.LINEAR`
title	`str \| None`	Custom item title.

MenuItemCustomQuantities¶

Menu item that shows a search dialog for filtering by custom quantities coming from all different custom schemas, including YAML and Python schemas. Will only show quantities that have been populated in the data.

name	type
width	`int`	Width of the item, 12 means maximum width. Note that the menu size can be changed. default: `12`
show_header	`bool`	Whether to show the header. default: `True`
title	`str \| None`	Custom item title.

MenuItemTerms¶

Menu item that shows a list of text values from e.g. str or MEnum quantities.

name	type
search_quantity	`str`	The targeted search quantity. default: `PydanticUndefined`
scale	`str`	Statistics scaling. default: `ScaleEnum.LINEAR` options: - `linear` - `log` - `1/2` - `1/4` - `1/8`
show_input	`bool`	Whether to show text input field. default: `True`
width	`int`	Width of the item, 12 means maximum width. Note that the menu size can be changed. default: `12`
show_header	`bool`	Whether to show the header. default: `True`
n_columns	`int`	The number of columns to use when displaying the options. default: `1`
sort_static	`bool`	Whether to sort static options by their occurrence in the data. Options are static if they are read from the enum options of the field or if they are explicitly given as a dictionary in 'options'. default: `True`
show_statistics	`bool`	Whether to show statistics for the options. default: `True`
quantity	`str \| None`	deprecated
showinput	`bool \| None`	deprecated
query_mode	`str \| None`	The query mode to use when multiple terms are selected.
title	`str \| None`	Custom item title.
options	`int \| bool \| dict[str, MenuItemOption] \| None`	Used to control the displayed options: - If not specified, sensible default options are shown based on the definition. For enum fields all of the defined options are shown, whereas for generic string fields the top 5 options are shown. - If a number is specified, that many options are dynamically fetched in order of occurrence. Set to 0 to completely disable options. - If a dictionary of str + MenuItemOption pairs is given, only these options will be shown.

MenuItemOption¶

Represents an option shown for a filter.

name	type
label	`str \| None`	The label to show for this option.
description	`str \| None`	Detailed description for this option.

MenuItemOptimade¶

Menu item that shows a dialog for entering OPTIMADE queries.

name	type
width	`int`	Width of the item, 12 means maximum width. Note that the menu size can be changed. default: `12`
show_header	`bool`	Whether to show the header. default: `True`
title	`str \| None`	Custom item title.

MenuItemVisibility¶

Menu item that shows a radio button that can be used to change the visiblity.

name	type
width	`int`	Width of the item, 12 means maximum width. Note that the menu size can be changed. default: `12`
show_header	`bool`	Whether to show the header. default: `True`
title	`str \| None`	Custom item title.

MenuItemNestedObject¶

Menu item that can be used to wrap several subitems into a nested object. By wrapping items with this class the query for them is performed as an Elasticsearch nested query: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-nested-query.html. Note that you cannot yet use nested queries for search quantities originating from custom schemas.

name	type
width	`int`	Width of the item, 12 means maximum width. Note that the menu size can be changed. default: `12`
show_header	`bool`	Whether to show the header. default: `True`
path	`str`	Path of the nested object. Typically a section name. default: `PydanticUndefined`
title	`str \| None`	Custom item title.
items	`list[MenuItemTerms \| MenuItemHistogram \| MenuItemPeriodicTable \| MenuItemVisibility \| MenuItemDefinitions \| MenuItemOptimade \| MenuItemCustomQuantities] \| None`	Items that are grouped by this nested object.

MenuItemDefinitions¶

Menu item that shows a tree for filtering data by the presence of definitions.

name	type
width	`int`	Width of the item, 12 means maximum width. Note that the menu size can be changed. default: `12`
show_header	`bool`	Whether to show the header. default: `True`
title	`str \| None`	Custom item title.

Dashboard¶

Dashboard configuration.

name	type
widgets	`list[WidgetTerms \| WidgetHistogram \| WidgetScatterPlot \| WidgetScatterPlotDeprecated \| WidgetBoxPlot \| WidgetPeriodicTable \| WidgetPeriodicTableDeprecated]`	List of widgets contained in the dashboard. default: `PydanticUndefined`

WidgetScatterPlotDeprecated¶

Deprecated copy of WidgetScatterPlot with a misspelled type.

name	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`. default: `PydanticUndefined`
x	`AxisLimitedScale \| str`	Configures the information source and display options for the x-axis. default: `PydanticUndefined`
y	`AxisLimitedScale \| str`	Configures the information source and display options for the y-axis. default: `PydanticUndefined`
size	`int`	Maximum number of entries to fetch. Notice that the actual number may be more or less, depending on how many entries exist and how many of the requested values each entry contains. default: `1000` deprecated
sample_size	`int`	Maximum number of samples to fetch. Notice that the actual number of data points may be more or less, depending on how many entries exist and how many of the requested values each entry contains. default: `1000`
drag_mode	`str`	Action to perform on mouse drag. default: `DragModeEnum.ZOOM`
autorange	`bool`	Whether to automatically set the range according to the data limits. default: `True`
title	`str \| None`	Custom widget title. If not specified, a widget-specific default title is used.
description	`str \| None`	Optional description of the widget and the data it is showing. Can contain markdown notation. If populated, an icon is shown next to the title that can be clicked to show the description.
markers	`Markers \| None`	Configures the information source and display options for the markers.
color	`str \| None`	Quantity used for coloring points. Note that this field is deprecated and `markers` should be used instead.

AxisLimitedScale¶

Configuration for a plot axis with limited scaling options.

name	type
search_quantity	`str`	Path of the targeted search quantity. Note that you can most of the features JMESPath syntax here to further specify a selection of values. This becomes especially useful when dealing with repeated sections or statistical values. default: `PydanticUndefined`
title	`str \| None`	Custom title to show for the axis.
unit	`str \| None`	Custom unit used for displaying the values.
quantity	`str \| None`	deprecated
scale	`str \| None`	Defines the axis scaling. Defaults to linear scaling. default: `ScaleEnumPlot.LINEAR`

Layout¶

Defines widget size and grid positioning for different breakpoints.

name	type
h	`int`	Height in grid units default: `PydanticUndefined`
w	`int`	Width in grid units. default: `PydanticUndefined`
x	`int`	Horizontal start location in the grid. default: `PydanticUndefined`
y	`int`	Vertical start location in the grid. default: `PydanticUndefined`
minH	`int \| None`	Minimum height in grid units. default: `3`
minW	`int \| None`	Minimum width in grid units. default: `3`

Markers¶

Configuration for plot markers.

name	type
color	`Axis \| None`	Configures the information source and display options for the marker colors.

WidgetScatterPlot¶

Scatter plot widget configuration.

name	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`. default: `PydanticUndefined`
x	`AxisLimitedScale \| str`	Configures the information source and display options for the x-axis. default: `PydanticUndefined`
y	`AxisLimitedScale \| str`	Configures the information source and display options for the y-axis. default: `PydanticUndefined`
size	`int`	Maximum number of entries to fetch. Notice that the actual number may be more or less, depending on how many entries exist and how many of the requested values each entry contains. default: `1000` deprecated
sample_size	`int`	Maximum number of samples to fetch. Notice that the actual number of data points may be more or less, depending on how many entries exist and how many of the requested values each entry contains. default: `1000`
drag_mode	`str`	Action to perform on mouse drag. default: `DragModeEnum.ZOOM`
autorange	`bool`	Whether to automatically set the range according to the data limits. default: `True`
title	`str \| None`	Custom widget title. If not specified, a widget-specific default title is used.
description	`str \| None`	Optional description of the widget and the data it is showing. Can contain markdown notation. If populated, an icon is shown next to the title that can be clicked to show the description.
markers	`Markers \| None`	Configures the information source and display options for the markers.
color	`str \| None`	Quantity used for coloring points. Note that this field is deprecated and `markers` should be used instead.

WidgetBoxPlot¶

Box plot widget configuration.

name	type
sample_size	`int`	Maximum number of samples to fetch. Notice that the actual number of data points may be more or less, depending on how many entries exist and how many of the requested values each entry contains. default: `1000`
show_points	`bool`	Whether to show individual data points. default: `True`
y	`Axis`	Configures the information source and display options for the y-axis. default: `PydanticUndefined`
group_by_size	`int`	Maximum number of groups to request when `group_by` is set. Note that the returned number of groups may be smaller because any group which does not contain the y-value still count in this limit, but are not returned to avoid visualization of empty groups. default: `10`
autorange	`bool`	Whether to automatically set the range according to the data limits. default: `True`
layout	`dict[str, Layout]`	Defines widget size and grid positioning for different breakpoints. The following breakpoints are supported: `sm`, `md`, `lg`, `xl` and `xxl`. default: `PydanticUndefined`
group_by	`str \| None`	Optional quantity used to group data into separate boxes along the x-axis. The groups will be ordered by the number of points matching each group in a descending order.
subgroup_by	`str \| None`	Optional quantity used to subgroup the groups into separate boxes along the x-axis. The subgroups will be ordered by the number of points matching each group in a descending order.
subgroup_by_size	`str \| None`	Maximum number of subgroups to request when `subgroup_by` is set. Note that the returned number of subgroups may be smaller because any subgroup which does not contain the y-value still count in this limit, but are not returned to avoid visualization of empty groups.
markers	`Markers \| None`	Configures the information source and display options for the markers.
title	`str \| None`	Custom widget title. If not specified, a widget-specific default title is used.
description	`str \| None`	Optional description of the widget and the data it is showing. Can contain markdown notation. If populated, an icon is shown next to the title that can be clicked to show the description.

WidgetTerms¶

Terms widget configuration.

name	type
search_quantity	`str`	The targeted search quantity. default: `PydanticUndefined`
scale	`str`	Statistics scaling. default: `ScaleEnum.LINEAR` options: - `linear` - `log` - `1/2` - `1/4` - `1/8`
show_input	`bool`	Whether to show text input field. default: `True`
layout	`dict[str, Layout]`	Defines widget size and grid positioning for different breakpoints. The following breakpoints are supported: `sm`, `md`, `lg`, `xl` and `xxl`. default: `PydanticUndefined`
quantity	`str \| None`	deprecated
showinput	`bool \| None`	deprecated
query_mode	`str \| None`	The query mode to use when multiple terms are selected.
title	`str \| None`	Custom widget title. If not specified, a widget-specific default title is used.
description	`str \| None`	Optional description of the widget and the data it is showing. Can contain markdown notation. If populated, an icon is shown next to the title that can be clicked to show the description.

WidgetHistogram¶

Histogram widget configuration.

name	type
show_input	`bool`	Whether to show text input field. default: `True`
x	`Axis \| str`	Configures the information source and display options for the x-axis. default: `PydanticUndefined`
y	`AxisScale \| str`	Configures the information source and display options for the y-axis. default: `PydanticUndefined`
autorange	`bool`	Whether to automatically set the range according to the data limits. default: `False`
layout	`dict[str, Layout]`	Defines widget size and grid positioning for different breakpoints. The following breakpoints are supported: `sm`, `md`, `lg`, `xl` and `xxl`. default: `PydanticUndefined`
quantity	`str \| None`	deprecated
scale	`str \| None`	deprecated
showinput	`bool \| None`	deprecated
n_bins	`int \| None`	Maximum number of histogram bins to request. Notice that the returned number of bins may be smaller if there are fewer data items available.
nbins	`int \| None`	deprecated
title	`str \| None`	Custom widget title. If not specified, a widget-specific default title is used.
description	`str \| None`	Optional description of the widget and the data it is showing. Can contain markdown notation. If populated, an icon is shown next to the title that can be clicked to show the description.

WidgetPeriodicTableDeprecated¶

Deprecated copy of WidgetPeriodicTable with a misspelled type.

name	type
search_quantity	`str`	The targeted search quantity. default: `PydanticUndefined`
layout	`dict[str, Layout]`	Defines widget size and grid positioning for different breakpoints. The following breakpoints are supported: `sm`, `md`, `lg`, `xl` and `xxl`. default: `PydanticUndefined`
quantity	`str \| None`	deprecated
scale	`str \| None`	Statistics scaling. default: `ScaleEnum.LINEAR`
title	`str \| None`	Custom widget title. If not specified, a widget-specific default title is used.
description	`str \| None`	Optional description of the widget and the data it is showing. Can contain markdown notation. If populated, an icon is shown next to the title that can be clicked to show the description.

WidgetPeriodicTable¶

Periodic table widget configuration.

name	type
search_quantity	`str`	The targeted search quantity. default: `PydanticUndefined`
layout	`dict[str, Layout]`	Defines widget size and grid positioning for different breakpoints. The following breakpoints are supported: `sm`, `md`, `lg`, `xl` and `xxl`. default: `PydanticUndefined`
quantity	`str \| None`	deprecated
scale	`str \| None`	Statistics scaling. default: `ScaleEnum.LINEAR`
title	`str \| None`	Custom widget title. If not specified, a widget-specific default title is used.
description	`str \| None`	Optional description of the widget and the data it is showing. Can contain markdown notation. If populated, an icon is shown next to the title that can be clicked to show the description.

FilterMenus¶

Contains filter menu definitions and controls their availability.

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

FilterMenu¶

Defines the layout and functionality for a filter menu.

name	type
label	`str \| None`	Menu label to show in the UI.
level	`int \| None`	Indentation level of the menu. default: `0`
size	`str \| None`	Width of the menu. default: `FilterMenuSizeEnum.S`
actions	`FilterMenuActions \| None`

FilterMenuActions¶

Contains filter menu action definitions and controls their availability.

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

FilterMenuActionCheckbox¶

Contains definition for checkbox action in the filter menu.

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

SearchQuantities¶

Controls the quantities that are available in the search interface. Search quantities correspond to pieces of information that can be queried in the search interface of the app, but also targeted in the rest of the app configuration. You can load quantities from custom schemas as search quantities, but note that not all quantities will be loaded: only scalar values are supported at the moment. The include and exlude attributes can use glob syntax to target metainfo, e.g. results.* or *.#myschema.schema.MySchema.

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

Column¶

Column show in the search results table. With quantity you may target a specific part of the data to be shown. Note that the use of JMESPath is supported here, and you can e.g. do the following:

Show first value from a repeating subsection: repeating_section[0].quantity
Show slice of values from a repeating subsection: repeating_section[1:2].quantity
Show all values from a repeating subsection: repeating_section[*].quantity
Show minimum value from a repeating section: min(repeating_section[*].quantity)
Show instance that matches a criterion: repeating_section[?label=='target'].quantity

name	type
selected	`bool`	Is this column initially selected to be shown. default: `False`
align	`str`	Alignment in the table. default: `AlignEnum.LEFT` options: - `left` - `right` - `center`
search_quantity	`str \| None`	Path of the targeted quantity. Note that you can most of the features JMESPath syntax here to further specify a selection of values. This becomes especially useful when dealing with repeated sections or statistical values.
quantity	`str \| None`	deprecated
title	`str \| None`	Label shown in the header. Defaults to the quantity name.
label	`str \| None`	Alias for title.
unit	`str \| None`	Unit to convert to when displaying. If not given will be displayed in using the default unit in the active unit system.
format	`Format \| None`	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: `ModeEnum.SCIENTIFIC` options: - `standard` - `scientific` - `separators` - `date` - `time`

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, free-text queries. Requires that a set of keywords has been filled in the entry.

name	type
exclude	`list[str] \| None`	List of excluded options.

How to create an app¶

Getting started¶

App entry point¶

Creating an App¶

Search quantities¶

Narrowing down search results in the app¶

Columns¶

Menu¶

Widgets¶

Row actions¶

App reference¶

App¶

Filters¶

Pagination¶

Rows¶

RowSelection¶

RowDetails¶

RowActions¶

RowActionNorth¶

RowActionURL¶

Menu¶

MenuItemHistogram¶

AxisScale¶

Axis¶

MenuItemPeriodicTable¶

MenuItemCustomQuantities¶

MenuItemTerms¶

MenuItemOption¶

MenuItemOptimade¶

MenuItemVisibility¶

MenuItemNestedObject¶

MenuItemDefinitions¶

Dashboard¶

WidgetScatterPlotDeprecated¶

AxisLimitedScale¶

Layout¶

Markers¶

WidgetScatterPlot¶

WidgetBoxPlot¶

WidgetTerms¶

WidgetHistogram¶

WidgetPeriodicTableDeprecated¶

WidgetPeriodicTable¶

FilterMenus¶

FilterMenu¶

FilterMenuActions¶

FilterMenuActionCheckbox¶

SearchQuantities¶

Column¶

Format¶

SearchSyntaxes¶

Creating an `App`¶