hoa-tools 1.0__tar.gz

hoa_tools-1.0/.github/dependabot.yml

@@ -0,0 +1,15 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"
+    groups:
+      github-actions:
+        patterns:
+          - "*"

hoa_tools-1.0/.github/workflows/tests.yml

@@ -0,0 +1,66 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    paths-ignore:
+      - "**.md"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run tests
+        # For example, using `pytest`
+        run: uv run pytest
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+  type-check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.12"
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras --dev
+
+      - name: Run type checking
+        run: uv run mypy src/hoa_tools

hoa_tools-1.0/.gitignore

@@ -0,0 +1,172 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# package version
+_version.py
+
+# Docs
+docs/_api_autogen
+
+# macOS
+.DS_Store
+
+# uv
+uv.lock

hoa_tools-1.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "src/hoa_tools/data/metadata"]
+	path = src/hoa_tools/data/metadata
+	url = https://github.com/HumanOrganAtlas/metadata-schemas

hoa_tools-1.0/.pre-commit-config.yaml

@@ -0,0 +1,44 @@
+ci:
+  autoupdate_commit_msg: "Update pre-commit hooks"
+
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.4
+    hooks:
+      - id: ruff
+      - id: ruff-format
+
+  - repo: https://github.com/rbubley/mirrors-prettier
+    rev: v3.5.3
+    hooks:
+      - id: prettier
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+        args:
+          - --fix=lf
+      - id: trailing-whitespace
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.1
+    hooks:
+      - id: codespell
+        args: ["--write-changes"]
+
+  - repo: https://github.com/adamchainz/blacken-docs
+    rev: 1.19.1
+    hooks:
+      - id: blacken-docs
+        additional_dependencies:
+          - black==22.12.0
+
+  - repo: https://github.com/ComPWA/taplo-pre-commit
+    rev: v0.9.3
+    hooks:
+      - id: taplo-format

hoa_tools-1.0/.readthedocs.yml

@@ -0,0 +1,20 @@
+version: 2
+
+submodules:
+  include:
+    - src/hoa_tools/data/metadata
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+
+mkdocs:
+  configuration: mkdocs.yml

hoa_tools-1.0/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "python.testing.pytestArgs": ["tests"],
+  "python.testing.unittestEnabled": false,
+  "python.testing.pytestEnabled": true
+}

hoa_tools-1.0/CITATION.cff

@@ -0,0 +1,10 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+authors:
+  - family-names: "Stansby"
+    given-names: "David"
+    email: "d.stansby@ucl.ac.uk"
+repository-code: "https://github.com/HumanOrganAtlas/hoa-tools"
+title: "HOA Tools: Tools for working with the Human Organ Atlas"
+license: "BSD-3"

hoa_tools-1.0/LICENSE.md

@@ -0,0 +1,27 @@
+Copyright (c) 2024, David Stansby
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+- Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+- Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+- Neither the name of HOA Tools nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

