Pna 2446 compute layouts on the fly in pixelator

[elhb]

Description

Layouts are now computed on the fly from each Component graph, instead of only being read from a stored layouts table (845fa6a3).

Before: pxl_dataset.precomputed_layouts().to_df()
After: pxl_dataset.layouts(...).to_df()

PNAPixelDataset.layouts() always computes coordinates from the active Component graphs.
It never reads the PXL layouts table.
Callers choose the Layout algorithm with algorithm= (default coarsened_pmds_3d, via DEFAULT_LAYOUT_ALGORITHM), optional random_seed, and other algorithm kwargs.
Results export through .first(), .iterator(), .to_df(), and .to_polars() with the same column shape as stored layouts (including optional spherical norm and marker counts).

precomputed_layouts() left as is and still reads the stored table when it exists, precomputed_layouts() is is deprecated and will emit DeprecationWarning.
pixelator single-cell-pna layout remains an opt-in writer of Precomputed layouts.

Layout algorithm defaults for layouts(), layout_coordinates, and the layout CLI all go through DEFAULT_LAYOUT_ALGORITHM (41c79182).

Also in this PR, but not specific to on-the-fly computation (cursor bug bot):

general robustness in coarsened_pmds_layout / layout_coordinates that we hit because layouts() now runs the default algorithm on typical Components instead of reading a stored table. These also affect the layout CLI and any other coarsened_pmds_layout / layout_coordinates caller:

• Graphs smaller than pivots (default 200) fall back to normalized PMDS on the full graph, instead of raising (00dd7c06).
• When Leiden yields too few communities, that fallback sizes pivots from the full graph so a valid low pivots does not fail pmds_layout's 0.2 * n bound (3b7d4f43).
• layout_coordinates / layouts() accept seed= as an alias for random_seed= (previously seed= TypeError'd because algorithms already take seed=) (730f607b).

Fixes: PNA-2446

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

How Has This Been Tested?

• tests/pna/pixeldataset/test_layouts.py: default algorithm constant, .layouts() / .first() / .iterator() / .to_df() / .to_polars(), column shape vs precomputed layouts, always-compute (does not read the layouts table), kwargs forwarding, seed= vs random_seed=, spherical norms (3D and 2D), missing marker counts filled with 0, DeprecationWarning on precomputed_layouts(), default coarsened_pmds_3d on Components smaller than the default pivot count.
• tests/pna/layout/test_coarsened_pmds_layout.py: graphs smaller than default pivots, Leiden too-few-communities fallback with a valid low pivots, determinism / validity / neighborhood preservation.
• tests/common/graph/test_layout_coordinates.py: seed= seeds the default algorithm the same way as random_seed=.

To reproduce the new tests:

uv run pytest tests/pna/pixeldataset/test_layouts.py tests/pna/layout/test_coarsened_pmds_layout.py tests/common/graph/test_layout_coordinates.py

PR checklist:

• This comment contains a description of changes (with reason).
• I have performed a self-review of my own code
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• If a new tool or package is included, I have updated dependencies in pyproject.toml and cited it properly
• I have checked my code and documentation and corrected any misspellings
• I have documented any significant changes to the code in CHANGELOG.md

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 730f607. Configure here.}