show right micron scale in the Xenium Explorer

Author: quentinblampey

docs/cli.md

@@ -41,73 +41,74 @@ $ spatialdata_xenium_explorer [OPTIONS] COMMAND [ARGS]...
 * `update-obs`: Update the cell categories for the Xenium...
 * `write`: Convert a spatialdata object to Xenium...
 
-### `write`
+### `spatialdata_xenium_explorer add-aligned`
 
-Convert a spatialdata object to Xenium Explorer's inputs
+After alignment on the Xenium Explorer, add an image to the SpatialData object
 
 **Usage**:
 
 ```console
-$ spatialdata_xenium_explorer write [OPTIONS] SDATA_PATH
+$ spatialdata_xenium_explorer add-aligned [OPTIONS] SDATA_PATH IMAGE_PATH TRANSFORMATION_MATRIX_PATH
 ```
 
 **Arguments**:
 
 * `SDATA_PATH`: Path to the SpatialData `.zarr` directory  [required]
+* `IMAGE_PATH`: Path to the image file to be added (`.ome.tif` used in the explorer during alignment)  [required]
+* `TRANSFORMATION_MATRIX_PATH`: Path to the `matrix.csv` file returned by the Explorer after alignment  [required]
 
 **Options**:
 
-* `--output-path TEXT`: Path to a directory where Xenium Explorer's outputs will be saved. By default, writes to the same path as `sdata_path` but with the `.explorer` suffix
-* `--image-key TEXT`: Name of the image of interest (key of `sdata.images`). This argument doesn't need to be provided if there is only one image.
-* `--shapes-key TEXT`: Name of the cell shapes (key of `sdata.shapes`). This argument doesn't need to be provided if there is only one shapes key or a table with only one region.
-* `--points-key TEXT`: Name of the transcripts (key of `sdata.points`). This argument doesn't need to be provided if there is only one points key.
-* `--gene-column TEXT`: Column name of the points dataframe containing the gene names
-* `--layer TEXT`: Layer of `sdata.table` where the gene counts are saved. If `None`, uses `sdata.table.X`.
-* `--lazy / --no-lazy`: If `True`, will not load the full images in memory (except if the image memory is below `ram_threshold_gb`)  [default: lazy]
-* `--ram-threshold-gb INTEGER`: Threshold (in gygabytes) from which image can be loaded in memory. If `None`, the image is never loaded in memory  [default: 4]
-* `--mode TEXT`: string that indicated which files should be created. `'-ib'` means everything except images and boundaries, while `'+tocm'` means only transcripts/observations/counts/metadata (each letter corresponds to one explorer file). By default, keeps everything
+* `--original-image-key TEXT`: Optional original-image key (of sdata.images) on which the new image will be aligned. This doesn't need to be provided if there is only one image
+* `--overwrite / --no-overwrite`: Whether to overwrite the image if existing  [default: no-overwrite]
 * `--help`: Show this message and exit.
 
-### `add-aligned`
+### `spatialdata_xenium_explorer update-obs`
 
-After alignment on the Xenium Explorer, add an image to the SpatialData object
+Update the cell categories for the Xenium Explorer's (i.e. what's in `adata.obs`). This is useful when you perform analysis and update your `AnnData` object
+
+!!! note "Usage"
+    This command should only be used if you updated `adata.obs`, after creation of the other explorer files.
 
 **Usage**:
 
 ```console
-$ spatialdata_xenium_explorer add-aligned [OPTIONS] SDATA_PATH IMAGE_PATH TRANSFORMATION_MATRIX_PATH
+$ spatialdata_xenium_explorer update-obs [OPTIONS] ADATA_PATH OUTPUT_PATH
 ```
 
 **Arguments**:
 
-* `SDATA_PATH`: Path to the SpatialData `.zarr` directory  [required]
-* `IMAGE_PATH`: Path to the image file to be added (`.ome.tif` used in the explorer during alignment)  [required]
-* `TRANSFORMATION_MATRIX_PATH`: Path to the `matrix.csv` file returned by the Explorer after alignment  [required]
+* `ADATA_PATH`: Path to the anndata file (`zarr` or `h5ad`) containing the new observations  [required]
+* `OUTPUT_PATH`: Path to the Xenium Explorer directory (it will update `analysis.zarr.zip`)  [required]
 
 **Options**:
 
