mesofield 0.3.2b0__py3-none-any.whl

mesofield/cli/__init__.py

@@ -0,0 +1,57 @@
+"""Mesofield command-line interface.
+
+The CLI is organized into a small set of day-to-day acquisition commands at
+the top level, plus four command groups:
+
+\b
+    mesofield launch | init | playback | viewer   acquisition workflow
+    mesofield rig ...        manage canonical hardware.yaml rigs
+    mesofield datakit ...    build / explore / profile / inspect datasets
+    mesofield process ...    batch-process & convert recorded data
+    mesofield tools ...      setup, export, and diagnostic utilities
+
+Run ``mesofield <cmd> --help`` (or ``mesofield <group> --help``) for details.
+"""
+
+from __future__ import annotations
+
+import os
+
+import click
+
+# Disable debugger warning about the use of frozen modules
+os.environ.setdefault("PYDEVD_DISABLE_FILE_VALIDATION", "1")
+
+from ._richhelp import RichGroup
+from .acquire import init, launch, playback, viewer
+from .datakit import datakit
+from .process import process
+from .rig import rig
+from .tools import tools
+
+
+@click.group(cls=RichGroup)
+def cli():
+    """Mesofield Command Line Interface."""
+
+
+# Set the free-standing acquisition commands (launch/init/playback/viewer)
+# apart from the command groups in the help tree.
+cli.loose_command_heading = "acquisition workflow"
+
+
+# --- Top-level acquisition commands ---
+cli.add_command(launch)
+cli.add_command(init)
+cli.add_command(playback)
+cli.add_command(viewer)
+
+# --- Command groups ---
+cli.add_command(rig)
+cli.add_command(datakit)
+cli.add_command(process)
+cli.add_command(tools)
+
+
+if __name__ == "__main__":
+    cli()

mesofield/cli/_richhelp.py

@@ -0,0 +1,100 @@
+"""Rich-rendered help for the Mesofield CLI.
+
+:class:`RichGroup` is a drop-in :class:`click.Group` that replaces the plain
+"Commands:" listing with a colored ``rich`` tree, so the command groupings
+are visible at a glance. Everything else (usage line, description, options)
+is left to Click's native formatter.
+
+Subgroups render their own commands as a flat tree; the root group nests one
+level deep so ``mesofield --help`` shows the whole map. Degrades gracefully
+to Click's default rendering if ``rich`` is unavailable or output is being
+captured oddly.
+"""
+
+from __future__ import annotations
+
+import io
+import shutil
+import sys
+
+import click
+
+
+def _short(cmd: click.Command) -> str:
+    return cmd.get_short_help_str(limit=70)
+
+
+def _add_leaves(node, items) -> None:
+    """Add ``(name, command)`` leaves to ``node``, name-padded for alignment."""
+    width = max((len(name) for name, _ in items), default=0)
+    for name, cmd in items:
+        node.add(f"[green]{name.ljust(width)}[/green]   [dim]{_short(cmd)}[/dim]")
+
+
+class RichGroup(click.Group):
+    """Click group that lists its subcommands as a ``rich`` tree.
+
+    Set :attr:`loose_command_heading` on an instance to bucket non-group
+    commands under a labeled node (used by the root group to set the
+    free-standing acquisition commands apart from the command groups).
+    """
+
+    loose_command_heading: str | None = None
+
+    def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        commands = []
+        for name in self.list_commands(ctx):
+            cmd = self.get_command(ctx, name)
+            if cmd is None or getattr(cmd, "hidden", False):
+                continue
+            commands.append((name, cmd))
+        if not commands:
+            return
+
+        try:
+            rendered = self._render_tree(ctx, commands)
+        except Exception:
+            super().format_commands(ctx, formatter)
+            return
+
+        formatter.write("\n")
+        formatter.write(rendered)
+        formatter.write("\n")
+
+    def _render_tree(self, ctx: click.Context, commands) -> str:
+        from rich.console import Console
+        from rich.tree import Tree
+
+        groups = [(n, c) for n, c in commands if isinstance(c, click.Group)]
+        leaves = [(n, c) for n, c in commands if not isinstance(c, click.Group)]
+
+        tree = Tree(f"[bold]{ctx.command_path}[/bold]", guide_style="dim")
+
+        if leaves:
+            if groups and self.loose_command_heading:
+                bucket = tree.add(f"[bold blue]{self.loose_command_heading}[/bold blue]")
+                _add_leaves(bucket, leaves)
+            else:
+                _add_leaves(tree, leaves)
+
+        for name, group in groups:
+            branch = tree.add(f"[bold cyan]{name}[/bold cyan]   [dim]{_short(group)}[/dim]")
+            sub = [
+                (sn, sc)
+                for sn in group.list_commands(ctx)
+                if (sc := group.get_command(ctx, sn)) and not getattr(sc, "hidden", False)
+            ]
+            if sub:
+                _add_leaves(branch, sub)
+
+        is_tty = bool(getattr(sys.stdout, "isatty", lambda: False)())
+        width = shutil.get_terminal_size((100, 24)).columns
+        buf = io.StringIO()
+        console = Console(
+            file=buf,
+            force_terminal=is_tty,
+            no_color=not is_tty,
+            width=max(40, width),
+        )
+        console.print(tree)
+        return buf.getvalue().rstrip("\n")

