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.22

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.22
File Size Uploaded Provenance Actions
polytope_python-2.1.22.tar.gz 14.4 MB Without provenance Details for polytope_python-2.1.22.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for polytope-python 2.1.22
File Actions
polytope_python-2.1.22-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.22-cp314-cp314-manylinux_2_28_x86_64.whl
polytope_python-2.1.22-cp314-cp314-macosx_11_0_arm64.whl CPython 3.14 CPython 3.14 macOS 11.0+ ARM64 Details for polytope_python-2.1.22-cp314-cp314-macosx_11_0_arm64.whl
polytope_python-2.1.22-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.22-cp313-cp313-manylinux_2_28_x86_64.whl
polytope_python-2.1.22-cp313-cp313-macosx_11_0_arm64.whl CPython 3.13 CPython 3.13 macOS 11.0+ ARM64 Details for polytope_python-2.1.22-cp313-cp313-macosx_11_0_arm64.whl
polytope_python-2.1.22-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.22-cp312-cp312-manylinux_2_28_x86_64.whl
polytope_python-2.1.22-cp312-cp312-macosx_11_0_arm64.whl CPython 3.12 CPython 3.12 macOS 11.0+ ARM64 Details for polytope_python-2.1.22-cp312-cp312-macosx_11_0_arm64.whl
polytope_python-2.1.22-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.22-cp311-cp311-manylinux_2_28_x86_64.whl
polytope_python-2.1.22-cp311-cp311-macosx_11_0_arm64.whl CPython 3.11 CPython 3.11 macOS 11.0+ ARM64 Details for polytope_python-2.1.22-cp311-cp311-macosx_11_0_arm64.whl
polytope_python-2.1.22-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.22-cp310-cp310-manylinux_2_28_x86_64.whl
polytope_python-2.1.22-cp310-cp310-macosx_11_0_arm64.whl CPython 3.10 CPython 3.10 macOS 11.0+ ARM64 Details for polytope_python-2.1.22-cp310-cp310-macosx_11_0_arm64.whl
polytope_python-2.1.22-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.22-cp39-cp39-manylinux_2_28_x86_64.whl
polytope_python-2.1.22-cp39-cp39-macosx_11_0_arm64.whl CPython 3.9 CPython 3.9 macOS 11.0+ ARM64 Details for polytope_python-2.1.22-cp39-cp39-macosx_11_0_arm64.whl

Total release size: 21.0 MB

Release files / polytope_python-2.1.22.tar.gz

Download URL polytope_python-2.1.22.tar.gz
Size 14.4 MB
Tags Source
SHA-256 checksum
How to use checksums
bb0c7bfbe78d07b91204f53dd428712de0b048e412c3627c54c8ac707d6df99f
BLAKE2b-256 checksum
How to use checksums
835fdf75ad4209a2e1f9357ac72ab57972775290c72b5aec543297e14070b9e8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

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

Download URL polytope_python-2.1.22-cp314-cp314-manylinux_2_28_x86_64.whl
Size 576.9 kB
Tags CPython 3.14 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
f763192f8b0c539039afc6cd917db4aef460d6c9206706370b1a5d242d1c92bf
BLAKE2b-256 checksum
How to use checksums
26fd7d5f6e18146aa9c54c1f2147b02ebebbc675fa7088de95f5f5bb286375bd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

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

Download URL polytope_python-2.1.22-cp314-cp314-macosx_11_0_arm64.whl
Size 526.8 kB
Tags CPython 3.14 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
622c15dc95e73adf046ee2f0c6effd4acf9cd9a0017c665c05da33fadfaf6952
BLAKE2b-256 checksum
How to use checksums
034e7dbafcca2d96657bfc981ff3e9556cc7791c28a3d2865d7cedabf43b322f
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.22-cp313-cp313-manylinux_2_28_x86_64.whl

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

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

Download URL polytope_python-2.1.22-cp313-cp313-macosx_11_0_arm64.whl
Size 525.7 kB
Tags CPython 3.13 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
305631019bdb46a44d8f896f1d1343321ca75f9d9cf9b7c69a76015a0a0d91ec
BLAKE2b-256 checksum
How to use checksums
ff905d150e6ecb4b89cb1738454bbec87c38ea2e0bb45340f9f140d6052ea115
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.22-cp312-cp312-manylinux_2_28_x86_64.whl

Download URL polytope_python-2.1.22-cp312-cp312-manylinux_2_28_x86_64.whl
Size 576.5 kB
Tags CPython 3.12 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
e37b8566a56e4d9e653d135a43ad7ee66a28e3d71df16375dd39de81b350740d
BLAKE2b-256 checksum
How to use checksums
195b4507cc8064c707939615eae6b3babc6967a7f7449361cd45b3703aec59c6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

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

Download URL polytope_python-2.1.22-cp312-cp312-macosx_11_0_arm64.whl
Size 524.7 kB
Tags CPython 3.12 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
06cb64580a5900435a204efe706a88a55f250986e81c4075465d8455371e2df7
BLAKE2b-256 checksum
How to use checksums
307da3e4259f6180c9f7045a37c698805d28f4df3ca0447c6d372ed52edd5a27
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.22-cp311-cp311-manylinux_2_28_x86_64.whl

Download URL polytope_python-2.1.22-cp311-cp311-manylinux_2_28_x86_64.whl
Size 581.5 kB
Tags CPython 3.11 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
35045542795f724feb05ab06a9cd6c4f74dee056ee7c755ff8d94e59f2190ec5
BLAKE2b-256 checksum
How to use checksums
d4c3095397e296d2ce61ecaaf711ca5865c697cfd8de551a3e773ce2b2e9a679
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

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

Download URL polytope_python-2.1.22-cp311-cp311-macosx_11_0_arm64.whl
Size 530.8 kB
Tags CPython 3.11 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
c9cc512b5dd96d503992a41c2460c441dee472c8e3b4e78883136c4b506571ab
BLAKE2b-256 checksum
How to use checksums
7e902ae4d2da5cbf81dcd63a07501888fa9019e11d1625db450d9d2e64877372
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.22-cp310-cp310-manylinux_2_28_x86_64.whl

Download URL polytope_python-2.1.22-cp310-cp310-manylinux_2_28_x86_64.whl
Size 581.3 kB
Tags CPython 3.10 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
7ba84aa1d2b47e33ba1bbd19ce2b4716c8aa4762c1fdcf00156982edd73dbb06
BLAKE2b-256 checksum
How to use checksums
e91ff7b16923af3d3b00df904f1c92e0b1073831beb2b4bd727f674181072f48
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

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

Download URL polytope_python-2.1.22-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
a8025ffd0bde37c55f1ab4784246556faaca7fd5df50e837c9844e3cafbefbc0
BLAKE2b-256 checksum
How to use checksums
1211dd45047d95431b11c4d3cb536f30658fd6d335a3d6b013ccbf8bdd3b23de
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.22-cp39-cp39-manylinux_2_28_x86_64.whl

Download URL polytope_python-2.1.22-cp39-cp39-manylinux_2_28_x86_64.whl
Size 584.5 kB
Tags CPython 3.9 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
997ec05b1fc54d36aa627eda9d6cbebb0401e74b69ba241b1703704706c035e2
BLAKE2b-256 checksum
How to use checksums
7c9fa14b9b748576388782f371fddecc66aaf526bd7d4bca08e9c723c66b31b9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.2

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

Download URL polytope_python-2.1.22-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
01fcd6eaa0e31f0e99f6282c515c85b8249bd17426ebbd75ab9540c0aa63660d
BLAKE2b-256 checksum
How to use checksums
e003338c19f14fd29f5c6ba17836098cdaa33da2f1a2946914ee4e4efa727a6b
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.22

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.22 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