Skip to main content

Manipulate JSON-like data with NumPy-like idioms.

Project description

PyPI version Conda-Forge Python 3.9‒3.13 BSD-3 Clause License Build Test

Scikit-HEP NSF-1836650 DOI Documentation Gitter

Awkward Array is a library for nested, variable-sized data, including arbitrary-length lists, records, mixed types, and missing data, using NumPy-like idioms.

Arrays are dynamically typed, but operations on them are compiled and fast. Their behavior coincides with NumPy when array dimensions are regular and generalizes when they're not.

Motivating example

Given an array of lists of objects with x, y fields (with nested lists in the y field),

import awkward as ak

array = ak.Array([
    [{"x": 1.1, "y": [1]}, {"x": 2.2, "y": [1, 2]}, {"x": 3.3, "y": [1, 2, 3]}],
    [],
    [{"x": 4.4, "y": [1, 2, 3, 4]}, {"x": 5.5, "y": [1, 2, 3, 4, 5]}]
])

the following slices out the y values, drops the first element from each inner list, and runs NumPy's np.square function on everything that is left:

output = np.square(array["y", ..., 1:])

The result is

[
    [[], [4], [4, 9]],
    [],
    [[4, 9, 16], [4, 9, 16, 25]]
]

The equivalent using only Python is

output = []
for sublist in array:
    tmp1 = []
    for record in sublist:
        tmp2 = []
        for number in record["y"][1:]:
            tmp2.append(np.square(number))
        tmp1.append(tmp2)
    output.append(tmp1)

The expression using Awkward Arrays is more concise, using idioms familiar from NumPy, and it also has NumPy-like performance. For a similar problem 10 million times larger than the one above (single-threaded on a 2.2 GHz processor),

  • the Awkward Array one-liner takes 1.5 seconds to run and uses 2.1 GB of memory,
  • the equivalent using Python lists and dicts takes 140 seconds to run and uses 22 GB of memory.

Awkward Array is even faster when used in Numba's JIT-compiled functions.

See the Getting started documentation on awkward-array.org for an introduction, including a no-install demo you can try in your web browser.

Getting help

Installation

Awkward Array can be installed from PyPI using pip:

pip install awkward

The awkward package is pure Python, and it will download the awkward-cpp compiled components as a dependency. If there is no awkward-cpp binary package (wheel) for your platform and Python version, pip will attempt to compile it from source (which has additional dependencies, such as a C++ compiler).

Awkward Array is also available on conda-forge:

conda install -c conda-forge awkward

Release history Release notifications | RSS feed

This version

2.8.5

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

awkward-2.8.5.tar.gz (6.2 MB view details)

Uploaded Source

Built Distribution

awkward-2.8.5-py3-none-any.whl (886.8 kB view details)

Uploaded Python 3

File details

Details for the file awkward-2.8.5.tar.gz.

File metadata

  • Download URL: awkward-2.8.5.tar.gz
  • Upload date:
  • Size: 6.2 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.8

File hashes

Hashes for awkward-2.8.5.tar.gz
Algorithm Hash digest
SHA256 4b9049440bb98214e05908098afd0d4f66af0b1b23c158159f9774db27447c89
MD5 82bdbc9e5f0c99c6c78c204c3c915276
BLAKE2b-256 5b5229c83188d1c75a41b59f1bce3ed34c570139c1168d0597240c206f544102

See more details on using hashes here.

Provenance

The following attestation bundles were made for awkward-2.8.5.tar.gz:

Publisher: deploy.yml on scikit-hep/awkward

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file awkward-2.8.5-py3-none-any.whl.

File metadata

  • Download URL: awkward-2.8.5-py3-none-any.whl
  • Upload date:
  • Size: 886.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.8

File hashes

Hashes for awkward-2.8.5-py3-none-any.whl
Algorithm Hash digest
SHA256 445a505ae5da32940c1b68033787b30d11d297d6e30c6af60b187f90fc7570d8
MD5 b10877062f15d555e9c12ba5870817c1
BLAKE2b-256 5e9f8b0e35d670006b2f51561b7ef66b88d0cf0d4d3553c10ab6a2f38fc75fb4

See more details on using hashes here.

Provenance

The following attestation bundles were made for awkward-2.8.5-py3-none-any.whl:

Publisher: deploy.yml on scikit-hep/awkward

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page