From d03f9a3e3b3f5ee2c494003c4900779518879ea7 Mon Sep 17 00:00:00 2001 From: Blampey Quentin Date: Wed, 13 Nov 2024 18:51:10 +0100 Subject: [PATCH] adding glossary + refactor API reference display --- .gitignore | 6 +- docs/api.md | 242 +----------------- docs/api/SpatialData.md | 8 + docs/api/data_formats.md | 36 +++ docs/api/dataloader.md | 8 + docs/api/datasets.md | 11 + docs/api/io.md | 11 + docs/api/models.md | 29 +++ docs/api/models_utils.md | 14 + docs/api/operations.md | 30 +++ docs/api/testing.md | 9 + docs/api/transformations.md | 29 +++ docs/api/transformations_utils.md | 13 + docs/conf.py | 1 + docs/glossary.md | 33 +++ docs/index.md | 1 + docs/installation.md | 6 +- .../transformations/transformations.py | 9 + 18 files changed, 262 insertions(+), 234 deletions(-) create mode 100644 docs/api/SpatialData.md create mode 100644 docs/api/data_formats.md create mode 100644 docs/api/dataloader.md create mode 100644 docs/api/datasets.md create mode 100644 docs/api/io.md create mode 100644 docs/api/models.md create mode 100644 docs/api/models_utils.md create mode 100644 docs/api/operations.md create mode 100644 docs/api/testing.md create mode 100644 docs/api/transformations.md create mode 100644 docs/api/transformations_utils.md create mode 100644 docs/glossary.md diff --git a/.gitignore b/.gitignore index 328be6b2..9ec77074 100644 --- a/.gitignore +++ b/.gitignore @@ -17,7 +17,9 @@ __pycache__/ /data/ # docs -/docs +docs/_build +!docs/api/.md +docs/**/generated # IDEs /.idea/ @@ -29,8 +31,6 @@ __pycache__/ # temp files temp/ -# rst generated from myst -docs/generated # symlinks (luca) for extending the refactoring to satellite projects napari-spatialdata diff --git a/docs/api.md b/docs/api.md index 23312c9b..15a0096e 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,231 +1,17 @@ # API -```{eval-rst} -.. module:: spatialdata +```{toctree} +:maxdepth: 1 + +api/SpatialData.md +api/io.md +api/operations.md +api/transformations.md +api/transformations_utils.md +api/datasets.md +api/dataloader.md +api/models.md +api/models_utils.md +api/testing.md +api/data_formats.md ``` - -## SpatialData - -The `SpatialData` class (follow the link to explore its methods). - -```{eval-rst} -.. autosummary:: - :toctree: generated - - SpatialData -``` - -## Operations - -Operations on `SpatialData` objects. - -```{eval-rst} -.. autosummary:: - :toctree: generated - - bounding_box_query - polygon_query - get_values - get_element_instances - get_extent - get_centroids - join_spatialelement_table - match_element_to_table - get_centroids - match_table_to_element - concatenate - transform - rasterize - rasterize_bins - to_circles - to_polygons - aggregate - map_raster -``` - -### Operations Utilities - -```{eval-rst} -.. autosummary:: - :toctree: generated - - unpad_raster - are_extents_equal - deepcopy - get_pyramid_levels -``` - -## Models - -The elements (building-blocks) that constitute `SpatialData`. - -```{eval-rst} -.. currentmodule:: spatialdata.models - -.. autosummary:: - :toctree: generated - - Image2DModel - Image3DModel - Labels2DModel - Labels3DModel - ShapesModel - PointsModel - TableModel -``` - -### Models Utilities - -```{eval-rst} -.. currentmodule:: spatialdata.models - -.. autosummary:: - :toctree: generated - - get_model - SpatialElement - get_axes_names - get_spatial_axes - points_geopandas_to_dask_dataframe - points_dask_dataframe_to_geopandas - get_channels - force_2d -``` - -## Transformations - -The transformations that can be defined between elements and coordinate systems in `SpatialData`. - -```{eval-rst} -.. currentmodule:: spatialdata.transformations - -.. autosummary:: - :toctree: generated - - BaseTransformation - Identity - MapAxis - Translation - Scale - Affine - Sequence -``` - -### Transformations Utilities - -```{eval-rst} -.. currentmodule:: spatialdata.transformations - -.. autosummary:: - :toctree: generated - - get_transformation - set_transformation - remove_transformation - get_transformation_between_coordinate_systems - get_transformation_between_landmarks - align_elements_using_landmarks - remove_transformations_to_coordinate_system -``` - -## DataLoader - -```{eval-rst} -.. currentmodule:: spatialdata.dataloader - -.. autosummary:: - :toctree: generated - - ImageTilesDataset -``` - -## Input/Output - -```{eval-rst} -.. currentmodule:: spatialdata - -.. autosummary:: - :toctree: generated - - read_zarr - save_transformations - get_dask_backing_files -``` - -## Testing utilities - -```{eval-rst} -.. currentmodule:: spatialdata.testing - -.. autosummary:: - :toctree: generated - - assert_spatial_data_objects_are_identical - assert_elements_are_identical - assert_elements_dict_are_identical -``` - -## Datasets - -Convenience small datasets - -```{eval-rst} -.. currentmodule:: spatialdata.datasets - -.. autosummary:: - :toctree: generated - - blobs - blobs_annotating_element - raccoon - -``` - -## Data format (advanced topic) - -The SpatialData format is defined as a set of versioned subclasses of :class:`spatialdata._io.format.SpatialDataFormat`, one per type of element. -These classes are useful to ensure backward compatibility whenever a major version change is introduced. We also provide pointers to the latest format. - -### Raster format - -```{eval-rst} -.. currentmodule:: spatialdata._io.format - -.. autosummary:: - :toctree: generated - - CurrentRasterFormat - RasterFormatV01 -``` - -### Shapes format - -```{eval-rst} -.. autosummary:: - :toctree: generated - - CurrentShapesFormat - ShapesFormatV01 - ShapesFormatV02 -``` - -### Points format - -```{eval-rst} -.. autosummary:: - :toctree: generated - - CurrentPointsFormat - PointsFormatV01 -``` - -### Tables format - -```{eval-rst} -.. autosummary:: - :toctree: generated - - CurrentTablesFormat - TablesFormatV01 -``` - diff --git a/docs/api/SpatialData.md b/docs/api/SpatialData.md new file mode 100644 index 00000000..da96ecf9 --- /dev/null +++ b/docs/api/SpatialData.md @@ -0,0 +1,8 @@ +## SpatialData object + +```{eval-rst} +.. currentmodule:: spatialdata + +.. autoclass:: SpatialData + :members: +``` diff --git a/docs/api/data_formats.md b/docs/api/data_formats.md new file mode 100644 index 00000000..40de781b --- /dev/null +++ b/docs/api/data_formats.md @@ -0,0 +1,36 @@ +## Data formats (advanced) + +The SpatialData format is defined as a set of versioned subclasses of `spatialdata._io.format.SpatialDataFormat`, one per type of element. +These classes are useful to ensure backward compatibility whenever a major version change is introduced. We also provide pointers to the latest format. + +```{eval-rst} +.. currentmodule:: spatialdata._io.format + +.. autoclass:: CurrentRasterFormat + :members: + :undoc-members: +.. autoclass:: RasterFormatV01 + :members: + :undoc-members: +.. autoclass:: CurrentShapesFormat + :members: + :undoc-members: +.. autoclass:: ShapesFormatV01 + :members: + :undoc-members: +.. autoclass:: ShapesFormatV02 + :members: + :undoc-members: +.. autoclass:: CurrentPointsFormat + :members: + :undoc-members: +.. autoclass:: PointsFormatV01 + :members: + :undoc-members: +.. autoclass:: CurrentTablesFormat + :members: + :undoc-members: +.. autoclass:: TablesFormatV01 + :members: + :undoc-members: +``` diff --git a/docs/api/dataloader.md b/docs/api/dataloader.md new file mode 100644 index 00000000..c97a26d8 --- /dev/null +++ b/docs/api/dataloader.md @@ -0,0 +1,8 @@ +## Data Loaders + +```{eval-rst} +.. currentmodule:: spatialdata.dataloader + +.. autoclass:: ImageTilesDataset + :members: +``` diff --git a/docs/api/datasets.md b/docs/api/datasets.md new file mode 100644 index 00000000..e31b4415 --- /dev/null +++ b/docs/api/datasets.md @@ -0,0 +1,11 @@ +## Datasets + +Convenience small datasets + +```{eval-rst} +.. currentmodule:: spatialdata.datasets + +.. autofunction:: blobs +.. autofunction:: blobs_annotating_element +.. autofunction:: raccoon +``` diff --git a/docs/api/io.md b/docs/api/io.md new file mode 100644 index 00000000..02d03fd9 --- /dev/null +++ b/docs/api/io.md @@ -0,0 +1,11 @@ +## Input/Output + +To read the data from a specific technology (e.g., Xenium, MERSCOPE, ...), you can use any of the [spatialdata-io readers](https://spatialdata.scverse.org/projects/io/en/latest/api.html). + +```{eval-rst} +.. currentmodule:: spatialdata + +.. autofunction:: read_zarr +.. autofunction:: save_transformations +.. autofunction:: get_dask_backing_files +``` diff --git a/docs/api/models.md b/docs/api/models.md new file mode 100644 index 00000000..1b9685d4 --- /dev/null +++ b/docs/api/models.md @@ -0,0 +1,29 @@ +## Models + +The elements (building-blocks) that constitute `SpatialData`. + +```{eval-rst} +.. currentmodule:: spatialdata.models + +.. autoclass:: Image2DModel + :members: + :undoc-members: +.. autoclass:: Image3DModel + :members: + :undoc-members: +.. autoclass:: Labels2DModel + :members: + :undoc-members: +.. autoclass:: Labels3DModel + :members: + :undoc-members: +.. autoclass:: ShapesModel + :members: + :undoc-members: +.. autoclass:: PointsModel + :members: + :undoc-members: +.. autoclass:: TableModel + :members: + :undoc-members: +``` diff --git a/docs/api/models_utils.md b/docs/api/models_utils.md new file mode 100644 index 00000000..62b76423 --- /dev/null +++ b/docs/api/models_utils.md @@ -0,0 +1,14 @@ +## Models utils + +```{eval-rst} +.. currentmodule:: spatialdata.models + +.. autofunction:: get_model +.. autofunction:: SpatialElement +.. autofunction:: get_axes_names +.. autofunction:: get_spatial_axes +.. autofunction:: points_geopandas_to_dask_dataframe +.. autofunction:: points_dask_dataframe_to_geopandas +.. autofunction:: get_channels +.. autofunction:: force_2d +``` diff --git a/docs/api/operations.md b/docs/api/operations.md new file mode 100644 index 00000000..0c7fe01c --- /dev/null +++ b/docs/api/operations.md @@ -0,0 +1,30 @@ +## Operations + +Operations on `SpatialData` objects. + +```{eval-rst} +.. module:: spatialdata + +.. autofunction:: bounding_box_query +.. autofunction:: polygon_query +.. autofunction:: get_values +.. autofunction:: get_element_instances +.. autofunction:: get_extent +.. autofunction:: get_centroids +.. autofunction:: join_spatialelement_table +.. autofunction:: match_element_to_table +.. autofunction:: get_centroids +.. autofunction:: match_table_to_element +.. autofunction:: concatenate +.. autofunction:: transform +.. autofunction:: rasterize +.. autofunction:: rasterize_bins +.. autofunction:: to_circles +.. autofunction:: to_polygons +.. autofunction:: aggregate +.. autofunction:: map_raster +.. autofunction:: unpad_raster +.. autofunction:: are_extents_equal +.. autofunction:: deepcopy +.. autofunction:: get_pyramid_levels +``` diff --git a/docs/api/testing.md b/docs/api/testing.md new file mode 100644 index 00000000..645eac6b --- /dev/null +++ b/docs/api/testing.md @@ -0,0 +1,9 @@ +## Testing utilities + +```{eval-rst} +.. currentmodule:: spatialdata.testing + +.. autofunction:: assert_spatial_data_objects_are_identical +.. autofunction:: assert_elements_are_identical +.. autofunction:: assert_elements_dict_are_identical +``` diff --git a/docs/api/transformations.md b/docs/api/transformations.md new file mode 100644 index 00000000..6eb3f5d4 --- /dev/null +++ b/docs/api/transformations.md @@ -0,0 +1,29 @@ +## Transformations + +The transformations that can be defined between elements and coordinate systems in `SpatialData`. + +```{eval-rst} +.. currentmodule:: spatialdata.transformations + +.. autoclass:: BaseTransformation + :members: + :undoc-members: +.. autoclass:: Identity + :members: + :undoc-members: +.. autoclass:: MapAxis + :members: + :undoc-members: +.. autoclass:: Translation + :members: + :undoc-members: +.. autoclass:: Scale + :members: + :undoc-members: +.. autoclass:: Affine + :members: + :undoc-members: +.. autoclass:: Sequence + :members: + :undoc-members: +``` diff --git a/docs/api/transformations_utils.md b/docs/api/transformations_utils.md new file mode 100644 index 00000000..3022adcb --- /dev/null +++ b/docs/api/transformations_utils.md @@ -0,0 +1,13 @@ +## Transformations utils + +```{eval-rst} +.. currentmodule:: spatialdata.transformations + +.. autofunction:: get_transformation +.. autofunction:: set_transformation +.. autofunction:: remove_transformation +.. autofunction:: get_transformation_between_coordinate_systems +.. autofunction:: get_transformation_between_landmarks +.. autofunction:: align_elements_using_landmarks +.. autofunction:: remove_transformations_to_coordinate_system +``` diff --git a/docs/conf.py b/docs/conf.py index 941c25fd..2c7f2b69 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -143,6 +143,7 @@ html_theme_options = { "navigation_with_keys": True, + "show_toc_level": 4, # "repository_url": repository_url, # "use_repository_button": True, } diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 00000000..c269a682 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,33 @@ +# Glossary + +### Spatial Element + +_Spatial Elements_ are the building blocks of _SpatialData_ datasets, and are split into multiple categories: `images`, `labels`, `shapes`, `points`, and `tables`. SpatialData elements are not special classes, but are instead standard scientific Python classes (e.g., `xarray.DataArray`, `AnnData`) with specified metadata. The metadata provides the necessary information for displaying and integrating the different elements (e.g., coordinate systems and coordinate transformations). + +### Raster / Rasterization + +Raster data represents images using a grid of pixels, where each pixel contains a specific value representing information such as color, intensity, or another attribute. + +Rasterization is the process of converting data from a vector format (see definition below) into a raster format of pixels (i.e., an image). + +### Vector / Vectorization + +Vector data represents spatial information using geometric shapes such as points, circles, or polygons, each defined by mathematical coordinates. + +Vectorization is the process of converting raster data (i.e. pixel-based images) into vector format. For instance, a "raster" cell boundary can be "vectorized" into a polygon represented by the coordinates of the vertices of the polygon. + +### IO + +IO means input/output. For instance, `spatialdata-io` is about reading and/or writing data. + +### Spatial query + +A spatial query subsets the data based on the location of the spatial elements. For example, subsetting data with a bounding box query selects elements within a defined rectangular region, while a polygon query selects data within a specified shape. + +### NGFF + +[NGFF (Next-Generation File Format)](https://ngff.openmicroscopy.org/latest/) is a specification for storing multi-dimensional, large-scale imaging and spatial data efficiently. Developed by the OME (Open Microscopy Environment), it supports formats like multi-resolution images, enabling flexible data access, high performance, and compatibility with cloud-based storage. NGFF is designed to handle modern microscopy, biomedical imaging, and other high-dimensional datasets in a scalable, standardized way, often using formats like Zarr for storage. + +### Zarr storage + +Zarr is a format for storing multi-dimensional arrays, designed for efficient, scalable access to large datasets. It supports chunking (splitting data into smaller, manageable pieces) and compression, enabling fast reading and writing of data, even for very large arrays. Zarr is particularly useful for distributed and parallel computing, allowing access to subsets of data without loading the entire dataset into memory. A `SpatialData` object can be stored as a Zarr store (`.zarr` directory). diff --git a/docs/index.md b/docs/index.md index b27ce758..8a0aff41 100644 --- a/docs/index.md +++ b/docs/index.md @@ -66,6 +66,7 @@ installation.md api.md tutorials/notebooks/notebooks.md tutorials/notebooks/datasets/README.md +glossary.md design_doc.md contributing.md changelog.md diff --git a/docs/installation.md b/docs/installation.md index 08538949..2d7d46fc 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -4,17 +4,17 @@ ## PyPI -Install `spatialdata` by running:: +Install `spatialdata` by running: ```bash pip install spatialdata ``` -## Visualization and IO +## Visualization and readers The SpatialData ecosystem is designed to work with the following packages: -- [spatialdata-io][]: `spatialdata` IO for common spatial omics technologies. +- [spatialdata-io][]: `spatialdata` readers for common spatial omics technologies. - [spatialdata-plot][]: Static plotting library for `spatialdata`. - [napari-spatialdata][]: napari plugin for `spatialdata`. diff --git a/src/spatialdata/transformations/transformations.py b/src/spatialdata/transformations/transformations.py index 585a731a..667da466 100644 --- a/src/spatialdata/transformations/transformations.py +++ b/src/spatialdata/transformations/transformations.py @@ -245,6 +245,15 @@ def __eq__(self, other: Any) -> bool: # drop axes. When convering from MapAxis to NgffMapAxis this can be done by returing a Sequence of NgffAffine and # NgffMapAxis, where the NgffAffine corrects the axes class MapAxis(BaseTransformation): + """ + Transformation that maps input axes to output axes. + + Parameters + ---------- + map_axis + Dictionnary with keys being the input axes and values the output axes. + """ + def __init__(self, map_axis: dict[ValidAxis_t, ValidAxis_t]) -> None: # to avoid circular imports from spatialdata.models import validate_axis_name