{"id":16195173,"url":"https://github.com/bdice/signac-dashboard","last_synced_at":"2025-04-07T15:54:15.836Z","repository":{"id":70397268,"uuid":"140858483","full_name":"bdice/signac-dashboard","owner":"bdice","description":"Data visualization, analysis, and dashboard monitoring tool for data managed in a signac project.","archived":false,"fork":false,"pushed_at":"2018-07-13T14:42:33.000Z","size":748,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-13T18:35:33.601Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://bitbucket.org/glotzer/signac-dashboard/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bdice.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-13T14:41:28.000Z","updated_at":"2018-07-13T15:19:48.000Z","dependencies_parsed_at":"2023-05-14T02:15:33.858Z","dependency_job_id":null,"html_url":"https://github.com/bdice/signac-dashboard","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdice%2Fsignac-dashboard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdice%2Fsignac-dashboard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdice%2Fsignac-dashboard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bdice%2Fsignac-dashboard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bdice","download_url":"https://codeload.github.com/bdice/signac-dashboard/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247685594,"owners_count":20979084,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-10T08:26:30.772Z","updated_at":"2025-04-07T15:54:15.817Z","avatar_url":"https://github.com/bdice.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# signac-dashboard: visual data management and analysis\n\n## About\n\nData visualization, analysis, and \"dashboard\" monitoring tool as part of the [signac framework](https://glotzerlab.engin.umich.edu/signac).\nThe signac-dashboard interface allows users to rapidly view data managed in a [signac project](http://signac.readthedocs.io/en/latest/projects.html).\n\n*The software is currently in an early development stage.*\n\n## Maintainers\n\n  * Bradley Dice (bdice@umich.edu)\n\n## Installation\n\nThe **signac-dashboard** app requires at least Python version 3.4!\nTo install this package, first clone the repository and install its submodules.\n```bash\n$ git clone https://bitbucket.org/glotzer/signac-dashboard.git\n$ cd signac-dashboard\n$ git submodule update --init --recursive\n```\nand then install using pip:\n```bash\n$ pip install .\n```\n\n## Usage\n\nYou can start a dashboard to visualize *signac* project data in the browser, by importing the `Dashboard` class and calling its run function.\n\n### Start a Dashboard\n\nThe code below will open a dashboard for an newly-initialized (empty) project, with no jobs and one module loaded.\n\n```python\n#!/usr/bin/env python3\nfrom signac_dashboard import Dashboard\nfrom signac_dashboard.modules import ImageViewer\n\n\nif __name__ == '__main__':\n    dashboard = Dashboard(modules=[ImageViewer()])\n    dashboard.run(host='localhost', port=8888)\n```\n\n### Specifying a custom job title\n\nBy creating a class that inherits from `Dashboard` (which we'll call `MyDashboard`), we can begin to customize some of the functions that make up the dashboard, like `job_title(job)`, which gives a human-readable title to each job.\n\n```python\nclass MyDashboard(Dashboard):\n\n    def job_title(self, job):\n        return 'Concentration(A) = {}'.format(job.sp['conc_A'])\n\nMyDashboard().run()\n```\n\n## Dissecting the Dashboard Structure\n\n- *Jobs* are how signac manages data. Each job has a statepoint (which contains job metadata) and a document (for persistent storage of key-value pairs). Jobs can be displayed in *list view* or *grid view*. The list view provides quick descriptions and status information from many jobs, while the grid view is intended to show text and media content from one or more jobs.\n- *Templates* provide the HTML structure of the dashboard's pages, written in Jinja template syntax for rendering content on the server\n- *Modules* are server-side Python code that interface with your signac data to display content. Generally, a module will render content from a specific *job* into a *card template*.\n- *Cards* are a type of template that is shown in *grid view* and contains content rendered by a *module*.\n\n## Included Modules\n\nDefining a module requires a *name* for display, a *context* to determine when the module should be shown (currently only `'JobContext'` is supported), and a *template* (written in HTML/Jinja-compatible syntax) where the content will be rendered. An optional `enabled` argument can be set to `False` to disable the module until it is selected by the user. A module must be a subclass of `Module` and define the function `get_cards()` which returns an array of dictionaries with properties `'name'` and `'content'`, like so:\n\n```python\nclass MyModule(Module):\n\n    def get_cards(self):\n        return [{'name': 'My Module', 'content': render_template('path/to/template.html')}]\n```\n\n### Statepoint Parameters\n\nThe `StatepointList` module shows the key-value pairs in the statepoint.\n\n```python\nfrom signac_dashboard.modules.statepoint_list import StatepointList\nsp_mod = StatepointList()\n```\n\n### Job Document\n\nThe `DocumentList` module shows the key-value pairs in the job document, with long values optionally truncated (default is no truncation).\n\n```python\nfrom signac_dashboard.modules.document_list import DocumentList\ndoc_mod = DocumentList(max_chars=140)  # Output will be truncated to one tweet length\n```\n\n### File List\n\nThe `FileList` module shows a listing of the job's workspace directory with links to each file. This can be very slow since it has to read the disk for every job displayed, use with caution in large signac projects.\n\n```python\nfrom signac_dashboard.modules.file_list import FileList\nfile_mod = FileList(enabled=False)  # Recommended to disable this module by default\n```\n\n### Image Viewer\n\nThe `ImageViewer` module displays images in any format that works with a standard HTML `\u003cimg\u003e` tag. The module defaults to showing all images of PNG, JPG, or GIF types. A filename or glob can be defined to select specific filenames. Multiple Image Viewer modules can be defined with different filenames or globs to enable/disable cards individually.\n\n```python\nfrom signac_dashboard.modules.image_viewer import ImageViewer\nimg_mod = ImageViewer()  # Shows all PNG/JPG/GIF images\nimg_mod = ImageViewer(name='Bond Order Diagram', img_globs=['bod.png'])\n```\n\n### Video Viewer\n\nThe `VideoViewer` module displays videos using a standard HTML `\u003cvideo\u003e` tag. The module defaults to showing all videos of MP4 or M4V types. A filename or glob can be defined to select specific filenames, which may be of any format supported by your browser with the `\u003cvideo\u003e` tag. 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 Video Viewer modules can be defined with different filenames or globs to enable/disable cards individually.\n\n```python\nfrom signac_dashboard.modules.video_viewer import VideoViewer\nvideo_mod = VideoViewer()  # Shows all MP4/M4V videos\nvideo_mod = VideoViewer(name='Cool Science Video',\n                        video_globs=['cool_science.mp4'],\n                        poster='cool_science_thumbnail.jpg',\n                        preload='none')\n```\n\n### Notes\n\nThe `Notes` module uses the `'notes'` key in the job document to store plain text, perhaps human-readable descriptions of a job that may be useful in later analysis.\n\n```python\nfrom signac_dashboard.modules.notes import Notes\nnotes_mod = Notes()\n```\n\n## Searching jobs\n\nThe search bar accepts JSON-formatted queries in the same way as the `signac find` command-line tool. For example, using the query `{\"key\": \"value\"}` will return all jobs where the job statepoint `key` is set to `value`. To search jobs by their document key-value pairs, use `doc:` before the JSON-formatted query, like `doc:{\"key\": \"value\"}`.\n\n\n## Tips for Developers\n\nDuring continuous integration, the code is checked with `flake8`. Run the following commands to [set up a pre-commit hook](http://flake8.pycqa.org/en/latest/user/using-hooks.html) that will ensure your code is compliant before pushing.\n\n```bash\nflake8 --install-hook git\ngit config --bool flake8.strict true\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbdice%2Fsignac-dashboard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbdice%2Fsignac-dashboard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbdice%2Fsignac-dashboard/lists"}