-* `--original-image-key TEXT`: Optional original-image key on which the new image will be aligned. This doesn't need to be provided if there is only one image
-* `--overwrite / --no-overwrite`: Whether to overwrite the image if existing  [default: no-overwrite]
 * `--help`: Show this message and exit.
 
-### `update-obs`
-
-Update the cell categories for the Xenium Explorer's (i.e. what's in `adata.obs`). This is useful when you perform analysis and update your `AnnData` object
+### `spatialdata_xenium_explorer write`
 
-!!! note "Usage"
-    This command should only be used if you updated `adata.obs`, after creation of the other explorer files.
+Convert a spatialdata object to Xenium Explorer's inputs
 
 **Usage**:
 
 ```console
-$ spatialdata_xenium_explorer update-obs [OPTIONS] ADATA_PATH OUTPUT_PATH
+$ spatialdata_xenium_explorer write [OPTIONS] SDATA_PATH
 ```
 
 **Arguments**:
 
-* `ADATA_PATH`: Path to the anndata file (`zarr` or `h5ad`) containing the new observations  [required]
-* `OUTPUT_PATH`: Path to the Xenium Explorer directory (it will update `analysis.zarr.zip`)  [required]
+* `SDATA_PATH`: Path to the SpatialData `.zarr` directory  [required]
 
 **Options**:
 
+* `--output-path TEXT`: Path to a directory where Xenium Explorer's outputs will be saved. By default, writes to the same path as `sdata_path` but with the `.explorer` suffix
+* `--image-key TEXT`: Name of the image of interest (key of `sdata.images`). This argument doesn't need to be provided if there is only one image.
+* `--shapes-key TEXT`: Name of the cell shapes (key of `sdata.shapes`). This argument doesn't need to be provided if there is only one shapes key or a table with only one region.
+* `--points-key TEXT`: Name of the transcripts (key of `sdata.points`). This argument doesn't need to be provided if there is only one points key.
+* `--gene-column TEXT`: Column name of the points dataframe containing the gene names
+* `--pixelsize FLOAT`: Number of microns in a pixel. Invalid value can lead to inconsistent scales in the Explorer.  [default: 0.2125]
+* `--layer TEXT`: Layer of `sdata.table` where the gene counts are saved. If `None`, uses `sdata.table.X`.
+* `--lazy / --no-lazy`: If `True`, will not load the full images in memory (except if the image memory is below `ram_threshold_gb`)  [default: lazy]
+* `--ram-threshold-gb INTEGER`: Threshold (in gygabytes) from which image can be loaded in memory. If `None`, the image is never loaded in memory  [default: 4]
+* `--mode TEXT`: string that indicated which files should be created. `'-ib'` means everything except images and boundaries, while `'+tocm'` means only transcripts/observations/counts/metadata (each letter corresponds to one explorer file). By default, keeps everything
 * `--help`: Show this message and exit.

spatialdata_xenium_explorer/_constants.py

@@ -11,6 +11,7 @@ class ExplorerConstants:
     GRID_SIZE = 250
     QUALITY_SCORE = 40
     MICRONS_TO_PIXELS = 4.705882
+    PIXELS_TO_MICRONS = 0.2125
 
     COLORS = ["white", 400, 500, 600, 700]
     NUCLEUS_COLOR = "white"
@@ -71,7 +72,7 @@ def group_attrs() -> dict:
     }
 
 
