diff --git a/CHANGELOG.md b/CHANGELOG.md index be64b3f1..40115606 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,49 +15,54 @@ and this project adheres to [Semantic Versioning][]. #### Major - Implemented support in `SpatialData` for storing multiple tables. - - These tables can annotate a `SpatialElement` but now not necessarily so. - - Deprecated `.table` attribute in favor of `.tables` dict-like accessor. +- These tables can annotate a `SpatialElement` but now not necessarily so. +- Deprecated `.table` attribute in favor of `.tables` dict-like accessor. + - Added join operations - - Added SQL like joins that can be executed by calling one public function `join_sdata_spatialelement_table`. The following joins are supported: `left`, `left_exclusive`, `right`, `right_exclusive` and `inner`. The function has an option to match rows. For `left` only matching `left` is supported and for `right` join only `right` matching of rows is supported. Not all joins are supported for `Labels` elements. - - Added function `match_element_to_table` which allows the user to perform a right join of `SpatialElement`(s) with a table with rows matching the row order in the table. +- Added SQL like joins that can be executed by calling one public function `join_sdata_spatialelement_table`. The following joins are supported: `left`, `left_exclusive`, `right`, `right_exclusive` and `inner`. The function has an option to match rows. For `left` only matching `left` is supported and for `right` join only `right` matching of rows is supported. Not all joins are supported for `Labels` elements. +- Added function `match_element_to_table` which allows the user to perform a right join of `SpatialElement`(s) with a table with rows matching the row order in the table. + - Incremental IO of data and metadata: - - Increased in-memory vs on-disk control: changes performed in-memory (e.g. adding a new image) are not automatically performed on-disk. - - Deprecated `add_image()`, `add_labels()`, `add_shapes()`, `add_points()` in favor of `.images`, `.labels`, `.shapes`, `.points` dict-like accessors. - - new methods `write_element()`, `write_transformations()`, `write_metadata()`, `remove_element_from_disk()` - - new methods `write_consolidated_metadata()` and `has_consolidated_metadata()` - - deprecated `save_transformations()` - - improved `__repr__()` with information on Zarr storage and Dask-backed files - - new utils `is_self_contained()`, `describe_elements_are_self_contained()` - - new utils `element_paths_in_memory()`, `element_paths_on_disk()` +- Increased in-memory vs on-disk control: changes performed in-memory (e.g. adding a new image) are not automatically performed on-disk. +- Deprecated `add_image()`, `add_labels()`, `add_shapes()`, `add_points()` in favor of `.images`, `.labels`, `.shapes`, `.points` dict-like accessors. +- new methods `write_element()`, `write_transformations()`, `write_metadata()`, `remove_element_from_disk()` +- new methods `write_consolidated_metadata()` and `has_consolidated_metadata()` +- deprecated `save_transformations()` +- improved `__repr__()` with information on Zarr storage and Dask-backed files +- new utils `is_self_contained()`, `describe_elements_are_self_contained()` +- new utils `element_paths_in_memory()`, `element_paths_on_disk()` #### Minor - Multiple table helper functions - - Added public helper function `get_table_keys()` in `spatialdata.models` to retrieve annotation information of a given table. - - Added public helper function `check_target_region_column_symmetry()` in `spatialdata.models` to check whether annotation - metadata in `table.uns['spatialdata_attrs']` corresponds with respective columns in `table.obs`. - - Added function `validate_table_in_spatialdata()` in SpatialData to validate the annotation target of a table being present in the `SpatialData` object. - - Added method `get_annotated_regions()` in `SpatialData` to get the regions annotated by a given table. - - Added method `get_region_key_column()` in `SpatialData` to get the region_key column in table.obs. - - Added method `get_instance_key_column()` in `SpatialData` to get the instance_key column in table.obs. - - Added method `set_table_annotates_spatialelement()` in `SpatialData` to either set or change the annotation metadata of a table in a given `SpatialData` object. - Added `table_name` parameter to the `aggregate()` function to allow users to give a custom table name to table resulting from aggregation. - - Added `table_name` parameter to the `get_values()` function. +- Added public helper function `get_table_keys()` in `spatialdata.models` to retrieve annotation information of a given table. +- Added public helper function `check_target_region_column_symmetry()` in `spatialdata.models` to check whether annotation + metadata in `table.uns['spatialdata_attrs']` corresponds with respective columns in `table.obs`. +- Added function `validate_table_in_spatialdata()` in SpatialData to validate the annotation target of a table being present in the `SpatialData` object. +- Added method `get_annotated_regions()` in `SpatialData` to get the regions annotated by a given table. +- Added method `get_region_key_column()` in `SpatialData` to get the region_key column in table.obs. +- Added method `get_instance_key_column()` in `SpatialData` to get the instance_key column in table.obs. +- Added method `set_table_annotates_spatialelement()` in `SpatialData` to either set or change the annotation metadata of a table in a given `SpatialData` object. - Added `table_name` parameter to the `aggregate()` function to allow users to give a custom table name to table resulting from aggregation. +- Added `table_name` parameter to the `get_values()` function. + - Utils - - Added `gen_spatial_elements()` generator in SpatialData to generate the `SpatialElements` in a given `SpatialData` object. - - Added `gen_elements` generator in `SpatialData` to generate elements of a `SpatialData` object including tables. - - added `SpatialData.subset()` API - - added `SpatialData.locate_element()` API - - added utils function: `get_centroids()` - - added utils function: `deepcopy()` - - added operation: `to_circles()` - - documented previously-added `get_channels()` to retrieve the channel names of a raster element indepently of it being single or multi-scale +- Added `gen_spatial_elements()` generator in SpatialData to generate the `SpatialElements` in a given `SpatialData` object. +- Added `gen_elements` generator in `SpatialData` to generate elements of a `SpatialData` object including tables. +- added `SpatialData.subset()` API +- added `SpatialData.locate_element()` API +- added utils function: `get_centroids()` +- added utils function: `deepcopy()` +- added operation: `to_circles()` +- documented previously-added `get_channels()` to retrieve the channel names of a raster element indepently of it being single or multi-scale + - Transformations-related + - added utils function: `transform_to_data_extent()` - added utils function: `are_extents_equal()` - added utils function: `postpone_transformation()` - added utils function: `remove_transformations_to_coordinate_system()` -- added testing utilities: `assert_spatial_data_objects_are_identical()`, `assert_elements_are_identical()`, - `assert_elements_dict_are_identical()` + +- added testing utilities: `assert_spatial_data_objects_are_identical()`, `assert_elements_are_identical()`, `assert_elements_dict_are_identical()` ### Changed/fixed @@ -69,8 +74,7 @@ and this project adheres to [Semantic Versioning][]. #### Minor -- Changed the string representation of `SpatialData` to reflect the changes in regard to multiple tables and - incremental IO. +- Changed the string representation of `SpatialData` to reflect the changes in regard to multiple tables and incremental IO. - improved usability and robustness of `sdata.write()` when `overwrite=True` @aeisenbarth - fixed warnings for categorical dtypes in tables in `TableModel` and `PointsModel` - fixed wrong order of points after spatial queries diff --git a/src/spatialdata/_core/spatialdata.py b/src/spatialdata/_core/spatialdata.py index f5172544..59489a44 100644 --- a/src/spatialdata/_core/spatialdata.py +++ b/src/spatialdata/_core/spatialdata.py @@ -1179,15 +1179,15 @@ def delete_element_from_disk(self, element_name: str) -> None: ----- In general, it is not recommended to delete an element from the Zarr store with the intention of saving an updated version of the element that is available only in-memory. This is because data loss may occur if the - execution is interrupted during writing. + execution is interrupted during writing. Here are some recommendations: - the above scenario may be acceptable when the element to save can be easily recreated from the data; - if data recreation is not possible or computationally expensive, it is recommended to first save the - element to a different location and then eventually copy it to the original desired location. Please - note that this approach is not guaranteed to be always safe (e.g. if multiple processes are trying to - write to the same Zarr store simultaneously, then the backup data may become corrupted). + element to a different location and then eventually copy it to the original desired location. Please + note that this approach is not guaranteed to be always safe (e.g. if multiple processes are trying to + write to the same Zarr store simultaneously, then the backup data may become corrupted). Ultimately, it is the responsibility of the user to consider the implications of the current computational environment (e.g. operating system, local vs network storage, file permissions, ...) and call this function diff --git a/src/spatialdata/dataloader/datasets.py b/src/spatialdata/dataloader/datasets.py index fb1ae955..9c028906 100644 --- a/src/spatialdata/dataloader/datasets.py +++ b/src/spatialdata/dataloader/datasets.py @@ -61,13 +61,13 @@ class ImageTilesDataset(Dataset): tile_scale This parameter is used to determine the size (width and height) of the tiles. Each tile will have size in units equal to tile_scale times the diameter of the circle that approximates (=same - area) the region that defines the tile. + area) the region that defines the tile. For example, suppose the regions to be multiscale labels; this is how the tiles are created: 1) for each tile, each label region is approximated with a circle with the same area of the label region. 2) The tile is then created as having the width/height equal to the diameter of the circle, - multiplied by `tile_scale`. + multiplied by `tile_scale`. If `tile_dim_in_units` is passed, `tile_scale` is ignored. tile_dim_in_units