How to write 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 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 write a Python schema package or a YAML schema package.

This documentation shows you how to write an plugin entry point for an app. You should read the documentation on getting started with 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

myapp = MyAppEntryPoint(
    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, Column, Menu, MenuItemPeriodicTable, MenuItemHistogram, MenuItemTerms, SearchQuantities

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.',
        # If you want to use quantities from a custom schema, you need to load
        # the search quantities from it first here. Note that you can use a glob
        # syntax to load the entire package, or just a single schema from a
        # package.
        search_quantities=SearchQuantities(
            include=['*#nomad_example.schema_packages.mypackage.MySchema'],
        ),
        # Controls which columns are shown in the results table
        columns=[
            Column(quantity='entry_id', selected=True),
            Column(
                quantity=f'data.section.myquantity#{schema}',
                selected=True
            ),
            Column(
                quantity=f'data.my_repeated_section[*].myquantity#{schema}',
                selected=True
            )
            Column(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:all": [schema]
        },
        # Controls the menu shown on the left
        menu = Menu(
            title='Material',
            items=[
                Menu(
                    title='elements',
                    items=[
                        MenuItemPeriodicTable(
                            quantity='results.material.elements',
                        ),
                        MenuItemTerms(
                            quantity='results.material.chemical_formula_hill',
                            width=6,
                            options=0,
                        ),
                        MenuItemTerms(
                            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={
            'widgets': [
                {
                    'type': 'histogram',
                    'show_input': False,
                    'autorange': True,
                    'nbins': 30,
                    'scale': 'linear',
                    'quantity': f'data.mysection.myquantity#{schema}',
                    'layout': {
                        'lg': {
                            'minH': 3,
                            'minW': 3,
                            'h': 4,
                            'w': 12,
                            'y': 0,
                            'x': 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)
        ),
    )

Loading quantity definitions into an app¶

By default, quantities from custom schemas are not available in an app, and they need to be explicitly added. Each app may define the quantities to load by using the search_quantities field in the app config. Once loaded, these search quantities can be queried in the search interface, but also targeted in the rest of the app configuration as explained below.

Important

Note that not all of the quantities from a custom schema can be loaded into the search. At the moment we only support loading 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 Schema. For example, if you have a python package called nomad_example, which has a subpackage called schema_packages, containing a module called mypackage.py, which contains the class MySchema, then the schema name will be nomad_example.schema_packages.mypackage.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 nomad_example.schema_packages.mypackage.MySchema, you could use:

search_quantities=SearchQuantities(
    include=['*#nomad_example.schema_packages.mypackage.MySchema']
)

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

search_quantities=SearchQuantities(
    include=['*#entry_id:<entry_id>.MySchema']
)

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

columns=[
    Column(quantity='entry_id', selected=True),
    Column(
        quantity='data.mysection.myquantity#nomad_example.schema_packages.mypackage.MySchema',
        selected=True
    ),
    Column(quantity='upload_create_time')
]

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.
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.

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 contains 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:

# 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(
                    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.
MenuItemOptimade: OPTIMADE query field.
MenuItemVisibility: Controls for the query visibility.
MenuItemDefinitions: Shows a tree of available definitions from which items can be selected for the query.
MenuItemCustomQuantities: Form for querying custom quantities coming from any schema.
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.

App 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	`List[Column]`	List of columns for the results table.
rows	`Rows`	Controls the display of entry rows in the results table. default: Complex object, default value not displayed.
menu	`Menu`	Filter menu displayed on the left side of the screen.
filter_menus	`FilterMenus`	deprecated
filters	`Filters`	deprecated
search_quantities	`SearchQuantities`	Controls the quantities that are available for search 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.

Rows¶

Controls the visualization of rows in the search results.

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

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`

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`

RowActions¶

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

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, RowActionURL]`	All available row actions.
enabled	`int`	Whether to enable row actions. default: `True`

RowActionURL¶

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

name	type
description	`str`	Description of the action shown to the user.
type	`str`	Set as `url` to get this widget type. default: `url`
path	`str`	JMESPath pointing to a path in the archive that contains the URL.

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
search_quantity	`str`	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`	deprecated
selected	`int`	Is this column initially selected to be shown. default: `False`
title	`str`	Label shown in the header. Defaults to the quantity name.
label	`str`	Alias for title.
align	`str`	Alignment in the table. default: `AlignEnum.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: `ModeEnum.SCIENTIFIC` options: - `standard` - `scientific` - `separators` - `date` - `time`

Filters¶

Alias for SearchQuantities.

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.

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	`int`	Whether to show the header. default: `True`
title	`str`	Custom item title.
type	`str`	Set as `nested_object` to get this menu item type.
size	`Union[str, str, NoneType]`	Size of the menu. Either use presets as defined by MenuSizeEnum, or then provide valid CSS widths. default: `MenuSizeEnum.SM`
indentation	`int`	Indentation level for the menu. default: `0`
items	`List[Union[MenuItemTerms, MenuItemHistogram, MenuItemPeriodicTable, MenuItemNestedObject, MenuItemVisibility, MenuItemDefinitions, MenuItemOptimade, MenuItemCustomQuantities, ForwardRef('Menu')]]`	List of items in the menu.

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	`int`	Whether to show the header. default: `True`
title	`str`	Custom item title.
type	`str`	Set as `optimade` to get this menu item type.

MenuItemHistogram¶

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

name	type
type	`str`	Set as `histogram` to get this widget type.
quantity	`str`	deprecated
scale	`str`	options: - `linear` - `log` - `1/2` - `1/4` - `1/8` deprecated
show_input	`int`	Whether to show text input field. default: `True`
showinput	`int`	deprecated
x	`Union[Axis, str]`	Configures the information source and display options for the x-axis.
y	`Union[AxisScale, str]`	Configures the information source and display options for the y-axis.
autorange	`int`	Whether to automatically set the range according to the data limits. default: `False`
n_bins	`int`	Maximum number of histogram bins. Notice that the actual number of bins may be smaller if there are fewer data items available.
nbins	`int`	deprecated
width	`int`	Width of the item, 12 means maximum width. Note that the menu size can be changed. default: `12`
show_header	`int`	Whether to show the header. default: `True`
title	`str`	Custom item title.
show_statistics	`int`	Whether to show the full histogram, or just a range slider. default: `True`

Axis¶

Configuration for a plot axis with limited scaling options.

name	type
title	`str`	Custom title to show for the axis.
unit	`str`	Custom unit used for displaying the values.
quantity	`str`	deprecated
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.
scale	`str`	Defines the axis scaling. Defaults to linear scaling. default: `ScaleEnum.LINEAR` options: - `linear` - `log` - `1/2` - `1/4` - `1/8`

AxisScale¶

Basic configuration for a plot axis.

name	type
scale	`str`	Defines the axis scaling. Defaults to linear scaling. default: `ScaleEnum.LINEAR` options: - `linear` - `log` - `1/2` - `1/4` - `1/8`

MenuItemTerms¶

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

name	type
quantity	`str`	deprecated
search_quantity	`str`	The targeted search quantity.
type	`str`	Set as `terms` to get this type.
scale	`str`	Statistics scaling. default: `ScaleEnum.LINEAR` options: - `linear` - `log` - `1/2` - `1/4` - `1/8`
show_input	`int`	Whether to show text input field. default: `True`
showinput	`int`	deprecated
width	`int`	Width of the item, 12 means maximum width. Note that the menu size can be changed. default: `12`
show_header	`int`	Whether to show the header. default: `True`
title	`str`	Custom item title.
options	`Union[int, Dict[str, MenuItemOption], NoneType]`	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.
n_columns	`int`	The number of columns to use when displaying the options. default: `1`
sort_static	`int`	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	`int`	Whether to show statistics for the options. default: `True`

MenuItemOption¶

Represents an option shown for a filter.

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

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	`int`	Whether to show the header. default: `True`
title	`str`	Custom item title.
type	`str`	Set as `nested_object` to get this menu item type.
path	`str`	Path of the nested object. Typically a section name.
items	`List[Union[MenuItemTerms, MenuItemHistogram, MenuItemPeriodicTable, MenuItemVisibility, MenuItemDefinitions, MenuItemOptimade, MenuItemCustomQuantities]]`	Items that are grouped by this nested object.

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	`int`	Whether to show the header. default: `True`
title	`str`	Custom item title.
type	`str`	Set as `custom_quantities` to get this menu item type.

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	`int`	Whether to show the header. default: `True`
title	`str`	Custom item title.
type	`str`	Set as `definitions` to get this menu item type.

MenuItemPeriodicTable¶

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

name	type
type	`str`	Set as `periodic_table` to get this widget type.
quantity	`str`	deprecated
search_quantity	`str`	The targeted search quantity.
scale	`str`	Statistics scaling. default: `ScaleEnum.LINEAR` options: - `linear` - `log` - `1/2` - `1/4` - `1/8`
width	`int`	Width of the item, 12 means maximum width. Note that the menu size can be changed. default: `12`
show_header	`int`	Whether to show the header. default: `True`
title	`str`	Custom item title.
show_statistics	`int`	Whether to show statistics for the options. default: `True`

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	`int`	Whether to show the header. default: `True`
title	`str`	Custom item title.
type	`str`	Set as `visibility` to get this menu item type.

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`

Dashboard¶

Dashboard configuration.

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

WidgetHistogram¶

Histogram widget configuration.

name	type
type	`str`	Set as `histogram` to get this type.
quantity	`str`	deprecated
scale	`str`	options: - `linear` - `log` - `1/2` - `1/4` - `1/8` deprecated
show_input	`int`	Whether to show text input field. default: `True`
showinput	`int`	deprecated
x	`Union[Axis, str]`	Configures the information source and display options for the x-axis.
y	`Union[AxisScale, str]`	Configures the information source and display options for the y-axis.
autorange	`int`	Whether to automatically set the range according to the data limits. default: `False`
n_bins	`int`	Maximum number of histogram bins. Notice that the actual number of bins may be smaller if there are fewer data items available.
nbins	`int`	deprecated
title	`str`	Custom widget title. If not specified, a widget-specific default title is used.
layout	`Dict[str, Layout]`	Defines widget size and grid positioning for different breakpoints. The following breakpoints are supported: `sm`, `md`, `lg`, `xl` and `xxl`.

Layout¶

Defines widget size and grid positioning for different breakpoints.

name	type
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.
minH	`int`	Minimum height in grid units. default: `3`
minW	`int`	Minimum width in grid units. default: `3`

WidgetPeriodicTableDeprecated¶

Deprecated copy of WidgetPeriodicTable with a misspelled type.

name	type
type	`str`	Set as `periodictable` to get this widget type.
quantity	`str`	deprecated
search_quantity	`str`	The targeted search quantity.
scale	`str`	Statistics scaling. default: `ScaleEnum.LINEAR` options: - `linear` - `log` - `1/2` - `1/4` - `1/8`
title	`str`	Custom widget title. If not specified, a widget-specific default title is used.
layout	`Dict[str, Layout]`	Defines widget size and grid positioning for different breakpoints. The following breakpoints are supported: `sm`, `md`, `lg`, `xl` and `xxl`.

WidgetScatterPlotDeprecated¶

Deprecated copy of WidgetScatterPlot with a misspelled type.

name	type
title	`str`	Custom widget title. If not specified, a widget-specific default title is used.
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	`Union[AxisLimitedScale, str]`	Configures the information source and display options for the x-axis.
y	`Union[AxisLimitedScale, str]`	Configures the information source and display options for the y-axis.
markers	`Markers`	Configures the information source and display options for the markers.
color	`str`	Quantity used for coloring points. Note that this field is deprecated and `markers` should be used instead.
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`
drag_mode	`str`	Action to perform on mouse drag. default: `DragModeEnum.ZOOM`
autorange	`int`	Whether to automatically set the range according to the data limits. default: `True`

Markers¶

Configuration for plot markers.

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

AxisLimitedScale¶

Configuration for a plot axis with limited scaling options.

name	type
title	`str`	Custom title to show for the axis.
unit	`str`	Custom unit used for displaying the values.
quantity	`str`	deprecated
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.
scale	`str`	Defines the axis scaling. Defaults to linear scaling. default: `ScaleEnumPlot.LINEAR` options: - `linear` - `log`

WidgetTerms¶

Terms widget configuration.

name	type
quantity	`str`	deprecated
search_quantity	`str`	The targeted search quantity.
type	`str`	Set as `terms` to get this type.
scale	`str`	Statistics scaling. default: `ScaleEnum.LINEAR` options: - `linear` - `log` - `1/2` - `1/4` - `1/8`
show_input	`int`	Whether to show text input field. default: `True`
showinput	`int`	deprecated
title	`str`	Custom widget title. If not specified, a widget-specific default title is used.
layout	`Dict[str, Layout]`	Defines widget size and grid positioning for different breakpoints. The following breakpoints are supported: `sm`, `md`, `lg`, `xl` and `xxl`.

WidgetScatterPlot¶

Scatter plot widget configuration.

name	type
title	`str`	Custom widget title. If not specified, a widget-specific default title is used.
type	`str`	Set as `scatter_plot` 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	`Union[AxisLimitedScale, str]`	Configures the information source and display options for the x-axis.
y	`Union[AxisLimitedScale, str]`	Configures the information source and display options for the y-axis.
markers	`Markers`	Configures the information source and display options for the markers.
color	`str`	Quantity used for coloring points. Note that this field is deprecated and `markers` should be used instead.
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`
drag_mode	`str`	Action to perform on mouse drag. default: `DragModeEnum.ZOOM`
autorange	`int`	Whether to automatically set the range according to the data limits. default: `True`

WidgetPeriodicTable¶

Periodic table widget configuration.

name	type
type	`str`	Set as `periodic_table` to get this type.
quantity	`str`	deprecated
search_quantity	`str`	The targeted search quantity.
scale	`str`	Statistics scaling. default: `ScaleEnum.LINEAR` options: - `linear` - `log` - `1/2` - `1/4` - `1/8`
title	`str`	Custom widget title. If not specified, a widget-specific default title is used.
layout	`Dict[str, Layout]`	Defines widget size and grid positioning for different breakpoints. The following breakpoints are supported: `sm`, `md`, `lg`, `xl` and `xxl`.

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]`	List of excluded options.

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]`	List of included options. Supports glob/wildcard syntax.
exclude	`List[str]`	List of excluded options. Supports glob/wildcard syntax. Has higher precedence than include.

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: `FilterMenuSizeEnum.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

How to write an app¶

Getting started¶

App entry point¶

Creating an App¶

Loading quantity definitions into an app¶

Menu¶

App reference¶

App¶

Rows¶

RowSelection¶

RowDetails¶

RowActions¶

RowActionURL¶

Column¶

Format¶

Filters¶

Menu¶

MenuItemOptimade¶

MenuItemHistogram¶

Axis¶

AxisScale¶

MenuItemTerms¶

MenuItemOption¶

MenuItemNestedObject¶

MenuItemCustomQuantities¶

MenuItemDefinitions¶

MenuItemPeriodicTable¶

MenuItemVisibility¶

Pagination¶

Dashboard¶

WidgetHistogram¶

Layout¶

WidgetPeriodicTableDeprecated¶

WidgetScatterPlotDeprecated¶

Markers¶

AxisLimitedScale¶

WidgetTerms¶

WidgetScatterPlot¶

WidgetPeriodicTable¶

SearchSyntaxes¶

SearchQuantities¶

FilterMenus¶

FilterMenu¶

FilterMenuActions¶

FilterMenuActionCheckbox¶

Creating an `App`¶