mesofield/cli/acquire.py

@@ -0,0 +1,254 @@
+"""Acquisition-workflow commands: launch, init, playback, viewer.
+
+These are the top-level day-to-day entry points and are attached directly to
+the root ``mesofield`` group (no subgroup prefix).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import click
+
+
+# ---------------------------------------------------------------------------
+# launch
+# ---------------------------------------------------------------------------
+
+
+@click.command()
+@click.argument('config', type=click.Path(), required=False, default=None)
+def launch(config):
+    """Launch the Mesofield acquisition interface.
+
+    CONFIG is an optional path to an experiment JSON config file.
+    When omitted, Mesofield opens in a default state and the
+    Configuration Wizard is shown for hot-loading configs.
+    """
+    import time
+
+    from PyQt6.QtWidgets import QApplication, QSplashScreen
+    from PyQt6.QtGui import QPixmap, QPainter, QFont
+    from PyQt6.QtCore import Qt
+    from PyQt6.QtGui import QColor, QRadialGradient
+    from PyQt6.QtGui import QIcon
+
+    from mesofield.gui.maingui import MainWindow
+    from mesofield.gui import theme
+    from mesofield.base import Procedure, load_procedure_from_config
+
+    app = QApplication([])
+    theme.apply_theme(app)
+    window_icon = QIcon(os.path.join(os.path.dirname(os.path.dirname(__file__)), "gui", "Mesofield_icon.png"))
+    app.setWindowIcon(window_icon)
+
+# ====================== Splash Screen with ASCII Art ========================= """
+
+# Font: Sub-Zero; character width: Full, Character Height: Fitted
+# https://patorjk.com/software/taag/#p=display&h=0&v=1&f=Sub-Zero&t=Mesofield
+    ascii = r"""
+ __    __     ______     ______     ______     ______   __      ____      __         _____
+/\ "-./  \   /\  ___\   /\  ___\   /\  __ \   /\  ___\ /\ \   /\  ___\   /\ \       /\  __-.
+\ \ \-./\ \  \ \  __\   \ \___  \  \ \ \/\ \  \ \  __\ \ \ \  \ \  __\   \ \ \____  \ \ \/\ \
+ \ \_\ \ \_\  \ \_____\  \/\_____\  \ \_____\  \ \_\    \ \_\  \ \_____\  \ \_____\  \ \____-
+  \/_/  \/_/   \/_____/   \/_____/   \/_____/   \/_/     \/_/   \/_____/   \/_____/   \/____/
+
+-------------------------  Mesofield Acquisition Interface  ---------------------------------
+"""
+
+    # Create a transparent pixmap
+    pixmap = QPixmap(1100, 210)
+    pixmap.fill(Qt.GlobalColor.transparent)
+
+    # Build a radial gradient: dark center that fades out at the edges
+    center = pixmap.rect().center()
+    radius = max(pixmap.width(), pixmap.height()) / 2
+    gradient = QRadialGradient(center.x(), center.y(), radius)
+    gradient.setColorAt(0.0, QColor(1, 25, 5))  # solid dark center
+    gradient.setColorAt(0.7, QColor(10, 15, 0, 200))  # keep dark until 80%
+    gradient.setColorAt(1.0, QColor(0, 0, 0, 0))    # fully transparent edges
+
+    painter = QPainter(pixmap)
+    # Fill entire pixmap with the gradient block
+    painter.fillRect(pixmap.rect(), gradient)
+
+    # Draw the ASCII art on top
+    painter.setPen(Qt.GlobalColor.green)
+    painter.setFont(QFont("Courier", 12))
+    painter.drawText(pixmap.rect(), Qt.AlignmentFlag.AlignCenter, ascii)
+    painter.end()
+
+    splash = QSplashScreen(pixmap)
+
+    splash.show()
+    app.processEvents()  # ensure the splash appears
+
+    time.sleep(0.5)  # give the splash screen a moment to show :)
+    procedure = load_procedure_from_config(config) if config else Procedure(config)
+
+    mesofield = MainWindow(procedure)
+    mesofield.show()
+    splash.finish(mesofield)
+    app.exec()
+
+
+# ---------------------------------------------------------------------------
+# init
+# ---------------------------------------------------------------------------
+
+
+def _resolve_init_hardware(rig, hardware):
+    """Resolve the ``hardware`` argument for :func:`scaffold_experiment`.
+
+    Returns a ``Path`` (copy a canonical rig file) or ``"dev"`` / ``"blank"``.
+    ``--hardware`` wins over ``--rig``; with neither, an interactive picker
+    over the rig store plus the ``dev`` / ``blank`` built-ins is shown.
+    """
+    from mesofield.scaffold import rigs
+
+    if hardware:
+        return Path(hardware)
+    if rig:
+        if rig in ("dev", "blank"):
+            return rig
+        try:
+            return rigs._resolve_existing(rig)
+        except FileNotFoundError as exc:
+            click.secho(str(exc), fg="red")
+            raise SystemExit(1)
+
+    choices = rigs.list_rigs() + ["dev", "blank"]
+    click.echo("Select a hardware configuration for this experiment:")
+    for name in rigs.list_rigs():
+        click.echo(f"  {name}    (canonical rig)")
+    click.echo("  dev      (mock devices -- runs without hardware)")
+    click.echo("  blank    (fill-out template)")
+    picked = click.prompt(
+        "Rig", type=click.Choice(choices), default="blank", show_choices=False
+    )
+    if picked in ("dev", "blank"):
+        return picked
+    return rigs.rig_path(picked)
+
+
+@click.command('init')
+@click.argument('directory', type=click.Path())
+@click.option('--name', default=None,
+              help='Experiment protocol name (default: directory basename uppercased).')
+@click.option('--force', is_flag=True,
+              help='Overwrite an existing non-empty directory.')
+@click.option('--rig', default=None,
+              help="Canonical rig to copy hardware.yaml from "
+                   "(or 'dev'/'blank'). Skips the interactive picker.")
+@click.option('--hardware', default=None, type=click.Path(exists=True, dir_okay=False),
+              help='Explicit hardware.yaml file to copy in (overrides --rig).')
+def init(directory, name, force, rig, hardware):
+    """Scaffold a new mesofield experiment in DIRECTORY.
+
+    Generates `experiment.json`, `hardware.yaml`, `procedure.py`, and a
+    `devices/` subdirectory with an annotated thermal-sensor example.
+
+    The `hardware.yaml` is chosen interactively: a canonical rig from this
+    machine's rig store (see `mesofield rig`), `dev` (mock devices, runs
+    without hardware), or `blank` (a fill-out template). Use --rig/--hardware
+    to skip the prompt.
+    """
+    from mesofield.scaffold import scaffold_experiment
+
+    hardware_choice = _resolve_init_hardware(rig, hardware)
+    try:
+        out = scaffold_experiment(
+            Path(directory), name=name, force=force, hardware=hardware_choice,
+        )
+    except FileExistsError as exc:
+        click.secho(str(exc), fg="red")
+        raise SystemExit(1)
+    click.secho(f"Scaffolded experiment at {out}", fg="green")
+    click.echo("Next steps:")
+    click.echo(f"  1. cd {out}")
+    if hardware_choice == "dev":
+        click.echo("  2. python procedure.py    # runs the mock acquisition")
+        click.echo(f"  3. open data/sub-SUBJ01/ses-01/manifest.json")
+    else:
+        click.echo("  2. review hardware.yaml   # confirm it matches this rig")
+        click.echo("  3. python procedure.py    # runs the acquisition")
+    click.echo("Read the generated README.md for customization tips.")
+
+
+# ---------------------------------------------------------------------------
+# playback
+# ---------------------------------------------------------------------------
+
+
+@click.command()
+@click.argument('experiment_dir')
+@click.option('--speed', default=1.0, show_default=True, help='Playback speed multiplier')
+@click.option('--loop/--no-loop', default=False, show_default=True, help='Loop playback when finished')
+def playback(experiment_dir: str, speed: float, loop: bool):
+    """Launch Mesofield in playback mode for a recorded experiment."""
+
+    from mesofield.playback import (
+        discover_playback_context,
+        discover_playback_sessions,
+        launch_playback_app,
+    )
+
+    sessions = discover_playback_sessions(Path(experiment_dir))
+    context = discover_playback_context(Path(experiment_dir), speed=speed, loop=loop)
+    launch_playback_app(context, browser_sessions=sessions)
+
+
+# ---------------------------------------------------------------------------
+# viewer
+# ---------------------------------------------------------------------------
+
+
+@click.command()
+@click.argument('config', type=click.Path(exists=True, dir_okay=False), required=False, default=None)
+def viewer(config):
+    """Launch the standalone TIFF ROI viewer.
+
+    CONFIG is an optional path to an ``experiment.json``. When provided, the
+    viewer's "Open TIFF…" dialog opens in that experiment's data directory
+    (``<experiment>/data`` if it exists, otherwise the JSON's parent dir).
+    Hardware is NOT initialized — this is a read-only inspection tool.
+    """
+    import json
+    from PyQt6.QtWidgets import QApplication
+    from PyQt6.QtGui import QIcon
+    from mesofield.data.proc.analysis import TiffViewer
+
+    initial_dir = ""
+    if config:
+        cfg_path = Path(config).resolve()
+        try:
+            with open(cfg_path) as f:
+                data = json.load(f)
+        except Exception:
+            data = {}
+        # Prefer an explicit save_dir from the config; fall back to
+        # <experiment>/data, then the JSON's parent directory.
+        save_dir = data.get('save_dir') if isinstance(data, dict) else None
+        candidates = []
+        if save_dir:
+            candidates.append(Path(save_dir))
+            candidates.append(Path(save_dir) / 'data')
+        candidates.append(cfg_path.parent / 'data')
+        candidates.append(cfg_path.parent)
+        for c in candidates:
+            if c and c.exists():
+                initial_dir = str(c)
+                break
+
+    app = QApplication([])
+    from mesofield.gui import theme
+    theme.apply_theme(app)
+    icon_path = os.path.join(os.path.dirname(os.path.dirname(__file__)), "gui", "Mesofield_icon.png")
+    if os.path.exists(icon_path):
+        app.setWindowIcon(QIcon(icon_path))
+
+    win = TiffViewer(initial_dir=initial_dir or None)
+    win.resize(1100, 800)
+    win.show()
+    app.exec()

