refactor: move video I/O to minian.io (part of #309)

[thicclatka]

Part of #309

Summary

Implements @sneakers-the-rat's step 1: move video/movie file I/O out of the god modules into a dedicated top-level minian.io module. This PR is move-only / behavior-neutral — no H264OutputOptions refactor, no change to ffmpeg kwargs in write_video.

• Add minian/io.py with load_videos, write_video, load_avi_ffmpeg, and private helpers (_ensure_ffmpeg, _load_avi_lazy, _load_tif_lazy, _load_tif_perframe)
• Keep load_avi_ffmpeg name unchanged (dask graph / TaskAnnotation contract)
• Deprecate (do not delete) legacy helpers with PEP 702 @deprecated: load_avi_lazy_framewise, load_avi_perframe, write_vid_blk, concat_video_recursive
• minian.utilities: scipy-style __getattr__ shim + DeprecationWarning for symbols that moved to minian.io
• minian.visualization: keep generate_videos; re-export write_video for backward compat; shim deprecated imports of write_vid_blk / concat_video_recursive
• Add explicit typing_extensions dependency (for @deprecated on Python <3.13)

Compatibility

Old import	New canonical import	Notes
from minian.utilities import load_videos	from minian.io import load_videos	Shim warns, still works
from minian.utilities import ensure_ffmpeg	—	Shim maps to private _ensure_ffmpeg
from minian.visualization import write_video	from minian.io import write_video	Re-export unchanged
from minian.visualization import write_vid_blk	from minian.io import write_vid_blk	Deprecated

Out of scope (follow-up PRs on #309)

• Split remaining utilities.py into submodules (dataset, dask_opt, chunking, signal)
• H264OutputOptions / shared ffmpeg output builder
• visualization/ package split

Test plan

• pdm run python -m pytest minian/test/test_pre_processing.py --no-cov
• pdm run ruff check minian/io.py minian/utilities.py minian/visualization.py
• Manual: from minian.utilities import load_videos emits DeprecationWarning and returns same object as minian.io.load_videos

Made with Cursor

[codecov]

Codecov Report

❌ Patch coverage is 45.97701% with 94 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
minian/io.py	45.94%	80 Missing ⚠️
minian/utilities.py	31.25%	11 Missing ⚠️
minian/visualization.py	70.00%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!

[daharoni]

Thanks @thicclatka. I think our plan is to first get robust unit tests up and running based on a data simulation module for minian I am close to making a PR for. Once we have that, it would be great to get some of these large minian modules refactored into more manageable chunks.

[thicclatka]

Noted, thanks @daharoni.

Happy to wait on this and sync up once your simulation module + unit-test PR lands. No rush on my side. We can hold #321 as-is for the time being.

#321 is step 1 on #309 (the broader utilities / I/O refactor proposal). Outside this PR, I'll use that issue to track follow-ups for the remaining refactors (e.g. splitting the rest of utilities.py). Downstream, I'd like to layer in things like shared logging and timing helpers (and similar cross-cutting pieces) on top of that test foundation, then work toward a headless pipeline mode. I think headless pipeline fits better after unit tests and the refactors land, so the order you outlined works well for me too.

For context on what I have in mind for the pipeline side (just reference implementations), the scripts/modules on my fork's master branch from the closed PR work are:

• minian/pipelines/cnmf_process.py: headless CNMF pipeline (minian-pipeline entry point)
• minian/pipelines/cross_reg.py: cross-registration CLI (minian-cross-reg)
• minian/config/pipeline_config.py: JSON pipeline config load/resolve
• minian/utilities/logger.py: CLI logging, wall-clock section helpers, and colored/differentiated log output so CNMF vs cross-reg (and other pipelines) are easy to tell apart in mixed runs

Happy to port those incrementally after simulation-backed tests exist, aligned with however you want the merge train ordered.