thyra 3.2.0__tar.gz → 3.2.2__tar.gz

{thyra-3.2.0 → thyra-3.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thyra
-Version: 3.2.0
+Version: 3.2.2
 Summary: A modern Python library for converting Mass Spectrometry Imaging (MSI) data into SpatialData/Zarr format - your portal to spatial omics
 License: MIT
 License-File: LICENSE

{thyra-3.2.0 → thyra-3.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "thyra"
-version = "3.2.0"
+version = "3.2.2"
 description = "A modern Python library for converting Mass Spectrometry Imaging (MSI) data into SpatialData/Zarr format - your portal to spatial omics"
 authors = ["Theodoros Visvikis <t.visvikis@maastrichtuniversity.nl>"]
 maintainers = ["Theodoros Visvikis <t.visvikis@maastrichtuniversity.nl>"]

{thyra-3.2.0 → thyra-3.2.2}/thyra/__init__.py

@@ -36,7 +36,7 @@ warnings.filterwarnings(
     category=FutureWarning,
 )
 
-__version__ = "3.2.0"
+__version__ = "3.2.2"
 
 # Import key components - avoid wildcard imports
 try:

{thyra-3.2.0 → thyra-3.2.2}/thyra/converters/spatialdata/base_spatialdata_converter.py

@@ -151,7 +151,7 @@ try:
     import xarray as xr
     import zarr
     from anndata import AnnData
-    from shapely.geometry import Polygon, box
+    from shapely.geometry import box
     from spatialdata import SpatialData
     from spatialdata.models import Image2DModel, ShapesModel, TableModel
     from spatialdata.transformations import Affine, Identity, Scale, Sequence
@@ -1509,48 +1509,63 @@ class BaseSpatialDataConverter(BaseMSIConverter, ABC):
 
         coo_arrays["current_idx"] = end_idx
 
-    def _create_pixel_shapes(
-        self, adata: AnnData, is_3d: bool = False
-    ) -> "ShapesModel":
+    def _create_pixel_shapes(self, adata: AnnData) -> "ShapesModel":
         """Create geometric shapes for pixels with proper transformations.
 
         When optical alignment is available (FlexImaging with Area definitions),
         shapes are created in optical image pixel coordinates for proper overlay.
         Otherwise, shapes use physical (micrometer) coordinates.
 
-        For a multi-slice volume the footprints are ``POLYGON Z``: a flat
-        square at the micrometre depth of the slice it was acquired on,
-        taken from ``obs["spatial_z"]``. They are footprints, not voxels --
-        shapely has no solid, so a pixel is its square at one depth rather
-        than a box spanning the slice thickness.
-
-        Two alternatives were measured and rejected:
-
+        **Footprints are two-dimensional, including on a multi-slice
+        volume.** A slice's depth is carried by the TIC image's ``Scale``
+        and by ``obs["spatial_z"]``; it is deliberately not also put on
+        the polygon geometry.
+
+        Three options were measured. All three are imperfect, so what
+        follows is the reasoning rather than a claim that this one is
+        free:
+
+        * **``POLYGON Z``** -- geometrically the most honest, and what
+          7317792 shipped in v3.2.0. It breaks ``spatialdata``'s spatial
+          queries: measured on a 5x3x2 volume, a bounding box enclosing
+          the whole dataset with 1000um of margin returned 26 of 30
+          footprints and 26 of 30 table rows, with no exception and no
+          warning. ``shapely.force_2d`` on the same geometry restored
+          30 of 30. A z-restricted query returned the same rows whether
+          z was inside or far outside the data, so z is ignored by the
+          query path rather than honoured.
         * **Flat 2D shapes carrying the depth in a transformation**
-          (one element per slice, each with a ``Translation`` in z). This
-          is what spatialdata's 2D shapes model invites, and it does not
-          work: the element parses without complaint, coexists with a 3D
-          image and round-trips, but the transform **silently drops z**
-          and every slice comes back at the same depth. It would put a
-          depth in the metadata that never reaches the geometry.
-        * **Leaving them flat** and documenting it. Honest, but then
-          ``docs/coordinate-systems.md``'s promise that every element
-          agrees at ``"global"`` stays false in z.
-
-        The cost of the choice: ``ShapesModel.parse``/``validate`` and
-        every downstream ``transform`` emit a ``UserWarning`` that 2
-        dimensions are expected. It is left unsuppressed deliberately --
-        it is upstream telling consumers this is outside the model, and
-        hiding it would be Thyra deciding that on their behalf. Only the
-        micrometre branch gains z; under optical alignment the frame is
-        optical pixels, which have no depth calibration to place a slice
-        in.
+          (one element per slice, each with a ``Translation`` in z).
+          The element parses, coexists with a 3D image and round-trips,
+          but the transform **silently drops z** and every slice comes
+          back at the same depth -- a depth in the metadata that never
+          reaches the geometry. ``test_3d_pixel_shapes_z.py`` pins this,
+          because it is the change someone will otherwise propose.
+        * **Flat, with the depth on the image and in ``obs`` only** --
+          what this does.
+
+        The deciding argument is that ``spatialdata`` itself asks for
+        this. ``ShapesModel.validate`` warns that a 3-dimensional
+        geometry column "could led to unexpected behaviors" and names
+        ``force_2d()`` as the remedy; the query result above is that
+        behaviour. 3D shapes are not on the upstream roadmap
+        (scverse/spatialdata#109 has been idle since June 2023 and
+        covers images, labels and transformations only), and the live
+        2.5D discussion (#961) scopes itself to points, images and
+        labels. Serial-section MSI is 2.5D in that taxonomy.
+
+        What this costs: ``docs/coordinate-systems.md``'s promise that
+        every element agrees at ``"global"`` is exact in x and y and
+        silent in z for the shapes element. That is a documented gap
+        rather than a wrong answer, which a truncated query is not. See
+        ``docs/output-format.md`` for the consumer-facing statement.
+
+        Reinstating z means restoring the ``is_3d`` parameter at all
+        three call sites as well; it was removed with the geometry so it
+        could not sit unread, which is how the original defect arose.
 
         Args:
             adata: AnnData object containing coordinates
-            is_3d: Whether this is the 3D volume route. Combined with
-                :attr:`_is_volume` (which also requires more than one
-                plane), decides whether footprints carry z.
 
         Returns:
             SpatialData shapes model
@@ -1628,29 +1643,15 @@ class BaseSpatialDataConverter(BaseMSIConverter, ABC):
             y_coords: NDArray[np.float64] = adata.obs["spatial_y"].values
             half_pixel_um = self.pixel_size_um / 2
 
-            # A volume's footprints carry the depth of the slice they were
-            # acquired on, so they meet the TIC volume at "global" instead
-            # of stacking flat at z=0. spatial_z is already the micrometre
-            # depth (z index * z_spacing_um), so it needs no scaling here
-            # -- the same column the table stores, which is what keeps the
-            # two elements agreeing.
-            z_coords: Optional[NDArray[np.float64]] = None
-            if is_3d and self._is_volume:
-                z_coords = adata.obs["spatial_z"].values
-
+            # Footprints are flat, on every route including volumes. A
+            # slice's depth lives on the TIC image's Scale and in
+            # obs["spatial_z"]; see the docstring for why it is not also
+            # put on the geometry.
             for i in range(len(adata)):
                 x, y = x_coords[i], y_coords[i]
                 x0, y0 = x - half_pixel_um, y - half_pixel_um
                 x1, y1 = x + half_pixel_um, y + half_pixel_um
-
-                if z_coords is None:
-                    pixel_box = box(x0, y0, x1, y1)
-                else:
-                    z = float(z_coords[i])
-                    pixel_box = Polygon(
-                        [(x0, y0, z), (x1, y0, z), (x1, y1, z), (x0, y1, z)]
-                    )
-                geometries.append(pixel_box)
+                geometries.append(box(x0, y0, x1, y1))
 
         # Create GeoDataFrame with appropriate index
         if valid_indices is not None:

{thyra-3.2.0 → thyra-3.2.2}/thyra/converters/spatialdata/spatialdata_2d_converter.py

@@ -328,9 +328,7 @@ class SpatialData2DConverter(BaseSpatialDataConverter):
 
                 # Add to tables and create shapes
                 data_structures["tables"][slice_id] = table
-                data_structures["shapes"][region_key] = self._create_pixel_shapes(
-                    adata, is_3d=False
-                )
+                data_structures["shapes"][region_key] = self._create_pixel_shapes(adata)
 
                 # Create TIC image for this slice
                 tic_values = slice_data["tic_values"]

{thyra-3.2.0 → thyra-3.2.2}/thyra/converters/spatialdata/spatialdata_3d_converter.py

@@ -246,9 +246,7 @@ class SpatialData3DConverter(BaseSpatialDataConverter):
 
             # Add to tables and create shapes
             data_structures["tables"][self.dataset_id] = table
-            data_structures["shapes"][region_key] = self._create_pixel_shapes(
-                adata, is_3d=True
-            )
+            data_structures["shapes"][region_key] = self._create_pixel_shapes(adata)
 
             # Create TIC image
             self._create_tic_image(data_structures)

{thyra-3.2.0 → thyra-3.2.2}/thyra/converters/spatialdata/streaming_converter.py

@@ -1004,9 +1004,7 @@ class StreamingSpatialDataConverter(BaseSpatialDataConverter):
 
                 # Add to tables and create shapes
                 data_structures["tables"][slice_id] = table
-                data_structures["shapes"][region_key] = self._create_pixel_shapes(
-                    adata, is_3d=False
-                )
+                data_structures["shapes"][region_key] = self._create_pixel_shapes(adata)
 
                 # Create TIC image for this slice
                 tic_values = slice_data["tic_values"]
@@ -1278,18 +1276,28 @@ class StreamingSpatialDataConverter(BaseSpatialDataConverter):
 
                 nnz = len(mz_indices)
                 if nnz > 0:
-                    # Count entries per column (vectorized)
-                    np.add.at(col_counts, mz_indices, 1)
-                    total_nnz += nnz
-
-                    # Accumulate for average spectrum (vectorized)
+                    # Accumulate for average spectrum (vectorized). Left
+                    # outside the bounds check to match the COO pre-scan,
+                    # which also averages over every spectrum read rather
+                    # than every spectrum stored.
                     np.add.at(total_intensity, mz_indices, resampled_ints)
 
-                    # TIC and occupancy. Both are indexed by grid position,
-                    # so both need the bounds check: a reader yielding a
+                    # Column counts, TIC and occupancy all describe a
+                    # spectrum that is going to get a row, so all three sit
+                    # behind the bounds check: a reader yielding a
                     # coordinate outside the declared dimensions would
                     # otherwise wrap round and land on an unrelated pixel.
+                    #
+                    # col_counts and total_nnz size the CSC arrays, and the
+                    # scatter pass skips exactly the spectra this rejects
+                    # (row_of_grid gives them no row). Counting them here
+                    # reserved slots nothing ever wrote: the memmap is
+                    # zero-filled, so they surfaced as explicit zeros at
+                    # row 0, out of order within their column, which is a
+                    # matrix scipy reports as non-canonical.
                     if 0 <= y < n_y and 0 <= x < n_x:
+                        np.add.at(col_counts, mz_indices, 1)
+                        total_nnz += nnz
                         tic_values[y, x] = resampled_ints.sum()
                         occupancy[y * n_x + x] = True
                     else: