arbok-inspector 0.0.0__py3-none-any.whl

arbok_inspector/widgets/build_xarray_grid.py

@@ -0,0 +1,141 @@
+"""Module to build a grid of xarray plots for a given run."""
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+import math
+import copy
+import plotly.graph_objects as go
+from nicegui import ui, app
+
+from arbok_inspector.helpers.unit_formater import unit_formatter
+from arbok_inspector.helpers.string_formaters import (
+    title_formater, axis_label_formater
+)
+
+if TYPE_CHECKING:
+    from arbok_inspector.classes.dim import Dim
+    from arbok_inspector.classes.run import Run
+    from plotly.graph_objs import Figure
+
+
+def build_xarray_grid() -> None:
+    """
+    Build a grid of xarray plots for the given run.
+
+    Args:
+        run (Run): The Run object containing the data to plot.
+
+    Returns:
+        Figure: The Plotly Figure object containing the grid of plots.
+    """
+    #client = await ui.context.client.connected()
+    run = app.storage.tab["run"]
+    container = app.storage.tab["placeholders"]['plots']
+    container.clear()
+    if run.dim_axis_option['x-axis'] is None:
+        ui.notify(
+            'Please select at least one dimension for the x-axis to display plots.<br>',
+            color = 'red')
+        return
+    ds = run.generate_subset()
+    print(f"Found {len(ds.dims)} dimensions to plot in subset:")
+    fig_dict = {}
+    if len(ds.dims) == 1:
+        create_1d_plot(run, ds, container)
+    elif len(ds.dims) == 2:
+        create_2d_grid(run, ds, container)
+    else:
+        ui.notify(
+            'The selected dimensions result in more than 2D data.<br>'
+            'Please select only 1 or 2 dimensions to plot)',
+            color = 'red')
+        return None
+
+def create_1d_plot(run: Run, ds: xr.Dataset, container: ui.Row) -> None:
+    """
+    Create a 1D plot for the given run and dataset.
+
+    Args:
+        run: The Run object containing the data to plot.
+        ds: The xarray Dataset containing the data.
+        container: The NiceGUI container to hold the plot.
+    """
+    print("Creating 1D plot")
+    x_dim = run.dim_axis_option['x-axis'].name
+    traces = []
+    plot_dict = copy.deepcopy(app.storage.tab["plot_dict_1D"])
+    for key in run.plot_selection:
+        da = ds[key]
+        traces.append({
+            "type": "scatter",
+            "mode": "lines+markers",
+            "name": key.replace("__", "."),
+            "x": da.coords[x_dim].values.tolist(),
+            "y": da.values.tolist(),
+        })
+
+    plot_dict["data"] = traces
+    plot_dict["layout"]["xaxis"]["title"]["text"] = axis_label_formater(ds, x_dim)
+    plot_dict["layout"]["title"]["text"] = title_formater(run)
+
+    with container:
+        fig = go.Figure(plot_dict)
+        ui.plotly(fig).classes('w-full').style('min-height: 400px;')
+        app.storage.tab["plot_dict_1D"] = plot_dict
+
+def create_2d_grid(run, ds, container) -> dict:
+    """
+    Create a grid of 2D plots for the given run and dataset.
+
+    Args:
+        run: The Run object containing the data to plot.
+        ds: The xarray Dataset containing the data.
+        container: The NiceGUI container to hold the plots.
+    """
+    print("Creating 2D grid of plots")
+    if not all([run.dim_axis_option[axis]is not None for axis in ['x-axis', 'y-axis']]):
+        ui.notify(
+            'Please select both x-axis and y-axis dimensions to display 2D plots.<br>'
+            f'x: {run.dim_axis_option["x-axis"]}<br>'
+            f'y: {run.dim_axis_option["y-axis"]}',
+            color = 'red')
+        return
+    keys = run.plot_selection
+    num_plots = len(keys)
+    num_columns = int(min([run.plots_per_column, len(keys)]))
+    num_rows = math.ceil(num_plots / num_columns)
+    pretty_keys = [key.replace("__", ".") for key in keys]
+
+    x_dim = run.dim_axis_option['x-axis'].name
+    y_dim = run.dim_axis_option['y-axis'].name
+    plot_dict = copy.deepcopy(app.storage.tab["plot_dict_2D"])
+    plot_dict["layout"]["xaxis"]["title"]["text"] = axis_label_formater(ds, x_dim)
+    plot_dict["layout"]["yaxis"]["title"]["text"] = axis_label_formater(ds, y_dim)
+    plot_idx = 0
+    def create_2d_plot(plot_idx):
+        key = keys[plot_idx]
+        da = ds[key]
+        if x_dim != da.dims[1]:
+            da = da.transpose(y_dim, x_dim)
+        plot_dict["data"][0]["z"] = da.values.tolist()
+        plot_dict["data"][0]["x"] = da.coords[x_dim].values.tolist()
+        plot_dict["data"][0]["y"] = da.coords[y_dim].values.tolist()
+        plot_dict["layout"]["title"]["text"] = (
+            f"<b>{pretty_keys[plot_idx]}</b><br>{title_formater(run)}")
+        return go.Figure(plot_dict)
+
+    with container:
+        with ui.column().classes('w-full'):
+            for row in range(num_rows):
+                with ui.row().classes('w-full justify-start flex-wrap'):
+                    for col in range(num_columns):
+                        if plot_idx >= num_plots:
+                            break
+                        fig = create_2d_plot(plot_idx)
+                        width_percent = 100 / num_columns - 2
+                        with ui.column().style(
+                            f"width: {width_percent}%; box-sizing: border-box;"
+                            ):
+                            ui.plotly(fig).classes('w-full').style('min-height: 300px;')
+                        plot_idx += 1
+    app.storage.tab["plot_dict_2D"] = plot_dict

