API Reference

This is the API for the signac-dashboard application.

The Dashboard

Attributes

`Dashboard.add_url`(import_name[, url_rules, ...])	Add a route to the dashboard.
`Dashboard.job_sorter`(job)	Override this method for custom job sorting.
`Dashboard.job_subtitle`(job)	Override this method for custom job subtitles.
`Dashboard.job_title`(job)	Override this method for custom job titles.
`Dashboard.main`([command_args])	Run the command line interface.
`Dashboard.register_module_asset`(asset)	Register an asset required by a dashboard module.
`Dashboard.run`(args, *kwargs)	Run the dashboard webserver.
`Dashboard.update_cache`()	Clear project and dashboard server caches.

class signac_dashboard.Dashboard(config={}, project=None, modules=[])[source]

A dashboard application to display a signac.Project.

The Dashboard class is designed to be used as a base class for a child class such as MyDashboard which can be customized and launched via its command line interface (CLI). The CLI is invoked by calling main() on an instance of this class.

Configuration options: The config dictionary recognizes the following options:

HOST: Sets binding address (default: localhost).
PORT: Sets port to listen on (default: 8888).
DEBUG: Enables debug mode if True (default: False).
PROFILE: Enables the profiler werkzeug.middleware.profiler.ProfilerMiddleware if True (default: False).
PER_PAGE: Maximum number of jobs to show per page (default: 24).
CARDS_PER_ROW: Cards to show per row in the desktop view. Must be a factor of 12 (default: 3).
ACCESS_TOKEN: The access token required to login to the dashboard. Set to None to disable authentication (not recommended on multi-user systems).
SECRET_KEY: This must be specified to run via WSGI with multiple workers, so that sessions remain intact. See the Flask docs for more information.
ALLOW_WHERE: If True, search queries can include $where statements, which potentially allows arbitrary code execution from user input. Caution: This should only be enabled in trusted environments, never on a publicly-accessible server (default: False).

Parameters:

config (dict) – Configuration dictionary (default: {}).
project (signac.Project) – signac project (default: None, autodetected).
modules (list) – List of Module instances to display.

add_url(import_name, url_rules=[], import_file='signac_dashboard', **kwargs)[source]

Add a route to the dashboard.

This method allows custom view functions to be triggered for specified routes. These view functions are imported lazily, when their route is triggered. For example, write a file my_views.py:

def my_custom_view(dashboard):
    return 'This is a custom message.'

Then, in dashboard.py:

from signac_dashboard import Dashboard

class MyDashboard(Dashboard):
    pass

if __name__ == '__main__':
    dashboard = MyDashboard()
    dashboard.add_url('my_custom_view', url_rules=['/custom-url'],
                      import_file='my_views')
    dashboard.main()

Finally, launching the dashboard with python dashboard.py run and navigating to /custom-url will show the custom message. This can be used in conjunction with user-provided jinja templates and the method flask.render_template() for extending dashboard functionality.

Parameters:

import_name (str) – The view function name to be imported.
url_rules (list) – A list of URL rules, see flask.Flask.add_url_rule().
import_file (str) – The module from which to import (default: 'signac_dashboard').
\**kwargs – Additional keyword arguments to pass to flask.Flask.add_url_rule().

job_sorter(job)[source]

Override this method for custom job sorting.

This method returns a key that can be compared to sort jobs. By default, the sorting key is based on Dashboard.job_title(), with natural sorting of numbers. Good examples of such keys are strings or tuples of properties that should be used to sort.

Parameters:: job (signac.job.Job) – The job being sorted.
Returns:: Key for sorting.
Return type:: any comparable type

job_subtitle(job)[source]

Override this method for custom job subtitles.

This method generates job subtitles. By default, the subtitle is a minimal unique substring of the job id.

Parameters:: job (signac.job.Job) – The job being subtitled.
Returns:: Subtitle to be displayed.
Return type:: str

job_title(job)[source]

Override this method for custom job titles.

