Skip to main content


Project Maturity ESEE

ci Documentation Status

Concept • Installation • Example • Testing • Documentation

Polytope is a library for extracting complex data from datacubes. It provides an API for non-orthogonal access to data, where the stencil used to extract data from the datacube can be any arbitrary n-dimensional polygon (called a polytope). This can be used to efficiently extract complex features from a datacube, such as polygon regions or spatio-temporal paths.

Polytope is designed to extend different datacube backends:

  • XArray dataarrays
  • FDB object stores (through the GribJump software)

Polytope supports datacubes which have branching, non-uniform indexing, and even cyclic axes. If the datacube backend supports byte-addressability and efficient random access (either in-memory or direct from storage), Polytope can be used to dramatically decrease overall I/O load.

[!IMPORTANT] This software is Incubating and subject to ECMWF's guidelines on Software Maturity.

Concept

Polytope is designed to enable extraction of arbitrary extraction of data from a datacube. Instead of the typical range-based bounding-box approach, Polytope can extract any shape of data from a datacube using a "polytope" (n-dimensional polygon) stencil.

Polytope Concept

The Polytope algorithm can for example be used to extract:

  • 2D cut-outs, such as country cut-outs, from a datacube

    Greece cut-out

  • timeseries from a datacube

    Timeseries

  • more complicated spatio-temporal paths, such as flight paths, from a datacube

    Flight path

  • and many more high-dimensional shapes in arbitrary dimensions...

For more information about the Polytope algorithm, refer to our paper. If this project is useful for your work, please consider citing this paper.

Installation

Install the polytope software with Python 3 (>=3.7) from GitHub directly with the command

python3 -m pip install git+ssh://git@github.com/ecmwf/polytope.git@develop

or from PyPI with the command

python3 -m pip install polytope-python

Example

Here is a step-by-step example of how to use this software.

  1. In this example, we first specify the data which will be in our Xarray datacube. Note that the data here comes from the GRIB file called "winds.grib", which is 3-dimensional with dimensions: step, latitude and longitude.

        import xarray as xr
    
        array = xr.open_dataset("winds.grib", engine="cfgrib")
    

    We then construct the Polytope object, passing in some additional metadata describing properties of the longitude axis.

        options = {"longitude": {"cyclic": [0, 360.0]}}
    
        from polytope_feature.polytope import Polytope
    
        p = Polytope(datacube=array, axis_options=options)
    
  2. Next, we create a request shape to extract from the datacube.
    In this example, we want to extract a simple 2D box in latitude and longitude at step 0. We thus create the two relevant shapes we need to build this 3-dimensional object,

        import numpy as np
        from polytope_feature.shapes import Box, Select
    
        box = Box(["latitude", "longitude"], [0, 0], [1, 1])
        step_point = Select("step", [np.timedelta64(0, "s")])
    

    which we then incorporate into a Polytope request.

        from polytope_feature.polytope import Request
    
        request = Request(box, step_point)
    
  3. Finally, extract the request from the datacube.

        result = p.retrieve(request)
    

    The result is stored as an IndexTree containing the retrieved data organised hierarchically with axis indices for each point.

        result.pprint()
        
    
        Output IndexTree: 
    
            ↳root=None
                ↳step=0 days 00:00:00
                        ↳latitude=0.0
                                ↳longitude=0.0
                                ↳longitude=1.0
                        ↳latitude=1.0
                                ↳longitude=0.0
                                ↳longitude=1.0
    

Testing

Additional Dependencies

The Polytope tests and examples require additional Python packages compared to the main Polytope algorithm. The additional dependencies are provided in the requirements_test.txt and requirements_examples.txt files, which can respectively be found in the tests and examples folders. Moreover, Polytope's tests and examples also require the installation of eccodes and GDAL. It is possible to install both of these dependencies using either a package manager or manually.

Contributing

The main repository is hosted on GitHub; testing, bug reports and contributions are highly welcomed and appreciated. Please see the Contributing document for the best way to help.

Main contributors:

See also the contributors for a more complete list.

License

Copyright 2021 European Centre for Medium-Range Weather Forecasts (ECMWF)

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0).

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

In applying this licence, ECMWF does not waive the privileges and immunities
granted to it by virtue of its status as an intergovernmental organisation nor
does it submit to any jurisdiction.

Citing

If this software is useful in your work, please consider citing our paper as

Leuridan, M., Hawkes, J., Smart, S., Danovaro, E., & Quintino, T. (2025, November). Polytope: An Algorithm for Efficient Feature Extraction on Hypercubes. In Journal of Big Data (pp. 1-25).

Other papers include:

Leuridan, M., Bradley, C., Hawkes, J., Quintino, T., & Schultz, M. (2025, June). Performance Analysis of an Efficient Algorithm for Feature Extraction from Large Scale Meteorological Data Stores. In Proceedings of the Platform for Advanced Scientific Computing Conference (pp. 1-9).

Acknowledgements

Past and current funding and support for Polytope is listed in the adjoining Acknowledgements.

Metadata