arbok_inspector/widgets/build_xarray_html.py

@@ -0,0 +1,57 @@
+"""
+Build and display xarray dataset HTML with dark theme.
+"""
+from __future__ import annotations
+from typing import TYPE_CHECKING
+
+from nicegui import ui, app
+
+if TYPE_CHECKING:
+    from arbok_inspector.classes.run import Run
+    from xarray import Dataset
+
+def build_xarray_html():
+    """Display the xarray dataset in a dark-themed style."""
+    run: Run = app.storage.tab["run"]
+    ds: Dataset = run.full_data_set
+    with ui.column().classes('w-full'):
+        ui.html('''
+        <style>
+        /* Wrap styles to only apply inside this container */
+        .xarray-dark-wrapper {
+            background-color: #343535; /* Tailwind gray-800 */
+            color: #ffffff;
+            padding: 1rem;
+            border-radius: 0.5rem;
+            overflow-x: auto;
+        }
+
+        .xarray-dark-wrapper th,
+        .xarray-dark-wrapper td {
+            color: #d1d5db; /* Tailwind gray-300 */
+            background-color: transparent;
+        }
+
+        .xarray-dark-wrapper .xr-var-name {
+            color: #93c5fd !important; /* Tailwind blue-300 */
+        }
+
+        .xarray-dark-wrapper .xr-var-dims,
+        .xarray-dark-wrapper .xr-var-data {
+            color: #d1d5db !important; /* Light gray */
+        }
+
+        /* Optional: override any inline black text */
+        .xarray-dark-wrapper * {
+            color: inherit !important;
+            background-color: transparent !important;
+        }
+        </style>
+        ''')
+
+        # Wrap the dataset HTML in a div with that class
+        ui.html(f'''
+        <div class="xarray-dark-wrapper">
+        {ds._repr_html_()}
+        </div>
+        ''')

arbok_inspector/widgets/json_plot_settings_dialog.py