hoa_tools-1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include src/hoa_tools/data/metadata/metadata/*.json
+prune src/hoa_tools/tests

hoa_tools-1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: hoa-tools
+Version: 1.0
+Summary: Tools for working with the Human Organ Atlas
+Author-email: David Stansby <d.stansby@ucl.ac.uk>
+License: Copyright (c) 2024, David Stansby
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        - Redistributions of source code must retain the above copyright notice, this
+          list of conditions and the following disclaimer.
+        
+        - Redistributions in binary form must reproduce the above copyright notice,
+          this list of conditions and the following disclaimer in the documentation
+          and/or other materials provided with the distribution.
+        
+        - Neither the name of HOA Tools nor the names of its
+          contributors may be used to endorse or promote products derived from
+          this software without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+        
+Project-URL: homepage, https://github.com/HumanOrganAtlas/hoa-tools
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: dask[array]
+Requires-Dist: gcsfs>2023
+Requires-Dist: pandas>=2
+Requires-Dist: pydantic>=2
+Requires-Dist: simpleitk
+Requires-Dist: xarray
+Requires-Dist: zarr<3,>2.16
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: jupyterlab; extra == "dev"
+Requires-Dist: jupytext; extra == "dev"
+Requires-Dist: pandas-stubs; extra == "dev"
+Requires-Dist: datamodel-code-generator; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocstrings-python; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocs-jupyter; extra == "docs"
+Requires-Dist: griffe-pydantic; extra == "docs"
+Requires-Dist: matplotlib; extra == "docs"
+Requires-Dist: numpydoc; extra == "docs"
+Requires-Dist: scikit-image; extra == "docs"
+Provides-Extra: test
+Requires-Dist: matplotlib; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-accept; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-doctestplus; extra == "test"
+Requires-Dist: pytest-vcr; extra == "test"
+Requires-Dist: scikit-image; extra == "test"
+Dynamic: license-file
+
+# HOA Tools
+
+[![Tests status][tests-badge]][tests-link]
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/HumanOrganAtlas/hoa-tools/main.svg)](https://results.pre-commit.ci/latest/github/HumanOrganAtlas/hoa-tools/main)
+[![Documentation Status](https://readthedocs.org/projects/hoa-tools/badge/?version=latest)](https://hoa-tools.readthedocs.io/en/latest/?badge=latest)
+
+[![License][license-badge]](./LICENSE.md)
+
+<!--
+[![PyPI version][pypi-version]][pypi-link]
+[![Conda-Forge][conda-badge]][conda-link]
+[![PyPI platforms][pypi-platforms]][pypi-link]
+-->
+
+<!-- prettier-ignore-start -->
+[tests-badge]:              https://github.com/HumanOrganAtlas/hoa-tools/actions/workflows/tests.yml/badge.svg
+[tests-link]:               https://github.com/HumanOrganAtlas/hoa-tools/actions/workflows/tests.yml
+[conda-badge]:              https://img.shields.io/conda/vn/conda-forge/hoa-tools
+[conda-link]:               https://github.com/conda-forge/hoa-tools-feedstock
+[pypi-link]:                https://pypi.org/project/hoa-tools/
+[pypi-platforms]:           https://img.shields.io/pypi/pyversions/hoa-tools
+[pypi-version]:             https://img.shields.io/pypi/v/hoa-tools
+[license-badge]:            https://img.shields.io/badge/License-BSD_3--Clause-blue.svg
+<!-- prettier-ignore-end -->
+
+Tools for working with data from the [Human Organ Atlas](https://human-organ-atlas.esrf.eu/).
+Documentation at https://hoa-tools.readthedocs.io.

hoa_tools-1.0/README.md

@@ -0,0 +1,27 @@
+# HOA Tools
+
+[![Tests status][tests-badge]][tests-link]
+[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/HumanOrganAtlas/hoa-tools/main.svg)](https://results.pre-commit.ci/latest/github/HumanOrganAtlas/hoa-tools/main)
+[![Documentation Status](https://readthedocs.org/projects/hoa-tools/badge/?version=latest)](https://hoa-tools.readthedocs.io/en/latest/?badge=latest)
+
+[![License][license-badge]](./LICENSE.md)
+
+<!--
+[![PyPI version][pypi-version]][pypi-link]
+[![Conda-Forge][conda-badge]][conda-link]
+[![PyPI platforms][pypi-platforms]][pypi-link]
+-->
+
+<!-- prettier-ignore-start -->
+[tests-badge]:              https://github.com/HumanOrganAtlas/hoa-tools/actions/workflows/tests.yml/badge.svg
+[tests-link]:               https://github.com/HumanOrganAtlas/hoa-tools/actions/workflows/tests.yml
+[conda-badge]:              https://img.shields.io/conda/vn/conda-forge/hoa-tools
+[conda-link]:               https://github.com/conda-forge/hoa-tools-feedstock
+[pypi-link]:                https://pypi.org/project/hoa-tools/
+[pypi-platforms]:           https://img.shields.io/pypi/pyversions/hoa-tools
+[pypi-version]:             https://img.shields.io/pypi/v/hoa-tools
+[license-badge]:            https://img.shields.io/badge/License-BSD_3--Clause-blue.svg
+<!-- prettier-ignore-end -->
+
+Tools for working with data from the [Human Organ Atlas](https://human-organ-atlas.esrf.eu/).
+Documentation at https://hoa-tools.readthedocs.io.

hoa_tools-1.0/docs/api/dataset.md

@@ -0,0 +1,3 @@
+# `hoa_tools.dataset`
+
+::: hoa_tools.dataset

hoa_tools-1.0/docs/api/index.md

@@ -0,0 +1,10 @@
+# API reference
+
+These pages contain reference documentation for the classes and functions
+in `hoa-tools`.
+
+- [`hoa_tools.dataset`](dataset.md)
+- [`hoa_tools.inventory`](inventory.md)
+- [`hoa_tools.metadata`](metadata.md)
+- [`hoa_tools.types`](types.md)
+- [`hoa_tools.voi`](voi.md)

hoa_tools-1.0/docs/api/inventory.md

@@ -0,0 +1,3 @@
+# `hoa_tools.inventory`
+
+::: hoa_tools.inventory

hoa_tools-1.0/docs/api/metadata.md

@@ -0,0 +1,5 @@
+# `hoa_tools.metadata`
+
+Metadata model for dataset metadata.
+
+::: hoa_tools.metadata

hoa_tools-1.0/docs/api/types.md

@@ -0,0 +1,3 @@
+# `hoa_tools.types`
+
+::: hoa_tools.types

hoa_tools-1.0/docs/api/voi.md

@@ -0,0 +1,3 @@
+# `hoa_tools.voi`
+
+::: hoa_tools.voi

hoa_tools-1.0/docs/development.md

@@ -0,0 +1,14 @@
+# Development
+
+## Updating the inventory
+
+To update the version of the inventory, update the git submodule at src/hoa_tools/data/metadata.
+The inventory is stored separately at https://github.com/HumanOrganAtlas/metadata-schemas.
+
+## Generating the data model
+
+Using [datamodel-code-generator](https://github.com/koxudaxi/datamodel-code-generator/):
+
+```
+datamodel-codegen --input src/hoa_tools/data/metadata/metadata-schema.json --input-file-type jsonschema --output src/hoa_tools/metadata.py --output-model-type pydantic_v2.BaseModel --use-annotated --enum-field-as-literal all --use-union-operator --use-standard-collections
+```

hoa_tools-1.0/docs/how_to.md

@@ -0,0 +1,6 @@
+# How do I...?
+
+## Use a private copy of the metadata database?
+
+Download the private metadata JSON files to a directory on your computer,
+then use [hoa_tools.dataset.change_metadata_directory][].

hoa_tools-1.0/docs/index.md

@@ -0,0 +1,19 @@
+# Human Organ Atlas Python Tools
+
+This package contains tools for working with data from the [Human Organ Atlas](https://human-organ-atlas.esrf.eu).
+
+## Getting started
+
+A few useful places to start:
+
+- The [tutorial](tutorial/index.md) contains a step by step guide to using `hoa-tools`
+- [How do I...?](how_to.md) lists how to do common tasks with `hoa-tools`
+- The [API reference](api/index.md) contains a listing of classes and functions in `hoa-tools`
+
+## Feedback
+
+Suggestions and bug reports are very welcome, and encouraged! Please [open an issue](https://github.com/HumanOrganAtlas/hoa-tools/issues/new) on our GitHub issue tracker.
+
+## Contributing
+
+Contributions are very welcome, and encouraged! Please open a pull request with your suggested change on our [GitHub repository](https://github.com/HumanOrganAtlas/hoa-tools).

hoa_tools-1.0/docs/release-notes.md

@@ -0,0 +1,5 @@
+# Release notes
+
+## 1.0
+
+First release of the `hoa-tools` package 🚀

hoa_tools-1.0/docs/tutorial/dataset.py

@@ -0,0 +1,37 @@
+# # Individual datasets
+#
+# In this chapter we'll look at what we can do with an individual dataset.
+# In ``hoa-tools`` individual datasets are represented by `Dataset` objects.
+
+import pandas as pd
+
+import hoa_tools.dataset
+import hoa_tools.inventory
+
+pd.options.display.width = None  # type: ignore[assignment]
+
+# First, lets print all the spleen datasets available from the inventory::
+
+inventory = hoa_tools.inventory.load_inventory()
+spleen_inventory = inventory[inventory["organ"] == "spleen"]
+spleen_inventory
+
+# We can see that three datasets are available. They are from the same organ, with one being the full
+# organ dataset and two being high resolution region of interest datasets. Lets get the full organ
+# dataset
+
+whole_spleen = hoa_tools.dataset.get_dataset(
+    "LADAF-2020-27_spleen_complete-organ_25.08um_bm05"
+)
+whole_spleen
+
+# Because this is a full-organ dataset, it will have a number of child datasets. These are scans of
+# the same organ taken at a higher resolution over a subset of the full volume. For our selected
+# dataset these child datasets are::
+
+child_datasets = whole_spleen.get_children()
+for dataset in child_datasets:
+    print(dataset)
+
+# We can see there are two child datasets, one at a resolution of 1.29 μm and one at a
+# resolution of 6.05 μm.

hoa_tools-1.0/docs/tutorial/fetching_data.py

@@ -0,0 +1,41 @@
+# # Fetching data
+
+# In this tutorial we will fetch some of the data. All public Human Organ Atlas
+# data is available through a read-only public Google Cloud Storage bucket.
+# in a chunked data format, making it easy to access sub-volumes of data.
+
+# ## Getting a remote data store
+
+# First we'll fetch a `Dataset` object from the inventory.
+
+import hoa_tools.dataset
+import hoa_tools.inventory
+
+inventory = hoa_tools.inventory.load_inventory()
+dataset_name = inventory.index[0]
+print(dataset_name)
+
+dataset = hoa_tools.dataset.get_dataset(dataset_name)
+print(dataset)
+
+# The `Dataset.remote_array` property gives us access to a remote data array for a dataset.
+# The ``level`` parameter lets us choose a downsampling level: ``level=0`` is the original
+# resolution dataset, and each time the level goes up by one the dataset is downsampled
+# by a factor of 2. All datasets are downsampled to ``level=4``, so lets get a remote store
+# for the lowest resolution copy of the data.
+
+data_array = dataset.data_array(downsample_level=4)
+data_array
+
+# Here we can see that the array is read-only, 16 bit, and has shape ``(477, 238, 238)``.
+# At this point no data has been downloaded - to download data you need to index the remote array.
+# As an example, lets fetch and show a slice in the x-y plane::
+
+
+middle_slice = data_array.isel(z=437)
+im = middle_slice.plot(cmap="Grays_r")
+im.axes.set_aspect("equal")
+
+
+# If you want to save a part of the array for later analysis, see the [xarray guide
+# to reading and writing files](https://docs.xarray.dev/en/stable/user-guide/io.html).