This method generates job titles. By default, the title is a pretty (but verbose) form of the job state point, based on the project schema.

Parameters:: job (signac.job.Job) – The job being titled.
Returns:: Title to be displayed.
Return type:: str

main(command_args=None)[source]

Run the command line interface.

Call this function to use signac-dashboard from its command line interface. For example, save this script as dashboard.py:

from signac_dashboard import Dashboard

class MyDashboard(Dashboard):
    pass

if __name__ == '__main__':
    MyDashboard().main()

Then the dashboard can be launched with:

python dashboard.py run

Parameters:: command_args (list) – List of CLI arguments to pass, e.g. ["--debug", "--port", "8889"] (default: None).

register_module_asset(asset)[source]

Register an asset required by a dashboard module.

Some modules require special scripts or stylesheets, like the signac_dashboard.modules.Notes module. It is recommended to use a namespace for each module that matches the example below:

dashboard.register_module_asset({
    'file': 'templates/my-module/js/my-script.js',
    'url': '/module/my-module/js/my-script.js'
})

Parameters:: asset (dict) – A dictionary with keys 'file' and 'url'.

run(*args, **kwargs)[source]

Run the dashboard webserver.

Use main() instead of this method for the command-line interface. Arguments to this function are passed directly to flask.Flask.run().

update_cache()[source]

Clear project and dashboard server caches.

The dashboard relies on caching for performance. If the data space is altered, this method may need to be called before the dashboard reflects those changes.

Dashboard Modules

`Module`(name, context, template[, enabled])	Base class for modules, the building blocks of the dashboard.
`modules.DocumentEditor`([name, context, template])	Provides an interface to edit the job document.
`modules.DocumentList`([name, context, ...])	Displays the job or project document.
`modules.FileList`([name, context, template, ...])	Lists files in the job directory with download links.
`modules.FlowStatus`([name, context, ...])	Show job labels from a `flow.FlowProject`.
`modules.ImageViewer`([name, context, ...])	Displays images that match a glob.
`modules.Notes`([name, context, template, key])	Displays a text box that is synced to the job document.
`modules.Schema`([name, context, template, ...])	Displays the project schema.
`modules.StatepointList`([name, context, template])	Displays the job state point.
`modules.TextDisplay`([name, context, ...])	Render custom text or Markdown in a card.
`modules.VideoViewer`([name, context, ...])	Displays videos that match a glob.

class signac_dashboard.Module(name, context, template, enabled=True)[source]

Base class for modules, the building blocks of the dashboard.

A module turns select information from the job directory or project directory into cards displayed on the dashboard. The cards pull content from the job directory or project directory depending on whether the module context is 'JobContext' or 'ProjectContext'.

Parameters:

name (str) – Name of the module for card titles.
context (str) – Context in which this module’s cards will be displayed, either 'JobContext' or 'ProjectContext'.
template (str) – Path to a template file for this module’s cards (e.g. cards/my_module.html, without the template directory prefix templates/).
enabled (bool) – Whether the module’s cards will be displayed. (default: True)

Custom modules: User-defined module classes should be a subclass of Module and define the function get_cards(). Template files are written in HTML/Jinja-compatible syntax. See this example.

Module assets: If a module requires scripts or stylesheets to be included for its content to be rendered, they must be handled by the callback register(). For example, a module inheriting from the base signac_dashboard.Module class may implement this by overriding the default method as follows:

def register(self, dashboard):
    assets = ['js/my-script.js', 'css/my-style.css']
    for asset in assets:
        dashboard.register_module_asset({
            'file': 'templates/my-module/{}'.format(asset),
            'url': '/module/my-module/{}'.format(asset)
        })

Then, when the module is active, its assets will be included and a route will be created that returns the asset file.

Module routes: The callback register() allows modules to implement custom routes, such as methods that should be triggered by POST requests or custom APIs. For example, a module inheriting from the base signac_dashboard.Module class may implement this by overriding the default method as follows:

