ngio 0.2.0b3__tar.gz → 0.2.1__tar.gz

{ngio-0.2.0b3 → ngio-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ngio
-Version: 0.2.0b3
+Version: 0.2.1
 Summary: Next Generation file format IO
 Project-URL: homepage, https://github.com/lorenzocerrone/ngio
 Project-URL: repository, https://github.com/lorenzocerrone/ngio
@@ -41,6 +41,8 @@ Requires-Dist: rich; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Requires-Dist: scikit-image; extra == 'dev'
 Provides-Extra: docs
+Requires-Dist: markdown-exec[ansi]; extra == 'docs'
+Requires-Dist: matplotlib; extra == 'docs'
 Requires-Dist: mike; extra == 'docs'
 Requires-Dist: mkdocs; extra == 'docs'
 Requires-Dist: mkdocs-autorefs; extra == 'docs'
@@ -49,7 +51,9 @@ Requires-Dist: mkdocs-git-revision-date-localized-plugin; extra == 'docs'
 Requires-Dist: mkdocs-jupyter; extra == 'docs'
 Requires-Dist: mkdocs-material; extra == 'docs'
 Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Requires-Dist: rich; extra == 'docs'
 Requires-Dist: scikit-image; extra == 'docs'
+Requires-Dist: tabulate; extra == 'docs'
 Provides-Extra: test
 Requires-Dist: pytest; extra == 'test'
 Requires-Dist: pytest-cov; extra == 'test'
@@ -69,9 +73,9 @@ NGIO is a Python library to streamline OME-Zarr image analysis workflows.
 **Main Goals:**
 
 - Abstract object base API for handling OME-Zarr files
-- Powefull iterators for processing data using common access patterns
+- Powerful iterators for processing data using common access patterns
 - Tight integration with [Fractal's Table Fractal](https://fractal-analytics-platform.github.io/fractal-tasks-core/tables/)
-- Validate OME-Zarr files
+- Validation of OME-Zarr files
 
 To get started, check out the [Getting Started](https://fractal-analytics-platform.github.io/ngio/getting-started/) guide. Or checkout our [Documentation](https://fractal-analytics-platform.github.io/ngio/)
 
@@ -91,10 +95,9 @@ To get started, check out the [Getting Started](https://fractal-analytics-platfo
 | Basic Iterators | Ongoing | End-September | Read and Write Iterators for common access patterns |
 | Base Documentation | ✅ | End-September | API Documentation and Examples |
 | Beta Ready Testing | ✅ | End-September | Beta Testing; Library is ready for testing, but the API is not stable |
-| Streaming from Fractal | Ongoing | December | Ngio can stream ome-zarr from fractal |
+| Streaming from Fractal | Ongoing | December | Ngio can stream OME-Zarr from fractal |
 | Mask Iterators | Ongoing | Early 2025 | Iterators over Masked Tables |
 | Advanced Iterators | Not started | mid-2025 | Iterators for advanced access patterns |
 | Parallel Iterators | Not started | mid-2025 | Concurrent Iterators for parallel read and write |
 | Full Documentation | Not started | 2025 | Complete Documentation |
 | Release 1.0 (Commitment to API) | Not started | 2025 | API is stable; breaking changes will be avoided |
-

{ngio-0.2.0b3 → ngio-0.2.1}/README.md

@@ -11,9 +11,9 @@ NGIO is a Python library to streamline OME-Zarr image analysis workflows.
 **Main Goals:**
 
 - Abstract object base API for handling OME-Zarr files
-- Powefull iterators for processing data using common access patterns
+- Powerful iterators for processing data using common access patterns
 - Tight integration with [Fractal's Table Fractal](https://fractal-analytics-platform.github.io/fractal-tasks-core/tables/)
-- Validate OME-Zarr files
+- Validation of OME-Zarr files
 
 To get started, check out the [Getting Started](https://fractal-analytics-platform.github.io/ngio/getting-started/) guide. Or checkout our [Documentation](https://fractal-analytics-platform.github.io/ngio/)
 
@@ -33,10 +33,9 @@ To get started, check out the [Getting Started](https://fractal-analytics-platfo
 | Basic Iterators | Ongoing | End-September | Read and Write Iterators for common access patterns |
 | Base Documentation | ✅ | End-September | API Documentation and Examples |
 | Beta Ready Testing | ✅ | End-September | Beta Testing; Library is ready for testing, but the API is not stable |
-| Streaming from Fractal | Ongoing | December | Ngio can stream ome-zarr from fractal |
+| Streaming from Fractal | Ongoing | December | Ngio can stream OME-Zarr from fractal |
 | Mask Iterators | Ongoing | Early 2025 | Iterators over Masked Tables |
 | Advanced Iterators | Not started | mid-2025 | Iterators for advanced access patterns |
 | Parallel Iterators | Not started | mid-2025 | Concurrent Iterators for parallel read and write |
 | Full Documentation | Not started | 2025 | Complete Documentation |
 | Release 1.0 (Commitment to API) | Not started | 2025 | API is stable; breaking changes will be avoided |
-

{ngio-0.2.0b3 → ngio-0.2.1}/_typos.toml

@@ -1,3 +1,4 @@
 [default.extend-words]
 # Don't correct the surname "Teh"
-OME = "OME"
+OME = "OME"
+FO = "FO"

ngio-0.2.1/docs/api/common.md

@@ -0,0 +1,6 @@
+# ngio.common API documentation
+
+!!! warning
+    Coming soon, ngio API documentation is not yet available.
+    If you have any questions please reach out to us on GitHub or via email.
+    We are happy to help you with any questions or issues you may have.

ngio-0.2.1/docs/api/hcs.md

@@ -0,0 +1,6 @@
+# ngio.hcs API documentation
+
+!!! warning
+    Coming soon, ngio API documentation is not yet available.
+    If you have any questions please reach out to us on GitHub or via email.
+    We are happy to help you with any questions or issues you may have.

ngio-0.2.1/docs/api/images.md

@@ -0,0 +1,6 @@
+# ngio.images API documentation
+
+!!! warning
+    Coming soon, ngio API documentation is not yet available.
+    If you have any questions please reach out to us on GitHub or via email.
+    We are happy to help you with any questions or issues you may have.

ngio-0.2.1/docs/api/ngio.md

@@ -0,0 +1,6 @@
+# ngio API documentation
+
+!!! warning
+    Coming soon, ngio API documentation is not yet available.
+    If you have any questions please reach out to us on GitHub or via email.
+    We are happy to help you with any questions or issues you may have.

ngio-0.2.1/docs/api/tables.md

@@ -0,0 +1,6 @@
+# ngio.tables API documentation
+
+!!! warning
+    Coming soon, ngio API documentation is not yet available.
+    If you have any questions please reach out to us on GitHub or via email.
+    We are happy to help you with any questions or issues you may have.

ngio-0.2.1/docs/api/utils.md

@@ -0,0 +1,6 @@
+# ngio.utils
+
+!!! warning
+    Coming soon, ngio API documentation is not yet available.
+    If you have any questions please reach out to us on GitHub or via email.
+    We are happy to help you with any questions or issues you may have.

ngio-0.2.1/docs/code_of_conduct.md

@@ -0,0 +1,2 @@
+!!! warning
+    The library is still in the early stages of development, the code of conduct is not yet established.

ngio-0.2.1/docs/contributing.md

@@ -0,0 +1,4 @@
+!!! warning
+    The library is still in the early stages of development, no contribution guidelines are established yet.
+    But contributions are welcome! Please open an issue or a pull request to discuss your ideas.
+    We are looking for contributors to help us improve the library and documentation.

ngio-0.2.1/docs/getting_started/0_quickstart.md

@@ -0,0 +1,99 @@
+# Quickstart
+
+Ngio is a Python package that provides a simple and intuitive API for reading and writing data to and from OME-Zarr. This guide will walk you through the basics of using `ngio` to read and write data.
+
+## Installation
+
+`ngio` can be installed from PyPI, conda-forge, or from source.
+
+- `ngio` requires Python `>=3.11`
+
+=== "pip"
+
+    The recommended way to install `ngio` is from PyPI using pip:
+
+    ```bash
+    pip install ngio
+    ```
+
+=== "mamba/conda"
+
+    Alternatively, you can install `ngio` using mamba:
+
+    ```bash
+    mamba install -c conda-forge ngio
+    ```
+
+    or conda:
+
+    ```bash
+    conda install -c conda-forge ngio
+    ```
+
+=== "Source"
+
+    1. Clone the repository:
+    ```bash
+    git clone https://github.com/fractal-analytics-platform/ngio.git
+    cd ngio
+    ```
+
+    2. Install the package:
+    ```bash
+    pip install .
+    ```
+
+### Troubleshooting
+
+Please report installation problems by opening an issue on our [GitHub repository](https://github.com/fractal-analytics-platform/ngio).
+
+## Setup some test data
+
+Let's start by downloading a sample OME-Zarr dataset to work with.
+
+```python exec="true" source="material-block" session="quickstart"
+from pathlib import Path
+from ngio.utils import download_ome_zarr_dataset
+
+# Download a sample dataset
+download_dir = Path("./data")
+download_dir = Path(".").absolute().parent.parent / "data" # markdown-exec: hide
+hcs_path = download_ome_zarr_dataset("CardiomyocyteSmallMip", download_dir=download_dir)
+image_path = hcs_path / "B" / "03" / "0"
+```
+
+## Open an OME-Zarr image
+
+Let's start by opening an OME-Zarr file and inspecting its contents.
+
+```pycon exec="true" source="console" session="quickstart"
+>>> from ngio import open_ome_zarr_container
+>>> ome_zarr_container = open_ome_zarr_container(image_path)
+>>> ome_zarr_container
+>>> print(ome_zarr_container) # markdown-exec: hide
+```
+
+### What is the OME-Zarr container?
+
+The `OME-Zarr Container` is the core of ngio and the entry point to working with OME-Zarr images. It provides high-level access to the image metadata, images, labels, and tables.
+
+### What is the OME-Zarr container not?
+
+The `OME-Zarr Container` object does not allow the user to interact with the image data directly. For that, we need to use the `Image`, `Label`, and `Table` objects.
+
+## Next steps
+
+To learn how to work with the `OME-Zarr Container` object, but also with the image, label, and table data, check out the following guides:
+
+- [OME-Zarr Container](1_ome_zarr_containers.md): An overview on how to use the OME-Zarr Container object and how to create new images and labels.
+- [Images/Labels](2_images.md): To know more on how to work with image data.
+- [Tables](3_tables.md): To know more on how to work with table data, and how you can combine tables with image data.
+- [Masked Images/Labels](4_masked_images.md): To know more on how to work with masked image data.
+- [HCS Plates](5_hcs.md): To know more on how to work with HCS plate data.
+
+Also, checkout our jupyer notebook tutorials for more examples:
+
+- [Image Processing](../tutorials/image_processing.ipynb): Learn how to perform simple image processing operations.
+- [Image Segmentation](../tutorials/image_segmentation.ipynb): Learn how to create new labels from images.
+- [Feature Extraction](../tutorials/feature_extraction.ipynb): Learn how to extract features from images.
+- [HCS Processing](../tutorials/hcs_processing.ipynb): Learn how to process high-content screening data using ngio.

ngio-0.2.1/docs/getting_started/1_ome_zarr_containers.md

@@ -0,0 +1,181 @@
+# 1. OME-Zarr Container
+
+Let's see how to open and explore an OME-Zarr image using `ngio`:
+
+```python exec="true" source="material-block" session="get_started"
+from pathlib import Path
+from ngio import open_ome_zarr_container
+from ngio.utils import download_ome_zarr_dataset
+
+# Download a sample dataset
+download_dir = Path("./data")
+download_dir = Path(".").absolute().parent.parent / "data" # markdown-exec: hide
+hcs_path = download_ome_zarr_dataset("CardiomyocyteSmallMip", download_dir=download_dir)
+image_path = hcs_path / "B" / "03" / "0"
+
+# Open the OME-Zarr container
+ome_zarr_container = open_ome_zarr_container(image_path)
+```
+
+The `OME-Zarr Container` in is your entry point to working with OME-Zarr images. It provides high-level access to the image metadata, images, labels, and tables.
+
+```pycon exec="true" source="console" session="get_started"
+>>> ome_zarr_container
+>>> print(ome_zarr_container) # markdown-exec: hide
+```
+
+The `OME-Zarr Container` will be the starting point for all your image processing tasks.
+
+## Main concepts
+
+### What is the OME-Zarr container?
+
+The `OME-Zarr Container` in ngio is your entry point to working with OME-Zarr images.
+
+It provides:
+
+- **OME-Zarr overview**: get an overview of the OME-Zarr file, including the number of image levels, list of labels, and tables available.
+- **Image access**: get access to the images at different resolution levels and pixel sizes.
+- **Label management**: check which labels are available, access them, and create new labels.
+- **Table management**: check which tables are available, access them, and create new tables.
+- **Derive new OME-Zarr images**: create new images based on the original one, with the same or similar metadata.
+
+### What is the OME-Zarr container not?
+
+The `OME-Zarr Container` object does not allow the user to interact with the image data directly. For that, we need to use the `Image`, `Label`, and `Table` objects.
+
+## OME-Zarr overview
+
+Examples of the OME-Zarr metadata access:
+
+=== "Number of Resolution Levels"
+    Show the number of resolution levels:
+    ```pycon exec="true" source="console" session="get_started"
+    >>> ome_zarr_container.levels # Show the number of resolution levels
+    >>> print(ome_zarr_container.levels) # markdown-exec: hide
+    ```
+
+=== "Available Paths"
+    Show the paths to all available resolution levels:
+    ```pycon exec="true" source="console" session="get_started"
+    >>> ome_zarr_container.levels_paths # Show the paths to all available images
+    >>> print(ome_zarr_container.levels_paths) # markdown-exec: hide
+    ```
+
+=== "Dimensionality"
+    Show if the image is 2D or 3D:
+    ```pycon exec="true" source="console" session="get_started"
+    >>> ome_zarr_container.is_3d # Get if the image is 3D
+    >>> print(ome_zarr_container.is_3d) # markdown-exec: hide
+    ```
+    or if the image is a time series:
+    ```pycon exec="true" source="console" session="get_started"
+    >>> ome_zarr_container.is_time_series # Get if the image is a time series
+    >>> print(ome_zarr_container.is_time_series) # markdown-exec: hide
+    ```
+
+=== "Full Metadata Object"
+    ```pycon exec="true" source="console" session="get_started"
+    >>> metadata = ome_zarr_container.image_meta
+    >>> print(metadata) # markdown-exec: hide
+    ```
+    The metadata object contains all the information about the image, for example, the channel labels:
+    ```pycon exec="true" source="console" session="get_started"
+    >>> metadata.channel_labels
+    >>> print(metadata.channel_labels) # markdown-exec: hide
+    ```
+
+## Accessing images / labels / tables
+
+To access images, labels, and tables, you can use the `get_image`, `get_label`, and `get_table` methods of the `OME-Zarr Container` object.
+
+A variety of examples and additional information can be found in the [Images and Labels](./2_images.md), and [Tables](../3_tables.md) sections.
+
+## Creating derived images
+
+When processing an image, you might want to create a new image with the same metadata:
+
+```python
+# Create a new image based on the original
+new_image = ome_zarr_container.derive_image("data/new_ome.zarr", overwrite=True)
+```
+
+This will create a new OME-Zarr image with the same metadata as the original image.
+But you can also create a new image with slightly different metadata, for example, with a different shape:
+
+```python
+# Create a new image with a different shape
+new_image = ome_zarr_container.derive_image(
+    "data/new_ome.zarr", 
+    overwrite=True, 
+    shape=(16, 128, 128), 
+    xy_pixelsize=0.65, 
+    z_spacing=1.0
+)
+```
+
+## Creating new images
+
+You can create OME-Zarr images from an existing numpy array using the `create_ome_zarr_from_array` function.
+
+```python
+import numpy as np
+from ngio import create_ome_zarr_from_array
+
+# Create a random 3D array
+x = np.random.randint(0, 255, (16, 128, 128), dtype=np.uint8)
+
+# Save as OME-Zarr
+new_ome_zarr_image = create_ome_zarr_from_array(
+    store="random_ome.zarr", 
+    array=x, 
+    xy_pixelsize=0.65, 
+    z_spacing=1.0
+)
+```
+
+Alternatively, if you wanto to create an a empty OME-Zarr image, you can use the `create_empty_ome_zarr` function:
+
+```python
+from ngio import create_empty_ome_zarr
+# Create an empty OME-Zarr image
+new_ome_zarr_image = create_empty_ome_zarr(
+    store="empty_ome.zarr", 
+    shape=(16, 128, 128), 
+    xy_pixelsize=0.65, 
+    z_spacing=1.0
+)
+```
+
+This will create an empty OME-Zarr image with the specified shape and pixel sizes.
+
+## Opening remote OME-Zarr containers
+
+You can use `ngio` to open remote OME-Zarr containers.
+For publicly available OME-Zarr containers, you can just use the `open_ome_zarr_container` function with a URL.
+
+For example, to open a remote OME-Zarr container hosted on a github repository:
+
+```python
+from ngio.utils import fractal_fsspec_store
+
+url = (
+    "https://raw.githubusercontent.com/"
+    "fractal-analytics-platform/fractal-ome-zarr-examples/"
+    "refs/heads/main/v04/"
+    "20200812-CardiomyocyteDifferentiation14-Cycle1_B_03_mip.zarr/"
+)
+
+store = fractal_fsspec_store(url=url)
+ome_zarr_container = open_ome_zarr_container(store)
+```
+
+For fractal users, the `fractal_fsspec_store` function can be used to open private OME-Zarr containers.
+In this case we need to provide a `fractal_token` to authenticate the user.
+
+```python
+from ngio.utils import fractal_fsspec_store
+ 
+store = fractal_fsspec_store(url="https://fractal_url...", fractal_token="**your_secret_token**")
+ome_zarr_container = open_ome_zarr_container(store)
+```

ngio-0.2.1/docs/getting_started/2_images.md

@@ -0,0 +1,200 @@
+# 2. Images and Labels
+
+## Images
+
+In order to start working with the image data, we need to instantiate an `Image` object.
+ngio provides a high-level API to access the image data at different resolution levels and pixel sizes.
+
+### Getting an image
+
+=== "Highest Resolution Image"
+    By default, the `get_image` method returns the highest resolution image:
+    ```pycon exec="true" source="console" session="get_started"
+    >>> ome_zarr_container.get_image() # Get the highest resolution image
+    >>> print(ome_zarr_container.get_image()) # markdown-exec: hide
+    ```
+
+=== "Specific Pyramid Level"
+    To get a specific pyramid level, you can use the `path` parameter:
+    ```pycon exec="true" source="console" session="get_started"
+    >>> ome_zarr_container.get_image(path="1") # Get a specific pyramid level
+    >>> print(ome_zarr_container.get_image(path="1")) # markdown-exec: hide
+    ```
+    This will return the image at the specified pyramid level.
+
+=== "Specific Resolution"
+    If you want to get an image with a specific pixel size, you can use the `pixel_size` parameter:
+    ```pycon exec="true" source="console" session="get_started"
+    >>> from ngio import PixelSize
+    >>> pixel_size = PixelSize(x=0.65, y=0.65, z=1.0)
+    >>> ome_zarr_container.get_image(pixel_size=pixel_size)
+    >>> image = ome_zarr_container.get_image(pixel_size=pixel_size) # markdown-exec: hide
+    >>> print(image) # markdown-exec: hide
+    ```
+
+=== "Nearest Resolution"
+    By default the pixels must match exactly the requested pixel size. If you want to get the nearest resolution, you can use the `strict` parameter:
+    ```pycon exec="true" source="console" session="get_started"
+    >>> from ngio import PixelSize
+    >>> pixel_size = PixelSize(x=0.60, y=0.60, z=1.0)
+    >>> ome_zarr_container.get_image(pixel_size=pixel_size, strict=False)
+    >>> image = ome_zarr_container.get_image(pixel_size=pixel_size, strict=False) # markdown-exec: hide
+    >>> print(image) # markdown-exec: hide
+    ```
+    This will return the image with the nearest resolution to the requested pixel size.
+
+Similarly to the `OME-Zarr Container`, the `Image` object provides a high-level API to access the image metadata.
+
+=== "Dimensions"
+    ```pycon exec="true" source="console" session="get_started"
+    >>> image.dimensions
+    >>> print(image.dimensions) # markdown-exec: hide
+    ```
+    The `dimensions` attribute returns a object with the image dimensions for each axis.
+
+=== "Pixel Size"
+    ```pycon exec="true" source="console" session="get_started"
+    >>> image.pixel_size
+    >>> print(image.pixel_size) # markdown-exec: hide
+    ```
+    The `pixel_size` attribute returns the pixel size for each axis.
+
+=== "On disk array infos"
+    ```pycon exec="true" source="console" session="get_started"
+    >>> image.shape, image.dtype, image.chunks
+    >>> print(image.shape, image.dtype, image.chunks) # markdown-exec: hide
+    ```
+    The `axes` attribute returns the order of the axes in the image.
+
+### Working with image data
+
+Once you have the `Image` object, you can access the image data as a:
+
+=== "Numpy Array"
+    ```pycon exec="true" source="console" session="get_started"
+    >>> data = image.get_array() # Get the image as a numpy array
+    >>> data.shape, data.dtype
+    >>> print(data.shape, data.dtype) # markdown-exec: hide
+    ```
+
+=== "Dask Array"
+    ```pycon exec="true" source="console" session="get_started"
+    >>> dask_array = image.get_array(mode="dask") # Get the image as a dask array
+    >>> dask_array
+    >>> print(dask_array) # markdown-exec: hide
+    ```
+
+=== "Dask Delayed"
+    ```pycon exec="true" source="console" session="get_started"
+    >>> dask_delayed = image.get_array(mode="delayed") # Get the image as a dask delayed object
+    >>> dask_delayed
+    >>> print(dask_delayed) # markdown-exec: hide
+    ```
+
+The `get_array` can also be used to slice the image data, and query specific axes in specific orders:
+
+```pycon exec="true" source="console" session="get_started"
+>>> image_slice = image.get_array(c=0, x=slice(0, 128), axes_order=["t", "z", "y", "x", "c"]) # Get a specific channel and axes order
+>>> image_slice.shape
+>>> print(image_slice.shape) # markdown-exec: hide
+```
+
+If you want to edit the image data, you can use the `set_array` method:
+
+```python
+>>> image.set_array(data) # Set the image data
+```
+
+The `set_array` method can be used to set the image data from a numpy array, dask array, or dask delayed object.
+
+A minimal example of how to use the `get_array` and `set_array` methods:
+
+```python exec="true" source="material-block" session="get_started"
+# Get the image data as a numpy array
+data = image.get_array(c=0, x=slice(0, 128), y=slice(0, 128), axes_order=["z", "y", "x", "c"])
+
+# Modify the image data
+some_function = lambda x: x # markdown-exec: hide
+data = some_function(data)
+
+# Set the modified image data
+image.set_array(data, c=0, x=slice(0, 128), y=slice(0, 128), axes_order=["z", "y", "x", "c"])
+image.consolidate() # Consolidate the changes to all resolution levels, see below for more details
+```
+
+!!! important
+    The `set_array` method will overwrite the image data at single resolution level. After you have finished editing the image data, you need to `consolidate` the changes to the OME-Zarr file at all resolution levels:
+    ```python
+    >>> image.consolidate() # Consolidate the changes
+    ```
+    This will write the changes to the OME-Zarr file at all resolution levels.
+
+## Labels
+
+`Labels` represent segmentation masks that identify objects in the image. In ngio `Labels` are similar to `Images` and can
+be accessed and manipulated in the same way.
+
+### Getting a label
+
+Now let's see what labels are available in our image:
+
+```pycon exec="true" source="console" session="get_started"
+# List all available labels
+>>> ome_zarr_container.list_labels() # Available labels
+>>> print(ome_zarr_container.list_labels()) # markdown-exec: hide
+>>> print("") # markdown-exec: hide
+```
+
+We have `4` labels available in our image. Let's see how to access them:
+
+=== "Highest Resolution Label"
+    By default, the `get_label` method returns the highest resolution label:
+    ```pycon exec="true" source="console" session="get_started"
+    >>> ome_zarr_container.get_label("nuclei") # Get the highest resolution label
+    >>> print(ome_zarr_container.get_label("nuclei")) # markdown-exec: hide
+    ```
+
+=== "Specific Pyramid Level"
+    To get a specific pyramid level, you can use the `path` parameter:
+    ```pycon exec="true" source="console" session="get_started"
+    >>> ome_zarr_container.get_label("nuclei", path="1") # Get a specific pyramid level
+    >>> print(ome_zarr_container.get_label("nuclei", path="1")) # markdown-exec: hide
+    ```
+    This will return the label at the specified pyramid level.
+
+=== "Specific Resolution"
+    If you want to get a label with a specific pixel size, you can use the `pixel_size` parameter:
+    ```pycon exec="true" source="console" session="get_started"
+    >>> from ngio import PixelSize
+    >>> pixel_size = PixelSize(x=0.65, y=0.65, z=1.0)
+    >>> ome_zarr_container.get_label("nuclei", pixel_size=pixel_size)
+    >>> label_nuclei = ome_zarr_container.get_label("nuclei", pixel_size=pixel_size) # markdown-exec: hide
+    >>> print(label_nuclei) # markdown-exec: hide
+    ```
+
+=== "Nearest Resolution"
+    By default the pixels must match exactly the requested pixel size. If you want to get the nearest resolution, you can use the `strict` parameter:
+    ```pycon exec="true" source="console" session="get_started"
+    >>> from ngio import PixelSize
+    >>> pixel_size = PixelSize(x=0.60, y=0.60, z=1.0)
+    >>> ome_zarr_container.get_label("nuclei", pixel_size=pixel_size, strict=False)
+    >>> label_nuclei = ome_zarr_container.get_label("nuclei", pixel_size=pixel_size, strict=False) # markdown-exec: hide
+    >>> print(label_nuclei) # markdown-exec: hide
+    ```
+    This will return the label with the nearest resolution to the requested pixel size.
+
+### Working with label data
+
+Data access and manipulation for `Labels` is similar to `Images`. You can use the `get_array` and `set_array` methods to access and modify the label data.
+
+### Deriving a label
+
+Often, you might want to create a new label based on an existing image. You can do this using the `derive_label` method:
+
+```pycon exec="true" source="console" session="get_started"
+>>> new_label = ome_zarr_container.derive_label("new_label", overwrite=True) # Derive a new label
+>>> print(new_label) # markdown-exec: hide
+```
+
+This will create a new label with the same dimensions as the original image (without channels) and compatible metadata.
+If you want to create a new label with slightly different metadata see [API Reference](../api/images.md).