dosho 0.1.0a1__py3-none-any.whl

dosho/__init__.py

@@ -0,0 +1,11 @@
+"""dosho -- a shinobi's tool bag. The native shinobi (stimela-ninja) cab
+repository. See AGENTS.md for the design rationale.
+"""
+
+from dosho import images
+from dosho._builder import define_cab
+from dosho.registry import get, list_cabs
+
+__all__ = ["define_cab", "get", "images", "list_cabs"]
+
+__version__ = "0.1.0a1"

dosho/_builder.py

@@ -0,0 +1,84 @@
+"""Thin builder for authoring a native `dosho` cab: wraps `shinobi.Cab` +
+`shinobi.loaders.build_model` + `shinobi.loaders.sanitize_unique` to remove
+the boilerplate of hand-transcribing a real tool's parameter list, without
+inventing any new schema surface.
+
+Generalises the `cab_from_defaults` helper first proven in
+stimela-ninja's `examples/ninja_selfcal.py`. Deliberately not a
+signature-introspecting decorator (`@cab`) -- that shape was tried once in
+shinobi itself (`ba2bd48`) and removed (`605b6f8`): it can't express
+`nom_de_guerre` (hyphenated CLI names aren't valid Python parameter
+names), `input_patterns`, `Policies`, `positional`, or `implicit`. Raw
+`Cab(...)` stays fully available for anything this helper doesn't cover --
+it's sugar, not a wall.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from shinobi import Cab
+from shinobi.loaders import build_model, sanitize_unique
+from shinobi.steps.schema import ParamMeta, ParamPattern, Policies
+
+
+def define_cab(
+    name: str,
+    command: str,
+    image: str,
+    fields: dict[str, tuple[str, bool, Any]],
+    *,
+    outputs: dict[str, tuple[str, bool, Any]] | None = None,
+    field_meta: dict[str, ParamMeta] | None = None,
+    policies: Policies | None = None,
+    input_patterns: list[ParamPattern] | None = None,
+    output_patterns: list[ParamPattern] | None = None,
+    flavour: str = "binary",
+    wranglers: dict[str, list[str]] | None = None,
+    info: str | None = None,
+) -> Cab:
+    """Build a `Cab` from a flat `{raw_param_name: (dtype, required,
+    default)}` dict -- the shape a tool's own `--help`/docs naturally give
+    you (e.g. `"data-ms": ("MS", True, None)`). Hyphenated/dotted raw
+    names are sanitised to valid pydantic field names, with the original
+    kept as a `nom_de_guerre` so the built cab's `build_argv` still emits
+    the tool's real flag.
+
+    `field_meta` entries the caller passes explicitly (keyed by the
+    *sanitised* field name -- e.g. an output field's `implicit` template,
+    or a `positional`/`repeat_as_tokens` override) are merged in on top of
+    the auto-derived `nom_de_guerre`s; an explicit entry that doesn't set
+    its own `nom_de_guerre` keeps the auto-derived one rather than losing
+    it.
+    """
+    resolved_fields: dict[str, tuple[str, bool, Any]] = {}
+    resolved_meta: dict[str, ParamMeta] = {}
+    seen: dict[str, str] = {}
+    for raw_name, spec in fields.items():
+        field = sanitize_unique(raw_name, seen)
+        resolved_fields[field] = spec
+        if field != raw_name:
+            resolved_meta[field] = ParamMeta(nom_de_guerre=raw_name)
+
+    for field, meta in (field_meta or {}).items():
+        auto = resolved_meta.get(field)
+        if auto is not None and meta.nom_de_guerre is None:
+            meta = meta.model_copy(update={"nom_de_guerre": auto.nom_de_guerre})
+        resolved_meta[field] = meta
+
+    return Cab(
+        name=name,
+        command=command,
+        image=image,
+        info=info,
+        flavour=flavour,
+        inputs_model=build_model(
+            f"{name}_Inputs", resolved_fields, allow_extra=bool(input_patterns)
+        ),
+        outputs_model=build_model(f"{name}_Outputs", outputs or {}),
+        field_meta=resolved_meta,
+        policies=policies or Policies(),
+        input_patterns=input_patterns or [],
+        output_patterns=output_patterns or [],
+        wranglers=wranglers or {},
+    )

dosho/cabs/__init__.py

@@ -0,0 +1,84 @@
+"""Every tool dosho ports, re-exported by name at package level, so a
+pipeline author who knows what they want at write-time can do
+`from dosho.cabs import wsclean` or `from dosho.cabs.casatasks import
+listobs` directly -- no need to know or care whether a given tool is a
+`Cab` (a real binary, argv-built and shelled out to) or a `StepRef` (a
+Python-package tool with no standalone binary, run via `@shinobi.pystep`
+and `ctx.import_func` inside a container instead -- CASA tasks are the
+only example so far). Both shapes are first-class for `Recipe.add_step`.
+
+For *runtime*/string-keyed lookup (the CLI, `shinobi.cabs` entry-point
+discovery), use `dosho.get(name)`/`dosho.registry` instead -- that's a
+second, parallel interface for a caller that doesn't know the name until
+it runs, not a replacement for these direct imports.
+
+Importing this module (or any of its submodules -- Python always
+initializes a parent package first) eagerly constructs every `Cab`/
+`StepRef` below. That's a deliberate, accepted tradeoff here: each one is
+cheap (pydantic model + dict construction, no I/O), so the "don't pay for
+what you don't use" laziness `dosho.registry`'s own submodule-path table
+still gives a caller that only wants one specific tool is preserved
+there, not here.
+"""
+
+from __future__ import annotations
+
+from dosho.cabs.aoflagger import aoflagger
+from dosho.cabs.casaplotms import plotms
+from dosho.cabs.casatasks import (
+    applycal,
+    bandpass,
+    clearcal,
+    fixvis,
+    flagdata,
+    flagmanager,
+    fluxscale,
+    gaincal,
+    initweights,
+    listobs,
+    mstransform,
+    polcal,
+    setjy,
+)
+from dosho.cabs.crystalball import crystalball
+from dosho.cabs.cubical import cubical
+from dosho.cabs.mosaic_queen import mosaic_queen
+from dosho.cabs.owlcat_plotelev import owlcat_plotelev
+from dosho.cabs.quartical import quartical
+from dosho.cabs.ragavi import ragavi
+from dosho.cabs.shadems import shadems
+from dosho.cabs.simms import simms_classic, skysim, telsim
+from dosho.cabs.sofia2 import sofia2
+from dosho.cabs.tricolour import tricolour
+from dosho.cabs.wsclean import wsclean
+
+__all__ = [
+    "aoflagger",
+    "applycal",
+    "bandpass",
+    "clearcal",
+    "crystalball",
+    "cubical",
+    "fixvis",
+    "flagdata",
+    "flagmanager",
+    "fluxscale",
+    "gaincal",
+    "initweights",
+    "listobs",
+    "mosaic_queen",
+    "mstransform",
+    "owlcat_plotelev",
+    "plotms",
+    "polcal",
+    "quartical",
+    "ragavi",
+    "setjy",
+    "shadems",
+    "simms_classic",
+    "skysim",
+    "sofia2",
+    "telsim",
+    "tricolour",
+    "wsclean",
+]

dosho/cabs/aoflagger.py

@@ -0,0 +1,69 @@
+"""aoflagger -- automatic RFI flagger (https://aoflagger.readthedocs.io).
+
+Ported field-by-field from cult-cargo's aoflagger.yml (a flat, static
+schema -- no dynamic_schema, no package-scoped _include -- so this is a
+mechanical transcription, not a structural fix like wsclean/cubical/
+quartical).
+"""
+
+from __future__ import annotations
+
+from shinobi.steps.schema import ParamMeta, Policies
+
+from dosho import images
+from dosho._builder import define_cab
+
+_FIELDS: dict[str, tuple[str, bool, object]] = {
+    "msname": ("MS", True, None),
+    "verbose": ("bool", False, False),
+    "threads": ("int", False, None),
+    "strategy": ("File", False, None),
+    "indirect_read": ("bool", False, True),
+    "memory_read": ("bool", False, False),
+    "auto_read_mode": ("bool", False, True),
+    "uvw": ("bool", False, False),
+    "column": ("str", False, "DATA"),
+    "skip_flagged": ("bool", False, False),
+    "bands": ("int", False, None),
+    "fields": ("int", False, None),
+}
+
+_FIELD_META: dict[str, ParamMeta] = {
+    "msname": ParamMeta(info="MS name(s) to be flagged"),
+    "verbose": ParamMeta(nom_de_guerre="v", info="Produce verbose output"),
+    "threads": ParamMeta(
+        nom_de_guerre="j",
+        info="overrides the number of threads specified in the strategy (default: one thread for each CPU core)",
+    ),
+    "strategy": ParamMeta(info="specifies a possible customized strategy"),
+    "indirect_read": ParamMeta(
+        nom_de_guerre="indirect-read",
+        info="will reorder the measurement set before starting, which is normally faster but requires free disk space to reorder the data to",
+    ),
+    "memory_read": ParamMeta(
+        nom_de_guerre="memory-read",
+        info="will read the entire measurement set in memory. This is the fastest, but requires much memory.",
+    ),
+    "auto_read_mode": ParamMeta(
+        nom_de_guerre="auto-read-mode",
+        info="will select either memory or direct mode based on available memory",
+    ),
+    "uvw": ParamMeta(info="reads uvw values (some exotic strategies require these)"),
+    "column": ParamMeta(info="specify column to flag"),
+    "skip_flagged": ParamMeta(
+        nom_de_guerre="skip-flagged",
+        info="will skip an ms if it has already been processed by AOFlagger according to its HISTORY table.",
+    ),
+    "bands": ParamMeta(info="comma separated list of (zero-indexed) band ids to process"),
+    "fields": ParamMeta(info="Field ID(s). Comma separated string if more than one field"),
+}
+
+aoflagger = define_cab(
+    "aoflagger",
+    "aoflagger",
+    images.AOFLAGGER,
+    _FIELDS,
+    field_meta=_FIELD_META,
+    policies=Policies(prefix="-"),
+    info="AOFlagger automatic RFI flagger (https://aoflagger.readthedocs.io)",
+)

dosho/cabs/casaplotms.py

@@ -0,0 +1,62 @@
+"""`@shinobi.pystep` wrapper for CASA's `plotms` task
+(`casaplotms.plotms`, a sibling package to `casatasks`, not part of it --
+same `ctx.import_func`-inside-container mechanism as
+`dosho.cabs.casatasks`, see that module's own docstring for the full
+rationale).
+
+One general wrapper covers both a minimal single-axis-pair plot (e.g. an
+elevation-vs-hourangle track) and the fuller per-datacolumn/per-correlation
+diagnostic-plot shape (iterating over correlations via `iteraxis`) --
+callers omit whatever they don't need; the real task's own defaults apply.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import shinobi
+from pydantic import BaseModel
+
+from dosho import images
+
+
+class PlotmsOutputs(BaseModel):
+    plotfile: Path
+
+
+@shinobi.pystep(image=images.CASA6)
+def plotms(
+    ctx,
+    vis: Path,
+    xaxis: str,
+    yaxis: str,
+    plotfile: Path,
+    xdatacolumn: str = "",
+    ydatacolumn: str = "",
+    coloraxis: str = "",
+    field: str = "",
+    correlation: str = "",
+    iteraxis: str = "",
+    expformat: str = "png",
+    exprange: str = "all",
+    overwrite: bool = True,
+    showgui: bool = False,
+) -> PlotmsOutputs:
+    plotms_fn = ctx.import_func("plotms", "casaplotms")
+    plotms_fn(
+        vis=str(vis),
+        xaxis=xaxis,
+        yaxis=yaxis,
+        xdatacolumn=xdatacolumn,
+        ydatacolumn=ydatacolumn,
+        coloraxis=coloraxis,
+        field=field,
+        correlation=correlation,
+        iteraxis=iteraxis,
+        plotfile=str(plotfile),
+        expformat=expformat,
+        exprange=exprange,
+        overwrite=overwrite,
+        showgui=showgui,
+    )
+    return PlotmsOutputs(plotfile=plotfile)