Consolidate multisession assignment and ROI similarity utilities

[FlorianPfaff]

Summary

This PR consolidates the generic multi-session assignment work and the reusable ROI-similarity utilities into a single branch against main.

It is intended as a cleaned-up merge target for the overlapping open work in:

• Codex/multisess convenience functions #1804
• Codex/multisess track2p convenience v2 #1806
• the utility-level core of Add Suite2p-aware weighted ROI similarity utilities #1803

Included

From #1804 / #1806

• generic solve_multisession_assignment
• MultiSessionAssignmentResult
• similarity-input wrapper solve_multisession_assignment_from_similarity
• dense exports/helpers:
  • tracks_to_session_labels
  • tracks_to_index_matrix
  • result.to_session_labels(...)
  • result.to_index_matrix(...)
• observation-specific start/end cost support via
  solve_multisession_assignment_with_observation_costs
• associated tests for the above

From #1803

• reusable weighted ROI similarity utilities in pyrecest.utils.roi_similarity
• centroid helpers and fused ROI cost-matrix construction
• associated tests
• public exports in pyrecest.utils

Intentional consolidation choices

• Use Codex/multisess convenience functions #1804 as the main backbone for the multi-session assignment implementation.
• Treat Codex/multisess track2p convenience v2 #1806 as overlapping/superseded by the consolidated multi-session core already represented here.
• Keep the reusable ROI-similarity layer from Add Suite2p-aware weighted ROI similarity utilities #1803 in PyRecEst because it is utility-level and works with dense masks, sparse coordinate lists, and generic mapping-based ROI formats.
• Do not add Track2p- or Suite2p-specific file I/O / pipeline orchestration here beyond the utility interfaces already present in the ROI helpers.

Notes

• This PR is meant to provide a single merge candidate instead of merging the overlapping branches separately.
• If desired, the older overlapping PRs can be closed after this is reviewed.

[github-actions]

✅MegaLinter analysis: Success

Descriptor	Linter	Files	Fixed	Errors	Warnings	Elapsed time
✅ COPYPASTE	jscpd	yes		no	no	15.06s
✅ JSON	prettier	2	0	0	0	0.48s
✅ JSON	v8r	2		0	0	2.58s
✅ MARKDOWN	markdownlint	2	0	0	0	0.69s
✅ MARKDOWN	markdown-table-formatter	2	0	0	0	0.27s
✅ PYTHON	bandit	372		0	0	5.68s
✅ PYTHON	black	372	17	0	0	9.8s
✅ PYTHON	flake8	372		0	0	3.16s
✅ PYTHON	isort	372	19	0	0	0.74s
✅ PYTHON	mypy	372		0	0	5.29s
✅ PYTHON	pylint	372		0	0	117.22s
✅ PYTHON	ruff	372	19	0	0	0.08s
✅ REPOSITORY	checkov	yes		no	no	22.22s
✅ REPOSITORY	gitleaks	yes		no	no	9.82s
✅ REPOSITORY	git_diff	yes		no	no	0.04s
✅ REPOSITORY	secretlint	yes		no	no	7.85s
✅ REPOSITORY	syft	yes		no	no	3.22s
✅ REPOSITORY	trivy-sbom	yes		no	no	2.17s
✅ REPOSITORY	trufflehog	yes		no	no	19.4s
✅ YAML	prettier	4	0	0	0	0.47s
✅ YAML	v8r	4		0	0	5.28s
✅ YAML	yamllint	4		0	0	0.45s

See detailed reports in MegaLinter artifacts

Your project could benefit from a custom flavor, which would allow you to run only the linters you need, and thus improve runtime performances. (Skip this info by defining FLAVOR_SUGGESTIONS: false)

• Documentation: Custom Flavors
• Command: npx mega-linter-runner@9.4.0 --custom-flavor-setup --custom-flavor-linters PYTHON_PYLINT,PYTHON_BLACK,PYTHON_FLAKE8,PYTHON_ISORT,PYTHON_BANDIT,PYTHON_MYPY,PYTHON_RUFF,COPYPASTE_JSCPD,JSON_V8R,JSON_PRETTIER,MARKDOWN_MARKDOWNLINT,MARKDOWN_MARKDOWN_TABLE_FORMATTER,REPOSITORY_CHECKOV,REPOSITORY_GIT_DIFF,REPOSITORY_GITLEAKS,REPOSITORY_SECRETLINT,REPOSITORY_SYFT,REPOSITORY_TRIVY_SBOM,REPOSITORY_TRUFFLEHOG,YAML_PRETTIER,YAML_YAMLLINT,YAML_V8R

Show us your support by starring ⭐ the repository

[github-actions]

Test Results

    4 files   -     8      4 suites   - 8   38m 54s ⏱️ - 3h 45m 8s
1 053 tests +   28  1 053 ✅ +   28  0 💤 ±    0  0 ❌ ±0 
4 388 runs   - 8 196  4 388 ✅  - 5 328  0 💤  - 2 868  0 ❌ ±0 

Results for commit a1aa0d1. ± Comparison against base commit 1345794.

♻️ This comment has been updated with latest results.