160 lines
4.5 KiB
Markdown
160 lines
4.5 KiB
Markdown
# Execution and Verification
|
|
|
|
## Goal
|
|
|
|
Turn a high-level publication figure/table request into a route that is actually runnable in the current environment.
|
|
|
|
## Minimum environment probe
|
|
|
|
Prefer the lightest useful checks.
|
|
|
|
### Preferred bundled probe
|
|
|
|
```bash
|
|
python3 scripts/ensure_publication_tooling.py --require pubfig --json
|
|
python3 scripts/ensure_publication_tooling.py --require pubtab --json
|
|
```
|
|
|
|
The helper probes availability, force-installs missing dependencies into the active interpreter, and returns the post-install status.
|
|
|
|
### Equivalent manual checks
|
|
|
|
```bash
|
|
python -c "import pubfig; print(pubfig.__version__)"
|
|
python -c "import pubtab; print(pubtab.__version__)"
|
|
pubtab --help
|
|
```
|
|
|
|
Do not spend the whole turn on setup if the user primarily needs design guidance. Just identify whether the route is executable now or should degrade gracefully.
|
|
|
|
## Automatic installation policy
|
|
|
|
If a dependency is missing and the task requires real execution, install it automatically before continuing.
|
|
|
|
### Preferred bundled route
|
|
|
|
Use the bundled helper when it is present:
|
|
|
|
```bash
|
|
python3 scripts/ensure_publication_tooling.py --require pubfig
|
|
python3 scripts/ensure_publication_tooling.py --require pubtab
|
|
```
|
|
|
|
The helper chooses `uv pip install --python <active-python>` when the project is clearly `uv`-managed, and otherwise falls back to `python -m pip install ...`.
|
|
|
|
### Equivalent manual install commands
|
|
|
|
```bash
|
|
uv pip install --python "$VIRTUAL_ENV/bin/python" pubfig
|
|
uv pip install --python "$VIRTUAL_ENV/bin/python" pubtab
|
|
python -m pip install pubfig
|
|
python -m pip install pubtab
|
|
```
|
|
|
|
### Required follow-up
|
|
|
|
After installation:
|
|
|
|
1. re-run the availability probe,
|
|
2. report the updated environment status,
|
|
3. continue with the runnable figure/table workflow.
|
|
|
|
If installation fails, capture the exact error and then fall back to design/specification guidance.
|
|
|
|
## Route selection
|
|
|
|
### Use `pubfig` when
|
|
|
|
- the task is primarily a figure,
|
|
- the user already has Python data structures,
|
|
- the result is a plot family already covered by `pubfig`,
|
|
- export quality matters immediately.
|
|
|
|
### Use `pubtab` when
|
|
|
|
- the task is primarily a publication table,
|
|
- the input is an Excel workbook, a `.tex` table, or a file-driven workflow,
|
|
- the reader needs exact values,
|
|
- previewing the table before manuscript insertion matters.
|
|
|
|
### Use both when
|
|
|
|
- the figure carries the visual pattern,
|
|
- the table preserves exact benchmark values,
|
|
- the paper section benefits from one fast visual plus one exact-value artifact.
|
|
|
|
## First runnable verification
|
|
|
|
### `pubfig`
|
|
|
|
After generating a minimal figure route, the first useful verification is:
|
|
|
|
- can the code execute,
|
|
- does `save_figure(...)` or `batch_export(...)` produce the expected files,
|
|
- do output suffixes match the intended formats.
|
|
|
|
### `pubtab`
|
|
|
|
After generating a minimal table route, the first useful verification is:
|
|
|
|
- can `xlsx2tex` or `tex2xlsx` run,
|
|
- can `preview` render PNG or PDF,
|
|
- does the chosen backend (`tabular` or `tabularray`) match the manuscript need.
|
|
|
|
## Current practical notes
|
|
|
|
### `pubfig`
|
|
|
|
Useful export primitives include:
|
|
|
|
- `save_figure(...)`
|
|
- `batch_export(...)`
|
|
- `export_panel(...)`
|
|
- `export_panels(...)`
|
|
|
|
Use panel export only when multi-panel assembly is truly needed.
|
|
|
|
### `pubtab`
|
|
|
|
Useful file-oriented routes include:
|
|
|
|
- `pubtab xlsx2tex ...`
|
|
- `pubtab tex2xlsx ...`
|
|
- `pubtab preview ...`
|
|
|
|
Remember:
|
|
|
|
- `xlsx2tex` exports all sheets by default when `--sheet` is not set,
|
|
- `preview` can render PNG or PDF,
|
|
- `--latex-backend tabularray` should be chosen only when the manuscript/backend requires `tblr`,
|
|
- when preview reliability is the immediate priority, validate the table body first and add final `caption` / `label` in a separate manuscript-facing step if needed.
|
|
|
|
## Graceful degradation
|
|
|
|
If the tool is missing:
|
|
|
|
- first try the bundled auto-install helper,
|
|
- if that route is unavailable, use the manual install commands above,
|
|
- if installation still fails, provide:
|
|
- the artifact recommendation,
|
|
- the exact files the user should prepare,
|
|
- a draft CLI or Python route,
|
|
- the export targets,
|
|
- and the publication QA checklist.
|
|
|
|
## Default output wording
|
|
|
|
When the route is runnable now, say:
|
|
|
|
- what to run,
|
|
- what files should appear,
|
|
- what to inspect next.
|
|
|
|
When the route is not runnable now, say:
|
|
|
|
- what is missing,
|
|
- which helper command or install command was attempted,
|
|
- whether the install succeeded or failed,
|
|
- what the intended route will be after install,
|
|
- and what design decision can already be locked in today.
|