pyairtree
Python bindings for AirTree — a high-performance library for building, compressing, and querying multi-dimensional histograms over floating-point data.
Turn large numeric datasets into compact .airtree histograms and run fast statistical queries without keeping the full raw data in memory.
Required Notice: Copyright AirMettle, Inc. (https://airmettle.com)
Installation
pip install pyairtree
Supported platforms
| Platform | Architecture | Python |
|---|---|---|
| Linux | x86_64, ARM | 3.8 – 3.12 |
| Windows | amd64 | 3.8 – 3.12 |
NumPy is installed automatically as a dependency.
Verify the install
import pyairtree
print(pyairtree.__version__)
Quick start
Build a 1D histogram from a NumPy array, save it, and query percentiles:
import numpy as np
import pyairtree
# Sample data
data = np.random.randn(100_000)
# Build a compressed histogram (1D, high precision)
buffer = pyairtree.generate(data)
# Save to disk
pyairtree.write(buffer, "histogram.airtree")
# Query percentiles
p = pyairtree.Percentile(buffer)
print(f"Median: {p.get_percentile(50):.4f}")
print(f"95th percentile: {p.get_percentile(95):.4f}")
Load data directly from .npy or single-array .npz files
buffer = pyairtree.generate("samples/data.npy")
Core workflow
A typical workflow has three steps:
- Generate — compress numeric arrays into an in-memory histogram buffer
- Store — write the buffer to a .airtree file
- Query — run statistics or spatial queries on the buffer or file
import pyairtree
# 1. Generate
buffer = pyairtree.generate(x, y, options)
# 2. Store
pyairtree.write(buffer, "output.airtree")
# 3. Query
reader = pyairtree.read("output.airtree")
p = pyairtree.Percentile(buffer)
Generating histograms
Unified generate() API (recommended)
Pass one NumPy array per dimension. Use AirTreeOptions to control dimensionality and precision:
import numpy as np
import pyairtree
x = np.random.randn(50_000)
y = np.random.randn(50_000)
options = pyairtree.AirTreeOptions()
options.dimensions = 2
options.type = pyairtree.ConfigType.XP # highest precision (default for most use cases)
buffer = pyairtree.generate(x, y, options)
Configuration types
| Type | Precision | Best for |
|---|---|---|
| ConfigType.XT | 13-bit | Large datasets, fastest builds |
| ConfigType.XF | 16-bit | General-purpose balance |
| ConfigType.XP | 20-bit (1D) / 10-bit (2D+) | Highest accuracy |
Dimensionality
# 1D
buf_1d = pyairtree.generate(a, options)
# 2D
buf_2d = pyairtree.generate(a, b, options)
# 3D
buf_3d = pyairtree.generate(a, b, c, options)
# 4D
buf_4d = pyairtree.generate(a, b, c, d, options)
Set options.dimensions to match the number of arrays you pass.
Named generation functions
Convenience functions are also available for explicit configs:
arr = pyairtree.buildFPHArray(data)
# 1D
pyairtree.generate_1DxT(arr) # 13-bit
pyairtree.generate_1DxF(arr) # 16-bit
pyairtree.generate_1DxP(arr) # 20-bit
# 2D / 3D / 4D
pyairtree.generate_2DxP(arr_x, arr_y)
pyairtree.generate_3DxP(arr_x, arr_y, arr_z)
pyairtree.generate_4DxP(arr_x, arr_y, arr_z, arr_w)
Supported array types
NumPy arrays with dtype float64, float32, int64, or int32.
File I/O
Write a histogram
pyairtree.write(buffer, "histogram.airtree")
Read a histogram
reader = pyairtree.read("histogram.airtree")
print(reader.dims) # number of dimensions
print(reader.bit_length) # encoding precision
print(reader.type) # configuration type
header = reader.header
print(header.version)
print(header.nan_count)
Query operations
Percentile (1D)
p = pyairtree.Percentile(buffer)
median = p.get_percentile(50.0)
p95 = p.get_percentile(95.0)
Min / Max (1D)
mm = pyairtree.MinMax(buffer)
print(mm.get_min(), mm.get_max())
Top-K (1D)
Return the bins with the highest counts:
topk = pyairtree.TopK(buffer)
results = topk.top_k(10.0) # top 10% of bins by count
for r in results:
print(r.lower_bound, r.upper_bound, r.count)
CDF (1D)
cdf = pyairtree.CDF(buffer)
values = cdf.get_cdf()
Bounding box (2D)
Count values inside a rectangular region:
bbox_query = pyairtree.BoundingBox(buffer_2d)
region = pyairtree.BoundingBoxCoordinate2D(
min_x=0.0, max_x=1.0,
min_y=0.0, max_y=1.0,
)
safe, edge = bbox_query.get_counts(region)
(safe_coords, safe_count) = safe
(edge_coords, edge_count) = edge
Grid query (1D)
Evaluate the histogram over a regular grid:
gq = pyairtree.GridQuery(buffer)
result = gq.get_grid(spec) # pass a GridSpec with min, max, steps
rows = result.materialize_rows()
Export
Export histogram data to common interchange formats:
pyairtree.export_tree(buffer, "output.arrow", pyairtree.ExportFormat.ARROW)
pyairtree.export_tree(buffer, "output.parquet", pyairtree.ExportFormat.PARQUET)
pyairtree.export_tree(buffer, "output.csv", pyairtree.ExportFormat.CSV)
Choosing a configuration
| Use case | Suggested config |
|---|---|
| Exploratory analysis on large 1D datasets | ConfigType.XT or generate_1DxT |
| Production 1D analytics | ConfigType.XF or generate_1DxF |
| High-precision 1D requirements | ConfigType.XP or generate_1DxP |
| 2D spatial / correlation data | generate_2DxP |
| 3D / 4D multi-variate data | generate_3DxP / generate_4DxP |
Error handling
import pyairtree
import numpy as np
try:
pyairtree.generate(np.array(["not", "numeric"]))
except (TypeError, RuntimeError) as e:
print(f"Generation failed: {e}")
try:
pyairtree.Percentile(two_d_buffer) # Percentile is 1D only
except RuntimeError as e:
print(f"Query failed: {e}")
License
AirMettle Noncommercial License
This software is provided for noncommercial use only. Government use requires a separate commercial license.
• Personal, research, educational, and qualifying nonprofit use is permitted • Commercial or government use requires a license from AirMettle
For commercial licensing, support, or enterprise usage:
Patent Pending — U.S. Patent Application Publication No. 2025/0217930 A1 (https://patents.google.com/patent/US20250217930A1)
See the bundled LICENSE file for full terms.
Links
- Homepage: https://airmettle.com
- Support: support@airmettle.com
Metadata
Release files for pyairtree 1.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 186.0 MB
Release files / pyairtree-1.3.1-cp312-cp312-win_amd64.whl
| Download URL | pyairtree-1.3.1-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 25.5 MB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
150deaa56b5539fae12aea3cb6a342b06fd6a01f7a078f2b83c07745bd7b2bb8
|
|
BLAKE2b-256 checksum How to use checksums |
5f8bfd1fb0f8b75eba13ce3d45938fadcf4fb3d8cec9bccd08cbce34a9d6b0ac
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / pyairtree-1.3.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | pyairtree-1.3.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 9.0 MB |
| Tags | CPython 3.12 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
2f42cf26751c044605e52524bda8191cd3205a83de66187d98a062682e5a39cf
|
|
BLAKE2b-256 checksum How to use checksums |
8f84126de46ef273bc66ad8b2e30f05b1975191c58d85eefe3db4e202a628d7e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / pyairtree-1.3.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | pyairtree-1.3.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 8.0 MB |
| Tags | CPython 3.12 Linux glibc 2.17+ ARM64 |
|
SHA-256 checksum How to use checksums |
1d083c53ba212c78fd6dcfb22c58202ddd4c196a300be1b09c8ac0ae1d2ba4ba
|
|
BLAKE2b-256 checksum How to use checksums |
2796b0ab70796b32a77825304fdee034f3201cdc15a544f9628b770efe955ddc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / pyairtree-1.3.1-cp312-cp312-macosx_26_0_arm64.whl
| Download URL | pyairtree-1.3.1-cp312-cp312-macosx_26_0_arm64.whl |
|---|---|
| Size | 6.1 MB |
| Tags | CPython 3.12 macOS 26.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
030a6b2b2aad6698b504932b4f79aa2ce60d664507e267a38f255cf87f423f57
|
|
BLAKE2b-256 checksum How to use checksums |
1b7917b30aaf01e1cb4cde51719590f79b98e03a1d0a0b66c2ac1cfd301e1862
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / pyairtree-1.3.1-cp311-cp311-win_amd64.whl
| Download URL | pyairtree-1.3.1-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 20.4 MB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
5426c8b17cceb509b90e66da5e0166aa9a5e0f4724e295e7ba2077a92b6a3aad
|
|
BLAKE2b-256 checksum How to use checksums |
41f6197f3ef5f6d1d12a18769c0861d3a3851bb86cc3b12efadab44794fa0eca
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / pyairtree-1.3.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | pyairtree-1.3.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 9.0 MB |
| Tags | CPython 3.11 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
ea38456f587dab6a542c721c2019fa87e8dc528be852e631fe55eea3d208891e
|
|
BLAKE2b-256 checksum How to use checksums |
85e4ae326fb25712c3609095750d11f4555b0408804bafd9b325c2bb93e9fabb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / pyairtree-1.3.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | pyairtree-1.3.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 8.0 MB |
| Tags | CPython 3.11 Linux glibc 2.17+ ARM64 |
|
SHA-256 checksum How to use checksums |
0bdb52b40ee14202148f6a95beb01f09dbccdda9ef39e367ef7d64edea7c0a60
|
|
BLAKE2b-256 checksum How to use checksums |
7ef77bb03ef975c684d934ddf11f3d4522c77ec379637a7966d6428cfa0e180b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / pyairtree-1.3.1-cp311-cp311-macosx_26_0_arm64.whl
| Download URL | pyairtree-1.3.1-cp311-cp311-macosx_26_0_arm64.whl |
|---|---|
| Size | 6.1 MB |
| Tags | CPython 3.11 macOS 26.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
6d38b905a0730369ecb77b9bf7eaec221d62f1b2cbeccd79087dd80dc49e7940
|
|
BLAKE2b-256 checksum How to use checksums |
e0d6e5a948aa5926b4845602428e632a77d66d77aa589bedfd2cf2fef258a436
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / pyairtree-1.3.1-cp310-cp310-win_amd64.whl
| Download URL | pyairtree-1.3.1-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 15.3 MB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
bc79ce2ce3622254a6c0ce179a1f402a4ec9b50109b5efe99652c9a3f562d469
|
|
BLAKE2b-256 checksum How to use checksums |
cfc097ba7dea829e58b756e65a2142dbb878982ee0fd318d8266c37fac59027b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / pyairtree-1.3.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | pyairtree-1.3.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 9.0 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
5bfc450e08af4b07dd2389b25bb5bf3e1e9f2ef9dd7b6d51b00fc3d1fc05f2f4
|
|
BLAKE2b-256 checksum How to use checksums |
9c2ae0ceaba2604baa8e4971eda30a9777a345db7ba91af5bcfda8fb2dd64d83
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / pyairtree-1.3.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | pyairtree-1.3.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 8.0 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ ARM64 |
|
SHA-256 checksum How to use checksums |
59edcd486a0e3b35b3b3b05ac0cbbcd1e36f72c84b2c3b9fa2a0321a55d60c2f
|
|
BLAKE2b-256 checksum How to use checksums |
4f53e564d272742e18036d645fba66cabc4031ff83b7e9d3634b434258bb5041
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / pyairtree-1.3.1-cp310-cp310-macosx_26_0_arm64.whl
| Download URL | pyairtree-1.3.1-cp310-cp310-macosx_26_0_arm64.whl |
|---|---|
| Size | 6.1 MB |
| Tags | CPython 3.10 macOS 26.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
784451efea0d737f351656d68d6ed113d5375cea724d6aae2176a7d281ef4dcb
|
|
BLAKE2b-256 checksum How to use checksums |
1c6713eae7e691adf233d0e30afe271b5f124d57f82a447be987ef20d4abd5ed
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / pyairtree-1.3.1-cp39-cp39-win_amd64.whl
| Download URL | pyairtree-1.3.1-cp39-cp39-win_amd64.whl |
|---|---|
| Size | 10.2 MB |
| Tags | CPython 3.9 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
c3c70831b520345523192b10023578290ab24aa0eaef8bb110078930dd3abf1d
|
|
BLAKE2b-256 checksum How to use checksums |
080bec3e4fb8caaa4109b53a291c9a9efe5f7eb2c1ab0d70bb2c2cf0fc02f6c0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / pyairtree-1.3.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | pyairtree-1.3.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 9.0 MB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
7c6df31fb6192deef86b20dab9f50efdd36565b6a60f8bedfc753ef86ccf73b3
|
|
BLAKE2b-256 checksum How to use checksums |
2f56ff5e01951abaf2aee4deb2e79f4f73404a9cfc5b1a1b7128953c6bf7d64e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / pyairtree-1.3.1-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | pyairtree-1.3.1-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 8.0 MB |
| Tags | CPython 3.9 Linux glibc 2.17+ ARM64 |
|
SHA-256 checksum How to use checksums |
0760f8b1c3199f29125d19aef4f5edb84f8d46247f0b83bc1586716db63da1ae
|
|
BLAKE2b-256 checksum How to use checksums |
261149ea20bdef82cdd34cda73fdbad220d7dd51e11ca91648a1c0c67dca5d46
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / pyairtree-1.3.1-cp39-cp39-macosx_26_0_arm64.whl
| Download URL | pyairtree-1.3.1-cp39-cp39-macosx_26_0_arm64.whl |
|---|---|
| Size | 6.1 MB |
| Tags | CPython 3.9 macOS 26.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
b86e7cc6f60042a91e5b58ebd72706a9f2e78349179a1c4818023b1c56924dea
|
|
BLAKE2b-256 checksum How to use checksums |
f37600e257758627a897dcead6e46c5424971541e0d60ebbce898336a3684644
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Release files / pyairtree-1.3.1-cp38-cp38-win_amd64.whl
| Download URL | pyairtree-1.3.1-cp38-cp38-win_amd64.whl |
|---|---|
| Size | 5.1 MB |
| Tags | CPython 3.8 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
2b22efa6719aacfa08860d6e6f4d615012457724fb68eda0db495eb751613085
|
|
BLAKE2b-256 checksum How to use checksums |
c2df66fdf8113b126e3b3fa1b17c9ce718a4da1feca4042f0722bb23f65761e5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / pyairtree-1.3.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | pyairtree-1.3.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 9.0 MB |
| Tags | CPython 3.8 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
a61cc560e1a5ba2104cd2f9ab85c9214e01183eaba18f90634c18ed86c82186e
|
|
BLAKE2b-256 checksum How to use checksums |
c1a052b8f10e56c60af93428cf7d749b74b715c8989ea42b5cb1aa1dcdfee950
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.13
|
Release files / pyairtree-1.3.1-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | pyairtree-1.3.1-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 8.0 MB |
| Tags | CPython 3.8 Linux glibc 2.17+ ARM64 |
|
SHA-256 checksum How to use checksums |
015fa6cc6f911913dfa71b5c7208e8e36d033052bc91565e3456aace5a93a23a
|
|
BLAKE2b-256 checksum How to use checksums |
e576afdd9a8629f02f4f603fbcac3b13cf18dec83b1a1399b07ba6222d3622c7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.3
|
Security for pyairtree 1.3.1
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.