def register(self, dashboard):
    @dashboard.app.route('/module/my-module/update', methods=['POST'])
    @flask_login.login_required
    def my_module_update():
        # Perform update
        return "Saved."

disable()[source]: Disable this module.

enable()[source]: Enable this module.

get_cards()[source]

Return this module’s cards for rendering.

The cards are returned as a list of dictionaries with keys 'name' and 'content'.

Returns:: List of module cards.
Return type:: list

register(dashboard)[source]

Register this module with the dashboard.

This method is a callback used to register assets and routes, as well as any other initialization that accesses or modifies the dashboard.

Parameters:: dashboard (signac_dashboard.Dashboard) – The dashboard invoking this callback method.

toggle()[source]: Toggle this module.

class signac_dashboard.modules.DocumentEditor(name='Document Editor', context='JobContext', template='cards/document_editor.html', **kwargs)[source]

Provides an interface to edit the job document.

This module shows keys in the job document with a form that allows users to edit their contents. When saving, the edited strings are parsed into JSON-compatible Python data structures (e.g., list and dict). Job document keys beginning with an underscore _ are treated as private and are not displayed.

Parameters:: context (str) – Supports 'JobContext'.

class signac_dashboard.modules.DocumentList(name=None, context='JobContext', template='cards/escaped_dict_display.html', max_chars=None, **kwargs)[source]

Displays the job or project document.

Long values can be optionally truncated.

Parameters:

context (str) – Supports 'JobContext' and 'ProjectContext'.
max_chars (int) – Truncation length for document values (default: None).

class signac_dashboard.modules.FileList(name='File List', context='JobContext', template='cards/file_list.html', prefix_jobid=True, **kwargs)[source]

Lists files in the job directory with download links.

Parameters:

context (str) – Supports 'JobContext'.
prefix_jobid (bool) – Whether filenames should be prefixed with the job id when being downloaded (default: True).

class signac_dashboard.modules.FlowStatus(name='Flow Status', context='JobContext', template='cards/flow_status.html', project_module='project', project_class='Project', **kwargs)[source]

Show job labels from a flow.FlowProject.

This module displays a card with labels from flow.FlowProject.labels(). The user must provide an instance of flow.FlowProject to the dashboard constructor. Example:

from project import Project  # Project is a FlowProject with labels
from signac_dashboard import Dashboard

if __name__ == '__main__':
    Dashboard(project=Project()).main()

Parameters:: context (str) – Supports 'JobContext'.

class signac_dashboard.modules.ImageViewer(name='Image Viewer', context='JobContext', template='cards/image_viewer.html', img_globs=('*.png', '*.jpg', '*.gif', '*.svg'), sort_key=None, **kwargs)[source]

Displays images that match a glob.

The ImageViewer module can display images in any format that works with a standard <img> tag. The module defaults to showing all images of PNG, JPG, GIF, and SVG types in the job or project directory. A filename or glob can be defined to select specific filenames. Each matching file yields a card.

Multiple ImageViewer modules can be defined with different filenames or globs to enable/disable cards for each image or image group.

Example:

from signac_dashboard.modules import ImageViewer
img_mod = ImageViewer()  # Show all PNG/JPG/GIF/SVG images
img_mod = ImageViewer(name='Bond Order Diagram', img_globs=['bod.png'])
img_mod = ImageViewer(context="ProjectContext",
                      img_globs=['/gallery/*.png'])  # search subdirectory of project path

Parameters:

context (str) – Supports 'JobContext' and 'ProjectContext'.
img_globs (list) – A list of glob expressions or exact filenames, relative to the job or project directory, to be displayed (default: ['*.png', '*.jpg', '*.gif', '*.svg']).
sort_key (callable) – Key to sort the image files, passed internally to sorted.

class signac_dashboard.modules.Navigator(name='Navigator', context='JobContext', template='cards/navigator.html', max_chars=6, **kwargs)[source]

Displays links to jobs differing in one state point parameter.

