Skip to content

Add pipeio.matlab module for MATLAB rule wiring

Goal

(promoted from note)

Context

(see source note)

Prompt

Fix the issue described below (source: /storage2/arash/projects/projio/docs/log/issue/issue-arash-20260408-191633-549705.md). Understand the problem, then implement the proposed fix.

Add pipeio.matlab module for MATLAB rule wiring

Pipeio needs a pipeio.matlab module that provides a generalized matlab2shell() utility for wiring MATLAB functions into Snakemake shell: directives.

Context

pixecog's tests/snakemake-matlab/matlab_utils.py has a proof-of-concept that works but is hardcoded. The pattern is valuable: compose a MATLAB -batch command string that Snakemake can call.

Requirements

  1. pipeio.matlab.matlab2shell() — generalized version:
  2. MATLAB binary path from runtime.matlab_bin config key (like runtime.projio_python and runtime.datalad_bin)
  3. Configurable startup script path (default: code/startup.m)
  4. Configurable path reset behavior

  5. No hardcoded paths

  6. runtime.matlab_bin config key — add to projio's runtime config schema alongside projio_python and datalad_bin

  7. Documentation — add a section to pipeio pipeline-docs or create a skill showing the MATLAB rule wiring pattern (Snakefile shell: directive using matlab2shell())

  8. Reference Snakefile pattern: 

    rule sleepstates:
    shell:
        matlab2shell("functionBrainStateClass_pipeline(pwd,'{wildcards.rec}',{params.nchannel},{params.fs},'{output.mat}','{output.png}')") + " >> {log} 2>&1"

Reference

  • Source: pixecog/tests/snakemake-matlab/matlab_utils.py
  • Snakefile: pixecog/tests/snakemake-matlab/Snakefile

Acceptance Criteria

  • [ ]

Result

Completed in 339.8s (1 steps, model: opus)

Session: 7d277ab5-734d-4e5a-99b2-48266135cda5 Result note: /storage2/arash/worklog/workflow/captures/20260408-192330-44f584/note.md

Output

All 71 projio tests pass. Here's a summary of what was implemented:

### Changes made

1. **`packages/pipeio/src/pipeio/matlab.py`** (new) — Generalized `matlab2shell()` function with:
   - `matlab_bin` parameter (falls back to `MATLAB_BIN` env var, then `"matlab"`)
   - Configurable `startup_script` (default: `"code/startup.m"`)
   - Configurable `reset_path` (default: `True` — prepends `restoredefaultpath; rehash toolboxcache;`)
   - No hardcoded paths

2. **`packages/pipeio/src/pipeio/__init__.py`** — Added lazy `matlab2shell` export

3. **`src/projio/config.py`** — Added `matlab` to `resolve_env_all()` (resolves from `code.envs.matlab`)

4. **`src/projio/init.py`** — Added `MATLAB ?= matlab` to `PROJIO_MK` template + substitution from `runtime.matlab_bin` or `code.envs.matlab`

5. **`packages/pipeio/tests/test_matlab.py`** (new) — 10 tests covering binary resolution, env fallback, prelude options, Snakemake pattern, and package import

## Next Steps

1. Create a pipeio skill or docs page showing the MATLAB rule wiring pattern (Snakefile `shell:` directive using `matlab2shell()` with `runtime.matlab_bin` config).
2. Update the pixecog `tests/snakemake-matlab/matlab_utils.py` to import from `pipeio.matlab` instead of using the hardcoded version.
3. Add `runtime.matlab_bin` to pixecog's `.projio/config.yml` pointing to `/storage/share/bin/R2023a/bin/matlab`.