@@ -0,0 +1,77 @@
+"""
+Dialog for editing JSON plot settings.
+"""
+import copy
+import json
+import importlib.resources as resources
+
+from nicegui import app, ui
+
+from arbok_inspector.widgets.build_xarray_grid import build_xarray_grid
+
+class JsonPlotSettingsDialog:
+    """
+    Dialog for editing JSON plot settings.
+    """
+    def __init__(self, dimension: str):
+        self.dimension = dimension
+        self.json_editor = None
+        self.dialog = self.build_plot_settings_dialog()
+
+    def build_plot_settings_dialog(self):
+        """
+        Build the dialog for plot settings.
+        """
+        plot_dict = app.storage.tab[self.dimension]
+
+        with ui.dialog() as dialog, ui.card():
+            with ui.column().classes('w_full h-screen'):
+                ui.label('Plot Settings')
+                self.json_editor = ui.json_editor(
+                    properties = {"content": {"json": plot_dict}},
+                ).classes("jse-theme-dark")
+                with ui.row().classes('w-full justify-end'):
+                    ui.button(
+                        text = 'Apply',
+                        on_click=lambda: self.set_editor_data(),
+                        color='green'
+                        )
+                    ui.button(
+                        text = 'Reset',
+                        on_click=lambda: self.reset_plot_settings(),
+                        color='blue'
+                        )
+                    ui.button(
+                        text = 'Close',
+                        color = 'red',
+                        on_click=dialog.close
+                        )
+        return dialog
+
+    def open(self):
+        """Open the dialog."""
+        print("Opening dialog and setting json data")
+        self.dialog.open()
+        self.json_editor.properties['content']['json'] = copy.deepcopy(
+            app.storage.tab[self.dimension])
+        self.json_editor.update()
+
+    async def set_editor_data(self):
+        """Sets json data from the JSON editor to the app storage and rebuilds plots."""
+        json_data = await self.json_editor.run_editor_method('get')
+        json_data = json_data["json"]
+        app.storage.tab[self.dimension] = json_data
+        build_xarray_grid()
+
+    def reset_plot_settings(self):
+        """Reset plot settings to defaults."""
+        if self.dimension == 'plot_dict_1D':
+            with resources.files("arbok_inspector.configurations").joinpath("1d_plot.json").open("r") as f:
+                app.storage.tab["plot_dict_1D"] = json.load(f)
+
+        elif self.dimension == 'plot_dict_2D':
+            with resources.files("arbok_inspector.configurations").joinpath("2d_plot.json").open("r") as f:
+                app.storage.tab["plot_dict_2D"] = json.load(f)
+
+        ui.notify('Reset to default settings', type='positive', position='top-right')
+        build_xarray_grid()

arbok_inspector/widgets/update_day_selecter.py

@@ -0,0 +1,36 @@
+from datetime import datetime
+from nicegui import ui, app
+
+from arbok_inspector.state import inspector
+
+def update_day_selecter(day_grid):
+    offset_hours = app.storage.general["timezone"]
+    inspector.cursor.execute(f"""
+        SELECT 
+            day,
+            MIN(run_timestamp) AS earliest_ts
+        FROM (
+            SELECT 
+                run_timestamp,
+                DATE(datetime(run_timestamp, 'unixepoch', '{offset_hours} hours')) AS day
+            FROM runs
+        )
+        GROUP BY day
+        ORDER BY day;
+    """)
+    day_grid.clear()
+    rows = inspector.cursor.fetchall()
+    row_data = []
+    for day, ts in rows[::-1]:
+        row_data.append({'day': day})
+
+    day_grid.options['rowData'] = row_data
+    day_grid.update()
+    ui.notify(
+        'Day selector updated: \n'
+        f'found {len(row_data)} days',
+        type='positive',
+        multi_line=True,
+        classes='multi-line-notification',
+        position = 'top-right'
+    )

arbok_inspector/widgets/update_run_selecter.py

@@ -0,0 +1,51 @@
+from datetime import datetime, timedelta
+from nicegui import ui, app
+
+from arbok_inspector.state import inspector
+
+def update_run_selecter(run_grid, target_day, run_grid_column_defs):
+    offset_hours = app.storage.general["timezone"]
+    print(target_day)
+    print(offset_hours)
+    inspector.cursor.execute(
+        f"""
+        SELECT *
+        FROM runs
+        WHERE DATE(datetime(run_timestamp, 'unixepoch', '{offset_hours} hours')) = ?
+        ORDER BY run_timestamp;
+        """,
+        (target_day,),
+    )
+    runs = inspector.cursor.fetchall()
+    results = [dict(row) for row in runs]
+
+    run_grid_rows = []
+    columns = [x['field'] for x in run_grid_column_defs]
+    for run in results:
+        print(f'Run: {run.keys()}')
+        run_dict = {}
+        for key in columns:
+            if key in run:
+                value = run[key]
+                if 'time' in key:
+                    if value is not None:
+                        # Apply offset and format nicely
+                        local_dt = datetime.utcfromtimestamp(value) + timedelta(hours=offset_hours)
+                        value = local_dt.strftime('%H:%M:%S')
+                    else:
+                        value = 'N/A'
+                run_dict[key] = value
+        run_grid_rows.insert(0, run_dict)
+
+    run_grid.options['rowData'] = run_grid_rows
+    run_grid.update()
+
+    ui.notify(
+        'Run selector updated: \n'
+        f'found {len(run_grid_rows)} run(s)',
+        type='positive',
+        multi_line=True,
+        classes='multi-line-notification',
+        position = 'top-right'
+    )
+

