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 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,
    Layout,
    Menu,
    MenuItemPeriodicTable,
    MenuItemHistogram,
    MenuItemTerms,
    SearchQuantities,
    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.',
        # 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': [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=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(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 by using the SearchQuantities field in the app config. This option supports a wildcard/glob syntax for including/excluding certain search quantities. For example, to include all search quantities 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']
)

Using loaded search quantity definitions

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.

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.

For example, one could configure the results table to show a new column using one of the search quantities with:

from nomad.config.models.ui import Column

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

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"]
}

Menu

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, MenuItemTerms, MenuItemHistogram

# 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.
• MenuItemOptimade: Field for entering OPTIMADE queries.
• 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.

Dashboard

The Dashboard field controls the content of the main search interface window. Different widgets can be added which contain terms or numerical information and can be controlled in size and position. There are 4 different types of Widgets: WidgetTerms, WidgetHistogram, WidgetScatterplot and WidgetPeriodicTable

dashboard = Dashboard(
    widgets=[
        WidgetPeriodicTable(
            title='Elements of the material',
            layout={
                'lg': Layout(h=8, minH=8, minW=12, w=12, x=0, y=0),
            },
            search_quantity='results.material.elements',
            scale='linear',
        ),
        WidgetTerms(
            title='Widget Terms Title',
            layout={
                'lg': Layout(h=8, minH=3, minW=3, w=6, x=12, y=0),
            },
            search_quantity=f'data.mysection.myquantity#{schema}',
            showinput=True,
            scale='linear',
        ),
        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(minH=3, minW=3, h=8, w=12, y=8, x=0)},
        ),
        WidgetScatterPlot(
            title='Scatterplot title',
            autorange=True,
            layout={
                'lg': Layout(h=8, minH=3, minW=8, w=12, x=12, y=8),
            },
            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
        ),
    ]
)

App reference

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.

Dashboard

Dashboard configuration.

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

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.

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

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. Notice that the actual 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.

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

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.

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

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

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.

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.

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.

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

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.

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.

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.

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.

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. Notice that the actual number of bins may be smaller if there are fewer data items available.
nbins	int | None	deprecated
title	str | None	Custom item title.

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.

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.

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.

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.