Release files for polytope-python 2.1.21

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for polytope-python 2.1.21
File Size Uploaded Provenance Actions
polytope_python-2.1.21.tar.gz 14.4 MB Without provenance Details for polytope_python-2.1.21.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for polytope-python 2.1.21
File Actions
polytope_python-2.1.21-cp314-cp314-manylinux_2_28_x86_64.whl CPython 3.14 CPython 3.14 Linux glibc 2.28+ x86-64 Details for polytope_python-2.1.21-cp314-cp314-manylinux_2_28_x86_64.whl
polytope_python-2.1.21-cp314-cp314-macosx_11_0_arm64.whl CPython 3.14 CPython 3.14 macOS 11.0+ ARM64 Details for polytope_python-2.1.21-cp314-cp314-macosx_11_0_arm64.whl
polytope_python-2.1.21-cp313-cp313-manylinux_2_28_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.28+ x86-64 Details for polytope_python-2.1.21-cp313-cp313-manylinux_2_28_x86_64.whl
polytope_python-2.1.21-cp313-cp313-macosx_11_0_arm64.whl CPython 3.13 CPython 3.13 macOS 11.0+ ARM64 Details for polytope_python-2.1.21-cp313-cp313-macosx_11_0_arm64.whl
polytope_python-2.1.21-cp312-cp312-manylinux_2_28_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.28+ x86-64 Details for polytope_python-2.1.21-cp312-cp312-manylinux_2_28_x86_64.whl
polytope_python-2.1.21-cp312-cp312-macosx_11_0_arm64.whl CPython 3.12 CPython 3.12 macOS 11.0+ ARM64 Details for polytope_python-2.1.21-cp312-cp312-macosx_11_0_arm64.whl
polytope_python-2.1.21-cp311-cp311-manylinux_2_28_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.28+ x86-64 Details for polytope_python-2.1.21-cp311-cp311-manylinux_2_28_x86_64.whl
polytope_python-2.1.21-cp311-cp311-macosx_11_0_arm64.whl CPython 3.11 CPython 3.11 macOS 11.0+ ARM64 Details for polytope_python-2.1.21-cp311-cp311-macosx_11_0_arm64.whl
polytope_python-2.1.21-cp310-cp310-manylinux_2_28_x86_64.whl CPython 3.10 CPython 3.10 Linux glibc 2.28+ x86-64 Details for polytope_python-2.1.21-cp310-cp310-manylinux_2_28_x86_64.whl
polytope_python-2.1.21-cp310-cp310-macosx_11_0_arm64.whl CPython 3.10 CPython 3.10 macOS 11.0+ ARM64 Details for polytope_python-2.1.21-cp310-cp310-macosx_11_0_arm64.whl
polytope_python-2.1.21-cp39-cp39-manylinux_2_28_x86_64.whl CPython 3.9 CPython 3.9 Linux glibc 2.28+ x86-64 Details for polytope_python-2.1.21-cp39-cp39-manylinux_2_28_x86_64.whl
polytope_python-2.1.21-cp39-cp39-macosx_11_0_arm64.whl CPython 3.9 CPython 3.9 macOS 11.0+ ARM64 Details for polytope_python-2.1.21-cp39-cp39-macosx_11_0_arm64.whl

Total release size: 21.0 MB

Release files / polytope_python-2.1.21.tar.gz

Download URL polytope_python-2.1.21.tar.gz
Size 14.4 MB
Tags Source
SHA-256 checksum
How to use checksums
4eb4844e6a5d160bd2da0d86abc4286a3b30f8c386ac56118499c10e94171e75
BLAKE2b-256 checksum
How to use checksums
3d954a1b195d95ed43dbbb92f06f83ee79ed600ba801b8169767f5a5436d4ce4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.1

Release files / polytope_python-2.1.21-cp314-cp314-manylinux_2_28_x86_64.whl

Download URL polytope_python-2.1.21-cp314-cp314-manylinux_2_28_x86_64.whl
Size 577.4 kB
Tags CPython 3.14 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
f1d6f8e59de1b5c0a334d25cda3c651889653d3c8e9283d252dc535a96f02321
BLAKE2b-256 checksum
How to use checksums
cd138ecf6bc1308ea787587272e7bc837f8c2ad810ba5a9785ba930793220aa6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.1

Release files / polytope_python-2.1.21-cp314-cp314-macosx_11_0_arm64.whl

Download URL polytope_python-2.1.21-cp314-cp314-macosx_11_0_arm64.whl
Size 526.9 kB
Tags CPython 3.14 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
8fcd365c9ad91ae02f4c00eb423a6ab08582faedb02b4edfcad2dfb54bb3f23d
BLAKE2b-256 checksum
How to use checksums
849d16db6585ab32daa3f672f1936b04b8aa7e8a7e0a59b1c488d87330b1ef4e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Release files / polytope_python-2.1.21-cp313-cp313-manylinux_2_28_x86_64.whl

Download URL polytope_python-2.1.21-cp313-cp313-manylinux_2_28_x86_64.whl
Size 576.9 kB
Tags CPython 3.13 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
eebbb977c0723150aa947a31db4b5fa0963804bf586f97a8c361a3eae0c44bba
BLAKE2b-256 checksum
How to use checksums
d6bb928e95ce606aca3aa67012373a3b5477f010a352990428b914022adce4d9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.1