-def experiment_dict(run_name: str, region_name: str, num_cells: int) -> dict:
+def experiment_dict(run_name: str, region_name: str, num_cells: int, pixelsize: float) -> dict:
     return {
         "major_version": Versions.EXPERIMENT[0],
         "minor_version": Versions.EXPERIMENT[1],
@@ -91,7 +92,7 @@ def experiment_dict(run_name: str, region_name: str, num_cells: int) -> dict:
         "panel_organism": "Human",
         "panel_num_targets_predesigned": 0,
         "panel_num_targets_custom": 0,
-        "pixel_size": 0.2125,
+        "pixel_size": pixelsize,
         "instrument_sn": "N/A",
         "instrument_sw_version": "N/A",
         "analysis_sw_version": "xenium-1.3.0.5",

spatialdata_xenium_explorer/cli/app.py

@@ -27,6 +27,10 @@ def write(
     gene_column: str = typer.Option(
         None, help="Column name of the points dataframe containing the gene names"
     ),
+    pixelsize: float = typer.Option(
+        0.2125,
+        help="Number of microns in a pixel. Invalid value can lead to inconsistent scales in the Explorer.",
+    ),
     layer: str = typer.Option(
         None,
         help="Layer of `sdata.table` where the gene counts are saved. If `None`, uses `sdata.table.X`.",
@@ -63,6 +67,7 @@ def write(
         shapes_key=shapes_key,
         points_key=points_key,
         gene_column=gene_column,
+        pixelsize=pixelsize,
         layer=layer,
         lazy=lazy,
         ram_threshold_gb=ram_threshold_gb,

spatialdata_xenium_explorer/converter.py

@@ -27,6 +27,7 @@ def write(
     shapes_key: str | None = None,
     points_key: str | None = None,
     gene_column: str | None = None,
+    pixelsize: float = 0.2125,
     layer: str | None = None,
     polygon_max_vertices: int = 13,
     lazy: bool = True,
@@ -62,6 +63,7 @@ def write(
         shapes_key: Name of the cell shapes (key of `sdata.shapes`). This argument doesn't need to be provided if there is only one shapes key or a table with only one region.
         points_key: Name of the transcripts (key of `sdata.points`). This argument doesn't need to be provided if there is only one points key.
         gene_column: Column name of the points dataframe containing the gene names.
+        pixelsize: Number of microns in a pixel. Invalid value can lead to inconsistent scales in the Explorer.
         layer: Layer of `sdata.table` where the gene counts are saved. If `None`, uses `sdata.table.X`.
         polygon_max_vertices: Maximum number of vertices for the cell polygons. A higher value will display smoother cells.
         lazy: If `True`, will not load the full images in memory (except if the image memory is below `ram_threshold_gb`).
@@ -100,25 +102,25 @@ def write(
         if sdata.table is not None:
             geo_df = geo_df.loc[adata.obs[adata.uns["spatialdata_attrs"]["instance_key"]]]
 
-        write_polygons(path, geo_df.geometry, polygon_max_vertices)
+        write_polygons(path, geo_df.geometry, polygon_max_vertices, pixelsize=pixelsize)
 
     ### Saving transcripts
     df = get_element(sdata, "points", points_key)
 
     if _should_save(mode, "t") and df is not None:
         if gene_column is not None:
             df = to_intrinsic(sdata, df, image_key)
-            write_transcripts(path, df, gene_column)
+            write_transcripts(path, df, gene_column, pixelsize=pixelsize)
         else:
             log.warn("The argument 'gene_column' has to be provided to save the transcripts")
 
     ### Saving image
     if _should_save(mode, "i"):
-        write_image(path, image, lazy=lazy, ram_threshold_gb=ram_threshold_gb)
+        write_image(path, image, lazy=lazy, ram_threshold_gb=ram_threshold_gb, pixelsize=pixelsize)
 
     ### Saving experiment.xenium file
     if _should_save(mode, "m"):
-        write_metadata(path, image_key, shapes_key, _get_n_obs(sdata, geo_df))
+        write_metadata(path, image_key, shapes_key, _get_n_obs(sdata, geo_df), pixelsize)
 
     log.info(f"Saved files in the following directory: {path}")
     log.info(f"You can open the experiment with 'open {path / FileNames.METADATA}'")
@@ -150,7 +152,12 @@ def _get_n_obs(sdata: SpatialData, geo_df: gpd.GeoDataFrame) -> int:
 
 
 def write_metadata(
-    path: str, image_key: str = "NA", shapes_key: str = "NA", n_obs: int = 0, is_dir: bool = True
+    path: str,
+    image_key: str = "NA",
+    shapes_key: str = "NA",
+    n_obs: int = 0,
+    is_dir: bool = True,
+    pixelsize: float = 0.2125,
 ):
     """Create an `experiment.xenium` file that can be open by the Xenium Explorer.
 
@@ -163,9 +170,10 @@ def write_metadata(
         shapes_key: Key of `SpatialData` object containing the boundaries shown on the explorer.
         n_obs: Number of cells
         is_dir: If `False`, then `path` is a path to a single file, not to the Xenium Explorer directory.
+        pixelsize: Number of microns in a pixel. Invalid value can lead to inconsistent scales in the Explorer.
     """
     path = explorer_file_path(path, FileNames.METADATA, is_dir)
 
     with open(path, "w") as f:
-        metadata = experiment_dict(image_key, shapes_key, n_obs)
+        metadata = experiment_dict(image_key, shapes_key, n_obs, pixelsize)
         json.dump(metadata, f, indent=4)

spatialdata_xenium_explorer/core/points.py

@@ -23,6 +23,7 @@ def write_transcripts(
     gene: str = "gene",
     max_levels: int = 15,
     is_dir: bool = True,
+    pixelsize: float = 0.2125,
 ):
     """Write a `transcripts.zarr.zip` file containing pyramidal transcript locations
 
@@ -32,17 +33,19 @@ def write_transcripts(
         gene: Column of `df` containing the genes names.
         max_levels: Maximum number of levels in the pyramid.
         is_dir: If `False`, then `path` is a path to a single file, not to the Xenium Explorer directory.
+        pixelsize: Number of microns in a pixel. Invalid value can lead to inconsistent scales in the Explorer.
     """
     path = explorer_file_path(path, FileNames.POINTS, is_dir)
 
     # TODO: make everything using dask instead of pandas
     df = df.compute()
 
     num_transcripts = len(df)
+    grid_size = ExplorerConstants.GRID_SIZE / ExplorerConstants.PIXELS_TO_MICRONS * pixelsize
     df[gene] = df[gene].astype("category")
 
     location = df[["x", "y"]]
-    location /= ExplorerConstants.MICRONS_TO_PIXELS
+    location *= pixelsize
     location = np.concatenate([location, np.zeros((num_transcripts, 1))], axis=1)
 
     if location.min() < 0:
@@ -84,7 +87,7 @@ def write_transcripts(
     GRIDS_ATTRS = {
         "grid_key_names": ["grid_x_loc", "grid_y_loc"],
         "grid_zip": False,
-        "grid_size": [ExplorerConstants.GRID_SIZE],
+        "grid_size": [grid_size],
         "grid_array_shapes": [],
         "grid_number_objects": [],
         "grid_keys": [],
@@ -100,7 +103,7 @@ def write_transcripts(
             log.info(f"   > Level {level}: {len(location)} transcripts")
             level_group = grids.create_group(level)
 
-            tile_size = ExplorerConstants.GRID_SIZE * 2**level
+            tile_size = grid_size * 2**level
 
             indices = np.floor(location[:, :2] / tile_size).clip(0).astype(int)
             tiles_str_indices = np.array([f"{tx},{ty}" for (tx, ty) in indices])

spatialdata_xenium_explorer/core/shapes.py

@@ -45,7 +45,11 @@ def pad_polygon(
 
 
 def write_polygons(
-    path: Path, polygons: Iterable[Polygon], max_vertices: int, is_dir: bool = True
+    path: Path,
+    polygons: Iterable[Polygon],
+    max_vertices: int,
+    is_dir: bool = True,
+    pixelsize: float = 0.2125,
 ) -> None:
     """Write a `cells.zarr.zip` file containing the cell polygonal boundaries
 
@@ -54,12 +58,13 @@ def write_polygons(
         polygons: A list of `shapely` polygons to be written
         max_vertices: The number of vertices per polygon (they will be transformed to have the right number of vertices)
         is_dir: If `False`, then `path` is a path to a single file, not to the Xenium Explorer directory.
+        pixelsize: Number of microns in a pixel. Invalid value can lead to inconsistent scales in the Explorer.
     """
     path = explorer_file_path(path, FileNames.SHAPES, is_dir)
 
     log.info(f"Writing {len(polygons)} cell polygons")
     coordinates = np.stack([pad_polygon(p, max_vertices) for p in polygons])
-    coordinates /= ExplorerConstants.MICRONS_TO_PIXELS
+    coordinates *= pixelsize
 
     num_cells = len(coordinates)
     cells_fourth = ceil(num_cells / 4)