This module uses the project schema to determine which state points vary, then displays links to jobs with adjacent values of these parameters in a table. Schema detection can be slow on slow file systems, so this module caches the project schema. Therefore, this module may not update if the signac project changes while the signac-dashboard is running.

Parameters:

context (str) – Supports 'JobContext'
max_chars (int) – Truncation length of state point values (default: 6).

class signac_dashboard.modules.Notes(name='Notes', context='JobContext', template='cards/notes.html', key='notes', **kwargs)[source]

Displays a text box that is synced to the job document.

The contents of the text box are saved to job.document['notes']. The Notes module can be used to annotate a large data space with tags or human-readable descriptions for post-processing, parsing, or searching.

Parameters:

context (str) – Supports 'JobContext'.
key (str) – Document key to display and update (default: 'notes').

class signac_dashboard.modules.Schema(name='Project Schema', context='ProjectContext', template='cards/escaped_dict_display.html', max_chars=None, exclude_const=False, subset=None, **kwargs)[source]

Displays the project schema.

Long values can be optionally truncated.

Parameters:

context (str) – Supports 'ProjectContext'.
max_chars (int) – Truncation length for schema values (default: None).
exclude_const (bool) – Exclude all state point parameters that are shared by all jobs in this project (default: False).
subset – A sequence of jobs or job ids specifying a subset over which the state point schema should be detected (default: None).

class signac_dashboard.modules.StatepointList(name='Statepoint Parameters', context='JobContext', template='cards/statepoint_list.html', **kwargs)[source]

Displays the job state point.

Parameters:: context (str) – Supports 'JobContext'.

class signac_dashboard.modules.TextDisplay(name='Text Display', context='JobContext', message=<function TextDisplay.<lambda>>, markdown=False, **kwargs)[source]

Render custom text or Markdown in a card.

This module calls a user-provided function to display text or Markdown content in a card. Rendering Markdown requires the markdown library to be installed. Example:

from signac_dashboard.modules import TextDisplay

def my_text(job):
    return f"This job id is {job}."

modules = [TextDisplay(message=my_text)]

Parameters:

context (str) – Supports 'JobContext' and 'ProjectContext'.
message (callable) – A callable accepting one argument of type signac.job.Job or signac.Project and returning text or Markdown content.
markdown (bool) – Enables Markdown rendering if True (default: False).

class signac_dashboard.modules.VideoViewer(name='Video Viewer', context='JobContext', template='cards/video_viewer.html', video_globs=('*.mp4', '*.m4v'), preload='none', poster=None, sort_key=None, **kwargs)[source]

Displays videos that match a glob.

The VideoViewer module displays videos using an HTML <video> tag. The module defaults to showing all videos of MP4 or M4V types in the job or project directory. A filename or glob can be defined to select specific filenames, which may be of any format supported by your browser with the <video> tag. Each matching file yields a card.

A “poster” can be defined, which shows a thumbnail with that filename before the video is started. Videos do not preload by default since file sizes can be large and there may be many videos on a page. To enable preloading, use the argument preload='auto' or preload='metadata'.

Multiple VideoViewer modules can be defined with different filenames or globs to enable/disable cards individually.

Example:

from signac_dashboard.modules import VideoViewer
video_mod = VideoViewer()  # Shows all MP4/M4V videos
video_mod = VideoViewer(name='Cool Science Video',
                        context="ProjectContext",
                        video_globs=['cool_science.mp4'],
                        poster='cool_science_thumbnail.jpg',
                        preload='none')

Parameters:

context (str) – Supports 'JobContext' and 'ProjectContext'.
video_globs (list) – A list of glob expressions or exact filenames, relative to the job or project directory, to be displayed (default: ['*.mp4', '*.m4v']).
preload (str) – Option for preloading videos, one of 'auto', 'metadata', or 'none' (default: 'none').
poster (str) – A path in the job directory or project directory for a poster image to be shown before a video begins playback (default: None).
sort_key (callable) – Key to sort the video files, passed internally to sorted.