Release files / polytope_python-2.1.21-cp313-cp313-macosx_11_0_arm64.whl

Download URL polytope_python-2.1.21-cp313-cp313-macosx_11_0_arm64.whl
Size 525.5 kB
Tags CPython 3.13 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
3521e3561cabae1f287fd7a3c1d435b1a6633f3dcdc14764801b84cfc580bf47
BLAKE2b-256 checksum
How to use checksums
cf000e5eb08a1916db92a14804cf1b91b93ad7575e51f9f2cab6e5baad705675
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Release files / polytope_python-2.1.21-cp312-cp312-manylinux_2_28_x86_64.whl

Download URL polytope_python-2.1.21-cp312-cp312-manylinux_2_28_x86_64.whl
Size 577.3 kB
Tags CPython 3.12 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
9dc70e2162a4df9c6978179c8bbd7a50cccf72472034b1da29313405c20c669d
BLAKE2b-256 checksum
How to use checksums
80f18d04fb0f8e619a82b7a6e056315a266eea3867bde6431df3b67988fdf1bd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.1

Release files / polytope_python-2.1.21-cp312-cp312-macosx_11_0_arm64.whl

Download URL polytope_python-2.1.21-cp312-cp312-macosx_11_0_arm64.whl
Size 525.1 kB
Tags CPython 3.12 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
cdd0be616f660324097dc7b85006a4c94ba6e9779d728a26457bbca363dcb3fe
BLAKE2b-256 checksum
How to use checksums
fdc19e5b376e2275d2f8430e2badad8cd93765a604cb6a8fbf0f75c8f460aec4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Release files / polytope_python-2.1.21-cp311-cp311-manylinux_2_28_x86_64.whl

Download URL polytope_python-2.1.21-cp311-cp311-manylinux_2_28_x86_64.whl
Size 581.9 kB
Tags CPython 3.11 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
fabae87a9a280ac33e23db85a7cbd908838904853cebc0dd16a4c8f49a93bf45
BLAKE2b-256 checksum
How to use checksums
2eec600540d9bd765193928ec00a16a4883a53388cb13450a1f21369de691a0a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.1

Release files / polytope_python-2.1.21-cp311-cp311-macosx_11_0_arm64.whl

Download URL polytope_python-2.1.21-cp311-cp311-macosx_11_0_arm64.whl
Size 530.9 kB
Tags CPython 3.11 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
7d34d14fe4f1037056ac19ffb93b2c0856d9fa6e14fa7d744d6dedaf35ed8d60
BLAKE2b-256 checksum
How to use checksums
0e9b035081450ba738e18abcaf730a0cc947c586515912537453126ab3951376
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Release files / polytope_python-2.1.21-cp310-cp310-manylinux_2_28_x86_64.whl

Download URL polytope_python-2.1.21-cp310-cp310-manylinux_2_28_x86_64.whl
Size 581.6 kB
Tags CPython 3.10 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
19949c04d4c48110ee6b4a64f7934e97abbc222e307f82b25ba104675270342c
BLAKE2b-256 checksum
How to use checksums
bef7545c59fecfaf4156cfbd6f62b8850c55a812a8cdd7daf651174bcc693f5a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.1

Release files / polytope_python-2.1.21-cp310-cp310-macosx_11_0_arm64.whl

Download URL polytope_python-2.1.21-cp310-cp310-macosx_11_0_arm64.whl
Size 530.9 kB
Tags CPython 3.10 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
3a93c0ed397015a9eab0ed3ac6daae9b759cddc73e29e2b80248bcb842705b0b
BLAKE2b-256 checksum
How to use checksums
fb56493e6d3b372a3d355f696c219c0c46d1d5f824aa8dd5f97c9884ea7215f5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Release files / polytope_python-2.1.21-cp39-cp39-manylinux_2_28_x86_64.whl

Download URL polytope_python-2.1.21-cp39-cp39-manylinux_2_28_x86_64.whl
Size 584.7 kB
Tags CPython 3.9 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
4e8ba1843c7eb5b90d3e1bfd8aa4f587405255208c2ee0bb8c13b3a395fe1e0e
BLAKE2b-256 checksum
How to use checksums
99c25e9a67f2d51547b7e10e6b25a027d69bc5a2bbf374ff5bb3fd7d6823d981
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.1

Release files / polytope_python-2.1.21-cp39-cp39-macosx_11_0_arm64.whl

Download URL polytope_python-2.1.21-cp39-cp39-macosx_11_0_arm64.whl
Size 531.8 kB
Tags CPython 3.9 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
c4b3acc3f3a1faaa169ba04072b323d34cb251d447ce7538825d0c184e74eff5
BLAKE2b-256 checksum
How to use checksums
30a7e78d3e6a81d032057aabb85594e2a93d3904cb1cf4175cdac5eafd4c685d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.10

Security for polytope-python 2.1.21

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

2.1.21 This release

13 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page