Refactor utils into sdata + data subpackages and migrate sd_utils imports

[Copilot]

This PR reorganizes src/xenium_analysis_tools/utils/ by decomposing the monolithic sd_utils.py into focused modules, relocating packaged data assets under utils/data, and removing legacy paths. It also updates all in-repo import sites to the new module layout (no compatibility shim).

• utils/sdata module split (from sd_utils.py)

  • Added:
    • utils/sdata/transforms.py (add_micron_coord_sys, get_microns_scales, extract_scale_transform, rename_coordinate_systems_manual)
    • utils/sdata/channels.py (rename_chans, get_channel_name, separate_channels)
    • utils/sdata/elements.py (element IO/introspection helpers and private helpers)
    • utils/sdata/file_ops.py (dataset JSON + filesystem orchestration)
  • Added utils/sdata/__init__.py re-exporting symbols across submodules.
  • Deleted utils/sd_utils.py.

• Packaged data relocation to utils/data

  • Moved:
    • utils/xenium_datasets.json → utils/data/xenium_datasets.json
    • utils/reference_tables/*.csv → utils/data/reference_tables/*.csv
  • Added utils/data/__init__.py for package/resource resolution.
  • Deleted stray notebook utils/reference_tables/816460.ipynb.
  • Removed old utils/reference_tables/ location.

• Import/resource path updates

  • Updated all utils.sd_utils import sites across alignment/processing modules and notebooks to utils.sdata.*.
  • Updated utils/env.py:
    • get_datasets_json_path() now resolves from xenium_analysis_tools.utils.data.
  • Updated utils/__init__.py:
    • Re-exported the new public API from utils.sdata.
    • Fixed get_datasets_info_file() to resolve resources from xenium_analysis_tools.utils.data.

• Packaging metadata

  • Updated [tool.setuptools.package-data] in pyproject.toml to:
    • "xenium_analysis_tools.utils.data" = ["*.json", "reference_tables/*.csv"]
  • Removed stale package-data entries tied to previous locations.

Example import migration:

# before
from xenium_analysis_tools.utils.sd_utils import add_micron_coord_sys, write_sdata_elements

# after
from xenium_analysis_tools.utils.sdata.transforms import add_micron_coord_sys
from xenium_analysis_tools.utils.sdata.elements import write_sdata_elements

Original prompt

Goal

Reorganize src/xenium_analysis_tools/utils/ by:

1. Splitting the monolithic sd_utils.py into a sdata/ subpackage with focused modules
2. Moving xenium_datasets.json and reference_tables/ into a utils/data/ subpackage
3. Deleting sd_utils.py and the old utils/reference_tables/ location
4. Updating all imports everywhere in the codebase

---

Target structure

src/xenium_analysis_tools/utils/
├── __init__.py               # re-export public API (see below)
├── env.py                    # unchanged except: fix get_datasets_json_path() reference
├── io_utils.py               # unchanged
├── xoa_server.py             # unchanged
│
├── sdata/
│   ├── __init__.py           # re-exports everything from submodules
│   ├── transforms.py         # coordinate/transform helpers
│   ├── channels.py           # channel rename/separate helpers
│   ├── elements.py           # element read/write/inspect helpers
│   └── file_ops.py           # dataset JSON + filesystem orchestration
│
└── data/
    ├── __init__.py            # empty, marks as package
    ├── xenium_datasets.json   # moved from utils/xenium_datasets.json
    └── reference_tables/      # moved from utils/reference_tables/
        └── *.csv

---

File assignments

utils/sdata/transforms.py

Move from sd_utils.py:

• add_micron_coord_sys
• get_microns_scales
• extract_scale_transform
• rename_coordinate_systems_manual

utils/sdata/channels.py

Move from sd_utils.py:

• rename_chans
• get_channel_name
• separate_channels

utils/sdata/elements.py

Move from sd_utils.py:

• _is_multiscale (private helper, keep private)
• _count_element_chunks (private helper, keep private)
• _TqdmDaskCallback (private helper, keep private)
• write_sdata_elements
• drop_sdata_elements
• rename_elements_section
• get_spatial_elements
• get_single_scale
• print_sdata_size_summary
• get_element_bytes
• get_transcripts_bboxes
• get_ome_metadata

utils/sdata/file_ops.py

Move from sd_utils.py:

• load_dataset_json
• get_dataset_paths
• cleanup_core_dumps
• move_bundle_sections
• move_sections_to_final_folder

utils/sdata/__init__.py

Re-export everything from all four submodules so that from xenium_analysis_tools.utils.sdata import X works.

utils/__init__.py

Update to re-export the public API from the new locations.

---

Files to DELETE

• src/xenium_analysis_tools/utils/sd_utils.py
• src/xenium_analysis_tools/utils/xenium_datasets.json (moved to utils/data/)
• src/xenium_analysis_tools/utils/reference_tables/816460.ipynb (stray notebook, do not move it anywhere)
• The entire old src/xenium_analysis_tools/utils/reference_tables/ directory after moving CSVs to utils/data/reference_tables/

---

Fix env.py

get_datasets_json_path() currently reads:

return _files("xenium_analysis_tools.data").joinpath("xenium_datasets.json")

Change to:

return _files("xenium_analysis_tools.utils.data").joinpath("xenium_datasets.json")

---

Update pyproject.toml

The [tool.setuptools.package-data] section currently has:

xenium_analysis_tools = ["data/*.json"]
"xenium_analysis_tools.utils" = ["*.csv", "*.json"]

Update to:

"xenium_analysis_tools.utils.data" = ["*.json", "reference_tables/*.csv"]

(Remove the now-stale xenium_analysis_tools = ["data/*.json"] and xenium_analysis_tools.utils entries, unless there are other data files in xenium_analysis_tools/data/ — check first.)

---

Update all import sites — NO backwards-compat shim needed

src/xenium_analysis_tools/alignment/confocal.py

# old
from xenium_analysis_tools.utils.sd_utils import add_micron_coord_sys, write_sdata_elements
# new
from xenium_analysis_tools.utils.sdata.transforms import add_micron_coord_sys
from xenium_analysis_tools.utils.sdata.elements import write_sdata_elements

src/xenium_analysis_tools/alignment/zstack_alignment.py

# old
from xenium_analysis_tools.utils.sd_utils import add_micron_coord_sys
# new
from xenium_analysis_tools.utils.sdata.transforms import add_micron_coord_sys

src/xenium_analysis_tools/alignment/qc_plots.py

# old
from xenium_analysis_tools.utils.sd_utils import add_micron_coord_sys
# new
from xenium_analysis_tools.utils.sdata.transforms import add_micron_coord_sys

src/xenium_analysis_tools/alignment/coregistration.py

# old
from xenium_analysis_tools.utils.sd_utils import add_micron_coord_sys, _is_multiscale
# new
from xenium_analysis_tools.utils.sdata.transforms import add_micron_coord_sys
from xenium_analysis_tools.utils.sdata.elements import _is_multiscale

src/xenium_analysis_tools/alignment/align_sections.py

# old
from xenium_analysis_tools.utils.sd_utils import (
    add_micron_coord_sys, get_microns_scales, _is_multiscale,
    drop_sdata_elements, get_spatial_elements, get_single_scale,
    separate_chann...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created from Copilot chat.*
>