mesofield/cli/datakit.py

@@ -0,0 +1,165 @@
+"""``mesofield datakit`` — build, explore, profile, and inspect datasets.
+
+A thin Click surface over :mod:`mesofield.datakit`. Each command maps to a
+public datakit API:
+
+\b
+    build     -> Dataset.from_directory(...).save(...)
+    explore   -> datakit.explore(target)
+    profile   -> datakit.profile_materialized(pkl)
+    inspect   -> datakit.inspect_sources(Dataset)
+    shell     -> datakit.open_shell(target)
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from ._richhelp import RichGroup
+
+
+@click.group('datakit', cls=RichGroup)
+def datakit():
+    """Build, explore, profile, and inspect materialized datasets."""
+
+
+# ---------------------------------------------------------------------------
+# build
+# ---------------------------------------------------------------------------
+
+
+@datakit.command('build')
+@click.argument('input_path', type=click.Path(exists=True, file_okay=False, dir_okay=True))
+@click.option('--output', '-o', 'output_path', type=click.Path(), default=None,
+              help='Output file path (default: <experiment>/processed/YYMMDD_dataset_mvp.<fmt>)')
+@click.option('--tags', '-t', multiple=True, default=None,
+              help='Source tags to include (repeatable; default: all configured tags)')
+@click.option('--format', '-f', 'fmt', type=click.Choice(['h5', 'parquet', 'csv', 'pickle']),
+              default='h5', show_default=True, help='Output format')
+@click.option('--progress', is_flag=True, help='Show a progress bar during materialization')
+@click.option('--shell', 'open_shell_after', is_flag=True,
+              help='Drop into an IPython session after building')
+def build(input_path, output_path, tags, fmt, progress, open_shell_after):
+    """Build a materialized dataset from an experiment directory.
+
+    Discovers the BIDS hierarchy under INPUT_PATH, loads all registered
+    data sources, and writes a single dataset file.
+    """
+    from mesofield.datakit import Dataset
+
+    ds = Dataset.from_directory(
+        Path(input_path),
+        sources=list(tags) if tags else None,
+    )
+    if output_path is None:
+        from datetime import datetime
+        stem = datetime.now().strftime("%y%m%d") + "_dataset_mvp"
+        ext = {"h5": ".h5", "parquet": ".parquet", "csv": ".csv", "pickle": ".pkl"}[fmt]
+        output_path = Path(input_path) / "processed" / (stem + ext)
+    result_path = ds.save(
+        Path(output_path),
+        format={"h5": "hdf5", "parquet": "parquet", "csv": "csv", "pickle": "pickle"}[fmt],
+        strict=True,
+        progress=progress,
+    )
+    click.secho(f"Dataset saved to {result_path}", fg="green")
+    if open_shell_after:
+        from mesofield.datakit import open_shell
+        open_shell(result_path)
+
+
+# ---------------------------------------------------------------------------
+# explore
+# ---------------------------------------------------------------------------
+
+
+@datakit.command('explore')
+@click.argument('target', type=click.Path(exists=True))
+@click.option('--hdf-key', default='dataset', show_default=True,
+              help='HDF5 key to read when TARGET is an .h5/.hdf5 file.')
+def explore(target, hdf_key):
+    """Print a structural report for a dataset.
+
+    TARGET may be an experiment directory (pre-load inventory report), or a
+    materialized ``.pkl`` / ``.h5`` file (post-load DataFrame report).
+    """
+    from mesofield.datakit import explore as explore_fn
+
+    explore_fn(Path(target), print_output=True, hdf_key=hdf_key)
+
+
+# ---------------------------------------------------------------------------
+# profile
+# ---------------------------------------------------------------------------
+
+
+@datakit.command('profile')
+@click.argument('pickle_path', type=click.Path(exists=True, dir_okay=False))
+@click.option('--json', 'json_path', type=click.Path(), default=None,
+              help='Write a JSON report to this path.')
+@click.option('--verbose', is_flag=True,
+              help='Print the detailed per-column breakdown instead of just the summary.')
+@click.option('--top-cells', default=20, show_default=True,
+              help='Number of largest individual cells to include.')
+def profile(pickle_path, json_path, verbose, top_cells):
+    """Profile the memory / storage footprint of a materialized dataset.
+
+    PICKLE_PATH is a materialized ``.pkl`` file produced by ``datakit build``.
+    """
+    from mesofield.datakit import profile_materialized
+
+    report = profile_materialized(Path(pickle_path), top_n_cells=top_cells)
+    click.echo(report.verbose(top_n_cells=top_cells) if verbose else report.summary())
+    if json_path:
+        out = report.to_json(json_path)
+        click.secho(f"\nWrote JSON report to: {out}", fg="green")
+
+
+# ---------------------------------------------------------------------------
+# inspect
+# ---------------------------------------------------------------------------
+
+
+@datakit.command('inspect')
+@click.argument('input_path', type=click.Path(exists=True, file_okay=False, dir_okay=True))
+@click.option('--tags', '-t', multiple=True, default=None,
+              help='Source tags to report (repeatable; default: all discovered tags)')
+def inspect(input_path, tags):
+    """Print per-source coverage for an experiment directory.
+
+    Discovers the BIDS hierarchy under INPUT_PATH and reports how many rows
+    carry each registered source (present / total / missing / coverage),
+    without loading any file payloads.
+    """
+    from mesofield.datakit import Dataset, inspect_sources
+
+    ds = Dataset.from_directory(Path(input_path))
+    summary = inspect_sources(ds, sources=list(tags) if tags else None)
+    if summary.empty:
+        click.secho("No registered sources found in the inventory.", fg="yellow")
+        return
+    click.echo(summary.to_string())
+
+
+# ---------------------------------------------------------------------------
+# shell
+# ---------------------------------------------------------------------------
+
+
+@datakit.command('shell')
+@click.argument('target', type=click.Path(exists=True), required=False, default=None)
+@click.option('--hdf-key', default='dataset', show_default=True,
+              help='HDF5 key to read when TARGET is an .h5/.hdf5 file.')
+def shell(target, hdf_key):
+    """Open an IPython shell pre-loaded with a datakit object.
+
+    TARGET may be an experiment directory (seeds ``dataset`` + ``inventory``)
+    or a materialized ``.pkl`` / ``.h5`` file (seeds ``df``). Omit TARGET for
+    a bare datakit shell. Each session also exposes ``datakit``, ``explore``,
+    and a pre-computed ``report``.
+    """
+    from mesofield.datakit import open_shell
+
+    open_shell(Path(target) if target else None, hdf_key=hdf_key)