arbok_inspector-0.0.0.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: arbok-inspector
+Version: 0.0.0
+Summary: Browser based QCoDeS database inspector
+License: MIT
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jupyterlab>=4.4.8
+Requires-Dist: nicegui>=2.24.2
+Requires-Dist: nodejs>=0.1.1
+Requires-Dist: plotly>=6.3.0
+Requires-Dist: qcodes>=0.53.0
+Requires-Dist: xarray>=2025.9.0
+Dynamic: license-file
+
+# arbok_inspector 🐍
+arbok_inspector is an browser based inspection and visualization utility for QCoDeS measurement
+databases.
+It provides a lightweight GUI and CLI to browse runs and visualize data. 
+
+## Features 🔎
+The most commonly used used tool to visualize QCoDeS databases is
+[plottr](https://github.com/toolsforexperiments/plottr).
+Plottr is a great tool to get started, but struggles with increasing abounts of data.
+
+This is how arbok_inspector streamlines your data inspection:
+- Fast browsing of measurement runs and their metadata
+- Written with [nicegui](https://nicegui.io/) acting as a [tailwind](https://tailwindcss.com/) wrapper
+- Browser based approach ensures cross system compatibily
+- Selected runs are opened in a new tab and run on a separate thread
+  - this avoids blocking the entire application when loading big datasets
+- plotting backend is plotly which natively returns html
+  - plotly plot customization is declarative and can therefore be tweaked in a simple json editor without implementing each customization by hand
+- runs are only loaded on demand
+  - startup time in plottr can be several minutes for large databases
+  - SQL queries load only the given days upon database selection, only loads respective runs once day is selected
+
+## Installation 📲
+
+From pypi install using pip in your environment:
+```bash
+pip install arbok-inspector
+```
+Even better if you are using uv, a uv.lock file is included!
+Launch from CLI:
+```bash
+arbok-inspector
+```
+
+## Project layout
+
+- `main.py` — app entrypoint and startup logic
+- `state.py` — application state & database handling
+- `pages/` — NiceGUI pages (database browser, run view, greeter, ...)
+- `widgets/` — reusable UI widgets (grid builders, selectors, dialogs)
+- `analysis/` — analysis and data-prep utilities
+- `classes/` — small domain objects used across the app
+- `helpers/` — formatting and utility helpers
+
+Development & testing 🛠️
+
+Clone this git repository and navigate into it.
+Use an editable install for local development to pick up changes immediately
+```bash
+pip install -e .
+```
+
+To launch the app in editable mode launch from dev.py file:
+```bash
+python -m arbok_inspector/dev.py
+```
+Contributing & help 🙌
+
+Contributions, bug reports, and small feature requests are welcome. If you want to add a visualization or a new page, use `pages/` and `widgets/` for examples of how UI components are composed. When opening a PR, please keep changes focused and include a short description of how to exercise the change locally.
+
+License
+
+See the `LICENSE` file in the project root for license details.
+
+Notes & tips
+
+- For exact runtime dependencies check `pyproject.toml` — prefer using that manifest (and a virtual environment) for reproducible installs.
+- If you want me to add a short walkthrough for common tasks (open a run, plot data, export CSV), tell me which task you'd like first and I can add a step-by-step example here. 📘
+

arbok_inspector-0.0.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+arbok_inspector/__init__.py,sha256=KEDfR87-199tMUCeufnGkPswwjGivDOIwF5w1_cZ6ZM,53
+arbok_inspector/cli.py,sha256=G0gIa4ByfQTMmeXCyLjnsmke5EEXs6DYuR5eVbhszXo,96
+arbok_inspector/dev.py,sha256=F19xar7hlR-fG1QTxGyXSwT5r80x52vZIlZDaimPc4E,413
+arbok_inspector/main.py,sha256=oQEypBKdD5jLARiXmz2u1_Op5OIos0BTqkM--oLU3lo,300
+arbok_inspector/state.py,sha256=FDsnqUq8_oGecTvFgQoVB0-JMgFtmgccsxPX7jYX74A,2295
+arbok_inspector/test_main.py,sha256=brV3O2ZVyuUrqnUmZr3U-tH6VY7PQxthNiElgIax_x0,1955
+arbok_inspector/analysis/analysis_base.py,sha256=7uChxCyoiHazQBId9DHgXZtk166fZshr-E-eF-SNw5Q,933
+arbok_inspector/analysis/prepare_data.py,sha256=DedVxlbTNDppMlNBwt8kN4cWk0_Nnyx9J442GqG1Asw,4393
+arbok_inspector/classes/dim.py,sha256=bPxVNn23ohZ9CVePmiqLUFABbh6iKiuN_dMAxIcqIG0,750
+arbok_inspector/classes/run.py,sha256=i50RhllM-fXanTNRLxBdcpBCkfiqjrNvupDSv4vwg2s,9895
+arbok_inspector/helpers/string_formaters.py,sha256=q8ldfHRlACWKBhjUpuwbDthbUBcP6q8Z9qaRLdiwxJ4,1000
+arbok_inspector/helpers/unit_formater.py,sha256=7h77hqPoLLBil3Z1n72T1iLv3Du84Qt0iZ3B0tzZtaY,1163
+arbok_inspector/pages/__init__.py,sha256=3ZbSQftX4VYoWU6DsAEZvXl89PLjwn89Xtxqwwxy8vc,88
+arbok_inspector/pages/database_browser.py,sha256=22KbzJwKSIPoLnk6Li6i0WYqjL713nH4Q222XDWjCsg,6793
+arbok_inspector/pages/greeter.py,sha256=O1QpLU9nMAOjG0kKNCVMPX00fnUlmoZzOP6Pdt_2H0g,1380
+arbok_inspector/pages/run_view.py,sha256=yEV7k_OdgT61PemMK8l1lDlqtzYNu8-Qguer0Iw5uMk,10980
+arbok_inspector/widgets/build_xarray_grid.py,sha256=TgFYWtFp2DqBI5neP_WqXkhmwTj6Hl6UqzIqcW_Xtsk,5409
+arbok_inspector/widgets/build_xarray_html.py,sha256=NaS8YKidcXOPhSY-QHraHS_Hag8cCqizrtaDJ__WwH0,1679
+arbok_inspector/widgets/json_plot_settings_dialog.py,sha256=tUjx9TqDHhKsT9IGZfw61zuzjY1BqJH00s_gtR5kzio,2913
+arbok_inspector/widgets/update_day_selecter.py,sha256=z5HVUVnxSqtZfoaK4lzMh5J16o9RoEZJwDvnwS-ewZ8,1011
+arbok_inspector/widgets/update_run_selecter.py,sha256=M7hvy80kXO2NA83ly3QeeMQsTfdslit--2K3CbkHrQc,1639
+arbok_inspector-0.0.0.dist-info/licenses/LICENSE,sha256=ZEqWKVZ2qROesXQcWpU2JTdY2yk6OkWR70H5771iIGc,1070
+arbok_inspector-0.0.0.dist-info/METADATA,sha256=LkbxLpru_KRa0pURJZ_Yk4kJ6NsdMPYeDGYI6flU4p0,3426
+arbok_inspector-0.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+arbok_inspector-0.0.0.dist-info/entry_points.txt,sha256=i1gVPzcOgNNzSly4zUqJ_z38eiUrMEOCNgtH1dr55zE,64
+arbok_inspector-0.0.0.dist-info/top_level.txt,sha256=-jLIWMq05sffOZ-lCiP8dZgVga7Upp95QsBgoE718oE,16
+arbok_inspector-0.0.0.dist-info/RECORD,,

arbok_inspector-0.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

arbok_inspector-0.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+arbok-inspector = arbok_inspector.main:ui.run

arbok_inspector-0.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andreas Nickl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

arbok_inspector-0.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+arbok_inspector